Skip to main content

Module mcp

Module mcp 

Source
Expand description

Hand-rolled Model Context Protocol (MCP) stdio server for MNemo.

Exposes a .mnemo file as an MCP server so any MCP-compatible agent (Claude Desktop, Cursor, mcp-server, custom clients) can drive it as a tool. Framed as JSON-RPC 2.0 with newline-delimited JSON over stdin/stdout, per the MCP spec. Stderr is used for human-readable diagnostics only — never for protocol traffic.

§Why hand-rolled

The official rmcp SDK declares edition = "2024" on its workspace, which requires Rust 1.85+; our MSRV is 1.75 and locked (transitive deps pin us). rmcp also brings in tokio + async, a big architectural shift for a sync-only core. Hand-rolling stdio JSON-RPC is ~250 LoC and adds zero dependencies beyond serde_json (already a dep). See CHANGELOG’s Phase 4 entry for the decision record.

§Protocol version

We advertise MCP protocol 2025-06-18 on initialize. If a client requests a different version we echo their version back — the standard compatibility dance. The seven tools we expose are stable across recent protocol revisions.

§Tools

  • about — read-only briefing (manifest + onboarding memories)
  • remember — insert a memory (BYO vector; embedder integration deferred to Phase 3)
  • recall — vector recall (BYO query vector)
  • forget — delete by ULID
  • list — enumerate live memories
  • snapshot_list — enumerate PITR snapshots
  • stats — database statistics

Every mutation calls Mnemo::flush() before returning success — MCP clients treat tool calls as atomic and expect on-disk durability.

§The secret

12.3 step 2: found through the key-source chain (crate::keys::resolve), by the file’s kind: MNEMO_KEY, MNEMO_KEY_FILE, MNEMO_KEY_COMMAND (10 s at most) or the keychain for a key; MNEMO_PASSPHRASE or the keychain for a passphrase. The server never prompts (stdio carries JSON-RPC) and takes no key flag, so what a client’s config holds carries no secret. It logs where the secret came from to stderr at start, never the secret.

Structs§

EmbedSpec
The server’s --embed-cmd embedder (12.3 step 4, v0.15): the tuple the other serve_* functions take, plus the query convention.

Functions§

serve_stdio
Run the MCP stdio server over the provided .mnemo file.
serve_stdio_with_embedder
Variant that optionally registers an crate::EmbedCmd embedder on the handle at server start (Phase 3 PR 10b). The MCP remember, recall, cache_put_semantic and cache_get_semantic tools then accept a text param as an alternative to the explicit vector — the embedder runs once per request against the persistent child process. Pass None for the pre-Phase-3 vector-only behavior.
serve_stdio_with_options
serve_stdio_with_embedder, and with shared set, in shared mode (12.4, mnemo serve --mcp --shared): the server holds no lock between tool calls, and each call is one read or one write window on the file, so other servers, the CLI and Python can use the brain meanwhile. The options’ deadline is how long one call waits for the lock.
serve_stdio_with_spec
serve_stdio_with_options with an EmbedSpec, so the embedder can have a query convention (mnemo serve --mcp --embed-query).
serve_with_streams
Run the MCP loop against explicit reader/writer streams. Extracted so integration tests can pipe scripted input without touching the real stdin/stdout. embed_spec is as in serve_stdio_with_embedder.
serve_with_streams_opts
serve_with_streams, in shared mode when shared is set (see serve_stdio_with_options).
serve_with_streams_spec
serve_with_streams_opts with an EmbedSpec.