telegram-claude-mcp 1.3.0 → 1.4.1

package/README.md

@@ -0,0 +1,286 @@
+# telegram-claude-mcp
+
+Get Telegram notifications from Claude Code with interactive permission buttons.
+
+When Claude needs permission to run a command or access a file, you'll get a Telegram message with Allow/Deny buttons. When Claude finishes working, you can reply with more instructions to continue.
+
+## Quick Start
+
+```bash
+npx telegram-claude-setup
+```
+
+Then:
+1. Create a Telegram bot via [@BotFather](https://t.me/BotFather)
+2. Get your chat ID (see instructions below)
+3. Edit `~/.claude/settings.json` with your bot token and chat ID
+4. Restart Claude Code
+
+## Features
+
+- **Permission buttons** - Allow/Deny tool usage from Telegram
+- **Interactive stop** - Reply to continue Claude's work after it stops
+- **Notifications** - Get notified about Claude events
+- **Multi-session** - Run multiple Claude instances with message tagging
+
+## Manual Installation
+
+If you prefer not to use npm, follow these steps:
+
+### 1. Create Hook Scripts
+
+Create directory `~/.claude/hooks/` and add these scripts:
+
+**~/.claude/hooks/permission-hook.sh**
+```bash
+#!/bin/bash
+SESSION_DIR="/tmp/telegram-claude-sessions"
+
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+  [ -d "$SESSION_DIR" ] || return
+  for info_file in "$SESSION_DIR"/*.info; do
+    [ -e "$info_file" ] || continue
+    local pid
+    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time
+      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"
+}
+
+INFO_FILE=$(find_active_session)
+[ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
+
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/permission"
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // .toolName // .name // empty')
+TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // .toolInput // .input // .arguments // {}')
+
+PAYLOAD=$(jq -n --arg tool_name "$TOOL_NAME" --argjson tool_input "$TOOL_INPUT" \
+  '{tool_name: $tool_name, tool_input: $tool_input}')
+
+RESPONSE=$(curl -s -X POST "$HOOK_URL" -H "Content-Type: application/json" -d "$PAYLOAD" --max-time 600)
+[ $? -eq 0 ] && echo "$RESPONSE"
+```
+
+**~/.claude/hooks/stop-hook.sh**
+```bash
+#!/bin/bash
+SESSION_DIR="/tmp/telegram-claude-sessions"
+
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+  [ -d "$SESSION_DIR" ] || return
+  for info_file in "$SESSION_DIR"/*.info; do
+    [ -e "$info_file" ] || continue
+    local pid
+    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time
+      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"
+}
+
+INPUT=$(cat)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+[ "$STOP_HOOK_ACTIVE" = "true" ] && exit 0
+
+INFO_FILE=$(find_active_session)
+[ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
+
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/stop"
+
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+PAYLOAD=$(jq -n --arg transcript_path "$TRANSCRIPT_PATH" '{transcript_path: $transcript_path}')
+
+RESPONSE=$(curl -s -X POST "$HOOK_URL" -H "Content-Type: application/json" -d "$PAYLOAD" --max-time 300)
+if [ $? -eq 0 ]; then
+  DECISION=$(echo "$RESPONSE" | jq -r '.decision // empty')
+  [ "$DECISION" = "block" ] && echo "$RESPONSE"
+fi
+```
+
+**~/.claude/hooks/notify-hook.sh**
+```bash
+#!/bin/bash
+SESSION_DIR="/tmp/telegram-claude-sessions"
+
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+  [ -d "$SESSION_DIR" ] || return
+  for info_file in "$SESSION_DIR"/*.info; do
+    [ -e "$info_file" ] || continue
+    local pid
+    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time
+      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"
+}
+
+INFO_FILE=$(find_active_session)
+[ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
+
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/notify"
+
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | jq -r '.message // "Notification"')
+PAYLOAD=$(jq -n --arg type "notification" --arg message "$MESSAGE" '{type: $type, message: $message}')
+
+curl -s -X POST "$HOOK_URL" -H "Content-Type: application/json" -d "$PAYLOAD" --max-time 10 >/dev/null 2>&1
+```
+
+Make them executable:
+```bash
+chmod +x ~/.claude/hooks/*.sh
+```
+
+### 2. Configure Claude Settings
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PermissionRequest": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-hook.sh" }]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "~/.claude/hooks/stop-hook.sh" }]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "~/.claude/hooks/notify-hook.sh" }]
+      }
+    ]
+  },
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "telegram-claude-mcp"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
+        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID",
+        "SESSION_NAME": "default"
+      }
+    }
+  }
+}
+```
+
+### 3. Create Telegram Bot
+
+1. Open Telegram and message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot` and follow prompts
+3. Copy the bot token
+
+### 4. Get Your Chat ID
+
+1. Start a chat with your new bot
+2. Send any message to it
+3. Visit: `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
+4. Find `"chat":{"id": YOUR_CHAT_ID}` in the response
+
+### 5. Update Settings
+
+Replace `YOUR_BOT_TOKEN` and `YOUR_CHAT_ID` in `~/.claude/settings.json`
+
+### 6. Restart Claude Code
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | Yes |
+| `TELEGRAM_CHAT_ID` | Your Telegram chat ID | Yes |
+| `SESSION_NAME` | Session identifier (for multi-instance) | No (default: "default") |
+| `SESSION_PORT` | Preferred HTTP port | No (default: 3333, auto-finds available) |
+
+## How It Works
+
+```
+Claude Code                    Hook Scripts                 telegram-claude-mcp
+    |                              |                              |
+    |-- Permission needed -------->|                              |
+    |                              |-- POST /permission --------->|
+    |                              |                              |-- Send to Telegram
+    |                              |                              |<- User clicks Allow
+    |                              |<-------- {allow} ------------|
+    |<-------- Allow --------------|                              |
+    |                              |                              |
+    |-- Work complete, stops ----->|                              |
+    |                              |-- POST /stop --------------->|
+    |                              |                              |-- Send to Telegram
+    |                              |                              |<- User replies
+    |                              |<-- {block, "do X next"} -----|
+    |<-- Continue with "do X" -----|                              |
+```
+
+## Multiple Sessions
+
+Run multiple Claude instances with different session names:
+
+```json
+{
+  "env": {
+    "SESSION_NAME": "project-a"
+  }
+}
+```
+
+Messages are tagged with `[project-a]` so you know which instance sent them.
+
+## Troubleshooting
+
+**Buttons appear but don't work:**
+- Check for stale MCP processes: `ps aux | grep telegram-claude`
+- Kill old processes and restart Claude
+
+**No messages in Telegram:**
+- Verify bot token and chat ID are correct
+- Ensure you've started a chat with your bot
+- Check Claude's MCP server logs
+
+**Permission hook not firing:**
+- Verify hook scripts are executable: `ls -la ~/.claude/hooks/`
+- Check Claude settings have hooks configured
+
+## License
+
+MIT

package/bin/setup.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+
+/**
+ * Setup script for telegram-claude-mcp hooks integration
+ *
+ * Usage: npx telegram-claude-mcp setup
+ *
+ * This will:
+ * 1. Copy hook scripts to ~/.claude/hooks/
+ * 2. Update Claude settings with hooks configuration
+ * 3. Display instructions for completing setup
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, chmodSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const CLAUDE_DIR = join(homedir(), '.claude');
+const HOOKS_DIR = join(CLAUDE_DIR, 'hooks');
+const SETTINGS_FILE = join(CLAUDE_DIR, 'settings.json');
+
+// Hook scripts content
+const PERMISSION_HOOK = `#!/bin/bash
+#
+# Claude Code Permission Hook - forwards permission requests to Telegram
+#
+
+SESSION_DIR="/tmp/telegram-claude-sessions"
+
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+
+  [ -d "$SESSION_DIR" ] || return
+
+  for info_file in "$SESSION_DIR"/*.info; do
+    [ -e "$info_file" ] || continue
+
+    local pid
+    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time
+      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"
+}
+
+INFO_FILE=$(find_active_session)
+
+if [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ]; then
+  exit 0
+fi
+
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://\${HOOK_HOST}:\${HOOK_PORT}/permission"
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
+
+if [ -z "$TOOL_NAME" ]; then
+  TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName // .name // empty')
+  TOOL_INPUT=$(echo "$INPUT" | jq -c '.toolInput // .input // .arguments // {}')
+fi
+
+PAYLOAD=$(jq -n \\
+  --arg tool_name "$TOOL_NAME" \\
+  --argjson tool_input "$TOOL_INPUT" \\
+  '{tool_name: $tool_name, tool_input: $tool_input}')
+
+RESPONSE=$(curl -s -X POST "$HOOK_URL" \\
+  -H "Content-Type: application/json" \\
+  -d "$PAYLOAD" \\
+  --max-time 600)
+
+[ $? -eq 0 ] && echo "$RESPONSE"
+`;
+
+const STOP_HOOK = `#!/bin/bash
+#
+# Claude Code Interactive Stop Hook - sends stop notification and waits for reply
+#
+
+SESSION_DIR="/tmp/telegram-claude-sessions"
+
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+
+  [ -d "$SESSION_DIR" ] || return
+
+  for info_file in "$SESSION_DIR"/*.info; do
+    [ -e "$info_file" ] || continue
+
+    local pid
+    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time
+      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"
+}
+
+INPUT=$(cat)
+
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+INFO_FILE=$(find_active_session)
+
+if [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ]; then
+  exit 0
+fi
+
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://\${HOOK_HOST}:\${HOOK_PORT}/stop"
+
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+
+PAYLOAD=$(jq -n \\
+  --arg transcript_path "$TRANSCRIPT_PATH" \\
+  '{transcript_path: $transcript_path}')
+
+RESPONSE=$(curl -s -X POST "$HOOK_URL" \\
+  -H "Content-Type: application/json" \\
+  -d "$PAYLOAD" \\
+  --max-time 300)
+
+if [ $? -eq 0 ]; then
+  DECISION=$(echo "$RESPONSE" | jq -r '.decision // empty')
+  REASON=$(echo "$RESPONSE" | jq -r '.reason // empty')
+
+  if [ "$DECISION" = "block" ] && [ -n "$REASON" ]; then
+    echo "$RESPONSE"
+  fi
+fi
+`;
+
+const NOTIFY_HOOK = `#!/bin/bash
+#
+# Claude Code Notification Hook - sends notifications to Telegram
+#
+
+SESSION_DIR="/tmp/telegram-claude-sessions"
+
+find_active_session() {
+  local latest_file=""
+  local latest_time=0
+
+  [ -d "$SESSION_DIR" ] || return
+
+  for info_file in "$SESSION_DIR"/*.info; do
+    [ -e "$info_file" ] || continue
+
+    local pid
+    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      local file_time
+      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"
+}
+
+INFO_FILE=$(find_active_session)
+
+if [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ]; then
+  exit 0
+fi
+
+HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
+HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
+HOOK_URL="http://\${HOOK_HOST}:\${HOOK_PORT}/notify"
+
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | jq -r '.message // "Notification from Claude"')
+
+PAYLOAD=$(jq -n \\
+  --arg type "notification" \\
+  --arg message "$MESSAGE" \\
+  '{type: $type, message: $message}')
+
+curl -s -X POST "$HOOK_URL" \\
+  -H "Content-Type: application/json" \\
+  -d "$PAYLOAD" \\
+  --max-time 10 > /dev/null 2>&1
+`;
+
+// Hooks configuration for Claude settings
+const HOOKS_CONFIG = {
+  PermissionRequest: [
+    {
+      matcher: '*',
+      hooks: [
+        {
+          type: 'command',
+          command: '~/.claude/hooks/permission-hook.sh'
+        }
+      ]
+    }
+  ],
+  Stop: [
+    {
+      matcher: '*',
+      hooks: [
+        {
+          type: 'command',
+          command: '~/.claude/hooks/stop-hook.sh'
+        }
+      ]
+    }
+  ],
+  Notification: [
+    {
+      matcher: '*',
+      hooks: [
+        {
+          type: 'command',
+          command: '~/.claude/hooks/notify-hook.sh'
+        }
+      ]
+    }
+  ]
+};
+
+function setup() {
+  console.log('\n📱 telegram-claude-mcp Setup\n');
+  console.log('This will configure Telegram notifications for Claude Code.\n');
+
+  // Create hooks directory
+  if (!existsSync(HOOKS_DIR)) {
+    mkdirSync(HOOKS_DIR, { recursive: true });
+    console.log('✓ Created ~/.claude/hooks/');
+  }
+
+  // Write hook scripts
+  const permissionHookPath = join(HOOKS_DIR, 'permission-hook.sh');
+  writeFileSync(permissionHookPath, PERMISSION_HOOK);
+  chmodSync(permissionHookPath, 0o755);
+  console.log('✓ Installed permission-hook.sh');
+
+  const stopHookPath = join(HOOKS_DIR, 'stop-hook.sh');
+  writeFileSync(stopHookPath, STOP_HOOK);
+  chmodSync(stopHookPath, 0o755);
+  console.log('✓ Installed stop-hook.sh');
+
+  const notifyHookPath = join(HOOKS_DIR, 'notify-hook.sh');
+  writeFileSync(notifyHookPath, NOTIFY_HOOK);
+  chmodSync(notifyHookPath, 0o755);
+  console.log('✓ Installed notify-hook.sh');
+
+  // Update Claude settings
+  let settings = {};
+  if (existsSync(SETTINGS_FILE)) {
+    try {
+      settings = JSON.parse(readFileSync(SETTINGS_FILE, 'utf-8'));
+    } catch {
+      console.log('⚠ Could not parse existing settings.json, creating new one');
+    }
+  }
+
+  // Merge hooks config
+  settings.hooks = { ...settings.hooks, ...HOOKS_CONFIG };
+
+  // Add MCP server config if not present
+  if (!settings.mcpServers) {
+    settings.mcpServers = {};
+  }
+
+  if (!settings.mcpServers.telegram) {
+    settings.mcpServers.telegram = {
+      command: 'npx',
+      args: ['-y', 'telegram-claude-mcp'],
+      env: {
+        TELEGRAM_BOT_TOKEN: 'YOUR_BOT_TOKEN',
+        TELEGRAM_CHAT_ID: 'YOUR_CHAT_ID',
+        SESSION_NAME: 'default'
+      }
+    };
+    console.log('✓ Added telegram MCP server config (needs bot token)');
+  }
+
+  writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2));
+  console.log('✓ Updated ~/.claude/settings.json with hooks');
+
+  // Print next steps
+  console.log('\n' + '─'.repeat(50));
+  console.log('\n📋 Next Steps:\n');
+
+  console.log('1. Create a Telegram bot:');
+  console.log('   - Open Telegram and message @BotFather');
+  console.log('   - Send /newbot and follow the prompts');
+  console.log('   - Copy the bot token\n');
+
+  console.log('2. Get your Chat ID:');
+  console.log('   - Start a chat with your new bot');
+  console.log('   - Send any message');
+  console.log('   - Visit: https://api.telegram.org/bot<TOKEN>/getUpdates');
+  console.log('   - Find "chat":{"id": YOUR_CHAT_ID}\n');
+
+  console.log('3. Update ~/.claude/settings.json:');
+  console.log('   - Set TELEGRAM_BOT_TOKEN to your bot token');
+  console.log('   - Set TELEGRAM_CHAT_ID to your chat ID\n');
+
+  console.log('4. Restart Claude Code\n');
+
+  console.log('─'.repeat(50));
+  console.log('\n✨ Setup complete! Configure your bot token and chat ID to finish.\n');
+}
+
+// Run setup
+setup();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-claude-mcp",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "MCP server that lets Claude message you on Telegram with hooks support",
   "author": "Geravant",
   "license": "MIT",
@@ -21,12 +21,14 @@
   "type": "module",
   "main": "src/index.ts",
   "bin": {
-    "telegram-claude-mcp": "./bin/run.js"
+    "telegram-claude-mcp": "./bin/run.js",
+    "telegram-claude-setup": "./bin/setup.js"
   },
   "files": [
     "src",
     "bin",
-    "hooks"
+    "hooks",
+    "README.md"
   ],
   "scripts": {
     "start": "node --import tsx src/index.ts",