x402-repohealth-mcp

# x402-repohealth-mcp

A free MCP (Model Context Protocol) server that computes a **GitHub repo
maintenance/abandonment health score** from live GitHub data: is a repo
actively maintained, slowing down, likely abandoned, or archived? No API
key, no payment, no rate-limit games — just an MCP tool any MCP client can
call.

This is the **open funnel twin** of a paid, x402-gated HTTP API:

**[x402-repohealth-poc.theliminalguy.workers.dev](https://x402-repohealth-poc.theliminalguy.workers.dev)**
— `GET /repo-health/:owner/:repo`, $0.01 USDC on Base per call via the
[x402 payment protocol](https://x402.org), for production/high-volume or
non-MCP (plain HTTP) / agent-automated use. Same scoring logic, same
output, just billed per call instead of free-via-MCP.

## Why this exists

Agents that pick dependencies, tools, or libraries need to know whether a
repo is safe to depend on — actively maintained vs. slowing down vs.
effectively dead — and GitHub's own API only gives raw signals (commits,
issues, releases), not the *decision* computed from them. This MCP server
is the free/local half of filling that gap — try it for nothing via MCP;
reach for the paid HTTP endpoint when you need it at volume or outside an
MCP client.

## What it does

One tool, `check_repo_health`, takes a GitHub `owner` + `repo` and computes
a **0-100 health score** across four weighted dimensions (commit recency,
commit activity, issue/PR responsiveness, release cadence, each 0-25
points), plus a verdict:

- `archived` — GitHub's own `archived` flag is true (overrides the score)
- `actively maintained` — score >= 75
- `slowing down` — score 45-74
- `likely abandoned` — score < 45

The response includes the full score breakdown, computed metrics (days
since last commit, commits in last 90 days, issue close ratio, etc.), and a
human-readable `reasoning` array built from the actual numbers — nothing is
hardcoded per-repo, it's fetched from GitHub's real public REST API and
scored at call time.

## Install & run

```bash
npx x402-repohealth-mcp
```

Or add it to an MCP client config (e.g. Claude Desktop's
`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "repohealth": {
      "command": "npx",
      "args": ["-y", "x402-repohealth-mcp"]
    }
  }
}
```

## Tool: `check_repo_health`

Input:

```jsonc
{
  "owner": "facebook",
  "repo": "react"
}
```

Output (MCP tool text content, JSON-stringified):

```jsonc
{
  "owner": "facebook",
  "repo": "react",
  "fetchedAt": "2026-08-01T22:00:00.000Z",
  "repoMeta": { "fullName": "facebook/react", "archived": false, "stargazersCount": 230000, "...": "..." },
  "metrics": { "daysSinceLastCommit": 1, "commitsLast90Days": 100, "...": "..." },
  "scoreBreakdown": { "commitRecency": 25, "commitActivity": 25, "issueResponsiveness": 17, "releaseCadence": 17 },
  "score": 84,
  "verdict": "actively maintained",
  "reasoning": [
    "Last commit 1 day ago (2026-07-31T...).",
    "100+ commits in the last 90 days.",
    "..."
  ]
}
```

## Scoring detail

| Dimension | Points | Logic |
|---|---|---|
| Commit recency | 0-25 | Days since last commit: <=14d->25, <=30d->21, <=90d->15, <=180d->9, <=365d->4, else 0 |
| Commit activity | 0-25 | Commits in trailing 90 days: 0->0, 1-2->6, 3-9->13, 10-29->20, 30+->25 |
| Issue/PR responsiveness | 0-25 | Of issues/PRs updated in the last 90 days: closed-ratio >=0.6 & median close <=14d->25, >=0.4->17, >=0.15->9, else->3. No recent activity -> neutral 14 |
| Release cadence | 0-25 | Days since latest tagged release: <=180d->25, <=365d->17, <=730d->9, else 3. No releases ever -> neutral 12 |

`archived: true` from GitHub overrides the score-derived verdict entirely —
an archived repo is confirmed dead by the maintainer's own action, not
merely "likely abandoned."

## What's real vs. limited

- **Real:** every GitHub API call, the scoring math, and the MCP tool
  response are computed live at call time from that repo's actual GitHub
  data — nothing is hardcoded or mocked.
- **No auth against GitHub:** uses GitHub's unauthenticated public REST API
  (60 requests/hour/IP shared across whoever runs this MCP server locally).
  A `check_repo_health` call costs ~3-4 GitHub requests. Fine for
  free/local/low-volume MCP use; the paid Worker adds a `GITHUB_TOKEN`
  (5,000 req/hr) server-side.
- **No caching:** every call re-fetches GitHub live.

## Local development

```bash
npm install
npm run dev              # runs src/index.ts directly on stdio via tsx
npm run build             # compiles to dist/ for the published npm package
npm run test:health       # calls getRepoHealth() directly against real repos, no MCP transport
```

`src/github.ts`, `src/score.ts`, `src/health.ts`, and `src/types.ts` are
the same GitHub-fetch + scoring logic as the paid Worker — this MCP server
is a thin `src/index.ts` wrapper around `getRepoHealth()`.

## When to use the paid HTTP twin instead

Use [`GET /repo-health/:owner/:repo`](https://x402-repohealth-poc.theliminalguy.workers.dev)
on the paid Worker instead of this MCP server when:

- You're calling from outside an MCP client (plain HTTP, any language).
- You need production/high-volume use and want to pay per call rather than
  share this MCP server's unauthenticated 60 req/hr GitHub budget.
- Your agent already speaks x402 (e.g. via `x402-fetch` / `x402-axios`) and
  can pay $0.01 USDC on Base per request.

Both routes call the exact same scoring function — output is identical.

## License

MIT