电报代理MCP
一个简化的Telegram机器人，带有MCP（模型上下文协议），用于本地开发和调试。
此存储库实现了一个代理服务器，允许访问与MCP工具集成的LLM代理。
特性
- 🤖 LLM代理集成：由OpenAI GPT模型提供支持
- 🛠️ MCP工具：用于计算、日期/时间等的自定义工具
- 📱 电报机器人：易于使用的界面
- 🔧 地方发展：调试和测试的简单设置
- 🚀 远程MCP服务器：连接到外部MCP服务器
- 🧠 对话记忆：带有InMemorySaver的内置内存系统
发展
先决条件
- Python 3.12+
uv包管理器- OpenAI API密钥
- Telegram Bot令牌
- 外部MCP服务器
环境设置
- 创建
.env文件基于env.example:
cp env.example .env- 填写所需的环境变量：
# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-5-nano
# MCP Server Configuration
MCP_SERVER_URL=mcp_server_url
MCP_SERVER_TRANSPORT=streamable_http
# Path to JSON with multiple MCP servers
MCP_SERVERS_FILE_PATH=mcp-servers.json\[！重要\] 对于开发，您可以使用mysql为了STORAGE_DB因为它将所有数据保存在内存中。
MCP服务器JSON（带env扩展）
您可以在JSON文件中定义多个MCP服务器。加载器支持环境变量扩展，如 ${VAR} 或 $VAR 在任何字符串字段中。
示例 mcp-servers.json:
{
"mcpServers": {
"RemoteHTTP": {
"transport": "streamable_http",
"url": "${MCP_SERVER_URL}"
},
"LocalSSE": {
"transport": "sse",
"url": "http://localhost:${MCP_PORT}/sse"
}
}
}加载服务器时，代理将合并和扩展变量，然后通过连接 langchain_mcp_adapters.
安装
安装依赖项：
uv sync --dev运行Bot
用一个命令启动机器人：
uv run --env-file .env src/main.py代理将自动连接到您的MCP服务器 .env 或 mcp-servers.json.
用法
- 在Telegram中查找您的机器人
- 发送
/start命令 - 发送任何消息，机器人将使用LLM和可用工具进行处理
项目结构
src/agent.py-连接到外部MCP服务器的LangChain代理src/main.py-带有消息处理程序的Telegram机器人src/storage.py-数据库存储层src/user.py-用户管理src/envs.py-环境配置
配置
OpenAI设置
- 模型:
gpt-5-nano（默认）或任何其他OpenAI模型 - 温度:
1（可配置用于创意） - 流媒体:
False（为了提高可靠性）
MCP服务器连接
- 统一资源定位符:
MCP_SERVER_URL或通过mcp-servers.json - 运输：可通过配置
MCP_SERVER_TRANSPORT或JSON格式 - 服务器文件:
MCP_SERVERS_FILE_PATH（默认值：mcp-servers.json) - 自动重新连接：是的，有错误处理功能
内存管理
- 内存保护程序：用于对话历史的内置LangGraph存储系统
- 基于线程的隔离：每个用户都有单独的对话上下文
- 自动持久化：消息之间会自动维护对话历史记录
通信模式
我们支持两种与Telegram服务器通信的方式：
- 轮询，即当机器人不时地访问电报服务器并检查新消息或事件时
- 网络钩子，即当bot注册自己的url时，电报服务器应该在那里发送新的消息和事件
这 COMMUNICATION_MODE env变量处理它 轮询 是默认值。
Webhook 配置
首先设置 COMMUNICATION_MODE 向 webhook.
使用webhook需要设置SSL。
此命令生成 private.key 和 cert.pem SSL文件。
openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 3650 -out cert.pem（请求FQDN时使用域名/IP地址）
然后我们需要定义 SSL_KEY_PATH 和 SSL_CERT_PATH env in .env 生成的文件。
这 WEBHOOK_PORT 应设置为80、88、443或8443。
这 WEBHOOK_URL 需要有格式 https://:在这种情况下，URL中需要.Port。
远程MCP服务器设置
要连接到远程MCP服务器：
- 确保服务器可访问:
- 服务器应绑定到 0.0.0.0:8080 （不是 127.0.0.1:8080) - 防火墙中的端口8080应打开 - 服务器应支持 streamable_http 运输
- 在中配置
.env:
MCP_SERVER_URL=http://your-server-ip:8080/mcp/
MCP_SERVER_TRANSPORT=streamable_http- 测试连接性:
curl http://your-server-ip:8080/mcp/调试
测试
uv run pytest -vs棉毛
运行过梁：
uv run ruff check格式代码：
uv run ruff format检查MCP服务器状态
测试MCP服务器是否正在运行：
curl $MCP_SERVER_URL测试
运行测试：
uv run pytest运作原理
- 外部MCP服务器：FastMCP服务器使用自定义工具在外部运行
- 朗链代理：连接到外部MCP服务器并处理用户消息
- 电报机器人：处理用户交互并将消息转发给代理
- LLM集成：OpenAI GPT处理消息并决定使用哪些工具
- 存储器系统：InMemorySaver维护每个用户的对话历史记录
部署
Heroku
Heroku仅与webhook模式集成。
您只需在Heroku网站上设置以下envs：
COMMUNICATION_MODE=webhookWEBHOOK_URL=https://.herokuapp.com/（请注意，端口不应出现在url中，因为Heroku通过代理与应用程序通信）TELEGRAM_BOT_TOKEN
无需设置 WEBHOOK_PORT, SSL_KEY_PATH 和 SSL_CERT_PATH 因为Heroku在其代理端管理SSL。至于港口，他们通过 PORT 我们使用的env变量，而不是 WEBHOOK_PORT 与他们的方法相结合。
依赖项
关键依赖关系：
langchain>=0.2.0langchain-openai>=0.2.0langchain-mcp-adapters>=0.1.0langgraph>=0.6.4fastmcp>=0.1.0python-telegram-bot>=22.3
回复服务MCP（独立）
一个轻量级的独立MCP服务器，允许外部系统从您的Telegram机器人向特定用户触发消息。
环境
添加到您的 .env （或使用默认值）：
REPLY_SERVICE_MCP_HOST=0.0.0.0
REPLY_SERVICE_MCP_PORT=8091需要 TELEGRAM_BOT_TOKEN 待设定。
跑
uv run --env-file .env python mcp_servers/reply_service/main.pyMCP端点将在以下位置可用：
http://${REPLY_SERVICE_MCP_HOST}:${REPLY_SERVICE_MCP_PORT}/mcp/从代理使用（可选）
assets/mcp-servers.json 已包含回复服务条目：
{
"mcpServers": {
"SimpleMCPServer": {
"transport": "${MCP_SERVER_TRANSPORT}",
"url": "${MCP_SERVER_URL}"
},
"ReplyService": {
"transport": "streamable_http",
"url": "http://${REPLY_SERVICE_MCP_HOST}:${REPLY_SERVICE_MCP_PORT}/mcp/"
}
}
}当代理启动时，它将加载此服务器并将其工具暴露给LLM。