telegram-claude-mcp 1.0.3 → 1.2.0

package/hooks/notify-hook.sh

@@ -0,0 +1,76 @@
+#!/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.
+#
+# The script auto-discovers the MCP server port from session info files.
+# No configuration needed - it finds running MCP servers automatically.
+#
+
+SESSION_DIR="/tmp/telegram-claude-sessions"
+EVENT_TYPE="${TELEGRAM_HOOK_EVENT:-stop}"
+
+# Function to find the most recent active session
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+
+  for info_file in "$SESSION_DIR"/*.info 2>/dev/null; do
+    [ -f "$info_file" ] || continue
+
+    # Check if the process is still running
+    local pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
+      if [ "$file_time" -gt "$latest_time" ]; then
+        latest_time=$file_time
+        latest_file=$info_file
+      fi
+    fi
+  done
+
+  echo "$latest_file"
+}
+
+# Find active session info
+INFO_FILE=$(find_active_session)
+
+if [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ]; then
+  echo "[notify-hook] No active session found, skipping notification" >&2
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Read port from session info
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/notify"
+
+echo "[notify-hook] Using session: $INFO_FILE (port $HOOK_PORT)" >&2
+
+# 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"')
+
+echo "[notify-hook] Event: $EVENT_TYPE, 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)
+curl -s -X POST "$HOOK_URL" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  --max-time 10 >/dev/null 2>&1 &
+
+# Return success immediately
+echo '{"continue": true}'

package/hooks/permission-hook.sh

@@ -0,0 +1,86 @@
+#!/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.
+#
+# The script auto-discovers the MCP server port from session info files.
+# No configuration needed - it finds running MCP servers automatically.
+#
+
+SESSION_DIR="/tmp/telegram-claude-sessions"
+
+# Function to find the most recent active session
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+
+  for info_file in "$SESSION_DIR"/*.info 2>/dev/null; do
+    [ -f "$info_file" ] || continue
+
+    # Check if the process is still running
+    local pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
+      if [ "$file_time" -gt "$latest_time" ]; then
+        latest_time=$file_time
+        latest_file=$info_file
+      fi
+    fi
+  done
+
+  echo "$latest_file"
+}
+
+# Find active session info
+INFO_FILE=$(find_active_session)
+
+if [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ]; then
+  echo "[permission-hook] No active session found" >&2
+  # Return empty to fall back to default behavior (terminal prompt)
+  exit 0
+fi
+
+# Read port from session info
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/permission"
+
+echo "[permission-hook] Using session: $INFO_FILE (port $HOOK_PORT)" >&2
+
+# 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, try alternative paths
+if [ -z "$TOOL_NAME" ]; then
+  TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName // .name // empty')
+  TOOL_INPUT=$(echo "$INPUT" | jq -c '.toolInput // .input // .arguments // {}')
+fi
+
+echo "[permission-hook] Tool: $TOOL_NAME" >&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)
+
+if [ $? -ne 0 ]; then
+  echo "[permission-hook] Error: Failed to connect to hook server" >&2
+  # Return empty to fall back to default behavior
+  exit 0
+fi
+
+echo "[permission-hook] Response: $RESPONSE" >&2
+echo "$RESPONSE"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "telegram-claude-mcp",
-  "version": "1.0.3",
-  "description": "MCP server that lets Claude message you on Telegram",
+  "version": "1.2.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,81 @@
  *
  * 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';
+import { writeFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+// Session info directory (shared with hooks)
+const SESSION_DIR = '/tmp/telegram-claude-sessions';
+
+/**
+ * Find an available port starting from the preferred port
+ */
+async function findAvailablePort(preferredPort: number): Promise<number> {
+  const net = await import('net');
+
+  return new Promise((resolve) => {
+    const tryPort = (port: number) => {
+      const server = net.createServer();
+      server.listen(port, '127.0.0.1');
+
+      server.on('listening', () => {
+        server.close(() => resolve(port));
+      });
+
+      server.on('error', () => {
+        // Port in use, try next
+        tryPort(port + 1);
+      });
+    };
+
+    tryPort(preferredPort);
+  });
+}
+
+/**
+ * Write session info file for hooks to discover
+ */
+function writeSessionInfo(sessionName: string, port: number): string {
+  if (!existsSync(SESSION_DIR)) {
+    mkdirSync(SESSION_DIR, { recursive: true });
+  }
+
+  const infoFile = join(SESSION_DIR, `${sessionName}.info`);
+  const info = {
+    port,
+    host: 'localhost',
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+  };
+
+  writeFileSync(infoFile, JSON.stringify(info, null, 2));
+  return infoFile;
+}
+
+/**
+ * Clean up session info file
+ */
+function cleanupSessionInfo(sessionName: string): void {
+  const infoFile = join(SESSION_DIR, `${sessionName}.info`);
+  try {
+    if (existsSync(infoFile)) {
+      unlinkSync(infoFile);
+    }
+  } catch {
+    // Ignore cleanup errors
+  }
+}
 
 async function main() {
   // Load configuration
@@ -35,6 +103,105 @@ async function main() {
 
   telegram.start();
 
+  // Find available port and start HTTP server for hooks
+  const actualPort = await findAvailablePort(config.sessionPort);
+  const sessionInfoFile = writeSessionInfo(config.sessionName, actualPort);
+
+  // 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(actualPort, () => {
+    console.error(`[HTTP] Hook server listening on port ${actualPort}`);
+    if (actualPort !== config.sessionPort) {
+      console.error(`[HTTP] (preferred port ${config.sessionPort} was in use)`);
+    }
+  });
+
   // Track active chat sessions
   let activeSessionId: string | null = null;
 
@@ -186,11 +353,15 @@ 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:${actualPort}`);
+  console.error(`Session info: ${sessionInfoFile}`);
   console.error('');
 
   // Graceful shutdown
   const shutdown = async () => {
     console.error('\nShutting down...');
+    cleanupSessionInfo(config.sessionName);
+    httpServer.close();
     telegram.stop();
     process.exit(0);
   };

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
    */