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

Related MCP server: pkgtruth

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 <score>, 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": []
}

A deprecated package is capped at 10 even when its downloads are still growing: popularity does not mean anyone is fixing it.

A GitHub repository is scored the same way, with its latest GitHub release as the version. There are no download statistics for a repository, so that signal is left out:

expressjs/express: 98/100 (A), healthy.

scan_manifest

Score every dependency in a manifest or lock file and list the riskiest first.

Pass path for lock files: they are often too large to paste into a tool call.

Supported formats:

Lock files include transitive dependencies, so they often list several hundred packages. Raise max_packages, and set a GitHub token.

Example response header:

Scanned 5 package(s). Grades: A=2, B=1, F=2. Needs attention: request (10), left-pad (10).

followed by { scanned, total_dependencies, grades, packages: [...] }, with each package in a compact form (score, grade, confidence, risks, signals, repository).

compare_packages

Rank 2–5 alternatives from the same registry, or GitHub repositories.

Healthiest: axios (92/100, A). Ranking: axios 92 > got 86 > request 10

followed by { ranking: [...] } in the same compact form.

Using it with an AI agent

Once the server is connected, ask in plain language. Some prompts that work well:

• "Before you add a date library, compare dayjs, date-fns and luxon with pkg-health."

• "Scan this project's package.json and tell me which dependencies look abandoned."

• "Is the nose package still maintained? If not, what should I migrate to?"

• "Is github.com/some-org/some-tool still alive? I want to vendor it."

• "Scan package-lock.json, including transitive dependencies, and list everything graded F."

• "Check every package in requirements.txt and make a checklist of the ones graded D or F."

To make it automatic, add a line to your project instructions (CLAUDE.md, .cursorrules, Copilot instructions…):

Before adding a new npm or PyPI dependency, call the pkg-health `check_package` tool.
Do not add packages graded D or F without asking me first, and mention any risks it reports.

Command line

The same engine runs without an MCP client.

# Score one or more npm packages
npx -y pkg-health-mcp check express lodash

# PyPI packages
npx -y pkg-health-mcp check requests flask --pypi

# Any GitHub repository (owner/repo or URL)
npx -y pkg-health-mcp check expressjs/express https://github.com/pallets/flask

# Every dependency in a manifest, worst first
npx -y pkg-health-mcp scan ./package.json
npx -y pkg-health-mcp scan ./pyproject.toml --dev

# Transitive dependencies from a lock file
npx -y pkg-health-mcp scan ./package-lock.json
npx -y pkg-health-mcp scan ./uv.lock --max 300

# Fail (exit code 1) if anything scores below 50
npx -y pkg-health-mcp scan ./package.json --fail-under 50

# Machine-readable or Markdown output
npx -y pkg-health-mcp check express --json
npx -y pkg-health-mcp scan ./package.json --markdown >> "$GITHUB_STEP_SUMMARY"

In the human-readable output, ! marks a risk and ~ a data warning. Exit codes: 0 success, 1 a package fell below --fail-under (or an error), 2 invalid arguments.

Cache

API responses are cached on disk for 12 hours in ~/.cache/pkg-health-mcp (or $XDG_CACHE_HOME/pkg-health-mcp), shared by the CLI and the MCP server. Only successful responses and 404s are cached.

GitHub Action

Add a dependency health report to every pull request, and optionally fail the job:

name: Dependency health
on: [pull_request]

jobs:
  pkg-health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: orcsnren/pkg-health-mcp@v0.2.0
        with:
          manifest: package-lock.json   # or package.json, yarn.lock, pnpm-lock.yaml, requirements.txt, poetry.lock, uv.lock …
          fail-under: 40                # leave out to report without failing
          max-packages: 300

The table of results is written to the job summary. Without the Action, the CLI does the same in any CI system:

- name: Dependency health
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: npx -y pkg-health-mcp scan package.json --fail-under 40 --markdown >> "$GITHUB_STEP_SUMMARY"

How the score works

Six signals are scored from 0 to 100 and combined with these weights:

• Signals without data are left out and the remaining weights are rescaled. confidence reports how much of the weight was backed by data.

• Hard caps: deprecated packages score at most 10, archived repositories at most 15.

• Grades: A ≥ 80, B ≥ 65, C ≥ 50, D ≥ 35, F below 35.

Every threshold, edge case and known blind spot is documented in docs/scoring.md.

Data sources

All public, no authentication required.

Responses are cached in memory for one hour and on disk for 12 hours (see Cache), and at most four packages are analysed at a time.

Limitations

• Maintenance, not security. This does not look for known vulnerabilities. Pair it with npm audit, pip-audit or OSV.

• "Done" is not "dead". A small, feature-complete utility can be safe with no commits for years. The score will flag it anyway; read the risks before acting.

• Repository data comes from GitHub. Packages hosted on GitLab, Codeberg or self-hosted forges are scored from registry data, with lower confidence.

• Monorepos share their activity with every package published from them.

• Large lock files are slow on a cold cache. A lock file with 800 packages needs a few thousand API calls the first time. Use a token and --max, or let the cache warm up.

• Maintainer responses are attributed by GitHub role. Only replies from owners, organization members and collaborators count. Projects triaged by community members can look less responsive than they are.

FAQ

Does it send my code or manifest anywhere? No. Only package names leave your machine, as part of the public API URLs listed above. See SECURITY.md.

Do I need the MCP server at all? No. The CLI and the GitHub Action use the same engine. The MCP server is what lets an AI agent check a package before it suggests one, which is where abandoned dependencies usually come from.

Why did a package I know is fine get a low score? Look at risks and subscores; they say exactly which signal pulled it down. If the score is still wrong, please open a "wrong score" issue. Those reports are how the thresholds get tuned.

What does confidence mean? The share of the scoring weight that was backed by real data. 1.0 means all six signals were available. Below 0.6 the summary says "low confidence".

How is this different from OpenSSF Scorecard, deps.dev or Socket? Scorecard grades a repository's security practices; this tool uses it as one input. deps.dev and Socket are excellent websites and services. pkg-health-mcp focuses on one question, is this still maintained?, and makes the answer available inside AI agents as a tool call, with a single explainable score across ecosystems.

Can I use it commercially? Yes. It is licensed under Apache 2.0.

Development

Requires Node.js 22+ for the test runner.

git clone https://github.com/orcsnren/pkg-health-mcp
cd pkg-health-mcp
npm install       # also builds dist/
npm test          # offline unit tests
npm run typecheck
node dist/index.js check express

Try the tools interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Project layout:

src/
├── index.ts          CLI entry point; starts the MCP server when run without arguments
├── server.ts         MCP tool definitions
├── analyze.ts        Gathers facts for a package from all sources
├── score.ts          Pure scoring functions
├── manifest.ts       Manifest and lock file parsing
├── http.ts           fetch with timeout, memory + disk cache and concurrency limit
├── types.ts
└── sources/
    ├── npm.ts        Registry metadata and download statistics
    ├── pypi.ts       PyPI JSON API and pypistats
    ├── github.ts     Repository, commits, issues, releases, first responses (GraphQL)
    ├── scorecard.ts  OpenSSF Scorecard via deps.dev
    └── repo-url.ts   Normalizes the many shapes of repository URLs
docs/
├── scoring.md        Full scoring methodology
└── architecture.md   How the pieces fit together, and how to add an ecosystem
examples/             Client configurations and sample manifests

Contributing

Bug reports, scoring feedback and pull requests are welcome. If a package you know well gets a grade that feels wrong, a wrong score report is the most useful thing you can send. New ecosystems (Maven Central, Go modules, crates.io, RubyGems) and repository hosts are good first contributions; docs/architecture.md lists the steps.

See CONTRIBUTING.md for the development setup and guidelines.

License

Apache License 2.0