vdiff-mcp

vdiff

npm パッケージの破壊的変更を比較する API です。パッケージと 2 つのバージョンを指定すると、実際に破壊された内容を構造化された機械可読リストで返します。削除されたエクスポート、変更された関数シグネチャ、削除または変更されたクラスやインターフェースのメンバーが含まれます。各項目には変更前と変更後のシグネチャ、および短い移行メモが含まれます。

https://vdiff-api.onrender.com で稼働しています。最も簡単に利用するには、MCP サーバー vdiff-mcp を使用します。

claude mcp add vdiff -- npx -y vdiff-mcp

または、REST API を直接呼び出します。

curl "https://vdiff-api.onrender.com/v1/diff?ecosystem=npm&package=zod&from=3.24.0&to=4.0.0"

開発の背景

LLM はトレーニング中にパッケージの API を学習しますが、その後パッケージは更新されます。コーディングエージェントが zod や express を使ってコードを書くとき、記憶しているバージョンを基に記述しますが、それは多くの場合、ロックファイルに記載されているバージョンとは異なります。その結果、2 つ前のメジャーバージョンで名前が変更または削除された関数を呼び出す、自信満々のコードが生成されます。

既存のツールで解決できるのは、この問題の一部だけです。バージョン検索ツールは、エージェントに現在のバージョンを伝えます。ドキュメントツールは、現在のドキュメントの内容を伝えます。しかし、どちらもエージェントが編集中に実際に知りたい「自分が知っているバージョンと、ここにインストールされているバージョンの間で何が変わったのか？」という疑問には答えません。

vdiff はまさにその疑問に答えます。差分は変更履歴ではなく、パッケージ独自の型宣言から算出されるため、出力には実際にエクスポートされている API が反映されます。また、すべての応答に信頼度スコアが付与されるため、利用側はどの程度信頼できるかを把握できます。

エンドポイントのリファレンス：docs/api.md。

仕組み

1. 解決。 npm レジストリからパッケージのメタデータ、バージョン、dist-tag を取得します。
2. 抽出。 2 つのバージョンそれぞれについて、tarball をダウンロードし、.d.ts ファイルのみを残してから、TypeScript コンパイラー API を使ってパブリックエクスポート（関数、クラス、メンバー、正規化された呼び出しシグネチャ）の一覧を作成します。バンドルされた宣言を優先します。それらを含まないパッケージでは、対応する DefinitelyTyped の @types/* パッケージを使用し、major.minor でバージョンを一致させます。
3. 比較。 2 つのエクスポート一覧の差分を、型付きの変更項目（export_removed、signature_changed、member_removed など）に変換します。各項目には変更前と変更後のシグネチャ、および移行メモが含まれます。
4. キャッシュと計測。 結果は Postgres に（パッケージ、変更元バージョン、変更先バージョン）をキーとして保存されるため、各バージョンの組み合わせは一度だけ計算されます。すべてのリクエストについて、キャッシュヒットの状態とユーザーエージェントを記録します。
5. 保護。 IP ごとのレート制限、同時に実行できる差分計算数の上限、tarball と抽出済み宣言のサイズ制限、フェッチのタイムアウトを設け、サービスを安全に公開できるようにします。

差分の対象は型レベルです。型に変更がないランタイムの動作変更は検出できません。バンドルされた型を使用する応答の信頼度は 0.9、コミュニティが保守する @types/* 宣言を使用する応答の信頼度は 0.8 です。

API の概要

エンドポイント	用途
GET /v1/diff	2 つのバージョン間の破壊的変更の差分（from は必須、to の既定値は最新バージョン）
GET /v1/resolve	パッケージの最新バージョンと dist-tag
GET /healthz	稼働状態の確認

パラメーター、応答形式、変更の種類、エラーコード、レート制限については、docs/api.md を参照してください。

技術スタック

レイヤー	選択肢	理由
ランタイム	Node 20+、TypeScript	npm のみの .d.ts 差分比較には TS コンパイラー API が必要なため、言語を統一できます
API	Fastify 5	高速で軽量、TypeScript のサポートも充実しています
差分比較	typescript コンパイラー API	.d.ts ファイルから構造化されたシンボルテーブルを作成でき、製品の中核を担います
データベース	Postgres 18（ローカルでは Docker、本番では Neon）	可変形式の差分データには JSONB、課金と分析には SQL を使用します
レジストリ	npm レジストリ HTTP API + tar	Packument と tarball を取得し、宣言ファイルのみを抽出します
テスト	Vitest	比較ロジックと @types のバージョン照合の単体テストに使用します

コードはクラウドに依存しません。通常のコンテナーと DATABASE_URL があれば動作します。現在は Neon Postgres とともに Render で実行されています。

自分で実行する

docker compose up -d      # Postgres 18 on :5432
npm install
npm run db:migrate        # apply src/db/schema.sql
npm run dev               # API on :3000

または、PaaS で実行する場合と同じ方法でコンテナー化して実行します（起動時にスキーマを適用し、その後リクエストを処理します）。

docker build -t vdiff-api .
docker run -p 3000:3000 -e DATABASE_URL="postgres://user:pass@host:5432/db" vdiff-api

設定

すべての設定は環境変数を使用します。

環境変数	デフォルト値	用途
PORT	3000	リッスンポート
DATABASE_URL	ローカルの Docker Postgres	Postgres 接続文字列
RATE_LIMIT_DIFF_MAX	30	IP ごとの /v1/diff リクエスト数（1 分あたり）
RATE_LIMIT_RESOLVE_MAX	120	IP ごとの /v1/resolve リクエスト数（1 分あたり）
COMPUTE_CONCURRENCY	2	同時に実行できる差分計算の最大数
TRUST_PROXY	未設定	PaaS プロキシの背後で true に設定すると、レートリミッターが実際のクライアント IP を認識します

セキュリティ強化に関する注意事項

• レート制限：IP ごとにインメモリで管理します（単一インスタンスでの運用に適しています）。プラットフォームのヘルスチェック用に /healthz は制限の対象外です。
• 計算数の上限：キャッシュされていない差分のコンパイルは、同時に最大 COMPUTE_CONCURRENCY 件までです。上限を超えたリクエストには、retry-after とともに 503 が返されます。キャッシュ済みの差分は常に返されます。
• サイズ制限：tarball のダウンロードサイズは 50 MB（content-length と実際のバイト数で確認）、展開後の宣言ファイルはバージョンごとに 15 MB までです。サイズ超過のパッケージには、明確なエラーメッセージとともに 422 が返されます。
• フェッチのタイムアウト：packument は 10 秒、tarball は 30 秒です。tarball は HTTPS 経由で registry.npmjs.org からのみ取得されます。

プロジェクト構成

src/
  index.ts          Fastify bootstrap, /healthz
  routes.ts         /v1/resolve, /v1/diff: validation, cache, dedup, metering
  registry/npm.ts   packument fetch, tarball download, .d.ts extraction
  diff/
    symbols.ts      .d.ts to symbol table (TS compiler API)
    compare.ts      symbol table diff to breaking changes
    engine.ts       orchestration, @types/* fallback, confidence
  db/
    schema.sql      packages, versions, diffs, diff_requests_log
    migrate.ts      applies schema
mcp/                vdiff-mcp, the MCP server wrapping this API (published to npm)
docs/
  api.md            endpoint reference, kept current with the code

テスト

npm test          # unit tests (Vitest)
npx tsc --noEmit  # typecheck

ライセンス

API と差分エンジンは、Functional Source License, v1.1, MIT Future License（FSL-1.1-MIT）の下でライセンスされています。競合するサービスの提供を除き、あらゆる目的で自由に使用、閲覧、変更できます。また、各リリースは公開から 2 年後に自動的に MIT ライセンスになります。

mcp/ の MCP サーバーラッパーはMIT ライセンスです。