subgraph-registry-mcp

サブグラフレジストリ

The Graph Network 上のすべてのサブグラフを、エージェントが扱いやすい形で意味的に分類します。

ドメイン分類、プロトコルタイプ検出、スキーマフィンガープリント、正規エンティティマッピング、複合信頼性スコアを備えた 15,330 個のサブグラフの事前計算済みインデックスです。

0.8.0 の新機能 — エージェントによる検出を強化する 3 つの機能：

• 384 次元の埋め込みを用いた**セマンティック検索**（semantic_search_subgraphs）
• 各結果に安定性日数を表示する**スキーマ変更の追跡**（get_schema_changes）
• MCP ツールと REST ルート用に自動生成される OpenAPI 3.1 仕様。/.well-known/openapi.json で提供されます

課題

The Graph に問い合わせるエージェントは、データをクエリする前に、適切なサブグラフを見つけて選択する必要があります。現在は、実際の作業に入るまでに 3〜4 回のツール呼び出し（検索、ボリュームの確認、スキーマの取得、構造の推測）が必要です。このレジストリはその流れを変え、エージェントが何もない状態からではなく、構造化された情報をもとに作業を始められるようにします。

機能

1. Graph Network のメタサブグラフから、アクティブなサブグラフをすべてクロールします
2. 各デプロイメントの GraphQL スキーマを取得します
3. 各マニフェストの dataSources と templates からコントラクトアドレスを抽出します。エージェントは「チェーン X 上のコントラクト 0x… をインデックスしているサブグラフはどれか？」という質問に回答できます
4. 解析したスキーマから、サブグラフごとの GraphQL クエリのひな形を生成します（実際のトップエンティティ、実際のフィールド、適切な orderBy）。ほとんどのサブグラフではコンパイルできない汎用的なひな形は不要です
5. 各サブグラフを、ドメイン、プロトコルタイプ、正規エンティティ、スキーマファミリー別に分類します
6. オンチェーンのシグナル（クエリ手数料、ボリューム、キュレーション、ステーク）を使用して信頼性をスコア化します
7. x402 と従来のクエリ URL を返します。エージェントは Base 上でクエリごとに $0.01 USDC を支払う（API キー不要）か、Studio キーを使用できます
8. SQLite データベース + REST API + MCP サーバーとして公開し、エコシステムのクローラー向けに サブグラフごとの JSON-LD を /.well-known/subgraph/{id}.jsonld で提供します
9. ビジュアルダッシュボードと、ボットが読み取れるカテゴリファイルを生成します（同期のたびに自動更新）

---

x402 によるクエリ（API キー不要）

すべての結果に、従来の query_url とともに query_url_x402 が含まれます。The Graph の公開 x402 ゲートウェイ（2026-05-08 から稼働）は、登録不要でクエリごとに Base 上で $0.01 USDC を受け付けます。

// An x402-native agent — discovery to data in two calls
const { recommendations } = await mcp.call("recommend_subgraph", {
  goal: "find DEX trades on Arbitrum",
});
const top = recommendations[0];

// POST your GraphQL query. The first call returns HTTP 402 with a
// base64 `payment-required` header; the x402 client signs the
// EIP-3009 USDC transfer on Base and retries automatically.
const data = await x402Fetch(top.query_url_x402, {
  method: "POST",
  body: JSON.stringify({ query: "{ swaps(first: 5) { id amountUSD } }" }),
});

サブグラフごとに返される料金マニフェスト：

{
  "amount_usd": 0.01,
  "asset": "USDC",
  "asset_contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chain": "base",
  "network": "eip155:8453",
  "pay_to": "0x79DC34E41B2b591078d3dE222C43EcaaBD52FcCB",
  "scheme": "exact",
  "asset_transfer_method": "eip3009"
}

クライアントライブラリ：@graphprotocol/client-x402、x402-fetch、または任意の汎用 x402 ラッパー。

---

レジストリの概要

グラフは同期のたびに registry.db から自動生成されます。詳細は python/generate_docs.py を参照してください。

---

カテゴリ別に見る

ドメイン

ユースケース別にサブグラフを探せます。各ファイルには、信頼性スコアの高い順に上位25件のサブグラフが掲載されています。

ドメイン	件数	ファイル
DeFi	7,844	スワップ、プール、レンディング、ボールト、イールド
NFTs	1,565	コレクション、マーケットプレイス、販売
分類なし	1,333	確信を持って分類できないもの
インフラストラクチャ	1,251	インデクサー、オラクル、レジストリ
アイデンティティ	1,061	ENS、ネームサービス、リゾルバー
分析	766	スナップショット、メトリクス、履歴データ
DAO	758	ガバナンス、提案、投票
ゲーム	585	プレイヤー、クエスト、アイテム、ワールド
ソーシャル	167	プロフィール、投稿、フォロー

全インデックス：docs/DOMAINS.md

ネットワーク

ブロックチェーン別にサブグラフを探せます。各ファイルには、そのチェーン上の上位25件のサブグラフが掲載されています。

ネットワーク	件数	ファイル
Ethereum	2,484	最大のエコシステム
Base	1,841	急成長中のL2
BSC	1,670	BNB Chain
Arbitrum	1,437	主要なL2
Polygon	1,304	Polygon PoS
Optimism	580	OP Stack L2
Avalanche	453	C-Chain

全インデックス：docs/NETWORKS.md

プロトコルの種類

種類	件数	説明
DEX	4,411	Uniswap、Sushi、Curve、Balancer、PancakeSwap
レンディング	1,469	Aave、Compound、Morpho、Spark、Silo
ステーキング	898	Lido、Rocket Pool、EigenLayer、Graph Network
ブリッジ	836	Hop、Stargate、Across、Wormhole、LayerZero
NFTマーケットプレイス	450	OpenSea、Blur、Rarible、Foundation
イールドアグリゲーター	425	Yearn、Beefy、Harvest、Convex
ガバナンス	425	Snapshot、Tally、Compound Governor
パーペチュアル	273	GMX、Gains、dYdX、Hyperliquid
ネームサービス	227	ENS、Space ID、Unstoppable Domains
オプション	192	Premia、Dopex、Lyra、Hegic

---

信頼性スコア

各サブグラフには、4つのオンチェーンシグナルに基づく複合信頼性スコア（0～1）が付与されます。

シグナル	重み	測定内容
クエリ手数料	30%	実際の利用によって得られたGRT手数料
クエリ量	30%	30日間のクエリ数
キュレーションシグナル	20%	コミュニティがキュレーションしたGRTトークン
インデクサーの割り当て	20%	インデクサーがこのサブグラフに割り当てたGRT

すべての値は対数スケールで調整され、上限は1.0です。サブグラフが拒否または非推奨になっている場合は、0.5のペナルティが適用されます。

スコアの区分： 高（0.7以上）＝強いシグナル、実際の利用あり｜中（0.3～0.7）＝機能しており、ある程度のアクティビティあり｜低（0.3未満）＝シグナルが最小限、またはテスト用デプロイ

スコアは利用状況を測るため、経過年数も反映されます

4つの入力値はすべて累積値です。手数料とキュレーションは蓄積され、ボリュームは少なくとも30日間経過しないと存在しません。そのため、先月デプロイされたサブグラフは、どれほど優れていてもスコアがほぼゼロになります。現在のコーパス（提供中かつ拒否されていないもの）で測定した結果は次のとおりです。

経過年数	件数	平均信頼性
30日未満	64	0.107
30～90日	227	0.143
90～365日	1,100	0.225
1年超	4,034	0.313

レジストリの上位25件に入っているサブグラフのうち、最も新しいものでも280日経過しています。それでも、30日未満の64件のうち59件は、すでに実際のクエリボリュームを処理しています。

スコアの重み付けを変更して、測定可能なシグナルを推測に置き換えるのではなく、search_subgraphs は若い候補を別個の emerging リストで返し、あわせて emerging_caveat で、その経過年数でスコアが低いのは問題ではなく予想どおりであることを説明します。各結果には age_days と maturity（30日未満は new、90日未満は emerging、それ以外は established）も含まれます。これは、成熟したデプロイが存在し得ない新しいチェーンやプロトコルで特に重要です。「perpetual futures」を検索すると、メインリストには数年前の Ethereum と BSC のデプロイが表示され、emerging には40日経過した Monad のパーペチュアル先物サブグラフが表示されます。

semantic_search_subgraphs は信頼性ではなくコサイン類似度で順位付けするため、すでに経過年数の影響を受けません。maturity ラベルは含まれますが、3週間前のサブグラフでも実力で上位になり得るため、emerging リストはありません。

順位付け

3つのツールが順位付けを行います。それぞれ意図的に異なる方法で順位付けします。

• search_subgraphs — クエリ語の一致数が多い順に並べ、次に信頼性で順位付けします。以前は語句を OR で結び、信頼性のみで並べていたため、偶然の1語だけに一致する人気サブグラフが、3語すべてに正確に一致する候補より上位になっていました。その結果、より具体的に検索すると、かえって結果が悪くなっていました。短すぎるとして除外せず、バージョントークン（v2、v3、v4）も保持します。
• semantic_search_subgraphs — semantic_score × (0.5 + 0.5 × reliability) の順に並べます。コサイン類似度だけでは、テストネットのテキストがメインネットのものとほぼ同じため、テストネットが上位になっていました。0.5の下限により、新しいサブグラフも競争力を保てます。
• recommend_subgraph — 目標からドメインとプロトコルの種類を推定しますが、これは常にフィルターではなく、順位付けのボーナスとして使います。フィルターとして使うと、キーワードが1つ誤っているだけで候補がゼロになっていました。

サブグラフの名前に一致する語句は、説明に一致する語句よりも重く評価されます。%ens% は「tokens」にも一致するため、同じ重み付けでは ens の検索が4つの Uniswap サブグラフに行き着いていました。

チェーン名には別名が設定されているため、ethereum、arbitrum、polygon、bnb は、それぞれコーパス内の値 mainnet、arbitrum-one、matic、bsc に解決されます。

テストネット

提供中の5,425件のサブグラフのうち723件はテストネット上にあり、テキストがメインネット上の対応するサブグラフとほぼ同じであるため、最上位の座を争います。デフォルトでは除外され、各結果には testnet: true|false が含まれます。表示するには include_testnets: true を渡してください。テストネットのネットワークを明示的に指定したリクエスト（network: "sepolia"）は常にデフォルト設定より優先されるため、その場合は指定した内容がそのまま返されます。

payql からのレジストリの利用

payql は、ネットワークサブグラフへのクエリに料金を支払う代わりに、このレジストリを無料の検索元として利用できます。レジストリの HTTP トランスポートを実行し、payql の接続先に指定してください。

npx subgraph-registry-mcp --http-only          # serves :3848
PAYQL_REGISTRY_URL=http://127.0.0.1:3848/graphql npx -y payql

POST /graphql は Graph ネットワークサブグラフの subgraphMetadataSearch 形式で応答します。payql はすでにこの形式を解析するため、payql 側の変更は不要で、検索は無料になり、ローカルで順位付けされます。

拒否されたデプロイ

キュレーションで拒否されたデプロイ（deniedAt > 0 — インデックス報酬が拒否されたもので、通常はスパム、重複、または非推奨のもの）は、search_subgraphs、semantic_search_subgraphs、recommend_subgraph からデフォルトで除外されます。表示するには、2つの検索ツールに include_denied: true を渡してください。その場合、各結果に denied: true|false が含まれるため、選択内容を確認できます。

---

MCP サーバー

レジストリはデュアルトランスポート対応の MCP サーバーとして利用できます。ローカルクライアント向けの stdio と、リモートエージェント向けの SSE/HTTP に対応しています。

graphops/subgraph-mcp と同じ機能（ホスト型 SSE https://subgraphs.mcp.thegraph.com/sse）を備え、ディスカバリーが強化されています。スキーマ、実行、コントラクト検索、30日間のカウントには公式のツール名を使っているため、エージェントはコネクターを切り替えられます。検索では、公式の search_subgraphs_by_keyword よりすでに優れている（信頼性、実際の query_volume_30d、ネットワーク）独自の名前（search_subgraphs、recommend_subgraph、semantic_search_subgraphs）を使い続けています。

公式のワークフローでは、選択前に必ず get_deployment_30day_query_counts を呼び出すよう指定されています。ここでは、その追加のラウンドトリップを省略できます。検索やレコメンドの結果には、すでに query_volume_30d が含まれています。カウントツールも公式名で引き続き利用でき、同じレジストリの数値を返します。公式のカウントが ENS、Lido、Uniswap で 0 を返す事例が確認されていますが、そのようなゼロ値は複製していません。

提供されるサーバーは src/index.js の Node 実装です。npx subgraph-registry-mcp が実行するのも、npm に公開されているのもこちらです。同じ SQLite データベースを使ったローカル開発用として、Python 版の python/mcp_server.py も維持しています。バグ修正や新しいツールは、まず Node 版に追加してください。

ディスカバリーツール（GraphQL を実行せず、ライブスキーマもイントロスペクトしません）：

• search_subgraphs — ドメイン、ネットワーク、プロトコルの種類、エンティティ、キーワードで絞り込みます。一致した用語、信頼性、実際の query_volume_30d に基づいて順位付けします。
• recommend_subgraph — 自然言語の目標に合う最適なサブグラフを提案します（schema_stable_days を含みます）。
• semantic_search_subgraphs — 事前計算済みの埋め込み（sentence-transformers/all-MiniLM-L6-v2、384次元）に対するベクトル類似検索です。文字どおりのキーワード検索では見つからない、曖昧な目標や言い換えられた目標に使います。
• get_subgraph_detail — 特定のサブグラフの分類情報全体を取得します（schema_changed_at とクロール済みの contract_addresses を含みます）。
• list_registry_stats — レジストリの概要（ドメイン、ネットワーク、件数）を取得します。
• get_schema_changes — サブグラフのスキーマフィンガープリントの変更履歴を時系列で取得します（検出された変更ごとに1行）。データ契約が安定している成熟したサブグラフをエージェントが優先するのに役立ちます。

オプトインのクエリ／スキーマ（呼び出し元が実行する必要があります。検索では自動でクエリを実行しません。コネクターを切り替えられるよう、公式名を使用）：

• execute_query_by_subgraph_id ／ execute_query_by_deployment_id ／ execute_query_by_ipfs_hash — GraphQL を The Graph ゲートウェイに POST します。ルーティングは公式と同じです（subgraphs/id と deployments/id）。THE_GRAPH_STUDIO_API_KEY（または GATEWAY_API_KEY）が必要です。キーがない場合は、待機状態になったり x402 による自動支払いを行ったりせず、すぐに {error: credentials_required, query_url, query_url_x402, hint} を返します。便利なスーパーセットとして、execute_query は id、deployment_id、ipfs_hash のいずれかを受け取ります。
• get_schema_by_subgraph_id ／ get_schema_by_deployment_id ／ get_schema_by_ipfs_hash — サブグラフがコーパスにある場合は、ネットワークアクセスなしでローカルの registry_schema（エンティティ、example_query、フィンガープリント）を返します。Studio キーが設定されている場合に限り、ライブの __schema イントロスペクションを行います。便利なスーパーセットとして、get_schema を利用できます。
• get_top_subgraph_deployments(contract_address, chain) — 公式名です。公式の chain は graph-node の ID（ethereum ではなく mainnet）ですが、こちらではどちらも受け付けます。クロール済みマニフェストから上位3件を、信頼性、次いで実際の30日間のボリュームの順に順位付けします（公式のクエリ手数料や、0件を返すオラクルは使いません）。Substreams を利用するサブグラフには dataSources のアドレスがないことがよくあります。その不足は報告され、捏造されません。
• get_deployment_30day_query_counts — 公式名です。ipfs_hashes を入力として受け取り、実際のレジストリの query_volume_30d を返します。不明なハッシュには、偽の0ではなく not_in_registry を返します。通常は不要です。同じ数値が各検索結果にすでに含まれています。 THE_GRAPH_STUDIO_API_KEY を MCP ホストの環境変数に設定すると、execute/live-schema が有効になります。秘密鍵はバンドルされていません。キー認証が必要なゲートウェイでは、認証情報がない場合でも GraphQL エラーを含むレスポンス本文とともに HTTP 200 が返されることがよくあります。execute_query は http_status と errors を正確に提示します。

インストール

# Claude Code
claude mcp add subgraph-registry -- npx subgraph-registry-mcp

# Claude Desktop
{
  "mcpServers": {
    "subgraph-registry": {
      "command": "npx",
      "args": ["subgraph-registry-mcp"],
      "env": {
        "THE_GRAPH_STUDIO_API_KEY": "your-studio-key"
      }
    }
  }
}

# Remote agents (SSE)
npx subgraph-registry-mcp --http-only
# Then connect to http://localhost:3848/sse

サーバーは初回起動時に、ビルド済みのレジストリ（8MB の SQLite）を GitHub から自動的にダウンロードします。

---

Well-Known JSON-LD マニフェスト

MCP を経由せずに、ほかのクローラーやエージェントフレームワークがインデックス化できる、サブグラフごとの安定した機械可読マニフェストです。Node MCP HTTP トランスポートから提供されます。

GET /.well-known/subgraph/{id}.jsonld     Full per-subgraph manifest (JSON-LD)
GET /subgraphs/{id}.jsonld                 Alias (same payload)
GET /.well-known/subgraph-index.jsonld     Discovery list — top 100 by reliability with @id links

各マニフェストには、分類、解析済みのエンティティ、コントラクトアドレス（インデックス化された dataSources 由来）、エンドポイント（x402 および API キー）、実際のスキーマから生成されたサブグラフごとのスタータークエリ、料金、メタデータが含まれます。@context と @type により、構造を自動検出できます。

# Start the HTTP transport
npx subgraph-registry-mcp --http-only

# Fetch the manifest for Uniswap V3 Mainnet
curl http://localhost:3848/.well-known/subgraph/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV.jsonld

---

セマンティック検索

すべてのサブグラフには、sentence-transformers/all-MiniLM-L6-v2 から事前計算された 384 次元の埋め込みがあります。埋め込みは、表示名、説明、正規エンティティ、スキーマ内の上位エンティティ名、プロトコルメタデータから生成されます。MCP ツールの呼び出し時に、Node サーバーは同じモデルを使用してクエリ文字列を埋め込み（@xenova/transformers 経由。量子化済み ONNX は npm パッケージにバンドルされているため、初回呼び出し時のダウンロードは不要です）、コサイン類似度で行を順位付けします。

const { subgraphs } = await mcp.call("semantic_search_subgraphs", {
  query: "lending positions near liquidation on a Layer 2",
  limit: 5,
});
// subgraphs[i].semantic_score is cosine similarity in [0, 1]; >0.5 ~= strong match.

以下の場合に使用してください。

• 目的が言い換えられている、またはユースケースに基づいている場合（search_subgraphs はキーワード検索のみです）。
• 特定のプロトコルのサブグラフを取得するのではなく、「X のデータには何があるか」を調べる場合。

同じモデルを Python のクロール時（fastembed）と JS のランタイム（@xenova/transformers）で共有しているため、ベクトルはビット単位で比較でき、コサイン類似度の計算による順位付けは、ランタイム間で一貫します。

埋め込みにより、registry.db のサイズが約 22 MB 増加します（14k × 384 × 4 バイト）。モデルのバンドルにより、npm パッケージのサイズが約 23 MB 増加します。

---

スキーマの進化

各クロールでは、サブグラフごとに schema_fingerprint（ソート済みの entity:field_count ペアの MD5）を計算します。フィンガープリントが前回の同期から変化すると、変更不可能な行が schema_history に書き込まれます。このテーブルは追記専用で、データベースを完全に再構築しても保持されます。

const history = await mcp.call("get_schema_changes", {
  subgraph_id: "5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV",
});
// {
//   total_changes: 3,
//   stable_days: 47.2,
//   changed_within_24h: false,
//   changed_within_7d: false,
//   changes: [
//     { fingerprint: "abc123...", prev_fingerprint: "def456...", detected_at: 1717... },
//     ...
//   ]
// }

recommend_subgraph と get_subgraph_detail の結果には、schema_changed_at（最後に変更が検出された時刻を示す Unix 秒）と schema_stable_days も含まれるようになりました。これにより、エージェントはデータコントラクトがより長く安定しているサブグラフを優先できます。エージェントの計画期間を通じてクエリを動作させ続ける必要がある場合に役立ちます。

---

OpenAPI

API の全機能（MCP ツールと REST ルート）は OpenAPI 3.1 として公開されています。

• openapi.yaml — リポジトリにコミットされている、唯一の信頼できる情報源
• data/openapi.json — npm の tarball にバンドル
• GET /.well-known/openapi.json — ライブ検出用に HTTP トランスポートから提供

仕様は、src/index.js の宣言的な TOOLS[] と REST_ROUTES[] のエクスポートから、リリースごとに scripts/gen-openapi.js を使って再生成されます。src/index.js を変更しているのに仕様が再生成されていない PR は、CI で失敗します。

---

REST API

GET /summary                    Registry overview and stats
GET /domains                    Domain breakdown
GET /networks                   Network breakdown
GET /families                   Schema family groups (fork/clone detection)
GET /subgraphs                  Filter subgraphs
GET /subgraphs/{id}             Full detail for one subgraph (now includes contract_addresses and example_query)
GET /search?q=uniswap           Free-text search
GET /recommend?goal=...&chain=  Agent-optimized recommendation

# Start API server
cd python && python server.py

# Example: find DEX subgraphs on Arbitrum
curl "http://localhost:3847/recommend?goal=query+DEX+trades+on+Arbitrum&chain=arbitrum-one"

# Example: filter by entity type
curl "http://localhost:3847/subgraphs?entity=liquidity_pool&network=base&min_reliability=0.5"

---

ボットが読み取れるカテゴリファイル

docs/ ディレクトリには、AI エージェントやボットが利用できるように設計された、YAML フロントマター付きの構造化 .md ファイルが含まれています。

docs/
├── DOMAINS.md           # Index of all domains with counts
├── NETWORKS.md          # Index of all networks with counts
├── charts/              # Auto-generated SVG visualizations
│   ├── domains.svg
│   ├── networks.svg
│   ├── protocol-types.svg
│   └── reliability.svg
├── domains/             # One file per domain
│   ├── defi.md          # Top 25 DeFi subgraphs by reliability
│   ├── nfts.md
│   ├── dao.md
│   └── ...
└── networks/            # One file per network
    ├── mainnet.md       # Top 25 Ethereum subgraphs by reliability
    ├── base.md
    ├── arbitrum-one.md
    └── ...

各カテゴリファイルには、以下が含まれます。

• YAML フロントマター（ドメイン／ネットワーク、件数、割合、最終更新日時）
• 信頼性スコア順に並べた上位 25 件のサブグラフ
• MCP ツールと REST API のクエリ例

---

アーキテクチャ

Graph Network Subgraph (meta-subgraph, 140M queries/month)
    |
    v
crawler.py ---- async httpx, ID-based cursor pagination
    |
    v
classifier.py - rule-based domain/protocol classification + schema fingerprinting
    |
    v
registry.py --- builds SQLite + indices
    |
    ├── server.py ------ FastAPI REST API (:3847)
    ├── generate_docs.py SVG charts + category .md files
    └── scheduler.py --- weekly incremental sync

MCP Server (src/index.js, published to npm)
    ├── stdio   ←── Claude Desktop / Claude Code
    └── SSE     ←── OpenClaw / remote agents (:3848)

python/mcp_server.py — local-dev MCP server hitting the same SQLite DB

クイックスタート（ローカルビルド）

cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

echo "GATEWAY_API_KEY=your-key-here" > .env

# Full crawl + classify (~11 min)
python registry.py

# Generate charts and category files
python generate_docs.py

# Start API server
python server.py

最新の状態を維持する仕組み

GitHub Actions ワークフローが 3 日ごとに実行されます。

1. 増分クロール（updatedAt_gte: lastSyncTimestamp）
2. 新規または変更されたサブグラフを再分類
3. SVG チャートとカテゴリ .md ファイルを再生成
4. 更新をコミットしてプッシュ

ライセンス

MIT