docs: consolidate documentation structure
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 <noreply@anthropic.com>
This commit is contained in:
RichardDillman
269
CONTRIBUTING.md
Normal file
269
CONTRIBUTING.md
Normal file
@@ -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)
|
||||||
26
README.md
26
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
|
- 🚀 **Background Service** - Runs independently, always available
|
||||||
- 🔧 **MCP Protocol** - Works as a standard MCP server in any Claude project
|
- 🔧 **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
|
1. **Bridge runs** as a background service (connects to Telegram)
|
||||||
# Quick command to get your config
|
2. **MCP server** is auto-started by Claude when needed
|
||||||
cd /path/to/claude-telegram-bridge
|
3. **Claude discovers** 5 tools automatically
|
||||||
./scripts/get-mcp-config.sh > ../your-project/.claude/mcp.json
|
4. **You communicate** via Telegram in real-time
|
||||||
```
|
|
||||||
|
|
||||||
Or manually copy the MCP config - see [SETUP-FOR-OTHER-PROJECTS.md](SETUP-FOR-OTHER-PROJECTS.md)
|
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
@@ -479,6 +476,15 @@ HOST=localhost
|
|||||||
ENABLED=true
|
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
|
## Contact
|
||||||
|
|
||||||
rdillman@gmail.com
|
- **Issues:** https://github.com/RichardDillman/claude-telegram-bridge/issues
|
||||||
|
- **Email:** rdillman@gmail.com
|
||||||
|
|||||||
@@ -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`
|
|
||||||
Reference in New Issue
Block a user