drawio-mcp-server 2.2.0 → 2.3.0

package/README.md

@@ -9,12 +9,16 @@ 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)
+- Claude Code plugin: `/plugin marketplace add lgazo/drawio-mcp-server` then `/plugin install drawio`, with `/drawio-open` and `/drawio-status` slash commands ![v2.3.0](https://img.shields.io/badge/v2.3.0-blue)
+- `npx drawio-mcp-server install <host>` writes the MCP config for `claude-code`, `claude-desktop`, `codex`, `zed`, `opencode`, or `all` ![v2.3.0](https://img.shields.io/badge/v2.3.0-blue)
+- Document persistence tools: `set-document-title` and `save-document` ![v2.3.0](https://img.shields.io/badge/v2.3.0-blue)
+- Draw.io library API version compatibility mechanism ![v2.2.0](https://img.shields.io/badge/v2.2.0-blue)
+- Enable Draw.io MCP in IFrames
+- AWS, GCP, Azure, Cisco19, and CiscoSafe stencils auto-discovered at runtime from drawio's sidebar
+- Multi-document targeting with `list-documents` and `target_document` selectors for multi-tab workflows
+- Multi-page targeting with required `target_page` selectors for page-scoped tools
+- Per-document FIFO serialization for live operations, so multiple agents can work on different files safely
+- Page management tools: `list-pages`, `get-current-page`, `create-page`, `copy-page`, `rename-page`
 - 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)
@@ -58,10 +62,15 @@ No additional requirements - runs out of the box with `--editor` flag.
 
 ### 1. Configure your MCP host
 
-Add the server to your MCP client configuration:
+**Fastest path:**
+
+- **Claude Code:** `/plugin marketplace add lgazo/drawio-mcp-server` then `/plugin install drawio`.
+- **Any other host:** `npx drawio-mcp-server install <host>` where `<host>` is `claude-code`, `claude-desktop`, `codex`, `zed`, `opencode`, or `all`.
+
+See [docs/PLUGINS.md](./docs/PLUGINS.md) for the full reference, flags, and uninstall, and [docs/release.md](./docs/release.md) for how releases are cut.
 
 <details>
-  <summary>Claude Desktop</summary>
+  <summary>Manual install (JSON snippet, Claude Desktop example)</summary>
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -75,63 +84,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
   }
 }
 ```
-</details>
-
-<details>
-  <summary>Claude Code</summary>
-
-```sh
-claude mcp add-json drawio '{"type":"stdio","command":"npx","args":["-y","drawio-mcp-server","--editor"]}'
-```
-</details>
-
-<details>
-  <summary>Zed</summary>
-
-Add to `~/.config/zed/settings.json`:
-
-```json
-{
-  "context_servers": {
-    "drawio": {
-      "command": "npx",
-      "args": ["-y", "drawio-mcp-server", "--editor"],
-      "env": {}
-    }
-  }
-}
-```
-</details>
-
-<details>
-  <summary>Codex</summary>
-
-Edit `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.drawio]
-command = "npx"
-args = ["-y", "drawio-mcp-server", "--editor"]
-```
-</details>
 
-<details>
-  <summary>OpenCode</summary>
-
-Add to `opencode.json` in your project root or `~/.config/opencode/opencode.json`:
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "drawio": {
-      "type": "local",
-      "command": ["npx", "-y", "drawio-mcp-server", "--editor"],
-      "enabled": true
-    }
-  }
-}
-```
 </details>
 
 For other MCP clients and detailed configuration (including pnpm options), see [Configuration](./CONFIG.md).
@@ -223,11 +176,11 @@ See [DESKTOP.md](./DESKTOP.md) for the full setup steps and the current limitati
 
 ## Star History
 
-<a href="https://star-history.com/#lgazo/drawio-mcp-server&Date">
+<a href="https://star-history.dera.page/#lgazo/drawio-mcp-server&type=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" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=lgazo/drawio-mcp-server&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=lgazo/drawio-mcp-server&type=Date" />
+   <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=lgazo/drawio-mcp-server&type=Date" />
  </picture>
 </a>
 

package/build/index.js

@@ -12,7 +12,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, existsSync, statSync, readdirSync, realpathSync, } from "node:fs";
 import { WebSocket, WebSocketServer } from "ws";
-const VERSION = process.env.npm_package_version ?? "2.2.0";
+const VERSION = process.env.npm_package_version ?? "2.3.0";
 import { buildConfig, defaultConfig, hasFlag, shouldShowHelp, getHttpFeatureConfig, } from "./config.js";
 import { installDesktopPlugin } from "./install-desktop-plugin.js";
 import { bus_reply_stream, bus_request_stream, } from "./types.js";
@@ -28,6 +28,17 @@ import { target_document_field } from "./tools/shared.js";
 import { resolveTlsMaterial } from "./tls/index.js";
 import { handleCompatReport } from "./drawio-compat/log-report.js";
 const fatalLog = create_console_logger();
+if (process.argv[2] === "install") {
+    const { runInstall } = await import("./install/index.js");
+    try {
+        const code = await runInstall(process.argv.slice(3));
+        process.exit(code);
+    }
+    catch (err) {
+        fatalLog.log("error", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 /**
  * Display help message and exit
  */
@@ -223,6 +234,20 @@ async function startHttpServer(createServer, disposeMcpServer, log, httpPort, co
             }
             : {}),
     });
+    // `serve()` calls `listen()` synchronously; wait for the outcome so a failed
+    // bind surfaces as a clean, fatal error instead of an unhandled 'error'
+    // event (or, worse, silence).
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", (error) => {
+            reject(new Error(`Failed to bind HTTP server on port ${httpPort}: ${error instanceof Error ? error.message : String(error)}`, { cause: error }));
+        });
+        if (httpServer.listening) {
+            resolve();
+        }
+        else {
+            httpServer.once("listening", () => resolve());
+        }
+    });
     const listeningPort = httpPort === 0
         ? (httpServer.address()?.port ?? httpPort)
         : httpPort;
@@ -877,7 +902,21 @@ async function main() {
             void shutdown("stdin-close");
         });
     }
-    await app.startHttpServer(config.httpPort, config, features);
+    // Only open the HTTP listener when something will actually be served on
+    // it. A stdio-only run previously bound port 3000 unconditionally,
+    // colliding with common dev servers while serving nothing useful
+    // (see upstream issue #66).
+    if (features.enableMcp || features.enableEditor) {
+        await app.startHttpServer(config.httpPort, config, features);
+    }
+    else {
+        app.log.debug("HTTP server not started: no HTTP surface enabled (stdio-only run). Use --transport http or --editor to serve HTTP.");
+        const httpPortExplicit = cliArgs.includes("--http-port") ||
+            Boolean(process.env.DRAWIO_MCP_HTTP_PORT?.length);
+        if (httpPortExplicit) {
+            app.log.log("warning", `--http-port was set but no HTTP surface is enabled; port ${config.httpPort} stays free. Use --transport http or --editor to serve HTTP.`);
+        }
+    }
     app.log.debug(`Draw.io MCP Server running on ${config.transports}`);
 }
 const isMainModule = process.argv[1]

package/build/install/config-io.js

@@ -0,0 +1,21 @@
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+import { createPatch } from "diff";
+export async function atomicWrite(target, contents) {
+    const dir = dirname(target);
+    const tmp = join(dir, `.${basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(tmp, contents, "utf8");
+    await fs.rename(tmp, target);
+}
+export async function ensureBackup(target) {
+    if (!existsSync(target))
+        return null;
+    const bak = `${target}.bak-${Date.now()}`;
+    const contents = await fs.readFile(target, "utf8");
+    await fs.writeFile(bak, contents, "utf8");
+    return bak;
+}
+export function unifiedDiff(oldText, newText, label) {
+    return createPatch(label, oldText, newText, "", "", { context: 3 });
+}

package/build/install/config-io.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, readdirSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { atomicWrite, ensureBackup, unifiedDiff } from "./config-io.js";
+describe("config-io", () => {
+    let dir;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "drawio-install-"));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("atomicWrite writes contents and leaves no tmp file", async () => {
+        const target = join(dir, "cfg.json");
+        await atomicWrite(target, '{\n  "a": 1\n}\n');
+        expect(readFileSync(target, "utf8")).toBe('{\n  "a": 1\n}\n');
+        expect(readdirSync(dir).filter((f) => f.startsWith(".cfg.json."))).toEqual([]);
+    });
+    it("ensureBackup copies once and returns backup path", async () => {
+        const target = join(dir, "cfg.json");
+        writeFileSync(target, "orig");
+        const bak = await ensureBackup(target);
+        expect(bak).toMatch(/cfg\.json\.bak-\d+$/);
+        expect(readFileSync(bak, "utf8")).toBe("orig");
+    });
+    it("ensureBackup returns null when file missing", async () => {
+        expect(await ensureBackup(join(dir, "nope.json"))).toBeNull();
+    });
+    it("unifiedDiff produces a diff header referencing the label", () => {
+        const d = unifiedDiff("a\n", "b\n", "cfg.json");
+        expect(d).toContain("--- cfg.json");
+        expect(d).toContain("+++ cfg.json");
+        expect(d).toContain("-a");
+        expect(d).toContain("+b");
+    });
+});

package/build/install/hosts/claude-code.js

@@ -0,0 +1,37 @@
+import { existsSync, promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { applyEdits, modify } from "jsonc-parser";
+export const claudeCodeAdapter = {
+    id: "claude-code",
+    displayName: "Claude Code (user scope)",
+    defaultPaths() {
+        return [join(homedir(), ".claude.json")];
+    },
+    async detect() {
+        return existsSync(claudeCodeAdapter.defaultPaths()[0])
+            ? "installed"
+            : "absent";
+    },
+    async read(path) {
+        return existsSync(path) ? fs.readFile(path, "utf8") : "";
+    },
+    merge(source, entry, name, { uninstall }) {
+        const text = source.trim() === "" ? "{}\n" : source;
+        const value = uninstall
+            ? undefined
+            : {
+                type: entry.transport,
+                command: entry.command,
+                args: entry.args,
+                ...(Object.keys(entry.env).length ? { env: entry.env } : {}),
+            };
+        const edits = modify(text, ["mcpServers", name], value, {
+            formattingOptions: { insertSpaces: true, tabSize: 2 },
+        });
+        return applyEdits(text, edits);
+    },
+    diffLabel() {
+        return claudeCodeAdapter.defaultPaths()[0];
+    },
+};

package/build/install/hosts/claude-code.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "@jest/globals";
+import { claudeCodeAdapter } from "./claude-code.js";
+const ENTRY = {
+    command: "npx",
+    args: ["-y", "drawio-mcp-server", "--editor"],
+    env: {},
+    transport: "stdio",
+};
+describe("claudeCodeAdapter.merge", () => {
+    it("adds mcpServers.drawio to a fresh file", () => {
+        const out = claudeCodeAdapter.merge("", ENTRY, "drawio", {
+            uninstall: false,
+        });
+        const parsed = JSON.parse(out);
+        expect(parsed.mcpServers.drawio).toEqual({
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "drawio-mcp-server", "--editor"],
+        });
+    });
+    it("uninstall removes only that key", () => {
+        const source = JSON.stringify({
+            mcpServers: {
+                drawio: { type: "stdio", command: "old" },
+                other: { command: "x" },
+            },
+        });
+        const out = claudeCodeAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: true,
+        });
+        const parsed = JSON.parse(out);
+        expect(parsed.mcpServers.drawio).toBeUndefined();
+        expect(parsed.mcpServers.other).toEqual({ command: "x" });
+    });
+    it("preserves unrelated top-level keys", () => {
+        const source = JSON.stringify({ projects: { "/tmp": {} }, mcpServers: {} }, null, 2);
+        const out = claudeCodeAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: false,
+        });
+        expect(JSON.parse(out).projects).toEqual({ "/tmp": {} });
+    });
+});
+describe("claudeCodeAdapter.defaultPaths", () => {
+    it("points at ~/.claude.json", () => {
+        expect(claudeCodeAdapter.defaultPaths()[0]).toMatch(/\.claude\.json$/);
+    });
+});

package/build/install/hosts/claude-desktop.js

@@ -0,0 +1,45 @@
+import { existsSync, promises as fs } from "node:fs";
+import { homedir, platform } from "node:os";
+import { posix, win32 } from "node:path";
+import { applyEdits, modify } from "jsonc-parser";
+export function resolveClaudeDesktopPath(plat, home, env) {
+    if (plat === "darwin")
+        return posix.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    if (plat === "win32") {
+        const appdata = env.APPDATA ?? win32.join(home, "AppData", "Roaming");
+        return win32.join(appdata, "Claude", "claude_desktop_config.json");
+    }
+    return posix.join(home, ".config", "Claude", "claude_desktop_config.json");
+}
+export const claudeDesktopAdapter = {
+    id: "claude-desktop",
+    displayName: "Claude Desktop",
+    defaultPaths() {
+        return [resolveClaudeDesktopPath(platform(), homedir(), process.env)];
+    },
+    async detect() {
+        return existsSync(claudeDesktopAdapter.defaultPaths()[0])
+            ? "installed"
+            : "absent";
+    },
+    async read(path) {
+        return existsSync(path) ? fs.readFile(path, "utf8") : "";
+    },
+    merge(source, entry, name, { uninstall }) {
+        const text = source.trim() === "" ? "{}\n" : source;
+        const value = uninstall
+            ? undefined
+            : {
+                command: entry.command,
+                args: entry.args,
+                ...(Object.keys(entry.env).length ? { env: entry.env } : {}),
+            };
+        const edits = modify(text, ["mcpServers", name], value, {
+            formattingOptions: { insertSpaces: true, tabSize: 2 },
+        });
+        return applyEdits(text, edits);
+    },
+    diffLabel() {
+        return claudeDesktopAdapter.defaultPaths()[0];
+    },
+};

package/build/install/hosts/claude-desktop.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "@jest/globals";
+import { claudeDesktopAdapter, resolveClaudeDesktopPath, } from "./claude-desktop.js";
+const ENTRY = {
+    command: "npx",
+    args: ["-y", "drawio-mcp-server", "--editor"],
+    env: {},
+    transport: "stdio",
+};
+describe("claudeDesktopAdapter.merge", () => {
+    it("adds mcpServers.drawio", () => {
+        const out = claudeDesktopAdapter.merge("", ENTRY, "drawio", {
+            uninstall: false,
+        });
+        const parsed = JSON.parse(out);
+        expect(parsed.mcpServers.drawio).toEqual({
+            command: "npx",
+            args: ["-y", "drawio-mcp-server", "--editor"],
+        });
+    });
+    it("preserves comments in jsonc source", () => {
+        const source = [
+            "{",
+            "  // pinned by me",
+            '  "mcpServers": {',
+            '    "other": { "command": "x" }',
+            "  }",
+            "}",
+        ].join("\n");
+        const out = claudeDesktopAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: false,
+        });
+        expect(out).toContain("// pinned by me");
+        expect(out).toContain('"drawio"');
+    });
+    it("uninstall removes the entry", () => {
+        const source = JSON.stringify({
+            mcpServers: { drawio: { command: "old" } },
+        });
+        const out = claudeDesktopAdapter.merge(source, ENTRY, "drawio", {
+            uninstall: true,
+        });
+        expect(JSON.parse(out).mcpServers).toEqual({});
+    });
+});
+describe("resolveClaudeDesktopPath", () => {
+    it("darwin uses Application Support", () => {
+        expect(resolveClaudeDesktopPath("darwin", "/Users/me", {})).toMatch(/Library\/Application Support\/Claude\/claude_desktop_config\.json$/);
+    });
+    it("win32 uses APPDATA when set", () => {
+        expect(resolveClaudeDesktopPath("win32", "C:\\Users\\me", {
+            APPDATA: "C:\\Users\\me\\AppData\\Roaming",
+        })).toMatch(/AppData\\Roaming\\Claude\\claude_desktop_config\.json$/);
+    });
+    it("linux uses ~/.config/Claude", () => {
+        expect(resolveClaudeDesktopPath("linux", "/home/me", {})).toBe("/home/me/.config/Claude/claude_desktop_config.json");
+    });
+});

package/build/install/hosts/codex.js

@@ -0,0 +1,171 @@
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { stringify } from "smol-toml";
+export const codexAdapter = {
+    id: "codex",
+    displayName: "Codex CLI",
+    defaultPaths() {
+        return [join(homedir(), ".codex", "config.toml")];
+    },
+    async detect() {
+        return existsSync(codexAdapter.defaultPaths()[0]) ? "installed" : "absent";
+    },
+    async read(path) {
+        if (!existsSync(path))
+            return "";
+        return fs.readFile(path, "utf8");
+    },
+    merge(source, entry, name, { uninstall }) {
+        return mergeTomlBlock(source, name, uninstall ? null : blockBody(entry));
+    },
+    diffLabel() {
+        return codexAdapter.defaultPaths()[0];
+    },
+};
+function blockBody(entry) {
+    const table = {
+        command: entry.command,
+        args: entry.args,
+    };
+    // `smol-toml` renders arrays/inline-tables with padding spaces
+    // (`[ "a", "b" ]`); normalize to the compact style used elsewhere in this
+    // project's generated configs (`["a", "b"]`).
+    const base = stringify(table)
+        .trim()
+        .replace(/\[ /g, "[")
+        .replace(/ \]/g, "]");
+    const envKeys = Object.keys(entry.env);
+    if (envKeys.length === 0)
+        return base;
+    // `smol-toml`'s `stringify` renders a nested object as a `[env]` sub-table
+    // header on its own line, which `removeBlock` (below) mistakes for a
+    // sibling top-level table -- corrupting idempotent merges and leaking
+    // secrets on uninstall (the header + its keys survive as an orphan
+    // block). Render `env` as a single-line inline table instead, which stays
+    // inside this block and cannot be mistaken for a new `[table]` header.
+    const envLine = `env = { ${envKeys
+        .map((k) => `${tomlKey(k)} = ${tomlString(entry.env[k])}`)
+        .join(", ")} }`;
+    return `${base}\n${envLine}`;
+}
+const BARE_KEY = /^[A-Za-z0-9_-]+$/;
+function tomlKey(key) {
+    return BARE_KEY.test(key) ? key : tomlString(key);
+}
+function tomlString(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/**
+ * Insert, replace, or remove a single TOML table (identified by its dotted
+ * `key`, e.g. `mcp_servers.drawio`) in `source`, leaving every other byte of
+ * the file untouched.
+ *
+ * `smol-toml`'s `parse` -> `stringify` round-trip (as sketched in the task
+ * brief) discards *all* comments and reformats the entire document -- not
+ * just the table being edited. That fails round-trip expectations for any
+ * config a human may have hand-edited. Splicing the target table's text
+ * directly avoids touching unrelated tables, comments, or blank-line layout.
+ */
+function mergeTomlBlock(source, name, body) {
+    const header = `[mcp_servers.${name}]`;
+    const lines = source.length > 0 ? source.split("\n") : [];
+    assertNoInlineInParentForm(lines, name);
+    const spliced = removeBlock(lines, name);
+    if (body === null)
+        return spliced.join("\n");
+    return appendBlock(spliced, header, body).join("\n");
+}
+/**
+ * Does `line` open the `[mcp_servers.<name>]` table, tolerating TOML-legal
+ * variants a hand-authored config might use: a quoted key segment
+ * (`[mcp_servers."drawio"]`) and/or whitespace around the `.` separator
+ * (`[mcp_servers . drawio]`)?
+ */
+function isTargetHeader(line, name) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return false;
+    const inner = trimmed.slice(1, -1).trim();
+    const segments = inner.split(/\s*\.\s*/).map(unquoteTomlKey);
+    return (segments.length === 2 &&
+        segments[0] === "mcp_servers" &&
+        segments[1] === name);
+}
+function unquoteTomlKey(segment) {
+    const s = segment.trim();
+    if (s.length >= 2) {
+        const first = s[0];
+        const last = s[s.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return s.slice(1, -1);
+        }
+    }
+    return s;
+}
+/**
+ * The inline-in-parent form (`[mcp_servers]` header followed by a bare
+ * `<name> = { ... }` assignment) is a different TOML structure from a
+ * nested `[mcp_servers.<name>]` table, and this tool's block-splice merge
+ * doesn't understand it. Rather than silently corrupt a hand-authored
+ * config (e.g. by appending a second, conflicting `drawio` entry), fail
+ * loudly and tell the user how to fix it.
+ */
+function assertNoInlineInParentForm(lines, name) {
+    const startIdx = lines.findIndex((line) => {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+            return false;
+        return trimmed.slice(1, -1).trim() === "mcp_servers";
+    });
+    if (startIdx === -1)
+        return;
+    const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const assignment = new RegExp(`^\\s*(?:${escapedName}|"${escapedName}"|'${escapedName}')\\s*=`);
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*\[[A-Za-z_"]/.test(line))
+            break;
+        if (assignment.test(line)) {
+            throw new Error(`Found "${name}" defined inline under [mcp_servers] (e.g. \`${name} = { ... }\`), ` +
+                `which this tool doesn't support. Please move the entry into a ` +
+                `[mcp_servers.${name}] table, or use --config-path to point at a different config file.`);
+        }
+    }
+}
+function removeBlock(lines, name) {
+    const startIdx = lines.findIndex((line) => isTargetHeader(line, name));
+    if (startIdx === -1)
+        return lines;
+    let endIdx = lines.length;
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        if (/^\s*\[[A-Za-z_"]/.test(lines[i])) {
+            endIdx = i;
+            break;
+        }
+    }
+    // Drop trailing blank lines that belong to the removed block.
+    while (endIdx > startIdx + 1 && lines[endIdx - 1].trim() === "") {
+        endIdx--;
+    }
+    const before = lines.slice(0, startIdx);
+    // Drop the single blank separator line preceding the block, if any, so
+    // removal doesn't leave a double blank line behind.
+    if (before.length > 0 && before[before.length - 1].trim() === "") {
+        before.pop();
+    }
+    const after = lines.slice(endIdx);
+    return [...before, ...after];
+}
+function appendBlock(lines, header, body) {
+    const bodyLines = body.split("\n");
+    // Drop the single trailing empty element representing the file's final
+    // newline, so we don't accumulate blank lines across repeated merges.
+    const trimmed = lines.length > 0 && lines[lines.length - 1] === ""
+        ? lines.slice(0, -1)
+        : lines;
+    if (trimmed.length === 0)
+        return [header, ...bodyLines, ""];
+    return [...trimmed, "", header, ...bodyLines, ""];
+}