MCP write tools

[CuriouslyCory]

Parent

PRD #2

What to build

MCP tools let an agent build and maintain the architecture: create a Component, create a child Component, connect Components, update documentation, and move a Component. Each is a thin adapter over the existing services, so all invariants (legal shapes, cycle prevention, de-dupe, authorization) are reused. Tool errors return readable text so the agent can self-correct. No delete tools are exposed in this surface.

Acceptance criteria

• Tools exist for create, create-child, connect, update-docs, and move, each calling the shared services
• Tools enforce the same invariants and authorization as the web path (no bypass)
• Service / validation errors surface to the agent as readable tool-error text, not stack traces
• No delete / destructive tool is exposed
• An MCP Inspector round-trip creates a Component via a tool and reads it back as markdown

Blocked by

• Authenticated MCP route + read resources + llms.txt #18 (slice 16: Authenticated MCP route + read resources)

[CuriouslyCory]

Realigned against #33 / docs/plans/flow-routed-connections.md.

Deltas:

• Flow-shaped MCP tools are now owned by the slice issues, not this one. The plan introduces attach-flow-spec, add-flow, update-flow, delete-flow, route-flow, unroute-flow, list-flows. Distribution:
  • attach-flow-spec, add-flow, list-flows → Slice 1 (Slice 1: Flows on Components — schema, service, spec paste #34)
  • route-flow, unroute-flow → Slice 2 (Slice 2: Same-Canvas baseline flow routing on a Connection #35); route-flow gains interiorEndpointId in Slice 3 (Slice 3: Refinement routing via boundary proxy palette #36)
  • update-flow, delete-flow → implicit in Slice 1's service surface (Slice 1: Flows on Components — schema, service, spec paste #34 acceptance criteria); register the tool wrappers there.
• This issue's scope narrows to the non-Flow write tools — create / create-child / connect / update-docs / move. Still a coherent slice on its own; ship it before the Flow tools layer on. Each Flow-tool registration is additive and gated by the corresponding slice issue landing first.
• "No delete tool" stance. Plan does include delete-flow (owner-only, undoable per ADR-0008). That's a soft-delete via the existing cascade machinery, not a destructive delete — consistent with the original "no destructive tool" rule. Worth noting in the agent's tool description so the distinction is clear.
• Read-only invariant unchanged. Tools still go through services; authorization, polarity, same-Canvas / cross-scope gating all live at the service seam (Slices 1–4 enforce them), the MCP adapter remains thin.

Sequence: this issue lands next on the MCP track (after #18). Flow tools follow per their slice issues; no umbrella supersession needed.

[CuriouslyCory]

Scope note (per docs/plans/flow-routed-connections.md):

Flow-related MCP tools (attach-flow-spec, add-flow, update-flow, delete-flow, list-flows, route-flow, unroute-flow) are NOT in this slice — they land alongside their services in #34 (Slice 1), #35 (Slice 2), and #36 (Slice 3). Keep this issue's surface to the five listed tools.

Build the error-translation layer so future tools plug in cleanly: per ADR-0010 the adapter should read structured details off cause.details (incl. archDetails) when translating ConflictError / validation errors to readable tool-error text, so #34/#35/#36's de-dupe conflicts (conflictingFlowIds, conflictingFlowRouteIds, conflictingEdgeIds) surface uniformly without further adapter work.

The "no delete tool" stance here is unchanged; delete-flow lands in #34 as an owner-only undoable soft-delete (ADR-0008), which is consistent with this issue's prohibition on destructive tools.