ProjectPulse MCP

ProjectPulse MCP 🏥

面向 AI 助手的 GitHub 仓库健康状况监控——适用于任何语言和任何仓库。

---

此 模型上下文协议（MCP）服务可让 AI 助手直接在对话中分析任意 GitHub 仓库的健康状况、安全性、CI/CD 状态和交付指标。

📑 目录

• 功能
• 示例
• 使用场景
• 前置条件
• 快速开始
• 工具
• 兼容性
• 架构
• 传输模式
• 配置
• 测试
• 参与贡献
• 许可证

✨ 功能

• 🏥 健康评分 — 全面的 0-100 分评分，包含等级（A-F）、分类明细和改进建议
• 🔒 安全性 — 将 Dependabot 警报与 OpenSSF Scorecard 检查结果相结合（权重分别为 60/40）
• 📊 DORA 指标 — 根据 GitHub 数据计算 DORA 指标的估算值：部署频率、前置时间、变更失败率、MTTR
• 🔍 代码扫描 — CodeQL 和其他代码扫描警报，包含严重程度、消息和创建日期
• 📦 依赖项分析 — 可按严重程度筛选 Dependabot 警报
• ⚙️ CI/CD 状态 — 最近的 GitHub Actions 工作流运行记录及其结论
• 📋 仓库信息 — 星标数、分叉数、语言、许可证和一般元数据
• 📝 最佳实践 — 包含 12 项检查内容的开源仓库质量清单（README、LICENSE、SECURITY.md、模板、分支保护等），并提供 A-F 等级

📸 示例

所有截图均实时取自 MCP Inspector。

get_health_score — A-F 评级及分类细项

get_dora_metrics — 基于 GitHub 数据的 DORA 交付指标

compare_repos — 并排比较健康评分排名

check_ci_status — 最近的 GitHub Actions 工作流运行记录

get_repo_health — 仓库元数据和统计信息

analyze_dependencies — Dependabot 漏洞警报

check_best_practices — 开源仓库质量检查清单及 A-F 评级

💡 使用场景

将这些提示词复制并粘贴到 Claude、Cursor、Windsurf 或任何兼容 MCP 的助手中。

尽职调查 — 采用库

“评估 facebook/react 是否适合用于生产环境。检查健康评分、安全漏洞（Dependabot 和 CodeQL），以及 CI 流水线是否持续通过。”

使用的工具：get_health_score、analyze_dependencies、analyze_code_scanning、check_ci_status

比较替代方案

“我需要在 expressjs/express、fastify/fastify 和 koajs/koa 之间做出选择。比较它们的健康评分，并告诉我哪个的技术风险最低。”

使用的工具：compare_repos

Sprint 评审 — DORA 指标

“计算 vercel/next.js 过去 30 天的 DORA 指标。我想在 Sprint 评审中展示交付表现。”

使用的工具：get_dora_metrics

趋势监测

“检查 microsoft/vscode 的健康评分。与上次检查相比，它有所改善还是变差了？”

使用的工具：get_health_score（重复调用时会进行趋势比较）

快速安全审计

“对 pallets/flask 执行安全审计：检查 Dependabot 警报、CodeQL 漏洞和 CI 构建状态。给我一个完整的情况概览。”

使用的工具：analyze_dependencies、analyze_code_scanning、check_ci_status

---

📋 前置条件

• Node.js v18 或更高版本 — 下载
• npm（随 Node.js 一同安装）
• GitHub 个人访问令牌（公开仓库可选；私有仓库和安全数据必需）

🚀 快速开始

Claude Code（CLI）

claude mcp add projectpulse -- npx projectpulse-mcp

注意： 运行 Claude Code 的目录中需要有一个包含 GITHUB_TOKEN 的 .env 文件。

Claude Desktop

步骤 1：获取 GitHub 令牌

1. 前往 GitHub 设置 > 开发者设置 > 个人访问令牌 > 细粒度令牌
2. 为令牌命名（例如，projectpulse）
3. 选择要监控的仓库（或“All repositories”）
4. 在 Permissions 下，为以下项目授予 Read-only 访问权限：
   • Code scanning alerts
   • Dependabot alerts
   • Metadata（默认已启用）
5. 点击 Generate token 并复制令牌

步骤 2：配置 Claude Desktop

1. 打开 Claude Desktop
2. 前往 Settings（齿轮图标）> Developer > Edit Config
3. 这会打开 claude_desktop_config.json。在 "mcpServers" 内添加 projectpulse 条目：

{
  "mcpServers": {
    "projectpulse": {
      "command": "npx",
      "args": ["-y", "projectpulse-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_paste_your_token_here"
      }
    }
  }
}

4. 保存文件并重启 Claude Desktop

步骤 3：验证是否正常工作

在新的 Claude Desktop 对话中，尝试提问：

"检查一下 facebook/react 的健康评分"

Claude 应调用 get_health_score 工具，并返回 A-F 等级及详细分析。

故障排除

问题	解决方案
未显示工具	编辑配置文件后重启 Claude Desktop
出现 "Rate limit exceeded" 错误	确保在配置中正确设置了 GITHUB_TOKEN
缺少 Dependabot/CodeQL 数据	令牌需要具有 Code scanning alerts 和 Dependabot alerts 权限
找不到 npx	安装 Node.js（v18 或更高版本），并确保 npx 位于 PATH 中

其他 MCP 客户端（Cursor、Windsurf 等）

配置新的 MCP 服务：

• 传输方式：stdio
• 命令：npx
• 参数：-y projectpulse-mcp
• 环境变量：GITHUB_TOKEN = 你的 GitHub PAT

🛠️ 工具

get_health_score

计算 0-100 的健康评分，并给出 A-F 等级。评估 5 个加权类别：CI 可靠性（25%）、代码新鲜度（20%）、安全状况（25%）、社区活跃度（15%）和维护质量（15%）。针对得分较低的类别返回可执行的改进建议。对同一仓库重复调用时，会提供趋势对比，显示自上次检查以来的评分变化。查询多个 GitHub API 端点和 OpenSSF Scorecard。

**副作用：**将趋势快照保存到本地磁盘（~/.projectpulse/snapshots/）。

输入：owner、repo 试着问： "microsoft/vscode 的健康评分是多少？"

get_dora_metrics

根据公开的 GitHub 数据计算代理 DORA 指标：部署频率（根据发布记录）、变更前置时间（PR 创建 → 合并）、变更失败率（CI 失败百分比）和平均恢复时间（CI 失败 → 下次成功）。数据不足时，相关指标返回 null。查询多个 GitHub API 端点（releases、pulls、actions），API 使用量高于仅查询单个端点的工具。

输入：owner、repo、days（可选，7-90，默认 30） 试着问： "显示 vercel/next.js 过去 60 天的 DORA 指标"

compare_repos

并排比较 2-5 个仓库的健康评分。按评分对每个仓库的完整健康分析进行排名。适用于评估替代方案，或将项目与类似项目进行对标。API 调用次数会随比较的仓库数量增加。

输入：repos（{owner, repo} 数组） 试着问： "比较 expressjs/express、fastify/fastify 和 koajs/koa 的健康状况"

get_repo_health

获取基本仓库元数据：星标数、复刻数、未关闭议题数、主要语言、许可证、最近推送日期、默认分支和归档状态。可用于快速了解概况；如需计算等级，请改用 get_health_score。

输入：owner、repo 试着问： "介绍一下 torvalds/linux 的基本信息"

analyze_dependencies

按严重程度（严重、高、中、低）列出易受攻击的包依赖项（npm、pip、Maven 等）的 Dependabot 安全警报。可按特定严重程度筛选。需要具有 Dependabot alerts 权限的令牌。

输入： owner、repo、severity（可选） 试着这样提问： “显示 my-org/my-app 中严重的依赖项漏洞”

check_ci_status

返回 GitHub Actions 中最近的 CI/CD 工作流运行记录：状态（success、failure、in_progress）、结论、分支、持续时间和时间戳。可用于在部署或合并前检查构建是否通过。

输入： owner、repo、limit（可选，默认值为 10） 试着这样提问： “facebook/react 的 CI 构建都通过了吗？”

analyze_code_scanning

列出 CodeQL 和其他代码扫描警报：规则 ID、严重程度、漏洞消息、受影响的文件和行号，以及创建日期。需要具有 Code scanning alerts 权限的令牌。还可选择触发 CodeQL 扫描并等待结果（需要 Advanced Setup，而非 Default Setup）。

输入： owner、repo、trigger_scan（可选，默认值为 false）、poll_timeout_seconds（可选，默认值为 300）、poll_interval_seconds（可选，默认值为 15） 试着这样提问： “my-org/my-api 中是否存在代码扫描发现的漏洞？”

check_best_practices

评估仓库是否遵循开源社区最佳实践。执行 12 项加权检查：README、LICENSE、SECURITY.md、CONTRIBUTING.md、CODE_OF_CONDUCT、议题/PR 模板、分支保护、Dependabot 配置、CI/CD 工作流、描述和主题。返回 0 到 100 的加权评分及 A-F 等级、每项检查的通过/失败/未知状态，以及针对所有缺失项的可操作建议。分支保护检查需要管理员令牌访问权限；若无法访问，则返回“未知”（不扣分）。

输入： owner、repo 试着这样提问： “my-org/my-repo 是否遵循开源最佳实践？”

ping

简单的连接检查。返回“pong”和你的消息。用于验证 MCP 服务是否正在运行。

输入： message

🆕 最新动态

HTTP 传输（v1.7.0）

除 stdio 外，ProjectPulse 现在还支持 Streamable HTTP 传输。这使其能够作为独立的 HTTP 服务运行，非常适合 Docker 容器、远程部署和跨运行时集成（例如，.NET 客户端通过网络调用 Node.js MCP 工具）。

默认行为保持不变——npx projectpulse-mcp 仍使用 stdio。启用 HTTP 模式：

MCP_TRANSPORT=http MCP_PORT=3000 node dist/index.js

环境变量	默认值	描述
MCP_TRANSPORT	stdio	传输模式：stdio 或 http
MCP_PORT	3000	HTTP 服务端口（仅在 MCP_TRANSPORT=http 时使用）

Docker 示例：

projectpulse:
  image: node:22-slim
  command: >-
    sh -c "npm install -g projectpulse-mcp &&
           node /usr/local/lib/node_modules/projectpulse-mcp/dist/index.js"
  environment:
    - MCP_TRANSPORT=http
    - MCP_PORT=3000
    - GITHUB_TOKEN=${GITHUB_TOKEN}

健康检查端点位于 GET /（返回包含服务名称和版本的 JSON）。MCP 协议端点位于 POST /mcp。

OpenSSF Scorecard 集成

安全评分现在结合了 Dependabot 警报（60%）和 OpenSSF Scorecard 检查（40%），以提供更全面的评估。系统会评估 12 项与安全相关的检查；没有 scorecard 的仓库会自动回退到仅使用 Dependabot 评分。

DORA 指标

新增的 get_dora_metrics 工具可根据公开的 GitHub 数据计算代理 DORA 指标：

指标	来源	单位
部署频率	Releases	次/周
变更前置时间	PR 创建 → 合并	小时（中位数）
变更失败率	CI 工作流结论	百分比
平均恢复时间	CI 失败 → 下次成功	小时（中位数）

数据不足时，指标会返回 null——可安全地用于任何仓库。

🔌 兼容性

ProjectPulse 适用于任何兼容 MCP 的客户端。已测试：

客户端	传输方式	状态
Claude Desktop	stdio	✅ 已测试
Claude Code (CLI)	stdio	✅ 已测试
Cursor	stdio	✅ 已测试
Windsurf	stdio	✅ 已测试
MCP Inspector	stdio	✅ 已测试
Docker / 远程	HTTP	✅ 已测试
任意 MCP 客户端	stdio 或 HTTP	✅ 兼容

🏗️ 架构

┌─────────────────────────────────────────────────┐
│                  MCP Client                     │
│        (Claude, Cursor, Windsurf, etc.)         │
└────────────────────┬────────────────────────────┘
                     │ stdio or HTTP
┌────────────────────▼────────────────────────────┐
│            ProjectPulse MCP Server              │
│                                                 │
│  ┌─────────────┐  ┌─────────────┐              │
│  │  Tool Layer  │  │  Transport  │              │
│  │  (8 tools)   │  │ stdio/HTTP  │              │
│  └──────┬──────┘  └─────────────┘              │
│         │                                       │
│  ┌──────▼──────┐  ┌─────────────┐              │
│  │  GitHub API  │  │   OpenSSF   │              │
│  │  (Octokit)   │  │  Scorecard  │              │
│  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────┘

• 工具层：8 个独立工具，各自位于单独的文件中（src/tools/）
• GitHub API：所有调用都通过共享的 Octokit 客户端（src/github/client.ts），并处理速率限制
• OpenSSF Scorecard：通过公共 API 集成，用于安全评分
• 输入验证：在 MCP 边界使用 Zod 架构
• 传输方式：stdio（默认）或 Streamable HTTP，可通过环境变量配置

🚢 传输模式

	stdio（默认）	HTTP
启用方式	npx projectpulse-mcp	MCP_TRANSPORT=http node dist/index.js
适用场景	本地 MCP 客户端	Docker、远程、跨运行时
健康检查	不适用	GET / → JSON
MCP 端点	stdin/stdout	POST /mcp
所需配置	无	MCP_TRANSPORT=http，可选配置 MCP_PORT

Docker 示例请参阅新功能：HTTP 传输。

⚙️ 配置

GITHUB_TOKEN

必需，用于避免速率限制并访问安全数据（Dependabot、CodeQL 警报）。

选项 A：细粒度 PAT（推荐）

1. Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. 选择目标仓库
3. 授予以下权限的只读访问权限：
   • Code scanning alerts
   • Dependabot alerts
   • Metadata（默认）

选项 B：经典令牌 生成包含 repo + security_events 范围的令牌。

提供令牌：

• Claude Desktop：在 claude_desktop_config.json 中设置（参见快速入门）
• Claude Code / 本地：创建 .env 文件：

  GITHUB_TOKEN=ghp_your_token_here
  

🧪 测试

所有 8 个工具都有专门的测试套件。测试使用 Vitest，并模拟 GitHub API 响应。

# Run all tests
npm test

# Watch mode
npm run test:watch

工具	测试文件	状态
get_health_score	src/tools/get-health-score.test.ts	✅
get_dora_metrics	src/tools/get-dora-metrics.test.ts	✅
compare_repos	src/tools/compare-repos.test.ts	✅
get_repo_health	src/tools/get-repo-health.test.ts	✅
analyze_dependencies	src/tools/analyze-dependencies.test.ts	✅
check_ci_status	src/tools/check-ci-status.test.ts	✅
analyze_code_scanning	src/tools/analyze-code-scanning.test.ts	✅
check_best_practices	src/tools/check-best-practices.test.ts	✅

👤 作者

alexbypa — GitHub · npm

🤝 贡献

欢迎贡献、提交问题和功能请求！

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 运行测试（npm test）并确保通过
4. 提交更改
5. 推送到分支并发起 Pull Request

请参阅 issues 页面，了解待处理任务和错误报告。

⭐ 支持我们

如果这个项目对你有所帮助，请点个 Star！

📝 许可证

MIT — 详情请参阅 LICENSE 文件。