项目管理MCP服务器
A. 模型上下文协议（MCP） 服务器充当AI助手的上下文感知中间件。它拦截用户查询，分析意图，从多个生产力系统（谷歌日历、GitHub、Slack和JIRA）获取上下文，组装一个结构化的上下文包，并将其与原始提示一起交付给Gemini AI模型，以获得超相关的响应。
此存储库（与Devpost演示视频一起）构成了构建自己的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 已经把他们排除在外了。
______________________________________________________________________
安装和设置
- 克隆存储库
git clone
cd MCP\ server- 创建并激活Python环境
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate- 安装依赖项
pip install -r requirements.txt- 提供凭据
- 将Google OAuth桌面凭据放置在 config/credentials.json. - 创建一个 .env 文件（副本 .env.example)并填充上面列出的令牌/密钥。
- 验证谷歌日历（首次运行）
首次运行服务器将启动Google OAuth的浏览器窗口，并生成 config/token.json.
______________________________________________________________________
运行服务器和UI
1.MCP服务器（基于stdio的JSON-RPC）
python main.py这注册了以下工具 chat, get_calendar_context, get_github_repositories, get_slack_mentions, get_jira_backlog等等。
2.流线型仪表板（可选UI）
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讨论板联系。