mcp-telegram-poc

🚀 MCP 集成示例与 Telegram 的结合使用

本项目是一个基于 Python 的模型上下文协议（MCP）客户端和服务器，它让大语言模型（LLM）能够通过 Telegram 发送通知，还能接收用户的回复，为 LLM 与 Telegram 的交互提供了便利。

🚀 快速开始

本项目能让 LLM 借助 Telegram 实现通知发送与用户回复接收功能。以下是使用前的准备步骤和操作示例：

1. 完成安装与配置（具体步骤见“📦 安装指南”和“📚 详细文档 - 配置”）。
2. 运行服务器：

python3 -m mcp_server

3. 发送警报：

python3 -c "from mcp_client import send_alert; send_alert('这是一个测试警报！')"

✨ 主要特性

• 文本警报发送：可向 Telegram 聊天发送带有可自定义优先级级别的文本警报。
• 用户回复检查：能够检查用户回复，并可配置超时时间。
• 灵活集成模板：支持与 MCP 兼容的 LLM 应用程序集成。

📚 详细文档

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

MCP 协议（模型上下文协议）：

• 分离推理与执行：将 LLM 的推理（“上下文”）与其外部操作的执行分离。例如，LLM 决定要采取什么行动，而 MCP 服务器处理如何执行该操作。
• 便于工具更新：这种解耦意味着您可以更新或更换外部工具而不更改核心 LLM 模型或其提示。
• 安全受控执行：它还允许以更安全和受控的方式执行操作。

LLM 函数调用或代理：

• 逻辑混合问题：直接函数调用或基于代理的方法通常将决策制定与执行逻辑混合在一起，这可能会使系统模块化程度较低。
• 维护困难：变更操作执行方式可能需要重构代理或修改 LLM 的提示，从而使维护变得更加困难。

配置

编辑 .env 文件，填入以下内容：

• TELEGRAM_BOT_TOKEN= 您的机器人令牌
• TELEGRAM_CHAT_ID= 您的聊天 ID
• OPENAI_API_KEY= 您的 OpenAI API 密钥

获取 Telegram 机器人令牌

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

获取您的聊天 ID

1. 向您的机器人发送消息（前往创建的机器人页面，发送一条示例消息，例如 hi）。
2. 访问 https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates。
3. 查找 chat 对象的 id 字段。您会看到类似的内容（例如 "chat":{"id": "<您的聊天 ID>", ...}）。提取 <您的聊天 ID>。

开发信息

• 项目文档: MCP 与 Telegram 集成
• 问题反馈: 在 GitHub Issues 提交错误或建议。

📦 安装指南

1. 克隆仓库：

git git@github.com: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

💻 使用示例

基础用法

发送警报

from mcp_client import send_alert

send_alert("系统检测到异常情况，请注意！")

检查用户回复

from mcp_client import check_reply

# 假设 message_id 为 123
reply = check_reply(123, timeout=60)
print(reply)

🔧 技术细节

先决条件

• Python 3.11+ 版本
• Telegram 机器人令牌（来自 @BotFather）
• 您的 Telegram 聊天 ID

📄 许可证

本项目基于 MIT 许可证。