Package Intel

パッケージと依存関係のインテリジェンス API（x402）

x402 支払いプロトコル（x402）を通じて、AI コーディングエージェントに npm、PyPI、crates.io（Rust）のパッケージの健全性、依存関係グラフ、脆弱性データを従量課金で提供する API です。Claude Desktop／Cursor のエージェントが呼び出して自動的に支払えるよう、MCP サーバーも備えています。

デフォルトでは、無料の公開ファシリテーターを介して 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回、1日2000回のレート制限があります。エージェントが制御不能なループに陥ると、上流へのリクエストが増え、こちらの送信元 IP が npm や OSV にブロックされる可能性があるためです。有料エンドポイントは制限の対象外で、料金が制限の役割を果たします。制限を超えると、Retry-After を含む 429 が返されます。

ティア、価格、説明、ディスカバリーメタデータはすべて src/catalog.ts で管理されています。ここを編集すれば、支払いミドルウェア、レート制限、マニフェスト、Bazaar の宣言に変更が反映されます。tier は必須の識別子であり、新しいエンドポイントが誤って無料になることはありません。

呼び出し元のアドレスを信頼する

レート制限ではクライアント IP ごとにカウントしますが、このサービスは Worker プロキシとトンネルの背後にあるため、すべてのリクエストが同じアドレスから届きます。プロキシは実際のアドレスを PROXY_SECRET で署名したうえで x-stable-ip として転送し、オリジンはシークレットが一致する場合にのみその値を受け入れます。それ以外の場合、シークレットが間違っている場合、シークレットがない場合、トンネルのホスト名に直接リクエストした場合は、すべて単一のバケットを共有します。この署名がなければ、呼び出し元はリクエストごとに新しいアドレスを偽装したり、プロキシを迂回したりして、上流へのリクエストを制限なく発生させることができます。

両方の場所に同じ値を設定してください。

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

メインネットでは、値が設定されていない場合にサーバーが起動時に警告します。

ローカル環境のセットアップ（テストネット）

npm install
npm run gen-wallet

gen-wallet はテストネット専用のキーペアを2組出力します。実際の資産をこれらのアドレスに送金しないでください。

• 販売者 — アドレスを .env の PAY_TO に設定します（支払いの受取先です）。
• 購入者 — 秘密鍵を .env の BUYER_PRIVATE_KEY に設定します（支払いを行うエージェントをテストスクリプトでシミュレートするために使用します）。

.env.example を .env にコピーし、値を入力します。その後、faucet.circle.com で購入者に Base Sepolia USDC を送金します（Base Sepolia を選択してください。アカウントは不要です）。テストネット ETH は必要ありません。x402 の exact スキームは EIP-3009 を使用するため、購入者はオフチェーンで署名するだけで、ガス代はファシリテーターが支払います。

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 では、先頭の / が Windows パスに書き換えられないように、先頭に MSYS_NO_PATHCONV=1 を付けてください。

存在しないパッケージへのリクエストは、課金されずに404 を返します。x402 ミドルウェアは、4xx／5xx のレスポンスでは決済処理を完全にスキップするため、失敗時は無料です。

MCP サーバー（エージェントによる利用方法）

mcp-client/ は独立した npm パッケージ（package-intel-mcp）です。購入者のマシン上で実行される stdio MCP サーバーです。このサーバーとは別に公開されるため、インストール時に Hono や x402 サーバースタックが取り込まれることはありません。また、src/ から何もインポートしません。

設定なしですぐに実行できます。 ウォレットがなくても、4 つの無料ツール（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 の支払いに署名して再試行します。エージェントからはデータだけが見えます。不正なキーは、理由もなく有料ツールが消えたように見えないよう、無料モードへ黙ってフォールバックするのではなく、明示的なエラーになります。

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

X402_PRIVATE_KEY は、NETWORK 上の USDC で資金を入れた エージェント運用者の ウォレットです。残高を少なく抑えた専用ウォレットを使用してください。これは自動で支払いを行うホットキーです。

ソースからローカルサーバーに接続して実行するには、npm run mcp を使用します。

エージェントに実際に呼び出させるには

ツールをインストールしても、エージェントがそれを使うとは限りません。利用側リポジトリの AGENTS.md／CLAUDE.md／.cursor/rules に一行追加すると、関連するタスクのたびに呼び出されます。繰り返し利用を生み出すのはこの仕組みであり、レジストリへの掲載ではありません。mcp-client/README.md には、そのままコピーして貼り付けられるブロックが用意されています。

GitHub Action

action.yml は、このリポジトリを依存関係レビュー用のアクションとして公開します。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	ホステッドサービス	独自のインスタンスに接続する場合に上書きします

知っておくとよい動作が 2 つあります。レビュー対象は追加された依存関係のみで、既存の依存関係のバージョン更新は対象外です。そのため、コメントがノイズになって読み飛ばされるようなことはありません。また、アドバイザリはバージョンごとに絞り込まれます。完全固定のバージョンは指定どおりにチェックされ、範囲指定はパッケージの現行リリースを基準にチェックされます。この違いは重要です。バージョンを指定せずに問い合わせると、過去に報告されたすべてのアドバイザリが返され、完全にパッチ適用済みの lodash まで重大な問題として報告されます。

検索できない依存関係が原因で失敗することはありません。上流サービスの停止によって、無関係なプルリクエストをブロックしてはなりません。

Coinbase CDP の設定

混同しやすい、異なる 2 種類の 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 がサポートされていると報告された場合は、NETWORK=eip155:84532 のまま USE_CDP_FACILITATOR=true を設定します。これにより、テスト資金を使って、実際の CDP 認証情報と決済経路を 試せます。サポートされていない場合は、フラグを設定しないでください。CDP の経路は最初にメインネットで実行されるため、最初の決済は少額にしてください。

メインネットへの移行

1. 受取ウォレット — 専用アドレス（できれば npm run cdp-wallet で作成したもの）を使い、個人用ウォレットは使わないでください。PAY_TO に設定するのは公開アドレスだけです。
2. NETWORK=eip155:8453 を設定します。 サーバーは自動的に CDP ファシリテーターに切り替わり、CDP キーがない場合は、テストネットのファシリテーターを黙って使うのではなく、起動を拒否します。
3. PUBLIC_URL に実際のオリジンを設定し、マニフェストに到達可能な URL が掲載されるようにします。
4. デプロイ（下記参照）し、実際の決済を 2～3 回行って決済の完了を確認します。CDP Bazaar は、最初の決済が正常に完了した後にのみサービスをカタログに登録します。

エンドポイントをどこかで紹介する前に、まず少額で開始し、PAY_TO アドレスに対する決済が BaseScan で確認できることを確かめてください。

デプロイ（Railway）

railway.json が含まれています（Nixpacks、npm run start:api、/healthz ヘルスチェック）。リポジトリをプッシュし、 そこから Railway プロジェクトを作成して、Railway の変数 UI で .env.example の環境変数を設定してください。コミット済みのファイルには設定しないでください。稼働監視の対象を /healthz に設定します。

掲載する

• CDP Bazaar — メインネットで CDP ファシリテーターを使うと、最初の 決済完了後に自動で登録されます。各ルートには、有効なサンプル入力（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 のヒューリスティックです。実際の利用データが集まるにつれて、重みを調整してください。