drawio-mcp-server 1.0.2 → 1.1.0

package/README.md

@@ -130,12 +130,60 @@ The configuration is usually in: ~/.local/share/oterm/config.json
 ```
 </details>
 
+### Connect with Zed
+
+1. Open the Zed Preview application.
+1. Click the Assistant (✨) icon in the bottom right corner.
+1. Click Settings in the top right panel of the Assistant.
+1. In the Context Servers section, click + Add Context Server.
+1. Configure with the following:
+
+<details>
+  <summary>Using <code>npm</code></summary>
+
+```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"],
+      /// The environment variables to set for the executable
+      "env": {}
+    }
+  }
+}
+```
+</details>
+
+<details>
+  <summary>Using <code>pnpm</code></summary>
+
+```json
+{
+  /// The name of your MCP server
+  "drawio": {
+    "command": {
+      /// The path to the executable
+      "path": "pnpm",
+      /// The arguments to pass to the executable
+      "args": ["dlx","drawio-mcp-server"],
+      /// The environment variables to set for the executable
+      "env": {}
+    }
+  }
+}
+```
+</details>
+
 ### Browser Extension Setup
 
 In order to control the Draw.io diagram, you need to install dedicated Browser Extension.
 
 1. Open [Draw.io in your browser](https://app.diagrams.net/)
-2. Install the Draw.io MCP Browser Extension from a web store (**still pending review**) or [use other means](https://github.com/lgazo/drawio-mcp-extension)
+2. Install the Draw.io MCP Browser Extension from a web store or [use other means](https://github.com/lgazo/drawio-mcp-extension)
 <p>
   <a href="https://chrome.google.com/webstore/detail/drawio-mcp-extension/okdbbjbbccdhhfaefmcmekalmmdjjide">
     <picture>
@@ -208,6 +256,22 @@ The Draw.io MCP server provides the following tools for programmatic diagram int
 
 ## Related Resources
 
+[Troubleshooting](./TROUBLESHOOTING.md)
+
+[Prompt examples](./docs/examples/index.md)
+
+[Contributing](./CONTRIBUTING.md)
+
 [Architecture](./ARCHITECTURE.md)
 
 [Development](./DEVELOPMENT.md)
+
+## Star History
+
+<a href="https://star-history.com/#lgazo/drawio-mcp-server&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=lgazo/drawio-mcp-server&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=lgazo/drawio-mcp-server&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=lgazo/drawio-mcp-server&type=Date" />
+ </picture>
+</a>

package/build/index.js

@@ -3,17 +3,28 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import EventEmitter from "node:events";
+import { createServer } from "node:net";
 import uWS from "uWebSockets.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 } from "./mcp_console_logger.js";
+const PORT = 3333;
 const log = create_logger();
+async function checkPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.listen(port, () => {
+            server.close(() => resolve(true));
+        });
+        server.on("error", () => resolve(false));
+    });
+}
 const emitter = new EventEmitter();
 const conns = [];
 const bus_to_ws_forwarder_listener = (event) => {
-    log.debug(`[bridge] received; passing to #${conns.length}`, event);
+    log.debug(`[bridge] received; forwarding message to #${conns.length} clients`, event);
     for (let i = 0; i < conns.length; i++) {
         try {
             conns[i].send(JSON.stringify(event));
@@ -25,8 +36,9 @@ const bus_to_ws_forwarder_listener = (event) => {
 };
 emitter.on(bus_request_stream, bus_to_ws_forwarder_listener);
 const ws_handler = {
+    maxPayloadLength: 128 * 1024,
     open: (ws) => {
-        log.debug("A WebSocket connected!");
+        log.debug(`[ws_handler] A WebSocket client #${conns.length} connected, presumably MCP Extension!`);
         conns.push(ws);
     },
     message: (ws, message, isBinary) => {
@@ -39,22 +51,34 @@ const ws_handler = {
         emitter.emit(bus_reply_stream, json);
     },
     close: (ws, code, message) => {
-        log.debug("WebSocket closed");
+        log.debug(`[ws_handler] WebSocket client closed with code ${code}`);
         //todo remove conn
     },
 };
-const app = uWS
-    .App()
-    .ws("/*", ws_handler)
-    .listen(3333, (token) => {
-    if (token) {
-        log.debug("Listening to port 3333");
+async function start_websocket_server() {
+    const isPortAvailable = await checkPortAvailable(PORT);
+    if (!isPortAvailable) {
+        console.error(`[start_websocket_server] Error: Port ${PORT} 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) => {
+        if (token) {
+            log.debug(`[start_websocket_server] Listening to port ${PORT}`);
+        }
+        else {
+            console.error(`[start_websocket_server] Error: Failed to listen on port ${PORT}`);
+            process.exit(1);
+        }
+    });
+    return app;
+}
 // Create server instance
 const server = new McpServer({
     name: "drawio-mcp-server",
-    version: "1.0.1",
+    version: "1.0.3",
     capabilities: {
         resources: {},
         tools: {},
@@ -174,7 +198,36 @@ 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_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
+        .number()
+        .optional()
+        .describe("Zero-based page number for pagination. Page 0 returns the first batch of cells, page 1 returns the next batch, etc. Default is 0.")
+        .default(0),
+    page_size: z
+        .number()
+        .optional()
+        .describe("Maximum number of cells to return in a single page. Controls response size and performance. Must be between 1 and 1000. Default is 50.")
+        .default(50),
+    filter: z
+        .object({
+        cell_type: z
+            .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: z
+            .array(z.any())
+            .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_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");
     const transport = new StdioServerTransport();
     await server.connect(transport);
     log.debug("Draw.io MCP Server running on stdio");

package/build/mcp_console_logger.js

@@ -1,10 +1,14 @@
 export function create_logger() {
     return {
-        log: (level, message, data) => {
-            return console.error(message, data);
+        log: (level, message, ...data) => {
+            return data.length > 0
+                ? console.error(`${level?.toUpperCase()}: ${message}`, ...data)
+                : console.error(`${level?.toUpperCase()}: ${message}`);
         },
-        debug: (message, data) => {
-            return console.error(message, data);
+        debug: (message, ...data) => {
+            return data.length > 0
+                ? console.error(`DEBUG: ${message}`, ...data)
+                : console.error(`DEBUG: ${message}`);
         },
     };
 }

package/build/mcp_console_logger.test.js

@@ -29,7 +29,7 @@ describe("create_logger", () => {
         const testLevel = "info";
         logger.log(testLevel, testMessage, testData);
         expect(mockConsoleError).toHaveBeenCalledTimes(1);
-        expect(mockConsoleError).toHaveBeenCalledWith(testMessage, testData);
+        expect(mockConsoleError).toHaveBeenCalledWith(`${testLevel.toUpperCase()}: ${testMessage}`, testData);
     });
     it("debug method should call console.error with message and data", () => {
         const logger = create_logger();
@@ -37,15 +37,27 @@ describe("create_logger", () => {
         const testData = { debug: true };
         logger.debug(testMessage, testData);
         expect(mockConsoleError).toHaveBeenCalledTimes(1);
-        expect(mockConsoleError).toHaveBeenCalledWith(testMessage, testData);
+        expect(mockConsoleError).toHaveBeenCalledWith(`DEBUG: ${testMessage}`, testData);
     });
-    it("should handle undefined data parameter", () => {
+    it("should handle no additional data parameters", () => {
         const logger = create_logger();
         const testMessage = "message without data";
         logger.log("warn", testMessage);
-        expect(mockConsoleError).toHaveBeenCalledWith(testMessage, undefined);
+        expect(mockConsoleError).toHaveBeenCalledWith(`WARN: ${testMessage}`);
         mockConsoleError.mockClear();
         logger.debug(testMessage);
-        expect(mockConsoleError).toHaveBeenCalledWith(testMessage, undefined);
+        expect(mockConsoleError).toHaveBeenCalledWith(`DEBUG: ${testMessage}`);
+    });
+    it("should handle multiple data parameters", () => {
+        const logger = create_logger();
+        const testMessage = "message with multiple data";
+        const data1 = { key1: "value1" };
+        const data2 = { key2: "value2" };
+        const data3 = "string data";
+        logger.log("error", testMessage, data1, data2, data3);
+        expect(mockConsoleError).toHaveBeenCalledWith(`ERROR: ${testMessage}`, data1, data2, data3);
+        mockConsoleError.mockClear();
+        logger.debug(testMessage, data1, data2, data3);
+        expect(mockConsoleError).toHaveBeenCalledWith(`DEBUG: ${testMessage}`, data1, data2, data3);
     });
 });

package/build/standard_console_logger.js

@@ -1,10 +1,10 @@
 export function create_logger() {
     return {
-        log: (level, message, data) => {
-            return console.log(message, data);
+        log: (level, message, ...data) => {
+            return console.log(message, ...data);
         },
-        debug: (message, data) => {
-            return console.debug(message, data);
+        debug: (message, ...data) => {
+            return console.debug(message, ...data);
         },
     };
 }

package/build/standard_console_logger.test.js

@@ -0,0 +1,83 @@
+import { jest } from "@jest/globals";
+import { create_logger } from "./standard_console_logger.js";
+describe("create_logger", () => {
+    let originalConsoleLog;
+    let originalConsoleDebug;
+    let mockConsoleLog;
+    let mockConsoleDebug;
+    beforeEach(() => {
+        // Save original console methods
+        originalConsoleLog = console.log;
+        originalConsoleDebug = console.debug;
+        // Create mocks
+        mockConsoleLog = jest.fn();
+        mockConsoleDebug = jest.fn();
+        console.log = mockConsoleLog;
+        console.debug = mockConsoleDebug;
+    });
+    afterEach(() => {
+        // Restore original console methods
+        console.log = originalConsoleLog;
+        console.debug = originalConsoleDebug;
+        // Clear all mocks
+        jest.clearAllMocks();
+    });
+    it("should return a Logger object with log and debug methods", () => {
+        const logger = create_logger();
+        expect(logger).toBeDefined();
+        expect(typeof logger.log).toBe("function");
+        expect(typeof logger.debug).toBe("function");
+    });
+    it("log method should call console.log with message and data", () => {
+        const logger = create_logger();
+        const testMessage = "test message";
+        const testData = { key: "value" };
+        const testLevel = "info";
+        logger.log(testLevel, testMessage, testData);
+        expect(mockConsoleLog).toHaveBeenCalledTimes(1);
+        expect(mockConsoleLog).toHaveBeenCalledWith(testMessage, testData);
+    });
+    it("debug method should call console.debug with message and data", () => {
+        const logger = create_logger();
+        const testMessage = "debug message";
+        const testData = { debug: true };
+        logger.debug(testMessage, testData);
+        expect(mockConsoleDebug).toHaveBeenCalledTimes(1);
+        expect(mockConsoleDebug).toHaveBeenCalledWith(testMessage, testData);
+    });
+    it("should handle no additional data parameters", () => {
+        const logger = create_logger();
+        const testMessage = "message without data";
+        logger.log("warn", testMessage);
+        expect(mockConsoleLog).toHaveBeenCalledWith(testMessage);
+        mockConsoleLog.mockClear();
+        logger.debug(testMessage);
+        expect(mockConsoleDebug).toHaveBeenCalledWith(testMessage);
+    });
+    it("should ignore level parameter in log method", () => {
+        const logger = create_logger();
+        const testMessage = "test message";
+        const testData = { key: "value" };
+        // Test with different levels - should all behave the same
+        logger.log("error", testMessage, testData);
+        expect(mockConsoleLog).toHaveBeenCalledWith(testMessage, testData);
+        mockConsoleLog.mockClear();
+        logger.log("warn", testMessage, testData);
+        expect(mockConsoleLog).toHaveBeenCalledWith(testMessage, testData);
+        mockConsoleLog.mockClear();
+        logger.log("info", testMessage, testData);
+        expect(mockConsoleLog).toHaveBeenCalledWith(testMessage, testData);
+    });
+    it("should handle multiple data parameters", () => {
+        const logger = create_logger();
+        const testMessage = "message with multiple data";
+        const data1 = { key1: "value1" };
+        const data2 = { key2: "value2" };
+        const data3 = "string data";
+        logger.log("info", testMessage, data1, data2, data3);
+        expect(mockConsoleLog).toHaveBeenCalledWith(testMessage, data1, data2, data3);
+        mockConsoleLog.mockClear();
+        logger.debug(testMessage, data1, data2, data3);
+        expect(mockConsoleDebug).toHaveBeenCalledWith(testMessage, data1, data2, data3);
+    });
+});

package/package.json

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