pkg-health-mcp

# pkg-health-mcp

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

[![CI](https://github.com/orcsnren/pkg-health-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/orcsnren/pkg-health-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/pkg-health-mcp)](https://www.npmjs.com/package/pkg-health-mcp)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)

`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](https://securityscorecards.dev) 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.

```console
$ 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](#why)
- [Features](#features)
- [Quick start](#quick-start)
- [GitHub token](#github-token)
- [Tools](#tools)
- [Using it with an AI agent](#using-it-with-an-ai-agent)
- [Command line](#command-line)
- [GitHub Action](#github-action)
- [How the score works](#how-the-score-works)
- [Data sources](#data-sources)
- [Limitations](#limitations)
- [FAQ](#faq)
- [Development](#development)
- [Contributing](#contributing)
- [License](#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 <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

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

```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](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](examples/vscode-mcp.json).

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

```bash
npx -y pkg-health-mcp
```

## GitHub token

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

| | Without token | With token |
| --- | --- | --- |
| GitHub API limit | 60 requests/hour | 5,000 requests/hour |
| Packages per hour (≈3–5 GitHub calls each) | about 15 | about 1,000+ |
| Time to first maintainer response | not measured (needs GraphQL) | measured |

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](https://github.com/settings/personal-access-tokens/new) → *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.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string | — | Package name (`express`, `@types/node`, `requests`) or GitHub repository (`owner/repo` or a `github.com` URL) |
| `ecosystem` | `"npm"` \| `"pypi"` \| `"github"` | `"npm"` | Where to look. `owner/repo` and GitHub URLs are detected automatically |

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

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

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