项目管理MCP服务器
A. 模型上下文协议(MCP) 服务器充当AI助手的上下文感知中间件。它拦截用户查询,分析意图,从多个生产力系统(谷歌日历、GitHub、Slack和JIRA)获取上下文,组装一个结构化的上下文包,并将其与原始提示一起交付给Gemini AI模型,以获得超相关的响应。
此存储库(与Devpost演示视频一起)构成了构建自己的MCP挑战赛的提交。
目录
- 高级工作流
- 关键能力
- 建筑
- 集成和所需凭据
- 安装和设置
- 运行服务器和UI
- 可用的MCP工具
- 提交清单
- 项目结构
- 故障排除
- 许可证和联系方式
高级工作流
- 拦截 用户查询(通过MCP客户端、CLI或Streamlit仪表板)。
- 分析 NLP驱动的意图
QueryAnalyzer(意图检测、实体提取、领域分类、时间解析)。 - 获取 来自相关数据源的补充上下文。
- 组装 使用缓存、排名、摘要和相关性引擎的排名和摘要上下文包。
- 交付 将上下文包和原始提示发送给Gemini进行最终回复。
关键能力
智能查询理解
- 检测日历、GitHub、Slack和JIRA域(或多域查询)。
- 提取存储库、PR/问题计数、日历日期、积压关键字等实体。
- 通过时间感知分析器支持相对和绝对时间参考。
多源上下文收集
- 谷歌日历: 事件、可用性、冲突和多日历聚合。
- github: 存储库、问题、PR、提交、部署、README摘要。
- 松弛: 频道、提及、未读消息、最近的活动。
- 吉拉: 董事会、分配的问题、待办事项、冲刺见解。
上下文打包
- 上下文缓存: 基于TTL的缓存,以最大限度地减少冗余的API调用。
- ContextRanker: 对每个查询中最相关的事件/问题进行优先级排序。
- 上下文摘要生成器: 压缩上下文以保持在令牌预算范围内。
- 上下文关联器: 跨服务的交叉链接信号(例如,会议、部署和Slack警报)。
通过Gemini交付
- 聚合上下文+用户提示→ 双子座(主要
gemini-2.5-flash)制定量身定制的回应。
建筑```
┌──────────────────────────┐
│ User Request │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ Query Analyzer │ ← intent detection, entities, time range
└────────────┬─────────────┘
│
┌──────────┼───────────┐
│ │ │
▼ ▼ ▼
Calendar GitHub Slack JIRA
Client Client Client Client
(fetch) (fetch) (fetch) (fetch)
│ │ │ │
└──────────┴───────────┴─────────┘
│
▼
┌──────────────────────────┐
│ Cache / Rank / Summarize │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ Gemini Client (Chat) │ → context + prompt → AI answer
└──────────────────────────┘
______________________________________________________________________
## 集成和所需凭据
|服务|凭据/环境变量|注释|
|------------------|----------------------------------------------------------|-------|
|谷歌日历| `config/credentials.json`, `config/token.json` (已生成)|具有日历作用域的OAuth桌面凭据|
|GitHub| `.env` → `GITHUB_TOKEN` |具有回购范围的个人访问令牌|
|松弛| `.env` → `SLACK_USER_TOKEN` |用户令牌 `channels:read`, `channels:history`, `groups:*`, `im:*`, `search:read`, `users:read` |
|吉拉| `.env` → `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` |Jira Cloud网站、电子邮件和API令牌|
|双子座| `.env` → `GEMINI_API_KEY` |Google AI Studio API密钥|
可选环境变量(代码中有默认值):
- `GOOGLE_CREDENTIALS_PATH` (默认值 `config/credentials.json`)
- `GOOGLE_TOKEN_PATH` (默认值 `config/token.json`)
- `CALENDAR_TIMEZONE` (用于时间解析默认值)
确保敏感文件(凭据和令牌)不受版本控制。 `.gitignore` 已经把他们排除在外了。
______________________________________________________________________
## 安装和设置
1. **克隆存储库**```bash
git clone
cd MCP\ server
- 创建并激活Python环境```bash
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
1. **安装依赖项**```bash
pip install -r requirements.txt
- 提供凭据
- 将Google OAuth桌面凭据放置在
config/credentials.json. - 创建一个
.env文件(副本.env.example)并填充上面列出的令牌/密钥。
- 验证谷歌日历(首次运行)
首次运行服务器将启动Google OAuth的浏览器窗口,并生成config/token.json.
运行服务器和UI
1.MCP服务器(基于stdio的JSON-RPC)```bash
python main.py
这注册了以下工具 `chat`, `get_calendar_context`, `get_github_repositories`, `get_slack_mentions`, `get_jira_backlog`等等。
### 2.流线型仪表板(可选UI)```bash
streamlit run streamlit_app.py
具有预定义的查询、快速操作和Calendar/GitHub/Slack/JIRA的自定义提示框。
3.CLI测试脚本(可选)
interactive_client.py用于命令行聊天测试。slack_test.py,jira_test.py用于快速凭证和API验证。
可用的MCP工具
工具 · 说明
chat · 主要会话端点;自动获取所有服务中的相关上下文。
日历
get_calendar_context · 分析查询并返回格式化的日历上下文。
check_availability · 检查特定时间段的可用性。
get_upcoming_events · 列出即将发生的事件。
detect_conflicts · 识别约会中的冲突。
GitHub
get_github_repositories · 列出存储库(含元数据)。
get_github_issues · 获取未解决的问题。
get_github_pull_requests · 获取PR。
get_github_deployments · 检索部署+状态。
Slack
get_slack_channels · 列出频道。
get_slack_unread · 有未读消息的频道。
get_slack_mentions · 最近提到。
JIRA
get_jira_boards · 列出公告板。
get_jira_issues · 一般问题检索(板/JQL)。
get_my_jira_issues · 分配给经过身份验证的用户的问题(有回退)。
get_jira_backlog · 积压项目(敏捷API+JQL回退)。
每个工具都返回一个适合直接包含在上下文包中的格式化字符串。
提交清单
✅ GitHub存储库 –包含完整的MCP服务器实现、连接器、UI和测试脚本。
✅ 上下文感知工作流 –拦截→ 分析→ 获取→ 组装→ 交付在四个服务中实施。
⚠️ Devpost视频演示 -仍然需要。请录制一个简短的演练,显示:
- 查询如何在系统中流动(例如,通过Streamlit UI)。
- 生成的上下文程序集(日志/UI代码段)。
- 双子座的动力反应。
- 任何独特的2.0功能(缓存、关联、摘要)。
将视频与repo链接一起上传到Devpost。
项目结构```
MCP server/
├── main.py # Entry point for MCP server
├── streamlit_app.py # Optional Streamlit UI
├── interactive_client.py # Simple CLI client
├── slack_test.py / jira_test.py# Quick integration smoke tests
├── src/
│ ├── server.py # MCP tools & orchestration layer
│ ├── query_analyzer.py # NLP intent/time/entity detection
│ ├── context_cache.py # TTL cache for API responses
│ ├── context_ranker.py # Relevance scoring
│ ├── context_summarizer.py # Compression + summarization utilities
│ ├── context_correlator.py # Multi-source correlation engine
│ ├── context_formatter.py # Human-friendly context formatting
│ ├── gemini_client.py # Gemini chat integration
│ ├── calendar_client.py # Google Calendar wrapper
│ ├── github_client.py # GitHub REST wrapper
│ ├── slack_client.py # Slack WebClient wrapper
│ ├── jira_client.py # Jira REST (Agile + Core) wrapper
│ └── connectors/ # Connector facades per service
├── config/
│ ├── credentials.json # Google OAuth client (excluded from git)
│ └── token.json # Google OAuth token (excluded from git)
├── requirements.txt
├── .env.example
└── README.md (this file)
```
故障排除
| 问题 | 解决 |
|---|---|
| 谷歌日历身份验证循环 | 删除 config/token.json 并重新运行以重新进行身份验证。确保OAuth同意屏幕将您作为测试用户。 |
| GitHub 401 | 重新生成 GITHUB_TOKEN (经典PAT) repo 范围。 |
松弛 missing_scope |
在下面添加所需的范围 用户令牌范围 并重新安装应用程序。 |
| JIRA 410错误 | 确认您可以访问JIRA Cloud网站并使用有效的API令牌。当搜索失败时,客户端已经退回到基于板的查询。 |
| Gemini错误 | 验证 GEMINI_API_KEY 正确,所选型号在您的地区/帐户中可用。 |
日志记录配置为stderr,以避免干扰MCP stdio响应。
许可证和联系方式
为 构建自己的MCP挑战.
如有疑问,请在提交演示时打开问题或通过Devpost讨论板联系。
