电报代理MCP
一个简化的Telegram机器人,带有MCP(模型上下文协议),用于本地开发和调试。
此存储库实现了一个代理服务器,允许访问与MCP工具集成的LLM代理。
特性
- 🤖 LLM代理集成:由OpenAI GPT模型提供支持
- 🛠️ MCP工具:用于计算、日期/时间等的自定义工具
- 📱 电报机器人:易于使用的界面
- 🔧 地方发展:调试和测试的简单设置
- 🚀 远程MCP服务器:连接到外部MCP服务器
- 🧠 对话记忆:带有InMemorySaver的内置内存系统
发展
先决条件
- Python 3.12+
uv包管理器- OpenAI API密钥
- Telegram Bot令牌
- 外部MCP服务器
环境设置
- 创建
.env文件基于env.example:```bash
cp env.example .env
2. 填写所需的环境变量:```bash
# 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:```json
{
"mcpServers": {
"RemoteHTTP": {
"transport": "streamable_http",
"url": "${MCP_SERVER_URL}"
},
"LocalSSE": {
"transport": "sse",
"url": "http://localhost:${MCP_PORT}/sse"
}
}
}
加载服务器时,代理将合并和扩展变量,然后通过连接 `langchain_mcp_adapters`.
### 安装
安装依赖项:```bash
uv sync --dev
运行Bot
用一个命令启动机器人:```bash
uv run --env-file .env src/main.py
代理将自动连接到您的MCP服务器 `.env` 或 `mcp-servers.json`.
## 用法
1. 在Telegram中查找您的机器人
1. 发送 `/start` 命令
1. 发送任何消息,机器人将使用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文件。```bash
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:```bash
MCP_SERVER_URL=http://your-server-ip:8080/mcp/
MCP_SERVER_TRANSPORT=streamable_http
3. **测试连接性**:```bash
curl http://your-server-ip:8080/mcp/
调试
测试```bash
uv run pytest -vs
### 棉毛
运行过梁:```bash
uv run ruff check
格式代码:```bash
uv run ruff format
### 检查MCP服务器状态
测试MCP服务器是否正在运行:```bash
curl $MCP_SERVER_URL
测试
运行测试:```bash
uv run pytest
## 运作原理
1. **外部MCP服务器**:FastMCP服务器使用自定义工具在外部运行
1. **朗链代理**:连接到外部MCP服务器并处理用户消息
1. **电报机器人**:处理用户交互并将消息转发给代理
1. **LLM集成**:OpenAI GPT处理消息并决定使用哪些工具
1. **存储器系统**:InMemorySaver维护每个用户的对话历史记录
## 部署
### Heroku
Heroku仅与webhook模式集成。
您只需在Heroku网站上设置以下envs:
- `COMMUNICATION_MODE=webhook`
- `WEBHOOK_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.0`
- `langchain-openai>=0.2.0`
- `langchain-mcp-adapters>=0.1.0`
- `langgraph>=0.6.4`
- `fastmcp>=0.1.0`
- `python-telegram-bot>=22.3`
## 回复服务MCP(独立)
一个轻量级的独立MCP服务器,允许外部系统从您的Telegram机器人向特定用户触发消息。
### 环境
添加到您的 `.env` (或使用默认值):```bash
REPLY_SERVICE_MCP_HOST=0.0.0.0
REPLY_SERVICE_MCP_PORT=8091
需要 TELEGRAM_BOT_TOKEN 待设定。
跑```bash
uv run --env-file .env python mcp_servers/reply_service/main.py
MCP端点将在以下位置可用:```text
http://${REPLY_SERVICE_MCP_HOST}:${REPLY_SERVICE_MCP_PORT}/mcp/
从代理使用(可选)
assets/mcp-servers.json 已包含回复服务条目: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。
