secondlayer

@secondlayer/mcp

让你的编码 Agent 直接访问 Stacks 数据，可使用托管 API（ api.secondlayer.tools）或你自己的实例： Index（解码后的行）、Subgraphs（你定义的表，可从你的账户或实例提供服务）， 以及 Streams（原始输入）。仅提供核心路径工具：Index 读取、subgraph 生命周期、 webhook、合约发现与脚手架、实例状态、归档验证／引导，以及托管服务的额度／报价。其他所有功能（单条记录查询、内存池、质押、证明、实时 Streams 读取） 都可通过 REST /v1 + OpenAPI 使用。没有 consume 工具。

托管服务

无需安装：托管 API 通过 Streamable HTTP 提供读取工具，并支持浏览器登录。

claude mcp add --transport http secondlayer https://api.secondlayer.tools/mcp

不支持 OAuth 的客户端可发送 Authorization: Bearer <sk-sl_ key>。Subgraph 部署、webhook、归档、代码生成和实例工具仅限本地使用。参见 /docs/mcp。

安装

bun add @secondlayer/mcp

身份验证

大多数读取操作为公开访问：index_* 和 contracts_find 无需密钥即可使用。Subgraph 工具在访问非回环地址时需要 INSTANCE_TOKEN；通过 HTTP 访问 GET /v1/subgraphs/<name>/<table>（{ rows, next_cursor, tip } 游标封装）也需要该令牌；在回环地址上则无需身份验证。没有按 subgraph 区分的公开或私有标志。streams_dumps 无需密钥：转储清单是公开的；该工具只需配置 SL_STREAMS_DUMPS_URL。streams_tip 必须提供密钥（无密钥时返回 401）。实时 Streams 列表读取仅支持 REST（GET /v1/streams/*）。写入操作（部署、重建索引、删除、webhook）需要密钥，且密钥取决于主机：在 https://api.secondlayer.tools 上，服务器会自动使用 SECONDLAYER_API_KEY（sk-sl_*）；在其他任何地址上，则使用 secondlayer init 中的 INSTANCE_TOKEN。托管服务的额度／报价也使用 SECONDLAYER_API_KEY。在托管 API 上，subgraph 数据源仅限事件筛选器和 contract_call／contract_deploy（否则返回 422 SOURCE_NOT_HOSTABLE）；请设置 startBlock。请先读取 secondlayer://context：它会报告身份验证状态和读取权限级别。

快速开始 — Stdio（IDE）

将以下内容添加到你的 Claude Desktop 或 Cursor 配置中：

{
  "mcpServers": {
    "secondlayer": {
      "command": "bunx",
      "args": ["-p", "@secondlayer/mcp", "secondlayer-mcp"],
      "env": {
        "SECONDLAYER_API_URL": "http://127.0.0.1:3800",
        "INSTANCE_TOKEN": "..."
      }
    }
  }
}

快速开始 — HTTP（远程）

export SECONDLAYER_API_URL=http://127.0.0.1:3800
export INSTANCE_TOKEN=<from secondlayer init>
export SECONDLAYER_MCP_SECRET=your-secret
bunx -p @secondlayer/mcp secondlayer-mcp-http
# Listening on port 3100

环境变量

变量	必需项	默认值	说明
INSTANCE_TOKEN	在你的实例上执行写入操作	—	来自 secondlayer init。在 api.secondlayer.tools 以外的地址上执行写入工具时必需；读取操作为公开访问。不会发送到托管 API。
SECONDLAYER_API_KEY	托管 API、credits/quote/latest	—	sk-sl_*；当 SECONDLAYER_API_URL 为 https://api.secondlayer.tools 时自动使用。
SECONDLAYER_API_URL	否	http://127.0.0.1:3800	实例 API；托管服务使用 https://api.secondlayer.tools。
SECONDLAYER_BIN	CLI 工具	PATH 上的 secondlayer	CLI 二进制文件的路径（bootstrap、repair）。
SECONDLAYER_CWD	CLI 工具	进程工作目录	Compose 项目目录。
SECONDLAYER_MCP_PORT	否	3100	HTTP 传输端口。
SECONDLAYER_MCP_SECRET	否	—	用于 HTTP 身份验证的 Bearer 令牌。未设置时禁用。

工具

领域	工具
索引（9）	index_events、index_ft_transfers、index_nft_transfers、index_contract_calls、index_blocks、index_transactions、index_print_schema、index_discover、batch_query
子图（12）	subgraphs_list、subgraphs_status、subgraphs_spec、subgraphs_scaffold、subgraphs_deploy、subgraphs_delete、subgraphs_query、subgraphs_backfill、subgraphs_reindex、subgraphs_stop、subgraphs_operations、subgraphs_gaps
Webhooks（13）	webhooks_create、webhooks_list、webhooks_get、webhooks_update、webhooks_delete、webhooks_test、webhooks_pause、webhooks_resume、webhooks_rotate_secret、webhooks_deliveries、webhooks_dead、webhooks_requeue、webhooks_replay
流（2）	streams_tip、streams_dumps
合约（2）	contracts_find、contracts_get_abi
实例（1）	instance_status
归档（5）	archive_verify、archive_bootstrap、archive_repair、archive_latest、archive_quote
额度（1）	credits_balance（需要 SECONDLAYER_API_KEY）
账户（2）	account_whoami、account_create_key（仅当指向 https://api.secondlayer.tools 时）

执行变更后验证：部署／重新索引／回填／停止操作使用 subgraphs_operations， 创建／测试／重放操作使用 webhooks_deliveries。索引为空时： 运行 archive_bootstrap，轮询 instance_status，直到解码器状态正常，然后 运行 archive_verify，再运行 codegen_index_schema。

外围功能（单个区块／交易查询、内存池、质押、证明、 额度／上限、实时 Streams 读取／SSE）仅支持 REST：请参阅 API 主机上的 OpenAPI 规范。实时 Streams 列表读取使用 GET /v1/streams/events。

通过 SECONDLAYER_API_URL 将服务指向你的实例（默认值为 http://127.0.0.1:3800）。写入操作使用 secondlayer init 生成的 INSTANCE_TOKEN。只有当服务指向 https://api.secondlayer.tools 时， 才会显示 account_* 工具。

webhooks_create 触发器

Webhook 由原始链上事件触发。传入 triggers 数组（合约／事件／ 函数／特征），例如 [{ "type": "contract_call", "contractId": "SP....amm", "functionName": "swap-*" }]。若要响应子图行数据，请从你自己的 Postgres 读取表，或轮询子图 API。

subgraphs_query 增强功能

• fields — 以逗号分隔的列投影（例如 "sender,amount_x"）
• count — 布尔值，返回行数而非行数据
• 过滤运算符：eq、neq、gt、gte、lt、lte、like
• 最大限制：200

资源

URI	描述
secondlayer://context	实时状态 — 当前存在的内容（你的子图、webhook、账户）、你可以执行的操作，以及读取权限级别。请先阅读。
secondlayer://filters	子图源过滤器类型及其字段
secondlayer://column-types	列类型映射和选项
secondlayer://traits	SIP 特征标准（有效的 trait 值）
secondlayer://chain-triggers	链上 webhook 触发器类型及其字段

错误处理

所有工具都会返回结构化错误，并包含 isError: true：

{ "error": { "type": "not_found", "status": 404, "message": "Subgraph not found" } }

错误类型	状态码	发生情况
unauthorized	401	API 密钥无效或缺失
not_found	404	资源不存在
rate_limited	429	请求过多
server_error	5xx	服务端故障
error	其他	验证、打包等错误

打包／部署错误使用描述性前缀："Bundle failed:"、"Module evaluation failed:"、"Validation failed:"。HTTP 传输会强制执行 1MB 请求体限制（413）和 JSON 解析安全检查（400）。脚手架 ABI 获取超时为 10s。

程序化用法

import { createServer } from "@secondlayer/mcp";

const server = createServer();
// Connect to your own transport

许可证

MIT