# 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

# 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

# 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

- `mcp-server` registration and product client execution wiring have not been implemented yet.
- Contract tests exist, but package install and test execution are still pending.

# Deferred

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

# Done When

- [ ] MCP tools cover core note workflows
- [ ] Mutating tool paths are auditable and scoped
- [ ] Coding agents have clear contracts for using tools safely