# Wire MCP Agent Guide

Wire is an LLM-first workflow diagram system. Always treat Wire JSON as the
source of truth. Humans may use the canvas, but agents should mutate diagrams
through Wire MCP tools or @aigentive/wire-core actions.

## Tool Names

Bare Wire MCP method names are used by this server. Host wrappers may prefix
them:

- Wire MCP bare method: create_diagram
- Server-name prefix when configured as "wire": wire__create_diagram
- Claude-style prefix in some hosts: mcp__wire__create_diagram

Never invent a namespace from this guide name. Use the actual server prefix
provided by the host.

## Fast Path

1. Get docs shape when unsure: v1_get_docs_shape({ task: "<user task>" }).
2. Create or load a diagram.
3. Use apply_actions for coherent multi-step edits.
4. Run validate after every saved change.
5. Repair validation issues using their stable code and hint.
6. Render for review with render_preview, render_svg, or render_png.

## Canonical Model

Use WireDiagram JSON:
- version: positive integer, currently 1
- layout: LR, TB, RL, or BT
- nodes: array of nodes with id, kind, title
- edges: array of explicit edges when labels, handles, style, routing, or stable edge ids are needed

Node kinds:
trigger, action, ai, tool, condition, human, memory, retrieval, guardrail, end,
note, group.

Use node.from for ordinary connections. Use "conditionId.branch" for condition
branches. Do not invent connectsTo, next, source, target, type, label-only
Mermaid, or React Flow JSON as the primary contract.

## Cards and Visual Content

Every non-group workflow node renders as a card in React and in static/share
exports. Pick the card kind with node.kind, then put the visible card header in
title and body copy in description. Use kind-specific fields for semantics:
- tool cards: kind="tool", title names the tool action, ref stores the MCP/tool/function name.
- ai cards: kind="ai", model and prompt are optional details.
- condition cards: kind="condition", branches declares the outgoing branch names.

Use node.data.card only for extra serializable card content: title,
description, badges, meta, progress, and footer. Do not emit HTML/SVG/React
components in data.card. Do not create separate "card" nodes; create workflow
nodes and let Wire render them as cards.

Put card visual styling in node.tone and node.style, not in CSS or data.card.
Use node.style.fill, stroke, strokeWidth, borderRadius, shadow, opacity, and
textColor only when the diagram needs explicit visual overrides.

## Wiring Rules

Wire direction is target-centric. To connect A -> B, set B.from = "A". For a
condition branch, set the target's from to "conditionId.branch" and ensure the
branch exists in the condition node's branches array. Use explicit edges only
for labels, custom handles, edge styles, routing, or stable edge ids. Never
create the same connection in both node.from and edges[].

## Tool Selection

- create_diagram: create empty or template-backed diagrams.
- load_diagram/get_diagram_json: read canonical JSON.
- apply_actions: preferred for multi-node or multi-edge edits.
- add_node/update_node/remove_node: direct single-node edits.
- connect/disconnect/update_edge/remove_edge: direct edge edits.
- validate: schema and structural checks with repair hints.
- render_preview: browser/share URLs; cloud URLs when WIRE_CLOUD_URL and WIRE_CLOUD_API_KEY are set.
- render_svg/render_png/export_mermaid: raw assets and export formats.
- v1_get_docs_shape: structured docs chunks for agent decisions.

Use explicit edges when labels, branches, handles, style, routing, or stable
edge ids are needed. Explicit edge fields include id, from, to, branch, label,
tone, fromHandle, toHandle, style, labelStyle, routing, and data. Use
update_edge to patch explicit edges.

## React Build Path

Use @aigentive/wire-react. Prefer WireWorkspace for full editors and
WireProvider + WireCanvas for custom shells. Persist the WireDiagram emitted
from onChange. Do not store React Flow nodes as application state.

## Cloud Path

Authenticated users can generate a Wire Cloud API key. Local MCP clients should
start @aigentive/wire-mcp with WIRE_CLOUD_URL and WIRE_CLOUD_API_KEY. Then
list_diagrams, save_diagram, apply_actions, validate, and render_preview operate
against the user's cloud wires.

Authenticated /wires chat is separate from the MCP cloud key. It requires the
user to save an OpenAI API key in the right chat sidebar. The hosted app stores
that key encrypted on the user's account through /api/user/openai-key, and
/api/wires/{id}/chat refuses LLM edits until the key is configured.

## Repair Loop

If a save or validation fails, do not guess from prose. Read the validation code,
repair the exact field, run validate again, then summarize what changed.

## Hosted Persistence Contract

Hosted apps should store canonical Wire JSON, validate before save, and persist
every accepted editor change from onChange. Cloud share links should expose
separate view and edit tokens; view tokens may expose browser, SVG, PNG, JSON,
and Mermaid assets, while edit tokens should only be minted intentionally.