From 0a0e23c810ca0a1433acd4f16e3a02afed9fdfba Mon Sep 17 00:00:00 2001 From: RichardDillman Date: Sun, 23 Nov 2025 01:11:16 -0500 Subject: [PATCH] docs: consolidate documentation structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Simplifies documentation by removing redundant multi-project setup guide and consolidating into: - README.md - User-facing installation and usage - CONTRIBUTING.md - Developer guide for local development Changes: - Removed SETUP-FOR-OTHER-PROJECTS.md (redundant) - Created CONTRIBUTING.md with development workflow - Simplified README "How It Works" section - Added proper Development and License sections to README - Improved contact information with issue tracker link The bridge works as a standard MCP server - no special multi-project setup needed. Just configure MCP and use the tools. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CONTRIBUTING.md | 269 ++++++++++++++++++++++++++++++++++++ README.md | 26 ++-- SETUP-FOR-OTHER-PROJECTS.md | 187 ------------------------- 3 files changed, 285 insertions(+), 197 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 SETUP-FOR-OTHER-PROJECTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e7523d0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,269 @@ +# Contributing to Claude Telegram Bridge + +Thanks for your interest in contributing! This guide covers local development setup. + +## Development Setup + +### Prerequisites + +- Node.js 18+ +- pnpm (`npm install -g pnpm`) +- Telegram account +- Git + +### Clone and Install + +```bash +git clone https://github.com/RichardDillman/claude-telegram-bridge.git +cd claude-telegram-bridge +pnpm install +``` + +### Environment Setup + +1. **Create a Telegram Bot:** + - Open Telegram, search for `@BotFather` + - Send `/newbot` and follow prompts + - Save your bot token + +2. **Configure Environment:** + ```bash + cp .env.example .env + ``` + + Edit `.env`: + ```env + TELEGRAM_BOT_TOKEN=your_token_here + TELEGRAM_CHAT_ID= # Leave empty + PORT=3456 + HOST=localhost + ENABLED=true + ``` + +3. **Initialize Bot:** + - Find your bot in Telegram + - Send `/start` + - Bot saves your chat ID automatically + +### Development Workflow + +```bash +# Build TypeScript +pnpm build + +# Run in development mode (auto-reload) +pnpm dev + +# Run MCP server directly (for testing) +pnpm mcp + +# View available tools +pnpm tools + +# Get MCP config for testing +pnpm config +``` + +### Project Structure + +``` +claude-telegram-bridge/ +├── src/ +│ ├── index.ts # HTTP bridge & Telegram bot +│ └── mcp-server.ts # MCP protocol implementation +├── scripts/ +│ ├── get-mcp-config.sh # Generate MCP config +│ └── list-tools.js # List available tools +├── dist/ # Built JavaScript (gitignored) +├── .env # Your secrets (gitignored) +├── .env.example # Environment template +├── package.json # Dependencies & scripts +└── tsconfig.json # TypeScript config +``` + +### Architecture + +**Two Components:** + +1. **HTTP Bridge** (`src/index.ts`) + - Runs as standalone service + - Communicates with Telegram Bot API + - Provides REST endpoints for notifications + - Manages message queue and bot commands + +2. **MCP Server** (`src/mcp-server.ts`) + - Implements MCP protocol via stdio + - Started by Claude when needed + - Translates MCP tool calls → HTTP requests + - Connects to bridge on `localhost:3456` + +**Flow:** +``` +Claude → MCP Server → HTTP Bridge → Telegram Bot → Your Phone + (stdio) (HTTP) (Bot API) +``` + +### Testing Locally + +#### Test HTTP Bridge + +```bash +# Start bridge +pnpm dev + +# In another terminal, test endpoints +curl http://localhost:3456/health + +curl -X POST http://localhost:3456/notify \ + -H "Content-Type: application/json" \ + -d '{"message": "Test!", "priority": "success"}' +``` + +#### Test MCP Server + +Create a test MCP config: +```bash +mkdir -p test-project/.claude +pnpm config > test-project/.claude/mcp.json +``` + +Start Claude in `test-project/` and try: +> "Send me a test notification via Telegram" + +### Making Changes + +#### Adding a New MCP Tool + +1. **Define tool in `src/mcp-server.ts`:** + ```typescript + const TOOLS: Tool[] = [ + // ... existing tools + { + name: 'telegram_new_feature', + description: 'Description of new feature', + inputSchema: { + type: 'object', + properties: { + param: { type: 'string', description: 'Parameter description' } + }, + required: ['param'] + } + } + ]; + ``` + +2. **Implement handler:** + ```typescript + case 'telegram_new_feature': { + const { param } = args as { param: string }; + // Implementation + return { + content: [{ type: 'text', text: 'Result' }] + }; + } + ``` + +3. **Add to `scripts/list-tools.js`** for documentation + +4. **Test it:** + ```bash + pnpm build + # Test with Claude or via MCP protocol + ``` + +#### Adding HTTP Endpoints + +Edit `src/index.ts`: +```typescript +app.post('/new-endpoint', async (req, res) => { + // Implementation +}); +``` + +### Code Style + +- Use TypeScript strict mode +- Follow existing patterns +- Add JSDoc comments for public APIs +- Keep functions focused and small + +### Commit Guidelines + +Use conventional commits: +- `feat:` - New features +- `fix:` - Bug fixes +- `docs:` - Documentation only +- `refactor:` - Code changes that neither fix bugs nor add features +- `test:` - Adding tests +- `chore:` - Maintenance tasks + +Example: +```bash +git commit -m "feat: add support for inline keyboards in notifications" +``` + +### Running in Production + +```bash +# Build +pnpm build + +# Start as daemon (requires pm2) +pnpm daemon + +# Check logs +pnpm logs + +# Stop +pnpm stop +``` + +### Debugging + +**Enable verbose logging:** +```typescript +// In src/index.ts +console.log('Debug:', message); +``` + +**Check bridge status:** +```bash +curl http://localhost:3456/health +``` + +**View bot logs:** +```bash +pnpm logs # If using daemon +# or check console if using pnpm dev +``` + +### Common Issues + +**"Bridge not responding"** +- Is it running? `curl http://localhost:3456/health` +- Check port 3456 isn't in use: `lsof -i :3456` + +**"MCP server not found"** +- Did you run `pnpm build`? +- Is the path in MCP config correct? + +**"Chat ID not set"** +- Send `/start` to your bot in Telegram +- Check `.env` - should have `TELEGRAM_CHAT_ID=123456789` + +## Pull Requests + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/amazing-feature` +3. Make your changes +4. Test thoroughly +5. Commit with conventional commits +6. Push and create a PR + +## Questions? + +Open an issue on GitHub or reach out via rdillman@gmail.com + +## License + +MIT - see [LICENSE](LICENSE) diff --git a/README.md b/README.md index fe3f550..560c4f7 100644 --- a/README.md +++ b/README.md @@ -28,17 +28,14 @@ After trying email, SMS, and Google Chat integrations, Telegram emerged as the b - 🚀 **Background Service** - Runs independently, always available - 🔧 **MCP Protocol** - Works as a standard MCP server in any Claude project -## Using in Other Projects +## How It Works -**Already have the bridge installed?** Just add this to your project's `.claude/mcp.json`: +This is a **standard MCP server** that works like any other MCP tool. Once installed and configured: -```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) +1. **Bridge runs** as a background service (connects to Telegram) +2. **MCP server** is auto-started by Claude when needed +3. **Claude discovers** 5 tools automatically +4. **You communicate** via Telegram in real-time ## Quick Start @@ -479,6 +476,15 @@ HOST=localhost ENABLED=true ``` +## Development + +Want to contribute or modify the bridge? See [CONTRIBUTING.md](CONTRIBUTING.md) for local development setup. + +## License + +MIT License - see [LICENSE](LICENSE) for details + ## Contact -rdillman@gmail.com +- **Issues:** https://github.com/RichardDillman/claude-telegram-bridge/issues +- **Email:** rdillman@gmail.com diff --git a/SETUP-FOR-OTHER-PROJECTS.md b/SETUP-FOR-OTHER-PROJECTS.md deleted file mode 100644 index 5ab15fc..0000000 --- a/SETUP-FOR-OTHER-PROJECTS.md +++ /dev/null @@ -1,187 +0,0 @@ -# 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`