Diagram Generator

--- name: diagram-generator description: Generate and edit diagrams with the mcp-diagram-generator MCP server. Use this skill for new diagrams, existing .drawio/.mmd/.excalidraw edits, network topology, architecture, flowchart, swimlane, sequence, class, ER, and Excalidraw whiteboard work. Always use this skill when the user asks to draw, generate, revise, or export any diagram. --- # Diagram Generator ## Purpose Create and edit diagrams by converting user intent into a structured JSON specification, then delegating file generation to the `mcp-diagram-generator` MCP server. Supported formats: - Draw.io: `.drawio` - Mermaid: `.mmd` or markdown Mermaid content - Excalidraw: `.excalidraw` Supported work: - Natural-language diagram creation - Existing `.drawio`, `.mmd`, and `.excalidraw` edits - Default output paths under `diagrams/{format}/` - Custom filenames and output paths ## Required MCP Tools Before generating a diagram, verify that the MCP server tools are available: - `mcp__mcp-diagram-generator__get_config` - `mcp__mcp-diagram-generator__generate_diagram` - `mcp__mcp-diagram-generator__init_config` If the tools are missing, configure the MCP server. Recommended remote configuration: ```json { "mcpServers": { "mcp-diagram-generator": { "command": "npx", "args": ["-y", "mcp-diagram-generator"] } } } ``` After changing configuration, restart the agent environment. On first use, the server creates `.diagram-config.json` and default output directories. For local development configuration, see the "Tool missing" entry in Troubleshooting. ## Main Workflow ### 1. Intake For new diagrams, collect the basic options before accepting or processing the full diagram prompt: - Diagram type - Output format - Layout direction - Usage context - Optional filename or output directory Read `references/interaction-intake-guide.md` before asking intake questions. Skip intake when the user already provided all required options and the full prompt. For existing-file edits, ask only for the target file and requested changes if missing. ### 2. Dispatch To A Playbook Select exactly one primary playbook based on the diagram type: | User Intent | Primary Playbook | | --- | --- | | Network topology, datacenter, zone, router, switch, firewall | `references/playbook-network-topology.md` | | System architecture, application architecture, layered component diagram | `references/playbook-architecture.md` | | Flowchart, process, decision tree | `references/playbook-flowchart.md` | | Swimlane, cross-team handoff, approval workflow by department | `references/playbook-swimlane.md` | | Sequence, class, ER, UML-style diagrams | `references/playbook-uml.md` | | Whiteboard sketch, hand-drawn style, informal Excalidraw diagram | `references/playbook-excalidraw.md` | | Unsure about format | `references/format-selection-guide.md` first, then the matching playbook | Only read the playbook needed for the current diagram. If a playbook points to `json-schema-guide.md` or `network-topology-examples.md`, read only the relevant section. For explicit geometry, also read `references/layout-quality-guide.md`. ### 3. Choose Format Use these defaults unless the user explicitly chooses otherwise: | Diagram Type | Default Format | Default Direction | | --- | --- | --- | | Network topology | Draw.io | Vertical | | Architecture | Draw.io | Vertical or automatic | | Flowchart | Mermaid | Vertical | | Swimlane | Draw.io | Horizontal | | Sequence | Mermaid | Automatic | | Class | Mermaid | Automatic | | ER | Mermaid | Automatic | | Whiteboard sketch | Excalidraw | Automatic | Usage context can override defaults: - Word: prefer portrait-friendly vertical layouts. - PPT: horizontal layouts are acceptable when readability improves. - Code repositories and documentation: prefer Mermaid for simple flow, sequence, class, and ER diagrams. - Whiteboard collaboration: prefer Excalidraw. - Complex network or architecture diagrams: prefer Draw.io unless the user explicitly asks for Excalidraw. ### 4. Build The JSON Specification Follow `references/json-schema-guide.md` for the schema. Core structure: ```json { "format": "drawio", "diagramType": "architecture", "title": "Diagram title", "elements": [ { "id": "unique-id", "type": "container", "name": "Display name", "level": "environment", "geometry": { "x": 0, "y": 0, "width": 800, "height": 600 }, "children": [] }, { "type": "edge", "source": "source-id", "target": "target-id" } ] } ``` Universal rules: - `elements` must be an array. - IDs must be unique. - Edges must be top-level elements, never inside `children`. Full field reference: `references/json-schema-guide.md`. ### 5. Quality Gate Before calling the MCP server, verify: - The chosen format matches the intake answer and playbook. - `diagramType` is explicit when supported. - Layout direction is reflected in coordinates or generator-specific fields. - Complex Draw.io and Excalidraw diagrams have explicit `geometry`. - Container hierarchy is valid. - Edges are top-level elements. - Text and connector rules for the selected format are followed. After generation, inspect the saved file enough to confirm the expected format-specific properties exist. For code changes to the MCP server, also run `npm run test:diagrams` from `mcp-diagram-generator/`. ### 6. Generate Preferred call: ```json { "diagram_spec": "" } ``` Optional filename: ```json { "diagram_spec": "", "filename": "my-diagram.drawio" } ``` Optional explicit output path: ```json { "diagram_spec": "", "output_path": "custom/path/to/diagram.drawio" } ``` The MCP server validates the schema, creates missing directories, and writes to the configured default directory when no output path is supplied. ## Configuration Helpers Initialize defaults: ```text init_config() ``` Set custom paths: ```json { "paths": { "drawio": "output/diagrams/drawio", "mermaid": "output/diagrams/mermaid", "excalidraw": "output/diagrams/excalidraw" } } ``` Inspect configuration: ```text get_config() ``` Update one format path: ```json { "format": "drawio", "path": "custom/drawio-path" } ``` ## Troubleshooting Tool missing: - Configure the MCP server with the remote (npx) block above and restart the agent environment. - For local development, use `"command": "node", "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"]` instead. Schema validation failed: - Read `references/json-schema-guide.md`. - Check required fields, unique IDs, edge source/target, and parent-child structure. Directory error: - Check write permissions. - Run `get_config()`. - Reinitialize with `init_config()` if needed. Wrong extension: - Draw.io uses `.drawio`. - Mermaid uses `.mmd` or markdown output. - Excalidraw uses `.excalidraw`. Nested container issue: - Child coordinates are relative to the direct parent. - Container sizes must fit child bounds plus padding. - Network topology must follow environment -> datacenter -> zone -> device. ## Reference Index Read only what is needed: - `references/interaction-intake-guide.md`: interactive intake defaults and question template. - `references/format-selection-guide.md`: format selection matrix. - `references/playbook-network-topology.md`: Draw.io and Excalidraw network topology rules. - `references/playbook-architecture.md`: layered architecture rules. - `references/playbook-flowchart.md`: process and decision flow rules. - `references/playbook-swimlane.md`: swimlane and handoff rules. - `references/playbook-uml.md`: sequence, class, and ER rules. - `references/playbook-excalidraw.md`: Excalidraw whiteboard and binding rules. - `references/layout-quality-guide.md`: explicit geometry, spacing, and connector readability rules. - `references/json-schema-guide.md`: schema details and examples. - `references/network-topology-examples.md`: network topology JSON patterns. ## Output Discipline When responding to the user: - Confirm the selected diagram type, format, direction, and output file. - Do not paste the full JSON unless the user asks. - Provide the saved file path. - Mention any validation or regression command that was run.