telegram-claude-mcp 1.6.1 → 2.0.2

package/ARCHITECTURE.md

@@ -0,0 +1,234 @@
+# Architecture Options for Multi-Session MCP
+
+This document describes three approaches for handling multiple Claude Code sessions with a shared Telegram bot.
+
+## Current Architecture (Baseline)
+
+```
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Server 1 (port 3333)           │
+│                 │                │  ├─ TelegramManager (polling)       │──►┌──────────┐
+│                 │                │  └─ HTTP Hook Server                │   │          │
+└─────────────────┘                └─────────────────────────────────────┘   │          │
+                                                                             │ Telegram │
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐   │   Bot    │
+│  Claude Code 2  │◄──────────────►│  MCP Server 2 (port 3334)           │   │          │
+│                 │                │  ├─ TelegramManager (polling)       │──►│          │
+│                 │                │  └─ HTTP Hook Server                │   └──────────┘
+└─────────────────┘                └─────────────────────────────────────┘
+
+Hook scripts discover ports via /tmp/telegram-claude-sessions/*.info files
+```
+
+**Problems:**
+- Multiple bot polling instances (potential rate limiting)
+- Port collision handling complexity
+- Session discovery via filesystem
+- Each process manages its own state
+
+---
+
+## Option 1: Proxy Pattern (Recommended)
+
+A singleton daemon handles all Telegram communication. Thin MCP proxies forward requests.
+
+```
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     ┌─────────────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Proxy 1    │◄───────────────────►│                             │
+│                 │                │  (session: proj1)│                     │     Singleton Daemon        │
+└─────────────────┘                └─────────────────┘                     │     (single process)        │
+                                                                           │                             │
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     │  ├─ TelegramManager         │──►┌──────────┐
+│  Claude Code 2  │◄──────────────►│  MCP Proxy 2    │◄───────────────────►│  │  (single polling)        │   │ Telegram │
+│                 │                │  (session: proj2)│                     │  ├─ SessionManager          │   │   Bot    │
+└─────────────────┘                └─────────────────┘                     │  │  (tracks all sessions)   │   └──────────┘
+                                                                           │  └─ HTTP Hook Server        │
+                                   ┌─────────────────┐     HTTP POST       │     (single port: 3333)     │
+                                   │  Hook Scripts   │────────────────────►│                             │
+                                   └─────────────────┘                     └─────────────────────────────┘
+```
+
+### Components
+
+**1. Singleton Daemon (`telegram-claude-daemon`)**
+- Single long-running process
+- Manages one TelegramManager with single bot polling
+- Exposes Unix socket for proxy connections
+- Exposes single HTTP port for all hooks
+- Tracks all active sessions in memory
+- Routes messages to correct session
+
+**2. MCP Proxy (`telegram-claude-proxy`)**
+- Spawned by Claude Code (stdio transport)
+- Connects to daemon via Unix socket
+- Registers session with unique ID
+- Forwards MCP tool calls to daemon
+- Receives responses from daemon
+
+### Protocol (Daemon <-> Proxy)
+
+```typescript
+// Proxy -> Daemon
+interface ProxyMessage {
+  type: 'connect' | 'disconnect' | 'tool_call';
+  sessionId: string;
+  sessionName: string;
+  payload?: {
+    tool: string;
+    arguments: Record<string, unknown>;
+  };
+}
+
+// Daemon -> Proxy
+interface DaemonMessage {
+  type: 'connected' | 'tool_result' | 'error';
+  sessionId: string;
+  payload?: {
+    result?: unknown;
+    error?: string;
+  };
+}
+```
+
+### Advantages
+- Single bot polling (no rate limiting)
+- Single port for hooks (no discovery needed)
+- Centralized session management
+- Clean separation of concerns
+- Daemon can outlive individual sessions
+
+### Disadvantages
+- Requires daemon to be running before Claude Code starts
+- Additional IPC complexity
+- Single point of failure
+
+### Implementation Files
+```
+server/src/
+├── daemon/
+│   ├── index.ts          # Daemon entry point
+│   ├── session-manager.ts # Track active sessions
+│   └── ipc-server.ts     # Unix socket server
+├── proxy/
+│   ├── index.ts          # Proxy entry point (MCP stdio)
+│   └── ipc-client.ts     # Unix socket client
+└── shared/
+    └── protocol.ts       # Shared types and constants
+```
+
+---
+
+## Option 2: Shared State Pattern
+
+Keep MCP-per-session but share Telegram connection via IPC to a daemon.
+
+```
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Server 1                       │
+│                 │                │  ├─ Full MCP implementation         │
+│                 │                │  ├─ HTTP Hook Server (port 3333)    │───┐
+└─────────────────┘                │  └─ IPC Client                      │   │
+                                   └─────────────────────────────────────┘   │
+                                                    │                        │
+                                                    │ IPC (send/receive)     │ HTTP
+                                                    ▼                        │
+                                   ┌─────────────────────────────────────┐   │
+                                   │  Telegram Daemon                    │   │
+                                   │  ├─ TelegramManager (single poll)  │──►┌──────────┐
+                                   │  └─ Message Router                  │   │ Telegram │
+                                   └─────────────────────────────────────┘   │   Bot    │
+                                                    ▲                        └──────────┘
+                                                    │ IPC (send/receive)
+                                                    │
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐
+│  Claude Code 2  │◄──────────────►│  MCP Server 2                       │
+│                 │                │  ├─ Full MCP implementation         │
+│                 │                │  ├─ HTTP Hook Server (port 3334)    │
+│                 │                │  └─ IPC Client                      │
+└─────────────────┘                └─────────────────────────────────────┘
+```
+
+### How It Works
+1. Each MCP server maintains its own HTTP hook server
+2. Telegram operations are forwarded to a shared daemon
+3. Daemon handles actual Telegram API calls
+4. Responses routed back via IPC
+
+### Advantages
+- MCP servers remain mostly unchanged
+- Gradual migration path
+- Each session still has its own hook endpoint
+
+### Disadvantages
+- Still requires port management for hooks
+- More complex message routing
+- Partial duplication of logic
+
+---
+
+## Option 3: Session ID in Tool Calls
+
+Single MCP server process, sessions identified by explicit IDs in every tool call.
+
+```
+┌─────────────────┐                              ┌─────────────────────────────┐
+│  Claude Code 1  │──┐                           │                             │
+│                 │  │   Multiple stdio          │  Singleton MCP Server       │
+└─────────────────┘  │   connections via         │                             │
+                     │   wrapper/multiplexer     │  ├─ TelegramManager         │──►┌──────────┐
+┌─────────────────┐  │                           │  ├─ SessionManager          │   │ Telegram │
+│  Claude Code 2  │──┼──────────────────────────►│  └─ HTTP Hook Server        │   │   Bot    │
+│                 │  │                           │                             │   └──────────┘
+└─────────────────┘  │                           │  Tools include session_id:  │
+                     │                           │  - send_message(session_id) │
+┌─────────────────┐  │                           │  - continue_chat(session_id)│
+│  Claude Code 3  │──┘                           │                             │
+└─────────────────┘                              └─────────────────────────────┘
+```
+
+### How It Works
+1. Single MCP server handles all sessions
+2. `connect` tool registers new session, returns session_id
+3. All other tools require session_id parameter
+4. Server routes operations by session_id
+
+### Challenges
+- MCP's stdio transport is 1:1 (one client per process)
+- Would need a multiplexer/wrapper to share one MCP server
+- Violates MCP design assumptions
+- Complex error handling when sessions disconnect
+
+### Advantages
+- Simplest daemon architecture
+- Single process for everything
+
+### Disadvantages
+- Requires custom MCP multiplexer
+- Not standard MCP usage
+- Harder to implement correctly
+
+---
+
+## Comparison Matrix
+
+| Aspect                    | Current      | Option 1 (Proxy)  | Option 2 (Shared) | Option 3 (Session ID) |
+|---------------------------|--------------|-------------------|-------------------|----------------------|
+| Bot polling instances     | N            | 1                 | 1                 | 1                    |
+| Port management           | Complex      | Simple (1 port)   | Complex           | Simple (1 port)      |
+| MCP compatibility         | Standard     | Standard          | Standard          | Non-standard         |
+| Implementation effort     | Done         | Medium            | Medium-High       | High                 |
+| Session isolation         | Full         | Full              | Full              | Logical only         |
+| Daemon dependency         | No           | Yes               | Yes               | Yes                  |
+| Hook simplicity           | Medium       | Simple            | Medium            | Simple               |
+
+---
+
+## Recommended: Option 1 (Proxy Pattern)
+
+Option 1 provides the best balance of:
+- **Simplicity**: Single port, single polling instance
+- **Compatibility**: Standard MCP stdio transport
+- **Reliability**: Clean session management
+- **Maintainability**: Clear separation between proxy and daemon
+
+The proxy is lightweight and only handles MCP protocol translation, while the daemon manages all Telegram complexity.

package/README.md

@@ -353,6 +353,128 @@ Each Claude config needs a unique `SESSION_NAME` in **both** the MCP server env
 - Verify hook scripts are executable: `ls -la ~/.claude/hooks/`
 - Check Claude settings have hooks configured
 
+---
+
+## v2: Daemon Architecture (Recommended for Multiple Sessions)
+
+Version 2 introduces a singleton daemon architecture that handles all Telegram communication from one process. This solves:
+- Multiple bot polling instances causing rate limiting
+- Complex port discovery between sessions
+- Session state synchronization issues
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed design documentation.
+
+### Quick Start with Daemon
+
+**Option A: Auto-start (recommended)**
+
+The proxy can auto-start the daemon if you provide credentials in the MCP config:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "telegram-claude-proxy"],
+      "env": {
+        "SESSION_NAME": "main",
+        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
+        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID"
+      }
+    }
+  }
+}
+```
+
+The first Claude session will start the daemon automatically. Subsequent sessions connect to the already-running daemon.
+
+**Option B: Manual daemon start**
+
+Start the daemon once, then proxies connect without needing credentials:
+
+```bash
+# Start daemon with credentials
+TELEGRAM_BOT_TOKEN=xxx TELEGRAM_CHAT_ID=yyy telegram-claude-ctl start
+
+# Check status
+telegram-claude-ctl status
+```
+
+2. **Configure Claude to use the proxy** in `~/.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "PermissionRequest": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks-v2/permission-hook.sh" }]
+    }],
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks-v2/stop-hook.sh" }]
+    }],
+    "Notification": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks-v2/notify-hook.sh" }]
+    }]
+  },
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "telegram-claude-proxy"],
+      "env": {
+        "SESSION_NAME": "main"
+      }
+    }
+  }
+}
+```
+
+### Daemon Commands
+
+```bash
+# Start daemon in background
+telegram-claude-ctl start
+
+# Stop daemon
+telegram-claude-ctl stop
+
+# Restart daemon
+telegram-claude-ctl restart
+
+# Check status (shows active sessions)
+telegram-claude-ctl status
+```
+
+### Architecture Overview
+
+```
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     ┌─────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Proxy 1    │◄───────────────────►│                     │
+└─────────────────┘                └─────────────────┘                     │  Singleton Daemon   │
+                                                                           │                     │
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     │  - Single bot poll  │──► Telegram
+│  Claude Code 2  │◄──────────────►│  MCP Proxy 2    │◄───────────────────►│  - Session manager  │
+└─────────────────┘                └─────────────────┘                     │  - HTTP hooks :3333 │
+                                                                           └─────────────────────┘
+```
+
+### Environment Variables (Daemon)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | Required |
+| `TELEGRAM_CHAT_ID` | Your Telegram chat ID | Required |
+| `CHAT_RESPONSE_TIMEOUT_MS` | Response timeout | 600000 (10 min) |
+| `PERMISSION_TIMEOUT_MS` | Permission timeout | 600000 (10 min) |
+
+### Environment Variables (Proxy/Hooks)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SESSION_NAME` | Session identifier | Auto-detected from CWD |
+| `TELEGRAM_CLAUDE_PORT` | Daemon HTTP port | 3333 |
+| `TELEGRAM_CLAUDE_HOST` | Daemon host | localhost |
+
 ## License
 
 MIT

package/bin/daemon-ctl.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * Daemon Control CLI
+ *
+ * Manage the telegram-claude-daemon:
+ *   daemon-ctl start   - Start the daemon
+ *   daemon-ctl stop    - Stop the daemon
+ *   daemon-ctl restart - Restart the daemon
+ *   daemon-ctl status  - Check daemon status
+ *   daemon-ctl logs    - Show daemon logs (if running with pm2 or similar)
+ */
+
+import { spawn, execSync } from 'child_process';
+import { existsSync, readFileSync, unlinkSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const DAEMON_PID_FILE = '/tmp/telegram-claude-daemon.pid';
+const DAEMON_SOCKET_PATH = '/tmp/telegram-claude-daemon.sock';
+const DAEMON_HTTP_PORT = 3333;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const daemonScript = join(__dirname, '..', 'dist', 'daemon', 'index.js');
+const daemonSrc = join(__dirname, '..', 'src', 'daemon', 'index.ts');
+
+function getPid() {
+  if (existsSync(DAEMON_PID_FILE)) {
+    try {
+      const pid = parseInt(readFileSync(DAEMON_PID_FILE, 'utf-8').trim(), 10);
+      // Check if process is alive
+      try {
+        process.kill(pid, 0);
+        return pid;
+      } catch {
+        // Process not running, clean up stale files
+        cleanup();
+        return null;
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function cleanup() {
+  try {
+    if (existsSync(DAEMON_PID_FILE)) unlinkSync(DAEMON_PID_FILE);
+    if (existsSync(DAEMON_SOCKET_PATH)) unlinkSync(DAEMON_SOCKET_PATH);
+  } catch {}
+}
+
+async function getStatus() {
+  const pid = getPid();
+  if (!pid) {
+    return { running: false };
+  }
+
+  try {
+    const response = await fetch(`http://localhost:${DAEMON_HTTP_PORT}/status`);
+    const data = await response.json();
+    return { running: true, pid, ...data };
+  } catch {
+    return { running: true, pid, sessions: [] };
+  }
+}
+
+async function start() {
+  const pid = getPid();
+  if (pid) {
+    console.log(`Daemon already running (PID: ${pid})`);
+    return;
+  }
+
+  // Determine which script to run
+  let script = daemonScript;
+  let runner = 'node';
+
+  if (!existsSync(daemonScript)) {
+    if (existsSync(daemonSrc)) {
+      script = daemonSrc;
+      runner = 'bun';
+    } else {
+      console.error('Error: Daemon script not found. Run `npm run build` first.');
+      process.exit(1);
+    }
+  }
+
+  console.log('Starting telegram-claude-daemon...');
+
+  const child = spawn(runner, [script], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: process.env,
+  });
+
+  child.unref();
+
+  // Wait for daemon to start
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+
+  const newPid = getPid();
+  if (newPid) {
+    console.log(`Daemon started (PID: ${newPid})`);
+    console.log(`  Socket: ${DAEMON_SOCKET_PATH}`);
+    console.log(`  HTTP: http://localhost:${DAEMON_HTTP_PORT}`);
+  } else {
+    console.error('Failed to start daemon');
+    process.exit(1);
+  }
+}
+
+function stop() {
+  const pid = getPid();
+  if (!pid) {
+    console.log('Daemon is not running');
+    return;
+  }
+
+  console.log(`Stopping daemon (PID: ${pid})...`);
+
+  try {
+    process.kill(pid, 'SIGTERM');
+
+    // Wait for process to exit
+    let attempts = 0;
+    while (attempts < 10) {
+      try {
+        process.kill(pid, 0);
+        execSync('sleep 0.5');
+        attempts++;
+      } catch {
+        break;
+      }
+    }
+
+    cleanup();
+    console.log('Daemon stopped');
+  } catch (err) {
+    console.error('Failed to stop daemon:', err.message);
+    cleanup();
+  }
+}
+
+async function status() {
+  const info = await getStatus();
+
+  if (!info.running) {
+    console.log('Daemon: not running');
+    return;
+  }
+
+  console.log('Daemon: running');
+  console.log(`  PID: ${info.pid}`);
+  console.log(`  Version: ${info.version || 'unknown'}`);
+  console.log(`  Active Sessions: ${info.activeSessions || 0}`);
+
+  if (info.sessions && info.sessions.length > 0) {
+    console.log('  Sessions:');
+    for (const session of info.sessions) {
+      console.log(`    - ${session.sessionName} (${session.sessionId})`);
+      console.log(`      Connected: ${session.connectedAt}`);
+      console.log(`      Last Activity: ${session.lastActivity}`);
+    }
+  }
+}
+
+async function main() {
+  const command = process.argv[2];
+
+  switch (command) {
+    case 'start':
+      await start();
+      break;
+
+    case 'stop':
+      stop();
+      break;
+
+    case 'restart':
+      stop();
+      await new Promise((r) => setTimeout(r, 500));
+      await start();
+      break;
+
+    case 'status':
+      await status();
+      break;
+
+    default:
+      console.log('Usage: daemon-ctl <command>');
+      console.log('');
+      console.log('Commands:');
+      console.log('  start   - Start the daemon');
+      console.log('  stop    - Stop the daemon');
+      console.log('  restart - Restart the daemon');
+      console.log('  status  - Check daemon status');
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/bin/daemon.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+/**
+ * Telegram Claude Daemon launcher
+ *
+ * Usage: telegram-claude-daemon
+ *
+ * Required environment variables:
+ *   TELEGRAM_BOT_TOKEN - Your Telegram bot token
+ *   TELEGRAM_CHAT_ID - Your Telegram chat ID
+ */
+
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+// Register tsx loader for TypeScript support
+register('tsx', pathToFileURL('./'));
+
+// Import and run the daemon
+import('../src/daemon/index.ts');

package/bin/proxy.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Telegram Claude MCP Proxy launcher
+ *
+ * Usage: telegram-claude-proxy
+ *
+ * This connects to a running telegram-claude-daemon via Unix socket.
+ * Make sure to start the daemon first: telegram-claude-ctl start
+ *
+ * Optional environment variables:
+ *   SESSION_NAME - Session identifier (default: auto-detected from CWD)
+ */
+
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+// Register tsx loader for TypeScript support
+register('tsx', pathToFileURL('./'));
+
+// Import and run the proxy
+import('../src/proxy/index.ts');

package/hooks/stop-hook.sh

@@ -108,6 +108,8 @@ REASON=$(echo "$RESPONSE" | jq -r '.reason // empty')
 if [ "$DECISION" = "block" ] && [ -n "$REASON" ]; then
   # User provided instructions - continue with them
   echo "$RESPONSE"
+  # Exit code 2 tells Claude Code to continue with the reason as instructions
+  exit 2
 else
   # User said done or no response - allow stop
   exit 0

package/hooks-v2/notify-hook.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Notify hook for telegram-claude-daemon (v2)
+# Uses single daemon port instead of session discovery
+
+DAEMON_PORT="${TELEGRAM_CLAUDE_PORT:-3333}"
+DAEMON_HOST="${TELEGRAM_CLAUDE_HOST:-localhost}"
+HOOK_URL="http://${DAEMON_HOST}:${DAEMON_PORT}/notify"
+
+# Read input from stdin
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | jq -r '.message // "Notification"')
+
+# Build payload
+if [ -n "$SESSION_NAME" ]; then
+  PAYLOAD=$(jq -n \
+    --arg type "notification" \
+    --arg message "$MESSAGE" \
+    --arg session_name "$SESSION_NAME" \
+    '{type: $type, message: $message, session_name: $session_name}')
+else
+  PAYLOAD=$(jq -n \
+    --arg type "notification" \
+    --arg message "$MESSAGE" \
+    '{type: $type, message: $message}')
+fi
+
+# Send to daemon (non-blocking, 10 second timeout)
+curl -s -X POST "$HOOK_URL" \
+  -H "Content-Type: application/json" \
+  -H "X-Session-Name: ${SESSION_NAME:-default}" \
+  -d "$PAYLOAD" \
+  --max-time 10 >/dev/null 2>&1