mirror of
https://github.com/jgraph/drawio-mcp.git
synced 2026-09-14 15:42:06 +08:00
feat: single source of truth for XML generation prompt
Move the draw.io XML generation reference to shared/xml-reference.md and wire all four consumers to use it instead of duplicating the content. Add layers, tags, and metadata/placeholders documentation. - MCP app server: reads at startup (Node.js) or pre-builds into generated-html.js (Workers) via build-html.js - MCP tool server: reads at startup with fallback to local copy; prepack script bundles the file before npm publish - Skill: references the GitHub raw URL so it works after install - Project instructions: tells users to copy from GitHub Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Gaudenz Alder
@@ -4,6 +4,7 @@ The official draw.io MCP (Model Context Protocol) server that enables LLMs to op
|
||||
|
||||
## Repository Structure
|
||||
|
||||
- **`shared/`** — Shared XML generation reference (`xml-reference.md`), the single source of truth for all LLM prompts.
|
||||
- **`mcp-app-server/`** — MCP App server (renders diagrams inline in chat via iframe). Hosted at `https://mcp.draw.io/mcp`. Can also be self-hosted via Node.js or Cloudflare Workers.
|
||||
- **`mcp-tool-server/`** — Original MCP tool server (stdio-based, opens browser). Published as `@drawio/mcp` on npm.
|
||||
- **`project-instructions/`** — Claude Project instructions (no MCP required, no install).
|
||||
@@ -83,119 +84,15 @@ Opens the draw.io editor with a Mermaid.js diagram definition.
|
||||
4. **Validate syntax**: Ensure Mermaid/CSV/XML syntax is correct before sending
|
||||
5. **Return the URL to users**: Always provide the generated URL so users can open the diagram in their browser
|
||||
|
||||
## Edge Routing Best Practices
|
||||
## XML Reference (Single Source of Truth)
|
||||
|
||||
**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
|
||||
```xml
|
||||
<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
|
||||
<mxGeometry relative="1" as="geometry" />
|
||||
</mxCell>
|
||||
```
|
||||
The complete draw.io XML generation reference — including edge routing, containers, layers, tags, metadata, dark mode colors, style properties, and XML well-formedness rules — lives in a single canonical file:
|
||||
|
||||
draw.io does **not** have built-in collision detection for edges. You must plan layout and routing carefully:
|
||||
**`shared/xml-reference.md`**
|
||||
|
||||
- Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors (most common)
|
||||
- **Space nodes generously** — at least 60px apart, prefer 200px horizontal / 120px vertical gaps
|
||||
- Use `exitX`/`exitY` and `entryX`/`entryY` (values 0–1) to control which side of a node an edge connects to. Spread connections across different sides to prevent overlap
|
||||
- **Leave room for arrowheads**: The final straight segment of an edge (between the last bend and the target shape, or between the source shape and the first bend) must be long enough to fit the arrowhead. The default arrow size is 6px (configurable via `startSize`/`endSize` styles). If the final segment is too short, the arrowhead overlaps the bend and looks broken. Ensure at least 20px of straight segment before the target and after the source when placing waypoints or positioning nodes
|
||||
- When using `orthogonalEdgeStyle`, the auto-router places bends automatically — if source and target are close together or nearly aligned on one axis, the router may place a bend very close to a shape, leaving no room for the arrow. Fix this by either increasing node spacing or adding explicit waypoints that keep the final segment long enough
|
||||
- Add explicit **waypoints** when edges would overlap:
|
||||
```xml
|
||||
<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="a" target="b">
|
||||
<mxGeometry relative="1" as="geometry">
|
||||
<Array as="points">
|
||||
<mxPoint x="300" y="150"/>
|
||||
<mxPoint x="300" y="250"/>
|
||||
</Array>
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
```
|
||||
- Use `rounded=1` on edges for cleaner bends
|
||||
- Use `jettySize=auto` for better port spacing on orthogonal edges
|
||||
- Align nodes to a grid (multiples of 10)
|
||||
All four delivery mechanisms (MCP App Server, MCP Tool Server, Skill + CLI, and Project Instructions) use this file as their single source of truth. The MCP servers read it at startup and include it in their tool descriptions. The skill and project instructions reference it via the GitHub URL.
|
||||
|
||||
## Containers and Groups
|
||||
|
||||
For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment — do **not** just place shapes on top of larger shapes.
|
||||
|
||||
### How containment works
|
||||
|
||||
Set `parent="containerId"` on child cells. Children use **relative coordinates** within the container.
|
||||
|
||||
### Container types
|
||||
|
||||
| Type | Style | When to use |
|
||||
|------|-------|-------------|
|
||||
| **Group** (invisible) | `group;` | Container has no connections and needs no visual border. Includes `pointerEvents=0` so child connections are not captured by the container |
|
||||
| **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar/header, or the container itself has connections |
|
||||
| **Custom container** | `container=1;pointerEvents=0;` added to any shape style | Any shape acting as a container without its own connections |
|
||||
|
||||
### Key rules
|
||||
|
||||
- **Always add `pointerEvents=0;`** to container styles that should not capture connections being rewired between children. This is critical for usability
|
||||
- Only omit `pointerEvents=0` when the container itself needs to be connectable — in that case, use `swimlane` style which handles this correctly (the client area is transparent for mouse events while the header remains connectable)
|
||||
- Children must set `parent="containerId"` and use coordinates **relative to the container**
|
||||
|
||||
### Example: Architecture container
|
||||
|
||||
```xml
|
||||
<!-- Swimlane container with title -->
|
||||
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
|
||||
</mxCell>
|
||||
<!-- Child inside container (relative coordinates) -->
|
||||
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="svc1">
|
||||
<mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;" vertex="1" parent="svc1">
|
||||
<mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
```xml
|
||||
<!-- Invisible group container -->
|
||||
<mxCell id="grp1" value="" style="group;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="c1" value="Component A" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="grp1">
|
||||
<mxGeometry x="10" y="10" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
## Dark Mode Colors
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black (or the system default dark color) in light theme and white (or the system default light color) in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180°. This is done by `mxUtils.getInverseColor` in the draw.io source code.
|
||||
- **`light-dark()` function** — To specify both light and dark colors explicitly, use `light-dark(lightColor,darkColor)` in the style string. The first argument is used in light mode, the second in dark mode. Example:
|
||||
```
|
||||
fontColor=light-dark(#7EA6E0,#FF0000)
|
||||
```
|
||||
This renders the text in blue (`#7EA6E0`) in light mode and red (`#FF0000`) in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`:
|
||||
```xml
|
||||
<mxGraphModel adaptiveColors="auto">
|
||||
<root>
|
||||
...
|
||||
</root>
|
||||
</mxGraphModel>
|
||||
```
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory and you need precise control over both appearances.
|
||||
|
||||
## Style Reference
|
||||
|
||||
For the complete draw.io style reference including all shape types, edge styles, color palettes, and more, see: https://www.drawio.com/doc/faq/drawio-style-reference.html
|
||||
|
||||
For the XML Schema Definition (XSD) for validating `.drawio` files: https://www.drawio.com/assets/mxfile.xsd
|
||||
|
||||
## CRITICAL: XML Well-Formedness
|
||||
|
||||
When generating draw.io XML, the output **must** be well-formed XML:
|
||||
- **NEVER include ANY XML comments (`<!-- -->`) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
|
||||
- Escape special characters in attribute values (`&`, `<`, `>`, `"`).
|
||||
When updating XML generation guidance, edit only this file — changes propagate to all consumers automatically.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
|
||||
@@ -66,6 +66,25 @@ An alternative approach that works **without installing anything**. Add instruct
|
||||
|
||||
---
|
||||
|
||||
## XML Reference (Single Source of Truth)
|
||||
|
||||
The draw.io XML generation reference — covering edge routing, containers, layers, tags, metadata, dark mode, style properties, and XML well-formedness — lives in a single canonical file:
|
||||
|
||||
**[`shared/xml-reference.md`](shared/xml-reference.md)**
|
||||
|
||||
All four approaches above use this file as their single source of truth for LLM prompts:
|
||||
|
||||
| Approach | How it accesses the reference |
|
||||
|----------|-------------------------------|
|
||||
| MCP App Server | Reads the file at startup / build time and includes it in the tool description |
|
||||
| MCP Tool Server | Reads the file at startup (from repo or bundled copy via `prepack`) |
|
||||
| Skill + CLI | References the [GitHub raw URL](https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md) |
|
||||
| Project Instructions | Users copy its contents into their Claude Project |
|
||||
|
||||
When updating XML generation guidance, edit only `shared/xml-reference.md` — changes propagate to all consumers automatically.
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
|
||||
@@ -69,17 +69,9 @@ The Worker uses **4 sharded Durable Objects** (`MCPSessionManager`) to manage al
|
||||
- CSP config goes on the **resource contents** `_meta.ui.csp`, not on the tool's `_meta.ui`
|
||||
- TypeScript narrowing: use `if (block.type === "text")` before accessing `.text` on content blocks
|
||||
|
||||
## Dark Mode Colors
|
||||
## XML Reference
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`).
|
||||
- **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`.
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory.
|
||||
The tool description for `create_diagram` is loaded at startup from `shared/xml-reference.md` (single source of truth for all prompts). The `xmlReference` string is passed to `createServer()` via options. For the Cloudflare Worker, it is pre-built into `generated-html.js` by `build-html.js`.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
|
||||
@@ -123,11 +123,15 @@ src/
|
||||
shared.js Shared logic: buildHtml(), processAppBundle(), createServer()
|
||||
index.js Node.js entry (Express + stdio transports)
|
||||
worker.js Cloudflare Workers entry (Web Standard fetch handler)
|
||||
build-html.js Build script: generates generated-html.js
|
||||
generated-html.js (gitignored) Pre-built HTML string for the Worker
|
||||
build-html.js Build script: generates generated-html.js + xml reference
|
||||
generated-html.js (gitignored) Pre-built HTML string + XML reference for the Worker
|
||||
wrangler.toml Wrangler configuration
|
||||
../shared/
|
||||
xml-reference.md Shared XML generation reference (single source of truth)
|
||||
```
|
||||
|
||||
The `create_diagram` tool description is loaded from `shared/xml-reference.md` at startup (Node.js) or pre-built into `generated-html.js` at deploy time (Workers). This file is the single source of truth for XML generation guidance across all four approaches in the repository.
|
||||
|
||||
### How the HTML is built
|
||||
|
||||
The server inlines two bundles into a self-contained HTML string:
|
||||
|
||||
@@ -29,10 +29,16 @@ const pakoDeflateJs = fs.readFileSync(
|
||||
"utf-8"
|
||||
);
|
||||
|
||||
// Read the shared XML reference (single source of truth for all prompts)
|
||||
const xmlReference = fs.readFileSync(
|
||||
path.join(__dirname, "..", "..", "shared", "xml-reference.md"),
|
||||
"utf-8"
|
||||
);
|
||||
|
||||
// Build the HTML and write it as an ES module export
|
||||
const html = buildHtml(appWithDepsJs, pakoDeflateJs);
|
||||
const outPath = path.join(__dirname, "generated-html.js");
|
||||
|
||||
fs.writeFileSync(outPath, `// Auto-generated by build-html.js — do not edit\nexport const html = ${JSON.stringify(html)};\n`);
|
||||
fs.writeFileSync(outPath, `// Auto-generated by build-html.js — do not edit\nexport const html = ${JSON.stringify(html)};\nexport const xmlReference = ${JSON.stringify(xmlReference)};\n`);
|
||||
|
||||
console.log(`Generated ${outPath} (${(html.length / 1024).toFixed(1)} KB)`);
|
||||
|
||||
@@ -55,6 +55,13 @@ if (process.env.VIEWER_PATH)
|
||||
}
|
||||
}
|
||||
|
||||
// Read the shared XML reference once at startup (single source of truth)
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const xmlReference = fs.readFileSync(
|
||||
path.join(__dirname, "..", "..", "shared", "xml-reference.md"),
|
||||
"utf-8"
|
||||
);
|
||||
|
||||
// Pre-build the HTML once
|
||||
const html = buildHtml(appWithDepsJs, pakoDeflateJs, { viewerJs });
|
||||
|
||||
@@ -106,7 +113,7 @@ async function startStreamableHTTPServer()
|
||||
return origEnd(chunk);
|
||||
};
|
||||
|
||||
const server = createServer(html, { domain: process.env.DOMAIN });
|
||||
const server = createServer(html, { domain: process.env.DOMAIN, xmlReference });
|
||||
|
||||
const transport = new StreamableHTTPServerTransport(
|
||||
{
|
||||
@@ -158,7 +165,7 @@ async function startStreamableHTTPServer()
|
||||
|
||||
async function startStdioServer()
|
||||
{
|
||||
await createServer(html, { domain: process.env.DOMAIN }).connect(new StdioServerTransport());
|
||||
await createServer(html, { domain: process.env.DOMAIN, xmlReference }).connect(new StdioServerTransport());
|
||||
}
|
||||
|
||||
async function main()
|
||||
|
||||
@@ -1406,7 +1406,7 @@ export function processAppBundle(raw)
|
||||
*/
|
||||
export function createServer(html, options = {})
|
||||
{
|
||||
const { domain, serverOptions = {} } = typeof options === "object" && options !== null
|
||||
const { domain, xmlReference = "", serverOptions = {} } = typeof options === "object" && options !== null
|
||||
? options
|
||||
: { serverOptions: options };
|
||||
const server = new McpServer(
|
||||
@@ -1423,25 +1423,8 @@ export function createServer(html, options = {})
|
||||
title: "Create Diagram",
|
||||
description:
|
||||
"Creates and displays an interactive draw.io diagram. Pass draw.io XML (mxGraphModel format) to render it inline. " +
|
||||
"IMPORTANT: The XML must be well-formed. Do NOT include ANY XML comments (<!-- -->) in the output — they are strictly forbidden. " +
|
||||
"EDGE GEOMETRY: Every edge mxCell MUST contain a <mxGeometry relative=\"1\" as=\"geometry\" /> child element, even when there are no waypoints. Self-closing edge cells (<mxCell ... edge=\"1\" ... />) are invalid and will not render correctly. " +
|
||||
"EDGE ROUTING: Use edgeStyle=orthogonalEdgeStyle for right-angle connectors. " +
|
||||
"Space nodes at least 60px apart to avoid overlapping edges. " +
|
||||
"Use exitX/exitY/entryX/entryY (0-1) to control which side of a node an edge connects to, spreading connections across different sides. " +
|
||||
"Add explicit waypoints via <Array as=\"points\"><mxPoint x=\"...\" y=\"...\"/></Array> inside mxGeometry when edges would overlap. " +
|
||||
"ARROWHEAD CLEARANCE: The final straight segment of an edge (between the last bend and the target, or source and first bend) must be long enough to fit the arrowhead (default size 6, configurable via startSize/endSize). If too short, the arrowhead overlaps the bend. Ensure at least 20px of straight segment. The orthogonal auto-router can place bends too close to shapes when nodes are nearly aligned - fix by increasing spacing or adding explicit waypoints. " +
|
||||
"CONTAINERS: For architecture diagrams and any diagram with nested elements, use proper parent-child containment (set parent=\"containerId\" on children, use relative coordinates). " +
|
||||
"Container types: (1) group style (style=\"group;\") for invisible containers with no connections - includes pointerEvents=0 so child connections are not captured by the container; " +
|
||||
"(2) swimlane style (style=\"swimlane;startSize=30;\") for labeled containers with a title bar - use when the container needs visual borders/headers or when the container itself has connections; " +
|
||||
"(3) any shape can be a container by adding container=1 to its style, but also add pointerEvents=0 unless the container itself needs to be connectable. " +
|
||||
"Always use pointerEvents=0 on container styles that should not capture connections being rewired between children. " +
|
||||
"EDGE LABELS: Do NOT wrap edge labels in HTML markup to reduce font size. The default font size for edge labels is already 11px (vs 12px for vertices), so they are already smaller. Just set the value attribute directly. " +
|
||||
"LAYOUT: Align nodes to a grid (multiples of 10). Use consistent spacing (e.g., 200px horizontal, 120px vertical between nodes). " +
|
||||
"DARK MODE COLORS: To enable dark mode color adaptation, the mxGraphModel element must include adaptiveColors=\"auto\". " +
|
||||
"strokeColor, fillColor, and fontColor default to 'default', which renders as black in light theme and white in dark theme. " +
|
||||
"Explicit colors (e.g. fillColor=#DAE8FC) specify the light-mode color; the dark-mode color is computed automatically by inverting RGB values and rotating the hue 180 degrees. " +
|
||||
"To specify both colors explicitly, use light-dark(lightColor,darkColor) in the style string, e.g. fontColor=light-dark(#7EA6E0,#FF0000). " +
|
||||
"See https://www.drawio.com/doc/faq/drawio-style-reference.html for the complete style reference.",
|
||||
"IMPORTANT: The XML must be well-formed. Do NOT include ANY XML comments (<!-- -->) in the output — they are strictly forbidden.\n\n" +
|
||||
xmlReference,
|
||||
inputSchema:
|
||||
{
|
||||
xml: z
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
import { createServer } from "./shared.js";
|
||||
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
|
||||
import { html } from "./generated-html.js";
|
||||
import { html, xmlReference } from "./generated-html.js";
|
||||
|
||||
const CORS_HEADERS =
|
||||
{
|
||||
@@ -114,7 +114,7 @@ export class MCPSessionManager
|
||||
this.log(`[session-create] domain=${this.env.DOMAIN || "UNDEFINED"} session=${sessionId.slice(0, 8)}`);
|
||||
}
|
||||
|
||||
const server = createServer(html, { domain: this.env.DOMAIN });
|
||||
const server = createServer(html, { domain: this.env.DOMAIN, xmlReference });
|
||||
const transport = new WebStandardStreamableHTTPServerTransport(
|
||||
{
|
||||
sessionIdGenerator: function() { return sessionId; },
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
node_modules/
|
||||
src/xml-reference.md
|
||||
@@ -40,17 +40,9 @@ Opens draw.io with Mermaid.js syntax. **Recommended default** — handles flowch
|
||||
| Custom styling, precise positioning | `open_drawio_xml` | High |
|
||||
| Org chart from data | `open_drawio_csv` | Medium |
|
||||
|
||||
## Dark Mode Colors
|
||||
## XML Reference
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`).
|
||||
- **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`.
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory.
|
||||
The `open_drawio_xml` tool description is loaded at startup from `shared/xml-reference.md` (single source of truth for all prompts). A `prepack` script copies the file into `src/` before `npm publish` so the npm package is self-contained.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
|
||||
@@ -116,6 +116,8 @@ Opens the draw.io editor with a Mermaid.js diagram.
|
||||
4. The URL is returned to the LLM, which can present it to the user
|
||||
5. Opening the URL loads draw.io with the diagram ready to view/edit
|
||||
|
||||
The `open_drawio_xml` tool description includes the full XML generation reference (edge routing, containers, layers, tags, metadata, dark mode, etc.) loaded from [`shared/xml-reference.md`](../shared/xml-reference.md) — the single source of truth for all draw.io MCP prompts. A `prepack` script bundles this file into the npm package so it works after `npm install`.
|
||||
|
||||
## Related Resources
|
||||
|
||||
- [draw.io](https://www.draw.io) - Free online diagram editor
|
||||
|
||||
@@ -8,7 +8,8 @@
|
||||
"drawio-mcp": "./src/index.js"
|
||||
},
|
||||
"scripts": {
|
||||
"start": "node src/index.js"
|
||||
"start": "node src/index.js",
|
||||
"prepack": "cp ../shared/xml-reference.md src/xml-reference.md"
|
||||
},
|
||||
"keywords": [
|
||||
"mcp",
|
||||
|
||||
@@ -5,12 +5,24 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
|
||||
import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
||||
import pako from "pako";
|
||||
import { spawn } from "child_process";
|
||||
import { writeFileSync, unlinkSync } from "fs";
|
||||
import { join } from "path";
|
||||
import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
|
||||
import { join, dirname } from "path";
|
||||
import { fileURLToPath } from "url";
|
||||
import { tmpdir } from "os";
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const DRAWIO_BASE_URL = "https://app.diagrams.net/";
|
||||
|
||||
// Read the shared XML reference once at startup (single source of truth).
|
||||
// In the repo: read from shared/. When installed via npm: read from the
|
||||
// local copy created by the prepack script.
|
||||
const sharedPath = join(__dirname, "..", "..", "shared", "xml-reference.md");
|
||||
const localPath = join(__dirname, "xml-reference.md");
|
||||
const xmlReference = readFileSync(
|
||||
existsSync(sharedPath) ? sharedPath : localPath,
|
||||
"utf-8"
|
||||
);
|
||||
|
||||
/**
|
||||
* Opens a URL in the default browser (cross-platform)
|
||||
*/
|
||||
@@ -121,26 +133,8 @@ const tools =
|
||||
description:
|
||||
"Opens the draw.io editor with a diagram from XML content. " +
|
||||
"Use this to view, edit, or create diagrams in draw.io format. " +
|
||||
"The XML should be valid draw.io/mxGraph XML format. " +
|
||||
"IMPORTANT: Do NOT include ANY XML comments (<!-- -->) in the output — they are strictly forbidden. " +
|
||||
"EDGE GEOMETRY: Every edge mxCell MUST contain a <mxGeometry relative=\"1\" as=\"geometry\" /> child element, even when there are no waypoints. Self-closing edge cells (<mxCell ... edge=\"1\" ... />) are invalid and will not render correctly. " +
|
||||
"EDGE ROUTING: Use edgeStyle=orthogonalEdgeStyle for right-angle connectors. " +
|
||||
"Space nodes at least 60px apart to avoid overlapping edges. " +
|
||||
"Use exitX/exitY/entryX/entryY (0-1) to control which side of a node an edge connects to, spreading connections across different sides. " +
|
||||
"Add explicit waypoints via <Array as=\"points\"><mxPoint x=\"...\" y=\"...\"/></Array> inside mxGeometry when edges would overlap. " +
|
||||
"ARROWHEAD CLEARANCE: The final straight segment of an edge (between the last bend and the target, or source and first bend) must be long enough to fit the arrowhead (default size 6, configurable via startSize/endSize). If too short, the arrowhead overlaps the bend. Ensure at least 20px of straight segment. The orthogonal auto-router can place bends too close to shapes when nodes are nearly aligned - fix by increasing spacing or adding explicit waypoints. " +
|
||||
"CONTAINERS: For architecture diagrams and any diagram with nested elements, use proper parent-child containment (set parent=\"containerId\" on children, use relative coordinates). " +
|
||||
"Container types: (1) group style (style=\"group;\") for invisible containers with no connections - includes pointerEvents=0 so child connections are not captured by the container; " +
|
||||
"(2) swimlane style (style=\"swimlane;startSize=30;\") for labeled containers with a title bar - use when the container needs visual borders/headers or when the container itself has connections; " +
|
||||
"(3) any shape can be a container by adding container=1 to its style, but also add pointerEvents=0 unless the container itself needs to be connectable. " +
|
||||
"Always use pointerEvents=0 on container styles that should not capture connections being rewired between children. " +
|
||||
"EDGE LABELS: Do NOT wrap edge labels in HTML markup to reduce font size. The default font size for edge labels is already 11px (vs 12px for vertices), so they are already smaller. Just set the value attribute directly. " +
|
||||
"LAYOUT: Align nodes to a grid (multiples of 10). Use consistent spacing (e.g., 200px horizontal, 120px vertical between nodes). " +
|
||||
"DARK MODE COLORS: To enable dark mode color adaptation, the mxGraphModel element must include adaptiveColors=\"auto\". " +
|
||||
"strokeColor, fillColor, and fontColor default to 'default', which renders as black in light theme and white in dark theme. " +
|
||||
"Explicit colors (e.g. fillColor=#DAE8FC) specify the light-mode color; the dark-mode color is computed automatically by inverting RGB values and rotating the hue 180 degrees. " +
|
||||
"To specify both colors explicitly, use light-dark(lightColor,darkColor) in the style string, e.g. fontColor=light-dark(#7EA6E0,#FF0000). " +
|
||||
"See https://www.drawio.com/doc/faq/drawio-style-reference.html for the complete style reference.",
|
||||
"The XML should be valid draw.io/mxGraph XML format.\n\n" +
|
||||
xmlReference,
|
||||
inputSchema:
|
||||
{
|
||||
type: "object",
|
||||
|
||||
@@ -15,17 +15,9 @@ Alternative approach that works without installing the MCP server. Users add ins
|
||||
3. The script outputs a complete HTML page with the URL embedded as a clickable button
|
||||
4. Claude presents the HTML as an artifact — the user clicks the button to open draw.io
|
||||
|
||||
## Dark Mode Colors
|
||||
## XML Reference
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`).
|
||||
- **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`.
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory.
|
||||
The detailed draw.io XML generation reference (edge routing, containers, layers, tags, metadata, dark mode, style properties, XML well-formedness) lives in `shared/xml-reference.md` at the repo root — the single source of truth for all prompts. Users should copy its contents into their Claude Project alongside `claude-project-instructions.txt`.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
|
||||
@@ -13,7 +13,8 @@ An alternative approach that works **without installing the MCP server**. Instea
|
||||
|
||||
1. Open your Claude Project settings
|
||||
2. Add the contents of [`claude-project-instructions.txt`](claude-project-instructions.txt) to your project instructions
|
||||
3. Ask Claude to create diagrams - it will generate clickable draw.io URLs
|
||||
3. Also add the contents of [`shared/xml-reference.md`](../shared/xml-reference.md) — this is the XML generation reference covering edge routing, containers, layers, tags, metadata, dark mode, and more
|
||||
4. Ask Claude to create diagrams - it will generate clickable draw.io URLs
|
||||
|
||||
## How It Works
|
||||
|
||||
|
||||
@@ -103,82 +103,10 @@ print(f"""<!DOCTYPE html>
|
||||
</html>""")
|
||||
```
|
||||
|
||||
## Edge Routing (XML)
|
||||
## XML Reference
|
||||
|
||||
**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
|
||||
```xml
|
||||
<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
|
||||
<mxGeometry relative="1" as="geometry" />
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
draw.io does **not** have built-in collision detection for edges. Plan layout carefully:
|
||||
|
||||
- Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors
|
||||
- **Space nodes generously** — at least 60px apart, prefer 200px horizontal / 120px vertical gaps
|
||||
- Use `exitX`/`exitY` and `entryX`/`entryY` (values 0–1) to control which side of a node an edge connects to. Spread connections across different sides to prevent overlap
|
||||
- **Leave room for arrowheads**: The final straight segment of an edge (between the last bend and the target shape, or between the source shape and the first bend) must be long enough to fit the arrowhead. The default arrow size is 6px (configurable via `startSize`/`endSize` styles). If the final segment is too short, the arrowhead overlaps the bend and looks broken. Ensure at least 20px of straight segment before the target and after the source when placing waypoints or positioning nodes
|
||||
- When using `orthogonalEdgeStyle`, the auto-router places bends automatically — if source and target are close together or nearly aligned on one axis, the router may place a bend very close to a shape, leaving no room for the arrow. Fix this by either increasing node spacing or adding explicit waypoints that keep the final segment long enough
|
||||
- Add explicit **waypoints** when edges would overlap:
|
||||
```xml
|
||||
<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="a" target="b">
|
||||
<mxGeometry relative="1" as="geometry">
|
||||
<Array as="points">
|
||||
<mxPoint x="300" y="150"/>
|
||||
<mxPoint x="300" y="250"/>
|
||||
</Array>
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
```
|
||||
- Use `rounded=1` on edges for cleaner bends, `jettySize=auto` for better port spacing
|
||||
- Align nodes to a grid (multiples of 10)
|
||||
- **Edge labels**: Do NOT wrap edge labels in HTML markup to reduce font size. The default font size for edge labels is already 11px (vs 12px for vertices), so they are already smaller. Just set the `value` attribute directly.
|
||||
|
||||
## Containers and Groups (XML)
|
||||
|
||||
For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment — do **not** just place shapes on top of larger shapes.
|
||||
|
||||
**How it works:** Set `parent="containerId"` on child cells. Children use **relative coordinates** within the container.
|
||||
|
||||
**Container types:**
|
||||
|
||||
| Type | Style | When to use |
|
||||
|------|-------|-------------|
|
||||
| **Group** (invisible) | `group;` | No visual border needed, container has no connections. Includes `pointerEvents=0` so child connections are not captured |
|
||||
| **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar/header, or the container itself has connections |
|
||||
| **Custom container** | Add `container=1;pointerEvents=0;` to any shape style | Any shape acting as a container without its own connections |
|
||||
|
||||
**Key rules:**
|
||||
- **Always add `pointerEvents=0;`** to container styles that should not capture connections being rewired between children
|
||||
- Only omit `pointerEvents=0` when the container itself needs to be connectable — use `swimlane` which handles this correctly
|
||||
- Children must set `parent="containerId"` and use coordinates **relative to the container**
|
||||
|
||||
**Example:**
|
||||
```xml
|
||||
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="svc1">
|
||||
<mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
## Dark Mode Colors
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`).
|
||||
- **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`.
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory.
|
||||
|
||||
## Style Reference
|
||||
|
||||
Complete style reference: https://www.drawio.com/doc/faq/drawio-style-reference.html
|
||||
XML Schema (XSD): https://www.drawio.com/assets/mxfile.xsd
|
||||
For detailed guidance on edge routing, containers, layers, tags, metadata, dark mode colors, style properties, and XML well-formedness rules, copy the contents of the following file into your Claude Project alongside these instructions:
|
||||
https://github.com/jgraph/drawio-mcp/blob/main/shared/xml-reference.md
|
||||
|
||||
## Format Examples
|
||||
|
||||
|
||||
@@ -0,0 +1,247 @@
|
||||
# draw.io XML Reference
|
||||
|
||||
Detailed reference for styles, edge routing, containers, layers, tags, metadata, and dark mode. Consult this when generating draw.io XML diagrams.
|
||||
|
||||
## Common styles
|
||||
|
||||
**Rounded rectangle:**
|
||||
```xml
|
||||
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
**Diamond (decision):**
|
||||
```xml
|
||||
<mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="200" width="120" height="80" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
**Arrow (edge):**
|
||||
```xml
|
||||
<mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="2" target="3" parent="1">
|
||||
<mxGeometry relative="1" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
**Labeled arrow:**
|
||||
```xml
|
||||
<mxCell id="5" value="Yes" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="3" target="6" parent="1">
|
||||
<mxGeometry relative="1" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
## Style properties
|
||||
|
||||
| Property | Values | Use for |
|
||||
|----------|--------|---------|
|
||||
| `rounded=1` | 0 or 1 | Rounded corners |
|
||||
| `whiteSpace=wrap` | wrap | Text wrapping |
|
||||
| `fillColor=#dae8fc` | Hex color | Background color |
|
||||
| `strokeColor=#6c8ebf` | Hex color | Border color |
|
||||
| `fontColor=#333333` | Hex color | Text color |
|
||||
| `shape=cylinder3` | shape name | Database cylinders |
|
||||
| `shape=mxgraph.flowchart.document` | shape name | Document shapes |
|
||||
| `ellipse` | style keyword | Circles/ovals |
|
||||
| `rhombus` | style keyword | Diamonds |
|
||||
| `edgeStyle=orthogonalEdgeStyle` | style keyword | Right-angle connectors |
|
||||
| `edgeStyle=elbowEdgeStyle` | style keyword | Elbow connectors |
|
||||
| `dashed=1` | 0 or 1 | Dashed lines |
|
||||
| `swimlane` | style keyword | Swimlane containers |
|
||||
| `group` | style keyword | Invisible container (pointerEvents=0) |
|
||||
| `container=1` | 0 or 1 | Enable container behavior on any shape |
|
||||
| `pointerEvents=0` | 0 or 1 | Prevent container from capturing child connections |
|
||||
|
||||
## Edge routing
|
||||
|
||||
**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
|
||||
```xml
|
||||
<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
|
||||
<mxGeometry relative="1" as="geometry" />
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
draw.io does **not** have built-in collision detection for edges. Plan layout and routing carefully:
|
||||
|
||||
- Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors (most common)
|
||||
- **Space nodes generously** — at least 60px apart, prefer 200px horizontal / 120px vertical gaps
|
||||
- Use `exitX`/`exitY` and `entryX`/`entryY` (values 0-1) to control which side of a node an edge connects to. Spread connections across different sides to prevent overlap
|
||||
- **Leave room for arrowheads**: The final straight segment of an edge (between the last bend and the target shape, or between the source shape and the first bend) must be long enough to fit the arrowhead. The default arrow size is 6px (configurable via `startSize`/`endSize` styles). If the final segment is too short, the arrowhead overlaps the bend and looks broken. Ensure at least 20px of straight segment before the target and after the source when placing waypoints or positioning nodes
|
||||
- When using `orthogonalEdgeStyle`, the auto-router places bends automatically — if source and target are close together or nearly aligned on one axis, the router may place a bend very close to a shape, leaving no room for the arrow. Fix this by either increasing node spacing or adding explicit waypoints that keep the final segment long enough
|
||||
- Add explicit **waypoints** when edges would overlap:
|
||||
```xml
|
||||
<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="a" target="b">
|
||||
<mxGeometry relative="1" as="geometry">
|
||||
<Array as="points">
|
||||
<mxPoint x="300" y="150"/>
|
||||
<mxPoint x="300" y="250"/>
|
||||
</Array>
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
```
|
||||
- Use `rounded=1` on edges for cleaner bends
|
||||
- Use `jettySize=auto` for better port spacing on orthogonal edges
|
||||
- Align all nodes to a grid (multiples of 10)
|
||||
- **Edge labels**: Do NOT wrap edge labels in HTML markup to reduce font size. The default font size for edge labels is already 11px (vs 12px for vertices), so they are already smaller. Just set the `value` attribute directly.
|
||||
|
||||
## Containers and groups
|
||||
|
||||
For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment — do **not** just place shapes on top of larger shapes.
|
||||
|
||||
### How containment works
|
||||
|
||||
Set `parent="containerId"` on child cells. Children use **relative coordinates** within the container.
|
||||
|
||||
### Container types
|
||||
|
||||
| Type | Style | When to use |
|
||||
|------|-------|-------------|
|
||||
| **Group** (invisible) | `group;` | No visual border needed, container has no connections. Includes `pointerEvents=0` so child connections are not captured |
|
||||
| **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar/header, or the container itself has connections |
|
||||
| **Custom container** | Add `container=1;pointerEvents=0;` to any shape style | Any shape acting as a container without its own connections |
|
||||
|
||||
### Key rules
|
||||
|
||||
- **Always add `pointerEvents=0;`** to container styles that should not capture connections being rewired between children
|
||||
- Only omit `pointerEvents=0` when the container itself needs to be connectable — in that case, use `swimlane` style which handles this correctly (the client area is transparent for mouse events while the header remains connectable)
|
||||
- Children must set `parent="containerId"` and use coordinates **relative to the container**
|
||||
|
||||
### Example: Architecture container with swimlane
|
||||
|
||||
```xml
|
||||
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="svc1">
|
||||
<mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;" vertex="1" parent="svc1">
|
||||
<mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
### Example: Invisible group container
|
||||
|
||||
```xml
|
||||
<mxCell id="grp1" value="" style="group;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="c1" value="Component A" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="grp1">
|
||||
<mxGeometry x="10" y="10" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
## Layers
|
||||
|
||||
Layers control visibility and z-order. Every cell belongs to exactly one layer. Use layers to manage diagram complexity — viewers can toggle layer visibility to show or hide groups of elements (e.g., "Physical Infrastructure" vs "Logical Network" vs "Security Zones").
|
||||
|
||||
Cell `id="0"` is the root and cell `id="1"` is the default layer — both always exist. Additional layers are `mxCell` elements with `parent="0"`:
|
||||
|
||||
```xml
|
||||
<mxGraphModel>
|
||||
<root>
|
||||
<mxCell id="0"/>
|
||||
<mxCell id="1" parent="0"/>
|
||||
<mxCell id="2" value="Annotations" parent="0"/>
|
||||
<mxCell id="10" value="Server" style="rounded=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="20" value="Note: deprecated" style="text;" vertex="1" parent="2">
|
||||
<mxGeometry x="100" y="170" width="120" height="30" as="geometry"/>
|
||||
</mxCell>
|
||||
</root>
|
||||
</mxGraphModel>
|
||||
```
|
||||
|
||||
- A layer is an `mxCell` with `parent="0"` and no `vertex` or `edge` attribute
|
||||
- Assign shapes to a layer by setting `parent` to the layer's id
|
||||
- Later layers render on top of earlier layers (higher z-order)
|
||||
- Add `visible="0"` as an attribute on the layer cell to hide it by default
|
||||
- Use layers when the diagram has distinct conceptual groupings that viewers may want to toggle independently
|
||||
|
||||
## Tags
|
||||
|
||||
Tags are visual filters that let viewers show or hide elements by category. Unlike layers, a single element can have multiple tags, making tags ideal for cross-cutting concerns (e.g., tagging shapes as "critical", "v2", or "backend").
|
||||
|
||||
Tags require wrapping `mxCell` in an `<object>` element. Tags are assigned via the `tags` attribute as a space-separated string:
|
||||
|
||||
```xml
|
||||
<mxGraphModel>
|
||||
<root>
|
||||
<mxCell id="0"/>
|
||||
<mxCell id="1" parent="0"/>
|
||||
<object id="2" label="Auth Service" tags="critical v2">
|
||||
<mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
</object>
|
||||
<object id="3" label="Legacy API" tags="critical deprecated">
|
||||
<mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="300" y="100" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
</object>
|
||||
</root>
|
||||
</mxGraphModel>
|
||||
```
|
||||
|
||||
- Tags require the `<object>` wrapper — a plain `mxCell` cannot have tags
|
||||
- The `label` attribute on `<object>` replaces `value` on `mxCell`
|
||||
- Tags are space-separated in the `tags` attribute
|
||||
- Viewers filter the diagram by selecting tags in the draw.io UI (Edit > Tags)
|
||||
- Tags do not affect z-order or structural grouping — they are purely a visibility filter
|
||||
|
||||
## Metadata and placeholders
|
||||
|
||||
Metadata stores custom key-value properties on shapes as additional attributes on the `<object>` wrapper element. Combined with placeholders, metadata values can be displayed in labels — useful for data-driven diagrams showing status, owner, IP addresses, or versions on each shape.
|
||||
|
||||
Set `placeholders="1"` on the `<object>` to enable `%propertyName%` substitution in the `label`:
|
||||
|
||||
```xml
|
||||
<mxGraphModel>
|
||||
<root>
|
||||
<mxCell id="0"/>
|
||||
<mxCell id="1" parent="0"/>
|
||||
<object id="2" label="<b>%component%</b><br>Owner: %owner%<br>Status: %status%"
|
||||
placeholders="1" component="Auth Service" owner="Team Backend" status="Active">
|
||||
<mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="160" height="80" as="geometry"/>
|
||||
</mxCell>
|
||||
</object>
|
||||
</root>
|
||||
</mxGraphModel>
|
||||
```
|
||||
|
||||
- Custom properties are plain XML attributes on `<object>` (e.g., `component="Auth Service"`)
|
||||
- Set `placeholders="1"` to enable `%key%` substitution in the label and tooltip
|
||||
- The label must use `html=1` style when using HTML formatting with placeholders
|
||||
- Placeholders resolve by walking up the containment hierarchy: shape attributes first, then parent container, then layer, then root — first match wins
|
||||
- Predefined placeholders work without custom properties: `%id%`, `%width%`, `%height%`, `%date%`, `%time%`, `%timestamp%`, `%page%`, `%pagenumber%`, `%pagecount%`, `%filename%`
|
||||
- Use `%%` for a literal percent sign in labels
|
||||
- Tags, metadata, and placeholders can all be combined on the same `<object>` element
|
||||
- Use metadata when shapes represent data records (servers, services, components) and you want to attach structured information beyond the visible label
|
||||
|
||||
## Dark mode colors
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`).
|
||||
- **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`.
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory.
|
||||
|
||||
## Style reference
|
||||
|
||||
Complete style reference: https://www.drawio.com/doc/faq/drawio-style-reference.html
|
||||
|
||||
XML Schema (XSD): https://www.drawio.com/assets/mxfile.xsd
|
||||
|
||||
## CRITICAL: XML well-formedness
|
||||
|
||||
When generating draw.io XML, the output **must** be well-formed XML:
|
||||
- **NEVER include ANY XML comments (`<!-- -->`) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
|
||||
- Escape special characters in attribute values: `&`, `<`, `>`, `"`
|
||||
- Always use unique `id` values for each `mxCell`
|
||||
+2
-10
@@ -32,17 +32,9 @@ The skill tries `drawio` first, then falls back to the platform-specific path. O
|
||||
|
||||
A `.drawio` file is native mxGraphModel XML. Mermaid and CSV formats require draw.io's server-side conversion and cannot be saved as native files. The skill generates XML directly for all diagram types.
|
||||
|
||||
## Dark Mode Colors
|
||||
## XML Reference
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`).
|
||||
- **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`.
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory.
|
||||
The XML generation reference lives in `shared/xml-reference.md` at the repo root (single source of truth for all prompts). The SKILL.md references it via the GitHub raw URL so it works after install without copying extra files.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
|
||||
@@ -66,6 +66,13 @@ More examples:
|
||||
|
||||
The `.drawio.*` double extension signals that the file contains embedded diagram XML. Open any of these in draw.io to recover and edit the full diagram. The intermediate `.drawio` source file is deleted after export since the exported file contains the complete diagram.
|
||||
|
||||
## XML Reference
|
||||
|
||||
The skill references the shared XML generation guide (edge routing, containers, layers, tags, metadata, dark mode, etc.) from GitHub at runtime:
|
||||
[`shared/xml-reference.md`](../shared/xml-reference.md)
|
||||
|
||||
This is the single source of truth for all draw.io MCP prompts across the repository. No extra files need to be copied during installation.
|
||||
|
||||
## Why XML Only?
|
||||
|
||||
A `.drawio` file is just mxGraphModel XML. Mermaid and CSV formats require draw.io's server-side conversion — they can't be saved as native files. Claude generates XML directly for all diagram types, which means:
|
||||
|
||||
@@ -162,47 +162,10 @@ Every diagram must have this structure:
|
||||
- Cell `id="1"` is the default parent layer
|
||||
- All diagram elements use `parent="1"` unless using multiple layers
|
||||
|
||||
Consult `references/xml-reference.md` for common styles, style properties, edge routing details (including waypoints), and container/group examples.
|
||||
## XML reference
|
||||
|
||||
## Edge routing
|
||||
|
||||
**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
|
||||
```xml
|
||||
<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
|
||||
<mxGeometry relative="1" as="geometry" />
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
- Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors (most common)
|
||||
- **Space nodes generously** — prefer 200px horizontal / 120px vertical gaps
|
||||
- **Leave room for arrowheads** — at least 20px of straight segment before the target
|
||||
- Add explicit **waypoints** when edges would overlap
|
||||
- Align all nodes to a grid (multiples of 10)
|
||||
- **Edge labels**: Do NOT wrap edge labels in HTML markup to reduce font size. The default font size for edge labels is already 11px (vs 12px for vertices), so they are already smaller. Just set the `value` attribute directly.
|
||||
|
||||
See `references/xml-reference.md` for full edge routing and container guidance.
|
||||
|
||||
## Containers and groups
|
||||
|
||||
Use parent-child containment (`parent="containerId"`) for nested elements — do **not** just stack shapes. Children use **relative coordinates** within the container. See `references/xml-reference.md` for container types, rules, and examples.
|
||||
|
||||
## Dark mode colors
|
||||
|
||||
draw.io supports automatic dark mode rendering. How colors behave depends on the property:
|
||||
|
||||
- **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically.
|
||||
- **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`).
|
||||
- **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode.
|
||||
|
||||
To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`.
|
||||
|
||||
When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory.
|
||||
|
||||
## Style reference
|
||||
|
||||
For the complete draw.io style reference: https://www.drawio.com/doc/faq/drawio-style-reference.html
|
||||
|
||||
For the XML Schema Definition (XSD): https://www.drawio.com/assets/mxfile.xsd
|
||||
For the complete draw.io XML reference including common styles, edge routing, containers, layers, tags, metadata, dark mode colors, and XML well-formedness rules, fetch and follow the instructions at:
|
||||
https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -1,132 +0,0 @@
|
||||
# draw.io XML Reference
|
||||
|
||||
Detailed reference for styles, edge routing, and containers. Consult this when generating complex diagrams.
|
||||
|
||||
## Common styles
|
||||
|
||||
**Rounded rectangle:**
|
||||
```xml
|
||||
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
**Diamond (decision):**
|
||||
```xml
|
||||
<mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="200" width="120" height="80" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
**Arrow (edge):**
|
||||
```xml
|
||||
<mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="2" target="3" parent="1">
|
||||
<mxGeometry relative="1" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
**Labeled arrow:**
|
||||
```xml
|
||||
<mxCell id="5" value="Yes" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="3" target="6" parent="1">
|
||||
<mxGeometry relative="1" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
## Style properties
|
||||
|
||||
| Property | Values | Use for |
|
||||
|----------|--------|---------|
|
||||
| `rounded=1` | 0 or 1 | Rounded corners |
|
||||
| `whiteSpace=wrap` | wrap | Text wrapping |
|
||||
| `fillColor=#dae8fc` | Hex color | Background color |
|
||||
| `strokeColor=#6c8ebf` | Hex color | Border color |
|
||||
| `fontColor=#333333` | Hex color | Text color |
|
||||
| `shape=cylinder3` | shape name | Database cylinders |
|
||||
| `shape=mxgraph.flowchart.document` | shape name | Document shapes |
|
||||
| `ellipse` | style keyword | Circles/ovals |
|
||||
| `rhombus` | style keyword | Diamonds |
|
||||
| `edgeStyle=orthogonalEdgeStyle` | style keyword | Right-angle connectors |
|
||||
| `edgeStyle=elbowEdgeStyle` | style keyword | Elbow connectors |
|
||||
| `dashed=1` | 0 or 1 | Dashed lines |
|
||||
| `swimlane` | style keyword | Swimlane containers |
|
||||
| `group` | style keyword | Invisible container (pointerEvents=0) |
|
||||
| `container=1` | 0 or 1 | Enable container behavior on any shape |
|
||||
| `pointerEvents=0` | 0 or 1 | Prevent container from capturing child connections |
|
||||
|
||||
## Edge routing
|
||||
|
||||
**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
|
||||
```xml
|
||||
<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
|
||||
<mxGeometry relative="1" as="geometry" />
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
draw.io does **not** have built-in collision detection for edges. Plan layout and routing carefully:
|
||||
|
||||
- Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors (most common)
|
||||
- **Space nodes generously** — at least 60px apart, prefer 200px horizontal / 120px vertical gaps
|
||||
- Use `exitX`/`exitY` and `entryX`/`entryY` (values 0-1) to control which side of a node an edge connects to. Spread connections across different sides to prevent overlap
|
||||
- **Leave room for arrowheads**: The final straight segment of an edge (between the last bend and the target shape, or between the source shape and the first bend) must be long enough to fit the arrowhead. The default arrow size is 6px (configurable via `startSize`/`endSize` styles). If the final segment is too short, the arrowhead overlaps the bend and looks broken. Ensure at least 20px of straight segment before the target and after the source when placing waypoints or positioning nodes
|
||||
- When using `orthogonalEdgeStyle`, the auto-router places bends automatically — if source and target are close together or nearly aligned on one axis, the router may place a bend very close to a shape, leaving no room for the arrow. Fix this by either increasing node spacing or adding explicit waypoints that keep the final segment long enough
|
||||
- Add explicit **waypoints** when edges would overlap:
|
||||
```xml
|
||||
<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="a" target="b">
|
||||
<mxGeometry relative="1" as="geometry">
|
||||
<Array as="points">
|
||||
<mxPoint x="300" y="150"/>
|
||||
<mxPoint x="300" y="250"/>
|
||||
</Array>
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
```
|
||||
- Use `rounded=1` on edges for cleaner bends
|
||||
- Use `jettySize=auto` for better port spacing on orthogonal edges
|
||||
- Align all nodes to a grid (multiples of 10)
|
||||
|
||||
## Containers and groups
|
||||
|
||||
For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment — do **not** just place shapes on top of larger shapes.
|
||||
|
||||
### How containment works
|
||||
|
||||
Set `parent="containerId"` on child cells. Children use **relative coordinates** within the container.
|
||||
|
||||
### Container types
|
||||
|
||||
| Type | Style | When to use |
|
||||
|------|-------|-------------|
|
||||
| **Group** (invisible) | `group;` | No visual border needed, container has no connections. Includes `pointerEvents=0` so child connections are not captured |
|
||||
| **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar/header, or the container itself has connections |
|
||||
| **Custom container** | Add `container=1;pointerEvents=0;` to any shape style | Any shape acting as a container without its own connections |
|
||||
|
||||
### Key rules
|
||||
|
||||
- **Always add `pointerEvents=0;`** to container styles that should not capture connections being rewired between children
|
||||
- Only omit `pointerEvents=0` when the container itself needs to be connectable — in that case, use `swimlane` style which handles this correctly (the client area is transparent for mouse events while the header remains connectable)
|
||||
- Children must set `parent="containerId"` and use coordinates **relative to the container**
|
||||
|
||||
### Example: Architecture container with swimlane
|
||||
|
||||
```xml
|
||||
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="svc1">
|
||||
<mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;" vertex="1" parent="svc1">
|
||||
<mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
|
||||
### Example: Invisible group container
|
||||
|
||||
```xml
|
||||
<mxCell id="grp1" value="" style="group;" vertex="1" parent="1">
|
||||
<mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
|
||||
</mxCell>
|
||||
<mxCell id="c1" value="Component A" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="grp1">
|
||||
<mxGeometry x="10" y="10" width="120" height="60" as="geometry"/>
|
||||
</mxCell>
|
||||
```
|
||||
Reference in New Issue
Block a user