diagram-generator

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:

{
  "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:

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:

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:

{
  "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:

{
  "diagram_spec": ""
}

Optional filename:

{
  "diagram_spec": "",
  "filename": "my-diagram.drawio"
}

Optional explicit output path:

{
  "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:

init_config()

Set custom paths:

{
  "paths": {
    "drawio": "output/diagrams/drawio",
    "mermaid": "output/diagrams/mermaid",
    "excalidraw": "output/diagrams/excalidraw"
  }
}

Inspect configuration:

get_config()

Update one format path:

{
  "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.