SQD

SQD Portal MCP 服务

一个可从 SQD Portal 数据中回答区块链问题的 MCP 服务：涵盖 EVM、Solana、Bitcoin、Substrate、Hyperliquid 和 Tron 网络上的交易、日志、调用轨迹、代币转账、钱包、分析、时间序列和蜡烛图，并提供可选的内置 Explorer。

该服务本身不会为链建立索引。它会验证输入、规划范围受限的 Portal 查询，并返回带有覆盖范围、新鲜度、分页和证据元数据的结果，让助手能够准确说明自己看到了什么。无需 SQD 账户、API 密钥或客户端凭据。

它通过 HTTP 和 stdio 使用无状态 MCP 2026-07-28 协议，并保留由 SDK 管理的旧版协商路径，以支持仍在逐步采用该修订版的客户端。发布说明见 CHANGELOG.md。如需参与代码开发，请参阅 CONTRIBUTING.md；如需报告漏洞，请参阅 SECURITY.md。

当前公开接口

• 28 个公开工具
• 3 个高级／调试工具
• 公开参数使用 network
• 发现筛选条件使用 vm
• v0.8.x 中没有旧版工具别名

原始查询工具默认返回精简响应。只有在需要更大负载时，才请求 response_format: "full"。

实体问题可以先使用 portal_resolve_entity。它会将 EVM 代币符号／地址、EVM 合约别名、池标识符、协议名称和 Hyperliquid 币种名称解析为可直接用于查询的筛选条件，同时明确标示存在歧义的匹配项。

代币符号解析和代币元数据来自开放的代币列表数据，而非内置的代币地址常量。如果某个网络的代币列表数据不可用、已过时或不受支持，响应中会明确说明。

钱包问题应从 portal_get_wallet_summary 开始。默认情况下，它会返回 fund_flow，包括流入／流出变动、资产流向、交易对手方、观察到的最大变动，以及进行原始工具深入查询的后续证据线索。

工具组

发现：

• portal_list_networks
• portal_get_network_info
• portal_get_head
• portal_resolve_entity

跨链便捷工具：

• portal_get_recent_activity
• portal_get_wallet_summary
• portal_get_time_series

EVM：

• portal_evm_query_transactions
• portal_evm_query_logs
• portal_evm_query_traces
• portal_evm_query_token_transfers
• portal_evm_get_contract_deployment
• portal_evm_get_contract_activity
• portal_evm_get_analytics
• portal_evm_get_ohlc

Solana：

• portal_solana_query_transactions
• portal_solana_query_instructions
• portal_solana_get_analytics

Bitcoin：

• portal_bitcoin_query_transactions
• portal_bitcoin_get_analytics

Substrate：

• portal_substrate_query_events
• portal_substrate_query_calls
• portal_substrate_get_analytics

Hyperliquid：

• portal_hyperliquid_query_fills
• portal_hyperliquid_get_analytics
• portal_hyperliquid_get_ohlc

Tron：

• portal_tron_query_transactions
• portal_tron_query_logs

高级／调试：

• portal_debug_query_blocks
• portal_debug_resolve_time_to_block
• portal_debug_hyperliquid_query_replica_commands

这些分组也对应工具集（discovery、convenience、evm、solana、bitcoin、substrate、hyperliquid、tron、debug）。部署时可以通过 MCP_TOOLSETS 或 MCP_TOOLS 精简目录；HTTP 连接还可以通过 ?toolsets= 或 X-MCP-Toolsets 标头进一步缩小范围；详情请参阅 HTTP 部署说明。未配置任何选项时，将提供完整的 31 个工具接口；托管端点也保留此默认设置。

支持的数据

• Portal 索引的 EVM 网络，包括 Base、Ethereum、Optimism、Arbitrum、Monad、Hyperliquid EVM 等许多网络
• Tron 原生交易（TRX 转账、TRC-10 转账、带内联日志和内部交易的合约调用）以及 TVM 事件日志（例如 TRC-20 转账），支持 Base58 或十六进制地址、精确的 TRX 金额，并在每条日志中包含父交易哈希；对于其他用法，捆绑的 SQD 插件技能会介绍原始 Stream API
• Solana 主网
• Bitcoin 主网
• Hyperliquid 成交和副本命令
• Portal 索引的 Substrate 网络

目前，Substrate 仅支持历史数据，不支持实时追踪。

响应结构

大多数工具会在 MCP structuredContent 中返回相同的封装结构；对于较旧的客户端，也会以紧凑的 JSON 文本作为回退格式。封装结构包含常规结果正文，以及以下共享元数据：

• answer
• display
• next_steps
• investigation
• _freshness
• _coverage
• _pagination
• _ordering

investigation 是面向 Agent 的精简证据指南：它会指出主要结果路径、限定范围的时间窗口、有用的转换字段（例如地址或交易哈希）、后续筛选条件，以及将结果视为完整结果之前需要了解的限制。成功且包含实质内容的结果还会附带 _evidence 收据，其中包含规范参数、确定性摘要、行数核对、数据源时间窗口，以及精确或语义重放语义。精确收据会固定证据时间窗口。语义收据会说明，重新运行一个会变化的相对时间窗口可能会返回更新的快照。

当响应使用估算、部分、抽样、封顶或分页数据时，顶层答案和元数据会明确说明。_pagination.has_more 仅当存在 next_cursor 时才为 true；_coverage 会说明是否已完整读取请求的时间窗口（window_complete），以及响应是否包含所有匹配行（result_complete）。安全的分页后续操作会包含可执行的工具调用元数据，并明确提供游标参数；无法安全重建的建议会标记为不可执行。

面向图表的工具还会返回图表和表格描述符，供 MCP 客户端或大模型直接渲染，无需逆向分析载荷。

SQD Explorer（测试版）

SQD Explorer 是一款 MCP App，可在支持 MCP Apps 的宿主中呈现工具结果。它目前处于测试版，默认关闭。默认部署只会返回 structuredContent 和精简的 JSON 文本，不会让任何工具结果请求宿主打开界面。你可以通过以下两种方式选择启用：

• 单个连接：在端点后添加 ?app=1，例如 https://portal.sqd.dev/mcp?app=1。这样可以体验测试版，而不影响其他用户。
• 整个部署：设置 MCP_APP_ENABLED=true。连接仍可双向覆盖此设置，因此 ?app=0 可让单个客户端重新选择退出。

无论是否选择启用，App 资源都会保持注册状态，因此宿主无需任何人选择启用即可直接读取。

启用后，兼容的宿主会收到一张按内容调整大小的内嵌卡片，以及一个全屏工作区，适用于 21 个数据工具：以主要数值为核心的指标、多序列和带符号值图表、带关联成交量和固定读数的价格蜡烛图、显示十行并带有“显示全部”控件的排名和时间线面板、每页显示十行且可搜索所有行的证据表、地址、哈希和区块的浏览器链接、来自 SQD 网络元数据的链徽标和名称、续传控件、当前会话历史记录，以及通过宿主进行的 JSON 或 CSV 导出。通过指针和键盘检查可查看精确的绘制值。缺失的数据桶仍会显示为空档，标识符不会缩短，任何本地行数上限都与服务器端数据完整性无关。后续请求失败时，错误下方仍会保留最近一次成功的结果。此 App 完全自包含，不使用持久化的浏览器存储；它在浏览器端唯一发出的请求是链徽标图片，来源为 cdn.subsquid.io 和 sqd.dev，这两个源已在资源 CSP 中声明。不支持 MCP App 的宿主会收到相同的 structuredContent 和精简 JSON 文本回退结果，因此底层答案始终不依赖 UI。docs/explorer-design.md 记录了此 App 遵循的设计规则。

三个 MCP 提示词提供可复现的起始示例，无需添加工具：

• investigate-wallet
• investigate-contract
• investigate-market

如需以图表为主的演示，请询问：Show BTC price action and trading volume on Hyperliquid for the past hour, using five-minute candles. Explain whether the final candle is closed.结果会打开 SQD Explorer，显示蜡烛图、成交量、证据表、请求和索引的时间范围，以及回执。需要进行稳定的验证运行时，请将返回的 requested_window_start_timestamp 和 requested_window_end_exclusive 作为固定的 from_timestamp 和 to_timestamp 输入重放。

在 Claude 中试用

托管端点默认关闭 Explorer，因此新用户需要为自己的连接选择启用：

1. 在 claude.ai 或 Claude Desktop 中，打开 设置 → 连接器 → 添加自定义连接器，输入 https://portal.sqd.dev/mcp?app=1，并选择无需身份验证。?app=1 仅会为此连接启用测试版。在 Claude Desktop 中，你也可以安装最新版本中的 sqd.mcpb，并开启“SQD Explorer (beta)”设置。
2. 开始新聊天，并为该聊天启用 SQD 连接器。
3. 提出数据问题。以下问题都能调用带有 Explorer 的工具：
   • What has this wallet been doing on Base lately?，并附上地址（钱包摘要）
   • Show me recent activity on Ethereum（近期活动）
   • Chart hourly transaction counts on Base for the last day（时间序列）

结果会呈现为内嵌卡片，而不是一段文本；打开卡片即可进入全屏工作区。只有 21 个数据工具带有 Explorer。诸如 Which networks do you support? 这样的目录问题会调用 portal_list_networks 并以纯文本作答，这是预期行为，并非故障。

安装

npm install
npm run build

运行

stdio：

npm start

HTTP：

npm run start:http

开发者发现

该服务为客户端构建者提供结构化的工具选择指南：

• MCP 资源 sqd://tools 返回分组的工具元数据、示例、入门指引和集成说明。
• MCP 资源 sqd://tools/{name} 返回单个工具的指南条目，例如 sqd://tools/portal_get_time_series。

工具和资源发现仍通过 MCP 协议本身进行。该服务不会维护重复的 HTTP 目录。

Codex 插件

Codex 插件封装位于 plugins/portal，默认使用托管 MCP 端点 https://portal.sqd.dev/mcp。

从此仓库本地的市场安装：

codex plugin marketplace add .
codex plugin add portal@sqd

安装后打开一个新的 Codex 对话线程。首次使用的提示词包括 Hyperliquid BTC 永续合约成交、近期 Base 交易量，以及 Base 上最新的 USDC 转账。

Claude Code 插件

Claude Code 插件使用相同的托管 MCP 端点和相同的公共选择器：

claude plugin marketplace add subsquid-labs/portal-mcp-server
claude plugin install portal@sqd

安装后打开一个新的 Claude Code 会话，以便加载 SQD MCP 工具。

Grok

Grok 聊天可以将 SQD 用作自定义连接器：

1. 打开 grok.com/connectors。
2. 选择 新建连接器，然后选择 自定义。
3. 将 https://portal.sqd.dev/mcp 输入为 MCP 服务 URL。
4. 将身份验证留空。

Grok Build 可直接读取 Claude Code 插件，因此使用相同的软件包：

grok plugin install --trust subsquid-labs/portal-mcp-server#plugins/portal

ChatGPT

在启用了自定义 MCP 应用的工作区中，打开 设置 → 应用 → 创建，输入 https://portal.sqd.dev/mcp，选择不使用身份验证，扫描工具，然后创建草稿应用。该服务为只读服务，不需要用户凭据。

Claude Desktop

从最新版本下载 sqd.mcpb 并打开：Claude Desktop 只需单击一次即可安装该捆绑包，并列出 31 个工具。该捆绑包包含服务、其生产依赖项，以及一个可选设置“SQD Explorer (beta)”，该设置默认关闭。运行所需机器上的 Node 版本为 22 或更高。

手动备用方案：从本地克隆仓库运行 npm run build 后，将类似下面的条目添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "SQD": {
      "command": "node",
      "args": ["/absolute/path/to/sqd-portal-mcp-server/dist/index.js"]
    }
  }
}

使用说明

• 如果不知道确切的网络名称，请从 portal_list_networks 开始。
• 如果需要近期索引状态，请先使用 portal_get_network_info 或 portal_get_head。
• 如果问题范围较广，请先使用 portal_get_recent_activity、portal_get_wallet_summary 或 portal_get_time_series，再使用原始查询。
• 时间范围接受简写和自然语言，例如 30m、past 30 minutes、in the past 1h、in last 38 mins、last hour 或 30 minutes ago。
• 仅在确实需要蜡烛图形状的输出时，才使用 portal_evm_get_ohlc 和 portal_hyperliquid_get_ohlc。
• 对于大型查询或探索性查询，除非需要完整记录结构，否则优先使用 response_format: "compact"。

HTTP 部署说明

HTTP 模式在 / 和 /mcp 提供 MCP，在 /health 提供存活状态检查，在 /ready 提供就绪状态检查。托管服务在 https://portal.sqd.dev/mcp/health 提供相同的版本化健康状态响应。

• MCP 和健康检查端点无需身份验证。
• 工具和资源发现使用 MCP 协议；已停用的 /tools 和 /tools.json 路由会返回 404。
• 运行多个进程的部署必须设置 MCP_CURSOR_SECRET，这样一个实例签发的游标才能被下一个实例接受。若不设置，每个进程都会使用各自的随机密钥签名，游标在重启或负载均衡切换后将失效。
• /health 会报告镜像构建所用的 git 提交对应的 version 和 commit，每个工具结果也会在 _server 中重复包含这两项。Docker Hub 标签：latest、X.Y.Z 和 X.Y 仅来自 v* 发布标签；edge 和 sha-<commit> 来自每次 main 推送。生产环境请固定使用版本标签。
• 只有在数据集目录至少加载过一次，且最近一次 Portal 探测成功时间距今未超过 MCP_READY_MAX_AGE_MS 时，/ready 才返回 200；否则返回 503，并附带 reason 和 Retry-After。编排器的就绪检查应指向 /ready，存活检查应指向 /health。Docker 镜像的 HEALTHCHECK 使用 /ready。
• 除非另行设置 MCP_BIND，服务器会绑定到 127.0.0.1；每个路由都会根据允许列表检查 Host 标头，以及浏览器发送的 Origin，因此经 DNS 重绑定的页面无法访问本地实例。环回主机和来源始终通过检查；没有 Origin 的请求始终通过来源检查。绑定到非环回地址时，必须设置 MCP_ALLOWED_HOSTS 和 MCP_ALLOWED_ORIGINS；如果缺少其中任一项，服务器会记录启动错误，并在不进行该项检查的情况下提供服务。Docker 镜像会设置 MCP_BIND=0.0.0.0，因此请在部署中设置这两个变量；如果前置代理已验证这些值，也可以设置为 *。
• 每个请求都有时限：标头必须在 MCP_HEADERS_TIMEOUT_MS 内接收完毕，整个请求必须在 MCP_REQUEST_TIMEOUT_MS 内完成，空闲的 keep-alive 连接时限为 MCP_KEEP_ALIVE_TIMEOUT_MS。超过 MCP_MAX_BODY_BYTES 的 MCP 请求体会在解析前被拒绝并返回 413；没有长度的分块请求体会返回 411。

常用环境变量：

• MCP_CURSOR_SECRET 用于签名分页游标的密钥。在运行多个进程的任何部署中都必须设置。 未设置时，每个进程都会使用自己的随机密钥签名，因此某个实例发出的游标会被下一个实例拒绝，客户端在重启或负载均衡切换后会丢失进度。它还可以防止调用方伪造工具从未提供过的窗口对应的游标。
• MCP_TOOLSETS 要提供的工具集，以逗号分隔（discovery、convenience、evm、solana、bitcoin、substrate、hyperliquid、tron、debug；all 或 default 表示全部）。未知名称会被忽略，并在启动时报告错误。优先级高于 MCP_TOOLS。默认值：全部九个工具集，共 31 个工具的完整目录。
• MCP_TOOLS 当未设置 MCP_TOOLSETS 时，要提供的精确工具名称，以逗号分隔。
• 对于每个连接，在端点 URL 中添加 ?toolsets=evm，或添加 X-MCP-Toolsets: evm 标头，只会缩小该连接可用的部署工具集范围，绝不会添加工具集。引用了当前启用范围之外工具的提示词不会提供。mcp_tool_client_calls_total 上的启用范围是有界标签（all、单个工具集名称或 custom）。
• MCP_BIND 要监听的接口，默认值为 127.0.0.1（Docker 镜像中为 0.0.0.0）
• MCP_ALLOWED_HOSTS 在回环地址之外，允许出现在 Host 中的主机名，以逗号分隔（忽略端口）；* 表示禁用检查。绑定非回环地址时必须设置。
• MCP_ALLOWED_ORIGINS 在回环地址之外，允许出现在 Origin 中的主机名，以逗号分隔；* 表示禁用检查。绑定非回环地址时必须设置。
• MCP_REQUEST_TIMEOUT_MS、MCP_HEADERS_TIMEOUT_MS、MCP_KEEP_ALIVE_TIMEOUT_MS 请求计时限值，默认值分别为 120000、30000、65000
• MCP_MAX_BODY_BYTES MCP 请求正文大小上限，默认值为 1048576
• MCP_READY_PROBE_INTERVAL_MS 和 MCP_READY_MAX_AGE_MS 就绪探测频率和新鲜度，默认值分别为 30000 和 90000
• MCP_APP_ENABLED 是否向兼容的主机提供 Beta 版 SQD Explorer，默认关闭。接受 true 或 1。每个连接可通过 ?app=1 和 ?app=0 覆盖此设置。
• MCP_TOOL_WEIGHT_BUDGET 用于限制活跃工具调用的总成本，默认值为 32。根据测得的配置文件，在队列中仍有待处理工作时，最多可同时进行 32 次查询、4 次原始或摘要调用，或 2 次分析调用；已排队的工作仍可感知取消操作。
• MCP_TOOL_MAX_QUEUE 用于限制排队的工具调用数，默认值为 64
• MCP_TOOL_QUEUE_TIMEOUT_MS 用于限制工具准入等待时间，默认值为 5000
• MCP_TOOL_CLIENT_WEIGHT_SHARE 单个调用方（一个连接，通过哈希地址标识）一次最多可占用的权重预算百分比，默认值为 50；不会低于单个最重工具所需的权重，确保每个工具都能获得调度。MCP_TOOL_CLIENT_MAX_QUEUE 限制单个调用方的排队调用数，默认值为 16。超过份额的调用方会收到可重试的 overloaded 结果，其中 reason: client_share；其他调用方的请求则不受影响。
• MCP_TRUST_PROXY 设置为 1（或服务器前方代理的数量），根据代理观测到的地址而非套接字地址进行公平性管理。只有当直接对端本身是受信任代理时，才会读取该标头；跳数从 X-Forwarded-For 的右侧开始计数，因为调用方可以随意填写左侧的内容。地址会经过哈希处理，且绝不存储或作为标签。
• MCP_TRUSTED_PROXY_PREFIXES 以逗号分隔的地址前缀列表，用于指定受信任的代理；通过匹配对端地址的开头进行判断（例如 203.0.113. 或 2606:4700:）。设置此项会替换默认值，而不是在默认值上追加，因此如果同机代理也能访问服务器，请将回环地址或你的私有地址范围包含在内。未设置时，回环地址和私有地址范围会被信任；同机代理通常位于这些范围内。在共享私有网络中，这意味着该网络上的任何主机都能提供转发地址，因此应在此类网络中明确指定代理。
• MCP_SLOW_REQUEST_MS 用于判定慢速请求的阈值；每次工具调用超过此阈值时，会向 stderr 输出一行 JSON，其中包含准入等待时间、执行耗时和有界的客户端类别。默认值为 5000。

成本护栏

服务中编译了每种工具各自的扫描上限：筛选后的跟踪扫描最多处理 5,000 个区块，合约部署搜索最多处理 1,000,000 个区块。护栏会在这些上限之上再增加一层上限，由部署通过环境变量设置，因此端点负载过高时，无需构建新镜像即可调低上限。

• MCP_GUARDRAIL_MODE 可设为 off（默认值）、shadow 或 enforce。
• MCP_GUARDRAIL_<CLASS>_<LIMIT> 用于设置一项上限，其中 <CLASS> 为 LOOKUP、RAW_QUERY、SUMMARY 或 ANALYTICS，<LIMIT> 为 MAX_SCAN_BLOCKS、MAX_WINDOW_SECONDS 或 MAX_UPSTREAM_BYTES。例如：MCP_GUARDRAIL_RAW_QUERY_MAX_SCAN_BLOCKS=50000。

没有任何数值默认值。 某个类别如果没有设置任何值，就不会增加额外上限，因此未配置任何值时，off 和 enforce 下的服务完全相同。只有设置数值，护栏才会改变行为。

shadow 会评估每项上限，并记录启用强制执行时会采取的操作，但不会更改任何响应。enforce 会实际执行：

• 扫描超过上限时，会在上限处停止，并通过扫描达到编译上限时已有的相同部分覆盖处理路径，报告已覆盖的范围。因此，_coverage.result_complete 会变为 false，响应也会列出搜索过的区块。它绝不会声称得到了实际上并未获取的完整答案。
• 查询时间窗口超过上限时，会在获取任何数据之前拒绝请求，并在错误中指出上限及后续步骤，因为对于尚未获准启动的请求，无法返回部分结果。

四个计数器，标签均有界：mcp_guardrail_admitted_total{class}、 mcp_guardrail_would_block_total{class,limit}、 mcp_guardrail_blocked_total{class,limit} 和 mcp_guardrail_fail_open_total{reason}。

建议的推出方式。 设置你正在考虑的上限，并运行 shadow 一周。查看 mcp_guardrail_would_block_total：其中记录的正是上限会拦截的实际请求。如果这类请求的数量超出预期，说明上限设错了，而不是流量有问题。达到预期规模后，再切换到 enforce。

追踪

指标说明发生的频率和持续时间；追踪则说明一次调用中时间花在了哪里。除非设置了 OTEL_EXPORTER_OTLP_ENDPOINT，否则追踪处于关闭状态。未设置该变量时，这里不会导入、分配或发送任何内容，也完全不需要安装 OpenTelemetry 软件包。

此软件包不依赖 SDK。SDK 及其导出器会额外引入约 74 个软件包，而已发布的 tarball 大约有 3.4MB；几乎没有通过 stdio 运行此服务的人会需要这些内容，因此它们被声明为可选对等依赖。若要启用追踪，请将它们与服务一同安装，并将服务指向你的收集器：

npm i @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

一次工具调用对应一棵追踪树：

mcp.request                       (HTTP only: method, transport)
└─ tools/call portal_evm_query_logs
   ├─ mcp.admission               (the wait for a slot)
   ├─ portal.fetch                (one per attempt: dataset, status, bytes, resend count)
   ├─ portal.fetch
   └─ mcp.format_result           (hashing the answer for the evidence receipt)

OpenTelemetry SDK 本身会读取 OTEL_* 变量，因此采样、标头、批处理和协议都按标准方式配置。其他说明：

• HTTP 请求中的 traceparent，或工具调用 _meta 中的 traceparent，会让此次调用加入调用方的追踪，而不是启动新的追踪。_meta 中的值优先，因为它对本次调用属于哪一轮有更具体的说明。
• 每个 Portal 请求都会携带一个 traceparent，用于标识其自身的 fetch span，因此 Portal 侧的追踪可以加入此次追踪。关闭追踪时不会添加任何内容。
• 启用追踪时，JSON 日志行会携带 trace_id 和 span_id，因此可以通过日志事件和 span 相互查找。
• /health 会报告是否已配置追踪、是否已启动追踪，以及是否启用了参数采集。

Span 属性不包含任何参数、地址、哈希值、游标或自由文本。它们仅包含工具名称、工作类别、数据集、有限范围内的计数和有限范围内的结果。Span 会离开进程并发送到收集器，而查询本身绝不会到达那里，因此这里遵循与指标标签相同的规则，并且比日志更严格；至少日志只会留在你自己的 stderr 中。MCP_OTEL_INCLUDE_ARGS=1 会将原始工具参数添加到工具 span 中。默认关闭，且不适合用于生产环境：工具参数通常是钱包地址，也常常包含用户自己的原话。

测试

npm run test:offline 会构建、检查代码风格、进行类型检查、运行单元测试，并运行所有不需要访问 Portal 的测试套件。npm run test:live 会运行依赖 Portal 的测试套件。RELEASE_ASSURANCE.md 概述了发布验证的内容，scripts/README.md 列出了所有测试套件。

许可证

MIT