File size: 4,219 Bytes
dbb04e4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 | # 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.
|