drawio-mcp-server 1.2.1 → 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
 
@@ -279,6 +357,33 @@ The Draw.io MCP server provides the following tools for programmatic diagram int
     - `text`: Optional text content
     - `style`: Optional additional style properties
 
+- **`set-cell-shape`**
+  Applies a library shape's style to an existing cell
+  *Parameters*:
+    - `cell_id`: ID of the cell whose appearance should change
+    - `shape_name`: Name of the library shape whose style should be applied
+
+- **`set-cell-data`**
+  Stores or updates a custom attribute on a cell
+  *Parameters*:
+    - `cell_id`: ID of the cell to update
+    - `key`: Attribute name to set
+    - `value`: Attribute value (stored as a string internally)
+
+- **`edit-cell`**
+  Updates an existing vertex/shape cell in place by ID
+  *Parameters*:
+    - `cell_id`: ID of the cell whose properties should change (required)
+    - `text`, `x`, `y`, `width`, `height`, `style`: Optional fields to update on the cell; omitted properties stay as-is
+
+- **`edit-edge`**
+  Updates an existing edge connection between cells by ID
+  *Parameters*:
+    - `cell_id`: ID of the edge cell to update (required)
+    - `text`: Optional edge label text
+    - `source_id`, `target_id`: Optional IDs of new source/target cells
+    - `style`: Optional replacement style string
+
 ## Related Resources
 
 [Troubleshooting](./TROUBLESHOOTING.md)

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,
 });
@@ -213,6 +234,68 @@ server.tool(TOOL_add_cell_of_shape, "This tool allows you to add new vertex cell
         .optional()
         .describe("Semi-colon separated list of Draw.io visual styles, in the form of `key=value`. Example: `whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;`"),
 }, default_tool(TOOL_add_cell_of_shape, context));
+const TOOL_set_cell_shape = "set-cell-shape";
+server.tool(TOOL_set_cell_shape, "Updates the visual style of an existing vertex cell to match a library shape by name.", {
+    cell_id: z
+        .string()
+        .describe("Identifier (`id` attribute) of the cell whose shape should change."),
+    shape_name: z
+        .string()
+        .describe("Name of the library shape whose style should be applied to the existing cell."),
+}, default_tool(TOOL_set_cell_shape, context));
+const TOOL_set_cell_data = "set-cell-data";
+server.tool(TOOL_set_cell_data, "Sets or updates a custom attribute on an existing cell.", {
+    cell_id: z
+        .string()
+        .describe("Identifier (`id` attribute) of the cell to update with custom data."),
+    key: z.string().describe("Name of the attribute to set on the cell."),
+    value: z
+        .union([z.string(), z.number(), z.boolean()])
+        .describe("Value to store for the attribute. Non-string values are stringified before storage."),
+}, default_tool(TOOL_set_cell_data, context));
+const TOOL_edit_cell = "edit-cell";
+server.tool(TOOL_edit_cell, "Update properties of an existing vertex/shape cell by its ID. Only provided fields are modified; unspecified properties remain unchanged.", {
+    cell_id: z
+        .string()
+        .describe("Identifier (`id` attribute) of the cell to update. Applies to vertex/shape cells."),
+    text: z
+        .string()
+        .optional()
+        .describe("Replace the cell's text/label content."),
+    x: z
+        .number()
+        .optional()
+        .describe("Set a new X-axis position for the cell."),
+    y: z
+        .number()
+        .optional()
+        .describe("Set a new Y-axis position for the cell."),
+    width: z.number().optional().describe("Set a new width for the cell."),
+    height: z.number().optional().describe("Set a new height for the cell."),
+    style: z
+        .string()
+        .optional()
+        .describe("Replace the cell's style string (semi-colon separated `key=value` pairs)."),
+}, default_tool(TOOL_edit_cell, context));
+const TOOL_edit_edge = "edit-edge";
+server.tool(TOOL_edit_edge, "Update properties of an existing edge by its ID. Only provided fields are modified; unspecified properties remain unchanged.", {
+    cell_id: z
+        .string()
+        .describe("Identifier (`id` attribute) of the edge cell to update. The ID must reference an edge."),
+    text: z.string().optional().describe("Replace the edge's label text."),
+    source_id: z
+        .string()
+        .optional()
+        .describe("Reassign the edge's source terminal to a different cell ID."),
+    target_id: z
+        .string()
+        .optional()
+        .describe("Reassign the edge's target terminal to a different cell ID."),
+    style: z
+        .string()
+        .optional()
+        .describe("Replace the edge's style string (semi-colon separated `key=value` pairs)."),
+}, default_tool(TOOL_edit_edge, context));
 const Attributes = z.lazy(() => z
     .array(z.union([
     z.string(),
@@ -248,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.2.1",
+  "version": "1.4.0",
   "description": "Provides Draw.io services to MCP Clients",
   "type": "module",
   "main": "index.js",