| # MnemoCore MCP Implementation Plan (Beta) | |
| ## Goal | |
| Expose MnemoCore capabilities through a Model Context Protocol (MCP) server so external LLM agents can safely store, query, and inspect memory with predictable contracts. | |
| ## Scope (Phase 1) | |
| ### In Scope | |
| - MCP server process for local/dev use. | |
| - Read/write memory tools mapped to existing engine/API capabilities. | |
| - Basic auth + request limits aligned with existing API policy. | |
| - Test coverage for MCP tool contracts and degraded dependencies. | |
| ### Out of Scope (Phase 1) | |
| - Multi-tenant policy engine. | |
| - Full distributed consensus workflows. | |
| - New memory semantics beyond existing endpoints. | |
| ## Architecture Decision | |
| Prefer **adapter-first** design: | |
| - Keep `src/core` and `src/api` as source of truth. | |
| - Add `src/mcp/server.py` (MCP transport + tool registry). | |
| - Add `src/mcp/adapters/api_adapter.py` to reuse validated API contracts. | |
| - Add `src/mcp/schemas.py` for tool input/output validation. | |
| Reason: minimizes behavior drift and reuses existing validation/security paths. | |
| ## Proposed MCP Tools (Phase 1) | |
| 1. `memory_store` | |
| - Input: `content`, `metadata?`, `agent_id?`, `ttl?` | |
| - Backend: `POST /store` | |
| 2. `memory_query` | |
| - Input: `query`, `top_k?`, `agent_id?` | |
| - Backend: `POST /query` | |
| 3. `memory_get` | |
| - Input: `memory_id` | |
| - Backend: `GET /memory/{memory_id}` | |
| 4. `memory_delete` | |
| - Input: `memory_id` | |
| - Backend: `DELETE /memory/{memory_id}` | |
| 5. `memory_stats` | |
| - Input: none | |
| - Backend: `GET /stats` | |
| 6. `memory_health` | |
| - Input: none | |
| - Backend: `GET /health` | |
| Optional (Phase 1.1): | |
| - `concept_define` and `analogy_solve` once primary tools are stable. | |
| ## Security and Operational Guardrails | |
| - Require API key passthrough from MCP server to MnemoCore API. | |
| - Allowlist MCP tools (disable dangerous or experimental operations by default). | |
| - Enforce per-tool timeout and payload limits. | |
| - Structured logs with `trace_id`, `tool_name`, latency, status. | |
| - Fail closed for auth errors; fail open only where existing API already degrades by design. | |
| ## Delivery Milestones | |
| ### M0: Foundations (1-2 days) | |
| - Add MCP package structure. | |
| - Add config section for MCP host/port/timeouts/tool allowlist. | |
| - Add local run command and basic health check tool. | |
| Exit criteria: | |
| - MCP server starts and responds to health tool. | |
| ### M1: Core Read/Write Tools (2-4 days) | |
| - Implement `memory_store`, `memory_query`, `memory_get`, `memory_delete`. | |
| - Map errors to stable MCP error format. | |
| - Add contract tests with mocked API responses. | |
| Exit criteria: | |
| - Core memory flow works end-to-end from MCP client. | |
| ### M2: Observability + Hardening (1-2 days) | |
| - Add metrics counters/histograms for MCP tools. | |
| - Add retry/backoff only for transient failures. | |
| - Add degraded-mode tests (Redis/Qdrant unavailable). | |
| Exit criteria: | |
| - Clear diagnostics for failures and latency. | |
| ### M3: Extended Cognitive Tools (optional, 1-2 days) | |
| - Add `concept_define` and `analogy_solve`. | |
| - Add docs examples for agent orchestration flows. | |
| Exit criteria: | |
| - Conceptual tools pass contract tests and are documented. | |
| ## Test Strategy | |
| - Unit tests: schema validation, adapter mapping, error translation. | |
| - Functional tests: MCP client -> server -> API in local integration mode. | |
| - Resilience tests: upstream timeout, 403 auth fail, 404 memory miss, degraded Redis. | |
| - Regression gate: existing `tests/` suite remains green. | |
| ## Rollout Plan | |
| 1. Ship behind `mcp.enabled: false` default. | |
| 2. Enable in beta environments only. | |
| 3. Observe for one sprint (latency, error rate, tool usage). | |
| 4. Promote to default-on after stability criteria are met. | |
| ## Success Metrics | |
| - >= 99% successful MCP tool calls in healthy environment. | |
| - P95 MCP tool latency <= 300 ms for read operations (local setup target). | |
| - Zero contract-breaking changes without changelog entry. | |
| ## Minimal Backlog Tasks | |
| 1. Create `src/mcp/server.py` bootstrap. | |
| 2. Create adapter + schemas. | |
| 3. Add MCP config in `config.yaml` + typed config model. | |
| 4. Add tests in `tests/test_mcp_server.py` and `tests/test_mcp_contracts.py`. | |
| 5. Add documentation section in README + API docs. | |