drawio

Draw.io Architecture Diagrams

Generate Azure architecture diagrams in .drawio format using the simonkurtz-MSFT Draw.io MCP server. The server has 700+ built-in Azure icons, fuzzy shape search, batch operations, group/layer/page management, and transactional mode for efficient multi-step workflows.

Authoritative reference: The MCP server's own src/instructions.md (519 lines) is the canonical guide for tool parameters, layout rules, and workflow patterns. It is automatically sent to the MCP client at startup via the server's instructions field — agents receive it in context without needing to read it. This skill provides project-specific conventions that complement (not duplicate) it.

Prerequisites

• Draw.io MCP server: simonkurtz-MSFT/drawio-mcp-server (Deno, stdio) configured in .vscode/mcp.json
• Deno runtime: Installed via devcontainer feature ghcr.io/devcontainers-community/features/deno
• VS Code extension (optional): hediet.vscode-drawio for in-editor preview

MCP Workflow Summary

Use the MCP server's startup instructions as the authoritative tool reference. This skill only captures the repo-specific sequence and guardrails that must stay consistent across generated diagrams.

• search-shapes — resolve all Azure icons up front in one batch
• create-groups — create VNets, subnets, resource groups, or app environments
• add-cells — add all vertices and edges in one batch using shape_name and temp_id
• add-cells-to-group — assign all children to groups in one batch
• finish-diagram or export-diagram — emit final XML with compress: true

For reusable call patterns, see references/azure-patterns.md.

Icon Handling

Icons are resolved automatically by the MCP server from its built-in library (700+ Azure icons from assets/azure-public-service-icons/).

• Use shape_name in add-cells to specify Azure icons (e.g., shape_name: "Front Doors")
• Do NOT specify width, height, or style when using shape_name — the server auto-applies correct dimensions and styling
• Use search-shapes with a queries array to find icon names by fuzzy match
• Azure icons use their official service names, often plural (e.g., "Key Vaults", "Container Apps", "App Services")
• Every shaped vertex MUST have a text label or omit text entirely — never pass text: ""
• Output format is embedded base64 SVG in the style attribute

Diagram Creation Workflows

Workflow A: Non-Transactional (small diagrams)

For simple diagrams or single operations. Each tool call returns full XML with complete SVG image data.

search-shapes → add-cells → export-diagram(compress: true) → save .drawio

Workflow B: Transactional (recommended for multi-step)

For any multi-step diagram. Intermediate responses use lightweight placeholders (~2KB instead of ~200KB). Real SVGs are resolved once at the end via finish-diagram.

search-shapes
→ create-groups(transactional: true)
→ add-cells(transactional: true)
→ add-cells-to-group(transactional: true)
→ edit-cells(transactional: true)     [if needed]
→ finish-diagram(compress: true)       [resolves all placeholders]
→ save .drawio via terminal command

CRITICAL: When using transactional mode, you MUST call finish-diagram at the end. Without it, the diagram contains placeholder shapes instead of real icons.

Saving .drawio Files

When finish-diagram or export-diagram returns XML in a JSON response, use the helper script to decompress, strip edge anchors, and save in one step:

python3 scripts/save-drawio.py '<temp-content-json-path>' '<output-path>.drawio'
node scripts/validate-drawio-files.mjs '<output-path>.drawio'

The script handles: compressed content decompression, mxGraphModel embedding (repo validator format), edge anchor/waypoint stripping, and directory creation.

Do NOT read the large MCP JSON response back through the LLM — extract data via terminal commands to avoid inflating the context window.

Batch-Only Workflow (CRITICAL)

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 in the queries array (main flow + cross-cutting)
2. create-groups — ONE call with ALL groups. Set text: "" for groups; create separate text vertex above.
3. add-cells — ONE call with ALL vertices AND edges. Vertices before edges. Use temp_id for cross-refs, shape_name for icons.
4. add-cells-to-group — ONE call with ALL assignments. Server auto-converts absolute → group-relative coords.
5. edit-cells/edit-edges — ONE call if adjustments needed.
6. finish-diagram (transactional) or export-diagram (default) — with compress: true.

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

Token Efficiency

• The MCP server is NOT stateful between tool calls. You MUST pass diagram_xml from the previous call's response on every subsequent call. Save the XML to a temp file between steps and read it back rather than inflating the LLM context with the full XML in every turn.
• Do NOT read back large MCP responses through the LLM. When a tool result is written to a temp file, extract only the data you need via a terminal command (e.g., cell IDs) rather than reading the entire JSON into context.
• Target 8–10 model turns for a complete diagram. Pre-compute the full layout (all vertices, edges, groups, assignments) before making any MCP calls, then execute the batch workflow in sequence.

Layout Conventions

General Rules

• Primary flow: left-to-right. Each stage occupies a column.
• Parallel services: stacked vertically within their column, never side-by-side.
• Spacing: 120px horizontal between columns, 80px vertical between rows, 40px around each cell.
• Page: US Letter 850×1100px. Content within 40px margins (usable: 770×1020).
• No overlapping: Components must not overlap each other.

Groups

• Create groups for VNets, subnets, Container Apps Environments, resource groups.
• Set text: "" for groups — create a separate bold text vertex above the group instead.
• Use suggest-group-sizing to calculate dimensions based on child count.

Edges

• Orthogonal only: Use edgeStyle=orthogonalEdgeStyle (the default).
• NO anchor points: Never set entryX, entryY, exitX, exitY in your edge style.
• NO waypoints: Do not add <Array as="points"> or <mxPoint> elements.
• Side exits preferred: edges exit/enter through left or right sides.
• One edge per source into a group: target the group cell, not children inside.
• No edges to cross-cutting services: their presence is implied.
• Fan-out staggering: When multiple edges leave the same source, keep them minimal. Consider merging semantically similar paths (e.g., "Partner Data Export" instead of Storage → Data Share → Partners as 3 separate edges).

CRITICAL — Post-Processing Required: The MCP server's auto-router injects exitX/exitY/entryX/entryY anchor points and <Array> waypoints into every edge it creates. These computed routes are poor for fan-out patterns and cause edges to pile up in horizontal corridors. After finish-diagram, the agent MUST run scripts/save-drawio.py which strips these injected anchors and waypoints, letting Draw.io's client-side renderer calculate clean orthogonal paths when the file is opened.

Cross-Cutting & Supporting Services

Place Azure Monitor, Entra ID, Key Vault, Azure Policy, Defender for Cloud, Container Registry, DNS Zones, Application Insights, Log Analytics at the bottom of the diagram, 120px below the main flow. No edges to them. Space 100px apart (center-to-center). Wrap into multiple rows at page width.

Use the Azure-aligned color palette from get-style-presets and the style examples in references/style-reference.md. Standard output filenames and the validation checklist live in references/validation-checklist.md.

Reference Index

File	Purpose
references/style-reference.md	Draw.io style properties for AI-generated files
references/azure-patterns.md	Reusable MCP tool call patterns for Azure architectures
references/validation-checklist.md	Validation rules for AI-generated .drawio files
references/abstraction-rules.md	Diagram abstraction and data-flow clarity rules
references/iac-to-diagram.md	Generate diagrams from Bicep/Terraform/ARM templates

Quality target samples: tmp/azure-architecture-example.drawio, tmp/03-des-diagram.svg