drawio-mcp-server 2.0.4 → 2.1.0

package/README.md

@@ -9,11 +9,21 @@ Let's do some Vibe Diagramming with the most wide-spread diagramming tool called
 
 ## Key Highlights
 
+- Enable Draw.io MCP in IFrames ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- AWS, GCP, Azure, Cisco19, and CiscoSafe stencils auto-discovered at runtime from drawio's sidebar ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Multi-document targeting with `list-documents` and `target_document` selectors for multi-tab workflows ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Multi-page targeting with required `target_page` selectors for page-scoped tools ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Per-document FIFO serialization for live operations, so multiple agents can work on different files safely ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Page management tools: `list-pages`, `get-current-page`, `create-page`, `copy-page`, `rename-page` ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Import, embed, or expand [Mermaid](https://mermaid.js.org/) diagrams ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Firefox support is back, TLS mode is necessary ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+- Server supports TLS mode and optionally generates self-signed certificates ![v2.1.0](https://img.shields.io/badge/v2.1.0-blue)
+
 - Import and export diagrams from/to XML, SVG (with embedded XML), or PNG (with embedded XML) ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
 - Edge geometry control with waypoints and automatic self-connector routing ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
 - Parent-child relationships for nested shapes and grouping ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
 - Unified Server and Extension in the same mono-repo ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
-- Built-in Draw.io editor - no browser extension required ![v1.8.0](https://img.shields.io/badge/v1.8.0-blue)
+- Built-in Draw.io editor - no browser extension required
 - MCP server that lets AI agents control Draw.io diagrams
 - Programmatic diagram creation, inspection, and modification via MCP tools
 - Layer management for complex diagrams
@@ -27,6 +37,8 @@ Two ways to use:
 1. **Built-in editor** - Server hosts Draw.io directly, accessible in your browser
 2. **Browser extension** - Connect to Draw.io running in your browser via extension
 
+Experimental: integration with the **draw.io desktop (Electron) app** is in progress but currently blocked by an upstream CSP issue — see [DESKTOP.md](./DESKTOP.md).
+
 ## Requirements
 
 - **Node.js** (v20 or higher) - Runtime environment for the MCP server
@@ -134,6 +146,8 @@ Example prompts you can try:
 
 > "Create an event-driven architecture diagram showing a message queue with producers, consumers, and three backend services"
 
+> "Create a three-page event-driven architecture diagram. Use three agents in parallel for service topology, message flow, and retry/failure handling, with each agent assigned to a separate target page."
+
 > "Draw a CRUD API diagram with a database, API gateway, and four microservices with their endpoints"
 
 > "Add a new layer called 'Background' and move all decorative elements to it, then create a new layer for annotations"
@@ -144,9 +158,13 @@ Your AI assistant can now control the diagram using MCP tools.
 
 The server provides MCP tools for:
 
-- **Diagram inspection** - read shapes, layers, and cell properties
-- **Diagram modification** - add/edit/delete shapes, edges, and labels
+- **Document discovery** - list connected Draw.io document instances and route later calls to a specific tab/file instance
+- **Diagram inspection** - read shapes, pages, layers, and cell properties
+- **Diagram modification** - add/edit/delete shapes, edges, and labels on a target page
+- **Page management** - list pages, inspect the current page, create pages, copy pages, and rename pages without forcing a visible page switch on supported runtimes
 - **Layer management** - create, switch, and organize layers
+- **Vendor shape coverage** - AWS, GCP, Azure, Cisco19, and CiscoSafe stencils auto-discovered at runtime from drawio's sidebar, so agents can place icons like `mxgraph.gcp2.cloud_run` or `mxgraph.cisco19.router` without hand-curated catalogs
+- **Built-in TLS** — opt-in HTTPS + WSS with manual cert/key or auto-generated self-signed material via a per-user local CA. See [CONFIG.md → TLS](./CONFIG.md#tls-https--wss).
 
 See [Tools Reference](./TOOLS.md) for the complete list of available tools.
 
@@ -179,6 +197,12 @@ Configuration without `--editor`:
 
 See the [extension documentation](./packages/drawio-mcp-extension/README.md) for more details.
 
+## Experimental: Draw.io Desktop
+
+Integration with the [draw.io desktop](https://github.com/jgraph/drawio-desktop) (Electron) app is **experimental** and currently blocked end-to-end by an upstream CSP issue. The plugin loads inside draw.io desktop, but its WebSocket connection back to the MCP server is rejected by draw.io's hard-coded `connect-src 'self'` policy.
+
+See [DESKTOP.md](./DESKTOP.md) for the full setup steps and the current limitation.
+
 ## Related Resources
 
 [Configuration](./CONFIG.md) - CLI flags and advanced options
@@ -195,6 +219,8 @@ See the [extension documentation](./packages/drawio-mcp-extension/README.md) for
 
 [Development](./DEVELOPMENT.md)
 
+[Draw.io Desktop (experimental)](./DESKTOP.md) - install path and known CSP limitation
+
 ## Star History
 
 <a href="https://star-history.com/#lgazo/drawio-mcp-server&Date">

package/build/assets/downloader.js

@@ -43,7 +43,7 @@ export async function extractWar(warPath, extractDir) {
         extract.on("error", reject);
     });
 }
-export function cleanupExtractedFiles(extractDir) {
+export function cleanupExtractedFiles(extractDir, log) {
     const webappDir = join(extractDir, "webapp");
     const pathsToRemove = [
         join(webappDir, "WEB-INF"),
@@ -53,44 +53,43 @@ export function cleanupExtractedFiles(extractDir) {
         if (existsSync(path)) {
             try {
                 rmSync(path, { recursive: true, force: true });
-                console.log(`Removed: ${path}`);
+                log.log("info", `Removed: ${path}`);
             }
             catch (err) {
-                console.warn(`Failed to remove ${path}:`, err);
+                log.log("warning", `Failed to remove ${path}:`, err);
             }
         }
     }
 }
-export async function downloadAndExtractAssets(targetDir, onProgress) {
-    const progress = onProgress || console.log;
-    progress("Fetching draw.io release info...");
+export async function downloadAndExtractAssets(targetDir, log) {
+    log.log("info", "Fetching draw.io release info...");
     const warUrl = await getLatestWarUrl();
     const warPath = join(targetDir, "draw.war");
-    progress(`Downloading draw.war from ${warUrl}...`);
+    log.log("info", `Downloading draw.war from ${warUrl}...`);
     await downloadFile(warUrl, warPath);
-    progress("Download complete.");
+    log.log("info", "Download complete.");
     const webappDir = join(targetDir, "webapp");
-    progress("Extracting archive...");
+    log.log("info", "Extracting archive...");
     await extractWar(warPath, webappDir);
-    progress("Extraction complete.");
-    progress("Cleaning up unnecessary files...");
-    cleanupExtractedFiles(targetDir);
+    log.log("info", "Extraction complete.");
+    log.log("info", "Cleaning up unnecessary files...");
+    cleanupExtractedFiles(targetDir, log);
     // Remove the WAR file
     try {
         rmSync(warPath, { force: true });
     }
     catch (err) {
-        console.warn("Failed to remove WAR file:", err);
+        log.log("warning", "Failed to remove WAR file:", err);
     }
-    progress("Assets ready!");
+    log.log("info", "Assets ready!");
 }
-export async function ensureAssets(config, onProgress) {
+export async function ensureAssets(config, log) {
     const { getCacheDir, getAssetRoot, assetsExist } = await import("./manager.js");
     const cacheDir = getCacheDir(config.assetPath);
     const assetRoot = getAssetRoot(config);
     if (!assetsExist(config)) {
-        console.log(`Assets not found in ${assetRoot}. Downloading...`);
-        await downloadAndExtractAssets(cacheDir, onProgress);
+        log.log("info", `Assets not found in ${assetRoot}. Downloading...`);
+        await downloadAndExtractAssets(cacheDir, log);
     }
     return { assetRoot, isLocal: true };
 }

package/build/config.js

@@ -1,6 +1,4 @@
-/**
- * Application configuration interface
- */
+import { isIP } from "node:net";
 /**
  * Default configuration values
  */
@@ -9,6 +7,9 @@ const DEFAULT_CONFIG = {
     httpPort: 3000,
     transports: ["stdio"],
     editorEnabled: false,
+    logger: "console",
+    tlsEnabled: false,
+    tlsAuto: false,
 };
 /**
  * Valid port range
@@ -49,6 +50,54 @@ export const parseHttpPortValue = (value) => {
     }
     return port;
 };
+/**
+ * Parse WebSocket URL value - pure function
+ * Accepts ws:// or wss:// URLs only
+ */
+export const parseWebSocketUrlValue = (value) => {
+    if (!value) {
+        return new Error("--websocket-url flag requires a URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return new Error(`Invalid WebSocket URL "${value}"`);
+    }
+    if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+        return new Error(`Invalid WebSocket URL "${value}". Protocol must be ws:// or wss://`);
+    }
+    return value;
+};
+/**
+ * Parse host value - pure function
+ * Accepts IPv4 or IPv6 addresses only (no hostnames)
+ */
+export const parseHostValue = (value) => {
+    if (!value) {
+        return new Error("--host flag requires an IP address");
+    }
+    if (isIP(value) === 0) {
+        return new Error(`Invalid host "${value}". Must be a valid IPv4 or IPv6 address`);
+    }
+    return value;
+};
+/**
+ * Parse logger mode value - pure function
+ * Accepts "console" or "mcp-server". For convenience the legacy underscore
+ * form "mcp_server" is normalised to "mcp-server".
+ */
+export const parseLoggerValue = (value) => {
+    if (!value) {
+        return new Error("--logger flag requires a mode (console|mcp-server)");
+    }
+    const normalized = value === "mcp_server" ? "mcp-server" : value;
+    if (normalized === "console" || normalized === "mcp-server") {
+        return normalized;
+    }
+    return new Error(`Invalid logger "${value}". Must be one of: console, mcp-server`);
+};
 export const parseTransports = (values) => {
     if (!values || values.length === 0) {
         return DEFAULT_CONFIG.transports;
@@ -103,6 +152,14 @@ export const parseConfig = (args) => {
     let transportValues;
     let editorEnabled = false;
     let assetPath;
+    let webSocketUrlValue;
+    let hostValue;
+    let loggerValue;
+    let tlsEnabled = false;
+    let tlsAuto = false;
+    let tlsCert;
+    let tlsKey;
+    let tlsDir;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--extension-port" || arg === "-p") {
@@ -154,6 +211,84 @@ export const parseConfig = (args) => {
             assetPath = nextValue;
             i += 1;
         }
+        else if (arg === "--websocket-url") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--websocket-url flag requires a URL");
+            }
+            webSocketUrlValue = nextValue;
+            i += 1;
+        }
+        else if (arg === "--host") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--host flag requires an IP address");
+            }
+            hostValue = nextValue;
+            i += 1;
+        }
+        else if (arg === "--logger") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--logger flag requires a mode (console|mcp-server)");
+            }
+            loggerValue = nextValue;
+            i += 1;
+        }
+        else if (arg === "--tls") {
+            tlsEnabled = true;
+        }
+        else if (arg === "--tls-auto") {
+            tlsAuto = true;
+        }
+        else if (arg === "--tls-cert") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--tls-cert flag requires a path");
+            }
+            tlsCert = nextValue;
+            i += 1;
+        }
+        else if (arg === "--tls-key") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--tls-key flag requires a path");
+            }
+            tlsKey = nextValue;
+            i += 1;
+        }
+        else if (arg === "--tls-dir") {
+            const nextValue = args[i + 1];
+            if (nextValue === undefined) {
+                return new Error("--tls-dir flag requires a directory path");
+            }
+            tlsDir = nextValue;
+            i += 1;
+        }
+    }
+    let logger = DEFAULT_CONFIG.logger;
+    if (loggerValue !== undefined) {
+        const parsed = parseLoggerValue(loggerValue);
+        if (parsed instanceof Error) {
+            return parsed;
+        }
+        logger = parsed;
+    }
+    let webSocketUrl;
+    if (webSocketUrlValue !== undefined) {
+        const parsed = parseWebSocketUrlValue(webSocketUrlValue);
+        if (parsed instanceof Error) {
+            return parsed;
+        }
+        webSocketUrl = parsed;
+    }
+    let host;
+    if (hostValue !== undefined) {
+        const parsed = parseHostValue(hostValue);
+        if (parsed instanceof Error) {
+            return parsed;
+        }
+        host = parsed;
     }
     if (httpPortValue !== undefined) {
         const httpPort = parseHttpPortValue(httpPortValue);
@@ -162,6 +297,21 @@ export const parseConfig = (args) => {
         }
         parsedHttpPort = httpPort;
     }
+    // TLS validation
+    if ((tlsCert || tlsKey || tlsAuto || tlsDir) && !tlsEnabled) {
+        return new Error("TLS sub-flags (--tls-cert, --tls-key, --tls-auto, --tls-dir) require --tls");
+    }
+    if (tlsEnabled) {
+        if (tlsCert && !tlsKey) {
+            return new Error("--tls-cert requires --tls-key");
+        }
+        if (tlsKey && !tlsCert) {
+            return new Error("--tls-key requires --tls-cert");
+        }
+        if (tlsAuto && (tlsCert || tlsKey)) {
+            return new Error("Cannot combine --tls-auto with --tls-cert/--tls-key. Pick one mode.");
+        }
+    }
     if (portValue !== undefined) {
         const extensionPort = parseExtensionPortValue(portValue);
         if (extensionPort instanceof Error) {
@@ -178,6 +328,14 @@ export const parseConfig = (args) => {
             transports,
             editorEnabled,
             assetPath,
+            webSocketUrl,
+            host,
+            logger,
+            tlsEnabled,
+            tlsAuto,
+            tlsCert,
+            tlsKey,
+            tlsDir,
         };
     }
     if (httpPortValue !== undefined) {
@@ -191,6 +349,14 @@ export const parseConfig = (args) => {
             transports,
             editorEnabled,
             assetPath,
+            webSocketUrl,
+            host,
+            logger,
+            tlsEnabled,
+            tlsAuto,
+            tlsCert,
+            tlsKey,
+            tlsDir,
         };
     }
     const transports = parseTransports(transportValues);
@@ -203,16 +369,98 @@ export const parseConfig = (args) => {
         transports,
         editorEnabled,
         assetPath,
+        webSocketUrl,
+        host,
+        logger,
+        tlsEnabled,
+        tlsAuto,
+        tlsCert,
+        tlsKey,
+        tlsDir,
     };
 };
+/**
+ * Map known DRAWIO_MCP_* environment variables to argv tokens.
+ * Pure function - injected env in, argv out.
+ *
+ * Result is concatenated BEFORE real CLI args so that parseConfig's
+ * last-wins semantics give CLI flags precedence over env vars.
+ */
+export const envToArgs = (env) => {
+    const out = [];
+    const extPort = env.DRAWIO_MCP_EXTENSION_PORT;
+    if (extPort && extPort.length > 0) {
+        out.push("--extension-port", extPort);
+    }
+    const httpPort = env.DRAWIO_MCP_HTTP_PORT;
+    if (httpPort && httpPort.length > 0) {
+        out.push("--http-port", httpPort);
+    }
+    const transport = env.DRAWIO_MCP_TRANSPORT;
+    if (transport && transport.length > 0) {
+        out.push("--transport", transport);
+    }
+    const editor = env.DRAWIO_MCP_EDITOR;
+    if (editor && editor.length > 0) {
+        const normalized = editor.toLowerCase();
+        if (normalized === "true" || normalized === "false") {
+            out.push("--editor", normalized);
+        }
+    }
+    const assetPath = env.DRAWIO_MCP_ASSET_PATH;
+    if (assetPath && assetPath.length > 0) {
+        out.push("--asset-path", assetPath);
+    }
+    const wsUrl = env.DRAWIO_MCP_WEBSOCKET_URL;
+    if (wsUrl && wsUrl.length > 0) {
+        out.push("--websocket-url", wsUrl);
+    }
+    const host = env.DRAWIO_MCP_HOST;
+    if (host && host.length > 0) {
+        out.push("--host", host);
+    }
+    const logger = env.DRAWIO_MCP_LOGGER;
+    if (logger && logger.length > 0) {
+        out.push("--logger", logger);
+    }
+    const tls = env.DRAWIO_MCP_TLS;
+    if (tls && tls.toLowerCase() === "true")
+        out.push("--tls");
+    const tlsAuto = env.DRAWIO_MCP_TLS_AUTO;
+    if (tlsAuto && tlsAuto.toLowerCase() === "true")
+        out.push("--tls-auto");
+    const tlsCert = env.DRAWIO_MCP_TLS_CERT;
+    if (tlsCert && tlsCert.length > 0)
+        out.push("--tls-cert", tlsCert);
+    const tlsKey = env.DRAWIO_MCP_TLS_KEY;
+    if (tlsKey && tlsKey.length > 0)
+        out.push("--tls-key", tlsKey);
+    const tlsDir = env.DRAWIO_MCP_TLS_DIR;
+    if (tlsDir && tlsDir.length > 0)
+        out.push("--tls-dir", tlsDir);
+    return out;
+};
 /**
  * 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);
+    const envArgs = envToArgs(process.env);
+    const cliArgs = process.argv.slice(2);
+    return parseConfig([...envArgs, ...cliArgs]);
+};
+/**
+ * Convenience: parse an empty argument list and return the default
+ * ServerConfig. Used by test harnesses that need a config object but do not
+ * exercise the parser.
+ */
+export const defaultConfig = () => {
+    const result = parseConfig([]);
+    if (result instanceof Error) {
+        throw result;
+    }
+    return result;
 };
 export function getHttpFeatureConfig(config) {
     return {