# MCP and Agent Tooling Roadmap

Status: Draft
Parent: `docs/ROADMAP.md`

# Phase A0 — Tool Design

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

# Phase A1 — Core Tools

- [x] List notes
- [x] Get note
- [x] Search notes
- [x] Create note draft
- [x] Workspace-scoped retrieval
- [x] Define tool input/output schemas
- [x] Add product-side executable tool layer
- [x] 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

- [x] Workspace/product scoping guardrails
- [x] Audit verification for mutating tools
- [x] Safe usage docs and runbooks
- [x] Regression tests for mutating tool paths
- [x] 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

# 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

- Shared `mcp-server` registration hookup has not been implemented in the common platform repo yet.

# Deferred

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

# Done When

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