feat(mcp): add multi-page (mxfile) support to MCP server (#862)

* feat(mcp): add multi-page (mxfile) support

The MCP server's write path could only address a single drawio page even
though the underlying .drawio file format and the embedded editor both
natively support multi-page documents. A user asking for "a second page
with a CNN diagram" would hit the validator with the error
"Expected closing tag </root> but found </mxCell>" because the validator
assumed input was a bare <mxGraphModel> and could not walk past the
<mxfile><diagram>...</diagram></mxfile> wrapper.

This patch closes the gap end to end:

* New helper module `pages.ts` centralises page CRUD (normalize, parse,
  list, find, add, rename, delete) so every layer agrees that the
  canonical in-memory shape is always <mxfile>. normalizeToMxfile and
  addPageToDoc both strip any leading <?xml ?> declaration before
  embedding a fragment inside <diagram> (the declaration is only valid
  at document start). addPageToDoc explicitly rejects full <mxfile>
  inputs so a caller cannot accidentally nest a document inside a page.
* `xml-validation.ts` now detects an <mxfile> root and scopes the
  duplicate-id check per <diagram>. The legacy regex check would
  otherwise reject every multi-page doc, because cells "0" and "1"
  repeat in each page's <root> by design. The DOM-parse path is gated
  by a cheap regex pre-check so legacy bare <mxGraphModel> callers
  don't pay any extra cost. The autoFix duplicate-id rename step is
  also guarded against mxfile inputs — renaming those sentinel cells
  would silently break drawio's parent references.
* `diagram-operations.ts` accepts an optional PageSelector. For
  <mxfile> input it resolves the page first and scopes all
  querySelectorAll calls to that page's <root>, so a delete on page 2's
  cell "2" no longer touches page 1's cell "2".
* `create_new_diagram` accepts either a bare <mxGraphModel> (legacy,
  auto-wrapped into a single-page mxfile) or a full <mxfile> with N
  diagrams. All existing single-page callers keep working unchanged.
* `edit_diagram`, `get_diagram`, and `export_diagram` gain optional
  `page_id` / `page_name` / `page_index` parameters. When omitted they
  target the first page — the "active by convention" default. Tool
  handlers with all-optional input schemas coalesce missing arguments
  via `input ?? {}` so a no-args MCP invocation can't crash on
  destructure before reaching the session-existence check.
* New tools: `list_pages`, `add_page`, `rename_page`, `delete_page`.
* Page-targeted PNG/SVG export uses a "load + export + restore" dance:
  the server projects the target page into a single-page <mxfile>,
  pushes it into the transient state so the browser reloads the iframe
  with just that page, waits for drawio to render (~3s), triggers the
  export, captures the data, and then restores the original multi-page
  document. The dance is wrapped in `try/finally` so the restore runs
  unconditionally — even if an exception is thrown mid-dance, the
  user's multi-tab view is recovered before the function returns.
  The earlier attempt to use drawio's `selectPage` postMessage was a
  no-op because drawio's JSON embed protocol does not expose that
  action — silently exporting whatever tab happened to be active. The
  load-export-restore approach trades a brief visible tab-flicker for
  correctness: the exported image is guaranteed to match the requested
  page.
* Tool description strings reflect the multi-page semantics so the LLM
  client learns the new contract.
* Package version bumped 0.2.0 → 0.3.0 (additive surface — four new
  tools, three extended input schemas, canonical XML shape change).
* CI: `.github/workflows/test.yml` gains an explicit install + vitest
  run for the mcp-server package so the new multi-page invariants are
  covered by automation, not just local runs.

Backward compatibility: every existing single-page caller continues to
work without modification. The session.xml shape is normalised on every
write, removing the wrapper-injection hack from the .drawio download
path.

Tests: 43 unit tests under `packages/mcp-server/tests/multi-page.test.ts`
pin the validator's mxfile path, the page-scoped operations, the XML
declaration-prefix handling for both normalizeToMxfile and addPageToDoc,
addPageToDoc's rejection of full <mxfile> inputs, the single-page
projection used by export_diagram (a direct regression test for the
selectPage bug — two distinct page selectors must produce visually
different projections), and the Transformer + CNN motivating scenario.
A `tests/smoke.mjs` smoke test drives the built `dist/index.js` over
JSON-RPC and asserts all 9 tools register with the right input schemas.
Root vitest suite (107 tests) still green.

* fix(mcp): rewrite page-targeted export browser-side; harden edit/get

The page-targeted PNG/SVG export never worked: export_diagram swapped the
live session to a single-page projection, slept 3s, then wrote the export
flag onto a state object that setState() had already replaced in the store
Map — so the browser never saw the request and every such export timed out.
The swap+restore also clobbered concurrent edits.

Move the projection entirely browser-side: requestExport() hands a single
-page <mxfile> to the bridge via state.exportXml; the bridge loads it,
lets draw.io render, exports, then reloads the user's real document. The
canonical session state is never mutated, so there is no restore race and
no fixed-delay guessing. The export poll now re-reads the live store entry
each tick instead of a captured reference. autosave is suppressed and the
version-bump reload is skipped while a projection is on screen; if no real
document was captured, restore forces a server reload rather than leaving
the iframe stuck on the projection.

Also:
- edit_diagram now returns isError on a page-level failure (selector matched
  no page / page has no <root>) instead of reporting success-with-warnings
  and persisting a no-op; the pre-edit history snapshot is taken only after
  that gate so a failed edit leaves no phantom undo entry.
- edit_diagram/get_diagram re-normalise browser-pushed xml to mxfile so a
  bare <mxGraphModel> can't silently strip a multi-page document.
- get_diagram now errors (instead of silently returning the full doc) when a
  selector is given but the session isn't a parseable mxfile.
- page_id / page_name / add_page.id get .min(1) so empty strings can't
  silently target the first page.
- Extract pages.ts:projectPage(), collapsing three copies of the
  parse→find→serialise projection logic in index.ts.
- Replace the never-in-CI tests/smoke.mjs with tests/server-wiring.test.ts,
  which boots the server from source via tsx and runs under the existing
  vitest CI step.

* chore(mcp): set version to 0.2.1 for release

---------

Co-authored-by: dayuan.jiang <jdy.toh@gmail.com>

packages/mcp-server/tests/server-wiring.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Server-wiring test: boot the actual MCP stdio server (from source via tsx)
+ * and drive it the way a real MCP client does — initialize handshake,
+ * tools/list — to catch registration/schema regressions that the unit tests
+ * (which import helpers directly) can't see.
+ *
+ * This replaces the old standalone tests/smoke.mjs, which spawned the BUILT
+ * dist/index.js and was therefore never run in CI (CI doesn't build this
+ * package before testing). Running from source via tsx means it executes as
+ * part of the normal `vitest run`.
+ *
+ * We deliberately do NOT call start_session — it would open a real browser
+ * window via open(). The browser bridge is covered by the Playwright e2e suite.
+ */
+
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const entry = path.resolve(__dirname, "..", "src", "index.ts")
+const tsxBin = path.resolve(
+    __dirname,
+    "..",
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "tsx.cmd" : "tsx",
+)
+
+const EXPECTED_TOOLS = [
+    "start_session",
+    "create_new_diagram",
+    "edit_diagram",
+    "get_diagram",
+    "export_diagram",
+    "list_pages",
+    "add_page",
+    "rename_page",
+    "delete_page",
+]
+
+let proc: ChildProcessWithoutNullStreams
+let stdoutBuf = ""
+const pending = new Map<
+    number,
+    { resolve: (m: any) => void; reject: (e: Error) => void; timeout: any }
+>()
+let nextId = 1
+
+function send(method: string, params: unknown, isNotification = false) {
+    const msg: Record<string, unknown> = { jsonrpc: "2.0", method, params }
+    if (!isNotification) msg.id = nextId++
+    proc.stdin.write(`${JSON.stringify(msg)}\n`)
+    if (isNotification) return Promise.resolve(undefined)
+    return new Promise<any>((resolve, reject) => {
+        const id = msg.id as number
+        const timeout = setTimeout(() => {
+            pending.delete(id)
+            reject(new Error(`Timed out waiting for response to ${method}`))
+        }, 15000)
+        pending.set(id, { resolve, reject, timeout })
+    })
+}
+
+beforeAll(async () => {
+    proc = spawn(tsxBin, [entry], {
+        stdio: ["pipe", "pipe", "pipe"],
+    }) as ChildProcessWithoutNullStreams
+
+    proc.stdout.on("data", (chunk: Buffer) => {
+        stdoutBuf += chunk.toString()
+        const lines = stdoutBuf.split("\n")
+        stdoutBuf = lines.pop() || ""
+        for (const line of lines) {
+            const trimmed = line.trim()
+            if (!trimmed) continue
+            let msg: any
+            try {
+                msg = JSON.parse(trimmed)
+            } catch {
+                // Non-JSON-RPC log line — ignore.
+                continue
+            }
+            const p = msg.id !== undefined ? pending.get(msg.id) : undefined
+            if (p) {
+                clearTimeout(p.timeout)
+                pending.delete(msg.id)
+                p.resolve(msg)
+            }
+        }
+    })
+
+    const initResp = await send("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "wiring-test", version: "0.0.0" },
+    })
+    expect(initResp.error, JSON.stringify(initResp.error)).toBeUndefined()
+    expect(initResp.result?.serverInfo?.name).toBeTruthy()
+    await send("notifications/initialized", {}, true)
+}, 30000)
+
+afterAll(() => {
+    proc?.kill("SIGTERM")
+})
+
+describe("MCP server wiring", () => {
+    it("registers all nine multi-page tools", async () => {
+        const resp = await send("tools/list", {})
+        expect(resp.error, JSON.stringify(resp.error)).toBeUndefined()
+        const names: string[] = (resp.result?.tools ?? []).map(
+            (t: { name: string }) => t.name,
+        )
+        for (const expected of EXPECTED_TOOLS) {
+            expect(names, `missing tool: ${expected}`).toContain(expected)
+        }
+    })
+
+    it("advertises page-selector params on edit_diagram", async () => {
+        const resp = await send("tools/list", {})
+        const edit = resp.result.tools.find(
+            (t: { name: string }) => t.name === "edit_diagram",
+        )
+        const props = edit?.inputSchema?.properties ?? {}
+        expect(props.page_id).toBeTruthy()
+        expect(props.page_name).toBeTruthy()
+        expect(props.page_index).toBeTruthy()
+    })
+
+    it("advertises name/id/xml on add_page", async () => {
+        const resp = await send("tools/list", {})
+        const addPage = resp.result.tools.find(
+            (t: { name: string }) => t.name === "add_page",
+        )
+        const props = addPage?.inputSchema?.properties ?? {}
+        expect(props.name).toBeTruthy()
+        expect(props.id).toBeTruthy()
+        expect(props.xml).toBeTruthy()
+    })
+})