telegram-claude-mcp 1.0.2 → 1.1.0

package/hooks/notify-hook.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+#
+# Claude Code Notification Hook
+#
+# This script receives notification events from Claude Code (stop, session events)
+# and forwards them to the Telegram MCP server.
+#
+# Usage: Configure this script in your Claude Code hooks settings for Stop event
+#
+# Environment variables:
+#   TELEGRAM_HOOK_PORT - Port of the MCP server (default: 3333)
+#   TELEGRAM_HOOK_HOST - Host of the MCP server (default: localhost)
+#   TELEGRAM_HOOK_EVENT - Event type override (default: from input or 'stop')
+#
+
+HOOK_PORT="${TELEGRAM_HOOK_PORT:-3333}"
+HOOK_HOST="${TELEGRAM_HOOK_HOST:-localhost}"
+HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/notify"
+EVENT_TYPE="${TELEGRAM_HOOK_EVENT:-stop}"
+
+# Read the hook input from stdin
+INPUT=$(cat)
+
+# Extract relevant information
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+MESSAGE=$(echo "$INPUT" | jq -r '.message // .stop_reason // "Agent stopped"')
+
+# Log for debugging
+echo "[notify-hook] Event: $EVENT_TYPE" >&2
+echo "[notify-hook] Message: $MESSAGE" >&2
+
+# Build the request payload
+PAYLOAD=$(jq -n \
+  --arg type "$EVENT_TYPE" \
+  --arg message "$MESSAGE" \
+  --arg session_id "$SESSION_ID" \
+  '{type: $type, message: $message, session_id: $session_id}')
+
+# Send the notification (non-blocking, we don't need to wait)
+curl -s -X POST "$HOOK_URL" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  --max-time 10 >/dev/null 2>&1 &
+
+# Return success immediately (hook doesn't need to block)
+echo '{"continue": true}'

package/hooks/permission-hook.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+#
+# Claude Code Permission Hook
+#
+# This script receives permission requests from Claude Code and forwards them
+# to the Telegram MCP server for interactive approval via Telegram.
+#
+# Usage: Configure this script in your Claude Code hooks settings
+#
+# Environment variables:
+#   TELEGRAM_HOOK_PORT - Port of the MCP server (default: 3333)
+#   TELEGRAM_HOOK_HOST - Host of the MCP server (default: localhost)
+#
+
+HOOK_PORT="${TELEGRAM_HOOK_PORT:-3333}"
+HOOK_HOST="${TELEGRAM_HOOK_HOST:-localhost}"
+HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/permission"
+
+# Read the hook input from stdin
+INPUT=$(cat)
+
+# Extract tool_name and tool_input from the Claude Code hook format
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
+
+# If no tool_name, this might be a different format - try to extract from the input
+if [ -z "$TOOL_NAME" ]; then
+  # Claude Code might send the data differently, try alternative paths
+  TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName // .name // empty')
+  TOOL_INPUT=$(echo "$INPUT" | jq -c '.toolInput // .input // .arguments // {}')
+fi
+
+# Log for debugging (goes to stderr, not stdout)
+echo "[permission-hook] Tool: $TOOL_NAME" >&2
+echo "[permission-hook] Sending to: $HOOK_URL" >&2
+
+# Build the request payload
+PAYLOAD=$(jq -n \
+  --arg tool_name "$TOOL_NAME" \
+  --argjson tool_input "$TOOL_INPUT" \
+  '{tool_name: $tool_name, tool_input: $tool_input}')
+
+# Send the request to the MCP server and wait for response
+RESPONSE=$(curl -s -X POST "$HOOK_URL" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  --max-time 600)
+
+# Check if curl succeeded
+if [ $? -ne 0 ]; then
+  echo "[permission-hook] Error: Failed to connect to hook server" >&2
+  # Return deny on error for safety
+  echo '{"hookSpecificOutput":{"decision":{"behavior":"deny","message":"Failed to connect to Telegram hook server"}}}'
+  exit 0
+fi
+
+# Log the response
+echo "[permission-hook] Response: $RESPONSE" >&2
+
+# Output the response (this goes back to Claude Code)
+echo "$RESPONSE"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "telegram-claude-mcp",
-  "version": "1.0.2",
-  "description": "MCP server that lets Claude message you on Telegram",
+  "version": "1.1.0",
+  "description": "MCP server that lets Claude message you on Telegram with hooks support",
   "author": "Geravant",
   "license": "MIT",
   "repository": {
@@ -14,7 +14,9 @@
     "mcp",
     "claude-code",
     "bot",
-    "messaging"
+    "messaging",
+    "hooks",
+    "permissions"
   ],
   "type": "module",
   "main": "src/index.ts",
@@ -23,7 +25,8 @@
   },
   "files": [
     "src",
-    "bin"
+    "bin",
+    "hooks"
   ],
   "scripts": {
     "start": "node --import tsx src/index.ts",

package/src/index.ts

@@ -5,13 +5,17 @@
  *
  * A stdio-based MCP server that lets Claude message you on Telegram.
  * Supports multiple Claude Code sessions with message tagging.
+ *
+ * Also provides an HTTP server for Claude Code hooks integration,
+ * allowing permission requests and notifications to flow through Telegram.
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { TelegramManager } from './telegram.js';
+import { TelegramManager, type HookEvent, type PermissionDecision } from './telegram.js';
 import { loadAppConfig, validateAppConfig } from './providers/index.js';
+import { createServer, type IncomingMessage, type ServerResponse } from 'http';
 
 async function main() {
   // Load configuration
@@ -35,6 +39,98 @@ async function main() {
 
   telegram.start();
 
+  // Start HTTP server for hooks
+  const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    if (req.method !== 'POST') {
+      res.writeHead(405, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Method not allowed' }));
+      return;
+    }
+
+    // Read body
+    let body = '';
+    for await (const chunk of req) {
+      body += chunk;
+    }
+
+    try {
+      const data = JSON.parse(body);
+      const url = req.url || '/';
+
+      // Handle permission request
+      if (url === '/permission' || url === '/hooks/permission') {
+        const { tool_name, tool_input } = data;
+
+        if (!tool_name) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Missing tool_name' }));
+          return;
+        }
+
+        console.error(`[HTTP] Permission request for tool: ${tool_name}`);
+
+        const decision = await telegram.handlePermissionRequest(
+          tool_name,
+          tool_input || {}
+        );
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          hookSpecificOutput: {
+            decision: {
+              behavior: decision.behavior,
+              message: decision.message,
+            },
+          },
+        }));
+        return;
+      }
+
+      // Handle notifications (stop, session events, etc.)
+      if (url === '/notify' || url === '/hooks/notify') {
+        const event: HookEvent = {
+          type: data.type || 'notification',
+          message: data.message,
+          session_id: data.session_id,
+          tool_name: data.tool_name,
+          tool_input: data.tool_input,
+          timestamp: data.timestamp || new Date().toISOString(),
+        };
+
+        console.error(`[HTTP] Notification: ${event.type}`);
+
+        await telegram.sendHookNotification(event);
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+        return;
+      }
+
+      // Unknown endpoint
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not found' }));
+    } catch (error) {
+      console.error('[HTTP] Error:', error);
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Internal server error' }));
+    }
+  });
+
+  httpServer.listen(config.sessionPort, () => {
+    console.error(`[HTTP] Hook server listening on port ${config.sessionPort}`);
+  });
+
   // Track active chat sessions
   let activeSessionId: string | null = null;
 
@@ -186,11 +282,13 @@ async function main() {
   console.error('Telegram Claude MCP server ready');
   console.error(`Session: ${config.sessionName}`);
   console.error(`Chat ID: ${config.telegramChatId}`);
+  console.error(`Hook server: http://localhost:${config.sessionPort}`);
   console.error('');
 
   // Graceful shutdown
   const shutdown = async () => {
     console.error('\nShutting down...');
+    httpServer.close();
     telegram.stop();
     process.exit(0);
   };

package/src/providers/index.ts

@@ -31,10 +31,20 @@ export function loadAppConfig(): AppConfig {
   const chatId = process.env.TELEGRAM_CHAT_ID;
   const sessionPort = process.env.SESSION_PORT || '3333';
 
+  // Auto-detect project name from current working directory
+  const cwd = process.cwd();
+  const projectName = cwd.split('/').pop() || 'unknown';
+
+  // Build session name: SESSION_NAME:projectName or just projectName
+  const baseSessionName = process.env.SESSION_NAME;
+  const sessionName = baseSessionName
+    ? `${baseSessionName}:${projectName}`
+    : projectName;
+
   return {
     telegramBotToken: process.env.TELEGRAM_BOT_TOKEN || '',
     telegramChatId: chatId ? parseInt(chatId, 10) : 0,
-    sessionName: process.env.SESSION_NAME || 'default',
+    sessionName,
     sessionPort: parseInt(sessionPort, 10),
     openrouterApiKey: process.env.OPENROUTER_API_KEY,
     openrouterModel: process.env.OPENROUTER_MODEL || 'openai/gpt-oss-120b',

package/src/telegram.ts

@@ -4,6 +4,8 @@
  * Handles Telegram messaging for Claude Code with multi-session support.
  * Multiple Claude Code instances can share one Telegram chat, with messages
  * tagged by session name and replies routed to the correct session.
+ *
+ * Also handles Claude Code hook events (permissions, notifications, etc.)
  */
 
 import TelegramBot from 'node-telegram-bot-api';
@@ -28,23 +30,48 @@ interface PendingResponse {
   timestamp: number;
 }
 
+interface PendingPermission {
+  resolve: (decision: PermissionDecision) => void;
+  reject: (error: Error) => void;
+  messageId: number;
+  timestamp: number;
+  toolName: string;
+}
+
+export interface PermissionDecision {
+  behavior: 'allow' | 'deny';
+  message?: string;
+}
+
+export interface HookEvent {
+  type: 'permission_request' | 'stop' | 'notification' | 'session_start' | 'session_end';
+  session_id?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  message?: string;
+  timestamp?: string;
+}
+
 export interface TelegramConfig {
   botToken: string;
   chatId: number;
   sessionName: string;
   responseTimeoutMs?: number;
+  permissionTimeoutMs?: number;
 }
 
 export class TelegramManager {
   private bot: TelegramBot;
   private config: TelegramConfig;
   private pendingResponses: Map<string, PendingResponse> = new Map();
+  private pendingPermissions: Map<string, PendingPermission> = new Map();
   private sessionStateFile: string;
   private isRunning = false;
 
   constructor(config: TelegramConfig) {
     this.config = {
       responseTimeoutMs: 180000, // 3 minutes default
+      permissionTimeoutMs: 300000, // 5 minutes for permissions
       ...config,
     };
 
@@ -57,6 +84,7 @@ export class TelegramManager {
     }
 
     this.setupMessageHandler();
+    this.setupCallbackHandler();
     this.updateSessionState({ waitingForResponse: false, messageIds: [] });
   }
 
@@ -151,6 +179,136 @@ export class TelegramManager {
     this.updateSessionState({ waitingForResponse: false, messageIds: [] });
   }
 
+  /**
+   * Handle a permission request from Claude Code hooks
+   * Sends a message with inline buttons and waits for user decision
+   */
+  async handlePermissionRequest(
+    toolName: string,
+    toolInput: Record<string, unknown>
+  ): Promise<PermissionDecision> {
+    // Format the tool input for display
+    const inputDisplay = this.formatToolInput(toolName, toolInput);
+
+    const message = `🔐 [${this.config.sessionName}] Permission Request\n\nTool: ${toolName}\n${inputDisplay}`;
+
+    const sent = await this.bot.sendMessage(this.config.chatId, message, {
+      reply_markup: {
+        inline_keyboard: [
+          [
+            { text: '✅ Allow', callback_data: `allow:${sent?.message_id || 'pending'}` },
+            { text: '❌ Deny', callback_data: `deny:${sent?.message_id || 'pending'}` },
+          ],
+        ],
+      },
+    });
+
+    // Update callback_data with actual message ID
+    await this.bot.editMessageReplyMarkup(
+      {
+        inline_keyboard: [
+          [
+            { text: '✅ Allow', callback_data: `allow:${sent.message_id}` },
+            { text: '❌ Deny', callback_data: `deny:${sent.message_id}` },
+          ],
+        ],
+      },
+      { chat_id: this.config.chatId, message_id: sent.message_id }
+    );
+
+    return this.waitForPermission(sent.message_id, toolName);
+  }
+
+  /**
+   * Send a hook notification (non-blocking)
+   */
+  async sendHookNotification(event: HookEvent): Promise<void> {
+    let emoji = '📢';
+    let title = 'Notification';
+
+    switch (event.type) {
+      case 'stop':
+        emoji = '🛑';
+        title = 'Agent Stopped';
+        break;
+      case 'session_start':
+        emoji = '🚀';
+        title = 'Session Started';
+        break;
+      case 'session_end':
+        emoji = '👋';
+        title = 'Session Ended';
+        break;
+      case 'notification':
+        emoji = '📢';
+        title = 'Notification';
+        break;
+    }
+
+    const message = `${emoji} [${this.config.sessionName}] ${title}\n\n${event.message || 'No details'}`;
+    await this.bot.sendMessage(this.config.chatId, message);
+  }
+
+  /**
+   * Format tool input for display
+   */
+  private formatToolInput(toolName: string, input: Record<string, unknown>): string {
+    // Special formatting for common tools
+    if (toolName === 'Bash' && input.command) {
+      return `Command: \`${input.command}\``;
+    }
+    if (toolName === 'Write' && input.file_path) {
+      const content = input.content as string;
+      const preview = content?.length > 100 ? content.slice(0, 100) + '...' : content;
+      return `File: ${input.file_path}\nContent: ${preview || '(empty)'}`;
+    }
+    if (toolName === 'Edit' && input.file_path) {
+      return `File: ${input.file_path}\nOld: ${input.old_string}\nNew: ${input.new_string}`;
+    }
+    if (toolName === 'Read' && input.file_path) {
+      return `File: ${input.file_path}`;
+    }
+
+    // Default: JSON stringify
+    try {
+      const str = JSON.stringify(input, null, 2);
+      return str.length > 500 ? str.slice(0, 500) + '...' : str;
+    } catch {
+      return '(unable to display input)';
+    }
+  }
+
+  /**
+   * Wait for a permission decision with timeout
+   */
+  private waitForPermission(messageId: number, toolName: string): Promise<PermissionDecision> {
+    return new Promise((resolve, reject) => {
+      const key = `${messageId}`;
+
+      const timeout = setTimeout(() => {
+        this.pendingPermissions.delete(key);
+        // Default to deny on timeout for safety
+        resolve({ behavior: 'deny', message: 'Permission request timed out' });
+      }, this.config.permissionTimeoutMs);
+
+      this.pendingPermissions.set(key, {
+        resolve: (decision: PermissionDecision) => {
+          clearTimeout(timeout);
+          this.pendingPermissions.delete(key);
+          resolve(decision);
+        },
+        reject: (error: Error) => {
+          clearTimeout(timeout);
+          this.pendingPermissions.delete(key);
+          reject(error);
+        },
+        messageId,
+        timestamp: Date.now(),
+        toolName,
+      });
+    });
+  }
+
   /**
    * Set up message handler for incoming messages
    */
@@ -202,6 +360,52 @@ export class TelegramManager {
     });
   }
 
+  /**
+   * Set up callback query handler for inline keyboard buttons
+   */
+  private setupCallbackHandler(): void {
+    this.bot.on('callback_query', async (query) => {
+      if (!query.data || !query.message) return;
+
+      const [action, messageId] = query.data.split(':');
+      const key = messageId;
+
+      console.error(`[${this.config.sessionName}] Callback query: ${action} for message ${messageId}`);
+
+      const pending = this.pendingPermissions.get(key);
+      if (!pending) {
+        // Answer the callback to remove loading state
+        await this.bot.answerCallbackQuery(query.id, { text: 'Request expired' });
+        return;
+      }
+
+      const decision: PermissionDecision = {
+        behavior: action === 'allow' ? 'allow' : 'deny',
+        message: action === 'deny' ? 'Denied by user via Telegram' : undefined,
+      };
+
+      // Update the message to show the decision
+      const statusEmoji = action === 'allow' ? '✅' : '❌';
+      const statusText = action === 'allow' ? 'Allowed' : 'Denied';
+
+      try {
+        await this.bot.editMessageReplyMarkup(
+          { inline_keyboard: [] },
+          { chat_id: query.message.chat.id, message_id: query.message.message_id }
+        );
+        await this.bot.editMessageText(
+          `${query.message.text}\n\n${statusEmoji} ${statusText}`,
+          { chat_id: query.message.chat.id, message_id: query.message.message_id }
+        );
+      } catch {
+        // Ignore edit errors (message might be too old)
+      }
+
+      await this.bot.answerCallbackQuery(query.id, { text: `${statusText}!` });
+      pending.resolve(decision);
+    });
+  }
+
   /**
    * Wait for a response with timeout
    */