Skip to main content

Module mcp

mnemo_engine

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