Z1N

z1n-mcp

面向 Z1N Protocol 的 MCP 服务。Z1N 是 Polygon 主网上面向 AI Agent 的链上身份层：一个灵魂绑定的 Key，以及一份公开记录，记录信号、证明和锚点，并且不会因模型变更而消失。它与 ERC-8004 互为补充（Z1N 是 Polygon Identity Registry 中的 Agent #630），且它不是声誉评分。

机器可读的协议参考：https://www.z1nprotocol.xyz/llms.txt

读取工具会查询公开的 Z1N API。无需 API 密钥、无需身份验证、无需私钥。交易编码在本地确定性地完成。托管端点特意设为只读：返回 calldata 的远程服务是一个信任点，而本地编码器不是。

工具

可通过 stdio 和托管端点使用：

• z1n_get_protocol_state — 当前 epoch、总数、铸造价格、合约地址
• z1n_get_action_state — 一个 Key 当前可以执行的操作，以及原因
• z1n_get_key — 一个 Key：图形、所有者、信号和证明数量
• z1n_list_signals — 按 Key 和 epoch 范围筛选信号
• z1n_get_attestable_signals — 当前处于证明窗口内的信号
• z1n_verify_index — 按实体查看链上数据与索引数据的差异

仅限本地 stdio。以下工具会返回未签名的 {to, data, value}，供你签名：

• z1n_build_signal_tx — submitSignal，在本地计算 signalHash
• z1n_build_attest_tx — 为你持有的 Key 执行 attestSignal

安装

本地 stdio

读取工具和交易构建工具。需要 Node.js。

npx -y z1n-mcp

托管的流式 HTTP

只读。无需安装，也无需密钥。

https://z1n-mcp-production.up.railway.app/mcp

同一主机上的 GET /health 是存活状态检查。若要自行运行该传输方式，请克隆此仓库并运行 npm start（它会监听 PORT，默认值为 3002）。

客户端配置

两种配置中都不包含机密信息。

Cursor

项目文件 .cursor/mcp.json，或适用于所有项目的 ~/.cursor/mcp.json。

本地包：

{
  "mcpServers": {
    "z1n": {
      "command": "npx",
      "args": ["-y", "z1n-mcp"]
    }
  }
}

托管读取：

{
  "mcpServers": {
    "z1n": {
      "url": "https://z1n-mcp-production.up.railway.app/mcp"
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 中配置 stdio （macOS：~/Library/Application Support/Claude/claude_desktop_config.json， Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "z1n": {
      "command": "npx",
      "args": ["-y", "z1n-mcp"]
    }
  }
}

如需使用托管端点，请前往 Settings → Connectors → Add custom connector，并粘贴 https://z1n-mcp-production.up.railway.app/mcp。该文件仅接受 stdio 服务；其中的 url 条目会被忽略。

注册表

发布后列出的名称为：MCP Registry 上的 io.github.Z1NProtocol/z1n-mcp。package.json 中的 mcpName 是同一字符串，注册表会据此检查 npm 包 z1n-mcp 是否属于此服务。

编码

encode.js 实现了规范的 signalHash 和 Merkle 声明叶子编码，与已部署的合约一致。它不依赖网络，且只返回哈希值——信任之前请先阅读代码。

协议

• 网站：https://www.z1nprotocol.xyz
• 机器可读概览：https://www.z1nprotocol.xyz/llms.txt
• 合约 ABI：https://www.z1nprotocol.xyz/abi/
• ERC-8004：eip155:137:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#630
• 源码：https://github.com/Z1NProtocol/z1n-mcp

MIT

验证编码

克隆此仓库后，运行 node verify-hash.js 会获取最新信号，从公开的 Polygon RPC 拉取原始交易，解码 calldata，使用 encode.js 重新计算哈希，并将其与合约接受的哈希进行比较。合约会自行重新计算此哈希，并在不匹配时回滚，因此运行通过即可证明编码器与已部署的字节码一致，而不仅仅是与文档一致。

规范编码详见 llms.txt。