io.github.liminalpepe/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 — GET /repo-health/:owner/:repo, $0.01 USDC on Base per call via the x402 payment protocol, 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

npx x402-repohealth-mcp

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

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

Tool: check_repo_health

Input:

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

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

{
  "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

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