drawio-mcp-server 2.1.1 → 2.3.0

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.1";
+const VERSION = process.env.npm_package_version ?? "2.3.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,7 +26,19 @@ 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();
+if (process.argv[2] === "install") {
+    const { runInstall } = await import("./install/index.js");
+    try {
+        const code = await runInstall(process.argv.slice(3));
+        process.exit(code);
+    }
+    catch (err) {
+        fatalLog.log("error", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 /**
  * Display help message and exit
  */
@@ -222,6 +234,20 @@ async function startHttpServer(createServer, disposeMcpServer, log, httpPort, co
             }
             : {}),
     });
+    // `serve()` calls `listen()` synchronously; wait for the outcome so a failed
+    // bind surfaces as a clean, fatal error instead of an unhandled 'error'
+    // event (or, worse, silence).
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", (error) => {
+            reject(new Error(`Failed to bind HTTP server on port ${httpPort}: ${error instanceof Error ? error.message : String(error)}`, { cause: error }));
+        });
+        if (httpServer.listening) {
+            resolve();
+        }
+        else {
+            httpServer.once("listening", () => resolve());
+        }
+    });
     const listeningPort = httpPort === 0
         ? (httpServer.address()?.port ?? httpPort)
         : httpPort;
@@ -320,12 +346,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 +373,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 +436,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 +641,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 +654,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 +685,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 +716,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 +764,7 @@ export function createDrawioMcpApp(options) {
                 });
             });
             wsServer = undefined;
+            getLog().debug(`[close] wsServer closed`);
         }
         if (wssHttpsServer) {
             const hs = wssHttpsServer;
@@ -687,8 +774,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 +791,9 @@ export function createDrawioMcpApp(options) {
                 });
             });
             httpServer = undefined;
+            getLog().debug(`[close] httpServer closed`);
         }
+        getLog().debug(`[close] done`);
     }
     return {
         createMcpServer,
@@ -772,10 +866,57 @@ 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");
+        });
+    }
+    // Only open the HTTP listener when something will actually be served on
+    // it. A stdio-only run previously bound port 3000 unconditionally,
+    // colliding with common dev servers while serving nothing useful
+    // (see upstream issue #66).
+    if (features.enableMcp || features.enableEditor) {
+        await app.startHttpServer(config.httpPort, config, features);
+    }
+    else {
+        app.log.debug("HTTP server not started: no HTTP surface enabled (stdio-only run). Use --transport http or --editor to serve HTTP.");
+        const httpPortExplicit = cliArgs.includes("--http-port") ||
+            Boolean(process.env.DRAWIO_MCP_HTTP_PORT?.length);
+        if (httpPortExplicit) {
+            app.log.log("warning", `--http-port was set but no HTTP surface is enabled; port ${config.httpPort} stays free. Use --transport http or --editor to serve HTTP.`);
+        }
     }
-    await app.startHttpServer(config.httpPort, config, features);
     app.log.debug(`Draw.io MCP Server running on ${config.transports}`);
 }
 const isMainModule = process.argv[1]

package/build/install/config-io.js

@@ -0,0 +1,21 @@
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+import { createPatch } from "diff";
+export async function atomicWrite(target, contents) {
+    const dir = dirname(target);
+    const tmp = join(dir, `.${basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(tmp, contents, "utf8");
+    await fs.rename(tmp, target);
+}
+export async function ensureBackup(target) {
+    if (!existsSync(target))
+        return null;
+    const bak = `${target}.bak-${Date.now()}`;
+    const contents = await fs.readFile(target, "utf8");
+    await fs.writeFile(bak, contents, "utf8");
+    return bak;
+}
+export function unifiedDiff(oldText, newText, label) {
+    return createPatch(label, oldText, newText, "", "", { context: 3 });
+}

package/build/install/config-io.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, readdirSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { atomicWrite, ensureBackup, unifiedDiff } from "./config-io.js";
+describe("config-io", () => {
+    let dir;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "drawio-install-"));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("atomicWrite writes contents and leaves no tmp file", async () => {
+        const target = join(dir, "cfg.json");
+        await atomicWrite(target, '{\n  "a": 1\n}\n');
+        expect(readFileSync(target, "utf8")).toBe('{\n  "a": 1\n}\n');
+        expect(readdirSync(dir).filter((f) => f.startsWith(".cfg.json."))).toEqual([]);
+    });
+    it("ensureBackup copies once and returns backup path", async () => {
+        const target = join(dir, "cfg.json");
+        writeFileSync(target, "orig");
+        const bak = await ensureBackup(target);
+        expect(bak).toMatch(/cfg\.json\.bak-\d+$/);
+        expect(readFileSync(bak, "utf8")).toBe("orig");
+    });
+    it("ensureBackup returns null when file missing", async () => {
+        expect(await ensureBackup(join(dir, "nope.json"))).toBeNull();
+    });
+    it("unifiedDiff produces a diff header referencing the label", () => {
+        const d = unifiedDiff("a\n", "b\n", "cfg.json");
+        expect(d).toContain("--- cfg.json");
+        expect(d).toContain("+++ cfg.json");
+        expect(d).toContain("-a");
+        expect(d).toContain("+b");
+    });
+});

package/build/install/hosts/claude-code.js

@@ -0,0 +1,37 @@
+import { existsSync, promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { applyEdits, modify } from "jsonc-parser";
+export const claudeCodeAdapter = {
+    id: "claude-code",
+    displayName: "Claude Code (user scope)",
+    defaultPaths() {
+        return [join(homedir(), ".claude.json")];
+    },
+    async detect() {
+        return existsSync(claudeCodeAdapter.defaultPaths()[0])
+            ? "installed"
+            : "absent";
+    },
+    async read(path) {
+        return existsSync(path) ? fs.readFile(path, "utf8") : "";
+    },
+    merge(source, entry, name, { uninstall }) {
+        const text = source.trim() === "" ? "{}\n" : source;
+        const value = uninstall
+            ? undefined
+            : {
+                type: entry.transport,
+                command: entry.command,
+                args: entry.args,
+                ...(Object.keys(entry.env).length ? { env: entry.env } : {}),
+            };
+        const edits = modify(text, ["mcpServers", name], value, {
+            formattingOptions: { insertSpaces: true, tabSize: 2 },
+        });
+        return applyEdits(text, edits);
+    },
+    diffLabel() {
+        return claudeCodeAdapter.defaultPaths()[0];
+    },
+};

package/build/install/hosts/claude-code.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "@jest/globals";
+import { claudeCodeAdapter } from "./claude-code.js";
+const ENTRY = {
+    command: "npx",
+    args: ["-y", "drawio-mcp-server", "--editor"],
+    env: {},
+    transport: "stdio",
+};
+describe("claudeCodeAdapter.merge", () => {
+    it("adds mcpServers.drawio to a fresh file", () => {
+        const out = claudeCodeAdapter.merge("", ENTRY, "drawio", {
+            uninstall: false,
+        });
+        const parsed = JSON.parse(out);
+        expect(parsed.mcpServers.drawio).toEqual({
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "drawio-mcp-server", "--editor"],
+        });
+    });
+    it("uninstall removes only that key", () => {
+        const source = JSON.stringify({
+            mcpServers: {
+                drawio: { type: "stdio", command: "old" },
+                other: { command: "x" },
+            },
+        });
+        const out = claudeCodeAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: true,
+        });
+        const parsed = JSON.parse(out);
+        expect(parsed.mcpServers.drawio).toBeUndefined();
+        expect(parsed.mcpServers.other).toEqual({ command: "x" });
+    });
+    it("preserves unrelated top-level keys", () => {
+        const source = JSON.stringify({ projects: { "/tmp": {} }, mcpServers: {} }, null, 2);
+        const out = claudeCodeAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: false,
+        });
+        expect(JSON.parse(out).projects).toEqual({ "/tmp": {} });
+    });
+});
+describe("claudeCodeAdapter.defaultPaths", () => {
+    it("points at ~/.claude.json", () => {
+        expect(claudeCodeAdapter.defaultPaths()[0]).toMatch(/\.claude\.json$/);
+    });
+});

package/build/install/hosts/claude-desktop.js

@@ -0,0 +1,45 @@
+import { existsSync, promises as fs } from "node:fs";
+import { homedir, platform } from "node:os";
+import { posix, win32 } from "node:path";
+import { applyEdits, modify } from "jsonc-parser";
+export function resolveClaudeDesktopPath(plat, home, env) {
+    if (plat === "darwin")
+        return posix.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    if (plat === "win32") {
+        const appdata = env.APPDATA ?? win32.join(home, "AppData", "Roaming");
+        return win32.join(appdata, "Claude", "claude_desktop_config.json");
+    }
+    return posix.join(home, ".config", "Claude", "claude_desktop_config.json");
+}
+export const claudeDesktopAdapter = {
+    id: "claude-desktop",
+    displayName: "Claude Desktop",
+    defaultPaths() {
+        return [resolveClaudeDesktopPath(platform(), homedir(), process.env)];
+    },
+    async detect() {
+        return existsSync(claudeDesktopAdapter.defaultPaths()[0])
+            ? "installed"
+            : "absent";
+    },
+    async read(path) {
+        return existsSync(path) ? fs.readFile(path, "utf8") : "";
+    },
+    merge(source, entry, name, { uninstall }) {
+        const text = source.trim() === "" ? "{}\n" : source;
+        const value = uninstall
+            ? undefined
+            : {
+                command: entry.command,
+                args: entry.args,
+                ...(Object.keys(entry.env).length ? { env: entry.env } : {}),
+            };
+        const edits = modify(text, ["mcpServers", name], value, {
+            formattingOptions: { insertSpaces: true, tabSize: 2 },
+        });
+        return applyEdits(text, edits);
+    },
+    diffLabel() {
+        return claudeDesktopAdapter.defaultPaths()[0];
+    },
+};

package/build/install/hosts/claude-desktop.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "@jest/globals";
+import { claudeDesktopAdapter, resolveClaudeDesktopPath, } from "./claude-desktop.js";
+const ENTRY = {
+    command: "npx",
+    args: ["-y", "drawio-mcp-server", "--editor"],
+    env: {},
+    transport: "stdio",
+};
+describe("claudeDesktopAdapter.merge", () => {
+    it("adds mcpServers.drawio", () => {
+        const out = claudeDesktopAdapter.merge("", ENTRY, "drawio", {
+            uninstall: false,
+        });
+        const parsed = JSON.parse(out);
+        expect(parsed.mcpServers.drawio).toEqual({
+            command: "npx",
+            args: ["-y", "drawio-mcp-server", "--editor"],
+        });
+    });
+    it("preserves comments in jsonc source", () => {
+        const source = [
+            "{",
+            "  // pinned by me",
+            '  "mcpServers": {',
+            '    "other": { "command": "x" }',
+            "  }",
+            "}",
+        ].join("\n");
+        const out = claudeDesktopAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: false,
+        });
+        expect(out).toContain("// pinned by me");
+        expect(out).toContain('"drawio"');
+    });
+    it("uninstall removes the entry", () => {
+        const source = JSON.stringify({
+            mcpServers: { drawio: { command: "old" } },
+        });
+        const out = claudeDesktopAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: true,
+        });
+        expect(JSON.parse(out).mcpServers).toEqual({});
+    });
+});
+describe("resolveClaudeDesktopPath", () => {
+    it("darwin uses Application Support", () => {
+        expect(resolveClaudeDesktopPath("darwin", "/Users/me", {})).toMatch(/Library\/Application Support\/Claude\/claude_desktop_config\.json$/);
+    });
+    it("win32 uses APPDATA when set", () => {
+        expect(resolveClaudeDesktopPath("win32", "C:\\Users\\me", {
+            APPDATA: "C:\\Users\\me\\AppData\\Roaming",
+        })).toMatch(/AppData\\Roaming\\Claude\\claude_desktop_config\.json$/);
+    });
+    it("linux uses ~/.config/Claude", () => {
+        expect(resolveClaudeDesktopPath("linux", "/home/me", {})).toBe("/home/me/.config/Claude/claude_desktop_config.json");
+    });
+});