docs: add engraph v2.2b design spec — MCP server

MCP stdio server exposing 7 read-only vault tools via rmcp SDK.
Arc+Mutex wrapping for Clone requirement, tokio::sync::Mutex for
async handlers, transport-io for stdio.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: devwhodevs

docs/specs/2026-03-24-engraph-v2.2b-design.md

@@ -0,0 +1,345 @@
+# engraph v2.2b — MCP Server
+
+**Date:** 2026-03-24
+**Milestone:** v0.5
+**Depends on:** v0.4.0 (context engine)
+
+---
+
+## Goal
+
+Add `engraph serve` command that runs an MCP stdio server, exposing the context engine as tools that Claude Code and other MCP clients can call directly.
+
+## What's in scope
+
+1. `engraph serve` command — starts MCP stdio server
+2. 7 read-only MCP tools mapping to existing context engine functions
+3. Dependencies: `rmcp` (official Rust MCP SDK), `tokio`, `schemars`
+
+## What's NOT in scope
+
+- HTTP daemon / REST API → v0.8
+- Agent authentication / permissions → v0.8
+- Write tools (create, append, update_metadata) → v0.6 (write pipeline)
+- SSE / streamable HTTP transport → v0.8
+
+---
+
+## 1. MCP Tools
+
+| Tool | Parameters | Maps to | Returns |
+|------|-----------|---------|---------|
+| `search` | `query: String, top_n?: usize` | `search_internal` | JSON array of results with score, path, heading, snippet, docid |
+| `read` | `file: String` | `context_read` | JSON NoteContent (full content, metadata, graph edges) |
+| `list` | `folder?: String, tags?: Vec<String>, limit?: usize` | `context_list` | JSON array of NoteListItem |
+| `vault_map` | (none) | `vault_map` | JSON VaultMap (folders, tags, recent files) |
+| `who` | `name: String` | `context_who` | JSON PersonContext (note, mentions, links) |
+| `project` | `name: String` | `context_project` | JSON ProjectContext (note, children, tasks, team) |
+| `context` | `topic: String, budget?: usize` | `context_topic_with_search` | JSON ContextBundle (sections, budget info) |
+
+All tools return JSON via `CallToolResult::success(vec![Content::text(json_string)])`.
+
+Tool parameters use `schemars::JsonSchema` derive for automatic schema generation in MCP tool listing.
+
+---
+
+## 2. Architecture
+
+```
+Claude Code / MCP Client
+        │ stdio (stdin/stdout)
+        ▼
+  engraph serve
+        │
+  ┌─────▼─────┐
+  │  MCP Server │  (rmcp ServerHandler)
+  │  serve.rs   │
+  └─────┬──────┘
+        │ calls directly (sync)
+  ┌─────▼──────────────────────┐
+  │  context.rs  │  search.rs  │
+  │  store.rs    │  graph.rs   │
+  │  embedder.rs │  hnsw.rs    │
+  └────────────────────────────┘
+```
+
+### Server Struct
+
+```rust
+use std::sync::Arc;
+use tokio::sync::Mutex;
+
+#[derive(Clone)]
+pub struct EngraphServer {
+    store: Arc<Mutex<Store>>,          // Connection is !Sync, needs Mutex
+    embedder: Arc<Mutex<Embedder>>,    // &mut self methods, needs Mutex
+    hnsw_index: Arc<HnswIndex>,        // Hnsw is Send+Sync, Arc alone is fine
+    vault_path: Arc<PathBuf>,
+    profile: Arc<Option<VaultProfile>>,
+}
+```
+
+**Why `Arc` + `Clone`:** rmcp's `#[tool_router]` macro requires the server struct to implement `Clone`. Since `Store` wraps `rusqlite::Connection` (which is `!Sync`) and `Embedder` needs `&mut self`, both are wrapped in `Arc<tokio::sync::Mutex<T>>`.
+
+**Why `tokio::sync::Mutex`:** Allows `.lock().await` in async tool handlers. Since MCP stdio processes one request at a time, contention is never an issue — but tokio's Mutex integrates cleanly with async handlers.
+
+**Helper method** for constructing `ContextParams` per tool call:
+
+```rust
+impl EngraphServer {
+    async fn with_context<F, T>(&self, f: F) -> Result<T, McpError>
+    where
+        F: FnOnce(&context::ContextParams<'_>) -> anyhow::Result<T>,
+    {
+        let store = self.store.lock().await;
+        let params = context::ContextParams {
+            store: &store,
+            vault_path: &self.vault_path,
+            profile: self.profile.as_ref().as_ref(),
+        };
+        f(&params).map_err(|e| McpError::internal(e.to_string()))
+    }
+}
+```
+
+### Async/Sync Bridge
+
+The existing codebase is synchronous. The MCP SDK is async (tokio). The bridge:
+
+1. `engraph serve` creates a tokio runtime via `#[tokio::main]` on main
+2. MCP tool handlers are `async fn` (required by rmcp)
+3. Inside each handler, lock the store/embedder Mutex, call sync functions, release
+4. Operations are fast (<100ms typically) — SQLite queries, disk reads, and occasional ONNX inference (CPU-bound, 20-80ms)
+
+**Conscious trade-off:** No `spawn_blocking` is used. ONNX inference in the `search` and `context` tools blocks the tokio worker thread for up to 80ms. For a single-client stdio server with no concurrent async work, this is harmless. If the server ever moves to multi-client HTTP, `spawn_blocking` should be added for embedding calls.
+
+### Startup Flow
+
+```
+engraph serve
+  → load Store from ~/.engraph/engraph.db
+  → load Embedder from ~/.engraph/models/
+  → load HnswIndex from ~/.engraph/hnsw/
+  → load VaultProfile from ~/.engraph/vault.toml (optional)
+  → get vault_path from store.get_meta("vault_path")
+  → create EngraphServer struct
+  → create stdio transport: (tokio::io::stdin(), tokio::io::stdout())
+  → server.serve(transport).await
+```
+
+### Error Handling
+
+Tool errors return `McpError` with descriptive messages. The server never panics — all errors are caught and returned as MCP error responses.
+
+If the index doesn't exist at startup, print error to stderr and exit (same as other commands).
+
+---
+
+## 3. Tool Implementations
+
+Each tool is a method on `EngraphServer` with `#[tool]` attribute:
+
+### `search`
+
+```rust
+#[tool(description = "Hybrid search across the vault using semantic, keyword, and graph lanes")]
+async fn search(&self, Parameters(params): Parameters<SearchParams>) -> Result<CallToolResult, McpError> {
+    let top_n = params.top_n.unwrap_or(5);
+    let store = self.store.lock().await;
+    let mut embedder = self.embedder.lock().await;
+    let output = search_internal(&params.query, top_n, &store, &mut embedder, &self.hnsw_index)
+        .map_err(|e| McpError::internal(e.to_string()))?;
+    let json = serde_json::to_string_pretty(&output.results)
+        .map_err(|e| McpError::internal(e.to_string()))?;
+    Ok(CallToolResult::success(vec![Content::text(json)]))
+}
+```
+
+### `read`
+
+```rust
+#[tool(description = "Read a note's full content with metadata and graph connections")]
+async fn read(&self, Parameters(params): Parameters<ReadParams>) -> Result<CallToolResult, McpError> {
+    self.with_context(|ctx| {
+        let note = context_read(ctx, &params.file)?;
+        Ok(serde_json::to_string_pretty(&note)?)
+    }).await
+    .map(|json| CallToolResult::success(vec![Content::text(json)]))
+}
+```
+
+### Pattern for all tools
+
+Each tool:
+1. Extract parameters (with defaults for optional fields)
+2. Build `ContextParams` via `self.context_params()`
+3. Call the corresponding context/search function
+4. Serialize result to JSON
+5. Return `CallToolResult::success`
+
+### Parameter Structs
+
+```rust
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct SearchParams {
+    /// The search query
+    pub query: String,
+    /// Number of results (default 5)
+    pub top_n: Option<usize>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct ReadParams {
+    /// File path, basename, or #docid
+    pub file: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct ListParams {
+    /// Filter to folder path prefix
+    pub folder: Option<String>,
+    /// Filter to notes with all listed tags
+    pub tags: Option<Vec<String>>,
+    /// Maximum results (default 20)
+    pub limit: Option<usize>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct WhoParams {
+    /// Person name
+    pub name: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct ProjectParams {
+    /// Project name
+    pub name: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct ContextToolParams {
+    /// Topic to search for
+    pub topic: String,
+    /// Character budget (default 32000, ~8000 tokens)
+    pub budget: Option<usize>,
+}
+```
+
+Note: `ContextToolParams` (MCP tool input) is distinct from `context::ContextParams` (the shared context struct). Different names, different purposes — no collision.
+
+---
+
+## 4. CLI
+
+```rust
+/// Start MCP stdio server.
+Serve,
+```
+
+Handler:
+```rust
+Command::Serve => {
+    if !index_exists(&data_dir) {
+        eprintln!("No index found. Run 'engraph index <path>' first.");
+        std::process::exit(1);
+    }
+    serve::run_serve(&data_dir).await?;
+}
+```
+
+Since `engraph serve` needs async, the `main()` function needs to handle this. Two options:
+- Make `main` itself `#[tokio::main]` (simplest, adds ~1ms overhead to non-serve commands)
+- Use `tokio::runtime::Runtime::new()` only in the Serve handler (avoids runtime for other commands)
+
+**Recommendation:** Use `#[tokio::main]` on main. The overhead is negligible and avoids complexity. All existing sync commands work fine inside a tokio runtime — they just don't use it.
+
+---
+
+## 5. Dependencies
+
+Add to `Cargo.toml`:
+
+```toml
+rmcp = { version = "1.2", features = ["transport-io"] }  # default includes server + macros
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+schemars = "0.8"
+```
+
+Note: `rmcp` default features include `server` (which pulls in `transport-async-rw` + `schemars`) and `macros`. The only extra feature needed is `transport-io` for stdio (`tokio/io-std`).
+
+---
+
+## 6. Testing
+
+Unit tests for the MCP server are limited since the tool handlers are thin wrappers around context/search functions (already tested with 146 tests).
+
+**Integration test approach:**
+- Test `EngraphServer` construction with in-memory store
+- Test each tool method directly (they're just async fns)
+- Don't test MCP protocol encoding (that's rmcp's responsibility)
+
+**Manual testing:**
+```bash
+# Start the server
+engraph serve
+
+# In another terminal, send JSON-RPC via stdin (or use Claude Code)
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | engraph serve
+```
+
+**Claude Code testing:**
+Add to settings, then use tools in a conversation.
+
+---
+
+## 7. File Structure
+
+### New Files
+- `src/serve.rs` — MCP server: EngraphServer struct, tool handlers, parameter structs, run_serve
+
+### Modified Files
+- `src/main.rs` — add `Serve` command, make main async with `#[tokio::main]`
+- `src/search.rs` — add `Serialize` derive to `InternalSearchResult` (currently only has `Debug, Clone`)
+- `Cargo.toml` — add rmcp, tokio, schemars
+- `src/lib.rs` — add `pub mod serve;`
+
+---
+
+## 8. Claude Code Integration
+
+After release, configure in `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "engraph": {
+      "command": "engraph",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Then Claude Code can call:
+- `engraph_search({ query: "delivery date" })`
+- `engraph_read({ file: "#bf84f0" })`
+- `engraph_who({ name: "John Nelson" })`
+- etc.
+
+---
+
+## 9. Revised Roadmap
+
+| Semver | Milestone | What |
+|--------|-----------|------|
+| v0.1 | Initial | Shipped 2026-03-19 |
+| v0.2 | v2.0 Foundation | Shipped 2026-03-24 |
+| v0.3 | v2.1 Graph | Shipped 2026-03-24 |
+| v0.4 | v2.2a Context Engine | Shipped 2026-03-24 |
+| **v0.5** | **v2.2b MCP Server** | **MCP stdio, 7 read-only tools** |
+| v0.6 | v2.3 Write Pipeline | Auto-filing, tag resolution, link discovery |
+| v0.7 | v2.4 Intelligence | Research orchestrator, temporal agent |
+| v0.8 | v2.5 Polish | HTTP/REST, auth, vault health, multi-vault |