telegram-claude-mcp 1.0.0

package/bin/run.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const srcPath = join(__dirname, '..', 'src', 'index.ts');
+const tsxPath = join(__dirname, '..', 'node_modules', '.bin', 'tsx');
+
+const child = spawn(tsxPath, [srcPath], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "telegram-claude-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that lets Claude message you on Telegram",
+  "author": "Geravant",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Geravant/telegram-claude"
+  },
+  "keywords": [
+    "claude",
+    "telegram",
+    "mcp",
+    "claude-code",
+    "bot",
+    "messaging"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "telegram-claude-mcp": "./bin/run.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "start": "node --import tsx src/index.ts",
+    "dev": "node --watch --import tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "node-telegram-bot-api": "^0.66.0",
+    "openai": "^4.77.3",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@types/node-telegram-bot-api": "^0.64.7",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env bun
+
+/**
+ * Telegram Claude MCP Server
+ *
+ * A stdio-based MCP server that lets Claude message you on Telegram.
+ * Supports multiple Claude Code sessions with message tagging.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { TelegramManager } from './telegram.js';
+import { loadAppConfig, validateAppConfig } from './providers/index.js';
+
+async function main() {
+  // Load configuration
+  const config = loadAppConfig();
+
+  // Validate configuration
+  const errors = validateAppConfig(config);
+  if (errors.length > 0) {
+    console.error('Configuration errors:');
+    errors.forEach((e) => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+
+  // Create Telegram manager
+  const telegram = new TelegramManager({
+    botToken: config.telegramBotToken,
+    chatId: config.telegramChatId,
+    sessionName: config.sessionName,
+    responseTimeoutMs: config.responseTimeoutMs,
+  });
+
+  telegram.start();
+
+  // Track active chat sessions
+  let activeSessionId: string | null = null;
+
+  // Create stdio MCP server
+  const mcpServer = new Server(
+    { name: 'telegram-claude', version: '1.0.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  // List available tools
+  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'send_message',
+          description:
+            'Send a message to the user via Telegram and wait for their response. Use when you need user input, want to report completed work, or need discussion.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              message: {
+                type: 'string',
+                description: 'What you want to say to the user. Be clear and concise.',
+              },
+            },
+            required: ['message'],
+          },
+        },
+        {
+          name: 'continue_chat',
+          description: 'Continue an active chat with a follow-up message and wait for response.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              chat_id: { type: 'string', description: 'The chat ID from send_message' },
+              message: { type: 'string', description: 'Your follow-up message' },
+            },
+            required: ['chat_id', 'message'],
+          },
+        },
+        {
+          name: 'notify_user',
+          description:
+            'Send a notification to the user without waiting for a response. Use for status updates or acknowledgments.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              chat_id: { type: 'string', description: 'The chat ID from send_message' },
+              message: { type: 'string', description: 'The notification message' },
+            },
+            required: ['chat_id', 'message'],
+          },
+        },
+        {
+          name: 'end_chat',
+          description: 'End an active chat session with an optional closing message.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              chat_id: { type: 'string', description: 'The chat ID from send_message' },
+              message: {
+                type: 'string',
+                description: 'Optional closing message',
+              },
+            },
+            required: ['chat_id'],
+          },
+        },
+      ],
+    };
+  });
+
+  // Handle tool calls
+  mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+      if (request.params.name === 'send_message') {
+        const { message } = request.params.arguments as { message: string };
+        const result = await telegram.sendMessageAndWait(message);
+        activeSessionId = result.chatId;
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Message sent to Telegram.\n\nChat ID: ${result.chatId}\n\nUser's response:\n${result.response}\n\nUse continue_chat for follow-ups or end_chat to close the session.`,
+            },
+          ],
+        };
+      }
+
+      if (request.params.name === 'continue_chat') {
+        const { chat_id, message } = request.params.arguments as {
+          chat_id: string;
+          message: string;
+        };
+
+        // Validate chat_id matches active session
+        if (activeSessionId && chat_id !== activeSessionId) {
+          console.error(`Warning: chat_id mismatch. Expected ${activeSessionId}, got ${chat_id}`);
+        }
+
+        const response = await telegram.continueChat(message);
+
+        return {
+          content: [{ type: 'text', text: `User's response:\n${response}` }],
+        };
+      }
+
+      if (request.params.name === 'notify_user') {
+        const { message } = request.params.arguments as {
+          chat_id: string;
+          message: string;
+        };
+        await telegram.notify(message);
+
+        return {
+          content: [{ type: 'text', text: `Notification sent: "${message}"` }],
+        };
+      }
+
+      if (request.params.name === 'end_chat') {
+        const { chat_id, message } = request.params.arguments as {
+          chat_id: string;
+          message?: string;
+        };
+        await telegram.endChat(message);
+        activeSessionId = null;
+
+        return {
+          content: [{ type: 'text', text: 'Chat session ended.' }],
+        };
+      }
+
+      throw new Error(`Unknown tool: ${request.params.name}`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      return {
+        content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // Connect MCP server via stdio
+  const transport = new StdioServerTransport();
+  await mcpServer.connect(transport);
+
+  console.error('');
+  console.error('Telegram Claude MCP server ready');
+  console.error(`Session: ${config.sessionName}`);
+  console.error(`Chat ID: ${config.telegramChatId}`);
+  console.error('');
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.error('\nShutting down...');
+    telegram.stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/providers/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Provider Factory
+ *
+ * Creates and configures providers based on environment variables.
+ * Supports Telegram for messaging and OpenRouter for LLM.
+ */
+
+import { OpenRouterProvider } from './llm-openrouter.js';
+
+export { OpenRouterProvider } from './llm-openrouter.js';
+export type { OpenRouterConfig, ChatMessage, CompletionResult } from './llm-openrouter.js';
+
+export interface AppConfig {
+  // Telegram settings
+  telegramBotToken: string;
+  telegramChatId: number;
+
+  // Session settings
+  sessionName: string;
+  sessionPort: number;
+
+  // OpenRouter settings (optional)
+  openrouterApiKey?: string;
+  openrouterModel?: string;
+
+  // Chat settings
+  responseTimeoutMs: number;
+}
+
+export function loadAppConfig(): AppConfig {
+  const chatId = process.env.TELEGRAM_CHAT_ID;
+  const sessionPort = process.env.SESSION_PORT || '3333';
+
+  return {
+    telegramBotToken: process.env.TELEGRAM_BOT_TOKEN || '',
+    telegramChatId: chatId ? parseInt(chatId, 10) : 0,
+    sessionName: process.env.SESSION_NAME || 'default',
+    sessionPort: parseInt(sessionPort, 10),
+    openrouterApiKey: process.env.OPENROUTER_API_KEY,
+    openrouterModel: process.env.OPENROUTER_MODEL || 'openai/gpt-oss-120b',
+    responseTimeoutMs: parseInt(process.env.CHAT_RESPONSE_TIMEOUT_MS || '180000', 10),
+  };
+}
+
+export function validateAppConfig(config: AppConfig): string[] {
+  const errors: string[] = [];
+
+  if (!config.telegramBotToken) {
+    errors.push('Missing TELEGRAM_BOT_TOKEN (get from @BotFather)');
+  }
+  if (!config.telegramChatId) {
+    errors.push('Missing TELEGRAM_CHAT_ID (your Telegram user/chat ID)');
+  }
+  if (!config.sessionName) {
+    errors.push('Missing SESSION_NAME (unique identifier for this session)');
+  }
+
+  return errors;
+}
+
+export function createOpenRouterProvider(config: AppConfig): OpenRouterProvider | null {
+  if (!config.openrouterApiKey) {
+    return null;
+  }
+
+  const provider = new OpenRouterProvider();
+  provider.initialize({
+    apiKey: config.openrouterApiKey,
+    model: config.openrouterModel,
+  });
+
+  return provider;
+}

package/src/providers/llm-openrouter.ts

@@ -0,0 +1,129 @@
+/**
+ * OpenRouter LLM Provider
+ *
+ * Uses the OpenAI-compatible API provided by OpenRouter to access
+ * various LLM models including Claude, GPT-4, Gemini, etc.
+ */
+
+import OpenAI from 'openai';
+
+export interface OpenRouterConfig {
+  apiKey: string;
+  model?: string;
+  baseUrl?: string;
+}
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface CompletionResult {
+  content: string;
+  model: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export class OpenRouterProvider {
+  readonly name = 'openrouter';
+  private client: OpenAI | null = null;
+  private model: string = 'openai/gpt-oss-120b';
+
+  /**
+   * Initialize the OpenRouter client
+   */
+  initialize(config: OpenRouterConfig): void {
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseUrl || 'https://openrouter.ai/api/v1',
+      defaultHeaders: {
+        'HTTP-Referer': 'https://github.com/anthropics/claude-code',
+        'X-Title': 'Claude Code Telegram Bridge',
+      },
+    });
+
+    this.model = config.model || 'anthropic/claude-3.5-sonnet';
+  }
+
+  /**
+   * Check if the provider is initialized
+   */
+  isInitialized(): boolean {
+    return this.client !== null;
+  }
+
+  /**
+   * Generate a chat completion
+   */
+  async complete(messages: ChatMessage[]): Promise<CompletionResult> {
+    if (!this.client) {
+      throw new Error('OpenRouter provider not initialized');
+    }
+
+    const response = await this.client.chat.completions.create({
+      model: this.model,
+      messages: messages.map((m) => ({
+        role: m.role,
+        content: m.content,
+      })),
+    });
+
+    const choice = response.choices[0];
+    if (!choice || !choice.message.content) {
+      throw new Error('No response from OpenRouter');
+    }
+
+    return {
+      content: choice.message.content,
+      model: response.model,
+      usage: response.usage
+        ? {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          }
+        : undefined,
+    };
+  }
+
+  /**
+   * Simple text completion with optional system prompt
+   */
+  async simpleComplete(prompt: string, systemPrompt?: string): Promise<string> {
+    const messages: ChatMessage[] = [];
+
+    if (systemPrompt) {
+      messages.push({ role: 'system', content: systemPrompt });
+    }
+
+    messages.push({ role: 'user', content: prompt });
+
+    const result = await this.complete(messages);
+    return result.content;
+  }
+
+  /**
+   * Summarize text
+   */
+  async summarize(text: string, maxLength?: number): Promise<string> {
+    const systemPrompt = maxLength
+      ? `Summarize the following text in ${maxLength} characters or less. Be concise.`
+      : 'Summarize the following text concisely.';
+
+    return this.simpleComplete(text, systemPrompt);
+  }
+}
+
+// Singleton instance for optional use
+let instance: OpenRouterProvider | null = null;
+
+export function getOpenRouterProvider(): OpenRouterProvider {
+  if (!instance) {
+    instance = new OpenRouterProvider();
+  }
+  return instance;
+}

package/src/telegram.ts

@@ -0,0 +1,342 @@
+/**
+ * Telegram Bot Manager
+ *
+ * Handles Telegram messaging for Claude Code with multi-session support.
+ * Multiple Claude Code instances can share one Telegram chat, with messages
+ * tagged by session name and replies routed to the correct session.
+ */
+
+import TelegramBot from 'node-telegram-bot-api';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Session state file location
+const SESSION_DIR = '/tmp/telegram-claude-sessions';
+
+interface SessionState {
+  sessionName: string;
+  chatId: number;
+  messageIds: number[]; // Telegram message IDs sent by this session
+  waitingForResponse: boolean;
+  lastActivity: number;
+}
+
+interface PendingResponse {
+  resolve: (response: string) => void;
+  reject: (error: Error) => void;
+  messageId: number;
+  timestamp: number;
+}
+
+export interface TelegramConfig {
+  botToken: string;
+  chatId: number;
+  sessionName: string;
+  responseTimeoutMs?: number;
+}
+
+export class TelegramManager {
+  private bot: TelegramBot;
+  private config: TelegramConfig;
+  private pendingResponses: Map<string, PendingResponse> = new Map();
+  private sessionStateFile: string;
+  private isRunning = false;
+
+  constructor(config: TelegramConfig) {
+    this.config = {
+      responseTimeoutMs: 180000, // 3 minutes default
+      ...config,
+    };
+
+    this.bot = new TelegramBot(config.botToken, { polling: true });
+    this.sessionStateFile = path.join(SESSION_DIR, `${config.sessionName}.json`);
+
+    // Ensure session directory exists
+    if (!fs.existsSync(SESSION_DIR)) {
+      fs.mkdirSync(SESSION_DIR, { recursive: true });
+    }
+
+    this.setupMessageHandler();
+    this.updateSessionState({ waitingForResponse: false, messageIds: [] });
+  }
+
+  /**
+   * Start the bot (called after initialization)
+   */
+  start(): void {
+    this.isRunning = true;
+    console.error(`[${this.config.sessionName}] Telegram bot started`);
+  }
+
+  /**
+   * Stop the bot
+   */
+  stop(): void {
+    this.isRunning = false;
+    this.bot.stopPolling();
+    this.cleanupSessionState();
+    console.error(`[${this.config.sessionName}] Telegram bot stopped`);
+  }
+
+  /**
+   * Send a message and wait for user response
+   */
+  async sendMessageAndWait(message: string): Promise<{ chatId: string; response: string }> {
+    const taggedMessage = `[${this.config.sessionName}] ${message}`;
+
+    const sent = await this.bot.sendMessage(this.config.chatId, taggedMessage);
+    const messageId = sent.message_id;
+
+    // Update session state
+    this.updateSessionState({
+      waitingForResponse: true,
+      messageIds: [...this.getSessionState().messageIds, messageId],
+    });
+
+    // Wait for response
+    const response = await this.waitForResponse(messageId);
+
+    return {
+      chatId: `${this.config.sessionName}:${this.config.chatId}`,
+      response,
+    };
+  }
+
+  /**
+   * Continue a chat - send follow-up and wait for response
+   */
+  async continueChat(message: string): Promise<string> {
+    const taggedMessage = `[${this.config.sessionName}] ${message}`;
+
+    const sent = await this.bot.sendMessage(this.config.chatId, taggedMessage);
+    const messageId = sent.message_id;
+
+    // Update session state
+    this.updateSessionState({
+      waitingForResponse: true,
+      messageIds: [...this.getSessionState().messageIds, messageId],
+    });
+
+    return this.waitForResponse(messageId);
+  }
+
+  /**
+   * Send a notification without waiting for response
+   */
+  async notify(message: string): Promise<void> {
+    const taggedMessage = `[${this.config.sessionName}] ${message}`;
+    const sent = await this.bot.sendMessage(this.config.chatId, taggedMessage);
+
+    // Track the message but don't wait
+    this.updateSessionState({
+      messageIds: [...this.getSessionState().messageIds, sent.message_id],
+    });
+  }
+
+  /**
+   * End the chat session
+   */
+  async endChat(message?: string): Promise<void> {
+    if (message) {
+      const taggedMessage = `[${this.config.sessionName}] ${message}`;
+      await this.bot.sendMessage(this.config.chatId, taggedMessage);
+    }
+
+    // Clear pending responses
+    for (const [key, pending] of this.pendingResponses) {
+      pending.reject(new Error('Chat ended'));
+      this.pendingResponses.delete(key);
+    }
+
+    this.updateSessionState({ waitingForResponse: false, messageIds: [] });
+  }
+
+  /**
+   * Set up message handler for incoming messages
+   */
+  private setupMessageHandler(): void {
+    this.bot.on('message', (msg) => {
+      // Ignore messages not from our target chat
+      if (msg.chat.id !== this.config.chatId) {
+        return;
+      }
+
+      // Ignore our own messages
+      if (msg.from?.is_bot) {
+        return;
+      }
+
+      const text = msg.text || '';
+
+      // Check if this is a reply to one of our messages
+      if (msg.reply_to_message) {
+        const replyToId = msg.reply_to_message.message_id;
+        if (this.isOurMessage(replyToId)) {
+          this.resolveResponse(text);
+          return;
+        }
+      }
+
+      // Check if message is prefixed with our session name
+      const sessionPrefix = `@${this.config.sessionName}`;
+      if (text.toLowerCase().startsWith(sessionPrefix.toLowerCase())) {
+        const response = text.slice(sessionPrefix.length).trim();
+        this.resolveResponse(response);
+        return;
+      }
+
+      // Check if we're the most recent waiting session
+      if (this.isWaitingAndMostRecent()) {
+        this.resolveResponse(text);
+      }
+    });
+
+    this.bot.on('polling_error', (error) => {
+      console.error(`[${this.config.sessionName}] Telegram polling error:`, error.message);
+    });
+  }
+
+  /**
+   * Wait for a response with timeout
+   */
+  private waitForResponse(messageId: number): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const key = `${messageId}`;
+
+      // Set timeout
+      const timeout = setTimeout(() => {
+        this.pendingResponses.delete(key);
+        this.updateSessionState({ waitingForResponse: false });
+        reject(new Error(`Response timeout after ${this.config.responseTimeoutMs}ms`));
+      }, this.config.responseTimeoutMs);
+
+      this.pendingResponses.set(key, {
+        resolve: (response: string) => {
+          clearTimeout(timeout);
+          this.pendingResponses.delete(key);
+          this.updateSessionState({ waitingForResponse: false });
+          resolve(response);
+        },
+        reject: (error: Error) => {
+          clearTimeout(timeout);
+          this.pendingResponses.delete(key);
+          reject(error);
+        },
+        messageId,
+        timestamp: Date.now(),
+      });
+    });
+  }
+
+  /**
+   * Resolve a pending response
+   */
+  private resolveResponse(text: string): void {
+    // Get the most recent pending response
+    let mostRecent: PendingResponse | null = null;
+    let mostRecentKey: string | null = null;
+
+    for (const [key, pending] of this.pendingResponses) {
+      if (!mostRecent || pending.timestamp > mostRecent.timestamp) {
+        mostRecent = pending;
+        mostRecentKey = key;
+      }
+    }
+
+    if (mostRecent && mostRecentKey) {
+      mostRecent.resolve(text);
+    }
+  }
+
+  /**
+   * Check if a message ID belongs to this session
+   */
+  private isOurMessage(messageId: number): boolean {
+    const state = this.getSessionState();
+    return state.messageIds.includes(messageId);
+  }
+
+  /**
+   * Check if this session is waiting and is the most recently active waiting session
+   */
+  private isWaitingAndMostRecent(): boolean {
+    const ourState = this.getSessionState();
+    if (!ourState.waitingForResponse) {
+      return false;
+    }
+
+    // Check all other sessions
+    const sessionFiles = fs.readdirSync(SESSION_DIR).filter((f) => f.endsWith('.json'));
+
+    for (const file of sessionFiles) {
+      if (file === `${this.config.sessionName}.json`) continue;
+
+      try {
+        const otherState = JSON.parse(
+          fs.readFileSync(path.join(SESSION_DIR, file), 'utf-8')
+        ) as SessionState;
+
+        // If another session is waiting and more recent, we're not the target
+        if (otherState.waitingForResponse && otherState.lastActivity > ourState.lastActivity) {
+          return false;
+        }
+      } catch {
+        // Ignore invalid files
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get current session state from file
+   */
+  private getSessionState(): SessionState {
+    try {
+      if (fs.existsSync(this.sessionStateFile)) {
+        return JSON.parse(fs.readFileSync(this.sessionStateFile, 'utf-8'));
+      }
+    } catch {
+      // Return default state on error
+    }
+
+    return {
+      sessionName: this.config.sessionName,
+      chatId: this.config.chatId,
+      messageIds: [],
+      waitingForResponse: false,
+      lastActivity: Date.now(),
+    };
+  }
+
+  /**
+   * Update session state file
+   */
+  private updateSessionState(updates: Partial<SessionState>): void {
+    const current = this.getSessionState();
+    const updated: SessionState = {
+      ...current,
+      ...updates,
+      lastActivity: Date.now(),
+    };
+
+    try {
+      fs.writeFileSync(this.sessionStateFile, JSON.stringify(updated, null, 2));
+    } catch (error) {
+      console.error(`[${this.config.sessionName}] Failed to update session state:`, error);
+    }
+  }
+
+  /**
+   * Clean up session state file on shutdown
+   */
+  private cleanupSessionState(): void {
+    try {
+      if (fs.existsSync(this.sessionStateFile)) {
+        fs.unlinkSync(this.sessionStateFile);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}