AgentChat

npm version License: MIT

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