Module server

MCP server — stdio JSON-RPC event loop.

Architecture

This is a synchronous, blocking server that reads JSON-RPC requests line-by-line from stdin and writes responses to stdout. This is the same pattern as ox-mcp (oxymake) and msgvault (Go).

Why synchronous? Because our hot path is SQLite reads, which are inherently blocking and complete in <1ms. Adding an async runtime would add complexity for zero benefit on the common path. The few tools that need network (BBT RPC, Zotero Web API, PDF resolver) use tokio::runtime::Builder::new_current_thread() on demand.

Flow

stdin → read_line → parse JSON-RPC → dispatch → tool handler → JSON-RPC → stdout
                                        │
                          ┌──────────────┼──────────────┐
                          │              │              │
                     initialize    tools/list     tools/call
                                                       │
                                                 tools::handle()

Structs

ServerContext

Runtime context shared across all tool calls.

Constants

SERVER_INSTRUCTIONS 🔒

Instructions sent to agents on MCP connection.

Functions

dispatch 🔒

Dispatch a JSON-RPC request to the appropriate handler. Shared between stdio and SSE transports.

handle_initialize 🔒

handle_tools_call 🔒

handle_tools_list 🔒

level_enabled 🔒

log

run_stdio

Run the MCP server over stdio (blocking).

write_response 🔒