Module mcp 

MCP (Model Context Protocol) server for Solo.

Exposes eighteen tools to MCP clients (Claude Desktop, Cursor, etc.):

Episode tools (v0.1+, with v0.9.2 additions):

• memory_remember(content, source_type?, source_id?, salience?) — store an episode. Returns the new MemoryId. salience (v0.9.2+) is optional in [0.0, 1.0] and defaults to 0.5.
• memory_remember_batch(items) (v0.9.2+) — atomically store N episodes in one writer-actor transaction. Each item has the same fields as memory_remember. Returns an ordered array of MemoryIds; either all items persist or none do.
• memory_recall(query, limit?) — vector search. Returns the top-K matches with content + tier + status.
• memory_context(query, subject?, window_days?, limit?) — combined recall + themes + facts + contradictions bundle for agent context.
• memory_update(memory_id, content) — correct/supersede an active episode’s content and refresh its embedding/index row.
• memory_forget(memory_id, reason?) — soft-delete an episode.
• memory_inspect(memory_id) — return the full episode record.

Derived-layer tools (v0.4.0+):

• memory_themes(window_days?, limit?) — list cluster themes.
• memory_facts_about(subject, ...) — query the structured-fact knowledge graph (subject-predicate-object triples).
• memory_entities(query, limit?) — discover entity ids from the structured-fact graph.
• memory_contradictions(limit?) — disagreements flagged during consolidation.
• memory_contradiction_resolve(...) — mark a contradiction resolved, unresolved, or reopened.

Derived-layer tools (v0.5.0+):

• memory_inspect_cluster(cluster_id, full_content?) — drill into one cluster’s abstraction + source episodes (truncated).

Document tools (v0.7.0+):

• memory_ingest_document(path) — read a file from disk, split it into chunks, embed each, and store under documents/document_chunks.
• memory_search_docs(query, limit?) — vector search restricted to document chunks; returns chunk content + parent-doc context.
• memory_inspect_document(doc_id) — show one document’s metadata plus a previewed list of its chunks.
• memory_list_documents(limit?, offset?, include_forgotten?) — paginate over ingested documents, newest first.
• memory_forget_document(doc_id) — soft-delete a document; chunks stop appearing in memory_search_docs and tombstone in HNSW.

Transport

serve_stdio wires the server to stdin/stdout for use as a subprocess (“claude_desktop_config.json or ~/.cursor/mcp.json invokes solo mcp-stdio”). The function awaits a graceful shutdown when stdin closes (parent disconnects) — same lifecycle as solo daemon’s Ctrl+C path.

What’s deferred

• SSE/HTTP transports — rmcp ships them, but v0.1 ships stdio only.
• prompts/ and resources/ capabilities — not needed for the four-tool surface; ServerHandler defaults return empty lists.
• Tool argument validation beyond JSON Schema typing — we trust rmcp to deserialize per the schema, then serde-deserialize into our typed param structs. Bad inputs surface as clear errors.

Structs

ContradictionResolveArgs

ContradictionsArgs

EntitiesArgs

FactsAboutArgs

ForgetArgs

ForgetDocumentArgs

IngestDocumentArgs

InspectArgs

InspectClusterArgs

Args for memory_inspect_cluster (v0.5.0 Priority 3). cluster_id is required; full_content is opt-in for the rare power-user case where 200-char-per-episode truncation is too aggressive.

InspectDocumentArgs

ListDocumentsArgs

MemoryContextArgs

RecallArgs

RememberArgs

RememberBatchArgs

v0.9.2 — args for the new memory_remember_batch MCP tool.

RememberItem

v0.9.2 — one item in a memory_remember_batch request.

SearchDocsArgs

SoloMcpServer

The MCP server. Cheap to clone — every field is Arc-cloneable.

ThemesArgs

UpdateArgs

Enums

InitializeDecision

v0.9.0 P2: outcome of inspecting the tenant’s [llm] config + the peer’s sampling capability at MCP initialize time.

Constants

ENV_MCP_PRINCIPAL_TOKEN

v0.8.1 P2: env var name MCP clients set when launching the server process to attribute audit rows on the stdio transport. Closes the v0.8.0 known-issue gap where MCP audit rows always carried principal_subject = NULL on the daemon path.

Functions

initialize_decision

v0.9.0 P2: decide the initialize outcome given the tenant’s [llm] config and whether the peer advertised the sampling capability.

resolve_mcp_principal

v0.8.1 P2: resolve the MCP-session principal at initialize-time.

sampling_capability_missing_error_message

v0.9.0 P2: locked error message body for both the daemon-startup rejection guard and the MCP initialize capability gate (plan §3 Decision 4 / BLOCKER 2 resolution). Returned verbatim to the operator so the commented-out TOML snippets are copy-pasteable.

serve_stdio

Convenience: run the server over stdio and await its termination. Returns when stdin closes (parent disconnect) or the runtime exits.

tool_names

Names of every tool this server exposes, in registration order.