Skip to content

mcp_plan.md

Latest commit

 

History

History
149 lines (112 loc) · 5.56 KB

mcp_plan.md

File metadata and controls

149 lines (112 loc) · 5.56 KB
Raw

MCP Native Integration Plan

mcp_plan

Goal

Make ai-memory-hub feel native to MCP clients (including Codex) by tightening the current MCP contract, fixing the insert ID flow, and improving discoverability and reliability without breaking existing clients.

Related plan: mcp_utility_compliance_plan.md tracks MCP utility support for pagination, sanitized logging, and deferred completion.

Scope

  • Keep the current MCP tool set working:
    • memory_validate
    • memory_insert
    • memory_search
    • memory_retrieve
    • memory_ask
  • Keep current resources and prompts working:
    • memory://conversation/example
    • memory://conversation/{id}
    • memory://search/{query}
    • memory://timeline/{day}
    • save_conversation
    • search_memory
    • ask_memory
    • summarize_conversation
  • Tighten tool I/O schemas and structured outputs.
  • Fix the insert ID contract so Codex can omit memory_id when the backend generates IDs.
  • Add protocol and regression coverage for the current MCP surface.

Non-Goals

  • Replacing the existing FastAPI REST endpoints.
  • Removing current MCP tools or changing their names.
  • Introducing a new UI or new ingestion source in this doc.

Workstreams

1) Insert ID Contract

Status: implemented

  • Make the insert path tolerant of omitted id/memory_id when the backend is allowed to assign the identifier.
  • Preserve UUID validation when an ID is provided explicitly.
  • Make the returned inserted ID the canonical ID used by metadata and vector storage.
  • Update prompt text and docs so Codex does not fabricate an ID.

Current code to align with:

  • memory.ingestion.mvp_ingestion.normalize_conversation_json() already assigns a UUID when id is absent.
  • memory.backend.metadata_store.SQLiteMetadataStore and PostgresMetadataStore still require valid UUIDs on write.
  • MCP memory_insert currently normalizes then validates before insert.

Acceptance criteria:

  • Codex can call memory_insert without supplying an ID and still succeed.
  • Explicit non-UUID IDs still fail fast with a clear validation error.
  • Retrieval/search continue to return the same canonical ID that was stored.

2) MCP Tool Contract

Status: implemented

  • Keep existing tool names for compatibility.
  • Keep the current structured envelope:
    • status, id, results, cursor, error_code, error_message
  • Keep memory_validate as the preflight path for malformed conversations.
  • Keep memory_search pagination/filtering semantics:
    • limit, cursor, source, date_from, date_to, tags

Acceptance criteria:

  • Tool responses preserve the envelope shape already used in tests.
  • Validation and runtime errors remain machine-readable and consistent.

3) Resources and Prompts

Status: implemented

  • Keep the current resource set and prompt set stable.
  • Verify prompt content still guides MCP clients through memory_validate before memory_insert.
  • Keep search and timeline resources returning predictable metadata and filtered result sets.

Acceptance criteria:

  • resources/list, resources/read, prompts/list, and prompt invocation continue to work as implemented.
  • Prompt text does not regress into direct REST or config-file workflows.

4) Protocol Reliability

Status: implemented

  • Preserve strict MCP JSON-RPC behavior on the streamable HTTP endpoint.
  • Keep required headers and session handling documented:
    • Accept: application/json, text/event-stream
    • Mcp-Session-Id after initialize
  • Keep transport error handling actionable for invalid envelopes and session misuse.

Acceptance criteria:

  • Initialize, tools, resources, and prompts work end-to-end over the MCP transport.
  • Common protocol errors remain deterministic and test-covered.

5) Test and Verification

Status: implemented

  • Extend existing tests around the insert-ID flow first.
  • Keep MCP tool/resource/prompt tests aligned with the actual server surface.
  • Add regression coverage for:
    • omitted ID on insert
    • explicit invalid UUID
    • insert result ID round-tripping through retrieve/search

Acceptance criteria:

  • CI covers the UUID-less insert path as the primary regression target.
  • The docs and tests agree with the implementation.

Suggested File-Level Changes

  • memory/interfaces/mcp_server.py
    • keep tool envelopes and update prompt text for UUID-less inserts
    • align resource/prompt docs with current behavior
  • memory/ingestion/mvp_ingestion.py
    • make insert ID generation and normalization explicit in code paths
  • memory/backend/metadata_store.py
    • clarify UUID validation boundaries and error messages
  • memory/backend/postgres_metadata_store.py
    • keep behavior consistent with SQLite metadata storage
  • tests/unit/test_mcp_tools.py
    • add omitted-ID and explicit-invalid-ID coverage
  • tests/integration/test_storage_features.py
    • keep UUID validation coverage for storage adapters
  • README.md
    • document that Codex should omit the ID by default when backend-generated IDs are enabled

Delivery Plan (Phased)

  1. Phase 1: Fix insert ID contract and add regression coverage
  2. Phase 2: Align docs and prompt text with the implemented MCP surface
  3. Phase 3: Tighten protocol/docs where tests reveal drift
  4. Phase 4: Only add new MCP resources/prompts if the current surface needs them

Rollout/Risk Controls

  • Keep current tool names and payload compatibility.
  • Prefer additive changes and doc updates over breaking schema changes.
  • Gate insert-ID changes with targeted tests before release.
  • Treat Codex insert behavior as the highest-priority regression surface.