Package Health

pkg-health-mcp

这个依赖还在维护吗？安装前先查清楚。

pkg-health-mcp 会从 0 到 100 为 npm 包、PyPI 包和 GitHub 仓库评估维护状况。它综合考量版本发布和提交活动、活跃维护者、问题响应时间、下载趋势、OpenSSF Scorecard 和许可证，给出 A–F 等级以及通俗易懂的风险列表。

它提供三种用法，均基于同一套引擎：

• MCP 服务，适用于 Claude Code、Claude Desktop、Cursor、VS Code 和任何其他 MCP 客户端，让你的 AI Agent 在推荐包之前先进行检查。
• 命令行工具，用于审查清单或锁定文件，包括传递依赖。
• GitHub Action，为每个拉取请求添加健康报告，并在评分低于阈值时让构建失败。

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

F   10/100  [email protected]  [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  [email protected]  [npm]
     !  Deprecated: use String.prototype.padStart()
     !  Source repository is archived

A   99/100  [email protected]  [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)

---

目录

• 为什么需要
• 功能
• 快速开始
• GitHub 令牌
• 工具
• 与 AI Agent 配合使用
• 命令行
• GitHub Action
• 评分原理
• 数据来源
• 局限性
• 常见问题
• 开发
• 贡献
• 许可证

为什么需要

一个典型的项目会引入数百个开源包。其中有些包悄然被弃用：多年没有发布新版本，唯一的维护者已经离开，问题堆积如山却无人回应。一旦其中某个包出现漏洞，就没人会来修复。

手动检查意味着要打开每个包的 GitHub 页面，查看提交日期、问题列表和贡献者图表。没人会为每个依赖都这样做，AI 编码助手更不会：它们会欣然推荐训练数据中曾经流行的任何库，包括多年前就已弃用的库。

pkg-health-mcp 将这项检查简化为一次工具调用，因此：

• AI Agent 可以避免推荐已被弃用的库，并标记现有代码中的高风险库。
• 工程负责人 可以在几秒内审查项目依赖。
• 安全与合规团队 可以获得可重复、可解释的维护状况信号，并将其与漏洞扫描器的结果一同使用。

功能

• **三种 MCP 工具：**为单个包评分、扫描整个清单，或比较替代方案。
• **npm、PyPI 和任意 GitHub 仓库。**传入 owner/repo 或 GitHub URL，即可为未发布到注册表的项目评分。
• 清单和锁文件：package.json、requirements.txt、pyproject.toml（PEP 621 和 Poetry），以及用于检查传递依赖的 package-lock.json、yarn.lock、pnpm-lock.yaml、poetry.lock 和 uv.lock。GitHub 上的 Git 依赖会按仓库评分。
• **六项指标：**最近一次发布和提交时间、活跃提交者、维护者首次响应时间、下载趋势、OpenSSF Scorecard、许可证。
• CI 门禁：--fail-under <score>、用于作业摘要的 Markdown 输出，以及开箱即用的 GitHub Action。
• 跨运行共享的磁盘缓存（默认 12 小时），因此重复扫描几乎不会产生 API 调用。
• **结果可解释：**每个评分都附带各项指标的详情和具体风险列表，而不只是一个数字。
• **如实说明数据缺失：**无法访问的 API 会降低 confidence 值，而不是影响评分。
• **无需账户或 API 密钥。**可选的 GITHUB_TOKEN 可提高 GitHub 的速率限制。
• **本地运行且保护隐私：**在你的机器上运行，直接访问公共 API；没有后端，也不会收集遥测数据。
• 支持人类可读、JSON 和 Markdown 输出，适用于终端、脚本和 CI 作业摘要。

快速开始

需要 Node.js 20 或更高版本。无需全局安装：npx 会在首次运行时下载此包。

Claude Code

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

不提供 -e GITHUB_TOKEN=… 即可在不使用令牌的情况下运行。

Claude Desktop

打开设置 → 开发者 → 编辑配置，或直接编辑文件：

• 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" }
    }
  }
}

重启 Claude Desktop。三个工具会显示在工具图标下方。

Cursor

将相同代码块添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。参见 examples/cursor-mcp.json。

VS Code

添加到 .vscode/mcp.json。服务器首次启动时，VS Code 会提示输入令牌，因此令牌不会保存在文件中。参见 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}" }
    }
  }
}

其他 MCP 客户端

此服务通过 stdio 使用 MCP 通信。使用以下命令启动：

npx -y pkg-health-mcp

GitHub 令牌

令牌为可选项，但如果要检查的包不止少数几个，强烈建议使用。

	不使用令牌	使用令牌
GitHub API 限额	每小时 60 次请求	每小时 5,000 次请求
每小时可检查的包数（每个约需 3–5 次 GitHub 调用）	约 15 个	约 1,000 个以上
维护者首次响应时间	不测量（需要 GraphQL）	测量

达到限额后，仍会根据注册表数据为包评分，报告也会包含相应警告。响应会缓存在磁盘上，因此在 12 小时内再次扫描同一项目时，不会发出任何 GitHub 调用。

**创建令牌：**GitHub → Settings → Developer settings → Fine-grained tokens → Public repositories (read-only)，无需其他权限。令牌只会发送到 api.github.com。也支持 GH_TOKEN。

工具

所有工具均为只读，并带有相应注解（readOnlyHint、idempotentHint），因此客户端可以直接运行，无需请求确认。

check_package

评估一个软件包。

参数	类型	默认值	描述
name	string	—	软件包名称（express、@types/node、requests）或 GitHub 仓库（owner/repo 或 github.com URL）
ecosystem	"npm" | "pypi" | "github"	"npm"	要查询的位置。系统会自动检测 owner/repo 和 GitHub URL

返回一行摘要，后跟完整报告：

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

即使下载量仍在增长，已弃用的软件包最高也只能得 10 分：受欢迎并不意味着有人在维护它。

GitHub 仓库也采用相同方式评分，版本使用其最新的 GitHub release。仓库没有下载统计数据，因此不纳入这一项信号：

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

scan_manifest

评估清单文件或锁定文件中的每个依赖项，并按风险从高到低列出。

参数	类型	默认值	描述
path	string	—	本地清单文件或锁定文件的路径。仅接受下方列出的文件名
content	string	—	文件的完整文本；未传入 path 时使用
filename	string	—	可选，与 content 一起使用；用于检测格式。否则使用内容嗅探
include_dev	boolean	false	同时评估 devDependencies / 可选依赖项
max_packages	integer	50	评估软件包数量的上限（1–1000）

锁定文件通常太大，不适合粘贴到工具调用中，因此请传入 path。

支持的格式：

文件	读取内容	跳过内容
package.json	dependencies、peerDependencies、optionalDependencies、devDependencies（使用 include_dev 时）、npm: 别名、GitHub 规格（owner/repo、github:）	file:、link:、workspace:、非 GitHub 的 git 和 URL 规格
requirements*.txt、requirements*.in	带 extras、版本规格符和环境标记的软件包名称；git+https://github.com/… URL	-r、--index-url 和其他选项、其他 URL、本地路径
pyproject.toml	PEP 621 [project] dependencies 和 optional-dependencies；Poetry [tool.poetry.dependencies] 和开发组	python 本身
package-lock.json、npm-shrinkwrap.json	所有已安装的软件包（lockfile v1、v2、v3），以及 dev 标记	链接的工作区、捆绑的软件包
yarn.lock	所有条目（Yarn 1 和 Berry）、npm: 别名、补丁	工作区、file:、link:、portal:。Yarn 不会记录仅用于开发的软件包
pnpm-lock.yaml	packages: 部分（lockfile v5、v6、v9），以及有记录时的 dev 标记	本地依赖和 tarball 依赖
poetry.lock、uv.lock	每个 [[package]]、Poetry 的 category = "dev"	项目本身、可编辑、路径和 URL 源

锁定文件包含传递依赖，因此通常会列出数百个软件包。请提高 max_packages，并设置 GitHub token。

响应标头示例：

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

后跟 { scanned, total_dependencies, grades, packages: [...] }，其中每个软件包都以紧凑形式呈现（score、grade、confidence、risks、signals、repository）。

compare_packages

对来自同一注册表的 2–5 个替代项或 GitHub 仓库进行排名。

参数	类型	默认值	描述
packages	string[]	—	2 到 5 个软件包名称或 owner/repo 仓库
ecosystem	"npm" | "pypi" | "github"	"npm"	要查询的位置

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

后跟 { ranking: [...] }，格式相同，为紧凑形式。

与 AI Agent 搭配使用

连接服务后，使用自然语言提问。以下提示词效果不错：

• "在添加日期库之前，用 pkg-health 比较 dayjs、date-fns 和 luxon。"
• "扫描此项目的 package.json，告诉我哪些依赖似乎已无人维护。"
• "nose 包还在维护吗？如果没有，我应该迁移到哪个包？"
• "github.com/some-org/some-tool 还在活跃维护吗？我想将它引入项目。"
• "扫描 package-lock.json，包括传递依赖，并列出所有评级为 F 的依赖。"
• "检查 requirements.txt 中的每个包，并列出评级为 D 或 F 的包，制作一份清单。"

要实现自动化，请在项目说明文件（CLAUDE.md、.cursorrules、Copilot 说明文件……）中添加一行：

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.

命令行

同一套引擎也可以在没有 MCP 客户端的情况下运行。

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

命令 / 标志	说明
(无参数)	通过 stdio 启动 MCP 服务
check <name...>	对包（除非使用 --pypi，否则按 npm 包处理）或 GitHub 仓库（owner/repo、URL）进行评分
scan <file>	对清单文件或锁定文件中的所有依赖进行评分
--pypi	将 check 参数视为 PyPI 包
--github	将 check 参数视为 GitHub 仓库（仅在输入格式特殊时需要）
--dev	在 scan 中包含开发依赖和可选依赖
--max <n>	在 scan 中最多对 n 个包进行评分
--fail-under <n>	如果任何包的评分低于 n，则以代码 1 退出。无法评分的包不会导致运行失败，但会计入消息中的数量
--json	以 JSON 格式打印完整报告
--markdown	打印 Markdown 表格，例如用于 $GITHUB_STEP_SUMMARY
--no-cache	本次运行不使用磁盘缓存
--help、--version

在人类可读的输出中，! 表示风险，~ 表示数据警告。退出代码：0 表示成功，1 表示某个包的评分低于 --fail-under（或发生错误），2 表示参数无效。

缓存

API 响应会在磁盘上缓存 12 小时，缓存位置为 ~/.cache/pkg-health-mcp（或 $XDG_CACHE_HOME/pkg-health-mcp），CLI 和 MCP 服务共用缓存。仅缓存成功的响应和 404 响应。

变量	默认值	说明
PKG_HEALTH_CACHE_DIR	~/.cache/pkg-health-mcp	缓存位置。设为 off 可禁用磁盘缓存
PKG_HEALTH_CACHE_TTL_HOURS	12	缓存响应的复用时长

GitHub Action

为每个拉取请求添加依赖健康报告，还可以选择让任务失败：

name: Dependency health
on: [pull_request]

jobs:
  pkg-health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: orcsnren/[email protected]
        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

输入项	默认值	说明
manifest	package.json	要扫描的文件
fail-under	(空)	如果任何依赖的评分低于此值，则任务失败
include-dev	false	同时对开发依赖进行评分
max-packages	(空)	最多对这么多个包进行评分
github-token	${{ github.token }}	用于调用 GitHub API 的令牌

结果表格会写入任务摘要。如果不使用 Action，CLI 也可以在任何 CI 系统中执行相同操作：

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

评分机制

六项信号的评分范围为 0 到 100，并按以下权重合并：

信号	权重	衡量内容
近期活动	30%	距离最近一次发布或提交的天数，以时间较近者为准
维护者多样性	20%	过去 12 个月内提交代码的独立人员数量（巴士系数）
问题响应速度	15%	维护者首次响应的中位时间（响应内容中包含令牌），否则为关闭问题的中位时间
下载趋势	15%	过去 90 天的下载量与此前 90 天的对比
OpenSSF Scorecard	10%	独立的安全实践评分
许可证	10%	宽松型、著作权传染型、专有型或缺失

• 没有数据的信号会被排除，并按比例重新调整其余权重。confidence 表示有数据支持的权重占比。
• **硬性上限：**已弃用的软件包最高得分为 10，已归档的仓库最高得分为 15。
• **等级：**A ≥ 80，B ≥ 65，C ≥ 50，D ≥ 35，F 低于 35。

所有阈值、边缘情况和已知盲点均记录在 docs/scoring.md 中。

数据来源

所有数据均为公开数据，无需身份验证。

数据	来源	说明
npm 元数据	registry.npmjs.org	最新版本、发布日期、弃用状态、许可证、维护者、仓库
npm 下载量	api.npmjs.org/downloads/range/last-year	每日下载量，使用最近 180 天的数据
PyPI 元数据	pypi.org/pypi/<name>/json	版本、上传时间、许可证、分类器、项目 URL
PyPI 下载量	pypistats.org	不含镜像站的每日下载量（保留约 180 天）
仓库活动	api.github.com（REST）	归档标记、许可证、最新发布、过去 12 个月的提交、最近关闭的问题
维护者首次响应	api.github.com/graphql	最近 60 个问题的评论；需要令牌
OpenSSF Scorecard	api.deps.dev	仓库的 Scorecard 总体结果

响应会在内存中缓存一小时，并在磁盘上缓存 12 小时（见 缓存），且一次最多分析四个软件包。

局限性

• 评估维护情况，而非安全性。 此工具不会查找已知漏洞。请结合使用 npm audit、pip-audit 或 OSV。
• “完成”不等于“停滞”。 小型且功能完备的工具即使多年没有提交，也可能很安全。评分仍会标记它；采取行动前请先阅读相关风险。
• 仓库数据来自 GitHub。 托管在 GitLab、Codeberg 或自托管代码托管平台上的软件包会根据注册表数据评分，置信度较低。
• 单体仓库的活动数据会由其中发布的每个软件包共享。
• 缓存未命中时，大型锁文件处理较慢。 包含 800 个软件包的锁文件首次处理时需要调用数千次 API。请使用令牌和 --max，或等待缓存预热。
• 维护者响应根据 GitHub 角色归属。 只有所有者、组织成员和协作者的回复才会计入。由社区成员进行问题分类的项目，其响应速度可能看起来比实际情况慢。

常见问题

它会把我的代码或清单发送到其他地方吗？ 不会。只有软件包名称会离开你的计算机，作为上文所列公共 API URL 的一部分。请参阅 SECURITY.md。

我一定要使用 MCP 服务吗？ 不需要。CLI 和 GitHub Action 使用相同的引擎。MCP 服务能让 AI Agent 在建议软件包之前先检查它，而已弃用的依赖项通常就是从这里引入的。

为什么我知道没问题的软件包却得分很低？ 查看 risks 和 subscores，它们会准确说明是哪个信号拉低了分数。如果分数仍然不对，请提交“分数错误”问题。这些报告有助于调整阈值。

confidence 是什么意思？ 它表示有实际数据支撑的评分权重占比。1.0 表示六项信号都有数据。低于 0.6 时，摘要会显示“低置信度”。

这与 OpenSSF Scorecard、deps.dev 或 Socket 有什么不同？ Scorecard 对代码仓库的安全实践进行评级；此工具将其作为一项输入。deps.dev 和 Socket 都是很出色的网站和服务。pkg-health-mcp 专注于一个问题：这个软件包仍在维护吗？ 它通过工具调用在 AI Agent 中提供答案，并在不同生态系统间使用一个可解释的统一评分。

我可以将它用于商业用途吗？ 可以。它采用 Apache 2.0 许可证。

开发

测试运行器需要 Node.js 22+。

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

使用 MCP Inspector 交互式试用这些工具：

npx @modelcontextprotocol/inspector node dist/index.js

项目结构：

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

贡献

欢迎提交错误报告、评分反馈和拉取请求。如果你熟悉的某个软件包得分看起来不对，报告分数错误是最有帮助的反馈。新增生态系统（Maven Central、Go modules、crates.io、RubyGems）和代码仓库托管平台都是很好的入门贡献；docs/architecture.md 列出了具体步骤。

开发环境设置和指南请参阅 CONTRIBUTING.md。

许可证

Apache License 2.0