drawio-mcp-server 1.4.0 → 1.5.0

package/README.md

@@ -71,6 +71,49 @@ The server listens on port 3333 by default for WebSocket connections from the br
 
 **Note**: When using a custom port, ensure the browser extension is configured to connect to the same port.
 
+### HTTP Transport Port
+
+The server can expose a streamable HTTP MCP transport on port 3000. Change this using the `--http-port` flag:
+
+```json
+{
+  "mcpServers": {
+    "drawio": {
+      "command": "npx",
+      "args": ["-y", "drawio-mcp-server", "--transport", "http", "--http-port", "4000"]
+    }
+  }
+}
+```
+
+### Transport Selection
+
+By default only the stdio transport starts. Limit or combine transports with the `--transport` flag:
+
+- `--transport stdio` – start only stdio (CLI-friendly)
+- `--transport http` – start only the HTTP transport (for remote clients)
+- `--transport stdio,http` – start both transports
+
+### Running the streamable HTTP transport
+
+Use the streamable HTTP transport when you need to reach the MCP server over the network (for example from a remote agent runtime). The Draw.io browser extension is still required, and you must opt in to the HTTP transport.
+
+1. Start the server with HTTP enabled (optionally alongside stdio):
+
+```sh
+npx -y drawio-mcp-server --transport http --http-port 3000
+# or both: npx -y drawio-mcp-server --transport stdio,http --http-port 4000
+```
+
+2. Verify the health endpoint:
+
+```sh
+curl http://localhost:3000/health
+# { "status": "ok" }
+```
+
+3. Point your MCP client to the `/mcp` endpoint (`http://localhost:3000/mcp` by default). CORS is enabled for all origins so you can call it from a browser-based client as well.
+
 ## Installation
 
 ### Connecting with Claude Desktop
@@ -254,6 +297,61 @@ To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to
 }
 ```
 
+### Connecting with Codex
+
+Edit the configuration usually located in: ~/.codex/config.toml
+
+<details>
+  <summary>Using <code>npm</code></summary>
+
+```toml
+[mcp_servers.drawio]
+command = "npx"
+args = [
+    "-y",
+    "drawio-mcp-server"
+]
+```
+</details>
+
+<details>
+  <summary>Using <code>pnpm</code></summary>
+
+```toml
+[mcp_servers.drawio]
+command = "pnpm"
+args = [
+    "dlx",
+    "drawio-mcp-server"
+]
+```
+</details>
+
+To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+
+<details>
+  <summary>Using <code>npm</code></summary>
+
+```toml
+[mcp_servers.drawio]
+command = "npx"
+args = [
+    "-y",
+    "drawio-mcp-server",
+    "--extension-port",
+    "8080"
+]
+```
+</details>
+
+To connect to a locally running MCP with Streamable HTTP transport:
+
+```toml
+[mcp_servers.drawio]
+url = "http://localhost:3000/mcp"
+```
+
+
 ### Browser Extension Setup
 
 In order to control the Draw.io diagram, you need to install dedicated Browser Extension.

package/build/config.js

@@ -3,6 +3,8 @@
  */
 const DEFAULT_CONFIG = {
     extensionPort: 3333,
+    httpPort: 3000,
+    transports: ["stdio"],
 };
 /**
  * Valid port range
@@ -27,6 +29,45 @@ export const parseExtensionPortValue = (value) => {
     }
     return port;
 };
+/**
+ * Parse http port value from string - pure function
+ */
+export const parseHttpPortValue = (value) => {
+    if (!value) {
+        return new Error("--http-port flag requires a port number");
+    }
+    const port = parseInt(value, 10);
+    if (isNaN(port)) {
+        return new Error(`Invalid port number "${value}". Port must be a number`);
+    }
+    if (port < PORT_RANGE.min || port > PORT_RANGE.max) {
+        return new Error(`Invalid port number "${value}". Port must be between ${PORT_RANGE.min} and ${PORT_RANGE.max}`);
+    }
+    return port;
+};
+export const parseTransports = (values) => {
+    if (!values || values.length === 0) {
+        return DEFAULT_CONFIG.transports;
+    }
+    const normalized = values
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim().toLowerCase())
+        .filter((value) => value.length > 0);
+    if (normalized.length === 0) {
+        return new Error("At least one transport must be specified");
+    }
+    const validTransports = [];
+    for (const value of normalized) {
+        if (value === "stdio" || value === "http") {
+            validTransports.push(value);
+        }
+        else {
+            return new Error(`Invalid transport "${value}". Supported transports: stdio, http`);
+        }
+    }
+    // Remove duplicates while preserving order
+    return Array.from(new Set(validTransports));
+};
 /**
  * Find argument value by flag name - pure function
  */
@@ -53,6 +94,9 @@ export const shouldShowHelp = (args) => {
 export const parseConfig = (args) => {
     // Walk arguments so repeated flags allow "last wins" semantics
     let portValue;
+    let httpPortValue;
+    let parsedHttpPort;
+    let transportValues;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--extension-port" || arg === "-p") {
@@ -63,19 +107,66 @@ export const parseConfig = (args) => {
             portValue = nextValue;
             i += 1; // Skip the value we just consumed
         }
+        else if (arg === "--http-port") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--http-port flag requires a port number");
+            }
+            httpPortValue = nextValue;
+            i += 1;
+        }
+        else if (arg === "--transport") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--transport flag requires a transport name");
+            }
+            transportValues = [nextValue];
+            i += 1;
+        }
+    }
+    if (httpPortValue !== undefined) {
+        const httpPort = parseHttpPortValue(httpPortValue);
+        if (httpPort instanceof Error) {
+            return httpPort;
+        }
+        parsedHttpPort = httpPort;
     }
     if (portValue !== undefined) {
         const extensionPort = parseExtensionPortValue(portValue);
         if (extensionPort instanceof Error) {
             return extensionPort;
         }
+        const transports = parseTransports(transportValues);
+        if (transports instanceof Error) {
+            return transports;
+        }
         return {
             ...DEFAULT_CONFIG,
             extensionPort,
+            httpPort: parsedHttpPort !== undefined ? parsedHttpPort : DEFAULT_CONFIG.httpPort,
+            transports,
         };
     }
+    if (httpPortValue !== undefined) {
+        const transports = parseTransports(transportValues);
+        if (transports instanceof Error) {
+            return transports;
+        }
+        return {
+            ...DEFAULT_CONFIG,
+            httpPort: parsedHttpPort,
+            transports,
+        };
+    }
+    const transports = parseTransports(transportValues);
+    if (transports instanceof Error) {
+        return transports;
+    }
     // Return default configuration
-    return DEFAULT_CONFIG;
+    return {
+        ...DEFAULT_CONFIG,
+        transports,
+    };
 };
 /**
  * Build configuration from process.argv

package/build/config.test.js

@@ -1,4 +1,4 @@
-import { parseExtensionPortValue, findArgValue, hasFlag, shouldShowHelp, parseConfig, buildConfig, } from "./config.js";
+import { parseExtensionPortValue, parseHttpPortValue, findArgValue, hasFlag, shouldShowHelp, parseConfig, buildConfig, parseTransports, } from "./config.js";
 describe("parseExtensionPortValue", () => {
     test("valid port returns number", () => {
         expect(parseExtensionPortValue("8080")).toBe(8080);
@@ -22,6 +22,42 @@ describe("parseExtensionPortValue", () => {
         expect(parseExtensionPortValue("65535")).toBe(65535);
     });
 });
+describe("parseHttpPortValue", () => {
+    test("valid port returns number", () => {
+        expect(parseHttpPortValue("3000")).toBe(3000);
+    });
+    test("undefined input returns Error", () => {
+        expect(parseHttpPortValue(undefined)).toBeInstanceOf(Error);
+    });
+    test("non-numeric string returns Error", () => {
+        expect(parseHttpPortValue("abc")).toBeInstanceOf(Error);
+    });
+    test("out of range returns Error", () => {
+        expect(parseHttpPortValue("70000")).toBeInstanceOf(Error);
+    });
+});
+describe("parseTransports", () => {
+    test("returns default when undefined", () => {
+        expect(parseTransports(undefined)).toEqual(["stdio"]);
+    });
+    test("parses single transport", () => {
+        expect(parseTransports(["stdio"])).toEqual(["stdio"]);
+    });
+    test("parses comma separated list", () => {
+        expect(parseTransports(["stdio,http"])).toEqual(["stdio", "http"]);
+    });
+    test("deduplicates transports", () => {
+        expect(parseTransports(["stdio", "stdio"])).toEqual(["stdio"]);
+    });
+    test("rejects empty string", () => {
+        const result = parseTransports([""]);
+        expect(result).toBeInstanceOf(Error);
+    });
+    test("rejects unknown transport", () => {
+        const result = parseTransports(["foo"]);
+        expect(result).toBeInstanceOf(Error);
+    });
+});
 describe("findArgValue", () => {
     test("finds value after flag", () => {
         expect(findArgValue(["--port", "8080", "--help"], "--port")).toBe("8080");
@@ -74,18 +110,46 @@ describe("shouldShowHelp", () => {
 });
 describe("parseConfig", () => {
     test("no args returns default config", () => {
-        expect(parseConfig([])).toEqual({ extensionPort: 3333 });
+        expect(parseConfig([])).toEqual({
+            extensionPort: 3333,
+            httpPort: 3000,
+            transports: ["stdio"],
+        });
     });
     test("--extension-port flag sets custom port", () => {
         expect(parseConfig(["--extension-port", "8080"])).toEqual({
             extensionPort: 8080,
+            httpPort: 3000,
+            transports: ["stdio"],
         });
     });
     test("-p flag sets custom port", () => {
-        expect(parseConfig(["-p", "8080"])).toEqual({ extensionPort: 8080 });
+        expect(parseConfig(["-p", "8080"])).toEqual({
+            extensionPort: 8080,
+            httpPort: 3000,
+            transports: ["stdio"],
+        });
+    });
+    test("--http-port flag sets custom port", () => {
+        expect(parseConfig(["--http-port", "4242"])).toEqual({
+            extensionPort: 3333,
+            httpPort: 4242,
+            transports: ["stdio"],
+        });
+    });
+    test("both ports can be configured", () => {
+        expect(parseConfig(["--extension-port", "8080", "--http-port", "4242"])).toEqual({
+            extensionPort: 8080,
+            httpPort: 4242,
+            transports: ["stdio"],
+        });
     });
     test("help flag is ignored in config parsing", () => {
-        expect(parseConfig(["--help"])).toEqual({ extensionPort: 3333 });
+        expect(parseConfig(["--help"])).toEqual({
+            extensionPort: 3333,
+            httpPort: 3000,
+            transports: ["stdio"],
+        });
     });
     test("invalid port returns Error", () => {
         const result = parseConfig(["--extension-port", "abc"]);
@@ -97,6 +161,11 @@ describe("parseConfig", () => {
         expect(result).toBeInstanceOf(Error);
         expect(result.message).toContain("--extension-port flag requires a port number");
     });
+    test("missing http port value returns Error", () => {
+        const result = parseConfig(["--http-port"]);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("--http-port flag requires a port number");
+    });
     test("out of range port returns Error", () => {
         const result = parseConfig(["--extension-port", "70000"]);
         expect(result).toBeInstanceOf(Error);
@@ -105,13 +174,42 @@ describe("parseConfig", () => {
     test("multiple --extension-port flags uses last one", () => {
         expect(parseConfig(["--extension-port", "8080", "--extension-port", "9090"])).toEqual({
             extensionPort: 9090,
+            httpPort: 3000,
+            transports: ["stdio"],
         });
     });
     test("short and long form both work, last wins", () => {
         expect(parseConfig(["--extension-port", "8080", "-p", "9090"])).toEqual({
             extensionPort: 9090,
+            httpPort: 3000,
+            transports: ["stdio"],
+        });
+    });
+    test("last http-port flag wins", () => {
+        expect(parseConfig(["--http-port", "4000", "--http-port", "5000"])).toEqual({
+            extensionPort: 3333,
+            httpPort: 5000,
+            transports: ["stdio"],
+        });
+    });
+    test("sets single transport", () => {
+        expect(parseConfig(["--transport", "stdio"])).toEqual({
+            extensionPort: 3333,
+            httpPort: 3000,
+            transports: ["stdio"],
         });
     });
+    test("sets multiple transports", () => {
+        expect(parseConfig(["--transport", "stdio,http"])).toEqual({
+            extensionPort: 3333,
+            httpPort: 3000,
+            transports: ["stdio", "http"],
+        });
+    });
+    test("rejects unknown transport", () => {
+        const result = parseConfig(["--transport", "foo"]);
+        expect(result).toBeInstanceOf(Error);
+    });
 });
 describe("buildConfig", () => {
     const originalArgv = process.argv;
@@ -121,12 +219,29 @@ describe("buildConfig", () => {
     test("uses default config with empty args", () => {
         process.argv = ["node", "script.js"];
         const result = buildConfig();
-        expect(result).toEqual({ extensionPort: 3333 });
+        expect(result).toEqual({
+            extensionPort: 3333,
+            httpPort: 3000,
+            transports: ["stdio"],
+        });
     });
     test("parses custom port from argv", () => {
         process.argv = ["node", "script.js", "--extension-port", "8080"];
         const result = buildConfig();
-        expect(result).toEqual({ extensionPort: 8080 });
+        expect(result).toEqual({
+            extensionPort: 8080,
+            httpPort: 3000,
+            transports: ["stdio"],
+        });
+    });
+    test("parses custom http port from argv", () => {
+        process.argv = ["node", "script.js", "--http-port", "4242"];
+        const result = buildConfig();
+        expect(result).toEqual({
+            extensionPort: 3333,
+            httpPort: 4242,
+            transports: ["stdio"],
+        });
     });
     test("returns Error for invalid config", () => {
         process.argv = ["node", "script.js", "--extension-port", "abc"];

package/build/index.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { serve } from "@hono/node-server";
 import { z } from "zod";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
 import EventEmitter from "node:events";
 import { createServer } from "node:net";
-import uWS from "uWebSockets.js";
+import { WebSocket, WebSocketServer } from "ws";
 import { buildConfig, shouldShowHelp } from "./config.js";
 import { bus_reply_stream, bus_request_stream, } from "./types.js";
 import { create_bus } from "./emitter_bus.js";
@@ -43,58 +47,63 @@ async function checkPortAvailable(port) {
     });
 }
 const emitter = new EventEmitter();
-const conns = [];
+const conns = new Set();
 const bus_to_ws_forwarder_listener = (event) => {
-    log.debug(`[bridge] received; forwarding message to #${conns.length} clients`, event);
-    for (let i = 0; i < conns.length; i++) {
+    log.debug(`[bridge] received; forwarding message to #${conns.size} clients`, event);
+    for (const ws of [...conns]) {
+        if (ws.readyState !== WebSocket.OPEN) {
+            conns.delete(ws);
+            continue;
+        }
         try {
-            conns[i].send(JSON.stringify(event));
+            ws.send(JSON.stringify(event));
         }
         catch (e) {
-            log.debug(`[bridge] error forwarding request at conn = ${i}`);
+            log.debug("[bridge] error forwarding request", e);
+            conns.delete(ws);
         }
     }
 };
 emitter.on(bus_request_stream, bus_to_ws_forwarder_listener);
-const ws_handler = {
-    maxPayloadLength: 128 * 1024,
-    open: (ws) => {
-        log.debug(`[ws_handler] A WebSocket client #${conns.length} connected, presumably MCP Extension!`);
-        conns.push(ws);
-    },
-    message: (ws, message, isBinary) => {
-        // ws.send(message, isBinary);
-        const decoder = new TextDecoder();
-        const str = decoder.decode(message);
-        const json = JSON.parse(str);
-        log.debug(`[ws] received from Extension`, json);
-        // const event_name = message.__event;
-        emitter.emit(bus_reply_stream, json);
-    },
-    close: (ws, code, message) => {
-        log.debug(`[ws_handler] WebSocket client closed with code ${code}`);
-        //todo remove conn
-    },
-};
 async function start_websocket_server(extensionPort) {
+    log.debug(`Draw.io MCP Server starting (WebSocket extension port: ${extensionPort})`);
     const isPortAvailable = await checkPortAvailable(extensionPort);
     if (!isPortAvailable) {
         console.error(`[start_websocket_server] Error: Port ${extensionPort} is already in use. Please stop the process using this port and try again.`);
         process.exit(1);
     }
-    const app = uWS
-        .App()
-        .ws("/*", ws_handler)
-        .listen(extensionPort, (token) => {
-        if (token) {
-            log.debug(`[start_websocket_server] Listening to port ${extensionPort}`);
-        }
-        else {
-            console.error(`[start_websocket_server] Error: Failed to listen on port ${extensionPort}`);
-            process.exit(1);
-        }
+    const server = new WebSocketServer({ port: extensionPort });
+    server.on("connection", (ws) => {
+        log.debug(`[ws_handler] A WebSocket client #${conns.size} connected, presumably MCP Extension!`);
+        conns.add(ws);
+        ws.on("message", (data) => {
+            const str = typeof data === "string" ? data : data.toString();
+            try {
+                const json = JSON.parse(str);
+                log.debug(`[ws] received from Extension`, json);
+                emitter.emit(bus_reply_stream, json);
+            }
+            catch (error) {
+                log.debug(`[ws] failed to parse message`, error);
+            }
+        });
+        ws.on("close", (code) => {
+            conns.delete(ws);
+            log.debug(`[ws_handler] WebSocket client closed with code ${code}`);
+        });
+        ws.on("error", (error) => {
+            log.debug(`[ws_handler] WebSocket client error`, error);
+            conns.delete(ws);
+        });
+    });
+    server.on("listening", () => {
+        log.debug(`[start_websocket_server] Listening to port ${extensionPort}`);
+    });
+    server.on("error", (error) => {
+        console.error(`[start_websocket_server] Error: Failed to listen on port ${extensionPort}`, error);
+        process.exit(1);
     });
-    return app;
+    return server;
 }
 const logger_type = process.env.LOGGER_TYPE;
 let capabilities = {
@@ -303,7 +312,8 @@ const Attributes = z.lazy(() => z
 ]))
     .refine((arr) => arr.length === 0 || typeof arr[0] === "string", {
     message: "If not empty, the first element must be a string operator",
-}));
+})
+    .default([]));
 const TOOL_list_paged_model = "list-paged-model";
 server.tool(TOOL_list_paged_model, "Retrieves a paginated view of all cells (vertices and edges) in the current Draw.io diagram. This tool provides access to the complete model data with essential fields only, sanitized to remove circular dependencies and excessive data. It allows to filter based on multiple criteria and attribute boolean logic. Useful for programmatic inspection of diagram structure without overwhelming response sizes.", {
     page: z
@@ -322,14 +332,45 @@ server.tool(TOOL_list_paged_model, "Retrieves a paginated view of all cells (ver
             .enum(["edge", "vertex", "object", "layer", "group"])
             .optional()
             .describe("Filter by cell type: 'edge' for connection lines, 'vertex' for vertices/shapes, 'object' for any cell type, 'layer' for layer cells, 'group' for grouped cells"),
-        attributes: Attributes.optional()
-            .describe('Boolean logic array expressions for filtering cell attributes. Format: ["and" | "or", ...expressions] or ["equal", key, value]. Matches against cell attributes and parsed style properties.')
-            .default([]),
+        attributes: Attributes.optional().describe('Boolean logic array expressions for filtering cell attributes. Format: ["and" | "or", ...expressions] or ["equal", key, value]. Matches against cell attributes and parsed style properties.'),
     })
         .optional()
         .describe("Optional filter criteria to apply to cells before pagination")
         .default({}),
 }, default_tool(TOOL_list_paged_model, context));
+async function start_stdio_transport() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log.debug(`Draw.io MCP Server STDIO transport active`);
+}
+async function start_streamable_http_transport(http_port) {
+    // Create a stateless transport (no options = no session management)
+    const transport = new WebStandardStreamableHTTPServerTransport();
+    // Create the Hono app
+    const app = new Hono();
+    // Enable CORS for all origins
+    app.use("*", cors({
+        origin: "*",
+        allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
+        allowHeaders: [
+            "Content-Type",
+            "mcp-session-id",
+            "Last-Event-ID",
+            "mcp-protocol-version",
+        ],
+        exposeHeaders: ["mcp-session-id", "mcp-protocol-version"],
+    }));
+    app.get("/health", (c) => c.json({ status: server.isConnected() ? "ok" : "mcp not ready" }));
+    app.all("/mcp", (c) => transport.handleRequest(c.req.raw));
+    await server.connect(transport);
+    serve({
+        fetch: app.fetch,
+        port: http_port,
+    });
+    log.debug(`Draw.io MCP Server Streamable HTTP transport active`);
+    log.debug(`Health check: http://localhost:${http_port}/health`);
+    log.debug(`MCP endpoint: http://localhost:${http_port}/mcp`);
+}
 async function main() {
     // Check if help was requested (before parsing config)
     if (shouldShowHelp(process.argv.slice(2))) {
@@ -344,12 +385,14 @@ async function main() {
         process.exit(1);
     }
     const config = configResult;
-    log.debug(`Draw.io MCP Server starting (WebSocket extension port: ${config.extensionPort})`);
     await start_websocket_server(config.extensionPort);
-    log.debug(`Draw.io MCP Server WebSocket started on extension port ${config.extensionPort}`);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    log.debug("Draw.io MCP Server running on stdio");
+    if (config.transports.indexOf("stdio") > -1) {
+        await start_stdio_transport();
+    }
+    if (config.transports.indexOf("http") > -1) {
+        start_streamable_http_transport(config.httpPort);
+    }
+    log.debug(`Draw.io MCP Server running on ${config.transports}`);
 }
 main().catch((error) => {
     log.debug("Fatal error in main():", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drawio-mcp-server",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Provides Draw.io services to MCP Clients",
   "type": "module",
   "main": "index.js",
@@ -27,22 +27,25 @@
   "author": "Ladislav Gazo",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.17.5",
-    "nanoid": "5.1.5",
-    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.52.0",
-    "zod": "3.24.3"
+    "@hono/node-server": "1.19.7",
+    "@modelcontextprotocol/sdk": "1.25.1",
+    "hono": "4.11.1",
+    "nanoid": "5.1.6",
+    "ws": "8.18.3",
+    "zod": "4.2.1"
   },
   "devDependencies": {
-    "@jest/globals": "30.1.2",
+    "@jest/globals": "30.2.0",
     "@types/jest": "30.0.0",
-    "@types/node": "24.3.1",
-    "globals": "16.3.0",
-    "jest": "30.1.3",
-    "jest-environment-node": "30.1.2",
-    "prettier": "3.5.3",
-    "rimraf": "6.0.1",
-    "ts-jest": "29.4.1",
-    "typescript": "5.9.2"
+    "@types/node": "25.0.3",
+    "@types/ws": "^8.18.1",
+    "globals": "16.5.0",
+    "jest": "30.2.0",
+    "jest-environment-node": "30.2.0",
+    "prettier": "3.7.4",
+    "rimraf": "6.1.2",
+    "ts-jest": "29.4.6",
+    "typescript": "5.9.3"
   },
   "scripts": {
     "build": "tsc",