docs/MCP_IMPLEMENTATION_PLAN.md

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.