MCP Integration example with Telegram

使用 Telegram 的 MCP 集成示例

一个基于 Python 的 Model Context Protocol（MCP）客户端和服务端，可让大模型通过 Telegram 发送通知并接收用户回复。

功能

• 向 Telegram 聊天发送文本提醒，并可自定义紧急程度
• 使用可配置的超时时间检查用户回复
• 提供灵活的模板，可与兼容 MCP 的大模型应用集成

MCP 与函数调用或 Agent 工具的对比

MCP 协议（Model Context Protocol）：

• 将大模型的推理（“上下文”）与外部操作的执行分开。例如，大模型决定要采取什么操作，而 MCP 服务负责处理如何执行该操作。
• 这种解耦意味着你可以更新或替换外部工具，而无需更改大模型的核心模型或提示词。
• 这也使操作的执行更加安全、可控。

大模型函数调用或 Agent：

• 直接函数调用或基于 Agent 的方法通常会将决策逻辑与执行逻辑混在一起，导致系统的模块化程度降低。
• 操作执行方式的变更可能需要重新设计 Agent 或修改大模型的提示词，从而增加维护难度。

前置条件

• Python 3.11+
• Telegram 机器人令牌（从 @BotFather 获取）
• 你的 Telegram 聊天 ID

安装

1. 克隆代码库：

   git [email protected]:arananet/mcp-telegram-poc.git
   cd mcp-telegram-poc
   

2. 安装依赖：

   pip install -r requirements.txt
   

3. 创建虚拟环境：

   python3 -m venv .venv
   

4. 将 .env.example 复制为 .env，并填写你的 Telegram 凭据：

   cp .env.example .env
   nano .env
   

配置

在 .env 中编辑以下内容：

• TELEGRAM_BOT_TOKEN=your_bot_token_here
• TELEGRAM_CHAT_ID=your_chat_id_here
• OPENAI_API_KEY=your_openai_apikey

获取 Telegram 机器人令牌

1. 在 Telegram 上与 @BotFather 聊天。
2. 发送 /newbot 并提供一个名称（例如 mcp_example），然后再提供一个用户名（例如 mcp_example_bot）。之后，Telegram BotFather 会回复令牌。
3. 复制提供的令牌。

查找你的聊天 ID

1. 向你的机器人发送一条消息（找到创建的机器人并发送示例消息，例如 hi）。
2. 访问 https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates。
3. 找到 chat 对象的 id 字段。你会看到类似这样的内容（例如 "chat":{"id":107184517,"first_name":"Edu","last_name":"Arana"...)，聊天 ID 为 107184517。

用法

独立运行

python3 src/mcp_handler.py

以编程方式使用

测试发送和接收提醒：

python3 examples/test_client.py

Agent 集成

使用 autogen 0.4 框架中的 Agent 测试 MCP 集成

python3 examples/test_autogen_agent.py

本地测试

使用测试脚本（Linux/macOS）：

chmod +x test_server.sh
./test_server.sh

可用工具

send_alert

• 参数：
  • message（str，必填）：要发送的消息（支持 Markdown）。
  • project（str，必填）：项目名称。
  • urgency（str，可选）："low"、"medium"、"high"（默认值："medium"）。
• 描述：发送 Telegram 提醒并等待回复。

check_reply

• 参数：
  • message_id（int，必填）：要检查的消息 ID。
  • timeout_seconds（int，可选）：等待时间（默认值：60）。
• 描述：轮询特定消息的回复。

开发

• 安装依赖：pip install -r requirements.txt
• 运行服务端：python3 src/mcp_handler.py
• 测试客户端：python3 examples/test_client.py
• 测试 Agent：python3 examples/test_autogen_agent.py

示例

examples 文件夹包含：

• test_server.py：独立运行服务端。

• test_client.py：演示客户端交互。

• test_autogen_agent.py：演示 AutoGen Agent 之间的 MCP 集成

• 在 images 文件夹中，你可以找到一些测试截图。

开发者

• Eduardo Arana

可用性

• 经 MCPHub 认证 https://mcphub.com/mcp-servers/arananet/mcp-telegram-poc