mcp-telegram-claudecode 1.1.0 → 1.3.1

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.3.1] - 2026-02-04
+
+### Fixed
+- Added `pollingInProgress` lock to prevent race condition when multiple polls overlap
+- Fixed message duplication issue caused by concurrent polling
+- Added request timeouts (10s for messages, 30s for photos) to prevent hanging
+- Moved FormData import to top level for better performance
+
+### Changed
+- Updated `telegram_send_message` tool description to emphasize always responding via Telegram
+- Updated `telegram_start_polling` description to note auto-start behavior
+
+### Added
+- Auto-start polling when MCP server starts (if BOT_TOKEN and CHAT_ID are configured)
+
+## [1.3.0] - 2026-02-04
+
+### Added
+- `telegram_send_photo` tool for sending images
+- Proxy support via HTTP_PROXY/HTTPS_PROXY environment variables
+
+### Changed
+- Improved error handling in polling
+
+## [1.2.0] - 2026-02-03
+
+### Added
+- `telegram_start_polling` and `telegram_stop_polling` tools
+- Auto-injection of Telegram messages to terminal via SendKeys (Windows)
+
+## [1.1.0] - 2026-02-02
+
+### Added
+- `telegram_check_new` tool for quick message check
+
+### Changed
+- Improved message filtering by chat ID
+
+## [1.0.0] - 2026-02-01
+
+### Added
+- Initial release
+- `telegram_send_message` tool
+- `telegram_get_messages` tool
+- Basic Telegram Bot API integration
+- MCP server implementation using @modelcontextprotocol/sdk
+
+---
+
+## Known Issues
+
+- **Multiple Claude Code instances**: Running multiple Claude Code windows will cause message duplication as each instance runs its own MCP server
+- **SendKeys reliability**: Terminal injection depends on window focus and may fail occasionally
+- **No message persistence**: Failed injections result in lost messages
+
+## Planned Improvements
+
+- Lock file mechanism to prevent multiple instance conflicts
+- Retry logic for SendKeys injection
+- Failure notifications via Telegram
+- Message queue for failed injections

package/README.md

@@ -182,6 +182,93 @@ If you're in a region where Telegram is blocked:
 
 ---
 
+## How It Works
+
+### Architecture
+
+This MCP server acts as a bridge between Claude Code and Telegram:
+
+```
+┌─────────────┐     MCP Protocol      ┌─────────────────┐     Telegram API     ┌──────────┐
+│ Claude Code │ ◄──────────────────► │ MCP Server      │ ◄─────────────────► │ Telegram │
+│             │                       │ (this project)  │                      │          │
+└─────────────┘                       └─────────────────┘                      └──────────┘
+```
+
+### Auto-Polling & Terminal Injection (Experimental)
+
+When the MCP server starts, it automatically begins polling for new Telegram messages. When a message is received, it attempts to inject the text into the active terminal window using:
+
+1. **Clipboard**: Message is copied to system clipboard
+2. **SendKeys (Windows)**: PowerShell script simulates Ctrl+V and Enter keystrokes
+3. **Window Activation**: Attempts to find and activate terminal windows (Windows Terminal, cmd, PowerShell, VS Code)
+
+**This is an experimental feature** - it enables "remote control" of Claude Code via Telegram, but has reliability limitations.
+
+### Tools Available
+
+| Tool | Description |
+|------|-------------|
+| `telegram_send_message` | Send text to Telegram |
+| `telegram_get_messages` | Retrieve recent messages |
+| `telegram_check_new` | Quick check for new messages |
+| `telegram_send_photo` | Send images to Telegram |
+| `telegram_start_polling` | Manually start auto-polling |
+| `telegram_stop_polling` | Stop auto-polling |
+
+---
+
+## Known Issues & Limitations
+
+### ⚠️ Multiple Claude Code Instances
+
+**Problem**: If you run multiple Claude Code windows, each will start its own MCP server instance. All instances will poll the same Telegram bot, causing:
+- Duplicate message processing
+- Multiple injection attempts
+- Duplicate responses
+
+**Workaround**: Only run one Claude Code instance when using Telegram integration, or disable the Telegram MCP in additional instances.
+
+### ⚠️ SendKeys Reliability (Windows)
+
+The terminal injection feature depends on:
+- **Window focus**: Target terminal must be activatable
+- **Clipboard access**: System clipboard must be available
+- **Timing**: SendKeys requires precise timing
+
+**When it may fail**:
+- Another application has focus and won't release it
+- System is under heavy load
+- Remote desktop or virtual machine environments
+- Screen is locked
+
+**Workaround**: If injection fails, manually check Telegram messages using the `telegram_get_messages` tool.
+
+### ⚠️ Platform Support
+
+- **Windows**: Full support (auto-polling + SendKeys injection)
+- **macOS/Linux**: Partial support (tools work, but auto-injection not implemented)
+
+### ⚠️ Not Fully Unattended
+
+This MCP cannot wake up Claude Code on its own. The auto-injection only works when:
+- Claude Code is running and waiting for input
+- A terminal window is accessible
+
+For true unattended operation, consider using Claude Code's hook system instead.
+
+---
+
+## Planned Improvements
+
+- [ ] Lock file mechanism to prevent multiple instance conflicts
+- [ ] Retry logic for failed injections
+- [ ] Failure notifications via Telegram
+- [ ] Message queue for failed injections
+- [ ] macOS/Linux injection support
+
+---
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.

package/README_CN.md

@@ -182,6 +182,93 @@ claude /settings
 
 ---
 
+## 工作原理
+
+### 架构
+
+这个 MCP 服务器充当 Claude Code 和 Telegram 之间的桥梁：
+
+```
+┌─────────────┐     MCP 协议         ┌─────────────────┐     Telegram API     ┌──────────┐
+│ Claude Code │ ◄──────────────────► │ MCP 服务器      │ ◄─────────────────► │ Telegram │
+│             │                       │ (本项目)        │                      │          │
+└─────────────┘                       └─────────────────┘                      └──────────┘
+```
+
+### 自动轮询与终端注入（实验性功能）
+
+MCP 服务器启动时会自动开始轮询 Telegram 新消息。收到消息后，会尝试将文本注入到活动的终端窗口：
+
+1. **剪贴板**：消息被复制到系统剪贴板
+2. **SendKeys (Windows)**：PowerShell 脚本模拟 Ctrl+V 和 Enter 按键
+3. **窗口激活**：尝试查找并激活终端窗口（Windows Terminal、cmd、PowerShell、VS Code）
+
+**这是一个实验性功能** - 它可以实现通过 Telegram "远程控制" Claude Code，但存在可靠性限制。
+
+### 可用工具
+
+| 工具 | 说明 |
+|------|------|
+| `telegram_send_message` | 发送文字到 Telegram |
+| `telegram_get_messages` | 获取最近消息 |
+| `telegram_check_new` | 快速检查新消息 |
+| `telegram_send_photo` | 发送图片到 Telegram |
+| `telegram_start_polling` | 手动启动自动轮询 |
+| `telegram_stop_polling` | 停止自动轮询 |
+
+---
+
+## 已知问题与限制
+
+### ⚠️ 多个 Claude Code 实例
+
+**问题**：如果运行多个 Claude Code 窗口，每个都会启动自己的 MCP 服务器实例。所有实例都会轮询同一个 Telegram 机器人，导致：
+- 消息重复处理
+- 多次注入尝试
+- 重复回复
+
+**解决方法**：使用 Telegram 集成时只运行一个 Claude Code 实例，或在其他实例中禁用 Telegram MCP。
+
+### ⚠️ SendKeys 可靠性 (Windows)
+
+终端注入功能依赖于：
+- **窗口焦点**：目标终端必须可以被激活
+- **剪贴板访问**：系统剪贴板必须可用
+- **时序控制**：SendKeys 需要精确的时序
+
+**可能失败的情况**：
+- 其他应用程序占用焦点且不释放
+- 系统负载过高
+- 远程桌面或虚拟机环境
+- 屏幕被锁定
+
+**解决方法**：如果注入失败，可以手动使用 `telegram_get_messages` 工具检查消息。
+
+### ⚠️ 平台支持
+
+- **Windows**：完整支持（自动轮询 + SendKeys 注入）
+- **macOS/Linux**：部分支持（工具可用，但未实现自动注入）
+
+### ⚠️ 非完全无人值守
+
+这个 MCP 无法主动唤醒 Claude Code。自动注入只在以下情况下有效：
+- Claude Code 正在运行并等待输入
+- 终端窗口可以被访问
+
+如需真正的无人值守操作，请考虑使用 Claude Code 的 Hook 系统。
+
+---
+
+## 计划改进
+
+- [ ] 锁文件机制防止多实例冲突
+- [ ] 注入失败重试逻辑
+- [ ] 通过 Telegram 发送失败通知
+- [ ] 失败消息队列
+- [ ] macOS/Linux 注入支持
+
+---
+
 ## 许可证
 
 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

package/index.js

@@ -17,6 +17,7 @@ const { HttpsProxyAgent } = require('https-proxy-agent');
 const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const FormData = require('form-data');
 
 // Configuration from environment variables
 const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
@@ -41,6 +42,7 @@ let lastUpdateId = 0;
 // Polling state
 let pollingActive = false;
 let pollingInterval = null;
+let pollingInProgress = false;
 
 // Temp directory for injection scripts
 const tempDir = process.env.TEMP || process.env.TMP || '/tmp';
@@ -56,7 +58,7 @@ async function sendMessage(text) {
   const response = await axiosInstance.post(`${API_BASE}/sendMessage`, {
     chat_id: CHAT_ID,
     text: text
-  });
+  }, { timeout: 10000 });
 
   return response.data;
 }
@@ -69,8 +71,6 @@ async function sendPhoto(photoPath, caption = '') {
     throw new Error('TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be configured');
   }
 
-  const FormData = require('form-data');
-
   const form = new FormData();
   form.append('chat_id', CHAT_ID);
   form.append('photo', fs.createReadStream(photoPath));
@@ -79,7 +79,8 @@ async function sendPhoto(photoPath, caption = '') {
   }
 
   const response = await axiosInstance.post(`${API_BASE}/sendPhoto`, form, {
-    headers: form.getHeaders()
+    headers: form.getHeaders(),
+    timeout: 30000
   });
 
   return response.data;
@@ -98,7 +99,8 @@ async function getMessages(limit = 10) {
       offset: lastUpdateId + 1,
       limit: limit,
       timeout: 0
-    }
+    },
+    timeout: 10000
   });
 
   const messages = [];
@@ -206,8 +208,9 @@ foreach ($proc in $windows) {
  * Poll for messages and inject to terminal
  */
 async function pollAndInject() {
-  if (!pollingActive) return;
+  if (!pollingActive || pollingInProgress) return;
 
+  pollingInProgress = true;
   try {
     const response = await axiosInstance.get(`${API_BASE}/getUpdates`, {
       params: {
@@ -240,6 +243,8 @@ async function pollAndInject() {
     if (!error.message.includes('timeout') && !error.message.includes('ECONNRESET')) {
       console.error('Poll error:', error.message);
     }
+  } finally {
+    pollingInProgress = false;
   }
 }
 
@@ -278,7 +283,7 @@ function stopPolling() {
 const server = new Server(
   {
     name: 'telegram-claude-mcp',
-    version: '1.1.0',
+    version: '1.3.1',
   },
   {
     capabilities: {
@@ -293,7 +298,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: 'telegram_send_message',
-        description: 'Send a text message to the configured Telegram chat. Use this to communicate with the user via Telegram.',
+        description: 'Send a text message to the configured Telegram chat. IMPORTANT: You MUST use this tool to reply to the user regardless of whether they sent their message via terminal or Telegram. Always respond through Telegram so the user can see your replies on their phone.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -346,7 +351,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'telegram_start_polling',
-        description: 'Start auto-polling for Telegram messages. When enabled, new messages will be automatically injected into the terminal as user input. Call this at the start of a session to enable remote communication.',
+        description: 'Manually start auto-polling for Telegram messages (polling starts automatically on MCP load, so this is usually not needed). When enabled, new messages will be automatically injected into the terminal as user input.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -477,7 +482,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error('Telegram Claude MCP server running (v1.1.0 with polling support)');
+  console.error('Telegram Claude MCP server running (v1.3.1)');
+
+  // Auto-start polling when server starts
+  if (BOT_TOKEN && CHAT_ID) {
+    startPolling(2000);
+    console.error('Auto-polling started');
+  }
 }
 
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-telegram-claudecode",
-  "version": "1.1.0",
+  "version": "1.3.1",
   "description": "MCP server for Telegram integration with Claude Code - Send and receive messages via Telegram",
   "main": "index.js",
   "bin": {