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.

§Passphrase

Read from the MNEMO_PASSPHRASE environment variable only. serve_stdio refuses to start without it. There is no CLI-flag fallback here — that would leave the passphrase in shell history and process listings.

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_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).