drawio-ai-kit

An orchestration and validation framework enabling AI agents to generate structurally precise and aesthetically standardized draw.io diagrams, optimized for AWS, Azure & GCP architectures.

It mitigates common AI agent hallucinations (such as generating non-existent stencil IDs that result in empty shapes) using three key components:

1. Declarative Catalog — A single source of truth mapping draw.io stencil IDs (mxgraph.aws4.*) to their respective taxonomies and canonical color palettes.
2. Design Principles — Codified architectural and layout rules (rules/principles.md).
3. Structural Validator — A static analysis engine that audits diagram XML to guarantee stencil references are valid and design principles are satisfied prior to serialization.

Exposed to the AI via the zero-dependency drawio-ai CLI.

Showcase

One diagram per platform — all generated end-to-end by the kit: no hand-placed coordinates, real stencils, validated, vision-checked. Full set in examples/.

Quick start

Full install — the CLI plus all 5 Domain Skills (AWS, Azure, GCP, Databricks, BPMN) — in one line:

npm i -g github:sparklabx/drawio-ai-kit && npx skills add sparklabx/drawio-ai-kit

Restart your agent, then try: "draw an AWS 3-tier web app".

The first command puts the drawio-ai binary on PATH (installs straight from GitHub — not yet on the npm registry; see INSTALL.md to pin a version or install from a clone). The second registers the Domain Skills with your agent (the skills CLI auto-detects Claude Code, Codex, Gemini CLI, …) — without it the agent never picks the kit up on its own.

• Just one domain instead: npx skills add sparklabx/drawio-ai-kit --skill drawio-aws (--list previews all 5)
• Optional, for the full experience: the draw.io desktop app enables drawio-ai render (the vision self-check); Graphviz enables vendor/autolayout.py for large graphs. Details in INSTALL.md.

Is it safe to install?

Short answer: yes — and you don't have to take my word for it.

• No hidden code. No postinstall (or any lifecycle) hooks — nothing runs on npm install. Zero runtime dependencies. No sudo, no curl | bash, no remote code.
• Zero runtime dependencies. The single dependency (@modelcontextprotocol/sdk) was removed at 1.0.0. The package is now fully self-contained.
• Runs locally, no telemetry. The CLI only reads/writes local files. The single optional outbound call is icon-logo fetching from public CDNs (lobe-icons), and it's opt-in.
• Easy to undo:

npm uninstall -g drawio-ai-kit              # remove the CLI
npx skills remove drawio-aws              # remove a domain skill (repeat for each)

• Updating — two independent channels:

npm i -g github:sparklabx/drawio-ai-kit   # CLI/engine (icon search, workflow, validator, rules)
npx skills update                         # the Domain Skills (SKILL.md) — always pulls latest

The skills are thin frontends that call drawio-ai at runtime, so engine fixes reach you the moment you update the CLI — no skill re-install needed. npx skills update only refreshes the SKILL.md text. Pin a specific release with github:sparklabx/drawio-ai-kit#v1.0.1.

To report a security issue, see SECURITY.md.

Build a diagram — declarative, no hardcoded coordinates

Define a diagram topology (pipeline/hierarchy/network/hubspoke/hybrid/mesh/sequence), declare the nested structure, and the layout engine programmatically computes spatial coordinates (x/y/w/h) — frames auto-size to fit their children, while rows and columns auto-space. You define the logical topology, not raw pixels.

import { Diagram } from "./src/builder.mjs";
import { group, icon, box, renderTree } from "./src/layout-engine.mjs";

const d = new Diagram("network");
const tree = group("region", "group_region", "Region", { dir: "row" }, [
  group("vpc", "group_vpc", "VPC", { dir: "col" }, [
    icon("alb", "elastic_load_balancing", "ALB"),
    icon("ec2", "ec2", "EC2"),
  ]),
]);
renderTree(d, tree);                 // engine lays everything out + sizes the page
d.title("My VPC");
d.link("alb", "ec2");                // edges by id; router picks straight/corridor
const res = d.validate();            // names real? colors/nesting/labels clean?
// d.mxfile("My VPC")  → write to .drawio, export PNG, then vision self-check

Icon names are retrieved from drawio-ai search to prevent name fabrication; edge routing, container sizing, alignment, and contextual corner styles are dynamically computed. The AI agent defines the logical layout and iterates via a render-analyze-rectify loop (vision-based self-correction). Example: examples/aws/build_mesh.mjs (zero manual coordinates).

Migration (from <1.0)

At 1.0.0 the MCP server and bespoke installer were removed. To migrate:

• Install: switch from claude mcp add ... mcp-server.mjs to npm i -g github:sparklabx/drawio-ai-kit.
• Skills: replace the old drawio-cloud-architect skill with the 5 thin Domain Skills — all at once with npx skills add sparklabx/drawio-ai-kit, or per domain with --skill drawio-aws etc.
• Vision self-check: the inline image was replaced by drawio-ai render → PNG → Read.
• Uninstall: npm uninstall -g drawio-ai-kit + remove each skill via the skills tooling.

Template library (examples/)

Each file builds one common architecture via the layout engine (zero hardcoded coordinates) — copy one as a starting point. Examples are organized into domain subfolders — see examples/README.md for the full index. Run any with node examples/<dir>/<file> → writes to out/*.drawio.

examples/aws/

examples/azure/ · gcp/ · databricks/ · multicloud/ · bpmn/

Runtime architecture

• Node 18+ (.nvmrc pins the current LTS) — orchestration and validation layer: CLI and validator (src/). Supported runtimes include Node 20, 22 (LTS), or 24.
• Python 3.11 (.python-version) — data ingestion and compilation pipeline: catalog generator + icon-pack builder (scripts/build_pack.py, stdlib only).

Install the dependencies:

nvm install --lts && nvm use --lts    # or: brew install node
brew install python@3.11              # then: python3.11 --version

CLI commands