🤖 MCP AgentChat

MCP AgentChat - 一个 Model Context Protocol (MCP) 服务，让 AI Agent 通过 Telegram 与用户实时交互：发送消息、图片，等待用户回复。

✨ 特性

| 功能 | 描述 | |------|------| | 📝 发送消息 | 支持 HTML/MarkdownV2/Markdown 格式 | | 🖼️ 发送图片 | 支持发送本地图片文件 | | ⌨️ 快捷回复按钮 | Inline Keyboard 候选回复 | | 📸 接收图片 | 用户回复的图片转 base64 返回 | | 💓 心跳机制 | 进度通知避免客户端超时 | | ⏱️ 超时策略 | 区分紧急/非紧急请求 |

📦 安装

# 全局安装
npm install -g mcp-agentchat

# 或者本地安装
npm install mcp-agentchat

🔧 配置

必需环境变量

| 变量 | 说明 | |------|------| | TELEGRAM_BOT_TOKEN | Bot Token（来自 @BotFather） | | TELEGRAM_CHAT_ID | 目标聊天 ID（仅支持私聊） |

可选环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | TELEGRAM_POLL_INTERVAL_MS | 2000 | 轮询间隔（毫秒） | | TELEGRAM_GETUPDATES_TIMEOUT_SECONDS | 25 | getUpdates 长轮询秒数 | | TELEGRAM_EMERGENCY_TIMEOUT_SECONDS | 6048000 | 紧急请求超时（秒） | | TELEGRAM_NON_EMERGENCY_TIMEOUT_SECONDS | 180 | 非紧急请求超时（秒） | | TELEGRAM_NON_EMERGENCY_TIMEOUT_TEXT | "用户暂时未回复..." | 非紧急超时返回文本 | | TELEGRAM_HEARTBEAT_INTERVAL_MS | 5000 | 心跳间隔（毫秒） | | TELEGRAM_PARSE_MODE | HTML | 默认消息格式 | | TELEGRAM_FORCE_REPLY | true | 启用强制回复 | | TELEGRAM_INCLUDE_IMAGES | true | 接收图片转 base64 | | TELEGRAM_MAX_IMAGES | 8 | 最多返回图片数 | | TELEGRAM_READ_RECEIPT_ENABLED | true | 发送已读回执 | | TELEGRAM_READ_RECEIPT_TEXT | 已收到 | 回执文本 | | TELEGRAM_READ_RECEIPT_SILENT | true | 静默发送回执 |

🛠️ MCP 工具

telegram_chat

通过 Telegram 向用户发送消息并等待回复。

参数

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | summary | string | 否 | 发送给用户的消息内容 | | images | string[] | 否 | 要发送的图片绝对路径列表 | | quick_replies | object[] | 否 | 候选回复按钮列表 | | emergency | boolean | 否 | 是否紧急（影响超时策略） | | parse_mode | string | 否 | 消息格式（HTML/MarkdownV2/Markdown） | | project_directory | string | 否 | 项目目录（显示在消息前缀） |

使用示例

基础用法：

{
  "summary": "代码已修改完成，请检查并反馈。"
}

发送图片：

{
  "summary": "这是生成的设计稿，请查看：",
  "images": [
    "/path/to/design.png",
    "/path/to/mockup.jpg"
  ]
}

带快捷回复按钮：

{
  "summary": "请选择下一步操作：",
  "quick_replies": [
    { "text": "✅ 继续" },
    { "text": "❌ 取消" },
    { "text": "🔄 重试", "callback_data": "retry" }
  ]
}

完整示例：

{
  "summary": "我完成了页面设计，请查看截图并选择：",
  "images": ["/tmp/screenshot.png"],
  "quick_replies": [
    { "text": "👍 很好，继续" },
    { "text": "✏️ 需要修改" }
  ],
  "emergency": false,
  "parse_mode": "HTML"
}

get_last_feedback_response

获取/等待最近一次提问的用户回复（用于处理外部超时中断）。

| 参数 | 类型 | 说明 | |------|------|------| | message_id | number | 指定提问消息 ID（可选） | | emergency | boolean | 是否紧急 |

📋 客户端配置示例

Cursor / Claude Desktop

{
  "mcpServers": {
    "agentchat": {
      "command": "npx",
      "args": ["mcp-agentchat"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

本地开发

{
  "mcpServers": {
    "agentchat": {
      "command": "node",
      "args": ["/path/to/mcp-agentchat/build/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_CHAT_ID": "your-chat-id",
        "TELEGRAM_HEARTBEAT_INTERVAL_MS": "5000"
      }
    }
  }
}

📝 消息格式说明

本项目将 summary 原样发送，AI 可自由使用 Telegram 支持的富文本格式。

HTML（推荐）

<b>粗体</b> <i>斜体</i> <code>代码</code>
<pre>代码块</pre>
<a href="https://example.com">链接</a>

需要转义：& → &、< → <、> → >

MarkdownV2

*粗体* _斜体_ `代码`

需要转义的字符：_ * [ ] ( ) ~ \ > # + - = | { } . !`

💓 心跳机制

为避免 MCP 客户端（如 Cursor）在等待用户回复时超时，本项目会定期发送 progress notification：

• 默认每 5 秒发送一次
• 支持 resetTimeoutOnProgress 的客户端会重置超时计时器
• 可通过 TELEGRAM_HEARTBEAT_INTERVAL_MS 调整间隔

⚠️ 重要说明

1. 仅支持私聊：启动时会校验 chat.type === "private"
2. 安全提示：不要将 TELEGRAM_BOT_TOKEN 提交到代码仓库
3. ForceReply：默认启用，避免多 Agent 并发时消息混淆

🔄 GitHub Actions 自动发布

推送 v* 标签会自动触发 npm 发布：

git tag v0.3.0
git push origin v0.3.0

需要在 GitHub Secrets 中配置 NPM_TOKEN。

📄 License

MIT