<h1 align="center">ProjectPulse MCP 🏥</h1>

<p align="center">
  <em>GitHub repository health monitoring for AI assistants — works with any language, any repo.</em>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/projectpulse-mcp"><img src="https://img.shields.io/npm/v/projectpulse-mcp.svg?color=blue" alt="npm version" /></a>
  <a href="https://github.com/alexbypa/github-projectpulse-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/alexbypa/github-projectpulse-mcp" alt="license" /></a>
  <a href="https://github.com/alexbypa/github-projectpulse-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/alexbypa/github-projectpulse-mcp/ci.yml?label=tests" alt="tests" /></a>
  <a href="https://github.com/alexbypa/github-projectpulse-mcp/stargazers"><img src="https://img.shields.io/github/stars/alexbypa/github-projectpulse-mcp" alt="stars" /></a>
  <a href="https://www.npmjs.com/package/projectpulse-mcp"><img src="https://img.shields.io/npm/dt/projectpulse-mcp" alt="downloads" /></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/alexbypa/github-projectpulse-mcp"><img src="https://img.shields.io/ossf-scorecard/github.com/alexbypa/github-projectpulse-mcp?label=openssf+scorecard" alt="OpenSSF Scorecard" /></a>
  <a href="https://m8ven.ai/badge/mcp/alexbypa/github-projectpulse-mcp"><img src="https://m8ven.ai/badge/mcp/alexbypa/github-projectpulse-mcp" alt="M8ven MCP" /></a>
</p>

---

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).

<details open>
<summary><strong>get_health_score</strong> — A-F grade with category breakdown</summary>

![get_health_score](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/get_health_score_Use_Case.png)
</details>

<details>
<summary><strong>get_dora_metrics</strong> — DORA delivery metrics from GitHub data</summary>

![get_dora_metrics](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/get_dora_metrics_Use_Case.png)
</details>

<details>
<summary><strong>compare_repos</strong> — Side-by-side health score ranking</summary>

![compare_repos](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/compare_repos_Use_Case.png)
</details>

<details>
<summary><strong>check_ci_status</strong> — Recent GitHub Actions workflow runs</summary>

![check_ci_status](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/check_ci_status_Use_Case.png)
</details>

<details>
<summary><strong>get_repo_health</strong> — Repository metadata and stats</summary>

![get_repo_health](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/get_repo_health_Use_Case.png)
</details>

<details>
<summary><strong>analyze_dependencies</strong> — Dependabot vulnerability alerts</summary>

![analyze_dependencies](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/analyze_dependencies_Use_Case.png)
</details>

<details>
<summary><strong>check_best_practices</strong> — Open-source repo quality checklist with A-F grade</summary>

![check_best_practices](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/check_best_practices_Use_Case.png)
</details>

## 💡 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.