pkg-health-mcp

pkg-health-mcp

Is this dependency still maintained? Find out before you install it.

pkg-health-mcp scores npm packages, PyPI packages and GitHub repositories from 0 to 100 for maintenance health. It combines release and commit activity, active maintainers, issue response times, download trends, OpenSSF Scorecard and license into an A–F grade and a plain-language list of risks.

Use it three ways, all built on the same engine:

• MCP server for Claude Code, Claude Desktop, Cursor, VS Code and any other MCP client, so your AI agent checks a package before it suggests one.

• CLI to audit a manifest or lock file, including transitive dependencies.

• GitHub Action to add a health report to every pull request and fail the build below a threshold.

$ npx -y pkg-health-mcp scan package.json

F   10/100  request@2.88.2  [npm]
      10  Recent activity        last release 2444d ago
       5  Maintainer diversity   0 active committer(s) in the last 12 months
      10  Issue responsiveness   median 113.2d to first maintainer response, 38% answered (8 issues)
      65  Download trend         171.5M downloads in last 90d (-5% vs previous 90d)
      34  OpenSSF Scorecard      3.4/10
     100  License                Apache-2.0 (permissive)
     !  Deprecated: request has been deprecated, see https://github.com/request/request/issues/3142
     !  No release in 6+ years
     !  No commits in the last 12 months
     !  62% of recent issues got no maintainer response

F   10/100  left-pad@1.3.0  [npm]
     !  Deprecated: use String.prototype.padStart()
     !  Source repository is archived

A   99/100  express@5.3.0  [npm]
     100  Recent activity        last release 12d ago, last commit 4d ago
     100  Maintainer diversity   42 active committer(s) in the last 12 months
     100  Issue responsiveness   median 0.2d to first maintainer response, 87% answered (53 issues)
     100  Download trend         1.6B downloads in last 90d (+22% vs previous 90d)
      85  OpenSSF Scorecard      8.5/10
     100  License                MIT (permissive)

Contents

• Why

• Features

• Quick start

• GitHub token

• Tools

• Using it with an AI agent

• Command line

• GitHub Action

• How the score works

• Data sources

• Limitations

• FAQ

• Development

• Contributing

• License

Why

A typical project pulls in hundreds of open-source packages. Some of them are quietly abandoned: no releases for years, one maintainer who moved on, issues piling up unanswered. When a vulnerability shows up in one of those, nobody fixes it.

Checking this by hand means opening each package's GitHub page and reading commit dates, issue lists and contributor graphs. Nobody does that for every dependency, and AI coding assistants never do it: they happily suggest whatever library was popular in their training data, including ones deprecated years ago.

pkg-health-mcp makes that check a single tool call, so:

• AI agents can avoid recommending abandoned libraries and flag risky ones in existing code.

• Engineering leads can audit a project's dependencies in seconds.

• Security and compliance teams get a repeatable, explainable maintenance signal alongside vulnerability scanners.

Features

• Three MCP tools: score one package, scan a whole manifest, or compare alternatives.

• npm, PyPI and any GitHub repository. Pass owner/repo or a GitHub URL to score a project that is not published to a registry.

• Manifests and lock files: package.json, requirements.txt, pyproject.toml (PEP 621 and Poetry), plus package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock and uv.lock for transitive dependencies. Git dependencies on GitHub are scored as repositories.

• Six signals: release and commit recency, active committers, time to first maintainer response, download trend, OpenSSF Scorecard, license.

• CI gating: --fail-under, Markdown output for job summaries, and a ready-made GitHub Action.

• Disk cache shared across runs (12 hours by default), so repeated scans cost almost no API calls.

• Explainable output: every score comes with per-signal details and a list of concrete risks, not just a number.

• Honest about missing data: unreachable APIs lower a confidence value instead of the score.

• No account or API key needed. An optional GITHUB_TOKEN raises GitHub's rate limit.

• Local and private: runs on your machine, talks directly to public APIs, no backend and no telemetry.

• Human, JSON and Markdown output for terminals, scripts and CI job summaries.

Quick start

Requires Node.js 20 or later. Nothing to install globally: npx downloads the package on first run.

Claude Code

claude mcp add pkg-health -e GITHUB_TOKEN=github_pat_xxx -- npx -y pkg-health-mcp

Leave out -e GITHUB_TOKEN=… to run without a token.

Claude Desktop

Open Settings → Developer → Edit Config, or edit the file directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pkg-health": {
      "command": "npx",
      "args": ["-y", "pkg-health-mcp"],
      "env": { "GITHUB_TOKEN": "github_pat_xxx" }
    }
  }
}

Restart Claude Desktop. The three tools appear under the tools icon.

Cursor

Add the same block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). See examples/cursor-mcp.json.

VS Code

Add to .vscode/mcp.json. VS Code asks for the token the first time the server starts, so it never sits in the file. See examples/vscode-mcp.json.

{
  "inputs": [
    { "type": "promptString", "id": "github-token", "description": "GitHub token (optional)", "password": true }
  ],
  "servers": {
    "pkg-health": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pkg-health-mcp"],
      "env": { "GITHUB_TOKEN": "${input:github-token}" }
    }
  }
}

Any other MCP client

The server speaks MCP over stdio. Start it with:

npx -y pkg-health-mcp

GitHub token

The token is optional, but strongly recommended for anything beyond a handful of packages.

When the limit is hit, packages are still scored from registry data and the report includes a warning saying so. Responses are cached on disk, so a second scan of the same project within 12 hours makes no GitHub calls at all.

Creating one: GitHub → Settings → Developer settings → Fine-grained tokens → Public repositories (read-only), no additional permissions. The token is sent only to api.github.com. GH_TOKEN is accepted as well.

Tools

All tools are read-only and annotated as such (readOnlyHint, idempotentHint), so clients can run them without asking for confirmation.

check_package

Score one package.

Returns a one-line summary followed by the full report:

left-pad: 10/100 (F), likely abandoned or unsafe to adopt. Main risk: Deprecated: use String.prototype.padStart().

{
  "package": "left-pad",
  "ecosystem": "npm",
  "version": "1.3.0",
  "score": 10,
  "grade": "F",
  "confidence": 1,                // share of the scoring weight backed by real data
  "summary": "left-pad: 10/100 (F), likely abandoned or unsafe to adopt. ...",
  "risks": [
    "Deprecated: use String.prototype.padStart()",
    "Source repository is archived",
    "No release in 8+ years",
    "No commits in the last 12 months"
  ],
  "subscores": [
    { "key": "activity",    "label": "Recent activity",      "weight": 0.3,  "score": 0,   "detail": "Repository is archived (read-only)" },
    { "key": "maintainers", "label": "Maintainer diversity", "weight": 0.2,  "score": 5,   "detail": "0 active committer(s) in the last 12 months" },
    { "key": "issues",      "label": "Issue responsiveness", "weight": 0.15, "score": 15,  "detail": "No issues closed in 12 months, 10 open" },
    { "key": "downloads",   "label": "Download trend",       "weight": 0.15, "score": 100, "detail": "25.9M downloads in last 90d (+57% vs previous 90d)" },
    { "key": "scorecard",   "label": "OpenSSF Scorecard",    "weight": 0.1,  "score": 39,  "detail": "3.9/10" },
    { "key": "license",     "label": "License",              "weight": 0.1,  "score": 100, "detail": "WTFPL (permissive)" }
  ],
  "repository": "https://github.com/left-pad/left-pad",
  "warnings": []
}