subgraph-registry-mcp

子图注册表

面向 Agent 的 The Graph Network 全部子图语义分类。

预先计算的索引，涵盖 15,330 个子图，包含领域分类、协议类型检测、架构指纹识别、规范实体映射和综合可靠性评分。

0.8.0 版本新增内容——三项 Agent 发现功能升级：

• 通过 384 维嵌入实现**语义搜索**（semantic_search_subgraphs）
• 架构演变追踪，在每个结果中显示稳定天数（get_schema_changes）
• OpenAPI 3.1 规范，为 MCP 工具和 REST 路由自动生成，并通过 /.well-known/openapi.json 提供

问题

Agent 在查询数据之前，需要先发现并选择合适的子图。目前，这需要调用 3-4 个工具（搜索、检查数据量、获取架构、推断结构），之后才能开始真正的工作。此注册表改变了这种方式：Agent 从结构化知识出发，而不是从一张白纸开始。

功能

1. 爬取 Graph Network 元子图中的所有活跃子图
2. 获取每个部署的 GraphQL 架构
3. 从每个清单的 dataSources 和 templates 中提取合约地址——Agent 可以回答“哪个子图索引了链 X 上的合约 0x…？”
4. 根据解析后的架构为每个子图生成入门 GraphQL 查询（真实的顶级实体、真实字段和合理的 orderBy）——不再使用无法通过大多数子图编译的通用样板查询
5. 按领域、协议类型、规范实体和架构系列对每个子图分类
6. 使用链上信号（查询费用、数据量、策展和质押）评估可靠性
7. 返回 x402 和传统查询 URL——Agent 可为每次查询在 Base 上支付 $0.01 USDC（无需 API 密钥），也可使用 Studio 密钥
8. 以 SQLite 数据库、REST API 和 MCP 服务的形式发布，并提供每个子图的 JSON-LD 文件 /.well-known/subgraph/{id}.jsonld，供生态系统爬虫使用
9. 生成可视化仪表板和机器人可读的类别文件（每次同步时自动更新）

---

使用 x402 查询（无需 API 密钥）

每个结果都包含 query_url_x402，以及传统的 query_url。The Graph 的公共 x402 网关（自 2026-05-08 起上线）支持每次查询支付 $0.01 USDC（Base 链），无需注册。

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

---

可靠性得分

每个子图都会根据四种链上信号获得综合可靠性得分（0-1）：

信号	权重	衡量内容
查询费用	30%	实际使用所产生的 GRT 费用
查询量	30%	30 天内的查询次数
策展信号	20%	社区策展的 GRT 代币数量
索引器分配	20%	索引器分配给该子图的 GRT

所有数值均采用对数缩放，最高不超过 1.0。如果子图已被拒绝/弃用，则扣除 0.5 分。

得分等级： 高（0.7+）= 信号强、实际使用 | 中（0.3-0.7）= 功能正常、有一定活动 | 低（<0.3）= 信号极少或为测试部署

分数衡量的是热度，因此也衡量了年龄

这四项输入都是累积值——费用和策展数据会不断累积，交易量则需要经过 30 天才会产生。所以上个月才部署的子图无论质量多好，得分都接近零。根据当前语料库（已提供服务、未被拒绝）测得：

年龄	数量	平均可靠性
< 30 天	64	0.107
30–90 天	227	0.143
90–365 天	1,100	0.225
> 1 年	4,034	0.313

注册表排名前 25 的子图中，最新的也已经有 280 天——但这 64 个未满 30 天的子图中，已有 59 个在提供真实查询量。

我们没有重新调整分数权重、用猜测取代可衡量信号，而是让 search_subgraphs 在单独的 emerging 列表中返回年轻的匹配项，并附上 emerging_caveat，说明该年龄下得分较低是意料之中的，而非值得否定的表现。每个结果还带有 age_days 和 maturity（new < 30d、emerging < 90d、established）。这对新链和新协议尤为重要，因为它们不可能已有成熟部署——搜索“perpetual futures”时，主列表会显示部署多年的 Ethereum 和 BSC 子图，而 emerging 下则会显示 40 天前部署的 Monad 永续合约子图。

semantic_search_subgraphs 根据余弦相似度而非可靠性排序，因此本身不受年龄影响——它会提供 maturity 标签，但没有 emerging 列表，因为只要匹配度足够好，三周前的子图也能排在前面。

排序

三个工具会进行排序，而且各自的排序方式都有意为之：

• search_subgraphs — 先按匹配到的查询词数量排序，再按可靠性排序。此前将查询词进行 OR 匹配、只按可靠性排序，导致一个只匹配了一个偶然词汇的热门子图，排在精准匹配全部三个词的结果前面；查询越具体，结果反而越差。版本标记（v2、v3、v4）会保留，不会因为太短而被忽略。
• semantic_search_subgraphs — 按 semantic_score × (0.5 + 0.5 × reliability) 排序。纯余弦相似度会让测试网排在前面，因为它们的文本与主网几乎完全相同。0.5 的下限让新子图也能保持竞争力。
• recommend_subgraph — 根据目标推断领域和协议类型，但只将其作为排名加分项，绝不作为筛选条件。若将其用作筛选条件，一个错误的关键词就会让候选池变空。

匹配子图名称中的词，比匹配描述中的词权重更高——%ens% 也会匹配“tokens”，因此如果权重相同，搜索 ens 就会返回四个 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 中排除。在两个搜索工具中传入 include_denied: true 即可查看；届时每个结果都会带有 denied: true|false，让这一选择清晰可见。

---

MCP 服务

该注册表可作为具有双传输方式的 MCP 服务使用——stdio 供本地客户端使用，SSE/HTTP 供远程 Agent 使用。

具备与 graphops/subgraph-mcp（托管的 SSE https://subgraphs.mcp.thegraph.com/sse）相同的能力，发现能力更强。Schema、执行、合约查询和 30 天计数使用官方工具名称，方便 Agent 切换连接器。搜索仍使用我们的名称（search_subgraphs、recommend_subgraph、semantic_search_subgraphs），因为它们的表现已经优于官方的 search_subgraphs_by_keyword（可靠性、真实的 query_volume_30d、网络）。

官方工作流要求在选择之前始终调用 get_deployment_30day_query_counts。这里可以跳过这次额外往返——每条搜索／推荐结果都已包含 query_volume_30d。计数工具仍以官方名称提供，并读取相同的注册表数据。我们发现官方计数对 ENS、Lido 和 Uniswap 返回过 0；我们不会照搬这些 0 值。

发布的服务是 src/index.js 中的 Node 实现；npx subgraph-registry-mcp 运行的就是它，npm 上发布的也是它。python/mcp_server.py 中保留了一个 Python 等效实现，用于在本地针对同一个 SQLite 数据库进行开发——错误修复和新工具应优先提交到 Node 版本。

发现工具（绝不执行 GraphQL，也绝不检查实时 schema）：

• 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 — 返回某个子图按时间顺序排列的 schema 指纹历史记录（每次检测到的变更占一行）。帮助 Agent 优先选择数据契约稳定、成熟的子图。

选择启用的查询／schema 工具（调用方必须主动调用；搜索不会自动查询）。用于切换连接器的官方名称：

• execute_query_by_subgraph_id / execute_query_by_deployment_id / execute_query_by_ipfs_hash — 向 The Graph 网关发送 GraphQL POST 请求。路由方式与官方一致（subgraphs/id 与 deployments/id）。需要 THE_GRAPH_STUDIO_API_KEY（或 GATEWAY_API_KEY）。未设置密钥时会立即返回 {error: credentials_required, query_url, query_url_x402, hint}——不会卡住，也不会自动支付 x402。便捷的超集工具：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（mainnet，而不是 ethereum）；我们两者都接受。根据抓取到的清单选出排名前 3 的结果，按可靠性和真实的 30 天流量排序（而非官方的 query-fees／0 计数预言机）。由 Substreams 驱动的子图通常没有 dataSources 地址——我们会报告这一缺失，不会伪造数据。
• get_deployment_30day_query_counts — 官方名称，输入 ipfs_hashes。返回注册表中的真实 query_volume_30d。未知哈希会返回 not_in_registry，而不是伪造的 0。通常无需调用：每条搜索结果中都已包含相同的数值。 在 MCP 主机环境中设置 THE_GRAPH_STUDIO_API_KEY，以启用 execute/live-schema。未捆绑任何私钥。缺少身份验证时，带密钥的网关通常会返回 HTTP 200，并在响应正文中包含 GraphQL 错误——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

服务会在首次运行时自动从 GitHub 下载预构建的注册表（8MB SQLite）。

---

众所周知的 JSON-LD 清单

稳定、机器可读的子图清单，其他爬虫和 Agent 框架无需通过 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 密钥）、根据实际 schema 生成的子图专用入门查询、定价和元数据。@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

---

语义搜索

每个子图都有一个预先计算的 384 维嵌入，该嵌入使用 sentence-transformers/all-MiniLM-L6-v2 生成，依据包括其显示名称、描述、规范实体、schema 中排名靠前的实体名称和协议元数据。在 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 bytes）；模型包会使 npm 包增加约 23 MB。

---

Schema 演进

每次爬取都会为每个子图计算一个 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，以便 Agent 优先选择数据契约稳定时间更长的子图——当查询需要在 Agent 的规划周期内持续可用时，这项信息很有用。

---

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/ 目录包含带 YAML frontmatter 的结构化 .md 文件，旨在供 AI Agent 和机器人使用：

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 frontmatter（领域/网络、数量、占比、最后更新日期）
• 按可靠性评分排序的前 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