drawio-mcp-server 2.1.0 → 2.2.0

package/README.md

@@ -41,7 +41,7 @@ Experimental: integration with the **draw.io desktop (Electron) app** is in prog
 
 ## Requirements
 
-- **Node.js** (v20 or higher) - Runtime environment for the MCP server
+- **Node.js** (v22 or higher; tested against v22 LTS and v24 LTS) - Runtime environment for the MCP server
 - **MCP client** - Claude Desktop, Claude Code, Zed, Codex, OpenCode, or any MCP-compatible host
 
 ### For Built-in Editor

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));
+}

package/build/index.js

@@ -12,7 +12,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, existsSync, statSync, readdirSync, realpathSync, } from "node:fs";
 import { WebSocket, WebSocketServer } from "ws";
-const VERSION = process.env.npm_package_version ?? "2.1.0";
+const VERSION = process.env.npm_package_version ?? "2.2.0";
 import { buildConfig, defaultConfig, hasFlag, shouldShowHelp, getHttpFeatureConfig, } from "./config.js";
 import { installDesktopPlugin } from "./install-desktop-plugin.js";
 import { bus_reply_stream, bus_request_stream, } from "./types.js";
@@ -26,6 +26,7 @@ import { registerTools } from "./tools/index.js";
 import { createServerWithSchemaStripping } from "./register-tool.js";
 import { target_document_field } from "./tools/shared.js";
 import { resolveTlsMaterial } from "./tls/index.js";
+import { handleCompatReport } from "./drawio-compat/log-report.js";
 const fatalLog = create_console_logger();
 /**
  * Display help message and exit
@@ -320,12 +321,12 @@ export function createDrawioMcpApp(options) {
         };
     }
     function listKnownDocuments() {
-        return [...conns.values()]
-            .map((entry) => entry.document)
-            .filter((document) => document !== null);
+        return [...conns.values()].flatMap((entry) => [
+            ...entry.documents.values(),
+        ]);
     }
     function findConnectionByDocumentId(documentId) {
-        return [...conns.values()].find((entry) => entry.document?.id === documentId);
+        return [...conns.values()].find((entry) => entry.documents.has(documentId));
     }
     function flushSyncWaiters(entry) {
         for (const resolve of [...entry.sync_waiters]) {
@@ -347,6 +348,24 @@ export function createDrawioMcpApp(options) {
         }));
         return true;
     }
+    function broadcastDocumentsChanged() {
+        const documents = listKnownDocuments();
+        const frame = JSON.stringify({
+            __control: "documents-changed",
+            documents,
+        });
+        for (const entry of conns.values()) {
+            if (entry.ws.readyState !== WebSocket.OPEN) {
+                continue;
+            }
+            try {
+                entry.ws.send(frame);
+            }
+            catch (error) {
+                getLog().debug(`[ws] documents-changed send failed`, error);
+            }
+        }
+    }
     function requestDocumentSync(entry) {
         return new Promise((resolve) => {
             let settled = false;
@@ -392,13 +411,14 @@ export function createDrawioMcpApp(options) {
                     await syncAllDocuments();
                     entry = findConnectionByDocumentId(documentId);
                 }
-                if (!entry || !entry.document) {
+                const document = entry?.documents.get(documentId);
+                if (!entry || !document) {
                     throw new Error(`Document with ID ${documentId} was not found`);
                 }
                 return {
                     connection_id: entry.connection_id,
                     target_document: { id: documentId },
-                    document: entry.document,
+                    document,
                 };
             }
             await syncAllDocuments();
@@ -596,7 +616,7 @@ export function createDrawioMcpApp(options) {
             const entry = {
                 connection_id,
                 ws,
-                document: null,
+                documents: new Map(),
                 updated_at: Date.now(),
                 sync_waiters: new Set(),
             };
@@ -609,9 +629,26 @@ export function createDrawioMcpApp(options) {
                     const json = JSON.parse(str);
                     getLog().debug(`[ws] received from Extension`, json);
                     if (json?.__control === "document-state") {
-                        entry.document = normalizeDocumentState(json.document);
+                        const document = normalizeDocumentState(json.document);
+                        if (document) {
+                            entry.documents.set(document.id, document);
+                        }
                         entry.updated_at = Date.now();
                         flushSyncWaiters(entry);
+                        broadcastDocumentsChanged();
+                        return;
+                    }
+                    if (json?.__control === "document-removed") {
+                        const removedId = normalizeOptionalString(json.document_id);
+                        if (removedId) {
+                            entry.documents.delete(removedId);
+                            entry.updated_at = Date.now();
+                            broadcastDocumentsChanged();
+                        }
+                        return;
+                    }
+                    if (json?.__control === "compat-report") {
+                        handleCompatReport(json, getLog());
                         return;
                     }
                     emitter.emit(bus_reply_stream, json);
@@ -623,12 +660,14 @@ export function createDrawioMcpApp(options) {
             ws.on("close", (code) => {
                 flushSyncWaiters(entry);
                 conns.delete(connection_id);
+                broadcastDocumentsChanged();
                 getLog().debug(`[ws_handler] WebSocket client ${connection_id} closed with code ${code}`);
             });
             ws.on("error", (error) => {
                 getLog().debug(`[ws_handler] WebSocket client error`, error);
                 flushSyncWaiters(entry);
                 conns.delete(connection_id);
+                broadcastDocumentsChanged();
             });
         });
         if (!tlsMaterial) {
@@ -652,22 +691,44 @@ export function createDrawioMcpApp(options) {
         return wsServer;
     }
     async function close() {
+        getLog().debug(`[close] begin`);
         emitter.off(bus_request_stream, bus_to_ws_forwarder_listener);
+        // ws.close() is graceful and waits for the peer close frame; a dead or
+        // slow peer keeps the underlying TCP socket alive, which in turn keeps
+        // the ws server's internal http.Server from firing its close callback.
+        // terminate() destroys the socket immediately.
         for (const entry of [...conns.values()]) {
             try {
                 flushSyncWaiters(entry);
-                entry.ws.close();
+                entry.ws.terminate();
             }
             catch {
                 // ignore
             }
         }
         conns.clear();
+        getLog().debug(`[close] tracked ws clients terminated`);
         for (const s of mcpServers) {
             await s.close();
         }
         mcpServers.clear();
+        getLog().debug(`[close] mcp servers closed`);
         if (wsServer) {
+            // Also terminate any straggler clients that connected but never
+            // completed our handshake (not in `conns`).
+            for (const client of wsServer.clients) {
+                try {
+                    client.terminate();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            // For port-created WebSocketServer, `_server` is the underlying
+            // http.Server; force-close any lingering TCP connections so its
+            // close() callback fires promptly.
+            const internal = wsServer._server;
+            internal?.closeAllConnections?.();
             await new Promise((resolve, reject) => {
                 wsServer?.close((error) => {
                     if (error) {
@@ -678,6 +739,7 @@ export function createDrawioMcpApp(options) {
                 });
             });
             wsServer = undefined;
+            getLog().debug(`[close] wsServer closed`);
         }
         if (wssHttpsServer) {
             const hs = wssHttpsServer;
@@ -687,8 +749,13 @@ export function createDrawioMcpApp(options) {
             // WebSocket upgrade) so the server closes immediately.
             hs.closeAllConnections?.();
             await new Promise((resolve) => hs.close(() => resolve()));
+            getLog().debug(`[close] wssHttpsServer closed`);
         }
         if (httpServer) {
+            // Node http.Server.close() waits for keep-alive TCP sockets to drain;
+            // MCP HTTP clients keep them open. Force them shut like wssHttpsServer.
+            const hs = httpServer;
+            hs.closeAllConnections?.();
             await new Promise((resolve, reject) => {
                 httpServer?.close((error) => {
                     if (error) {
@@ -699,7 +766,9 @@ export function createDrawioMcpApp(options) {
                 });
             });
             httpServer = undefined;
+            getLog().debug(`[close] httpServer closed`);
         }
+        getLog().debug(`[close] done`);
     }
     return {
         createMcpServer,
@@ -772,8 +841,41 @@ async function main() {
         app.log.debug("Assets ready!");
     }
     await app.startWebSocketServer(config.extensionPort, config.host);
+    let shuttingDown = false;
+    const shutdown = async (reason) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        app.log.debug(`[shutdown] triggered by ${reason}`);
+        try {
+            await app.close();
+        }
+        catch (error) {
+            app.log.log("error", "[shutdown] error while closing app", error);
+        }
+        process.exit(0);
+    };
+    process.on("SIGTERM", () => {
+        void shutdown("SIGTERM");
+    });
+    process.on("SIGINT", () => {
+        void shutdown("SIGINT");
+    });
+    process.on("SIGHUP", () => {
+        void shutdown("SIGHUP");
+    });
     if (config.transports.indexOf("stdio") > -1) {
         await app.startStdioTransport();
+        // MCP hosts (e.g. Claude Desktop on Windows) signal disconnect by
+        // closing the stdio pipe rather than sending a POSIX signal. Without
+        // this, the WebSocket server keeps the event loop alive and port
+        // 3333 leaks across host restarts.
+        process.stdin.once("end", () => {
+            void shutdown("stdin-end");
+        });
+        process.stdin.once("close", () => {
+            void shutdown("stdin-close");
+        });
     }
     await app.startHttpServer(config.httpPort, config, features);
     app.log.debug(`Draw.io MCP Server running on ${config.transports}`);