drawio-mcp-server 2.1.1 → 2.3.0

package/README.md

@@ -9,12 +9,16 @@ Let's do some Vibe Diagramming with the most wide-spread diagramming tool called
 
 ## Key Highlights
 
-- Enable Draw.io MCP in IFrames ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
-- AWS, GCP, Azure, Cisco19, and CiscoSafe stencils auto-discovered at runtime from drawio's sidebar ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
-- Multi-document targeting with `list-documents` and `target_document` selectors for multi-tab workflows ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
-- Multi-page targeting with required `target_page` selectors for page-scoped tools ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
-- Per-document FIFO serialization for live operations, so multiple agents can work on different files safely ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
-- Page management tools: `list-pages`, `get-current-page`, `create-page`, `copy-page`, `rename-page` ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Claude Code plugin: `/plugin marketplace add lgazo/drawio-mcp-server` then `/plugin install drawio`, with `/drawio-open` and `/drawio-status` slash commands ![v2.3.0](https://img.shields.io/badge/v2.3.0-blue)
+- `npx drawio-mcp-server install <host>` writes the MCP config for `claude-code`, `claude-desktop`, `codex`, `zed`, `opencode`, or `all` ![v2.3.0](https://img.shields.io/badge/v2.3.0-blue)
+- Document persistence tools: `set-document-title` and `save-document` ![v2.3.0](https://img.shields.io/badge/v2.3.0-blue)
+- Draw.io library API version compatibility mechanism ![v2.2.0](https://img.shields.io/badge/v2.2.0-blue)
+- Enable Draw.io MCP in IFrames
+- AWS, GCP, Azure, Cisco19, and CiscoSafe stencils auto-discovered at runtime from drawio's sidebar
+- Multi-document targeting with `list-documents` and `target_document` selectors for multi-tab workflows
+- Multi-page targeting with required `target_page` selectors for page-scoped tools
+- Per-document FIFO serialization for live operations, so multiple agents can work on different files safely
+- Page management tools: `list-pages`, `get-current-page`, `create-page`, `copy-page`, `rename-page`
 - Import, embed, or expand [Mermaid](https://mermaid.js.org/) diagrams ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
 - Firefox support is back, TLS mode is necessary ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
 - Server supports TLS mode and optionally generates self-signed certificates ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
@@ -58,10 +62,15 @@ No additional requirements - runs out of the box with `--editor` flag.
 
 ### 1. Configure your MCP host
 
-Add the server to your MCP client configuration:
+**Fastest path:**
+
+- **Claude Code:** `/plugin marketplace add lgazo/drawio-mcp-server` then `/plugin install drawio`.
+- **Any other host:** `npx drawio-mcp-server install <host>` where `<host>` is `claude-code`, `claude-desktop`, `codex`, `zed`, `opencode`, or `all`.
+
+See [docs/PLUGINS.md](./docs/PLUGINS.md) for the full reference, flags, and uninstall, and [docs/release.md](./docs/release.md) for how releases are cut.
 
 <details>
-  <summary>Claude Desktop</summary>
+  <summary>Manual install (JSON snippet, Claude Desktop example)</summary>
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -75,63 +84,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
   }
 }
 ```
-</details>
-
-<details>
-  <summary>Claude Code</summary>
-
-```sh
-claude mcp add-json drawio '{"type":"stdio","command":"npx","args":["-y","drawio-mcp-server","--editor"]}'
-```
-</details>
-
-<details>
-  <summary>Zed</summary>
-
-Add to `~/.config/zed/settings.json`:
-
-```json
-{
-  "context_servers": {
-    "drawio": {
-      "command": "npx",
-      "args": ["-y", "drawio-mcp-server", "--editor"],
-      "env": {}
-    }
-  }
-}
-```
-</details>
-
-<details>
-  <summary>Codex</summary>
-
-Edit `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.drawio]
-command = "npx"
-args = ["-y", "drawio-mcp-server", "--editor"]
-```
-</details>
 
-<details>
-  <summary>OpenCode</summary>
-
-Add to `opencode.json` in your project root or `~/.config/opencode/opencode.json`:
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "drawio": {
-      "type": "local",
-      "command": ["npx", "-y", "drawio-mcp-server", "--editor"],
-      "enabled": true
-    }
-  }
-}
-```
 </details>
 
 For other MCP clients and detailed configuration (including pnpm options), see [Configuration](./CONFIG.md).
@@ -223,11 +176,11 @@ See [DESKTOP.md](./DESKTOP.md) for the full setup steps and the current limitati
 
 ## Star History
 
-<a href="https://star-history.com/#lgazo/drawio-mcp-server&Date">
+<a href="https://star-history.dera.page/#lgazo/drawio-mcp-server&type=Date">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=lgazo/drawio-mcp-server&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=lgazo/drawio-mcp-server&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=lgazo/drawio-mcp-server&type=Date" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=lgazo/drawio-mcp-server&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=lgazo/drawio-mcp-server&type=Date" />
+   <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=lgazo/drawio-mcp-server&type=Date" />
  </picture>
 </a>
 

package/build/assets/auto-refresh.js

@@ -0,0 +1,21 @@
+import { rmSync } from "node:fs";
+import { SERVER_COMPAT_MATRIX, versionInWindow, } from "../drawio-compat/matrix.js";
+export { SERVER_COMPAT_MATRIX };
+import { getAssetRoot, getCacheDir } from "./manager.js";
+import { readCachedDrawioVersion } from "./version.js";
+export async function ensureSupportedAssets(config, matrix, log, ports) {
+    const cacheDir = getCacheDir(config.assetPath);
+    const assetRoot = getAssetRoot(config);
+    const cached = await readCachedDrawioVersion(assetRoot);
+    if (cached && versionInWindow(cached, matrix)) {
+        return { version: cached, refetched: false };
+    }
+    log.log("warning", `cached drawio v${cached ?? "?"} is outside supported window (>= v${matrix.supportedFloor}); refetching latest`);
+    rmSync(assetRoot, { recursive: true, force: true });
+    await ports.downloadAndExtract(cacheDir, log);
+    const after = await readCachedDrawioVersion(assetRoot);
+    if (!after || !versionInWindow(after, matrix)) {
+        log.log("error", `drawio latest v${after ?? "?"} is still outside supported window; tools may misbehave`);
+    }
+    return { version: after, refetched: true };
+}

package/build/assets/auto-refresh.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ensureSupportedAssets } from "./auto-refresh.js";
+import { SERVER_COMPAT_MATRIX } from "../drawio-compat/matrix.js";
+function makeCachedVersion(version) {
+    const root = mkdtempSync(join(tmpdir(), "auto-refresh-"));
+    const webapp = join(root, "webapp");
+    const jsDir = join(webapp, "js");
+    mkdirSync(jsDir, { recursive: true });
+    writeFileSync(join(jsDir, "app.min.js"), `pre;EditorUi.VERSION="${version}";post`);
+    return root;
+}
+const logger = {
+    log: jest.fn(),
+};
+describe("ensureSupportedAssets", () => {
+    it("returns cached version without refetch when in range", async () => {
+        const cacheDir = makeCachedVersion("30.2.6");
+        const download = jest.fn(async () => { });
+        const result = await ensureSupportedAssets({ assetPath: cacheDir }, SERVER_COMPAT_MATRIX, logger, { downloadAndExtract: download });
+        expect(download).not.toHaveBeenCalled();
+        expect(result).toEqual({ version: "30.2.6", refetched: false });
+    });
+    it("wipes cache and re-downloads when cached is out of window", async () => {
+        const cacheDir = makeCachedVersion("28.0.0");
+        const download = jest.fn(async (target) => {
+            const jsDir = join(target, "webapp", "js");
+            mkdirSync(jsDir, { recursive: true });
+            writeFileSync(join(jsDir, "app.min.js"), `pre;EditorUi.VERSION="30.2.6";post`);
+        });
+        const result = await ensureSupportedAssets({ assetPath: cacheDir }, SERVER_COMPAT_MATRIX, logger, { downloadAndExtract: download });
+        expect(download).toHaveBeenCalled();
+        expect(result).toEqual({ version: "30.2.6", refetched: true });
+    });
+    it("logs error when refetched version is still out of window", async () => {
+        const cacheDir = makeCachedVersion("28.0.0");
+        const download = jest.fn(async (target) => {
+            const jsDir = join(target, "webapp", "js");
+            mkdirSync(jsDir, { recursive: true });
+            writeFileSync(join(jsDir, "app.min.js"), `pre;EditorUi.VERSION="28.5.0";post`);
+        });
+        const errorLogs = [];
+        const trackingLogger = {
+            log: (level, ...args) => {
+                if (level === "error")
+                    errorLogs.push(args);
+            },
+        };
+        await ensureSupportedAssets({ assetPath: cacheDir }, SERVER_COMPAT_MATRIX, trackingLogger, { downloadAndExtract: download });
+        expect(errorLogs.length).toBeGreaterThan(0);
+    });
+});

package/build/assets/downloader.js

@@ -85,11 +85,15 @@ export async function downloadAndExtractAssets(targetDir, log) {
 }
 export async function ensureAssets(config, log) {
     const { getCacheDir, getAssetRoot, assetsExist } = await import("./manager.js");
+    const { ensureSupportedAssets, SERVER_COMPAT_MATRIX } = await import("./auto-refresh.js");
     const cacheDir = getCacheDir(config.assetPath);
     const assetRoot = getAssetRoot(config);
     if (!assetsExist(config)) {
         log.log("info", `Assets not found in ${assetRoot}. Downloading...`);
         await downloadAndExtractAssets(cacheDir, log);
     }
+    await ensureSupportedAssets(config, SERVER_COMPAT_MATRIX, log, {
+        downloadAndExtract: (targetDir) => downloadAndExtractAssets(targetDir, log),
+    });
     return { assetRoot, isLocal: true };
 }

package/build/assets/version.js

@@ -0,0 +1,38 @@
+import { createReadStream, existsSync } from "node:fs";
+import { join } from "node:path";
+const CHUNK_BYTES = 1024 * 1024;
+const OVERLAP_BYTES = 64;
+const VERSION_RE = /EditorUi\.VERSION\s*=\s*"(\d+\.\d+\.\d+)"/;
+export async function readCachedDrawioVersion(assetRoot) {
+    const path = join(assetRoot, "js", "app.min.js");
+    if (!existsSync(path))
+        return null;
+    return new Promise((resolve, reject) => {
+        const stream = createReadStream(path, { highWaterMark: CHUNK_BYTES });
+        let tail = "";
+        let resolved = false;
+        const finish = (value) => {
+            if (resolved)
+                return;
+            resolved = true;
+            stream.destroy();
+            resolve(value);
+        };
+        stream.on("data", (chunk) => {
+            const text = tail + (typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+            const match = VERSION_RE.exec(text);
+            if (match) {
+                finish(match[1] ?? null);
+                return;
+            }
+            tail = text.slice(-OVERLAP_BYTES);
+        });
+        stream.on("end", () => finish(null));
+        stream.on("error", (err) => {
+            if (resolved)
+                return;
+            resolved = true;
+            reject(err);
+        });
+    });
+}

package/build/assets/version.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "@jest/globals";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readCachedDrawioVersion } from "./version.js";
+function makeFixture(contents) {
+    const root = mkdtempSync(join(tmpdir(), "drawio-version-"));
+    const jsDir = join(root, "js");
+    mkdirSync(jsDir, { recursive: true });
+    writeFileSync(join(jsDir, "app.min.js"), contents);
+    return root;
+}
+describe("readCachedDrawioVersion", () => {
+    it("returns the version parsed from app.min.js", async () => {
+        const root = makeFixture(`prefix;EditorUi.VERSION="30.2.6";suffix`);
+        await expect(readCachedDrawioVersion(root)).resolves.toBe("30.2.6");
+    });
+    it("returns null when app.min.js is missing", async () => {
+        const root = mkdtempSync(join(tmpdir(), "drawio-version-"));
+        await expect(readCachedDrawioVersion(root)).resolves.toBeNull();
+    });
+    it("returns null when VERSION assignment is absent", async () => {
+        const root = makeFixture("no version marker here");
+        await expect(readCachedDrawioVersion(root)).resolves.toBeNull();
+    });
+});

package/build/documents-changed-broadcast.test.js

@@ -0,0 +1,123 @@
+import WebSocket from "ws";
+import { createDrawioMcpApp } from "./index.js";
+import { MemoryLogger } from "./real-environment/logger.js";
+const HOST = "127.0.0.1";
+async function waitForMessage(ws, predicate, timeoutMs = 2000) {
+    return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            ws.off("message", onMessage);
+            reject(new Error("timeout waiting for matching WebSocket message"));
+        }, timeoutMs);
+        function onMessage(data) {
+            const text = typeof data === "string" ? data : data.toString();
+            let json;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                return;
+            }
+            if (predicate(json)) {
+                clearTimeout(timer);
+                ws.off("message", onMessage);
+                resolve(json);
+            }
+        }
+        ws.on("message", onMessage);
+    });
+}
+async function openClient(port) {
+    const ws = new WebSocket(`ws://${HOST}:${port}`);
+    await new Promise((resolve, reject) => {
+        ws.once("open", () => resolve());
+        ws.once("error", reject);
+    });
+    // Server sends `sync-document-state` on connect; ignore it here.
+    return ws;
+}
+describe("documents-changed broadcast", () => {
+    let app;
+    let logger;
+    let port;
+    beforeEach(async () => {
+        logger = new MemoryLogger();
+        app = createDrawioMcpApp({ log: logger });
+        const wsServer = await app.startWebSocketServer(0, HOST);
+        port = wsServer.address().port;
+    });
+    afterEach(async () => {
+        await app.close();
+    });
+    it("emits documents-changed after inbound document-state", async () => {
+        const ws = await openClient(port);
+        const received = waitForMessage(ws, (json) => json?.__control === "documents-changed");
+        ws.send(JSON.stringify({
+            __control: "document-state",
+            document: {
+                id: "doc-a",
+                title: "Alpha",
+                mode: "device",
+                hash: null,
+                file_url: null,
+                page_count: 1,
+                current_page: {
+                    index: 0,
+                    id: "p1",
+                    name: "Page-1",
+                    is_current: true,
+                },
+            },
+        }));
+        const payload = await received;
+        expect(payload.documents).toHaveLength(1);
+        expect(payload.documents[0].id).toBe("doc-a");
+        expect(payload.documents[0].title).toBe("Alpha");
+        ws.close();
+    });
+    it("emits documents-changed after inbound document-removed", async () => {
+        const ws = await openClient(port);
+        ws.send(JSON.stringify({
+            __control: "document-state",
+            document: {
+                id: "doc-b",
+                title: "Beta",
+                mode: "device",
+                hash: null,
+                file_url: null,
+                page_count: 1,
+                current_page: null,
+            },
+        }));
+        await waitForMessage(ws, (json) => json?.__control === "documents-changed" && json.documents.length === 1);
+        const removed = waitForMessage(ws, (json) => json?.__control === "documents-changed" && json.documents.length === 0);
+        ws.send(JSON.stringify({
+            __control: "document-removed",
+            document_id: "doc-b",
+        }));
+        const payload = await removed;
+        expect(payload.documents).toEqual([]);
+        ws.close();
+    });
+    it("emits documents-changed to remaining clients after peer disconnect", async () => {
+        const clientA = await openClient(port);
+        const clientB = await openClient(port);
+        clientA.send(JSON.stringify({
+            __control: "document-state",
+            document: {
+                id: "doc-c",
+                title: "Gamma",
+                mode: "device",
+                hash: null,
+                file_url: null,
+                page_count: 1,
+                current_page: null,
+            },
+        }));
+        await waitForMessage(clientB, (json) => json?.__control === "documents-changed" && json.documents.length === 1);
+        const drained = waitForMessage(clientB, (json) => json?.__control === "documents-changed" && json.documents.length === 0);
+        clientA.close();
+        const payload = await drained;
+        expect(payload.documents).toEqual([]);
+        clientB.close();
+    });
+});

package/build/drawio-compat/log-report.js

@@ -0,0 +1,21 @@
+export function handleCompatReport(payload, log) {
+    const v = payload.drawioVersion ?? "unknown";
+    switch (payload.state) {
+        case "ok":
+            log.log("info", `drawio v${v} is within supported window`);
+            return;
+        case "below-floor":
+            log.log("error", `drawio v${v} predates supported floor v${payload.floor}; ` +
+                `version-gated tools will return errors`);
+            return;
+        case "above-window":
+            log.log("warning", `drawio v${v} is newer than the tested window ` +
+                `(last tested min: v${payload.detail ?? "?"}); running on newest impl`);
+            return;
+        case "no-version":
+            log.log("warning", `plugin could not detect drawio version (${payload.detail ?? "?"})`);
+            return;
+        default:
+            log.log("warning", `unknown compat state \`${payload.state}\` (drawio v${v})`);
+    }
+}

package/build/drawio-compat/log-report.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "@jest/globals";
+import { handleCompatReport } from "./log-report.js";
+function makeLogger() {
+    const calls = [];
+    return {
+        calls,
+        logger: {
+            log: (lvl, msg) => calls.push([lvl, msg]),
+        },
+    };
+}
+describe("handleCompatReport", () => {
+    it("emits info for ok state", () => {
+        const { calls, logger } = makeLogger();
+        handleCompatReport({ drawioVersion: "30.2.6", state: "ok", floor: "29.0.0" }, logger);
+        expect(calls.some(([lvl]) => lvl === "info")).toBe(true);
+    });
+    it("emits error for below-floor state", () => {
+        const { calls, logger } = makeLogger();
+        handleCompatReport({ drawioVersion: "28.0.0", state: "below-floor", floor: "29.0.0" }, logger);
+        expect(calls.some(([lvl]) => lvl === "error")).toBe(true);
+    });
+    it("emits warning for above-window state", () => {
+        const { calls, logger } = makeLogger();
+        handleCompatReport({
+            drawioVersion: "31.0.0",
+            state: "above-window",
+            floor: "29.0.0",
+            detail: "30.0.0",
+        }, logger);
+        expect(calls.some(([lvl]) => lvl === "warning")).toBe(true);
+    });
+    it("emits warning for no-version state", () => {
+        const { calls, logger } = makeLogger();
+        handleCompatReport({
+            drawioVersion: null,
+            state: "no-version",
+            floor: "29.0.0",
+            detail: "missing",
+        }, logger);
+        expect(calls.some(([lvl]) => lvl === "warning")).toBe(true);
+    });
+});

package/build/drawio-compat/matrix.js

@@ -0,0 +1,14 @@
+import { isInRange, parseVersion, } from "../vendored/compat/index.js";
+export const SERVER_COMPAT_MATRIX = {
+    supportedFloor: "29.0.0",
+    supportedRanges: [
+        { min: "29.0.0", maxExclusive: "30.0.0" },
+        { min: "30.0.0", maxExclusive: null },
+    ],
+};
+export function versionInWindow(version, matrix) {
+    const parsed = parseVersion(version);
+    if (!parsed)
+        return false;
+    return matrix.supportedRanges.some((r) => isInRange(parsed, r));
+}