The MCP server (memprove mcp)

memprove mcp serve is a Model Context Protocol server on standard input and output. The client starts it (the entry init writes), and an agent reads and writes the ledger through its ten tools: pack, claims, context, tasks, and ledger_verify read; begin, checkpoint, decide, end, and complete write. Parameters are numbers and labels, never a UUID. No tool runs a command; tests are recorded with memprove run in a shell, and their labels are then cited through the tools. Both protocol eras are served, decided per request: the 2026-07-28 revision (server/discover, the protocol version in each request’s _meta) and the initialize handshake of 2025-11-25 and 2025-06-18. Standard output carries protocol messages only; standard error carries one line per message and never a token or an argument value.

tool	kind	daemon operations	token scope
pack	read	getTaskCapsule, listTasks	mcp-read
claims	read	getTaskCapsule, listTasks	mcp-read
context	read	none (local files only)	none
tasks	read	listTasks	mcp-read
ledger_verify	read	verifyLedger	mcp-read
begin	write	listSessions, resolveWorkspace, createTask, listTasks, createSession, transitionTask	mcp-write
checkpoint	write	getTaskCapsule, createCheckpoint, listTasks, listSessions	mcp-write
decide	write	getTaskCapsule, proposeDecision, listTasks, listSessions	mcp-write
end	write	endSession, getTaskCapsule, listSessions, listTasks	mcp-write
complete	write	transitionTask, getTaskCapsule, listTasks, listSessions	mcp-write

• pack returns the Pack as resume --pack prints it, byte for byte, after an opening statement like the hook’s (the Task, the current UTC time, the server’s agent, the open-item sentence); The pack tool’s default budget is 6000 UTF-16 code units; query selects as --query does, manifest adds nothing since U16. claims gives the full lines of named claims. begin takes task (a number from tasks) or new_task, and agent_name, agent_role, parent_session (else the server’s environment, else its context); its result names the Session’s agent. checkpoint takes facts, open items, reaffirmations, withdrawals and the next action with labels (r1) and claim numbers; decide a Decision; end ends the context’s Session, or with abandoned the Session a number names; complete completes the Task on the context’s passed runs. Every result’s object begins with task_id and session_id. An error result’s text begins with the Problem code (role_forbidden: …) and a fixed sentence.
• memprove mcp print-config prints it and writes nothing: the entry belongs in <Workspace root>/.mcp.json (project scope) or in ~/.claude.json (local or user scope). The entry names the executable, the arguments mcp serve --config-dir <config> and env.MEMPROVE_CONFIG_DIR, no data directory, no token: A token never goes into .mcp.json. Every tool call reads the token and the data directory anew: the token from MEMPROVE_TOKEN, else the file named by MEMPROVE_TOKEN_FILE, else <configuration directory>/token; the data directory from MEMPROVE_DATA_DIR, else the one line of <configuration directory>/data-dir. A rotated or revoked token takes effect on the next call.
• The read tools need mcp-read; the writes need mcp-write. The write tools also send reads, which need mcp-read: begin lists Sessions and Tasks, checkpoint and decide read the Capsule to resolve numbers. The agent token carries both scopes.
• The Workspace is the one of CLAUDE_PROJECT_DIR, else of the server’s working directory (the MCP server works in the Workspace of CLAUDE_PROJECT_DIR, which Claude Code sets to the project root, else of its working directory). Nothing is kept between calls: every call reads the context files on disk again, so a memprove run in the shell and a checkpoint through the tool see each other.

From docs/guide.md at 2625064cbf0a · Markdown