🤖 MCP AgentChat

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

✨ 特性

📦 安装

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

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

🔧 配置

必需环境变量

可选环境变量

🛠️ MCP 工具

telegram_chat

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

#### 参数

#### 使用示例

基础用法：

{
  "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

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

📋 客户端配置示例

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