three.ws Provenance

@three-ws/provenance-mcp

通过 MCP 记录 Agent 操作溯源——仅追加、采用 ERC-191 签名、可在链上验证。记录 Agent 执行的操作，并让其他 Agent 审计其操作轨迹；任何 AI 助手都能使用。

---

一个面向 three.ws Agent 信任层的 Model Context Protocol 服务。Agent 执行的每项操作都会写入仅追加的账本，并且可以选择使用 Agent 的 EVM 钱包进行签名（ERC-191），从而证明其作者身份，而非仅凭口头声称。本服务可让一个 Agent 记录自己的操作，并让任何 Agent 读取和加密验证其他 Agent 的溯源轨迹。

为何重要：分叉、购买或委托而来的 Agent，只有在其历史可验证时才值得信任。provenance-mcp 将“Agent 声称自己执行了 X”变为“Agent 签名确认自己执行了 X，任何人都可以通过 ecrecover 恢复签名者以进行验证”。账本不可变——记录永远不会被编辑或删除。

安装

npm install @three-ws/provenance-mcp

也可以通过 npx 运行（无需安装）：

npx @three-ws/provenance-mcp

快速开始

Claude Code，一行命令：

claude mcp add provenance --env THREE_WS_TOKEN=sk_live_… -- npx -y @three-ws/provenance-mcp

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"provenance": {
			"command": "npx",
			"args": ["-y", "@three-ws/provenance-mcp"],
			"env": {
				"THREE_WS_TOKEN": "sk_live_…",
				"THREE_WS_SIGNER_KEY": "0x…"
			}
		}
	}
}

使用 MCP Inspector 查看工具接口：

THREE_WS_TOKEN=sk_live_… npx -y @modelcontextprotocol/inspector npx @three-ws/provenance-mcp

工具

工具	类型	功能
list_agent_actions	只读	读取 Agent 的操作轨迹，按最新记录优先排序，并使用游标分页。每条记录都会在行内进行签名验证。
query_action	只读	按 ID 获取一项操作并恢复其签名者，以证明指定 Agent 创建了这项未经篡改的操作。
append_agent_action	写入	使用 ERC-191 对新操作签名，并将其追加到不可变账本。绝不覆盖或删除。

append_agent_action 是唯一的写入工具。它会将记录追加到仅追加的账本：每次调用都会创建一条新的永久记录（因此它不是幂等操作——不要盲目重试），而且任何内容都不会被覆盖或删除（因此它不会造成破坏）。

输入参数

list_agent_actions：agent_id（必填，Agent 身份的 uuid）、limit（1 到 200，默认值为 50）、cursor（数字，取自先前返回的 next_cursor）。

query_action：agent_id（必填，Agent 身份的 uuid）、id（必填，数字类型的操作 ID）。

append_agent_action：agent_id（必填，Agent 身份的 uuid）、type（必填，不超过 64 个字符）、payload（对象，可选）、source_skill（可选）、signer_key（可选的 0x EVM 密钥，在本次调用中覆盖 THREE_WS_SIGNER_KEY）。

签名与验证的工作原理

当你追加操作且配置了签名密钥时，服务端会：

1. 构建操作的规范化形式 — { v, agentId, type, payload, sourceSkill }，并递归排序键，以确保相同的逻辑操作始终生成相同的字节。
2. 对其计算 SHA-256 摘要，并将摘要封装为 threews:action:v1:<digest>（使用域分隔，因此操作签名绝不会被重放为其他 three.ws 消息）。
3. 使用 Agent 的 EVM 密钥对该字符串进行 ERC-191 personal_sign 签名，并将生成的 signature 和 signer_address 与操作一并发送。

list_agent_actions 和 query_action 会离线执行相反的操作：从存储的记录重新计算摘要，并通过 ecrecover 恢复签名者。verification.reason 为 ok 表示签名恢复出的地址与所声明的地址一致 — 这是作者身份和完整性的密码学证明。signer_mismatch 表示记录未通过验证（遭到篡改，或使用了其他签名方案），不得信任；unsigned 表示未附加签名。

这是 three.ws 在服务端为其 Portable & Verifiable Brain 使用的同一原语 — 验证只需要公开记录和 Agent 的地址。

示例

// append_agent_action
> { "agent_id": "6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913", "type": "launch", "payload": { "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "name": "$THREE" }, "source_skill": "pump-launch" }
{
  "ok": true,
  "action": {
    "id": "10482",
    "agent_id": "6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913",
    "type": "launch",
    "payload": { "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "name": "$THREE" },
    "source_skill": "pump-launch",
    "signature": "0x…",
    "signer_address": "0xAbC…",
    "created_at": "2026-06-24T18:20:00.000Z"
  },
  "signing": { "signed": true, "signer_address": "0xAbC…", "digest": "…" }
}

// query_action  →  verify it independently
> { "agent_id": "6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913", "id": "10482" }
{
  "ok": true,
  "action": { "id": "10482", "type": "launch", "signature": "0x…", "signer_address": "0xAbC…", /* … */ },
  "verification": { "signed": true, "valid": true, "reason": "ok", "recovered": "0xAbC…", "digest": "…" }
}

要求

• Node.js >= 20。
• 可访问网络 https://three.ws（或你自己的 THREE_WS_BASE）。
• 一个 THREE_WS_TOKEN — three.ws API 密钥（sk_live_…）或 OAuth 访问令牌。账本会对每次调用进行身份验证，并且限定所有者范围：你只能读取和追加你所拥有的 Agent 的操作。

环境变量

变量	必需	默认值	用途
THREE_WS_TOKEN	yes	—	用于对每次调用进行身份验证的 Bearer 令牌（API 密钥或 OAuth 访问令牌）。请像密码一样保管。
THREE_WS_SIGNER_KEY	no	—	0x EVM 私钥 — 设置后，append_agent_action 会对每个操作进行 ERC-191 签名。请像现金一样保管。
THREE_WS_BASE	no	https://three.ws	API 基础 URL — 用于覆盖以支持自托管或预览部署。
THREE_WS_TIMEOUT_MS	no	20000	每个请求的超时时间，单位为毫秒。

链接

• 主页：https://three.ws
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0。参见 LICENSE。

---

_{属于 three.ws SDK 套件 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}