子图注册表（Subgraph Registry）

面向 Agent 的、涵盖 The Graph 网络上 15,500+ 个已分类子图的发现服务。支持按领域（domain）、网络（network）、协议类型（protocol type）或自然语言目标进行搜索 —— 返回结果附带可靠性评分，并提供 x402-ready 查询 URL。Agent 可直接从问题 → 答案，全程无需接触 Studio API 密钥。

工具

• search_subgraphs — 按领域（defi、nfts、dao、gaming）、网络（ethereum、arbitrum、base）、协议类型（dex、lending、bridge）、实体类型或关键词过滤
• recommend_subgraph — 输入自然语言目标，例如“查找 Arbitrum 上的 DEX 交易”，返回最匹配的子图
• get_subgraph_detail — 返回完整分类信息、实体列表、可靠性评分、x402 与 legacy 查询 URL，以及两条路径的分步查询说明
• list_registry_stats — 注册表概览，包括当前支持的领域、网络和协议类型
• semantic_search_subgraphs — 基于嵌入（embedding）的自然语言搜索，覆盖整个注册表。通过 @xenova/transformers 加载内置 ONNX 模型；若内置模型缺失，则仅首次运行时从 Hugging Face 下载一次（参见“网络与数据行为”）。如需严格离线运行，请跳过此工具。
• get_schema_changes — 报告某子图在不同索引版本间的 Schema / 实体变更情况

查询路径

每个结果现在均附带两个 URL 和一份 pricing 清单：

• query_url_x402 （推荐） — https://gateway.thegraph.com/api/x402/subgraphs/id/{id}。向该地址 POST GraphQL 查询；网关将返回 HTTP 402 状态码及支付清单（payment manifest）。使用 x402 客户端（如 @graphprotocol/client-x402、x402-fetch 或任意通用封装器），通过 EIP-3009 在 Base 链上对 0.01 USDC 进行签名并重试。无需注册、无需 Studio 密钥、无需 GRT。
• query_url （传统路径） — https://gateway.thegraph.com/api/[api-key]/subgraphs/id/{id}。请前往 thegraph.com/studio/apikeys 获取 API 密钥，并替换占位符。

运行要求

• 运行时环境： Node.js >= 18（通过 npx 运行）
• 环境变量： 无需设置。注册表已预构建并打包完成 —— 仅读取用途下无需 API 密钥。
• 执行 x402 查询时： Agent 的签名钱包中需持有 Base 链上的 USDC（单次查询约消耗 $0.01）。

安装

请固定使用经验证的稳定版本。如计划将其部署至自主 Agent 运行时环境，请在安装前于 GitHub 上审计源代码。

# 固定到已发布的版本；切勿不带版本号运行（`npx subgraph-registry-mcp`
# 不加 @VERSION 将拉取当时最新的任意版本）。
npx subgraph-registry-mcp@0.6.0

网络与数据行为

• 首次运行时，服务端会从 GitHub 仓库下载预构建的 registry.db（SQLite 格式，约 5 MB）。该文件将被本地缓存并在后续运行中复用。
• 下载完成后，服务端会将该文件的 SHA-256 哈希值与 npm 包中硬编码的哈希值进行比对 —— 具体参见下方“验证注册表”章节。若校验失败（例如 GitHub 托管文件被篡改，或本地缓存遭破坏），则自动删除该文件且服务拒绝启动。
• 过滤/查询类工具（search_subgraphs、recommend_subgraph、get_subgraph_detail、list_registry_stats、get_schema_changes）完全基于本地数据库运行 —— 查询阶段不发起任何外部 API 调用。
• 例外 — semantic_search_subgraphs： 该工具通过 @xenova/transformers 加载内置 ONNX 嵌入模型。若模型未预置，运行时将 仅首次 从 Hugging Face（huggingface.co）下载并缓存。这是唯一在查询阶段发生的网络请求。如需严格气隙（air-gapped）运行，请避免调用该工具，或提前手动预置模型。
• 可选本地 HTTP/SSE 服务器： 默认通信方式为 stdio（无监听端口）。传入 --http 或 --http-only 参数后，将在 3848 端口启动本地 HTTP/SSE 服务（可通过 MCP_HTTP_PORT 修改端口），暴露 /messages、健康检查及 OpenAPI/manifest 接口。该服务默认关闭；启用时请确保仅绑定至可信或防火墙隔离的环境。

验证注册表

npm 包版本 0.6.0 内置以下预期哈希值：

SHA-256(registry.db) = f81b79c53cc13c3428472024187fc7fd502f7418f5da20f0a6e01807dd4011c6

该哈希值硬编码于 src/index.js 中（变量名为 EXPECTED_DB_SHA256）。每次运行时，服务端均会校验缓存或新下载的 registry.db 文件是否匹配。若哈希不一致（可能因 GitHub 托管文件被替换，或本地缓存遭篡改），服务端将 拒绝加载数据库 并报错退出。异常文件会被自动删除，以便下次运行尝试重新下载。

可手动验证：

shasum -a 256 ~/.npm/_npx/*/node_modules/subgraph-registry-mcp/data/registry.db
# （路径随 npx 缓存结构而异；实际文件即包内 `data/registry.db` 所指）

若您主动使用可选 Python 爬虫本地重建了 DB，其哈希值将不匹配。此时可设置 SUBGRAPH_REGISTRY_SKIP_VERIFY=1 跳过校验 —— 但切勿在 Agent 运行时的默认配置中启用该选项。

每当注册表被重新生成，维护者将同步提升 npm 版本 并 原子化更新哈希常量 —— 因此每个 npm 版本唯一对应一个已知且确定的 DB 快照。

典型应用场景

• 在查询 The Graph 前，快速定位最合适的子图
• 按链（chain）筛选高可靠性 DeFi、NFT、DAO 或治理类子图
• 无需人工探索，直接获取查询 URL 与实体 Schema
• 依据可靠性评分（查询费用、策展信号、索引器质押）横向对比子图