🤖 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调整间隔
⚠️ 重要说明
- 仅支持私聊：启动时会校验
chat.type === "private" - 安全提示：不要将
TELEGRAM_BOT_TOKEN提交到代码仓库 - ForceReply：默认启用，避免多 Agent 并发时消息混淆
🔄 GitHub Actions 自动发布
推送 v* 标签会自动触发 npm 发布：
git tag v0.3.0
git push origin v0.3.0需要在 GitHub Secrets 中配置 NPM_TOKEN。
📄 License
MIT
