feat(mcp): add load_diagram tool to load .drawio files into the session (#893)

* feat(mcp): add load_diagram tool to load .drawio files into the session

Loading a file previously required the agent to read the file itself and
pass the entire XML through create_new_diagram - wasteful for large
diagrams and impossible for draw.io's compressed save format.

load_diagram takes a file path; the server reads it, decompresses any
compressed pages (base64 -> raw deflate -> URI-decode, per page), and
replaces the session document. The loaded XML is deliberately NOT marked
as seen by the edit gate: the model only supplied a path, so it must
call get_diagram once before editing.

* chore(mcp): version 0.2.3

* fix(mcp): report package.json version in the MCP handshake

The McpServer metadata version was a separate hardcoded string that
never matched the published version (stuck at 0.1.2, then 0.3.0 while
npm shipped 0.2.x). Read it from package.json at startup instead —
works from both src/ (tsx) and dist/ (published build).

packages/mcp-server/src/index.ts

@@ -36,6 +36,7 @@ class XMLSerializerPolyfill {
 }
 ;(globalThis as any).XMLSerializer = XMLSerializerPolyfill
 
+import { createRequire } from "node:module"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import open from "open"
@@ -55,6 +56,7 @@ import {
     startHttpServer,
     waitForSync,
 } from "./http-server.js"
+import { parseDrawioFileContent } from "./load-diagram.js"
 import { log } from "./logger.js"
 import {
     addPageToDoc,
@@ -88,10 +90,17 @@ let currentSession: {
     lastSeenXml: string
 } | null = null
 
-// Create MCP server
+// Create MCP server. The version reported in the MCP handshake is read from
+// package.json so it can never drift from the published npm version again
+// (it sat hardcoded at stale values for most of this package's history).
+// Both src/ (tsx dev) and dist/ (published build) live one level below the
+// package root, so the relative path works in either runtime.
+const require = createRequire(import.meta.url)
+const packageVersion: string = require("../package.json").version
+
 const server = new McpServer({
     name: "next-ai-drawio",
-    version: "0.3.0",
+    version: packageVersion,
 })
 
 // Shared Zod schema fragment for page-targeting parameters.
@@ -164,6 +173,10 @@ server.prompt(
 1. Call start_session to open the browser preview
 2. Use create_new_diagram with either a bare <mxGraphModel> (single page) or a full <mxfile> with one or more <diagram> children (multi-page)
 
+## Opening an Existing .drawio File
+- Use load_diagram with the file path — the server reads and decompresses the file itself; don't read it and pass the XML through create_new_diagram
+- After loading, call get_diagram once before editing (you haven't seen the file's cell IDs yet)
+
 ## Working with Multiple Pages
 - Use list_pages to discover existing pages (id, name, index)
 - Use add_page to append a new page (without losing existing ones — unlike create_new_diagram which REPLACES everything)
@@ -421,6 +434,123 @@ COMMON STYLES:
     },
 )
 
+// Tool: load_diagram
+server.registerTool(
+    "load_diagram",
+    {
+        description:
+            "Load a .drawio file from disk into the current session, REPLACING the entire diagram (all pages). " +
+            "The server reads the file directly — you do NOT need to read the file yourself or pass its XML through create_new_diagram. " +
+            "Handles both plain-XML and draw.io's compressed save format.\n\n" +
+            "After loading, call get_diagram before edit_diagram — you haven't seen the file's cell IDs or structure yet.",
+        inputSchema: {
+            path: z
+                .string()
+                .describe(
+                    "Path to the .drawio file to load (e.g., ./diagram.drawio)",
+                ),
+        },
+    },
+    async ({ path }) => {
+        try {
+            if (!currentSession) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: No active session. Please call start_session first.",
+                        },
+                    ],
+                    isError: true,
+                }
+            }
+
+            const fs = await import("node:fs/promises")
+            const nodePath = await import("node:path")
+            const absolutePath = nodePath.resolve(path)
+
+            let content: string
+            try {
+                content = await fs.readFile(absolutePath, "utf-8")
+            } catch (e) {
+                const msg = e instanceof Error ? e.message : String(e)
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: Cannot read file ${absolutePath}: ${msg}`,
+                        },
+                    ],
+                    isError: true,
+                }
+            }
+
+            const loaded = parseDrawioFileContent(content)
+            if (!loaded.ok) {
+                return {
+                    content: [{ type: "text", text: `Error: ${loaded.error}` }],
+                    isError: true,
+                }
+            }
+            const xml = loaded.xml
+
+            log.info(
+                `Loading diagram from ${absolutePath} (${xml.length} chars)`,
+            )
+
+            // Save the user's current state before replacing (same flow as
+            // create_new_diagram).
+            const browserState = getState(currentSession.id)
+            if (browserState?.xml) {
+                currentSession.xml = browserState.xml
+            }
+            if (currentSession.xml) {
+                addHistory(
+                    currentSession.id,
+                    currentSession.xml,
+                    browserState?.svg || "",
+                )
+            }
+
+            currentSession.xml = xml
+            currentSession.version++
+            setState(currentSession.id, xml)
+            // Deliberately NOT marking the loaded XML as seen: the model only
+            // supplied a path, so it doesn't know the file's cell IDs. The
+            // edit gate will require one get_diagram before edits.
+            currentSession.lastSeenXml = ""
+
+            addHistory(currentSession.id, xml, "")
+
+            const doc = parseMxfile(xml)
+            const pages = doc ? listPagesFromDoc(doc) : []
+            const pageSummary =
+                pages.length > 0
+                    ? `Pages (${pages.length}): ${pages.map((p) => `[${p.index}] id=${p.id} name="${p.name}" cells=${p.cellCount}`).join(" | ")}`
+                    : "no pages parsed"
+
+            log.info(`Diagram loaded from file (${pageSummary})`)
+
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Diagram loaded from ${absolutePath}!\n\nThe diagram is now visible in your browser.\n\n${pageSummary}\n\nCall get_diagram before edit_diagram — you haven't seen this file's cell IDs yet.`,
+                    },
+                ],
+            }
+        } catch (error) {
+            const message =
+                error instanceof Error ? error.message : String(error)
+            log.error("load_diagram failed:", message)
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            }
+        }
+    },
+)
+
 // Tool: edit_diagram
 server.registerTool(
     "edit_diagram",

packages/mcp-server/src/load-diagram.ts

@@ -0,0 +1,101 @@
+/**
+ * File-loading helpers for the load_diagram tool.
+ *
+ * A .drawio file is an <mxfile> whose <diagram> children hold each page's
+ * <mxGraphModel> either as plain XML or — draw.io's default save format —
+ * compressed: encodeURIComponent(xml) → raw deflate → base64 as the
+ * diagram's text content. The rest of the server assumes plain XML inside
+ * every <diagram>, so loading decompresses all pages up front.
+ */
+import { inflateRawSync } from "node:zlib"
+import { DOMParser } from "linkedom"
+import {
+    isMxFile,
+    isMxGraphModel,
+    normalizeToMxfile,
+    parseMxfile,
+    serializeMxfile,
+} from "./pages.js"
+
+export type LoadResult =
+    | { ok: true; xml: string }
+    | { ok: false; error: string }
+
+/**
+ * Decode one compressed page body (base64 → raw deflate → URI-decode).
+ * Returns null if the text isn't in that format.
+ */
+export function decompressPageContent(compressed: string): string | null {
+    try {
+        const inflated = inflateRawSync(
+            Buffer.from(compressed.trim(), "base64"),
+        ).toString("utf-8")
+        try {
+            return decodeURIComponent(inflated)
+        } catch {
+            // Not URI-encoded (older files) — the inflated text is the XML.
+            return inflated
+        }
+    } catch {
+        return null
+    }
+}
+
+/**
+ * Parse the content of a .drawio file into the canonical session shape:
+ * an <mxfile> whose every page holds plain <mxGraphModel> XML. Accepts a
+ * bare <mxGraphModel> (wrapped into a one-page mxfile) and decompresses
+ * any compressed pages.
+ */
+export function parseDrawioFileContent(content: string): LoadResult {
+    const trimmed = content.trim()
+    if (!trimmed) return { ok: false, error: "File is empty." }
+
+    if (isMxGraphModel(trimmed)) {
+        const normalized = normalizeToMxfile(trimmed)
+        return normalized
+            ? { ok: true, xml: normalized }
+            : { ok: false, error: "Failed to parse <mxGraphModel> XML." }
+    }
+    if (!isMxFile(trimmed)) {
+        return {
+            ok: false,
+            error: "Not a draw.io file: expected an <mxfile> or <mxGraphModel> root element.",
+        }
+    }
+    const doc = parseMxfile(trimmed)
+    if (!doc) return { ok: false, error: "Failed to parse <mxfile> XML." }
+
+    let decompressedAny = false
+    for (const d of Array.from(doc.querySelectorAll("diagram"))) {
+        if (d.querySelector("mxGraphModel")) continue
+        const text = (d.textContent || "").trim()
+        if (!text) continue // an empty page is valid
+        const pageLabel =
+            d.getAttribute("name") || d.getAttribute("id") || "unnamed"
+        const xml = decompressPageContent(text)
+        if (!xml || !isMxGraphModel(xml)) {
+            return {
+                ok: false,
+                error: `Page "${pageLabel}" has content that is neither plain <mxGraphModel> XML nor draw.io's compressed format.`,
+            }
+        }
+        const inner = new DOMParser().parseFromString(xml, "text/xml")
+        if (
+            inner.querySelector("parsererror") ||
+            inner.documentElement?.tagName !== "mxGraphModel"
+        ) {
+            return {
+                ok: false,
+                error: `Page "${pageLabel}" decompressed but its XML failed to parse.`,
+            }
+        }
+        d.textContent = ""
+        d.appendChild(
+            doc.importNode(inner.documentElement as unknown as Node, true),
+        )
+        decompressedAny = true
+    }
+    // Nothing changed — keep the file's own serialisation.
+    return { ok: true, xml: decompressedAny ? serializeMxfile(doc) : trimmed }
+}