EasyPomodoro项目顾问
使用MCP（模型上下文协议）服务器为EasyPomodoro Android项目提供咨询的人工智能系统。
项目概述
该系统提供：
- 电报机器人 -项目问题的交互式聊天（文本+语音）
- REST API -后端与MCP集成，用于AI驱动的响应
- PR代码审查 -通过API自动审核拉取请求
- 语音输入 -通过Telegram发送语音信息（俄语、gpt音频迷你版）
- 用户个性化 -可定制的用户配置文件，用于定制响应
- 本地开发 -在本地运行服务器进行调试
- 通过GitHub Copilot MCP浏览和分析项目代码
- 使用RAG（检索增强生成）搜索项目文档
建筑
┌─────────────────┐ ┌─────────────────┐
│ Telegram User │ │ GitHub Actions │
└────────┬────────┘ └────────┬────────┘
│ │
↓ ↓
┌─────────────────────────────────────────────────────────────┐
│ Telegram Bot Client │
│ (client/) │
│ - Handles /start command │
│ - Forwards messages to backend │
│ - Shows "Думаю..." indicator │
└─────────────────────────┬───────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ Backend Server (server/) │
│ FastAPI + MCP │
│ │
│ Endpoints: │
│ ├─ POST /api/chat - General chat with AI │
│ ├─ POST /api/chat-voice - Voice input (gpt-audio-mini) │
│ ├─ POST /api/review-pr - AI code review for PRs │
│ ├─ GET /api/profile/:id - Get user profile │
│ └─ GET /health - Health check │
│ │
│ Components: │
│ ├─ chat_service.py - Message processing + tool loops │
│ ├─ audio_service.py - Voice message processing │
│ ├─ mcp_manager.py - MCP server connections │
│ ├─ openrouter_client.py - LLM API + audio models │
│ ├─ profile_manager.py - User personalization │
│ └─ prompts.py - System prompts │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────────┴───────────────┐
↓ ↓
┌──────────────────────┐ ┌──────────────────────┐
│ GitHub Copilot MCP │ │ RAG Specs MCP │
│ (HTTP Transport) │ │ (Python/stdio) │
│ │ │ │
│ URL: │ │ Tools: │
│ api.githubcopilot. │ │ - rag_query │
│ com/mcp/ │ │ - list_specs │
│ │ │ - get_spec_content │
│ Tools: │ │ - rebuild_index │
│ - get_file_contents │ │ - get_project_ │
│ - list_commits │ │ structure │
│ - get_commit │ │ │
│ - list_issues │ │ Uses: │
│ - issue_read │ │ - GitHub API │
│ - list_pull_requests │ │ - OpenRouter │
│ - pull_request_read │ │ Embeddings │
└──────────────────────┘ └──────────────────────┘API终点
POST/api/聊天
项目问题的通用聊天端点。
请求：
{
"user_id": "string",
"message": "string"
}答复：
{
"response": "string",
"tool_calls_count": 0,
"mcp_used": false
}POST/api/审核公关
基于AI的代码审查，用于拉取请求。
请求：
{
"pr_number": 123
}答复：
{
"review": "## Summary\n...",
"tool_calls_count": 5
}审查包括：
- 文件合规性检查（通过RAG）
- 架构和设计模式审查
- Kotlin/Android最佳实践
- 安全分析
- 性能考虑
- 使用行号逐个文件查找结果
- 裁决：批准/请求_变更/评论
POST/api/聊天语音
使用gpt音频mini处理语音信息。
请求：
POST /api/chat-voice
Content-Type: multipart/form-data
user_id: string
audio: file (.oga, .mp3, .wav)答复：
{
"transcription": null,
"response": "AI model response",
"latency_ms": 1653,
"audio_tokens": 153,
"cost_usd": 0.000092
}特征：
- 型号：
openai/gpt-audio-mini通过OpenRouter - 语言：俄语（可配置）
- 最长持续时间：60秒
- 最大文件大小：10 MB
- 通过ffmpeg进行音频转换
- 无需单独转录（模型直接处理音频）
GET/健康
健康检查端点。
答复：
{
"status": "healthy",
"mcp_connected": true,
"tools_count": 11
}GitHub操作集成
在CI/CD管道中使用PR审查端点：
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- name: Request AI Review
id: review
run: |
RESPONSE=$(curl -s -X POST "${{ secrets.MCP_SERVER_URL }}/api/review-pr" \
-H "X-API-Key: ${{ secrets.MCP_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{"pr_number": ${{ github.event.pull_request.number }}}')
echo "$RESPONSE" | jq -r '.review' > review.md
- name: Post Review Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = fs.readFileSync('review.md', 'utf8');
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: '## AI Code Review\n\n' + review
});所需机密：
MCP_SERVER_URL-后端服务器URL（例如。，https://your-server.railway.app)MCP_API_KEY-用于身份验证的API密钥
系统组件
1.后端服务器（服务器/）
文件夹：
main.py-FastAPI应用程序入口点app.py-API路由和终结点chat_service.py-使用MCP工具集成进行消息处理audio_service.py-语音信息处理mcp_manager.py-MCP服务器连接管理mcp_http_transport.py-GitHub Copilot MCP的HTTP传输openrouter_client.py-OpenRouter LLM+音频API集成prompts.py-不同任务的系统提示schemas.py-API的Pydantic模型conversation.py-每个用户的对话历史记录profile_manager.py-用户配置文件管理profile_storage.py-配置文件的JSON存储auth.py-API密钥验证config.py-配置和环境变量logger.py-日志记录配置Dockerfile-使用ffmpeg进行Docker配置
2.电报机器人客户端（客户端/）
文件夹：
main.py-应用程序入口点bot.py-电报机器人处理程序backend_client.py-后端API的HTTP客户端config.py-Bot配置logger.py-日志记录配置
3.RAG MCP服务器（服务器/MCP_RAG/）
文件夹：
server.py-配备RAG工具的MCP服务器github_fetcher.py-用于/specs文件夹的GitHub API客户端rag_engine.py-OpenRouter嵌入的矢量搜索
4.MCP服务器
GitHub Copilot MCP（HTTP）
网址： https://api.githubcopilot.com/mcp/
运输： HTTP（可流式HTTP传输，MCP规范2025-03-26）
基本工具：
get_file_contents-从存储库读取文件内容list_commits/get_commit-查看提交历史记录list_issues/issue_read-处理问题list_pull_requests/pull_request_read-与PR合作
身份验证： GitHub个人访问令牌（PAT）
RAG规范MCP（Python/stdio）
工具：
rag_query-搜索具有语义相似性的文档list_specs-列出可用的规范文件get_spec_content-获取规范文件的完整内容rebuild_index-重建RAG索引get_project_structure-获取目录树
目标存储库： LebedAlIv2601/EasyPomodoro
安装
先决条件
- Python 3.12+（推荐3.14）
- OpenRouter API密钥
- GitHub个人访问令牌
- Telegram机器人令牌（用于客户端）
- ffmpeg（用于语音消息处理）
服务器安装程序
- 克隆存储库：
git clone
cd McpSystem- 创建虚拟环境：
python3.14 -m venv venv
source venv/bin/activate- 安装依赖项：
pip install -r requirements.txt- 配置环境：
cd server
cp .env.example .env
# Edit .env:
# BACKEND_API_KEY=your_secure_api_key
# OPENROUTER_API_KEY=your_openrouter_key
# GITHUB_TOKEN=your_github_pat- 运行服务器：
python main.py客户端设置
- 配置环境：
cd client
cp .env.example .env
# Edit .env:
# TELEGRAM_BOT_TOKEN=your_bot_token
# BACKEND_URL=http://localhost:8000
# BACKEND_API_KEY=same_as_server- 运行客户端：
python main.pyGitHub PAT范围
使用以下范围创建经典PAT：
repo-完全访问存储库read:org-读取组织数据（可选）read:user-读取用户数据
配置
服务器环境变量
| 变量 | 描述 |
|---|---|
BACKEND_API_KEY | 用于身份验证的API密钥 |
OPENROUTER_API_KEY | OpenRouter API密钥 |
GITHUB_TOKEN | GitHub个人访问令牌 |
OPENROUTER_MODEL | LLM模型（默认值： deepseek/deepseek-v3.2) |
PORT | 服务器端口（默认值： 8000) |
HOST | 服务器主机（默认值： 0.0.0.0) |
客户端环境变量
| 变量 | 描述 |
|---|---|
TELEGRAM_BOT_TOKEN | Telegram机器人令牌 |
BACKEND_URL | 后端服务器URL |
BACKEND_API_KEY | 后端的API密钥 |
技术栈
- Python 3.14 -主要语言
- 快速API -后端API框架
- python电报机器人 -电报集成
- MCP-SDK -模型上下文协议（HTTP+stdio传输）
- HTTPX -异步HTTP客户端
- 开放路由 -LLM API访问
- 派丹蒂克 -数据验证
部署
本地开发（建议测试）
有关详细说明，请参阅 LOCAL_SETUP.md
快速启动：
# Terminal 1: Backend Server
cd server
source ../venv/bin/activate
python main.py
# Terminal 2: Telegram Bot
cd client
source ../venv/bin/activate
python main.py本地运行的先决条件：
- 已安装ffmpeg：
brew install ffmpeg（macOS） - 在中配置的环境变量
server/.env - 在中为本地服务器配置了客户端
client/.env:
- BACKEND_URL=http://localhost:8000
优势：
- 代码更改的即时反馈
- 完全访问日志和调试
- 没有云部署延迟
- 脱机工作（API调用除外）
铁路部署
该服务器专为铁路部署而设计：
- 将存储库连接到铁路
- 在铁路仪表板中设置环境变量
- 将根目录设置为
server - 推送时自动部署
所需铁路变量：
BACKEND_API_KEYOPENROUTER_API_KEYGITHUB_TOKEN
注： Dockerfile包含用于语音处理的ffmpeg。
手动测试
# Local server
curl http://localhost:8000/health
# Railway server
curl https://your-server.railway.app/health
# Chat
curl -X POST "http://localhost:8000/api/chat" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "test", "message": "What is the project structure?"}'
# PR Review
curl -X POST "http://localhost:8000/api/review-pr" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pr_number": 1}'文档
- LOCAL_SETUP.md -详细的当地发展指南
- CLAUDE.md -完整的技术文档
- 部署.md -铁路部署说明
- 个性化.md -用户配置文件定制
故障排除
GitHub Copilot MCP连接错误
- 验证PAT的范围是否正确(
repo,read:org) - 检查令牌未过期
- 检查api.githubcopilot.com的网络连接
PR审核的空响应
- 检查日志中的工具调用错误
- 验证
tool_choice: required设置为第一次迭代 - 模型可能无法很好地支持函数调用-尝试其他模型
高延迟
- 由于多次工具调用，PR审查可能需要30-60秒
- 检查OpenRouter速率限制
语音输入错误
- 未找到ffmpeg： 安装ffmpeg：
brew install ffmpeg - 音频转换失败： 检查ffmpeg安装和日志
- 无效的API密钥： 同步
BACKEND_API_KEY在服务器端/.env和客户端/.env中 - OpenRouter 500错误： 检查音频格式和型号可用性
端口已在使用中（本地）
# Kill process on port 8000
lsof -ti:8000 | xargs kill -9许可证
该项目展示了人工智能项目咨询的MCP集成。