# drawio-mcp-bridge

把本机 **draw.io** 接成 **MCP 工具 + 命令行**：用 JSON 规格生成图，离线导出 PNG / SVG / PDF，也能通过 CDP 直接控制正在运行的编辑器——实时改图、读回 XML、截图。

零依赖，Node ≥ 22（使用内置 `fetch` / `WebSocket`）。实测环境：Windows 11 + draw.io 32.5.5 + Node v24.13.1。

> 上游项目：[jgraph/drawio](https://github.com/jgraph/drawio)（draw.io 是 JGraph 的桌面客户端与在线编辑器）。
> 本仓库是**第三方桥接与自动化工具**，不包含 draw.io 源码或资源，与 JGraph 没有隶属关系。

## 功能

| 能力 | 说明 |
|---|---|
| 规格生成图 | JSON（节点 / 边 / 分组）→ `.drawio`，支持 flow 分层与 grid 布局 |
| 离线导出 | 调用 draw.io 自带 CLI 导出 PNG / SVG / PDF，支持倍率、多页、裁边 |
| 实时控制 | 以调试端口启动 draw.io，CDP 注入钩子拿到 `EditorUi`，直接调用编辑器 API |
| 读回与截图 | `pull` 取当前图 XML，`shot` 截窗口，`open` 把文件灌进编辑器 |
| MCP 服务 | stdio MCP server，9 个工具，NDJSON 与 Content-Length 两种帧都支持 |

## 工作原理

- **离线**：`draw.io.exe --export --format png --output x.png x.drawio`，与 GUI 无关，可批量。
- **在线**：启动参数带 `--remote-debugging-port=9333`，通过 CDP 注入初始化脚本，包装 `EditorUi.prototype.init`，页面初始化时把实例挂到 `window.__drawioUi`；之后所有操作走 `setFileData` / `getFileData` / `Page.captureScreenshot`，不模拟鼠标键盘。

## 环境要求

- Node.js **≥ 22**（内置 `fetch`、`WebSocket`）
- draw.io 桌面版（默认绝对路径 `E:\draw.io\draw.io.exe`，可用 `--exe` 或环境变量 `DRAWIO_EXE` 覆盖）
- Windows（路径按 Windows 绝对路径编写；Linux/macOS 需自行改 `--exe` 指向）

## 安装

```powershell
git clone https://github.com/wangcangxing/drawio-mcp-bridge.git "D:\program\drawio-mcp-bridge"
cd "D:\program\drawio-mcp-bridge"
node "D:\program\drawio-mcp-bridge\test\smoke.mjs"
```

无需 `npm install`，没有第三方依赖。

## 快速开始（绝对路径）

```powershell
# 1) JSON 规格 -> .drawio -> PNG
node "D:\program\drawio-mcp-bridge\src\cli.mjs" gen --spec "D:\program\drawio-mcp-bridge\examples\architecture.json" --out "D:\work\out\architecture.drawio"
node "D:\program\drawio-mcp-bridge\src\cli.mjs" export --input "D:\work\out\architecture.drawio" --format png --scale 2

# 2) 启动带调试端口的 draw.io，并把图灌进编辑器
node "D:\program\drawio-mcp-bridge\src\cli.mjs" launch --port 9333
node "D:\program\drawio-mcp-bridge\src\cli.mjs" apply --input "D:\work\out\architecture.drawio" --shot "D:\work\out\live.png"

# 3) 从正在运行的编辑器取回当前图
node "D:\program\drawio-mcp-bridge\src\cli.mjs" pull --output "D:\work\out\current.drawio"
```

## 命令

```
gen     --spec <spec.json|-> [--out <x.drawio>]
export  --input <x.drawio> [--output <out>] [--format png|svg|pdf] [--scale 2]
        [--border 10] [--all-pages] [--page-index 0] [--crop] [--transparent] [--exe <draw.io.exe>]
launch  [--port 9333] [--file <x.drawio>] [--profile <dir>] [--exe <draw.io.exe>]
attach  [--port 9333] [--no-reload]
status  [--port 9333]
apply   (--spec <spec.json> | --xml <x.drawio> | --input <x.drawio|spec.json>)
        [--shot <out.png>] [--save <out.drawio>] [--port 9333]
open    --file <x.drawio> [--shot <out.png>] [--port 9333]
pull    [--output <x.drawio>] [--port 9333]
shot    --output <out.png> [--port 9333]
mcp     以 stdio MCP server 运行
```

端口默认 `9333`（`DRAWIO_CDP_PORT`），可执行文件默认 `E:\draw.io\draw.io.exe`（`DRAWIO_EXE`）。

## spec 格式

```json
{
  "title": "支付链路",
  "page": { "name": "Payment Flow", "width": 1200, "height": 720 },
  "defaults": { "fill": "#dae8fc", "stroke": "#6c8ebf", "fontSize": 13 },
  "layout": { "mode": "flow", "gapX": 90, "gapY": 70, "margin": 50 },
  "groups": [
    { "id": "cloud", "label": "云端", "x": 40, "y": 40, "w": 600, "h": 200, "fill": "#e1d5e7", "stroke": "#9673a6" }
  ],
  "nodes": [
    { "id": "client", "label": "客户端", "shape": "rounded", "group": "cloud" },
    { "id": "db", "label": "MySQL", "shape": "database" }
  ],
  "edges": [
    { "from": "client", "to": "db", "label": "SQL", "dashed": true }
  ]
}
```

- `shape`：`rounded` `rect` `ellipse` `circle` `diamond` `database` `cloud` `note` `actor` `hexagon` `process` `document` `queue` `terminal` `text`，或用 `style` 直接写 draw.io 样式串。
- 节点可选 `x/y/w/h/fill/stroke/fontColor/fontSize/dashed/shadow/style/group`；给了 `x` 和 `y` 就不再自动布局。
- `layout.mode`：`flow`（按边做最长路径分层）或 `grid`（`columns` 控制列数）；有环自动退回 grid。
- `groups`：swimlane 容器，子节点坐标自动转相对坐标；不给 `x/y/w/h` 时按成员包围盒外扩。
- 标签支持 `\n` 换行（生成 `<br>`）。

## MCP 接入

服务命令（**绝对路径**）：

```json
{
  "mcpServers": {
    "drawio": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "D:\\program\\drawio-mcp-bridge\\src\\cli.mjs",
        "mcp"
      ],
      "env": {
        "DRAWIO_EXE": "E:\\draw.io\\draw.io.exe",
        "DRAWIO_CDP_PORT": "9333"
      }
    }
  }
}
```

工具清单：

| 工具 | 作用 |
|---|---|
| `drawio_status` | 是否已挂上钩子、当前图元数、文件名、画布尺寸 |
| `drawio_launch` | 带调试端口启动 draw.io（可附文件） |
| `drawio_attach` | 连接并注入钩子（首次可能 reload） |
| `drawio_generate` | spec → XML / `.drawio` |
| `drawio_export` | PNG / SVG / PDF 导出 |
| `drawio_apply` | 规格或 XML 实时灌进编辑器，可截图 / 另存 |
| `drawio_pull` | 取回当前图 XML |
| `drawio_screenshot` | 窗口截图 |
| `drawio_open` | 在运行中的编辑器里打开 `.drawio` |

## 已实测（2026-10-21，draw.io 32.5.5 / Node v24.13.1）

| 项 | 结果 |
|---|---|
| `gen` 8 节点 7 边 | 3932 字节 `.drawio` |
| `export --format png --scale 2` | 1985×765，112601 字节 |
| `export --format svg` | 118905 字节 |
| `export --format pdf`（GUI 同时运行） | 28572 字节，exit 0 |
| `launch --port 9333` | CDP 可达，钩子注入成功 |
| `apply --shot` | 编辑器显示该图，`cells: 15` |
| `pull` | 4415 字节 mxfile |
| `status`（应用后） | `cells: 15`、`modified: true` |
| 杀掉进程后 `status` | 明确报错；`launch` 可重新挂载 |
| MCP `initialize` / `tools/list` / `tools/call` | 均返回合法 JSON-RPC 结果 |

## 已知限制

- 在线控制只对用 `launch`（或手动加 `--remote-debugging-port`）启动的实例生效；已经开着的普通实例需要先完全退出。
- 首次 `attach` 到非本工具启动的实例需要 reload 一次以注入钩子，当前未保存编辑有丢失风险（draw.io 自带备份可能恢复，不能依赖）；`attach --no-reload` 只检测不注入。
- 在线写图走 `setFileData`，不会自动落盘，界面显示「修改未保存」；落盘用 `pull --output` 或 `apply --save`。
- `export` 在 GUI 同时运行时 stderr 可能有 Chromium 磁盘缓存告警（`Unable to move the cache`），不影响退出码与产物。
- 自动布局不保证零交叉；精确排版请直接给节点 `x/y`，或在 draw.io 里调好后 `pull` 固化坐标。

## 目录结构

```
drawio-mcp-bridge/
├─ src/
│  ├─ cdp.mjs        # CDP 连接、Page.enable、EditorUi 钩子注入、弹框自动确认
│  ├─ spec.mjs       # JSON 规格 -> mxfile XML；分组、多行标签、flow/grid 布局
│  ├─ drawio.mjs     # 启动、CLI 导出、apply / pull / screenshot / status
│  ├─ cli.mjs        # 命令行入口
│  └─ mcp.mjs        # stdio MCP server
├─ test/smoke.mjs    # 冒烟：spec -> XML -> PNG，在线状态可选
├─ examples/         # 两个示例规格
├─ package.json
├─ LICENSE
└─ README.md
```

## 相关链接

- draw.io 上游仓库：[https://github.com/jgraph/drawio](https://github.com/jgraph/drawio)
- draw.io 桌面版下载：[https://github.com/jgraph/drawio-desktop](https://github.com/jgraph/drawio-desktop)
- draw.io 扩展 / 插件文档：[https://www.drawio.com/doc/faq/plugins](https://www.drawio.com/doc/faq/plugins)

## 许可

MIT，见 [LICENSE](LICENSE)。

本仓库不包含 draw.io 的任何源码、二进制或商标资源；draw.io 的版权归 JGraph Ltd 所有。