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)

1. 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_