diff --git a/.claude-mcp-template.json b/.claude-mcp-template.json new file mode 100644 index 0000000..5b0e1a6 --- /dev/null +++ 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" + } + } + } +} diff --git a/README.md b/README.md index a1338c9..fe3f550 100644 --- 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: /dist/mcp-server.js +cd claude-telegram-bridge && pwd +# Use output: /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: diff --git a/SETUP-FOR-OTHER-PROJECTS.md b/SETUP-FOR-OTHER-PROJECTS.md new file mode 100644 index 0000000..5ab15fc --- /dev/null +++ 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` diff --git a/package.json b/package.json index 655b271..11fa59c 100644 --- 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", diff --git a/scripts/get-mcp-config.sh b/scripts/get-mcp-config.sh new file mode 100755 index 0000000..4545c63 --- /dev/null +++ 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 < { + 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');