ProjectPulse MCP ๐ฅ
GitHub repository health monitoring for AI assistants โ works with any language, any repo.
---
This [Model Context Protocol](https://modelcontextprotocol.io/) (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](#-features)
- [Examples](#-examples)
- [Use Cases](#-use-cases)
- [Prerequisites](#-prerequisites)
- [Quick Start](#-quick-start)
- [Tools](#๏ธ-tools)
- [Compatibility](#-compatibility)
- [Architecture](#-architecture)
- [Transport Modes](#-transport-modes)
- [Configuration](#๏ธ-configuration)
- [Testing](#-testing)
- [Contributing](#-contributing)
- [License](#-license)
## โจ Features
- ๐ฅ **Health Score** โ comprehensive 0-100 score with grade (A-F), category breakdown, and improvement suggestions
- ๐ **Security** โ Dependabot alerts blended with [OpenSSF Scorecard](https://scorecard.dev/) checks (60/40 weighted)
- ๐ **DORA Metrics** โ proxy [DORA metrics](https://dora.dev/) 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](https://modelcontextprotocol.io/docs/tools/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](https://nodejs.org/)
- **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)
```bash
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](https://github.com/settings/personal-access-tokens/new)
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"`:
```json
{
"mcpServers": {
"projectpulse": {
"command": "npx",
"args": ["-y", "projectpulse-mcp"],
"env": {
"GITHUB_TOKEN": "ghp_paste_your_token_here"
}
}
}
}
```
4. 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
| Problem | Solution |
| --- | --- |
| Tools not showing up | Restart Claude Desktop after editing the config file |
| "Rate limit exceeded" errors | Make sure `GITHUB_TOKEN` is set correctly in the config |
| Dependabot/CodeQL data missing | Your token needs `Code scanning alerts` and `Dependabot alerts` permissions |
| `npx` not found | Install [Node.js](https://nodejs.org/) (v18 or later) and make sure `npx` is in your PATH |
### 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](https://scorecard.dev/).
**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](https://dora.dev/) 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:
```bash
MCP_TRANSPORT=http MCP_PORT=3000 node dist/index.js
```
| Env Variable | Default | Description |
| --- | --- | --- |
| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
| `MCP_PORT` | `3000` | HTTP server port (only used when `MCP_TRANSPORT=http`) |
**Docker example:**
```yaml
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](https://dora.dev/) from public GitHub data:
| Metric | Source | Unit |
| --- | --- | --- |
| Deployment Frequency | Releases | releases/week |
| Lead Time for Changes | PR created โ merged | hours (median) |
| Change Failure Rate | CI workflow conclusions | percentage |
| Mean Time to Recovery | CI failure โ next success | hours (median) |
Metrics return `null` when insufficient data is available โ works safely on any repository.
## ๐ Compatibility
ProjectPulse works with any MCP-compatible client. Tested with:
| Client | Transport | Status |
| --- | --- | --- |
| [Claude Desktop](https://claude.ai/download) | stdio | โ
Tested |
| [Claude Code (CLI)](https://docs.anthropic.com/en/docs/claude-code) | stdio | โ
Tested |
| [Cursor](https://cursor.sh/) | stdio | โ
Tested |
| [Windsurf](https://codeium.com/windsurf) | stdio | โ
Tested |
| [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) | stdio | โ
Tested |
| Docker / Remote | HTTP | โ
Tested |
| Any MCP client | stdio or HTTP | โ
Compatible |
## ๐๏ธ 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
| | stdio (default) | HTTP |
| --- | --- | --- |
| **Activation** | `npx projectpulse-mcp` | `MCP_TRANSPORT=http node dist/index.js` |
| **Best for** | Local MCP clients | Docker, remote, cross-runtime |
| **Health check** | N/A | `GET /` โ JSON |
| **MCP endpoint** | stdin/stdout | `POST /mcp` |
| **Config needed** | None | `MCP_TRANSPORT=http`, optionally `MCP_PORT` |
See [What's New: HTTP Transport](#http-transport-v170) 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:
```env
GITHUB_TOKEN=ghp_your_token_here
```
## ๐งช Testing
All 8 tools have dedicated test suites. Tests use [Vitest](https://vitest.dev/) with mocked GitHub API responses.
```bash
# Run all tests
npm test
# Watch mode
npm run test:watch
```
| Tool | Test file | Status |
| --- | --- | --- |
| `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` | โ
|
## ๐ค Author
**alexbypa** โ [GitHub](https://github.com/alexbypa) ยท [npm](https://www.npmjs.com/~alexbypa)
## ๐ค 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](https://github.com/alexbypa/github-projectpulse-mcp/issues) for open tasks and bug reports.
## โญ Show your support
Give a star if this project helped you!
## ๐ License
MIT โ see the [LICENSE](LICENSE) file for details.