feat: add easy multi-project setup and tool discovery

Makes it simple to use the Telegram bridge MCP server in multiple Claude projects with minimal configuration. New Features: - Auto-generate MCP config: `pnpm config` - List available tools: `pnpm tools` - Multi-project setup guide (SETUP-FOR-OTHER-PROJECTS.md) - MCP config template (.claude-mcp-template.json) - Helper scripts for config generation Changes: - Added scripts/get-mcp-config.sh - Auto-generates MCP config with correct paths - Added scripts/list-tools.js - Lists all 5 MCP tools with descriptions - Added SETUP-FOR-OTHER-PROJECTS.md - Guide for using in multiple projects - Updated README with easier setup options - Added npm scripts: `tools` and `config` Now you can: 1. Install bridge once 2. Run `pnpm config` to get MCP config 3. Copy to any project's .claude/mcp.json 4. Use Telegram tools in that project! 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-23 01:04:16 -05:00
parent 6c8c9350a1
commit fdb1fa74b4
6 changed files with 326 additions and 7 deletions
--- a/.claude-mcp-template.json
+++ b/.claude-mcp-template.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://modelcontextprotocol.io/schema/mcp.json",
+  "mcpServers": {
+    "telegram": {
+      "command": "node",
+      "args": [
+        "/REPLACE/WITH/ABSOLUTE/PATH/TO/claude-telegram-bridge/dist/mcp-server.js"
+      ],
+      "env": {
+        "TELEGRAM_BRIDGE_URL": "http://localhost:3456"
+      }
+    }
+  }
+}
--- a/README.md
+++ b/README.md
@@ -26,6 +26,19 @@ After trying email, SMS, and Google Chat integrations, Telegram emerged as the b
 - 🔔 **Priority Notifications** - Different icons for info, success, warning, error, question
 - 🌐 **HTTP API** - Easy integration from any app/project
 - 🚀 **Background Service** - Runs independently, always available
+- 🔧 **MCP Protocol** - Works as a standard MCP server in any Claude project
+
+## Using in Other Projects
+
+**Already have the bridge installed?** Just add this to your project's `.claude/mcp.json`:
+
+```bash
+# Quick command to get your config
+cd /path/to/claude-telegram-bridge
+./scripts/get-mcp-config.sh > ../your-project/.claude/mcp.json
+```
+
+Or manually copy the MCP config - see [SETUP-FOR-OTHER-PROJECTS.md](SETUP-FOR-OTHER-PROJECTS.md)

 ## Quick Start

@@ -89,6 +102,17 @@ pnpm daemon

 ### 5. Add MCP Server to Claude

+#### Option A: Auto-Generate Config (Easiest)
+
+```bash
+cd claude-telegram-bridge
+./scripts/get-mcp-config.sh
+```
+
+Copy the output to your MCP config file.
+
+#### Option B: Manual Setup
+
 Add to your Claude Code MCP settings (`~/.config/claude-code/settings/mcp.json`):

 ```json
@@ -107,15 +131,18 @@ Add to your Claude Code MCP settings (`~/.config/claude-code/settings/mcp.json`)
 }
 ```

-**Replace `/ABSOLUTE/PATH/TO/` with your actual path!**
-
-To find your absolute path:
+**Find your path:**
 ```bash
-cd claude-telegram-bridge
-pwd
-# Copy the output and use: <output>/dist/mcp-server.js
+cd claude-telegram-bridge && pwd
+# Use output: <result>/dist/mcp-server.js
 ```

+#### MCP Config Locations
+
+- **Global (all projects):** `~/.config/claude-code/settings/mcp.json`
+- **Per-project:** `your-project/.claude/mcp.json`
+- **VS Code:** `your-project/.vscode/mcp.json`
+
 ### 6. Available Tools

 Once configured, Claude can automatically use:
@@ -125,6 +152,13 @@ Once configured, Claude can automatically use:
 - `telegram_reply` - Reply to your messages
 - `telegram_check_health` - Check bridge status

+**View detailed tool info:**
+```bash
+pnpm tools
+# or
+node scripts/list-tools.js
+```
+
 ### 7. Test It

 Restart Claude Code, then tell Claude:
--- a/SETUP-FOR-OTHER-PROJECTS.md
+++ b/SETUP-FOR-OTHER-PROJECTS.md
@@ -0,0 +1,187 @@
+# Using Telegram Bridge in Other Claude Projects
+
+## Quick Setup (Recommended)
+
+### Option 1: Global Installation (Use Anywhere)
+
+Install once, use in any Claude project:
+
+```bash
+# Install globally
+cd /path/to/claude-telegram-bridge
+pnpm install
+pnpm build
+
+# Start the bridge (leave running)
+pnpm daemon
+```
+
+Then in **any project**, add to MCP config:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "node",
+      "args": ["/path/to/claude-telegram-bridge/dist/mcp-server.js"]
+    }
+  }
+}
+```
+
+### Option 2: Per-Project Installation
+
+Install as a dependency in your project:
+
+```bash
+# In your project directory
+cd your-project
+pnpm add github:RichardDillman/claude-telegram-bridge
+
+# The bridge needs to run separately
+cd node_modules/claude-telegram-bridge
+pnpm daemon
+```
+
+Add to your project's `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "node",
+      "args": ["./node_modules/claude-telegram-bridge/dist/mcp-server.js"]
+    }
+  }
+}
+```
+
+### Option 3: Environment Variable (Most Flexible)
+
+Set an environment variable once:
+
+```bash
+# Add to your ~/.bashrc or ~/.zshrc
+export TELEGRAM_BRIDGE_PATH="/path/to/claude-telegram-bridge"
+```
+
+Then in any project's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "node",
+      "args": ["$TELEGRAM_BRIDGE_PATH/dist/mcp-server.js"]
+    }
+  }
+}
+```
+
+## MCP Configuration Locations
+
+Depending on where you're using Claude:
+
+### Claude Code (CLI)
+Create `.claude/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "node",
+      "args": ["/absolute/path/to/claude-telegram-bridge/dist/mcp-server.js"],
+      "env": {
+        "TELEGRAM_BRIDGE_URL": "http://localhost:3456"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (Global)
+Edit `~/.config/claude-code/settings/mcp.json`
+
+### VS Code Extension
+Edit workspace `.vscode/mcp.json`
+
+## The Bridge Must Be Running!
+
+**Important:** The HTTP bridge must be running for the MCP server to work:
+
+```bash
+# Start once, use from all projects
+cd /path/to/claude-telegram-bridge
+pnpm daemon
+
+# Check it's running
+curl http://localhost:3456/health
+```
+
+## Available Tools in Any Project
+
+Once configured, Claude in **any project** can use:
+
+- `telegram_notify` - Send notifications
+- `telegram_ask` - Ask questions and wait for answers
+- `telegram_get_messages` - Check for messages
+- `telegram_reply` - Reply to messages
+- `telegram_check_health` - Verify bridge is working
+
+## Example: Using in Multiple Projects
+
+```
+~/projects/
+├── claude-telegram-bridge/     ← Install once
+│   └── pnpm daemon              ← Keep running
+│
+├── project-a/
+│   └── .claude/mcp.json         ← Points to bridge
+│
+├── project-b/
+│   └── .claude/mcp.json         ← Points to same bridge
+│
+└── project-c/
+    └── .claude/mcp.json         ← Points to same bridge
+```
+
+All three projects share the **same** Telegram bridge instance!
+
+## Testing the Setup
+
+In any project with the MCP configured, tell Claude:
+
+> "Send me a test notification via Telegram"
+
+Claude will automatically discover and use the `telegram_notify` tool.
+
+## Pro Tip: Project-Specific MCP Configs
+
+Create `.claude/mcp.json` in each project that needs Telegram:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "node",
+      "args": ["/Users/you/claude-telegram-bridge/dist/mcp-server.js"]
+    }
+  }
+}
+```
+
+Add `.claude/` to your `.gitignore` if you don't want to commit MCP configs.
+
+## Troubleshooting
+
+**"Telegram bridge not available"**
+- Is the bridge running? `curl http://localhost:3456/health`
+- Is the path correct in mcp.json? Use `pwd` to verify
+
+**"Tool not found"**
+- Restart Claude Code after adding MCP config
+- Check: `ls /path/to/claude-telegram-bridge/dist/mcp-server.js`
+
+**"Connection refused"**
+- Start the bridge: `pnpm daemon`
+- Verify: `pnpm logs`
--- a/package.json
+++ b/package.json
@@ -14,7 +14,9 @@
    "start": "node dist/index.js",
    "daemon": "pm2 start dist/index.js --name claude-telegram",
    "stop": "pm2 stop claude-telegram",
-    "logs": "pm2 logs claude-telegram"
+    "logs": "pm2 logs claude-telegram",
+    "tools": "node scripts/list-tools.js",
+    "config": "bash scripts/get-mcp-config.sh"
  },
  "keywords": [
    "telegram",
--- a/scripts/get-mcp-config.sh
+++ b/scripts/get-mcp-config.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+# Quick script to generate MCP config for this bridge
+
+BRIDGE_PATH=$(cd "$(dirname "$0")/.." && pwd)
+
+cat <<EOF
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "node",
+      "args": [
+        "$BRIDGE_PATH/dist/mcp-server.js"
+      ],
+      "env": {
+        "TELEGRAM_BRIDGE_URL": "http://localhost:3456"
+      }
+    }
+  }
+}
+EOF
--- a/scripts/list-tools.js
+++ b/scripts/list-tools.js
@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+// List all available MCP tools from the Telegram bridge
+
+const tools = [
+  {
+    name: 'telegram_notify',
+    description: 'Send a notification to the user via Telegram. Use this to keep the user informed about progress, completion, warnings, or errors.',
+    parameters: {
+      message: 'string (required) - The notification message to send. Supports Markdown formatting.',
+      priority: 'string (optional) - Priority level: info, success, warning, error, question. Default: info',
+    }
+  },
+  {
+    name: 'telegram_ask',
+    description: 'Ask the user a question via Telegram and wait for their answer. This blocks until the user responds.',
+    parameters: {
+      question: 'string (required) - The question to ask the user. Supports Markdown formatting.',
+      timeout: 'number (optional) - Timeout in milliseconds. Default: 300000 (5 minutes)',
+    }
+  },
+  {
+    name: 'telegram_get_messages',
+    description: 'Retrieve unread messages from the user. Use this to check if the user has sent any messages.',
+    parameters: {}
+  },
+  {
+    name: 'telegram_reply',
+    description: 'Send a reply to a user message via Telegram. Use after getting messages to respond to the user.',
+    parameters: {
+      message: 'string (required) - The reply message. Supports Markdown formatting.',
+    }
+  },
+  {
+    name: 'telegram_check_health',
+    description: 'Check the health and status of the Telegram bridge. Returns connection status, unread message count, and pending questions.',
+    parameters: {}
+  },
+];
+
+console.log('📡 Telegram Bridge MCP Tools\n');
+console.log('═'.repeat(60));
+
+tools.forEach((tool, i) => {
+  console.log(`\n${i + 1}. ${tool.name}`);
+  console.log('   ' + tool.description);
+
+  const paramKeys = Object.keys(tool.parameters);
+  if (paramKeys.length > 0) {
+    console.log('\n   Parameters:');
+    paramKeys.forEach(key => {
+      console.log(`   • ${key}: ${tool.parameters[key]}`);
+    });
+  } else {
+    console.log('\n   Parameters: none');
+  }
+  console.log('');
+});
+
+console.log('═'.repeat(60));
+console.log('\n💡 Usage: Claude automatically discovers these tools when');
+console.log('   the MCP server is configured in your project.\n');