telegram-claude-mcp 1.4.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-claude-mcp",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "MCP server that lets Claude message you on Telegram with hooks support",
   "author": "Geravant",
   "license": "MIT",
@@ -27,7 +27,8 @@
   "files": [
     "src",
     "bin",
-    "hooks"
+    "hooks",
+    "README.md"
   ],
   "scripts": {
     "start": "node --import tsx src/index.ts",