ProjectPulse MCP

ProjectPulse MCP 🏥

GitHub repository health monitoring for AI assistants — works with any language, any repo.

---

This Model Context Protocol (MCP) server gives AI assistants the ability to analyze health, security, CI/CD status, and delivery metrics of any GitHub repository — directly from your conversations.

📑 Table of Contents

• Features
• Examples
• Use Cases
• Prerequisites
• Quick Start
• Tools
• Compatibility
• Architecture
• Transport Modes
• Configuration
• Testing
• Contributing
• License

✨ Features

• 🏥 Health Score — comprehensive 0-100 score with grade (A-F), category breakdown, and improvement suggestions
• 🔒 Security — Dependabot alerts blended with OpenSSF Scorecard checks (60/40 weighted)
• 📊 DORA Metrics — proxy DORA metrics from GitHub data: deployment frequency, lead time, change failure rate, MTTR
• 🔍 Code Scanning — CodeQL and other code scanning alerts with severity, message, and creation date
• 📦 Dependency Analysis — Dependabot alerts with severity filtering
• ⚙️ CI/CD Status — recent GitHub Actions workflow runs and conclusions
• 📋 Repository Info — stars, forks, language, license, and general metadata
• 📝 Best Practices — 12-point checklist for open-source repo quality (README, LICENSE, SECURITY.md, templates, branch protection, etc.) with A-F grade

📸 Examples

All screenshots taken live from MCP Inspector.

get_health_score — A-F grade with category breakdown

get_dora_metrics — DORA delivery metrics from GitHub data

compare_repos — Side-by-side health score ranking

check_ci_status — Recent GitHub Actions workflow runs

get_repo_health — Repository metadata and stats

analyze_dependencies — Dependabot vulnerability alerts

check_best_practices — Open-source repo quality checklist with A-F grade

💡 Use Cases

Copy-paste these prompts into Claude, Cursor, Windsurf, or any MCP-compatible assistant.

Due Diligence — Library Adoption

"Evaluate whether facebook/react is production-ready. Check the health score, security vulnerabilities (Dependabot and CodeQL), and whether the CI pipeline passes consistently."

Tools used: get_health_score, analyze_dependencies, analyze_code_scanning, check_ci_status

Compare Alternatives

"I need to choose between expressjs/express, fastify/fastify, and koajs/koa. Compare their health scores and tell me which one has the lowest technical risk."

Tools used: compare_repos

Sprint Review — DORA Metrics

"Calculate the DORA metrics for vercel/next.js over the last 30 days. I want to present delivery performance at our sprint review."

Tools used: get_dora_metrics

Trend Monitoring

"Check the health score of microsoft/vscode. Has it improved or worsened since the last time we checked?"

Tools used: get_health_score (includes trend comparison on repeated calls)

Quick Security Audit

"Run a security audit of pallets/flask: Dependabot alerts, CodeQL vulnerabilities, and CI build status. Give me a complete picture."

Tools used: analyze_dependencies, analyze_code_scanning, check_ci_status

---

📋 Prerequisites

• Node.js v18 or later — download
• npm (included with Node.js)
• GitHub Personal Access Token (optional for public repos, required for private repos and security data)

🚀 Quick Start

Claude Code (CLI)

claude mcp add projectpulse -- npx projectpulse-mcp

Note: You need a .env file with your GITHUB_TOKEN in the directory where you run Claude Code.

Claude Desktop

Step 1: Get a GitHub Token

1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Give it a name (e.g., projectpulse)
3. Select the repositories you want to monitor (or "All repositories")
4. Under Permissions, grant Read-only access to:
   • Code scanning alerts
   • Dependabot alerts
   • Metadata (enabled by default)
5. Click Generate token and copy it

Step 2: Configure Claude Desktop

1. Open Claude Desktop
2. Go to Settings (gear icon) > Developer > Edit Config
3. This opens claude_desktop_config.json. Add the projectpulse entry inside "mcpServers":

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

1. Save the file and restart Claude Desktop

Step 3: Verify it works

In a new Claude Desktop conversation, try asking:

"Check the health score of facebook/react"

Claude should call the get_health_score tool and return an A-F grade with a detailed breakdown.

Troubleshooting

Other MCP Clients (Cursor, Windsurf, etc.)

Configure a new MCP server with:

• Transport: stdio
• Command: npx
• Arguments: -y projectpulse-mcp
• Environment: GITHUB_TOKEN = your GitHub PAT

🛠️ Tools

get_health_score

Calculates a 0-100 health score with an A-F grade. Evaluates 5 weighted categories: CI reliability (25%), code freshness (20%), security posture (25%), community activity (15%), and maintenance quality (15%). Returns actionable improvement suggestions for low-scoring categories. On repeated calls for the same repo, includes a trend comparison showing score change since last check. Queries multiple GitHub API endpoints and OpenSSF Scorecard.

Side effect: saves a trend snapshot to local disk (~/.projectpulse/snapshots/).

Inputs: owner, repo Try asking: "What's the health score of microsoft/vscode?"

get_dora_metrics

Calculates proxy DORA metrics from public GitHub data: Deployment Frequency (from releases), Lead Time for Changes (PR created → merged), Change Failure Rate (CI failure percentage), and Mean Time to Recovery (CI failure → next success). Returns null for metrics with insufficient data. Queries multiple GitHub API endpoints (releases, pulls, actions) — heavier API usage than single-endpoint tools.

Inputs: owner, repo, days (optional, 7-90, default 30) Try asking: "Show me the DORA metrics for vercel/next.js over the last 60 days"

compare_repos

Compares health scores side-by-side for 2-5 repositories. Returns each repo's full health breakdown ranked by score. Useful for evaluating alternatives or benchmarking your project against similar ones. API calls are multiplied by the number of repos compared.

Inputs: repos (array of {owner, repo}) Try asking: "Compare the health of expressjs/express, fastify/fastify, and koajs/koa"

get_repo_health

Fetches basic repository metadata: stars, forks, open issues count, primary language, license, last push date, default branch, and archive status. Use this for a quick overview — for a computed grade, use get_health_score instead.

Inputs: owner, repo Try asking: "Give me general info about torvalds/linux"

analyze_dependencies

Lists Dependabot security alerts for vulnerable package dependencies (npm, pip, Maven, etc.) grouped by severity (critical, high, medium, low). Optionally filter by a specific severity level. Requires a token with Dependabot alerts permission.

Inputs: owner, repo, severity (optional) Try asking: "Show me critical dependency vulnerabilities in my-org/my-app"

check_ci_status

Returns the most recent CI/CD workflow runs from GitHub Actions: status (success, failure, in_progress), conclusion, branch, duration, and timestamps. Useful for checking if builds are green before deploying or merging.

Inputs: owner, repo, limit (optional, default 10) Try asking: "Are the CI builds passing for facebook/react?"

analyze_code_scanning

Lists CodeQL and other code scanning alerts: rule ID, severity, vulnerability message, affected file and line number, and creation date. Requires a token with Code scanning alerts permission. Can optionally trigger a CodeQL scan and wait for results (requires Advanced Setup, not Default Setup).

Inputs: owner, repo, trigger_scan (optional, default false), poll_timeout_seconds (optional, default 300), poll_interval_seconds (optional, default 15) Try asking: "Are there any code scanning vulnerabilities in my-org/my-api?"

check_best_practices

Evaluates whether a repository follows open-source community best practices. Runs 12 weighted checks: README, LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT, issue/PR templates, branch protection, Dependabot config, CI/CD workflows, description, and topics. Returns a 0-100 weighted score with A-F grade, per-check pass/fail/unknown status, and actionable suggestions for every missing item. Branch protection check requires admin token access — returns "unknown" (not penalized) if unavailable.

Inputs: owner, repo Try asking: "Does my-org/my-repo follow open-source best practices?"

ping

Simple connectivity check. Returns "pong" with your message. Use to verify the MCP server is running.

Inputs: message

🆕 What's New

HTTP Transport (v1.7.0)

ProjectPulse now supports Streamable HTTP transport in addition to stdio. This enables running as a standalone HTTP server — ideal for Docker containers, remote deployments, and cross-runtime integrations (e.g., .NET clients consuming Node.js MCP tools over the network).

Default behavior is unchanged — npx projectpulse-mcp still uses stdio. To activate HTTP mode:

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

Docker example:

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}

Health check endpoint available at GET / (returns JSON with server name and version). MCP protocol endpoint at POST /mcp.

OpenSSF Scorecard Integration

Security score now blends Dependabot alerts (60%) with OpenSSF Scorecard checks (40%) for a more complete picture. 12 security-relevant checks are evaluated — repos without a scorecard gracefully fall back to Dependabot-only scoring.

DORA Metrics

New get_dora_metrics tool calculates proxy DORA metrics from public GitHub data:

Metrics return null when insufficient data is available — works safely on any repository.

🔌 Compatibility

ProjectPulse works with any MCP-compatible client. Tested with:

🏗️ Architecture

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

• Tool layer: 8 independent tools, each in its own file (src/tools/)
• GitHub API: all calls through a shared Octokit client (src/github/client.ts) with rate-limit handling
• OpenSSF Scorecard: integrated via public API for security scoring
• Input validation: Zod schemas at the MCP boundary
• Transport: stdio (default) or Streamable HTTP — configurable via environment variables

🚢 Transport Modes

See What's New: HTTP Transport for Docker examples.

⚙️ Configuration

GITHUB_TOKEN

Required to avoid rate limits and access security data (Dependabot, CodeQL alerts).

Option A: Fine-grained PAT (Recommended)

1. Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Select target repositories
3. Grant Read-only access to:
   • Code scanning alerts
   • Dependabot alerts
   • Metadata (default)

Option B: Classic Token Generate with repo + security_events scopes.

Providing the token:

• Claude Desktop: set in claude_desktop_config.json (see Quick Start)
• Claude Code / Local: create a .env file:

  GITHUB_TOKEN=ghp_your_token_here

🧪 Testing

All 8 tools have dedicated test suites. Tests use Vitest with mocked GitHub API responses.

# Run all tests
npm test

# Watch mode
npm run test:watch

👤 Author

alexbypa — GitHub · npm

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (npm test) and ensure they pass
4. Commit your changes
5. Push to the branch and open a Pull Request

See the issues page for open tasks and bug reports.

⭐ Show your support

Give a star if this project helped you!

📝 License

MIT — see the LICENSE file for details.