Package Intel

软件包与依赖情报 API（x402）

通过 x402 支付协议，向 AI 编码 Agent 提供 npm、PyPI 和 crates.io（Rust）软件包健康状况、依赖图和漏洞数据的按次付费 API — 另提供 MCP 服务，以便 Claude Desktop/Cursor 中的 Agent 调用并自动付款。

默认通过免费的公共 facilitator 使用 Base Sepolia 测试网。切换到主网需要显式更改配置（参见切换到主网）。

端点

对上游数据源的原样转发免费：npm、PyPI、crates.io、OSV 和 deps.dev 本身均免费且无需身份验证，因此对它们的中继服务收费，定价等于零。收费的是数据整合 — 即评分。

端点	方法	价格	返回内容
/v1/package/:ecosystem/:name	GET	免费	综合快照
/v1/vulns/:ecosystem/:name	GET	免费	已知漏洞（OSV.dev）
/v1/deps/:ecosystem/:name	GET	免费	依赖图（deps.dev）
/v1/downloads/:ecosystem/:name	GET	免费	下载次数
/v1/health/:ecosystem/:name	GET	$0.01	健康/风险评分 0-100
/v1/batch	POST	$0.02	批量健康评分（≤50 个软件包）

:ecosystem 为 npm、pypi 或 crates。以下接口也免费：/healthz、/v1/sample（预置示例响应）、/.well-known/x402（发现清单）。

免费路由的速率限制为每个调用方每分钟 60 次、每天 2000 次 — Agent 循环失控可能导致我们的出口 IP 被 npm 或 OSV 封禁。付费路由不受此限制；价格本身就是限流器。超出限制时会返回 429，并附带 Retry-After。

层级、价格、说明和发现元数据均来自 src/catalog.ts — 在此处编辑后，支付中间件、速率限制器、清单和 Bazaar 声明都会保持同步。tier 是必需的判别字段，因此新增端点不会默认变为免费端点。

信任调用方地址

速率限制器按客户端 IP 计数，但服务位于 Worker 代理和隧道之后，因此每个请求看起来都来自同一个地址。代理会将真实地址作为 x-stable-ip 转发，并使用 PROXY_SECRET 签名；只有密钥匹配时，源站才会认可该地址。其他情况 — 密钥错误、没有密钥，或请求直接发往隧道主机名 — 都会共用一个计数桶。没有此签名时，调用方可以为每个请求伪造一个新地址，或绕过代理，从而不受限制地调用上游服务。

在两处设置相同的值：

# .env for the origin, plus:
npx wrangler secret put PROXY_SECRET

如果主网环境缺少此值，服务器会在启动时发出警告。

本地设置（测试网）

npm install
npm run gen-wallet

gen-wallet 会输出两组仅供测试网使用的密钥对 — 切勿向其中转入真实资产：

• 卖方 — 将其地址填入 .env 中的 PAY_TO（收款地址）。
• 买方 — 将其私钥填入 .env 中的 BUYER_PRIVATE_KEY（测试脚本用它来模拟付费 Agent）。

将 .env.example 复制为 .env 并填写这些值。然后在 faucet.circle.com 为买方领取 Base Sepolia USDC（选择 Base Sepolia；无需账户）。不需要测试网 ETH — x402 的 exact 方案使用 EIP-3009，因此买方只需在链下签名，由 facilitator 支付 Gas。

npm run dev

验证：curl http://localhost:4021/healthz → 200，以及 curl -i http://localhost:4021/v1/health/npm/express → 402，并返回支付说明。

测试支付流程

npm run test-buyer                              # GET /v1/health/npm/express (default)
npm run test-buyer -- /v1/deps/npm/express
npm run test-buyer -- /v1/batch

在 Git Bash/Windows 上，请在命令前加上 MSYS_NO_PATHCONV=1，以免开头的 / 被改写成 Windows 路径。

请求不存在的软件包会返回 404，且不会收费 — x402 中间件会在任何 4xx/5xx 响应时完全跳过结算，因此失败请求免费。

MCP 服务（Agent 如何使用它）

mcp-client/ 是一个独立的 npm 软件包（package-intel-mcp）——一个 stdio MCP 服务，在买方的机器上运行。它与此服务分开发布，因此安装时不会连带引入 Hono 和 x402 服务栈；它不会从 src/ 导入任何内容。

**它完全无需配置即可运行。**没有钱包时，它会注册四个免费工具 （package_snapshot、package_vulns、package_deps、package_downloads）。要求先准备好 有资金的钱包才能使用工具，是最大的采用障碍，因此现在这已是默认路径，而非错误。

claude mcp add package-intel -- npx -y package-intel-mcp

设置 X402_PRIVATE_KEY 后，还会注册 package_health 和 package_batch_health，它们会调用付费端点，并在收到 402 时，从该钱包签署 USDC 付款 后重试——Agent 看到的只有数据。格式错误的密钥会直接报错，而不是静默退回免费模式， 否则付费工具无故消失会让人困惑。

{
  "mcpServers": {
    "package-intel": {
      "command": "npx",
      "args": ["-y", "package-intel-mcp"],
      "env": { "X402_PRIVATE_KEY": "0x..." }
    }
  }
}

X402_PRIVATE_KEY 是Agent 运营者的钱包，需在 NETWORK 上存有 USDC。请使用 余额较低的专用钱包——它是会自动支出的热密钥。

若要从源代码运行，并连接本地服务：npm run mcp。

让 Agent 真正调用它

安装工具并不会让 Agent 主动调用它。在使用该工具的仓库的 AGENTS.md / CLAUDE.md / .cursor/rules 中添加一行说明，才能让它在每个相关任务中调用—— 这是实现持续调用的机制，而不是在注册表中列出工具。mcp-client/README.md 提供了可直接复制粘贴的内容。

GitHub Action

action.yml 会将此仓库发布为依赖项审查 Action。当拉取请求涉及 package.json、requirements*.txt 或 Cargo.toml 时，它会查询每个新增 依赖项，并在评论中列出安全公告、弃用情况、过时情况和缺失的许可证。

name: Dependency review
on:
  pull_request:
    paths: ["**/package.json", "**/requirements*.txt", "**/Cargo.toml"]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # needed: the action diffs base against head
      - uses: adam121393/package-intel@v1
        with:
          fail-on: critical     # none | low | moderate | high | critical

仅使用免费端点——无需钱包、API 密钥或注册。没有运行时依赖，因此将其加入流水线 不会带来供应链风险。

输入	默认值	用途
fail-on	none	达到此严重级别或更高级别时，使检查失败
comment	true	发布并更新拉取请求评论
github-token	${{ github.token }}	需要 pull-requests: write
api-url	托管服务	可覆盖为连接到你自己的实例

有两点值得了解。它只审查新增依赖项，不审查现有依赖项的版本升级，因此评论不会变成 让人学会直接略过的噪音。安全公告按版本范围筛选：精确固定版本会按原样检查，而版本 范围则会根据软件包的当前版本检查。这一区别很重要——不指定版本进行查询会返回所有 曾发布的安全公告，从而将已完全修复的 lodash 报告为严重问题。

无法查询的依赖项不会导致失败。上游服务中断不应阻塞无关的拉取请求。

Coinbase CDP 设置

两种不同的 CDP 凭据，很容易混淆：

凭据	用途
CDP_API_KEY_ID + CDP_API_KEY_SECRET	支付协调器——验证并结算付款
CDP_WALLET_SECRET	钱包 SDK——创建和控制由 CDP 管理的账户

接收付款只需要一个公开地址。服务绝不会持有密钥材料来收款—— CDP_WALLET_SECRET 仅供 npm run cdp-wallet 使用。

# 1. Add CDP_API_KEY_ID + CDP_API_KEY_SECRET to .env, then:
npm run cdp-check          # verifies keys, prints which networks CDP actually serves

# 2. Add CDP_WALLET_SECRET, then create a TEE-backed receiving account:
npm run cdp-wallet                  # prints an address to use as PAY_TO
npm run cdp-wallet -- --faucet      # also request Base Sepolia test funds

之所以提供 cdp-check，是因为 CDP 的文档将支持的网络列为“Base、Polygon、Arbitrum、 World、Solana”，却没有说明是否包含 Base Sepolia，而 /supported 需要身份验证。 它会通过实测给出答案，并告知你是否可以进行下文所述的测试网演练。

在测试网上演练 CDP 路径

如果 cdp-check 报告支持 Base Sepolia，请设置 USE_CDP_FACILITATOR=true，同时 保持 NETWORK=eip155:84532。这样你就能使用真实的 CDP 凭证和结算路径处理测试 资金。如果不支持，请不要设置该标志——CDP 路径会先在主网上运行，因此首次付款金额应较小。

上线主网

1. 收款钱包——使用专用地址（最好通过 npm run cdp-wallet 生成），切勿使用 个人钱包。PAY_TO 中只填写公开地址。
2. 设置 NETWORK=eip155:8453。 服务会自动切换到 CDP facilitator，并且在缺少 CDP 密钥时拒绝启动，而不会悄悄使用测试网 facilitator。
3. 设置 PUBLIC_URL 为实际来源地址，确保清单公布的 URL 可访问。
4. 部署（见下文），然后完成 2–3 笔真实结算付款——CDP Bazaar 只有在首次成功结算后才会收录服务。

在任何地方推广端点之前，先从小额付款开始，并在 BaseScan 上确认款项已结算到你的 PAY_TO 地址。

部署（Railway）

已包含 railway.json（Nixpacks、npm run start:api、/healthz 健康检查）。推送代码仓库， 基于该仓库创建 Railway 项目，并在 Railway 的变量界面中设置 .env.example 里的环境变量——不要放入已提交的文件中。将运行时间监控指向 /healthz。

收录

• CDP Bazaar——通过 CDP facilitator 上线主网后，在首次结算付款后自动收录。每条路由都已声明发现元数据，并提供有效的示例输入（npm/express）；这很重要，因为 Bazaar 会使用该输入进行探测，并且只会索引返回 402 的端点——占位的生态系统会返回 400，因此永远不会被收录。
• /.well-known/x402——已提供，供 agentic.market / x402scan / x402-list 使用。
• MCP 注册表——发布到官方 MCP Registry，然后发布到 Glama、Smithery、PulseMCP。

备注

• **缓存：**进程内 LRU 缓存，TTL 从 1 小时（漏洞）到 24 小时（下载量/依赖项）不等。上游失败时，会提供过期值并标记 stale: true，而不是返回错误。
• **付款前验证：**不支持的生态系统会在中间件中、付款检查前返回 400，因此不会产生扣款。
• **按版本限定漏洞查询：**健康评分会针对解析出的当前版本查询 OSV。不指定版本进行查询会返回软件包历史中的所有公告，严重误导对持续维护的软件包的评估。
• pypistats 的速率限制非常严格（快速连续调用几次后就会返回 429）。下载量仅尽力提供：请求失败时会省略该字段，而不会导致请求失败。如果这很重要，请为热门软件包预热缓存。
• src/domain/health.ts 中的健康评分是有文档说明的 v1 启发式方案——随着实际使用数据积累，可调整权重。