{
  "markdown": "# @toremlabs/proof-mcp\n\n[Proof](https://proof.toremlabs.com) is an audit trail for AI-written code: it\nrecords what the agent changed, what a person actually reviewed, and who signed\noff. This package is its MCP server.\n\nA Model Context Protocol (MCP) server that exposes a Proof\nworkspace to any MCP-capable client (Claude Desktop, Claude Code, Cursor,\nWindsurf, custom agents). The server logs into the user's Proof account,\ntalks to the same Supabase project the webapp talks to, and respects the\nsame RLS. Webapp and MCP are two front-ends to one cloud workspace.\n\nCurrent version: `1.2.0`.\n\n> Setting this up as an AI agent on someone's behalf? Read\n> [`llms-install.md`](./llms-install.md) instead — same steps, written for you,\n> and it flags the one step that needs a human.\n\n## Install\n\n```bash\nnpm install -g @toremlabs/proof-mcp\n# or on demand without installing:\nnpx -y @toremlabs/proof-mcp\n```\n\nThe npm package is `@toremlabs/proof-mcp` and the command it installs is\n`proof-mcp`, so subcommands run directly:\n\n```bash\nnpx -y @toremlabs/proof-mcp login\n```\n\n## Quickstart\n\n### 1. Link this machine to your Proof account\n\n```bash\nnpx -y @toremlabs/proof-mcp login\n```\n\nThe CLI prints a device code and a one-click URL of the form\n`https://proof.toremlabs.com/device?code=XXXX-XXXX`. Open it in your browser,\nsign in if you aren't already, and confirm the device. The CLI polls in the\nbackground and writes credentials to `~/.proof/credentials.json` (chmod 600 on\nPOSIX) the moment you confirm. Subsequent runs of the MCP are silent.\n\nThe login flow rides three Supabase Edge Functions: `mcp-device-init`,\n`mcp-device-grant`, and `mcp-device-poll`.\n\nTo unlink a machine: `npx -y @toremlabs/proof-mcp logout`, or open\nSettings ▸ Connected devices in the webapp to revoke remotely.\n\n`npx -y @toremlabs/proof-mcp whoami` confirms which account a machine is\ncurrently linked to.\n\n### 2. Point your MCP client at it\n\n**Claude Desktop.** Edit\n`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,\nor `%APPDATA%/Claude/claude_desktop_config.json` on Windows:\n\n```json\n{\n  \"mcpServers\": {\n    \"proof\": { \"command\": \"npx\", \"args\": [\"-y\", \"@toremlabs/proof-mcp\"] }\n  }\n}\n```\n\n**Claude Code / Cursor / Windsurf.** Drop a `.mcp.json` in the workspace root:\n\n```json\n{\n  \"mcpServers\": {\n    \"proof\": { \"command\": \"npx\", \"args\": [\"-y\", \"@toremlabs/proof-mcp\"] }\n  }\n}\n```\n\nRestart the client. The Proof tools appear in the tool menu.\n\n### 3. CLI subcommands\n\n```bash\nnpx -y @toremlabs/proof-mcp whoami        # show the linked account + device\nnpx -y @toremlabs/proof-mcp logout        # delete the credentials file\nnpx -y @toremlabs/proof-mcp --help        # all options\nnpx -y @toremlabs/proof-mcp --no-realtime # boot the server with live sync off (persisted)\nnpx -y @toremlabs/proof-mcp --realtime    # re-enable live sync\n```\n\n## Headless mode (CI, cloud agents, disposable containers)\n\nDevice pairing writes a **refresh token** to disk. That works great on a\npersonal machine, but it does **not** survive disposable/ephemeral\nenvironments (CI runners, cloud agent containers, \"Claude Code on the web\"):\nthe filesystem is wiped between runs, and a Supabase refresh token is\n**single-use under rotation** — so a token baked into config dies after the\nfirst session.\n\nFor those environments, skip pairing and let the server **sign in fresh on\nevery boot** from your account email + password (a password is not consumed on\nuse, so it works forever with no re-pairing). Set three env vars:\n\n```bash\nPROOF_EMAIL=you@example.com          # your Proof account email\nPROOF_PASSWORD=your-account-password # secret — store it in a secrets manager\nPROOF_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)\n# optional: PROOF_SUPABASE_URL=...   # defaults to the production Proof project\n```\n\nWhen `PROOF_EMAIL` + `PROOF_PASSWORD` are present they take precedence over any\n`credentials.json`, and the MCP server authenticates per boot — no device link\nrequired. Requirements:\n\n- Email + password sign-in must be enabled for the Supabase project, and the\n  account must have a password set (passwordless / magic-link-only accounts\n  need a password added first).\n- Treat `PROOF_PASSWORD` as a secret. Prefer a dedicated account if your\n  environment can only expose env vars that are visible to its users.\n\n> **Legacy env names.** The server previously shipped as Heuresis, so every\n> variable also accepts its old `HEURESIS_*` spelling (`HEURESIS_EMAIL`,\n> `HEURESIS_SNAPSHOT`, …). The `PROOF_*` name wins when both are set. Machines\n> paired under the old `~/.heuresis/` directory keep working — reads fall back\n> to it and the next write migrates to `~/.proof/`.\n\n## Live sync\n\nWhen the MCP boots in cloud mode it subscribes to the workspace over Supabase\nRealtime and notifies the client whenever a `nodes`, `edges`, `projects`, or\n`ideas` row changes. Edits made in the webapp show up in the agent's view\nwithout a manual refresh, and writes from one MCP-connected client reach any\nother connected client the same way. Pass `--no-realtime` to disable the\nsubscription (useful if the chatter is noisy or the client logs every\nnotification). The preference is saved to `~/.proof/config.json` so the flag\nonly needs to be passed once.\n\n## Tools\n\n53 tools total: 49 data tools against the cloud workspace, plus 4 operator\ntools that drive the same ideation operators the webapp uses.\n\n**Reads.** `get_workspace_summary`, `list_projects`, `get_project_graph`,\n`get_subtree`, `list_concepts`, `list_edges`, `get_concept`, `search_concepts`,\n`find_concepts`, `find_orphans`, `list_recent_decisions`. Most agent sessions\nstart with `get_workspace_summary` or `list_projects`.\n\n**Concept writes.** `add_concept`, `update_concept`, `bulk_add_concepts`,\n`set_parent`, `link_concepts`, `add_kref`, `validate_concept`, `set_standing`,\n`archive_concept`, `unarchive_concept`, `star_concept`, `remove_concept`,\n`remove_concepts`.\n\n**Idea & project writes.** `create_idea`, `rename_idea`, `recolor_idea`,\n`set_idea_members`, `add_to_idea`, `delete_idea`, `create_project`,\n`update_project`, `delete_project`.\n\n**Agent runs & handoffs.** `list_agent_runs`, `get_agent_run`,\n`update_agent_run`, `list_pending_handoffs`, `claim_handoff`.\n\n**Evidence, proof & review.** `add_evidence`, `add_challenge`, `record_proof`,\n`get_concept_proof`, `list_proofs`, `list_verification_records`,\n`get_verification_record`, `submit_review_summary`.\n\nEvery write **that targets a concept** stamps a row in `public.provenance`\nwith `origin='mcp'`, so the webapp's session log shows which surface and which\ndevice made the change. Writes at the idea, project or agent-run level do not:\na provenance row is keyed to a node (`node_id NOT NULL`), and those operations\nhave no single concept to point at.\n\n**Operators (4).** `run_operator` (generate candidates with Branch / Matrix /\nASIT / TRIZ / Combine / Free / Contradiction), `run_operator_and_commit` (same,\nplus commit the result in one round-trip), `expand_concept` (recursive Branch;\nexpansion is geometric, so it is capped by the number of model calls it makes,\nnot by depth × breadth), and `get_run` (fetch a prior operator run).\n\nTool input shapes mirror their counterparts in the webapp's `src/agent/tools.ts`,\nso an agent that uses both surfaces sees a uniform contract.\n\n## Snapshot mode (read-only)\n\nWithout credentials, the server can read a JSON workspace export from disk and\nexpose the read-only tool set (`get_workspace_summary`, `list_projects`,\n`search_concepts`, `get_concept`, `get_subtree`, `get_project_graph`,\n`list_recent_decisions`). Point `PROOF_SNAPSHOT` at the file:\n\n```bash\nexport PROOF_SNAPSHOT=\"/absolute/path/to/your-export.json\"\nnpx @toremlabs/proof-mcp\n```\n\nExport a workspace from the webapp via Settings → Workspace → Export. This mode\nis a convenience for offline / read-only use; cloud mode is the primary path.\n\n## License\n\nAGPL-3.0-or-later.\n",
  "bytes": 7946,
  "sha": "a6a6ca7e10012c68f827b7cc9ea98c7a2dc768aeb3fb546abb1c96d0fd92cbad",
  "repo_slug": "toremlabs/proof-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_toremlabs_proof_9b8af078/readme"
}