# @achmadya-dev/mcp-drawio

MCP server for [draw.io](https://www.draw.io). Create diagrams via LLM — rendered **inline in chat** using [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps).

Built on [`@achmadya-dev/mcp-core`](https://www.npmjs.com/package/@achmadya-dev/mcp-core) and [`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps).

## Requirements

- Node.js **≥ 20**
- MCP host with MCP Apps support (e.g. **Cursor**)

## Install via npx

```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@achmadya-dev/mcp-drawio"]
    }
  }
}
```

## Tools

| Tool | Description |
| ---- | ----------- |
| `show_inline_drawio` | Render a diagram inline in chat from **Mermaid** or draw.io **XML** |
| `search_shapes` | Search 10k+ industry icon shapes (AWS, Cisco, P&ID, …) for XML diagrams |

`search_shapes` is registered when the bundled shape index is present (included in the npm package after build).

### `show_inline_drawio`

Provide **exactly one** of `mermaid` or `xml`:

| Input | Use for |
| ----- | ------- |
| `mermaid` | Flowchart, sequence, ER, class, state, gantt, mindmap, C4, and [25+ other types](src/assets/shared/mermaid-reference.md) |
| `xml` | Hand-placed layouts, swimlanes, cloud/network/P&ID stencils, UI mockups |

Optional layout passes (**XML only**):

| Option | Effect |
| ------ | ------ |
| `postLayout: "elk"` | Re-layout vertices with ELK (flowcharts, pipelines, hierarchical diagrams) |
| `direction: "vertical" \| "horizontal"` | ELK flow direction (XML only; defaults to vertical) |
| `routing: "libavoid"` | Obstacle-avoiding edge routing without moving vertices |

For industry icons in XML diagrams, call `search_shapes` first and use the returned `style` strings in `mxCell` attributes. References: [`xml-reference.md`](src/assets/shared/xml-reference.md), [`mermaid-reference.md`](src/assets/shared/mermaid-reference.md).

## Inline viewer

The `create_diagram` tool renders an interactive iframe in chat:

- Zoom, pan, and fit-to-view
- Fullscreen mode
- **Open in draw.io** — opens the diagram in [app.diagrams.net](https://app.diagrams.net) for editing and export (PNG, SVG, PDF)

To save a diagram as an image, use **Open in draw.io → File → Export as**.

## Develop from source

```bash
git clone https://github.com/achmadya-dev/mcp-drawio.git
cd drawio-mcp
pnpm install
pnpm run build
pnpm start
```

Local Cursor config (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "drawio": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

After changing viewer or server code, rebuild and **restart the MCP server** in Cursor.

### Scripts

| Command | Description |
| ------- | ----------- |
| `pnpm run build` | Compile TypeScript and copy `src/assets/` → `dist/assets/` |
| `pnpm start` | Run MCP server (stdio) |
| `pnpm test` | Run tests |
| `pnpm run generate:shapes` | Regenerate shape search index (requires network) |
| `pnpm run format` | Format with Prettier |

## Environment

| Variable | Description |
| -------- | ----------- |
| `DOMAIN` | MCP Apps iframe domain (passed in resource `_meta.ui`) |
| `VIEWER_PATH` | Optional path to a local `viewer-static.min.js` override |
| `ELK_PATH` | Optional path to a local `drawio-elk.min.js` override |
| `MERMAID_PATH` | Optional path to a local `drawio-mermaid.min.js` override |

The draw.io viewer loads from `https://viewer.diagrams.net` by default (CDN). Optional bundle overrides are useful for offline development or pinning a specific draw.io release.

## Project layout

```
src/
  index.ts              MCP server entry (stdio, MCP Apps)
  drawio/
    drawio.ts           Bundle loader (HTML, shape index, references)
    utils.ts            createDiagram, searchShapes, validation
    viewer/html.ts      Inline MCP App viewer (draw.io + MCP SDK)
  tools/
    search_shapes.ts    Shape search tool (defineTool)
  assets/
    shared/             Tool description references (XML, Mermaid)
    shape-search/       Pre-built shape index (~10k shapes)
    vendor/app/         libavoid WASM (edge routing in viewer)
  scripts/
    copy-assets.ts      Build-time asset copy
    generate-shape-index.ts
dist/                   Published to npm
```

## Diagram formats (quick guide)

| Need | Approach |
| ---- | -------- |
| Flowchart, sequence, ER, class, … | Mermaid via `show_inline_drawio` |
| AWS / Azure / Cisco / P&ID icons | XML + `search_shapes` |
| Edit or export PNG/SVG | **Open in draw.io** in the inline viewer |

## libavoid vendor refresh

Browser WASM lives in `src/assets/vendor/app/libavoid/`. To refresh:

```bash
cd src/assets/vendor/app/libavoid
npm pack libavoid-js && tar -xzf libavoid-js-*.tgz
cp package/dist/index.js libavoid.min.js
cp package/dist/libavoid.wasm libavoid.wasm
```

Regenerate shape index (optional, when draw.io releases new shapes):

```bash
pnpm run generate:shapes
pnpm run build
```

## Release

Uses [Changesets](https://github.com/changesets/changesets):

```bash
pnpm changeset
pnpm run version-packages
```

Push to `main` → GitHub opens a **Version packages** PR → merge → npm publish via CI.

Requires `NPM_TOKEN` secret on the repository.

## License

Apache-2.0