The Graph MCP 技能

使用此技能，可通过 uxc 调用原生 SSE MCP 端点，执行 The Graph Subgraph MCP 相关操作。

复用 uxc 技能实现通用协议发现、信封解析及错误处理规则。

前提条件

• uxc 已安装并位于 PATH 中。
• 可访问网络地址 https://subgraphs.mcp.thegraph.com/sse。
• 已获取 The Graph Gateway API 密钥，用于身份验证调用。

核心工作流（The Graph 特定）

在最终确定前，需评估以下端点候选输入：

• 官方远程 MCP 端点：
  • https://subgraphs.mcp.thegraph.com/sse

1. 从官方源验证协议/路径并进行探测：
   • 官方文档地址：https://thegraph.com/docs/en/ai-suite/subgraph-mcp/introduction/
   • 对候选端点执行探测命令：
     • uxc https://subgraphs.mcp.thegraph.com/sse -h
   • 确认协议为 MCP（信封中 protocol == "mcp"）。
2. 显式检测身份验证需求：
   • 运行主机帮助命令或最小化读取调用，并检查返回信封。
   • 该端点要求提供 The Graph Gateway API 密钥，以 Authorization: Bearer 方式发送。
3. 注册凭据，并默认使用固定链接命令：
   • uxc auth credential set thegraph --secret-env THEGRAPH_API_KEY
   • uxc auth binding add --id thegraph-sse --host subgraphs.mcp.thegraph.com --path-prefix /sse --scheme https --credential thegraph --priority 100
   • command -v thegraph-mcp-cli
   • 若命令不存在，则创建：
     • uxc link thegraph-mcp-cli https://subgraphs.mcp.thegraph.com/sse
   • thegraph-mcp-cli -h
   • 如检测到命令冲突且无法安全复用，应立即中止并提请技能维护者选择另一个固定的命令名称。
4. 执行前检查操作 Schema：
   • thegraph-mcp-cli -h
   • thegraph-mcp-cli -h
5. 优先执行发现/Schema 类操作：
   • 查找候选子图（subgraph）或部署（deployment）
   • 检查 Schema
   • 仅在明确标识符与 Schema 后再执行查询

能力映射

• 发现（Discovery）：
  • 按关键词搜索子图
  • 查找某合约的热门部署
  • 查看部署热度 / 近 30 日查询量
• Schema：
  • 通过 deployment ID 获取 Schema
  • 通过 subgraph ID 获取 Schema
  • 通过 IPFS 哈希值获取 Schema
• 查询执行（Query execution）：
  • 通过 deployment ID 执行 GraphQL 查询
  • 通过 subgraph ID 执行 GraphQL 查询
  • 通过 IPFS 哈希值执行 GraphQL 查询

防护机制（Guardrails）

• 自动化流程应始终基于 JSON 输出信封；不得依赖 --text 参数。
• 优先解析稳定字段：ok、kind、protocol、data、error。
• 默认使用 thegraph-mcp-cli 作为命令路径。
• 当配置了相同的认证绑定时，thegraph-mcp-cli ... 等价于 uxc https://subgraphs.mcp.thegraph.com/sse ...。
• 仅在链接配置不可用时，临时回退至直接使用 uxc "" ...。
• 优先执行发现和 Schema 检查，再执行查询。
• 在生产环境或稳定工作流中，应优先基于 deployment 进行选择，而非依赖易变的“最新版本”引用。
• 首次查询时应限制 GraphQL 查询范围：
  • 添加过滤条件（filters）
  • 添加数量限制（limits）
  • 仅请求必需字段
• 若身份验证失败：
  • 确认 uxc auth credential info thegraph 执行成功
  • 确认 uxc auth binding match https://subgraphs.mcp.thegraph.com/sse 可解析为 thegraph
  • 重新运行 thegraph-mcp-cli -h

已验证的真实场景

以下流程已在真实端点上通过 uxc 成功执行：

• 搜索 uniswap 子图
• 使用 get_deployment_30day_query_counts 对候选结果进行对比
• 选取查询量最高的候选项
• 获取所选子图的 Schema
• 执行最简化的 _meta GraphQL 查询

本次运行中选定的候选项为：

• subgraph ID：5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV
• deployment IPFS hash：QmTZ8ejXJxRo7vDBS4uwqBeGoxLSWbhaA7oXa1RvxunLy7

经验证的最简化查询结构如下：

{
  _meta {
    deployment
    hasIndexingErrors
  }
}

参考资料

• 调用模式：
  • references/usage-patterns.md