16ane sandbox wallet

@16ane/mcp-server — 面向 MCP 主机的 16ane 沙盒钱包适配器

将 16ane 测试网沙盒作为七种受限工具提供给兼容 MCP 的大模型主机（Claude Desktop、 Cursor、MCP 客户端）：服务发现、报价、余额查看和限额购买。通过 stdio 和 Streamable HTTP 使用 MCP 2026-07-28 （规范，核验于 2026-10-22）。无运行时依赖。

测试代币（tANE）——无现金价值。此适配器仅转移模拟测试网代币，不处理 INR、兑换或任何形式的真实价值。

快速开始：两步使用公共沙盒（#147）

需要 Node.js 24 或更高版本。无需克隆，也无需为 Agent 准备 ETH。

1. 创建 Agent 密钥。 此操作只会创建一个 Agent 密钥（~/.config/16ane/agent.key，权限模式为 0600），并打印 其地址。再次运行时会保留同一密钥。

npx -y @16ane/mcp-server init

2. 作为金库所有者，从你自己的钱包向该地址委托预算。 打开 init 打印的链接 （https://app.16ane.com/#/delegate?agent=0x…）。创建金库，用免费 tANE 为其注资，并为 Agent 签署固定预算。所有者的交易需要少量 Base Sepolia ETH；Agent 的付款则不需要。所有者密钥会保留 在你的钱包中：此服务完全没有所有者密钥选项。

3. 使用金库地址将服务添加到 MCP 主机。其他设置均默认为公共 Base Sepolia 沙盒和 https://api.16ane.com。

claude mcp add 16ane -e ANE_VAULT_ADDRESS=0xYourVault -- npx -y @16ane/mcp-server          # Claude Code

{ "mcpServers": { "16ane": { "command": "npx", "args": ["-y", "@16ane/mcp-server"], "env": { "ANE_VAULT_ADDRESS": "0xYourVault" } } } }

JSON 配置适用于 Claude Desktop（claude_desktop_config.json）和 Cursor（设置 → MCP）。服务启动时 会检查其密钥是否为金库的有效 Agent，否则拒绝运行。随后，Agent 可以发现服务、获取报价、检查预算并付款。每笔付款都受金库强制执行的预算限制。

该服务已在 MCP 注册表 中登记为 io.github.bytesbrains/16ane。软件包附带编译后的 JavaScript，且仅依赖 @16ane/sdk。在 检出目录中，运行 node --experimental-strip-types packages/mcp-server/src/main.ts（或 16ane-mcp-server 可执行文件；存在源文件时，该文件会运行源代码）。

工具

工具	效果
list_services	列出目录中的服务及其价格，并检查清单签名。只读。
get_quote	获取 402 报价但不付款；交叉核对来源清单。只读，绝不签名。
wallet_balance	金库 tANE 余额及基于链上状态的委托记账信息。只读。
payment_status	链上付款记录及可验证的收据查询。只读。
purchase_service	在 max_payment 和金库策略限制内支付一次服务调用。会花费资金。
publish_service	为此 Agent 自己的服务清单签名并注册。收入会记入其金库。
request_refund	根据链上记录准备退款请求。不转移资金；只有商家可以退款。

金额为基本单位的整数字符串（"16"）。每项服务描述、 报价和购买结果都是不可信的商家内容：在文本输出中会作为数据（绝非指令）进行隔离，在结构化输出中则标记为 untrusted: true。

安全模型

• 进程只持有一个密钥：委托的 agentSigner （ANE_AGENT_PRIVATE_KEY）。此处没有任何所有者密钥选项；请先在此服务之外（CLI、控制面板）完成资金存入、委托和撤销操作。
• 启动时，服务会在链上验证所持密钥确实是保险库委托的 agentSigner，且委托处于生效状态，否则拒绝提供服务。
• 支出受到三层限制：调用要求的 max_payment、可选的服务端 ANE_MCP_MAX_PAYMENT 上限，以及保险库的链上策略（真正的执行保障；提示词不具备此作用）。
• publish_service 不接受收款方、代币或网络覆盖选项：收入始终指向此保险库，以 tANE 结算，并使用已配置的网络。
• 密钥由 SDK 的 SecretKey 封装持有，绝不会出现在工具结果、错误、日志或标准输入输出中；test/security.test.ts 使用提示词注入测试样例对此进行了验证。
• 报价探测（get_quote）会将商家响应限制在 256 KiB，并在 30 秒后失败，避免恶意或故障的端点耗尽内存或导致调用挂起。
• Streamable HTTP 默认绑定到 127.0.0.1，验证 Origin，强制校验 MCP-Protocol-Version/Mcp-Method/Mcp-Name 标头与请求正文镜像，并支持 ANE_MCP_AUTH_TOKEN bearer 令牌（只要端点不再限于本地主机，就应设置令牌）。

配置

仅需设置 ANE_VAULT_ADDRESS。未设置网络参数时，服务会使用公共沙盒（https://sepolia.base.org、链 ID 84532、注册表 0x01d5daB670DE5868305eB862721ebE62772C3Df3、https://api.16ane.com）。若要使用其他链，请同时设置 ANE_RPC_URL 和 ANE_CHAIN_ID。Agent 密钥取自 ANE_AGENT_PRIVATE_KEY；若未设置，则使用 init 写入的文件（ANE_AGENT_KEY_FILE，默认值为 ~/.config/16ane/agent.key；如果其他用户可读取该文件，则会拒绝使用）。

export ANE_VAULT_ADDRESS="0x..."                # the vault whose owner delegated to this agent (required)
export ANE_RPC_URL="http://127.0.0.1:8545"      # optional, with ANE_CHAIN_ID: another chain (e.g. Anvil)
export ANE_CHAIN_ID="31337"                     # optional, with ANE_RPC_URL: 84532 or 31337
export ANE_AGENT_PRIVATE_KEY="0x..."            # optional: otherwise the init key file
export ANE_REGISTRY_ADDRESS="0x..."             # optional on the sandbox; or the four ANE_*_ADDRESS values below
# export ANE_TOKEN_ADDRESS / ANE_VAULT_FACTORY_ADDRESS / ANE_FAUCET_ADDRESS / ANE_SERVICE_DIRECTORY_ADDRESS
export ANE_API_BASE_URL="https://api.16ane.com" # service listing, publishing, receipts
export ANE_MCP_MAX_PAYMENT="16"                 # optional per-call ceiling (base units)

使用 stdio 运行（Claude Desktop、Cursor）

命令：node --experimental-strip-types /path/to/16ane/packages/mcp-server/src/main.ts （或在 npm install 后使用 16ane-mcp-server 可执行文件；它会使用该标志重新执行）。

Claude Desktop 配置（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "16ane": {
      "command": "node",
      "args": ["--experimental-strip-types", "/path/to/16ane/packages/mcp-server/src/main.ts"],
      "env": {
        "ANE_RPC_URL": "https://sepolia.base.org",
        "ANE_CHAIN_ID": "84532",
        "ANE_VAULT_ADDRESS": "0x...",
        "ANE_AGENT_PRIVATE_KEY": "0x...",
        "ANE_REGISTRY_ADDRESS": "0x...",
        "ANE_API_BASE_URL": "https://api.16ane.com",
        "ANE_MCP_MAX_PAYMENT": "16"
      }
    }
  }
}

Cursor 在 Settings → MCP → Add server（stdio 类型）中使用相同格式。 任何支持协议版本 2026-07-28 的 MCP 客户端均可使用；仅支持旧版 initialize 握手的客户端则不可用（此服务仅支持现代版本，并会以 JSON-RPC 错误 -32601 响应 initialize）。

使用 Streamable HTTP 运行（远程）

export ANE_MCP_TRANSPORT="http" ANE_MCP_PORT="8786"
export ANE_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export ANE_MCP_ALLOWED_ORIGINS="https://app.example.com"
node --experimental-strip-types packages/mcp-server/src/main.ts
# POST JSON-RPC to http://127.0.0.1:8786/mcp

每个 POST 请求都需要包含 MCP-Protocol-Version: 2026-07-28、Mcp-Method: <method>（调用 tools/call 时还需包含 Mcp-Name: <tool>），且这些标头须与请求正文中的 method 相对应；配置了令牌时，还需包含 Authorization: Bearer <token>。响应均为单个 JSON 对象（服务绝不会开启 SSE 流）；未知方法返回 404，协议违规返回 400，通知返回 202。

开发

npm run test:mcp    # or: make test-mcp (from the repo root)
npm run typecheck

目录结构：src/protocol.ts（MCP 2026-07-28 JSON-RPC 核心）、src/tools.ts（七个工具）、src/backend.ts（封装在可模拟接口后的 SDK/REST 接线）、src/stdio.ts、src/http.ts、src/config.ts、src/main.ts。测试与源文件一一对应；test/security.test.ts 是根据该问题验收标准编写的提示词注入测试套件。