Draw.io Architecture Diagrams

Generate Azure architecture diagrams in .drawio format using the simonkurtz-MSFT Draw.io MCP server. The server ships the full Azure icon set (see assets/azure-public-service-icons/), fuzzy shape search, batch operations, group/layer/page management, and transactional mode for efficient multi-step workflows.

The MCP server's own src/instructions.md is the authoritative tool reference; it is auto-sent to the client at startup. This skill captures project-specific conventions that complement (not duplicate) it.

Naming note: "drawio" can refer to (a) this skill, (b) the MCP server slug simonkurtz-MSFT/drawio-mcp-server, or (c) the mcp_drawio_* tool family. In agent-facing references, disambiguate explicitly — say "the drawio skill" or "the drawio MCP server", not bare drawio.

Prerequisites

• MCP server: simonkurtz-MSFT/drawio-mcp-server (Deno, stdio) configured in .vscode/mcp.json
• Deno runtime: installed via devcontainer feature
• VS Code extension (optional): hediet.vscode-drawio for in-editor preview

MCP Workflow Summary

The MCP server's startup src/instructions.md is the authoritative tool reference. The table below lists the most-used tools and the repo-specific batch sequence. Reusable call patterns: references/azure-patterns.md.

Standard sequence: search-shapes → create-groups → add-cells → add-cells-to-group → (optional edit-*) → validate-group-containment → finish-diagram / export-diagram (compress: true).

import-diagram input contract (CRITICAL — Phase D3 of nordic-foods lessons plan): when calling import-diagram (or any tool whose schema declares an xml parameter), the field MUST be XML content as a string — never a file path. Passing a bare path/to/file.drawio string produces INVALID_XML from the server and burns an MCP round trip. If you have a path on disk:

WRONG: import-diagram(xml="agent-output/foo/03-des-diagram.drawio")
RIGHT: read_file("agent-output/foo/03-des-diagram.drawio") → import-diagram(xml=<content>)

Mirror this warning in 04-design.agent.md next to every import-diagram reference. The two locations must stay in sync.

CLI Fallback

There is no programmatic CLI fallback for diagram authoring. The Draw.io desktop app is the only manual alternative; if the MCP server is unavailable, stop and surface the failure rather than hand-rolling XML. The tools/scripts/save-drawio.py and cleanup-drawio.py helpers are post-processing utilities for MCP output, not authoring fallbacks.

Icon Handling

Icons are resolved automatically by the MCP server from its built-in library (the full Azure icon set bundled with the server).

• shape_name in add-cells specifies an Azure icon (e.g., "Front Doors"). Do NOT pass width, height, or style alongside it — the server applies them.
• search-shapes with a queries array finds icon names by fuzzy match.
• Azure icons use official service names, often plural ("Key Vaults", "Container Apps").
• Every shaped vertex MUST have a text label or omit text entirely — never pass "".
• Output format is embedded base64 SVG in the style attribute.

Diagram Creation Workflows

Two modes — non-transactional (small diagrams, full XML each call) and transactional (recommended for multi-step; lightweight placeholders during the loop, real SVGs resolved by finish-diagram at the end). Full call chains, the save-drawio.py save procedure, and the post-save cleanup script live in references/creation-workflows.md.

Critical: transactional mode MUST end with finish-diagram(compress: true) or the saved diagram keeps placeholder cells instead of real Azure icons.

Rules

• Batch-only workflow — every tool that accepts an array MUST be called exactly ONCE with all items; never call a tool repeatedly for individual items (see Batch-Only Workflow (CRITICAL) below)
• Use shape_name for Azure icons — do NOT pass width, height, or style alongside it; the server applies them
• Every shaped vertex MUST have a text label or omit text entirely — never pass ""
• Vertices first in add-cells — edges must be ordered after the vertices they reference
• Transactional mode for multi-step diagrams — use placeholders + finish-diagram at the end (~2KB intermediate vs ~200KB)
• Use compress: true on export-diagram / finish-diagram to keep .drawio files small
• Do NOT pipe large MCP JSON back through the LLM — use python3 tools/scripts/save-drawio.py to extract via terminal
• Out of scope: WAF / cost charts (use python-diagrams), inline Mermaid (use mermaid)

Steps

Every tool that accepts an array MUST be called exactly ONCE with all items. Never call a tool repeatedly for individual items.

1. search-shapes — ONE call with all queries (main flow + cross-cutting)
2. create-groups — ONE call with all groups. Set text: "" and create a separate text vertex above each group
3. add-cells — ONE call with all vertices AND edges, vertices first. Use temp_id for cross-refs, shape_name for icons
4. add-cells-to-group — ONE call with all assignments
5. edit-cells / edit-edges — ONE call if adjustments are needed
6. finish-diagram (transactional) or export-diagram (default) — with compress: true

After group assignments, call validate-group-containment to detect children that exceed group bounds.

Token efficiency

• MCP server is NOT stateful — pass diagram_xml from the previous call on every subsequent call. Save XML to a temp file between steps; read only the IDs you need rather than the whole JSON.
• Never read back large MCP responses through the LLM — extract data via terminal commands.
• Target 8–10 model turns for a complete diagram. Pre-compute the full layout before making any MCP calls.

Layout Conventions

Concise summary; load references/style-reference.md → "Layout Conventions (extended)" for full detail (numbered callouts, fan-out staggering, legend HTML, group sizing, non-Azure component styling).

• Primary flow: left-to-right; parallel services stacked vertically per column
• Spacing minimums: 120px between columns, 80px between rows, 40px around each cell; groups need ≥150px width per icon
• Page: US Letter 850×1100px (extend to 1300px if a legend is included); 40px margins
• Edges: orthogonal only (edgeStyle=orthogonalEdgeStyle); never set entryX/Y / exitX/Y and never add <Array as="points"> waypoints. Target specific icons inside groups, not the group cell
• Cross-cutting services (Azure Monitor, Entra ID, Key Vault, Defender): single light-grey rounded container at the bottom, 120px apart, no edges into them
• Legend: required on every diagram, below the cross-cutting box; use inline HTML for arrow indicators; explicitly set text: "" on shape samples
• External actors (Users, Operators): outside all group boundaries

Edge post-processing (CRITICAL): After finish-diagram, run tools/scripts/save-drawio.py to strip auto-router anchors and waypoints so Draw.io can recalculate clean orthogonal paths. The post-save cleanup script (cleanup-drawio.py) is documented in references/creation-workflows.md.

Gotchas

• text: "" breaks shapes — every shaped vertex MUST have a text label or omit text entirely; never pass "".
• No dimensions with shape_name — never pass width, height, or style when using shape_name; the MCP server auto-applies correct values.
• Transactional mode MUST end with finish-diagram — otherwise the diagram keeps ~2KB placeholders instead of real SVG icons.
• shape=image + image=data:image/svg+xml;base64,… is the RESOLVED form — do NOT confuse it with placeholder=1. After finish-diagram(compress: true), every Azure icon appears as shape=image;…;image=data:image/svg+xml;base64,<svg> with a multi-path Azure-brand SVG inside. The validator counts these as totalImages (real icons). The placeholder=1 style attribute is the ONLY marker of an unresolved transactional cell — count it with grep -c 'placeholder=1' file.drawio before declaring a diagram broken.
• Never read large MCP responses through the LLM — extract data via terminal (Python script) to avoid context-window inflation.
• Batch-only workflow — every tool accepting arrays is called ONCE with ALL items.
• No edge anchors or waypoints — never set entryX/Y, exitX/Y, or add <Array as="points"> to edges.

Reference Index

Quality Reference Examples