@drawio/mcp 1.0.0

package/README.md

@@ -0,0 +1,285 @@
+# Draw.io MCP Server
+
+The official [draw.io](https://www.draw.io) MCP (Model Context Protocol) server that enables LLMs to create and open diagrams in the draw.io editor.
+
+## Features
+
+- **Open XML diagrams**: Load native draw.io/mxGraph XML format
+- **Import CSV data**: Convert tabular data to diagrams (org charts, flowcharts, etc.)
+- **Render Mermaid.js**: Transform Mermaid syntax into editable draw.io diagrams
+- **URL support**: Fetch content from URLs automatically
+- **Customizable display**: Lightbox mode, dark mode, and more
+
+## Installation
+
+### Using npx (recommended)
+
+```bash
+npx @drawio/mcp
+```
+
+### Global installation
+
+```bash
+npm install -g @drawio/mcp
+drawio-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/jgraph/drawio-mcp.git
+cd drawio-mcp
+npm install
+npm start
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "drawio": {
+      "command": "npx",
+      "args": ["@drawio/mcp"]
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Configure your MCP client to run the server via stdio:
+
+```bash
+npx @drawio/mcp
+```
+
+## Tools
+
+### `open_drawio_xml`
+
+Opens the draw.io editor with XML content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | Yes | Draw.io XML or URL to XML |
+| `lightbox` | boolean | No | Read-only view mode (default: false) |
+| `dark` | string | No | "auto", "true", or "false" (default: "auto") |
+
+### `open_drawio_csv`
+
+Opens the draw.io editor with CSV data converted to a diagram.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | Yes | CSV content or URL to CSV |
+| `lightbox` | boolean | No | Read-only view mode (default: false) |
+| `dark` | string | No | "auto", "true", or "false" (default: "auto") |
+
+### `open_drawio_mermaid`
+
+Opens the draw.io editor with a Mermaid.js diagram.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | Yes | Mermaid syntax or URL |
+| `lightbox` | boolean | No | Read-only view mode (default: false) |
+| `dark` | string | No | "auto", "true", or "false" (default: "auto") |
+
+## Example Prompts
+
+Here are example prompts you can use with Claude to create diagrams.
+
+**Important:** Claude Desktop may have multiple ways to create diagrams (artifacts, browser control, MCP tools). To ensure Claude uses the draw.io MCP, explicitly mention the tool name in your prompt.
+
+You can also add a system instruction to your Claude Desktop project:
+> "Always use the draw.io MCP tools (open_drawio_mermaid, open_drawio_csv, open_drawio_xml) to create diagrams. Do not use browser control or artifacts."
+
+### Explicit MCP Tool Calls
+
+These prompts explicitly request the draw.io MCP tools:
+
+**Mermaid:**
+- "Use `open_drawio_mermaid` to create a flowchart for a user login process"
+- "Use the draw.io MCP tool `open_drawio_mermaid` to make a sequence diagram showing OAuth2 flow"
+- "Create a state diagram with `open_drawio_mermaid` for an order lifecycle"
+
+**CSV:**
+- "Use `open_drawio_csv` to create an org chart for our team: CEO -> CTO, CFO; CTO -> 3 Engineers"
+- "Use the draw.io MCP tool `open_drawio_csv` to generate a network topology diagram"
+- "Create a microservices architecture with `open_drawio_csv`"
+
+**XML:**
+- "Use `open_drawio_xml` to create a detailed AWS architecture diagram with VPC, subnets, and security groups"
+- "Use the draw.io MCP tool `open_drawio_xml` to create a floor plan with 3 offices and a conference room"
+- "Create a network rack diagram with `open_drawio_xml` showing servers, switches, and cabling"
+
+### Mermaid Diagrams
+
+**Flowcharts:**
+- "Create a flowchart showing a user login process with password validation and 2FA"
+- "Make a diagram of a CI/CD pipeline with build, test, and deploy stages"
+- "Draw a decision tree for troubleshooting network connectivity issues"
+
+**Sequence Diagrams:**
+- "Create a sequence diagram showing OAuth2 authentication flow"
+- "Make a sequence diagram of a REST API request/response cycle"
+- "Draw the interaction between a web browser, server, and database for a search query"
+
+**Class Diagrams:**
+- "Create a class diagram for a simple e-commerce system with Product, Order, and Customer classes"
+- "Make a UML class diagram showing inheritance for a vehicle hierarchy"
+
+**Other Mermaid Types:**
+- "Create an entity relationship diagram for a blog with users, posts, and comments"
+- "Make a state diagram for an order lifecycle (pending, confirmed, shipped, delivered)"
+- "Draw a Gantt chart for a 3-month software development project"
+
+### CSV Diagrams
+
+**Org Charts (generated from description):**
+- "Create an org chart for a tech startup with a CEO, CTO with 3 engineers, and CFO with 2 accountants"
+- "Make an organizational diagram for a hospital with departments: Emergency, Surgery, Pediatrics, each with a head doctor and 2 staff"
+- "Generate an org chart showing: John (CEO) manages Sarah (VP Sales) and Mike (VP Engineering). Sarah manages 2 sales reps, Mike manages 3 developers"
+
+**Network/Architecture Diagrams (generated from description):**
+- "Create a network diagram showing: Load Balancer connects to 3 Web Servers, each Web Server connects to a shared Database and Cache"
+- "Make an AWS architecture diagram with: Users -> CloudFront -> ALB -> 2 EC2 instances -> RDS"
+- "Generate a microservices diagram with API Gateway connecting to Auth, Users, Orders, and Payments services"
+
+**Process/Workflow Diagrams (generated from description):**
+- "Create a diagram showing our hiring process: Application -> HR Review -> Technical Interview -> Culture Fit -> Offer -> Onboarding"
+- "Make a diagram of a pizza order flow from customer order through kitchen stations to delivery"
+
+**From Existing Data:**
+- "Create a diagram from this CSV data showing project dependencies"
+- "Turn this spreadsheet of employees and managers into an org chart"
+
+### XML Diagrams
+
+**Complex Custom Diagrams:**
+- "Create a detailed AWS architecture diagram with VPC, subnets, EC2, and RDS"
+- "Make a custom floor plan layout with specific room dimensions"
+- "Draw a circuit diagram with specific component placements"
+
+**Importing Existing Diagrams:**
+- "Open this draw.io XML file and let me edit it"
+- "Load my existing diagram from this URL: https://example.com/diagram.xml"
+
+## Format Examples
+
+### Flowchart with Mermaid
+
+```text
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action 1]
+    B -->|No| D[Action 2]
+    C --> E[End]
+    D --> E
+```
+
+### Sequence Diagram with Mermaid
+
+```text
+sequenceDiagram
+    participant User
+    participant Server
+    participant Database
+
+    User->>Server: Login Request
+    Server->>Database: Validate Credentials
+    Database-->>Server: User Data
+    Server-->>User: JWT Token
+```
+
+### Org Chart with CSV
+
+```csv
+## Org Chart
+# label: %name%<br><i style="color:gray;">%title%</i>
+# style: rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;
+# connect: {"from":"manager","to":"name","invert":true,"style":"curved=1;endArrow=blockThin;endFill=1;"}
+# layout: auto
+# nodespacing: 40
+# levelspacing: 60
+name,title,manager
+Alice Johnson,CEO,
+Bob Smith,CTO,Alice Johnson
+Carol Williams,CFO,Alice Johnson
+Dave Brown,Lead Engineer,Bob Smith
+Eve Davis,Senior Engineer,Bob Smith
+Frank Miller,Accountant,Carol Williams
+```
+
+### Entity List with CSV
+
+```csv
+## Entity Diagram
+# label: %name%
+# style: shape=rectangle;rounded=1;whiteSpace=wrap;html=1;
+# connect: {"from":"connects_to","to":"name","style":"endArrow=classic;"}
+# layout: horizontalflow
+name,type,connects_to
+API Gateway,service,Auth Service
+Auth Service,service,User Database
+User Database,database,
+API Gateway,service,Product Service
+Product Service,service,Product Database
+Product Database,database,
+```
+
+### Native XML
+
+```xml
+<mxGraphModel>
+  <root>
+    <mxCell id="0"/>
+    <mxCell id="1" parent="0"/>
+    <mxCell id="2" value="Hello World" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
+            vertex="1" parent="1">
+      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
+    </mxCell>
+    <mxCell id="3" value="Another Box" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
+            vertex="1" parent="1">
+      <mxGeometry x="280" y="100" width="120" height="60" as="geometry"/>
+    </mxCell>
+    <mxCell id="4" style="endArrow=classic;html=1;" edge="1" parent="1" source="2" target="3">
+      <mxGeometry relative="1" as="geometry"/>
+    </mxCell>
+  </root>
+</mxGraphModel>
+```
+
+## How It Works
+
+1. The MCP server receives diagram content (XML, CSV, or Mermaid)
+2. Content is compressed using pako deflateRaw and encoded as base64
+3. A draw.io URL is generated with the `#create` hash parameter
+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
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run the server
+npm start
+```
+
+## Related Resources
+
+- [draw.io](https://www.draw.io) - Free online diagram editor
+- [draw.io Desktop](https://github.com/jgraph/drawio-desktop) - Desktop application
+- [Mermaid.js Documentation](https://mermaid.js.org/intro/)
+- [MCP Specification](https://modelcontextprotocol.io/)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@drawio/mcp",
+  "version": "1.0.0",
+  "description": "Official draw.io MCP server for LLMs - Open diagrams in draw.io editor",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "drawio-mcp": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "drawio",
+    "draw.io",
+    "diagrams",
+    "mermaid",
+    "csv",
+    "xml",
+    "llm",
+    "claude",
+    "anthropic"
+  ],
+  "author": "JGraph Ltd",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jgraph/drawio-mcp.git"
+  },
+  "homepage": "https://github.com/jgraph/drawio-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/jgraph/drawio-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.11.2",
+    "pako": "^2.1.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/index.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import pako from "pako";
+import { exec } from "child_process";
+
+const DRAWIO_BASE_URL = "https://app.diagrams.net/";
+
+/**
+ * Opens a URL in the default browser (cross-platform)
+ */
+function openBrowser(url)
+{
+  const platform = process.platform;
+  let command;
+
+  if (platform === "win32")
+  {
+    command = `start "" "${url}"`;
+  }
+  else if (platform === "darwin")
+  {
+    command = `open "${url}"`;
+  }
+  else
+  {
+    command = `xdg-open "${url}"`;
+  }
+
+  exec(command, (error) =>
+  {
+    if (error)
+    {
+      console.error(`Failed to open browser: ${error.message}`);
+    }
+  });
+}
+
+/**
+ * Compresses data using pako deflateRaw and encodes as base64
+ * This matches the compression used by draw.io tools
+ */
+function compressData(data)
+{
+  if (!data || data.length === 0)
+  {
+    return data;
+  }
+  const encoded = encodeURIComponent(data);
+  const compressed = pako.deflateRaw(encoded);
+  return Buffer.from(compressed).toString("base64");
+}
+
+/**
+ * Generates a draw.io URL with the #create hash parameter
+ */
+function generateDrawioUrl(data, type, options = {})
+{
+  const {
+    lightbox = false,
+    border = 10,
+    dark = false,
+    edit = "_blank",
+  } = options;
+
+  const compressedData = compressData(data);
+
+  const createObj = {
+    type: type,
+    compressed: true,
+    data: compressedData,
+  };
+
+  const params = new URLSearchParams();
+
+  if (lightbox)
+  {
+    params.set("lightbox", "1");
+    params.set("edit", "_blank");
+    params.set("border", "10");
+  }
+  else
+  {
+    params.set("grid", "0");
+    params.set("pv", "0");
+  }
+
+  if (dark === true)
+  {
+    params.set("dark", "1");
+  }
+
+  params.set("border", border.toString());
+  params.set("edit", edit);
+
+  const createHash = "#create=" + encodeURIComponent(JSON.stringify(createObj));
+
+  // Workaround for unsupported xml type
+  if (createObj.type === "xml")
+  {
+    createHash = "#R" + compressedData;
+  }
+
+  const paramsStr = params.toString();
+
+  return DRAWIO_BASE_URL + (paramsStr ? "?" + paramsStr : "") + createHash;
+}
+
+/**
+ * Fetches content from a URL
+ */
+async function fetchContent(url)
+{
+  const response = await fetch(url);
+  if (!response.ok)
+  {
+    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  }
+  return response.text();
+}
+
+/**
+ * Determines if the input is a URL
+ */
+function isUrl(input)
+{
+  try
+  {
+    new URL(input);
+    return true;
+  }
+  catch
+  {
+    return false;
+  }
+}
+
+// Define the tools
+const tools =
+[
+  {
+    name: "open_drawio_xml",
+    description:
+      "Opens the draw.io editor with a diagram from XML content or a URL to XML content. " +
+      "Use this to view, edit, or create diagrams in draw.io format. " +
+      "The XML should be valid draw.io/mxGraph XML format.",
+    inputSchema:
+    {
+      type: "object",
+      properties:
+      {
+        content:
+        {
+          type: "string",
+          description:
+            "The draw.io XML content or a URL pointing to XML content. " +
+            "If a URL is provided, the content will be fetched automatically.",
+        },
+        lightbox:
+        {
+          type: "boolean",
+          description: "Open in lightbox mode (read-only view). Default: false",
+        },
+        dark:
+        {
+          type: "string",
+          enum: ["auto", "true", "false"],
+          description: "Dark mode setting. Default: auto",
+        },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "open_drawio_csv",
+    description:
+      "Opens the draw.io editor with a diagram generated from CSV data or a URL to CSV data. " +
+      "The CSV format should follow draw.io's CSV import specification which allows " +
+      "creating org charts, flowcharts, and other diagrams from tabular data.",
+    inputSchema:
+    {
+      type: "object",
+      properties:
+      {
+        content:
+        {
+          type: "string",
+          description:
+            "The CSV content or a URL pointing to CSV content. " +
+            "If a URL is provided, the content will be fetched automatically. " +
+            "The CSV should follow draw.io's CSV import format.",
+        },
+        lightbox:
+        {
+          type: "boolean",
+          description: "Open in lightbox mode (read-only view). Default: false",
+        },
+        dark:
+        {
+          type: "string",
+          enum: ["auto", "true", "false"],
+          description: "Dark mode setting. Default: auto",
+        },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "open_drawio_mermaid",
+    description:
+      "Opens the draw.io editor with a diagram generated from Mermaid.js syntax or a URL to Mermaid content. " +
+      "Supports flowcharts, sequence diagrams, class diagrams, state diagrams, " +
+      "entity relationship diagrams, and more using Mermaid.js syntax.",
+    inputSchema:
+    {
+      type: "object",
+      properties:
+      {
+        content:
+        {
+          type: "string",
+          description:
+            "The Mermaid.js diagram definition or a URL pointing to Mermaid content. " +
+            "If a URL is provided, the content will be fetched automatically. " +
+            "Example: 'graph TD; A-->B; B-->C;'",
+        },
+        lightbox:
+        {
+          type: "boolean",
+          description: "Open in lightbox mode (read-only view). Default: false",
+        },
+        dark:
+        {
+          type: "string",
+          enum: ["auto", "true", "false"],
+          description: "Dark mode setting. Default: auto",
+        },
+      },
+      required: ["content"],
+    },
+  },
+];
+
+// Create the MCP server
+const server = new Server(
+  {
+    name: "drawio-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities:
+    {
+      tools: {},
+    },
+  }
+);
+
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () =>
+{
+  return { tools };
+});
+
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) =>
+{
+  const { name, arguments: args } = request.params;
+
+  try
+  {
+    let content;
+    let type;
+    const lightbox = args?.lightbox === true;
+    const darkArg = args?.dark;
+    const dark = darkArg === "true" ? true : darkArg === "false" ? false : "auto";
+
+    const inputContent = args?.content;
+
+    if (!inputContent)
+    {
+      return {
+        content:
+        [
+          {
+            type: "text",
+            text: "Error: content parameter is required",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Fetch content if it's a URL
+    if (isUrl(inputContent))
+    {
+      content = await fetchContent(inputContent);
+    }
+    else
+    {
+      content = inputContent;
+    }
+
+    switch (name)
+    {
+      case "open_drawio_xml":
+        type = "xml";
+        break;
+      case "open_drawio_csv":
+        type = "csv";
+        break;
+      case "open_drawio_mermaid":
+        type = "mermaid";
+        break;
+      default:
+        return {
+          content:
+          [
+            {
+              type: "text",
+              text: `Error: Unknown tool "${name}"`,
+            },
+          ],
+          isError: true,
+        };
+    }
+
+    const url = generateDrawioUrl(content, type, { lightbox, dark });
+
+    // Open the URL in the default browser
+    openBrowser(url);
+
+    return {
+      content:
+      [
+        {
+          type: "text",
+          text: `Draw.io Editor URL:\n${url}\n\nThe diagram has been opened in your default browser.`,
+        },
+      ],
+    };
+  }
+  catch (error)
+  {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      content:
+      [
+        {
+          type: "text",
+          text: `Error: ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main()
+{
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Draw.io MCP server running on stdio");
+}
+
+main().catch((error) =>
+{
+  console.error("Fatal error:", error);
+  process.exit(1);
+});