compose-diagram

Compose Diagram

You build and edit LeanIX diagrams by composing tool calls — never by writing XML yourself.

"Canvas" means "diagram." Users may call it a canvas ("put this on a canvas", "add to my canvas"); it is the same thing — the LeanIX diagram you build with these tools. Treat the two terms as interchangeable throughout this skill.

CRITICAL: API Access

All LeanIX API calls use MCP tools. No shell commands, no token exchange, no curl.

• Authentication is handled internally by the MCP server
• No bearer tokens need to be managed in the skill workflow
• No .mcp.json parsing is required — MCP handles credentials automatically

Before any LeanIX tool call: if only mcp__leanix__authenticate and mcp__leanix__complete_authentication are available, tell the user to run /mcp and authenticate the leanix server (browser opens automatically). Do NOT call authenticate yourself or suggest claude mcp add — the former returns a URL without triggering the browser flow (copy-paste UX), the latter would shadow the plugin's bundled server. If /mcp doesn't surface tools after auth, treat it as a plugin bug.

Golden rules

These govern every request. The rest of this skill elaborates on them.

1. mcp__leanix__create_diagram_draft + mcp__leanix__commit_diagram_draft are a transaction pair (BEGIN/END). Every draft you open MUST be committed on the same draft_id, with at least one mutation in between. NEVER open a draft just to read a diagram (use mcp__leanix__get_diagram_by_id); NEVER open→commit with no change (a no-op that, for a new diagram, saves an empty one). This flow exists for editing only. If you open a draft, you own committing it — do not abandon it.
2. Call tools strictly sequentially — NEVER in parallel. Issue one call, wait for its diff, then the next. Each mutation depends on the prior one's draft_id and cell IDs, so a parallel batch is not supported.
3. NEVER produce, copy, or hand-edit XML. The server owns the XML; you change it only through tools, passing intent and parameters. mcp__leanix__create_diagram_draft may return the draft's XML once as a read-only reference — read it, never write it back.
4. HTML in a cell's value MUST be raw, NEVER XML-escaped. When a cell uses html=1, pass emphasis markup literally — <b>SAP</b>, <br>, <font color="#6c8ebf">…</font> — NEVER escaped (<b>SAP</b>). Escaped tags render as visible literal text (<b>SAP</b> shown on the diagram) instead of formatting, which silently breaks the diagram's appearance. This is non-negotiable for every cell that carries styled text.
5. Diagrams must always look good — clean, readable layout is a hard requirement, not a nice-to-have. Shapes MUST NOT overlap unless overlap is explicitly intended: before placing or moving any cell, check that its x, y, width, and height are compatible with what is already on the diagram, and leave clear spacing between elements. Give text containers (summaries, legends, titles, annotations) enough height that their text never overlaps — when unsure, err on the side of a taller container rather than a cramped one. Route relations so edges do not cross fact sheets or pile up on each other (see Placing dependencies).
6. Prefer acting over asking. Default to producing a reasonable result: search, use what you find, apply sensible defaults, and let the user refine after seeing it — don't describe a plan and wait for confirmation on routine requests. But when a request is genuinely ambiguous (unclear what to diagram, which entities, or what the goal is) and a best-effort guess would likely be wrong, ask a brief clarifying question first.
7. Always search then add — resolve a fact sheet by name/attribute, never ask the user for a fact_sheet_id.
8. Always give the user the diagram's URL after committing. Call mcp__leanix__get_diagram_by_id for it and include it in your reply. The URL is stable (the diagram_id never changes), so fetch it once per diagram and reuse it across later edits.
9. LeanIX data uses the fact-sheet tools; plain visuals use the cell/edge tools — never substitute one for the other. A LeanIX entity → mcp__leanix__add_diagram_fact_sheet_cell, NEVER mcp__leanix__add_diagram_cell. A real relation between fact sheets → mcp__leanix__add_diagram_dependencies (or mcp__leanix__add_diagram_drill_down for hierarchical), NEVER mcp__leanix__add_diagram_edge — this holds even when both fact sheets are already on the diagram: connect them with mcp__leanix__add_diagram_dependencies, do NOT hand-place cells and wire them with a plain edge. A plain edge between two fact sheets is acceptable ONLY when the line represents some other, non-LeanIX semantic link. See Tool choice for why and the full mapping.