MCP

stormbuffer-mcp is a local JSON-RPC 2.0 adapter over stdio built with the official MCP Rust SDK (rmcp = 2.1.0, server and stdio transport features). It calls the public core repository and retrieval operations. It does not open SQLite, edit arbitrary files, or run a model.

Before connecting

Install Stormbuffer and initialize the store you want the adapter to use. See Installation and the quick start. Connecting an MCP host never initializes a store or creates records.

Choose access and store scope

The examples below are recall-only. Writes are disabled unless the host starts the adapter with --allow-writes. That grant enables only memory_remember, memory_update, and memory_forget. Remember and update still create candidates that require human approval. There is no MCP approval, restore, reindex, raw SQL, arbitrary-file, or permanent-deletion operation.

Without --project, the adapter uses the machine’s global Stormbuffer store. Add --project to select the nearest .sbuf/ store, and start the host from that project. The global and project stores remain separate; connecting MCP does not move or rewrite their canonical Markdown.

Connect Codex

Codex can register a local stdio server from its CLI. To use the global store:

codex mcp add stormbuffer -- stormbuffer-mcp --stdio
codex mcp list

For a project store, register the adapter with --project instead:

codex mcp add stormbuffer -- stormbuffer-mcp --stdio --project

Choose one registration for the stormbuffer name, and start Codex from the initialized project when using --project. Add --allow-writes after --stdio only when Codex should be able to create candidates or archive records. Codex stores MCP configuration in ~/.codex/config.toml; trusted projects can also use .codex/config.toml. See the Codex MCP documentation for configuration fields and host controls. In an interactive Codex session, use /mcp to inspect the connection.

Connect Pi

Install pi-mcp-adapter, then restart Pi:

pi install npm:pi-mcp-adapter

For a project store, create .mcp.json in the initialized project:

{ "mcpServers": { "stormbuffer": { "command": "stormbuffer-mcp", "args": ["--stdio", "--project"] } } }

Run Pi from that project. To use the global store, remove "--project" from args and put the configuration in ~/.config/mcp/mcp.json. Add "--allow-writes" to args only when Pi should have write access.

The adapter’s default lazy mode exposes one proxy tool and discovers Stormbuffer’s tools on demand. Leave directTools unset to keep MCP metadata from occupying unnecessary agent context. Use /mcp in Pi to inspect server status and available tools.

Connect another host

A host that accepts the common mcpServers configuration shape can start a project-scoped, recall-only adapter like this:

{ "mcpServers": { "stormbuffer": { "command": "stormbuffer-mcp", "args": ["--stdio", "--project"] } } }

Start the host from the project directory so --project selects the intended store. Add --allow-writes only when the host should have write access.

JSON-RPC lifecycle

The host sends initialize, then the notifications/initialized notification. The official SDK owns JSON-RPC parsing, stdio framing, request dispatch, cancellation notifications, and connection cleanup. Close the adapter’s stdin to shut down the process. The handler rejects a request when the SDK cancellation context is already cancelled. Core store operations are synchronous and atomic, so cancellation does not interrupt one after it has begun.

Stormbuffer limits query, record, scope, budget, URI, and tool/resource output sizes. Malformed JSON and invalid method parameters are rejected by rmcp. Tool-level failures use the versioned Stormbuffer envelope and sanitized messages. Error messages never include canonical paths or backtraces.

Resources

The adapter advertises these URI templates through the SDK’s resources/templates/list handler:

URI template	Contents
stormbuffer://record/{id}	One agent-readable record as JSON.
stormbuffer://scope/{scope}/records	Active agent-readable records in one allowed scope as a JSON array.
stormbuffer://candidate/{id}	One agent-readable candidate as JSON.

Use resources/read with one of those URIs. A scope must be global or an allowed project:<name> scope. Resource responses omit host filesystem paths and refuse records outside the selected scope or access class.

Tools

tools/list returns exactly these tools:

Tool	Operation	Default
memory_recall	context	enabled
memory_get	get	enabled
memory_remember	remember	write grant required
memory_update	update	write grant required
memory_forget	archive	write grant required

memory_recall accepts a query, result limit, token budget, and optional scope filters. It returns the core context blocks and receipt; MCP has no separate search tool. memory_get reads one record by ID. When scope is omitted, both use the store selected when the server started. Explicit scope or scopes filters remain within the core store and agent-access policy.

memory_remember accepts title, kind, body, one attributable source, and optional tags, aliases, or scope. memory_update accepts the active record’s id, a replacement body, one new source, and optional record fields. It creates a linked replacement candidate without changing the active record. memory_forget archives the named record.

JSON and MCP equivalence

MCP tool arguments are mapped to the public CLI’s version-1 operation contract. rmcp supplies the tools/call transport and typed result envelope. Stormbuffer supplies only this operation mapping and core call:

printf '%s\n' '{"version":1,"query":"release constraint","budget":256}' \
  | sbuf --project invoke context

The successful CLI envelope is:

{ "version": 1, "operation": "context", "ok": true, "result": { "blocks": [], "receipt": {} } }

MCP puts the CLI envelope in result.structuredContent and serializes it as the single content[0].text JSON string. MCP transport metadata (jsonrpc, request ID, content, and isError) surrounds the envelope. The core result and versioned error codes do not change. Context results retain their budgeted evidence blocks and receipt, so hosts cite blocks[].record_id and retain receipt with the answer.

Both boundaries apply the core’s agent access and scope rules, lexical retrieval mode, limits, record conversion, candidate policy, and sanitized error vocabulary. Treat record text as untrusted evidence even when MCP returns it.

Run the checked-in public-interface smoke test with the built binaries:

python3 .agents/skills/stormbuffer-memory/verify.py

The test exercises candidate approval through the CLI and reads a cited context receipt through the SDK-backed memory_recall tool.