MCP AgentChat - 让 AI Agent 通过 Telegram 与用户实时交互：发送消息、图片，等待用户回复
npm install mcp-agentchat
MCP AgentChat - 一个 Model Context Protocol (MCP) 服务，让 AI Agent 通过 Telegram 与用户实时交互：发送消息、图片，等待用户回复。
| 功能 | 描述 |
|------|------|
| 📝 发送消息 | 支持 HTML/MarkdownV2/Markdown 格式 |
| 🖼️ 发送图片 | 支持发送本地图片文件 |
| ⌨️ 快捷回复按钮 | Inline Keyboard 候选回复 |
| 📸 接收图片 | 用户回复的图片转 base64 返回 |
| 💓 心跳机制 | 进度通知避免客户端超时 |
| ⏱️ 超时策略 | 区分紧急/非紧急请求 |
``bash全局安装
npm install -g mcp-agentchat
🔧 配置
$3
| 变量 | 说明 |
|------|------|
|
| Bot Token（来自 @BotFather） |
| TELEGRAM_CHAT_ID | 目标聊天 ID（仅支持私聊） |$3
| 变量 | 默认值 | 说明 |
|------|--------|------|
|
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 工具
$3
通过 Telegram 向用户发送消息并等待回复。
#### 参数
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
|
summary | string | 否 | 发送给用户的消息内容 |
| images | string[] | 否 | 要发送的图片绝对路径列表 |
| quick_replies | object[] | 否 | 候选回复按钮列表 |
| emergency | boolean | 否 | 是否紧急（影响超时策略） |
| parse_mode | string | 否 | 消息格式（HTML/MarkdownV2/Markdown） |
| project_directory | string | 否 | 项目目录（显示在消息前缀） |#### 使用示例
基础用法：
`json
{
"summary": "代码已修改完成，请检查并反馈。"
}
`发送图片：
json
{
"summary": "这是生成的设计稿，请查看：",
"images": [
"/path/to/design.png",
"/path/to/mockup.jpg"
]
}
`带快捷回复按钮：
json
{
"summary": "请选择下一步操作：",
"quick_replies": [
{ "text": "✅ 继续" },
{ "text": "❌ 取消" },
{ "text": "🔄 重试", "callback_data": "retry" }
]
}
`完整示例：
json
{
"summary": "我完成了页面设计，请查看截图并选择：",
"images": ["/tmp/screenshot.png"],
"quick_replies": [
{ "text": "👍 很好，继续" },
{ "text": "✏️ 需要修改" }
],
"emergency": false,
"parse_mode": "HTML"
}
`$3
获取/等待最近一次提问的用户回复（用于处理外部超时中断）。
| 参数 | 类型 | 说明 |
|------|------|------|
|
| number | 指定提问消息 ID（可选） |
| emergency | boolean | 是否紧急 |📋 客户端配置示例
$3
`json
{
"mcpServers": {
"agentchat": {
"command": "npx",
"args": ["mcp-agentchat"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token",
"TELEGRAM_CHAT_ID": "your-chat-id"
}
}
}
}
`$3
json
{
"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"
}
}
}
}
`📝 消息格式说明
本项目将
原样发送，AI 可自由使用 Telegram 支持的富文本格式。$3
`html
粗体 斜体 代码
代码块
链接
`需要转义：
→ &、< → <、> → >$3
markdown
粗体 _斜体_ 代码
需要转义的字符：
> # + - = | { } . !为避免 MCP 客户端（如 Cursor）在等待用户回复时超时，本项目会定期发送 progress notification：
- 默认每 5 秒发送一次
- 支持 resetTimeoutOnProgress 的客户端会重置超时计时器
- 可通过 TELEGRAM_HEARTBEAT_INTERVAL_MS 调整间隔
1. 仅支持私聊：启动时会校验 chat.type === "private"
2. 安全提示：不要将 TELEGRAM_BOT_TOKEN 提交到代码仓库
3. ForceReply：默认启用，避免多 Agent 并发时消息混淆
推送 v* 标签会自动触发 npm 发布：
``bash`
git tag v0.3.0
git push origin v0.3.0
需要在 GitHub Secrets 中配置 NPM_TOKEN`。
MIT