内容
# GitPulse AI
**一个MCP服务器，使AI助手（Claude、ChatGPT等）能够分析任何公共GitHub仓库的健康状况 — 加上一个用于可视化结果的React仪表盘。**
GitPulse AI通过将实时的GitHub数据与LLM生成的叙述、评分和建议相结合，回答诸如 *"这个仓库健康吗？"*、 *"审查这个拉取请求"* 和 *"我应该先修复哪些问题？"* 之类的问题。
## 功能
GitPulse通过 **模型上下文协议（MCP）** 暴露了五个工具，因此任何与MCP兼容的AI客户端都可以直接在对话中调用它们：
| 工具 | 描述 |
|---|---|
| `get_repo_health` | 对仓库进行0-100的评分，并将其分类为 `健康`、`停滞`、`有风险` 或 `已存档`，并附有AI生成的优势、风险和建议的叙述。 |
| `review_file` | 审查单个文件的代码质量、命名、文档覆盖率、复杂度和潜在错误。 |
| `review_pull_request` | 审查PR中每个更改的文件，并生成每个文件的审查结果和整体摘要。 |
| `triage_issues` | 将开放的问题分类为高优先级错误、过时、良好初始问题、文档请求或功能请求，并附有维护者的建议。 |
| `full_repo_assessment` | 将健康检查、问题分类和质量检查（README、安全、CI/CD、贡献健康）结合成一份完整的报告。 |
配套的React仪表盘（目前运行在模拟数据上）可视化这些数据：仓库列表、健康评分、活动图表和AI洞察面板。
## 架构
```
终端用户
│ "这个仓库健康吗？"
▼
MCP客户端（Claude / ChatGPT）
│ 工具调用（JSON-RPC via stdio）
▼
GitPulse MCP服务器（Python）
│
├── GitHub API层 ──────► GitHub REST API（认证、重试、缓存）
├── LLM处理层 ───► OpenAI API（叙述生成）
└── 分析引擎 ───────► 健康评分 · 代码审查 · 问题分类
│
▼
结构化JSON + 自然语言报告 → 返回给AI客户端
```
每个工具都是一个无状态的、可独立测试的服务 — 参见 [`architecture.md`](./architecture.md) 以获取每个组件的完整分解，以及 [`techstack.md`](./techstack.md) 以了解选择每个库的原因。
## 项目结构
```
GitPulse-AI/
├── gitpulse_mcp/ # MCP服务器包（源代码）
│ ├── main.py # 注册5个工具，stdio传输入口点
│ ├── config.py # Pydantic设置（环境变量驱动）
│ ├── api/ # 可选的FastAPI HTTP层（用于仪表盘/测试）
│ ├── github/ # GitHub REST API客户端（仓库、提交、问题、PR、文件）
│ ├── llm/ # LLM客户端、提示模板、结构化响应模式
│ ├── services/ # 健康/审查/分类/评估业务逻辑
│ ├── cache/ # 会话级响应缓存
│ └── tests/ # 包的单元测试
├── src/ # React + TypeScript仪表盘（Vite）
│ ├── pages/ # 首页、仪表盘、仓库详情、AI洞察
│ ├── components/ # 导航栏、侧边栏、仓库表格等
│ └── data/mockData.ts # 模拟数据（仪表盘尚未连接到API）
├── tests/ # 根级测试套件（镜像gitpulse_mcp/tests）
├── demo.py # 直接调用工具的最小脚本，无需MCP客户端
├── architecture.md # 完整系统设计文档
├── techstack.md # 技术选择和理由
└── project-context.md # 项目背景/目标
```
## 入门指南
### 前提条件
- Python 3.11+
- Node.js 18+（用于仪表盘）
- [GitHub个人访问令牌](https://github.com/settings/tokens)（公共仓库无需特殊范围）
- [OpenAI API密钥](https://platform.openai.com/api-keys)
### 1. 后端 — MCP服务器
```bash
# 安装带有开发依赖的包
pip install -e ".[dev]"
# 配置环境变量
cp .env.example .env # 然后填写GITHUB_TOKEN和OPENAI_API_KEY
```
`.env` 应至少包含：
```
GITHUB_TOKEN=ghp_your_token_here
OPENAI_API_KEY=sk-your_key_here
```
运行MCP服务器（stdio传输，用于Claude Desktop或MCP Inspector）：
```bash
python -m gitpulse_mcp.main
```
或在没有MCP客户端的情况下直接尝试工具：
```bash
python demo.py
```
可选地，运行FastAPI HTTP层（用于本地测试或驱动仪表盘）：
```bash
pip install fastapi uvicorn
uvicorn gitpulse_mcp.api.main:app --reload
```
### 2. 连接到Claude Desktop
将GitPulse添加到Claude Desktop的MCP配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"gitpulse": {
"command": "python",
"args": ["-m", "gitpulse_mcp.main"]
}
}
}
```
重启Claude Desktop并询问类似 *"使用GitPulse检查facebook/react的健康状况。"*
### 3. 前端 — 仪表盘
```bash
npm install
npm run dev
```
这启动了Vite开发服务器。仪表盘当前渲染的是 `src/data/mockData.ts` 中的模拟数据；将其连接到FastAPI层是路线图上的下一步。
## 运行测试
```bash
python -m pytest tests/ -v
```
测试套件涵盖了GitHub客户端、缓存、模型和所有四个服务（健康、审查、分类、评估），使用 `respx` 模拟GitHub/OpenAI HTTP调用，共有65+个测试。
## 配置
所有运行时设置都位于 `gitpulse_mcp/config.py` 并从 `.env` 加载：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GITHUB_TOKEN` | — | GitHub个人访问令牌（必填） |
| `OPENAI_API_KEY` | — | OpenAI API密钥（必填） |
| `OPENAI_MODEL` | `gpt-4o-mini` | 用于叙述生成的LLM |
| `WEIGHT_COMMIT_FREQ` | `0.30` | 健康评分权重 — 提交频率 |
| `WEIGHT_PR_MERGE_RATIO` | `0.25` | 健康评分权重 — PR合并比率 |
| `WEIGHT_ISSUE_CLOSE_RATE` | `0.25` | 健康评分权重 — 问题关闭率 |
| `WEIGHT_CONTRIBUTOR_ACTIVITY` | `0.20` | 健康评分权重 — 贡献者活动 |
| `ACTIVITY_LOOKBACK_DAYS` | `30` | 用于活动指标的历史天数 |
| `CACHE_TTL_SECONDS` | `300` | 会话缓存TTL（`0` 禁用缓存） |
四个 `WEIGHT_*` 值之和必须为1.0 — 如果它们不相等，应用程序将在启动时引发验证错误。
## 技术栈
- **MCP服务器：** Python 3.11， [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)，HTTPX（异步GitHub调用），Pydantic v2，OpenAI SDK
- **可选HTTP层：** FastAPI + Uvicorn
- **仪表盘：** React 18，TypeScript，Vite，Tailwind CSS，Framer Motion，Recharts，lucide-react
- **测试：** pytest，pytest-asyncio，respx
参见 [`techstack.md`](./techstack.md) 以获取每个选择的完整理由。
## 状态
这是一个学生构建的项目（参见 [`project-context.md`](./project-context.md) 以获取背景信息）。MCP服务器及其五个工具功能齐全且经过测试；React仪表盘是一个独立的UI，目前由模拟数据驱动，计划下一步与后端集成。
## 许可证
MIT — 参见 [`LICENSE`](./LICENSE)。
