proof

@toremlabs/proof-mcp

Proof 是 AI 编写代码的审计跟踪工具：它会记录 Agent 修改了什么、人员实际审查了什么，以及由谁签字确认。此软件包是它的 MCP 服务。

这是一个模型上下文协议（MCP）服务，可向任何支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor、Windsurf、自定义 Agent）提供 Proof 工作区。此服务会登录用户的 Proof 账户，与 Web 应用使用同一个 Supabase 项目通信，并遵循相同的 RLS。Web 应用和 MCP 是同一个云端工作区的两个前端。

当前版本：1.2.0。

要代表他人将其设置为 AI Agent？请改读 llms-install.md——步骤相同，但专为你编写，并标出了需要人工操作的一步。

安装

npm install -g @toremlabs/proof-mcp
# or on demand without installing:
npx -y @toremlabs/proof-mcp

npm 软件包名为 @toremlabs/proof-mcp，安装的命令为 proof-mcp，因此可直接运行子命令：

npx -y @toremlabs/proof-mcp login

快速入门

1. 将此设备关联到你的 Proof 账户

npx -y @toremlabs/proof-mcp login

CLI 会显示设备代码和一个一键访问 URL，格式为 https://proof.toremlabs.com/device?code=XXXX-XXXX。在浏览器中打开此 URL，若尚未登录则先登录，然后确认此设备。CLI 会在后台轮询，并在你确认后立即将凭据写入 ~/.proof/credentials.json（POSIX 系统上权限为 chmod 600）。之后运行 MCP 时不会显示提示。

登录流程会调用三个 Supabase Edge Functions：mcp-device-init、mcp-device-grant 和 mcp-device-poll。

要解除设备关联：运行 npx -y @toremlabs/proof-mcp logout，或在 Web 应用中打开「设置 ▸ 已连接的设备」以远程撤销。

运行 npx -y @toremlabs/proof-mcp whoami 可确认设备当前关联的账户。

2. 将 MCP 客户端指向此服务

Claude Desktop。 在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Windows 上编辑 %APPDATA%/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "proof": { "command": "npx", "args": ["-y", "@toremlabs/proof-mcp"] }
  }
}

Claude Code / Cursor / Windsurf。 在工作区根目录下放置 .mcp.json：

{
  "mcpServers": {
    "proof": { "command": "npx", "args": ["-y", "@toremlabs/proof-mcp"] }
  }
}

重启客户端。Proof 工具就会显示在工具菜单中。

3. CLI 子命令

npx -y @toremlabs/proof-mcp whoami        # show the linked account + device
npx -y @toremlabs/proof-mcp logout        # delete the credentials file
npx -y @toremlabs/proof-mcp --help        # all options
npx -y @toremlabs/proof-mcp --no-realtime # boot the server with live sync off (persisted)
npx -y @toremlabs/proof-mcp --realtime    # re-enable live sync

无头模式（CI、云端 Agent、临时容器）

设备配对会将刷新令牌写入磁盘。这在个人设备上效果很好，但无法在临时环境（CI 运行器、云端 Agent 容器、「Claude Code on the web」）中持久使用：每次运行之间文件系统都会被清除，而 Supabase 刷新令牌在轮换时是一次性使用的，因此写入配置的令牌在第一个会话后就会失效。

在这些环境中，请跳过配对，让服务在每次启动时使用账户邮箱和密码重新登录（密码使用后不会失效，因此无需重新配对即可一直使用）。设置三个环境变量：

[email protected]          # your Proof account email
PROOF_PASSWORD=your-account-password # secret — store it in a secrets manager
PROOF_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)
# optional: PROOF_SUPABASE_URL=...   # defaults to the production Proof project

如果设置了 PROOF_EMAIL 和 PROOF_PASSWORD，它们的优先级高于任何 credentials.json，MCP 服务会在每次启动时进行身份验证——无需关联设备。要求：

• 必须为 Supabase 项目启用邮箱和密码登录，且账户必须已设置密码（仅使用无密码登录 / 魔法链接的账户需先添加密码）。
• 将 PROOF_PASSWORD 视为机密。如果你的环境只能公开用户可见的环境变量，建议使用专用账户。

旧版环境变量名。 此服务以前名为 Heuresis，因此每个变量也接受其旧版 HEURESIS_* 名称（HEURESIS_EMAIL、HEURESIS_SNAPSHOT……）。如果两者均已设置，则优先使用 PROOF_* 名称。使用旧版 ~/.heuresis/ 目录完成配对的设备仍可正常使用——读取时会回退到该目录，下次写入时则会迁移到 ~/.proof/。

实时同步

MCP 以云模式启动时，会通过 Supabase Realtime 订阅工作区，并在 nodes、edges、projects 或 ideas 行发生变更时通知客户端。在 Web 应用中进行的编辑无需手动刷新，就会显示在 Agent 的视图中；一个 MCP 连接客户端所做的写入也会以相同方式传达给其他已连接客户端。传入 --no-realtime 可禁用订阅（如果通知过多，或客户端会记录每条通知，这会很有用）。此偏好会保存到 ~/.proof/config.json，因此只需传入一次该标志。

工具

共 53 个工具：49 个用于操作云工作区的数据工具，以及 4 个用于驱动与 Web 应用相同构思运算符的操作工具。

读取。 get_workspace_summary、list_projects、get_project_graph、 get_subtree、list_concepts、list_edges、get_concept、search_concepts、 find_concepts、find_orphans、list_recent_decisions。大多数 Agent 会话 会从 get_workspace_summary 或 list_projects 开始。

概念写入。 add_concept、update_concept、bulk_add_concepts、 set_parent、link_concepts、add_kref、validate_concept、set_standing、 archive_concept、unarchive_concept、star_concept、remove_concept、 remove_concepts。

构思和项目写入。 create_idea、rename_idea、recolor_idea、 set_idea_members、add_to_idea、delete_idea、create_project、 update_project、delete_project。

Agent 运行与移交。 list_agent_runs、get_agent_run、 update_agent_run、list_pending_handoffs、claim_handoff。

证据、证明与审核。 add_evidence、add_challenge、record_proof、 get_concept_proof、list_proofs、list_verification_records、 get_verification_record、submit_review_summary。

每次针对概念的写入都会在 public.provenance 中记录一行，其中 origin='mcp'，因此 Web 应用的会话日志会显示变更来自哪个界面和设备。构思、项目或 Agent 运行层面的写入则不会：来源记录行以节点为键（node_id NOT NULL），而这些操作没有可供指向的单一概念。

运算符（4 个）。 run_operator（使用 Branch / Matrix / ASIT / TRIZ / Combine / Free / Contradiction 生成候选项）、run_operator_and_commit（相同操作， 并在一次往返中提交结果）、expand_concept（递归 Branch； 展开是几何级数增长的，因此上限取决于所进行的模型调用次数， 而不是深度 × 广度），以及 get_run（获取之前的运算符运行）。

工具输入格式与 Web 应用中的 src/agent/tools.ts 对应项一致， 因此同时使用这两个界面的 Agent 会看到统一的接口约定。

快照模式（只读）

无需凭据，服务端即可从磁盘读取 JSON 工作区导出文件，并 提供只读工具集（get_workspace_summary、list_projects、 search_concepts、get_concept、get_subtree、get_project_graph、 list_recent_decisions）。将 PROOF_SNAPSHOT 指向该文件：

export PROOF_SNAPSHOT="/absolute/path/to/your-export.json"
npx @toremlabs/proof-mcp

通过“设置” → “工作区” → “导出”从 Web 应用导出工作区。此模式 方便离线或只读使用；云模式是主要使用方式。

许可证

AGPL-3.0-or-later。