learning_ai_notes/docs/roadmaps/05_MCP_AGENT_ROADMAP.md

MCP and Agent Tooling Roadmap

Status: Draft Parent: docs/ROADMAP.md

Phase A0 — Tool Design

• Define product namespace
• Define tool taxonomy
• Classify read-only vs mutating tools
• Define role gating rules
• Define audit requirements
• Define dry-run expectations where practical

Phase A1 — Core Tools

• List notes
• Get note
• Search notes
• Create note draft
• Workspace-scoped retrieval
• Define tool input/output schemas
• Add product-side executable tool layer
• Add product-side registration/export adapter

Phase A2 — Agent Workflows

• Propose note edit
• Summarize note
• Extract tasks
• Attach citations
• Review approvals
• Export note bundle/context pack

Phase A3 — Operational Hardening

• Workspace/product scoping guardrails
• Audit verification for mutating tools
• Safe usage docs and runbooks
• Regression tests for mutating tool paths
• Review mcp-server integration against auth boundaries

A2A Follow-On Work

• Define ingest -> enrich -> approve -> persist flow
• Define which workflows remain synchronous vs async
• Define optional webhook/job triggers

Progress Notes

• 2026-03-10 — Product-side MCP contract layer added under backend/src/mcp/note-tool-contracts.ts.
• Defined first core tool contracts:
  • notes.notes.list
  • notes.notes.get
  • notes.notes.search
  • notes.notes.create_draft
• Contract decisions currently encoded in schemas:
  • read-only tools require viewer
  • draft creation requires admin
  • mutating draft creation supports dryRun, idempotencyKey, and correlationId
  • all core tools are explicitly workspace-scoped
• 2026-03-10 — Product-side executable MCP note tools added under backend/src/mcp/note-tools.ts.
• Verified behavior now includes:
  • executable list/get/search handlers over the existing notes repository
  • executable create_draft handler
  • dry-run draft preview behavior
  • persisted draft creation with note-agent-actions audit/proposal record creation
  • Vitest coverage for executable MCP tools
• 2026-03-10 — Product-side MCP registration/export adapter added under backend/src/mcp/register-note-tools.ts.
• Compatibility work now includes:
  • an adapter that exports the note tools in a shape compatible with shared mcp-server registration
  • a clear product-side handoff point for future shared-server wiring
  • backend verification still passing after the adapter layer was introduced
  • explicit adapter tests now verify exported tool shape and registration callback coverage
• 2026-03-10 — Product-side MCP hardening advanced:
  • executable tools now reject mismatched productId scope at runtime
  • regression coverage now asserts mutating calls do not persist when scope is invalid
  • core tools remain workspace-scoped through input contracts and repository calls
• 2026-03-10 — Shared-server auth-boundary review completed against learning_ai_common_plat/services/mcp-server:
  • shared toolRoutes performs role checks before execute()
  • shared toolRoutes validates arguments via safeParse before execute()
  • shared toolRoutes passes jwtPayload, authorization, and requestId into tool execution
  • product-side note tools additionally enforce authenticated user presence and productId scope before repository access
• 2026-03-10 — Shared mcp-server hookup completed in learning_ai_common_plat/services/mcp-server:
  • Notes backend URL config was added for the notes product backend on port 4016
  • shared-server Notes client/tool modules now expose notes.notes.list, notes.notes.get, notes.notes.search, and notes.notes.create_draft
  • shared mcp-server typecheck passes and shared test suite still passes after the Notes integration was added

Safe Usage Rules

• Read-only note tools may run with viewer or above.
• Mutating note tools must require admin or above.
• Mutating note tools must remain workspace-scoped and product-scoped.
• Mutating note tools must persist an audit/proposal record before the workflow can be considered complete.
• Shared mcp-server hookup must preserve the request jwtPayload, auth header, and request ID passed to product-side tools.

Open Questions

• Should the namespace stay notes.* or be prefixed more explicitly for ByteLyst internal routing?
• Should create_draft return a draft note directly or create a note-agent-actions proposal record first?
• Which MCP calls should require admin vs super_admin once operator review flows exist?

Blockers

• None for the current core MCP note tool scope inside this repo pair.

Deferred

• Mutating workflow execution
• Approval/review tools
• Export/context-pack tools
• A2A orchestration specifics

Done When

• MCP tools cover core note workflows at the product-backend execution layer
• Product-side MCP tools are exportable in a shared-server-compatible registration shape
• Mutating tool paths are auditable and scoped for the current create_draft path
• Coding agents have clear contracts for using tools safely at the product-backend layer