proofmcp

Stdio MCP server wrapping the Proof SDK HTTP API. Lets Claude (Desktop/Code) create and edit Proof documents on a locally-running Proof SDK instance.

Setup

./setup.sh

This installs deps, builds dist/, and pulls .env from the vault (or copies .env.example).

Requires a running Proof SDK instance. By default proofmcp talks to http://localhost:4000. Set PROOF_SDK_URL to point elsewhere.

Run

proofmcp is a stdio server — Claude Desktop/Code launches it on demand. Register it via The Setterupper → + New (transport: stdio, command: node, args: ["dist/index.js"], cwd: ~/bin/proofmcp).

For manual testing:

node dist/index.js

…then send JSON-RPC frames on stdin.

Test

npm test

Tools

Tool	Wraps	Use for
proof_create_document	POST /documents	Create a new doc; returns slug, shareUrl, ownerSecret, accessToken.
proof_get_state	GET /documents/:slug/state	Read current markdown + metadata.
proof_get_snapshot	GET /documents/:slug/snapshot	Block-level snapshot (input for proof_edit_v2).
proof_edit_v2	POST /documents/:slug/edit/v2	Preferred block-level edit.
proof_edit_structured	POST /documents/:slug/edit	append/replace/insert by section heading or anchor.
proof_apply_op	POST /documents/:slug/ops	comment.add, suggestion.add/accept/reject, rewrite.apply.
proof_update_presence	POST /documents/:slug/presence	Announce agent presence.
proof_get_pending_events	GET /documents/:slug/events/pending	Poll for events since after.
proof_ack_events	POST /documents/:slug/events/ack	Mark events processed.
proof_bridge_get_state	GET /documents/:slug/bridge/state	Agent-flavored read.
proof_bridge_get_marks	GET /documents/:slug/bridge/marks	List comments/suggestions.
proof_bridge_add_comment	POST /documents/:slug/bridge/comments	Add a comment via the bridge route.
proof_bridge_add_suggestion	POST /documents/:slug/bridge/suggestions	Add a replace/insert/delete suggestion.
proof_bridge_rewrite	POST /documents/:slug/bridge/rewrite	Full-doc rewrite (disruptive).
proof_bridge_update_presence	POST /documents/:slug/bridge/presence	Bridge-route presence update.

Env

Var	Default	Purpose
PROOF_SDK_URL	http://localhost:4000	Base URL of the Proof SDK HTTP API.
PROOF_API_KEY	(unset)	Bearer token if Proof SDK runs with PROOF_SHARE_MARKDOWN_AUTH_MODE=api_key. Per-document accessToken / ownerSecret can be passed as the token tool argument and overrides this.
PROOF_AGENT_ID	ai:proofmcp	Identifier used for X-Agent-Id and authorship (by).

Notes

• Registered with The Setterupper via + New.
• proof-sdk itself runs as a separate service on port 4000 — start it independently (cd ~/bin/proof-sdk && npm run serve) or register it in setterupper as its own server entry.