ProjectPulse MCP 是一个 GitHub 仓库健康监控工具，以 Model Context Protocol（MCP）服务器形式提供，让 AI 助手能在对话中直接分析任意 GitHub 仓库的健康、安全、CI/CD 状态与交付指标，支持任意语言、任意仓库。
用途 它面向需要在对话中快速评估 GitHub 仓库质量与风险的场景，例如：库选型尽调（判断某项目是否可投入生产）、方案对比（比较多个候选仓库的技术风险）、冲刺回顾（展示 DORA 指标）、趋势监控（对比同一仓库历史健康分）、快速安全审计（依赖告警、代码扫描与 CI 状态）。
主要能力（8 个工具）
- get_health_score：计算 0-100 健康分并给出 A-F 等级，评估 5 个加权维度：CI 可靠性 25%、代码新鲜度 20%、安全态势 25%、社区活跃度 15%、维护质量 15%；对低分维度给出可操作改进建议；同一仓库重复调用时会返回与上次检查的趋势对比。查询多个 GitHub API 端点与 OpenSSF Scorecard。副作用：将趋势快照保存到本地磁盘（~/.projectpulse/snapshots/）。输入：owner、repo。
- get_dora_metrics：从公开 GitHub 数据推算代理 DORA 指标：部署频率（来自 releases）、变更前置时间（PR 创建到合并）、变更失败率（CI 失败百分比）、平均恢复时间（CI 失败到下次成功）。数据不足的指标返回 null。查询多个 GitHub API 端点（releases、pulls、actions），API 用量高于单端点工具。输入：owner、repo、days（可选，7-90，默认 30）。
- compare_repos：并排比较 2-5 个仓库的健康分，按分数排序返回每个仓库的完整健康明细，适合评估替代方案或与同类项目对标。API 调用数随仓库数量成倍增加。输入：repos（{owner, repo} 数组）。
- get_repo_health：获取基础仓库元信息：stars、forks、未解决 issue 数、主要语言、许可证、最后推送日期、默认分支、归档状态。如需计算的评级请改用 get_health_score。输入：owner、repo。
- analyze_dependencies：列出 Dependabot 安全告警（npm、pip、Maven 等），按严重程度（critical、high、medium、low）分组，可按指定严重级别过滤。需要具备 Dependabot alerts 权限的 token。输入：owner、repo、severity（可选）。
- check_ci_status：返回最近的 GitHub Actions 工作流运行：状态（success、failure、in_progress）、结论、分支、时长与时间戳，适合在部署或合并前检查构建是否通过。输入：owner、repo、limit（可选，默认 10）。
- analyze_code_scanning：列出 CodeQL 及其他代码扫描告警：规则 ID、严重程度、漏洞消息、受影响文件与行号、创建日期。需要具备 Code scanning alerts 权限的 token。可选触发 CodeQL 扫描并等待结果（需要 Advanced Setup，而非 Default Setup）。输入：owner、repo、trigger_scan（可选，默认 false）、poll_timeout_seconds（可选，默认 300）、poll_interval_seconds（可选，默认 15）。
- check_best_practices：评估仓库是否遵循开源社区最佳实践，运行 12 项加权检查：README、LICENSE、SECURITY.md、CONTRIBUTING.md、CODE_OF_CONDUCT、issue/PR 模板、分支保护、Dependabot 配置、CI/CD 工作流、描述与 topics。返回 0-100 加权分与 A-F 等级、每项通过/失败/未知状态，以及每个缺失项的可操作建议。分支保护检查需要管理员 token 权限，不可用时返回“unknown”且不扣分。输入：owner、repo。 另有 ping：简单连通性检查，返回带有你消息的“pong”，用于验证 MCP 服务器正在运行。输入：message。
使用方式 前置条件：Node.js v18 或更高版本、npm（随 Node.js 提供）、GitHub Personal Access Token（公开仓库可选，私有仓库与安全数据必需）。
- Claude Code（CLI）：需在运行 Claude Code 的目录中提供包含 GITHUB_TOKEN 的 .env 文件。
- Claude Desktop：打开 Settings（齿轮图标）> Developer > Edit Config，编辑 claude_desktop_config.json，在 "mcpServers" 中添加 projectpulse 条目，保存后重启。
- 其他 MCP 客户端（Cursor、Windsurf 等）：配置新的 MCP 服务器，Transport 为 stdio，Arguments 为 -y projectpulse-mcp，环境变量 GITHUB_TOKEN 设为你的 GitHub PAT。
- HTTP 传输（v1.7.0）：除 stdio 外新增 Streamable HTTP 传输，可运行为独立 HTTP 服务器，适用于 Docker 容器、远程部署与跨运行时集成。默认行为不变，npx projectpulse-mcp 仍使用 stdio；通过环境变量激活 HTTP 模式。健康检查端点为 GET /（返回含服务器名称与版本的 JSON），MCP 协议端点为 POST /mcp。 Token 权限：推荐使用 Fine-grained PAT，在 Settings > Developer settings > Personal access tokens > Fine-grained tokens 中选择目标仓库，授予 Code scanning alerts、Dependabot alerts、Metadata（默认启用）的只读权限，也可使用具备 repo + security_events 作用域的经典 token。
适用场景
- 库采用尽调：评估某仓库是否可投入生产，检查健康分、安全漏洞与 CI 是否稳定通过。
- 比较替代方案：在多个候选仓库间比较健康分，找出技术风险最低者。
- 冲刺回顾：计算某项目近 30 天的 DORA 指标。
- 趋势监控：重复检查某仓库健康分，观察改善或恶化。
- 快速安全审计：汇总 Dependabot 告警、CodeQL 漏洞与 CI 构建状态。
兼容性与架构 可配合任意 MCP 兼容客户端使用。架构上，工具层为 8 个独立工具，各占 src/tools/ 下一个文件；所有调用通过共享 Octokit 客户端（src/github/client.ts）并处理速率限制；OpenSSF Scorecard 通过公开 API 集成用于安全评分；输入验证使用 MCP 边界处的 Zod 模式；传输方式为 stdio（默认）或 Streamable HTTP，可通过环境变量配置。
限制
- 需要 GitHub token 才能避免速率限制并访问安全数据（Dependabot、CodeQL 告警）。
- get_dora_metrics 为基于公开 GitHub 数据的代理指标，数据不足时对应指标返回 null。
- 代码扫描的触发扫描功能需要 Advanced Setup，而非 Default Setup。
- 分支保护检查需要管理员 token 权限，不可用时返回“unknown”且不扣分。
- get_health_score 会在本地磁盘保存趋势快照。
- 测试使用 Vitest，配合模拟的 GitHub API 响应。
许可与支持：MIT 许可证，详见 LICENSE 文件。作者为 alexbypa，仓库与 npm 均有发布。欢迎贡献、提交 issue 与功能请求。
