Technical deep dive into building a zero-dependency Model Context Protocol (MCP) server, concurrency tempfile scoping, and TDD error boundaries for associative graph memory.
Model Context Protocol (MCP) Server & Concurrency Scoping for Graph RAG Memory
Lightweight, zero-dependency Model Context Protocol (MCP) server in pure Python stdlib for associative agent memory recall, crash-safe subprocess isolation, and granular error diagnostics.
Key Engineering Deliverables
•Native MCP Server Interface (PR #8, Issue #5): Designed and built a zero-framework stdio JSON-RPC 2.0 MCP server exposing memory_recall tools for Claude Desktop and Cursor.
•Concurrency Scoping & Noise Prevention (PR #10, Issue #9): Introduced unique temporary file scoping via NamedTemporaryFile and BRAIN_ANSWER_OUT, eliminating race conditions and stdout prompt pollution.
The repository provided a CLI script (brain_ask.py), but lacked a standardized interface for AI agent clients (Claude Desktop, Cursor, Cline) to execute memory recall queries via tool use.
•
Pure Stdlib MCP Server:Built a lightweight, pure Python standard library JSON-RPC 2.0 MCP server (examples/mcp_server.py) over stdio.
•
Memory Recall Schema:Implemented the memory_recall tool schema supporting query and retrieval modes (associative, direct, ab).
•
Crash-Safe Subprocesses:Implemented subprocess execution isolating heavy model inference from the server event loop.
•
Zero-Dependency Footprint:Maintained zero external framework dependencies with sub-second unit test execution.
Maintainer Code Review
"Merged into main; established native MCP connectivity for agent clients over JSON-RPC 2.0 stdio."
On 0-match queries, an empty answer file caused the server to fall back to subprocess.stdout, leaking tokenizer warnings and startup logs into agent memory contexts. Concurrent requests also collided on a single default answer file.
•
Per-Call Scoped Temp Files:Introduced per-call unique temporary files via tempfile.NamedTemporaryFile passed through the BRAIN_ANSWER_OUT environment variable.
•
Explicit Empty Return:Ensured empty answer files explicitly return ("(no matching notes found)", True) without falling back to stdout.
•
Deterministic Cleanup:Guaranteed safe temporary file removal in a finally: block.
•
Mutation Testing:Wrote mutation-tested unit tests pinning unique path scoping per concurrent call.
Maintainer Code Review
"Mutation 3 matters more than it looks... your stub that writes nothing really does test 'file exists but is empty', not 'file missing'. That is the exact case from #9."