drawio-mcp-server 1.3.0 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Let's do some Vibe Diagramming with the most wide-spread diagramming tool called Draw.io (Diagrams.net).
 
-[![Build project](https://github.com/lgazo/drawio-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/lgazo/drawio-mcp-server/actions/workflows/ci.yml)
+[![Discord channel](https://shields.io/static/v1?logo=discord&message=draw.io%20mcp&label=chat&color=5865F2&logoColor=white)](https://discord.gg/dM4PWdf42q) [![Build project](https://github.com/lgazo/drawio-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/lgazo/drawio-mcp-server/actions/workflows/ci.yml)
 
 ## Introduction
 
@@ -39,6 +39,38 @@ To use the Draw.io MCP server, you'll need:
 
 Note: The Draw.io desktop app or web version must be accessible to the system where the MCP server runs.
 
+## Configuration
+
+### WebSocket Port
+
+The server listens on port 3333 by default for WebSocket connections from the browser extension. You can customize this port using the `--extension-port` or `-p` flag.
+
+**Default behavior** (port 3333):
+```json
+{
+  "mcpServers": {
+    "drawio": {
+      "command": "npx",
+      "args": ["-y", "drawio-mcp-server"]
+    }
+  }
+}
+```
+
+**Custom port** (e.g., port 8080):
+```json
+{
+  "mcpServers": {
+    "drawio": {
+      "command": "npx",
+      "args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
+    }
+  }
+}
+```
+
+**Note**: When using a custom port, ensure the browser extension is configured to connect to the same port.
+
 ## Installation
 
 ### Connecting with Claude Desktop
@@ -86,6 +118,19 @@ Note: The Draw.io desktop app or web version must be accessible to the system wh
 ```
 </details>
 
+To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+
+```json
+{
+  "mcpServers": {
+    "drawio": {
+      "command": "npx",
+      "args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
+    }
+  }
+}
+```
+
 4. Restart Claude Desktop
 
 ### Connecting with oterm
@@ -130,6 +175,19 @@ The configuration is usually in: ~/.local/share/oterm/config.json
 ```
 </details>
 
+To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+
+```json
+{
+  "mcpServers": {
+    "drawio": {
+      "command": "npx",
+      "args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
+    }
+  }
+}
+```
+
 ### Connect with Zed
 
 1. Open the Zed Preview application.
@@ -178,6 +236,24 @@ The configuration is usually in: ~/.local/share/oterm/config.json
 ```
 </details>
 
+To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+
+```json
+{
+  /// The name of your MCP server
+  "drawio": {
+    "command": {
+      /// The path to the executable
+      "path": "npx",
+      /// The arguments to pass to the executable
+      "args": ["-y","drawio-mcp-server","--extension-port","8080"],
+      /// The environment variables to set for the executable
+      "env": {}
+    }
+  }
+}
+```
+
 ### Browser Extension Setup
 
 In order to control the Draw.io diagram, you need to install dedicated Browser Extension.
@@ -198,6 +274,8 @@ In order to control the Draw.io diagram, you need to install dedicated Browser E
 </p>
 3. Ensure it is connected, the Extension icon should indicate green signal overlay <img alt="Extension connected" src="https://raw.githubusercontent.com/lgazo/drawio-mcp-extension/refs/heads/main/public/icon/logo_connected_32.png" />
 
+**Important**: If you configured the MCP server to use a custom port (not 3333), you must configure the browser extension to use the same port. See the extension documentation for port configuration instructions.
+
 
 ## Sponsoring
 

package/build/config.js

@@ -0,0 +1,88 @@
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+    extensionPort: 3333,
+};
+/**
+ * Valid port range
+ */
+const PORT_RANGE = {
+    min: 1,
+    max: 65535,
+};
+/**
+ * Parse extension port value from string - pure function
+ */
+export const parseExtensionPortValue = (value) => {
+    if (!value) {
+        return new Error("--extension-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;
+};
+/**
+ * Find argument value by flag name - pure function
+ */
+export const findArgValue = (args, ...flags) => {
+    const index = args.findIndex((arg) => flags.includes(arg));
+    return index !== -1 ? args[index + 1] : undefined;
+};
+/**
+ * Check if any flag exists in arguments - pure function
+ */
+export const hasFlag = (args, ...flags) => {
+    return args.some((arg) => flags.includes(arg));
+};
+/**
+ * Check if help was requested - pure function
+ */
+export const shouldShowHelp = (args) => {
+    return hasFlag(args, "--help", "-h");
+};
+/**
+ * Parse command line arguments into configuration object
+ * Pure function - no side effects, deterministic output
+ */
+export const parseConfig = (args) => {
+    // Walk arguments so repeated flags allow "last wins" semantics
+    let portValue;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--extension-port" || arg === "-p") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--extension-port flag requires a port number");
+            }
+            portValue = nextValue;
+            i += 1; // Skip the value we just consumed
+        }
+    }
+    if (portValue !== undefined) {
+        const extensionPort = parseExtensionPortValue(portValue);
+        if (extensionPort instanceof Error) {
+            return extensionPort;
+        }
+        return {
+            ...DEFAULT_CONFIG,
+            extensionPort,
+        };
+    }
+    // Return default configuration
+    return DEFAULT_CONFIG;
+};
+/**
+ * Build configuration from process.argv
+ * This is the main entry point for configuration
+ * Returns Error for invalid config, or ServerConfig
+ */
+export const buildConfig = () => {
+    const args = process.argv.slice(2);
+    return parseConfig(args);
+};

package/build/config.test.js

@@ -0,0 +1,136 @@
+import { parseExtensionPortValue, findArgValue, hasFlag, shouldShowHelp, parseConfig, buildConfig, } from "./config.js";
+describe("parseExtensionPortValue", () => {
+    test("valid port returns number", () => {
+        expect(parseExtensionPortValue("8080")).toBe(8080);
+    });
+    test("undefined input returns Error", () => {
+        expect(parseExtensionPortValue(undefined)).toBeInstanceOf(Error);
+    });
+    test("non-numeric string returns Error", () => {
+        expect(parseExtensionPortValue("abc")).toBeInstanceOf(Error);
+    });
+    test("out of range (too low) returns Error", () => {
+        expect(parseExtensionPortValue("0")).toBeInstanceOf(Error);
+    });
+    test("out of range (too high) returns Error", () => {
+        expect(parseExtensionPortValue("70000")).toBeInstanceOf(Error);
+    });
+    test("port 1 is valid", () => {
+        expect(parseExtensionPortValue("1")).toBe(1);
+    });
+    test("port 65535 is valid", () => {
+        expect(parseExtensionPortValue("65535")).toBe(65535);
+    });
+});
+describe("findArgValue", () => {
+    test("finds value after flag", () => {
+        expect(findArgValue(["--port", "8080", "--help"], "--port")).toBe("8080");
+    });
+    test("returns undefined when flag not found", () => {
+        expect(findArgValue(["--help"], "--port")).toBeUndefined();
+    });
+    test("returns undefined when flag is last argument", () => {
+        expect(findArgValue(["--port"], "--port")).toBeUndefined();
+    });
+    test("finds value with short flag", () => {
+        expect(findArgValue(["-p", "8080"], "-p")).toBe("8080");
+    });
+    test("works with readonly array", () => {
+        const args = ["--port", "8080"];
+        expect(findArgValue(args, "--port")).toBe("8080");
+    });
+});
+describe("hasFlag", () => {
+    test("returns true when flag exists", () => {
+        expect(hasFlag(["--help", "--port", "8080"], "--help")).toBe(true);
+    });
+    test("returns false when flag does not exist", () => {
+        expect(hasFlag(["--port", "8080"], "--help")).toBe(false);
+    });
+    test("returns true with short flag", () => {
+        expect(hasFlag(["-h"], "-h")).toBe(true);
+    });
+    test("works with multiple flags", () => {
+        expect(hasFlag(["-h"], "-h", "--help")).toBe(true);
+    });
+    test("works with readonly array", () => {
+        const args = ["--help"];
+        expect(hasFlag(args, "--help")).toBe(true);
+    });
+});
+describe("shouldShowHelp", () => {
+    test("returns true for --help", () => {
+        expect(shouldShowHelp(["--help"])).toBe(true);
+    });
+    test("returns true for -h", () => {
+        expect(shouldShowHelp(["-h"])).toBe(true);
+    });
+    test("returns false for no help flag", () => {
+        expect(shouldShowHelp(["--extension-port", "8080"])).toBe(false);
+    });
+    test("returns false for empty args", () => {
+        expect(shouldShowHelp([])).toBe(false);
+    });
+});
+describe("parseConfig", () => {
+    test("no args returns default config", () => {
+        expect(parseConfig([])).toEqual({ extensionPort: 3333 });
+    });
+    test("--extension-port flag sets custom port", () => {
+        expect(parseConfig(["--extension-port", "8080"])).toEqual({
+            extensionPort: 8080,
+        });
+    });
+    test("-p flag sets custom port", () => {
+        expect(parseConfig(["-p", "8080"])).toEqual({ extensionPort: 8080 });
+    });
+    test("help flag is ignored in config parsing", () => {
+        expect(parseConfig(["--help"])).toEqual({ extensionPort: 3333 });
+    });
+    test("invalid port returns Error", () => {
+        const result = parseConfig(["--extension-port", "abc"]);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("Invalid port number");
+    });
+    test("missing port value returns Error", () => {
+        const result = parseConfig(["--extension-port"]);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("--extension-port flag requires a port number");
+    });
+    test("out of range port returns Error", () => {
+        const result = parseConfig(["--extension-port", "70000"]);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("Invalid port number");
+    });
+    test("multiple --extension-port flags uses last one", () => {
+        expect(parseConfig(["--extension-port", "8080", "--extension-port", "9090"])).toEqual({
+            extensionPort: 9090,
+        });
+    });
+    test("short and long form both work, last wins", () => {
+        expect(parseConfig(["--extension-port", "8080", "-p", "9090"])).toEqual({
+            extensionPort: 9090,
+        });
+    });
+});
+describe("buildConfig", () => {
+    const originalArgv = process.argv;
+    afterEach(() => {
+        process.argv = originalArgv;
+    });
+    test("uses default config with empty args", () => {
+        process.argv = ["node", "script.js"];
+        const result = buildConfig();
+        expect(result).toEqual({ extensionPort: 3333 });
+    });
+    test("parses custom port from argv", () => {
+        process.argv = ["node", "script.js", "--extension-port", "8080"];
+        const result = buildConfig();
+        expect(result).toEqual({ extensionPort: 8080 });
+    });
+    test("returns Error for invalid config", () => {
+        process.argv = ["node", "script.js", "--extension-port", "abc"];
+        const result = buildConfig();
+        expect(result).toBeInstanceOf(Error);
+    });
+});

package/build/index.js

@@ -5,13 +5,34 @@ import { z } from "zod";
 import EventEmitter from "node:events";
 import { createServer } from "node:net";
 import uWS from "uWebSockets.js";
+import { buildConfig, shouldShowHelp } from "./config.js";
 import { bus_reply_stream, bus_request_stream, } from "./types.js";
 import { create_bus } from "./emitter_bus.js";
 import { default_tool } from "./tool.js";
 import { nanoid_id_generator } from "./nanoid_id_generator.js";
 import { create_logger as create_console_logger } from "./mcp_console_logger.js";
 import { create_logger as create_server_logger, validLogLevels, } from "./mcp_server_logger.js";
-const PORT = 3333;
+/**
+ * Display help message and exit
+ */
+function showHelp() {
+    console.log(`
+Draw.io MCP Server
+
+Usage: drawio-mcp-server [options]
+
+Options:
+  --extension-port, -p <number>  WebSocket server port for browser extension (default: 3333)
+  --help, -h                     Show this help message
+
+Examples:
+  drawio-mcp-server                           # Use default extension port 3333
+  drawio-mcp-server --extension-port 8080     # Use custom extension port 8080
+  drawio-mcp-server -p 8080                   # Short form
+  `);
+    process.exit(0);
+}
+// No PORT constant needed - using dynamic config
 async function checkPortAvailable(port) {
     return new Promise((resolve) => {
         const server = createServer();
@@ -55,21 +76,21 @@ const ws_handler = {
         //todo remove conn
     },
 };
-async function start_websocket_server() {
-    const isPortAvailable = await checkPortAvailable(PORT);
+async function start_websocket_server(extensionPort) {
+    const isPortAvailable = await checkPortAvailable(extensionPort);
     if (!isPortAvailable) {
-        console.error(`[start_websocket_server] Error: Port ${PORT} is already in use. Please stop the process using this port and try again.`);
+        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(PORT, (token) => {
+        .listen(extensionPort, (token) => {
         if (token) {
-            log.debug(`[start_websocket_server] Listening to port ${PORT}`);
+            log.debug(`[start_websocket_server] Listening to port ${extensionPort}`);
         }
         else {
-            console.error(`[start_websocket_server] Error: Failed to listen on port ${PORT}`);
+            console.error(`[start_websocket_server] Error: Failed to listen on port ${extensionPort}`);
             process.exit(1);
         }
     });
@@ -92,7 +113,7 @@ if (logger_type === "mcp_server") {
 // Create server instance
 const server = new McpServer({
     name: "drawio-mcp-server",
-    version: "1.2.1",
+    version: "1.4.0",
 }, {
     capabilities,
 });
@@ -310,9 +331,22 @@ server.tool(TOOL_list_paged_model, "Retrieves a paginated view of all cells (ver
         .default({}),
 }, default_tool(TOOL_list_paged_model, context));
 async function main() {
-    log.debug("Draw.io MCP Server starting");
-    await start_websocket_server();
-    log.debug("Draw.io MCP Server WebSocket started");
+    // Check if help was requested (before parsing config)
+    if (shouldShowHelp(process.argv.slice(2))) {
+        showHelp();
+        // never returns
+    }
+    // Build configuration from command line args
+    const configResult = buildConfig();
+    // Handle errors from configuration parsing
+    if (configResult instanceof Error) {
+        console.error(`Error: ${configResult.message}`);
+        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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drawio-mcp-server",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Provides Draw.io services to MCP Clients",
   "type": "module",
   "main": "index.js",