drawio-mcp-server 2.0.3 → 2.1.0

package/build/tool.js

@@ -1,30 +1,89 @@
 import { strip_internal_fields } from "./events.js";
-export function build_channel({ bus, id_generator, log }, event_name, handler) {
-    const fn = async (_args, _extra) => {
+const DEFAULT_REPLY_TIMEOUT_MS = (() => {
+    const raw = process.env.DRAWIO_MCP_REPLY_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
+    }
+    return 60_000;
+})();
+export function build_channel({ bus, id_generator, request_queue, document_routing, log }, event_name, handler, options = {}) {
+    const routing = options.routing ?? "document";
+    const invoke = async (request_payload, queue_key) => {
+        const reply_timeout_ms = options.reply_timeout_ms && options.reply_timeout_ms > 0
+            ? options.reply_timeout_ms
+            : DEFAULT_REPLY_TIMEOUT_MS;
         const request_id = id_generator.generate();
-        // const event_name = `get-selected-cell`;
         const reply_name = `${event_name}.${request_id}`;
         bus.send_to_extension({
             __event: event_name,
             __request_id: request_id,
-            ..._args,
+            ...request_payload,
         });
-        log.debug(`[${event_name}] emitted, waiting for reply @${reply_name}`);
-        const p = new Promise((resolve, _reject) => {
+        log.debug(`[${event_name}] emitted on ${queue_key}, waiting for reply @${reply_name}`);
+        const p = new Promise((resolve, reject) => {
             log.debug(`[${event_name}] waiting for response @${reply_name}`);
-            bus.on_reply_from_extension(reply_name, (reply) => {
+            let settled = false;
+            let timeout_handle;
+            let cleanup;
+            const finish = (finalize) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (timeout_handle) {
+                    clearTimeout(timeout_handle);
+                }
+                cleanup?.();
+                finalize();
+            };
+            timeout_handle = setTimeout(() => {
+                finish(() => {
+                    const error = new Error(`Timed out waiting for reply to \`${event_name}\` after ${reply_timeout_ms}ms`);
+                    log.log("warn", `[${reply_name}] ${error.message}`);
+                    reject(error);
+                });
+            }, reply_timeout_ms);
+            cleanup = bus.on_reply_from_extension(reply_name, (reply) => {
                 // bus.on(reply_name, (args) => {
-                log.debug(`[${reply_name}] received response`, reply);
-                const data = strip_internal_fields(reply);
-                const response = handler(data);
-                resolve(response);
+                finish(() => {
+                    log.debug(`[${reply_name}] received response`, reply);
+                    const data = strip_internal_fields(reply);
+                    try {
+                        const response = handler(data);
+                        resolve(response);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                });
             });
+            if (settled) {
+                cleanup?.();
+            }
         });
         return p;
     };
+    const fn = async (_args, _extra) => {
+        let request_payload = { ..._args };
+        let queue_key = "global";
+        if (routing === "document") {
+            const resolved = await document_routing.resolve_target_document(request_payload);
+            queue_key = resolved.connection_id;
+            request_payload = {
+                ...request_payload,
+                target_document: resolved.target_document,
+                __target_connection_id: resolved.connection_id,
+            };
+        }
+        if (options.queue) {
+            return request_queue.enqueue(queue_key, () => invoke(request_payload, queue_key));
+        }
+        return invoke(request_payload, queue_key);
+    };
     return fn;
 }
-export function default_tool(name, context) {
+export function default_tool(name, context, options = {}) {
     const fn = build_channel(context, name, (reply) => {
         const response = {
             content: [
@@ -35,10 +94,10 @@ export function default_tool(name, context) {
             ],
         };
         return response;
-    });
+    }, options);
     return fn;
 }
-export function export_tool_handler(name, context) {
+export function export_tool_handler(name, context, options = {}) {
     const fn = build_channel(context, name, (reply) => {
         const { success, result, error } = reply;
         if (!success) {
@@ -81,6 +140,6 @@ export function export_tool_handler(name, context) {
             content,
         };
         return response;
-    });
+    }, options);
     return fn;
 }

package/build/tool.test.js

@@ -1,30 +1,72 @@
 import { jest } from "@jest/globals";
 import { build_channel, default_tool } from "./tool.js";
 import { create_logger } from "./standard_console_logger.js";
+import { create_request_queue } from "./request_queue.js";
 describe("build_channel", () => {
     let mockBus;
     let mockIdGenerator;
+    let mockRequestQueue;
+    let mockDocumentRouting;
     let context;
     const mockHandler = jest.fn();
     const log = create_logger();
+    const resolvedDocument = {
+        id: "doc-1",
+        title: "Document One",
+        mode: "local",
+        hash: null,
+        file_url: null,
+        page_count: 1,
+        current_page: {
+            index: 0,
+            id: "page-1",
+            name: "Page 1",
+            is_current: true,
+        },
+    };
     beforeEach(() => {
         mockBus = {
             send_to_extension: jest.fn(),
-            on_reply_from_extension: jest.fn(),
+            on_reply_from_extension: jest.fn(() => jest.fn()),
         };
         mockIdGenerator = {
             generate: jest.fn().mockReturnValue("123"),
         };
+        mockRequestQueue = {
+            enqueue: jest.fn((_, task) => task()),
+        };
+        mockDocumentRouting = {
+            list_documents: jest.fn(async () => [resolvedDocument]),
+            resolve_target_document: jest.fn(async () => ({
+                connection_id: "conn-1",
+                target_document: { id: resolvedDocument.id },
+                document: resolvedDocument,
+            })),
+        };
         context = {
             bus: mockBus,
             id_generator: mockIdGenerator,
+            request_queue: mockRequestQueue,
+            document_routing: mockDocumentRouting,
             log,
         };
         mockHandler.mockReset();
     });
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+    async function flushMicrotasks() {
+        await Promise.resolve();
+        await Promise.resolve();
+    }
     it("should create a function that sends a message via bus", async () => {
         const eventName = "test-event";
-        const toolFn = build_channel(context, eventName, mockHandler);
+        const toolFn = build_channel(context, eventName, mockHandler, {
+            routing: "none",
+        });
+        mockHandler.mockReturnValue({
+            content: [{ type: "text", text: "ok" }],
+        });
         const args = { key: "value" };
         const extra = {};
         const promise = toolFn(args, extra);
@@ -33,10 +75,17 @@ describe("build_channel", () => {
             __request_id: "123",
             key: "value",
         });
+        const replyCallback = mockBus.on_reply_from_extension.mock.calls[0][1];
+        replyCallback({ ok: true });
+        await expect(promise).resolves.toEqual({
+            content: [{ type: "text", text: "ok" }],
+        });
     });
     it("should wait for reply and call handler with response", async () => {
         const eventName = "test-event";
-        const toolFn = build_channel(context, eventName, mockHandler);
+        const toolFn = build_channel(context, eventName, mockHandler, {
+            routing: "none",
+        });
         const mockResponse = {
             content: [{ type: "text", text: "response" }],
         };
@@ -53,14 +102,170 @@ describe("build_channel", () => {
     it("should use correct reply channel name format", async () => {
         mockIdGenerator.generate.mockReturnValue("456");
         const eventName = "another-event";
-        const toolFn = build_channel(context, eventName, mockHandler);
-        toolFn({}, {});
+        const toolFn = build_channel(context, eventName, mockHandler, {
+            routing: "none",
+        });
+        mockHandler.mockReturnValue({
+            content: [{ type: "text", text: "ok" }],
+        });
+        const promise = toolFn({}, {});
         expect(mockBus.on_reply_from_extension).toHaveBeenCalledWith("another-event.456", expect.any(Function));
+        const replyCallback = mockBus.on_reply_from_extension.mock.calls[0][1];
+        replyCallback({ ok: true });
+        await expect(promise).resolves.toEqual({
+            content: [{ type: "text", text: "ok" }],
+        });
+    });
+    it("should enqueue queued tools through the shared request queue", async () => {
+        const eventName = "queued-event";
+        const toolFn = build_channel(context, eventName, mockHandler, {
+            queue: true,
+            routing: "none",
+        });
+        mockHandler.mockReturnValue({
+            content: [{ type: "text", text: "queued" }],
+        });
+        const promise = toolFn({}, {});
+        const replyCallback = mockBus.on_reply_from_extension.mock.calls[0][1];
+        replyCallback({ data: "queued" });
+        await promise;
+        expect(mockRequestQueue.enqueue).toHaveBeenCalledTimes(1);
+        expect(mockRequestQueue.enqueue).toHaveBeenCalledWith("global", expect.any(Function));
+    });
+    it("should time out pending requests and unsubscribe the reply listener", async () => {
+        jest.useFakeTimers();
+        const eventName = "timeout-event";
+        const unsubscribe = jest.fn();
+        mockBus.on_reply_from_extension.mockReturnValue(unsubscribe);
+        const toolFn = build_channel(context, eventName, mockHandler, {
+            reply_timeout_ms: 25,
+            routing: "none",
+        });
+        const promise = toolFn({}, {});
+        const failure = expect(promise).rejects.toThrow("Timed out waiting for reply to `timeout-event` after 25ms");
+        await jest.advanceTimersByTimeAsync(25);
+        await failure;
+        expect(unsubscribe).toHaveBeenCalledTimes(1);
+    });
+    it("should continue queued processing after a timed out request", async () => {
+        jest.useFakeTimers();
+        const listeners = new Map();
+        const toolFn = build_channel({
+            ...context,
+            request_queue: create_request_queue(log),
+        }, "queued-timeout-event", (reply) => ({
+            content: [{ type: "text", text: JSON.stringify(reply) }],
+        }), {
+            queue: true,
+            reply_timeout_ms: 25,
+            routing: "none",
+        });
+        mockIdGenerator.generate
+            .mockReturnValueOnce("first")
+            .mockReturnValueOnce("second");
+        mockBus.on_reply_from_extension.mockImplementation((event_name, listener) => {
+            listeners.set(event_name, listener);
+            return () => {
+                listeners.delete(event_name);
+            };
+        });
+        const first = toolFn({}, {});
+        const second = toolFn({}, {});
+        await Promise.resolve();
+        expect(listeners.has("queued-timeout-event.first")).toBe(true);
+        expect(listeners.has("queued-timeout-event.second")).toBe(false);
+        const firstFailure = expect(first).rejects.toThrow("Timed out waiting for reply to `queued-timeout-event` after 25ms");
+        await jest.advanceTimersByTimeAsync(25);
+        await firstFailure;
+        await Promise.resolve();
+        expect(listeners.has("queued-timeout-event.second")).toBe(true);
+        listeners.get("queued-timeout-event.second")?.({
+            __event: "queued-timeout-event.second",
+            data: "ok",
+        });
+        await expect(second).resolves.toEqual({
+            content: [{ type: "text", text: JSON.stringify({ data: "ok" }) }],
+        });
+    });
+    it("resolves the target document by default and injects it into the request", async () => {
+        const toolFn = build_channel(context, "document-event", mockHandler, {
+            queue: true,
+        });
+        mockHandler.mockReturnValue({
+            content: [{ type: "text", text: "ok" }],
+        });
+        const promise = toolFn({ key: "value" }, {});
+        await Promise.resolve();
+        const replyCallback = mockBus.on_reply_from_extension.mock.calls[0][1];
+        replyCallback({ ok: true });
+        await promise;
+        expect(mockDocumentRouting.resolve_target_document).toHaveBeenCalledWith({
+            key: "value",
+        });
+        expect(mockRequestQueue.enqueue).toHaveBeenCalledWith("conn-1", expect.any(Function));
+        expect(mockBus.send_to_extension).toHaveBeenCalledWith({
+            __event: "document-event",
+            __request_id: "123",
+            key: "value",
+            target_document: { id: "doc-1" },
+            __target_connection_id: "conn-1",
+        });
+    });
+    it("propagates document routing errors before sending any request", async () => {
+        mockDocumentRouting.resolve_target_document.mockRejectedValueOnce(new Error("No connected Draw.io documents"));
+        const toolFn = build_channel(context, "document-event", mockHandler);
+        await expect(toolFn({}, {})).rejects.toThrow("No connected Draw.io documents");
+        expect(mockBus.send_to_extension).not.toHaveBeenCalled();
+    });
+    it("fails queued document requests immediately when delivery breaks after waiting in queue", async () => {
+        const listeners = new Map();
+        let sendCount = 0;
+        mockIdGenerator.generate
+            .mockReturnValueOnce("first")
+            .mockReturnValueOnce("second");
+        mockBus.send_to_extension.mockImplementation(() => {
+            sendCount += 1;
+            if (sendCount === 2) {
+                throw new Error("Target document doc-1 is no longer connected; call list-documents and retry");
+            }
+        });
+        mockBus.on_reply_from_extension.mockImplementation((event_name, listener) => {
+            listeners.set(event_name, listener);
+            return () => {
+                listeners.delete(event_name);
+            };
+        });
+        const toolFn = build_channel({
+            ...context,
+            request_queue: create_request_queue(log),
+        }, "document-event", (reply) => ({
+            content: [{ type: "text", text: JSON.stringify(reply) }],
+        }), {
+            queue: true,
+        });
+        const first = toolFn({}, {});
+        const second = toolFn({}, {});
+        await flushMicrotasks();
+        expect(mockBus.send_to_extension).toHaveBeenCalledTimes(1);
+        expect(listeners.has("document-event.first")).toBe(true);
+        expect(listeners.has("document-event.second")).toBe(false);
+        listeners.get("document-event.first")?.({
+            __event: "document-event.first",
+            ok: true,
+        });
+        await expect(first).resolves.toEqual({
+            content: [{ type: "text", text: JSON.stringify({ ok: true }) }],
+        });
+        await expect(second).rejects.toThrow("Target document doc-1 is no longer connected; call list-documents and retry");
+        expect(mockBus.send_to_extension).toHaveBeenCalledTimes(2);
+        expect(listeners.has("document-event.second")).toBe(false);
     });
 });
 describe("default_tool", () => {
     let mockBus;
     let mockIdGenerator;
+    let mockRequestQueue;
+    let mockDocumentRouting;
     const log = create_logger();
     let context;
     beforeEach(() => {
@@ -68,20 +273,47 @@ describe("default_tool", () => {
             send_to_extension: jest.fn(),
             on_reply_from_extension: jest.fn((_, callback) => {
                 callback({ test: "data" });
+                return jest.fn();
             }),
         };
         mockIdGenerator = {
             generate: jest.fn().mockReturnValue("789"),
         };
+        mockRequestQueue = {
+            enqueue: jest.fn((_, task) => task()),
+        };
+        mockDocumentRouting = {
+            list_documents: jest.fn(async () => []),
+            resolve_target_document: jest.fn(async () => ({
+                connection_id: "conn-1",
+                target_document: { id: "doc-1" },
+                document: {
+                    id: "doc-1",
+                    title: "Document One",
+                    mode: "local",
+                    hash: null,
+                    file_url: null,
+                    page_count: 1,
+                    current_page: {
+                        index: 0,
+                        id: "page-1",
+                        name: "Page 1",
+                        is_current: true,
+                    },
+                },
+            })),
+        };
         context = {
             bus: mockBus,
             id_generator: mockIdGenerator,
+            request_queue: mockRequestQueue,
+            document_routing: mockDocumentRouting,
             log,
         };
     });
     it("should create a tool that returns JSON stringified response", async () => {
         const toolName = "default-tool";
-        const tool = default_tool(toolName, context);
+        const tool = default_tool(toolName, context, { routing: "none" });
         const result = await tool({}, {});
         expect(result).toEqual({
             content: [
@@ -94,11 +326,22 @@ describe("default_tool", () => {
     });
     it("should use the provided tool name in the channel", async () => {
         const toolName = "custom-tool";
-        const tool = default_tool(toolName, context);
+        const tool = default_tool(toolName, context, { routing: "none" });
         await tool({}, {});
         expect(mockBus.send_to_extension).toHaveBeenCalledWith({
             __event: toolName,
             __request_id: "789",
         });
     });
+    it("routes default tools through the resolved document by default", async () => {
+        const tool = default_tool("custom-tool", context);
+        await tool({}, {});
+        expect(mockDocumentRouting.resolve_target_document).toHaveBeenCalledWith({});
+        expect(mockBus.send_to_extension).toHaveBeenCalledWith({
+            __event: "custom-tool",
+            __request_id: "789",
+            target_document: { id: "doc-1" },
+            __target_connection_id: "conn-1",
+        });
+    });
 });

package/build/tools/add-cell-of-shape.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_add_cell_of_shape = "add-cell-of-shape";
 export const registerAddCellOfShapeTool = (server, context) => {
-    server.tool(TOOL_add_cell_of_shape, "This tool allows you to add new vertex cell (object) on the current page of a Draw.io diagram by its shape name. It accepts multiple optional input parameter.", {
+    server.tool(TOOL_add_cell_of_shape, "This tool allows you to add a new vertex cell on the target page of the current Draw.io document by its shape name.", {
+        target_page: target_page_field(),
         shape_name: z
             .string()
             .describe("Name of the shape to retrieved from the shape library of the current diagram."),
@@ -38,5 +40,5 @@ export const registerAddCellOfShapeTool = (server, context) => {
             .string()
             .optional()
             .describe("ID of the parent cell. If provided, the new cell will be created as a child of this cell. If omitted, the cell is created at the diagram root level."),
-    }, default_tool(TOOL_add_cell_of_shape, context));
+    }, default_tool(TOOL_add_cell_of_shape, context, { queue: true }));
 };

package/build/tools/add-edge.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_add_edge = "add-edge";
 export const registerAddEdgeTool = (server, context) => {
     server.tool(TOOL_add_edge, "This tool creates an edge, sometimes called also a relation, between two vertexes (cells). When source and target are the same shape (self-connector), a loop edge style is automatically applied if no custom style is provided.", {
+        target_page: target_page_field(),
         source_id: z
             .string()
             .describe("Source ID of a cell. It is represented by `id` attribute."),
@@ -29,5 +31,5 @@ export const registerAddEdgeTool = (server, context) => {
             .string()
             .optional()
             .describe("ID of the parent cell. If provided, the new edge will be created as a child of this cell. If omitted, the edge is created at the diagram root level."),
-    }, default_tool(TOOL_add_edge, context));
+    }, default_tool(TOOL_add_edge, context, { queue: true }));
 };

package/build/tools/add-rectangle.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_add_rectangle = "add-rectangle";
 export const registerAddRectangleTool = (server, context) => {
-    server.tool(TOOL_add_rectangle, "This tool allows you to add new Rectangle vertex cell (object) on the current page of a Draw.io diagram. It accepts multiple optional input parameter.", {
+    server.tool(TOOL_add_rectangle, "This tool allows you to add a new Rectangle vertex cell on the target page of the current Draw.io document.", {
+        target_page: target_page_field(),
         x: z
             .number()
             .optional()
@@ -37,5 +39,5 @@ export const registerAddRectangleTool = (server, context) => {
             .string()
             .optional()
             .describe("ID of the parent cell. If provided, the new rectangle will be created as a child of this cell. If omitted, the rectangle is created at the diagram root level."),
-    }, default_tool(TOOL_add_rectangle, context));
+    }, default_tool(TOOL_add_rectangle, context, { queue: true }));
 };

package/build/tools/copy-page.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
+export const TOOL_copy_page = "copy-page";
+export const registerCopyPageTool = (server, context) => {
+    server.tool(TOOL_copy_page, "Creates a copy of an existing page in the target/current Draw.io document, appends the copy to the end of the page list, and returns the copied page metadata. When possible, the previously visible page is restored after the copy is created.", {
+        page: target_page_field().describe("Source page selector for the page to copy. Provide exactly one of `{ index }` or `{ id }`."),
+        name: z
+            .string()
+            .optional()
+            .describe("Optional name for the copied page."),
+    }, default_tool(TOOL_copy_page, context, { queue: true }));
+};

package/build/tools/create-layer.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_create_layer = "create-layer";
 export const registerCreateLayerTool = (server, context) => {
-    server.tool(TOOL_create_layer, "Creates a new layer in the diagram.", {
+    server.tool(TOOL_create_layer, "Creates a new layer on the target page.", {
+        target_page: target_page_field(),
         name: z.string().describe("Name for the new layer"),
-    }, default_tool(TOOL_create_layer, context));
+    }, default_tool(TOOL_create_layer, context, { queue: true }));
 };

package/build/tools/create-page.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { default_tool } from "../tool.js";
+export const TOOL_create_page = "create-page";
+export const registerCreatePageTool = (server, context) => {
+    server.tool(TOOL_create_page, "Appends a new blank page to the current Draw.io document without changing the visible page when the runtime supports background page insertion.", {
+        name: z.string().describe("Name for the new page"),
+    }, default_tool(TOOL_create_page, context, { queue: true }));
+};

package/build/tools/delete-cell-by-id.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_delete_cell_by_id = "delete-cell-by-id";
 export const registerDeleteCellByIdTool = (server, context) => {
-    server.tool(TOOL_delete_cell_by_id, "Deletes a cell, whether it is a vertex or edge.", {
+    server.tool(TOOL_delete_cell_by_id, "Deletes a cell from the target page, whether it is a vertex or edge.", {
+        target_page: target_page_field(),
         cell_id: z
             .string()
             .describe("The ID of a cell to delete. The cell can be either vertex or edge. The ID is located in `id` attribute."),
-    }, default_tool(TOOL_delete_cell_by_id, context));
+    }, default_tool(TOOL_delete_cell_by_id, context, { queue: true }));
 };

package/build/tools/edit-cell.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_edit_cell = "edit-cell";
 export const registerEditCellTool = (server, context) => {
     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.", {
+        target_page: target_page_field(),
         cell_id: z
             .string()
             .describe("Identifier (`id` attribute) of the cell to update. Applies to vertex/shape cells."),
@@ -24,5 +26,5 @@ export const registerEditCellTool = (server, context) => {
             .string()
             .optional()
             .describe("Replace the cell's style string (semi-colon separated `key=value` pairs)."),
-    }, default_tool(TOOL_edit_cell, context));
+    }, default_tool(TOOL_edit_cell, context, { queue: true }));
 };

package/build/tools/edit-edge.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_edit_edge = "edit-edge";
 export const registerEditEdgeTool = (server, context) => {
     server.tool(TOOL_edit_edge, "Update properties of an existing edge by its ID. Only provided fields are modified; unspecified properties remain unchanged. Supports setting waypoints for edge geometry control.", {
+        target_page: target_page_field(),
         cell_id: z
             .string()
             .describe("Identifier (`id` attribute) of the edge cell to update. The ID must reference an edge."),
@@ -26,5 +28,5 @@ export const registerEditEdgeTool = (server, context) => {
         }))
             .optional()
             .describe("Array of {x, y} waypoints to set as edge geometry control points. Replaces existing waypoints. Use an empty array to clear waypoints."),
-    }, default_tool(TOOL_edit_edge, context));
+    }, default_tool(TOOL_edit_edge, context, { queue: true }));
 };

package/build/tools/export-diagram.js

@@ -1,9 +1,11 @@
 import { writeFileSync, existsSync } from "node:fs";
 import { z } from "zod";
 import { export_tool_handler } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_export_diagram = "export-diagram";
 export const registerExportDiagramTool = (server, context) => {
-    server.tool(TOOL_export_diagram, "Export the current diagram as SVG, PNG, or XML. Returns the diagram data as base64 (PNG) or text (SVG/XML). Optionally saves to a file.", {
+    server.tool(TOOL_export_diagram, "Export the target page or current diagram as SVG, PNG, or XML. Returns the diagram data as base64 (PNG) or text (SVG/XML). Optionally saves to a file.", {
+        target_page: target_page_field(),
         format: z
             .enum(["svg", "png", "xml"])
             .describe("Export format: svg for vector graphics, png for raster image, xml for raw diagram data"),
@@ -56,13 +58,15 @@ export const registerExportDiagramTool = (server, context) => {
             .enum(["selection", "page", "diagram"])
             .optional()
             .default("diagram")
-            .describe("What to export: 'selection' for selected cells only, 'page' for current page, 'diagram' for entire model"),
+            .describe("What to export: 'selection' for selected cells only, 'page' for the target page, 'diagram' for the entire model"),
         output_path: z
             .string()
             .optional()
             .describe("Absolute file path to save the exported file (must be an absolute path)"),
     }, async (args, _extra) => {
-        const exportHandler = export_tool_handler(TOOL_export_diagram, context);
+        const exportHandler = export_tool_handler(TOOL_export_diagram, context, {
+            queue: true,
+        });
         const result = await exportHandler(args, _extra);
         if (args.output_path) {
             const path = await import("node:path");

package/build/tools/get-active-layer.js

@@ -1,5 +1,8 @@
 import { default_tool } from "../tool.js";
+import { target_page_field } from "./shared.js";
 export const TOOL_get_active_layer = "get-active-layer";
 export const registerGetActiveLayerTool = (server, context) => {
-    server.tool(TOOL_get_active_layer, "Gets the currently active layer information.", {}, default_tool(TOOL_get_active_layer, context));
+    server.tool(TOOL_get_active_layer, "Gets the currently active layer information for the target page. If the target page is not currently visible, Draw.io may switch the visible page first because active-layer state is UI-bound.", {
+        target_page: target_page_field(),
+    }, default_tool(TOOL_get_active_layer, context, { queue: true }));
 };

package/build/tools/get-current-page.js

@@ -0,0 +1,5 @@
+import { default_tool } from "../tool.js";
+export const TOOL_get_current_page = "get-current-page";
+export const registerGetCurrentPageTool = (server, context) => {
+    server.tool(TOOL_get_current_page, "Gets the currently visible page metadata, including index, id, name, and whether it is active.", {}, default_tool(TOOL_get_current_page, context, { queue: true }));
+};