slidemind 0.1.6 → 0.1.8

package/src/mcp/server.mjs

@@ -1,958 +0,0 @@
-// Slidemind MCP server (stdio).
-//
-// Exposes the deck-authoring + push-to-PowerPoint surface to a local agent
-// (Claude Code, Codex, opencode) as native MCP tools so the agent can
-// enumerate open PowerPoint windows and push a freshly built deck without
-// leaving an on-disk .pptx behind.
-//
-// Tools:
-//   slidemind_list_open_presentations
-//     Lists PowerPoint windows registered with the local bridge, including
-//     retained entries whose task-pane socket is temporarily disconnected.
-//
-//   slidemind_read_presentation
-//     Pulls the current content of an open PowerPoint window — a per-slide
-//     outline (summary) or each slide's full plain text (raw) — so the agent can
-//     inspect the live deck before editing it.
-//
-//   slidemind_push_deck
-//     Renders a deck server-side via the add-in and pushes its slides into one
-//     open PowerPoint window.
-//
-//   slidemind_view_draft
-//     Renders the deck's authored slides to per-slide preview images locally and
-//     returns them WITHOUT pushing — the agent's "look at my own draft" check
-//     before push / the human review gate.
-//
-//   slidemind_list_engines
-//     Lists the live engine catalog (image + slide) for the active corporate
-//     design, filterable by type/subtype.
-//
-//   slidemind_search_engine
-//     Searches the active corporate design's engine (image/icon OR slide,
-//     content/visual intent) over the bridge.
-//
-//   slidemind_view_slide
-//     Returns a preview image of a chosen slide search result.
-//
-//   slidemind_insert_slide
-//     Inserts chosen slide search results live into an open PowerPoint window.
-//
-//   slidemind_add_slide_to_deck
-//     Folds chosen slide search results into a deck as native one-slide .pptx
-//     under slides/ (survive re-render, spliced into play order).
-//
-//   slidemind_download_result
-//     Fetches a chosen image search result's bytes and writes them into a deck's
-//     assets/ folder for the slide JSX to reference.
-//
-// Everything routes through the add-in's cloud relay at
-// `<backendURL>/api/cli/*` with the Bearer session token established by
-// `slidemind pair`. See src/bridge/client.mjs.
-
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-import { describeRecolor } from "./recolor.mjs";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
-const SRC_DIR = path.join(PACKAGE_ROOT, "src");
-
-async function loadBridgeClient() {
-  return import(pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href);
-}
-
-async function loadBuildAndPush() {
-  return import(
-    pathToFileURL(path.join(SRC_DIR, "bridge", "build-and-push.mjs")).href
-  );
-}
-
-async function loadBundle() {
-  return import(pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href);
-}
-
-async function loadReusedSlides() {
-  return import(pathToFileURL(path.join(SRC_DIR, "lib", "reused-slides.mjs")).href);
-}
-
-function textResult(value) {
-  const text =
-    typeof value === "string" ? value : JSON.stringify(value, null, 2);
-  return { content: [{ type: "text", text }] };
-}
-
-function errorResult(err) {
-  let text = err && err.message ? err.message : String(err);
-  const code = err && err.code;
-  // Known transient states are recoverable without rebuilding anything — tell
-  // the agent exactly how to resume if the bridge timed out waiting for a true
-  // task-pane reconnect. Normal backgrounded PowerPoint should not reach this.
-  if (code === "pane_suspended") {
-    text +=
-      "\n\nRecoverable: the CLI already waited ~2 minutes for the task pane to " +
-      "reconnect. The render itself never needs the pane (it runs server-side) — " +
-      "only pushing/engine ops do. Ask the user to click the slidemind task pane " +
-      "once, then retry this same call; do NOT ask them to keep PowerPoint " +
-      "foregrounded beyond that.";
-  } else if (code === "engine_auth_expired") {
-    text +=
-      "\n\nRecoverable: ask the user to click the slidemind task pane for ~1s so " +
-      "it refreshes its sign-in, then retry this call.";
-  }
-  return { content: [{ type: "text", text }], isError: true };
-}
-
-// Parse a `data:<mime>;base64,<data>` URI into an MCP image content block so a
-// vision-capable agent can "see" the result grid, exactly as the in-app design
-// agent does.
-function imageContentFromDataUri(dataUri) {
-  const m = /^data:([^;]+);base64,(.+)$/.exec(dataUri || "");
-  if (!m) return null;
-  return { type: "image", data: m[2], mimeType: m[1] };
-}
-
-const MIME_EXT = {
-  "image/svg+xml": "svg",
-  "image/png": "png",
-  "image/jpeg": "jpg",
-  "image/jpg": "jpg",
-  "image/webp": "webp",
-  "image/gif": "gif",
-};
-
-// Derive a usable file extension from an engine result's MIME type. The brand
-// engine can return any image Content-Type (image/x-icon, image/bmp,
-// image/avif, …) and may carry a `;charset=` suffix, so an exact-match table
-// alone would fall back to a useless `.bin` that won't render in an <img>.
-// Strip params, then fall back to the MIME subtype itself for any `image/*`.
-function extFromMime(mimeType) {
-  const mt = String(mimeType || "")
-    .split(";")[0]
-    .trim()
-    .toLowerCase();
-  if (MIME_EXT[mt]) return MIME_EXT[mt];
-  const m = /^image\/(?:x-)?([a-z0-9.+-]+)$/.exec(mt);
-  if (m) {
-    const sub = m[1].replace(/\+xml$/, "");
-    if (sub === "svg") return "svg";
-    if (sub === "jpeg") return "jpg";
-    if (sub === "icon") return "ico";
-    return sub; // png, gif, webp, bmp, avif, tiff, heic, …
-  }
-  return "bin";
-}
-
-const server = new McpServer(
-  { name: "slidemind", version: "0.1.0" },
-  {
-    instructions:
-      "Build on-brand slide decks under <cwd>/decks/<slug>/slides/*.jsx for the " +
-      "presentation's active corporate design, then render + push them into a running " +
-      "PowerPoint window via the slidemind add-in. The corporate design (tokens, layouts, " +
-      "brand rules) and the .pptx render both live in the add-in — an open PowerPoint host " +
-      "with an active corporate design is required, and all brand rules come from that " +
-      "design's bundle (design.md), never hardcoded here. " +
-      "Always call slidemind_list_open_presentations first to learn which presentation_id to target. " +
-      "If connection/readiness is unclear, call slidemind_connection_status before asking the user for help. " +
-      "To inspect what's already in a window before editing, call slidemind_read_presentation (summary outline or raw plain text). " +
-      "After authoring or editing slides, call slidemind_view_draft to LOOK at your own draft (per-slide images, nothing pushed) and self-correct before slidemind_push_deck. " +
-      "The CLI may be paired with several add-in environments (local/dev/prod) at once; the list spans " +
-      "all of them and each entry is tagged with its env, and routing to the right backend is automatic — " +
-      "just pass the presentation_id back. " +
-      "Renders run server-side and never need the task pane awake (a suspended/backgrounded PowerPoint " +
-      "is fine); only pushing slides and engine search/download touch the pane, and those wait for it " +
-      "and retry automatically. " +
-      "For brand imagery, slidemind_search_engine then slidemind_download_result.",
-  },
-);
-
-server.registerTool(
-  "slidemind_list_open_presentations",
-  {
-    title: "List open PowerPoint windows",
-    description:
-      "List PowerPoint windows registered with the slidemind local bridge, including retained entries whose task-pane socket is temporarily disconnected. " +
-      "Spans every paired add-in environment (local/dev/prod); each entry carries an `env` tag and a stable presId — pass the presId as `presentation_id` to the other tools and routing to that env is automatic. " +
-      "If the list is empty the user has no PowerPoint open with the add-in loaded.",
-    inputSchema: {},
-  },
-  async () => {
-    try {
-      const { listOpenPresentations, toPublicPresentation } =
-        await loadBridgeClient();
-      const list = await listOpenPresentations();
-      return textResult({ presentations: list.map(toPublicPresentation) });
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_connection_status",
-  {
-    title: "Diagnose CLI/add-in connection readiness",
-    description:
-      "Return paired backend reachability and per-window readiness. Use this when a slidemind tool fails or before asking the user for manual action.",
-    inputSchema: {},
-  },
-  async () => {
-    try {
-      const client = await loadBridgeClient();
-      const status = await client.connectionStatus();
-      return textResult({
-        paired: status.paired,
-        backendCount: status.backendCount,
-        backends: (status.backends ?? []).map((b) => ({
-          env: b.env,
-          ok: b.ok,
-          readinessV1: b.readinessV1 === true,
-          capabilities: b.capabilities ?? null,
-          error: b.error,
-          summary: b.summary ?? null,
-          presentations: (b.presentations ?? []).map(client.toPublicPresentation),
-        })),
-        presentations: (status.presentations ?? []).map(client.toPublicPresentation),
-      });
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_read_presentation",
-  {
-    title: "Read the current content of an open presentation",
-    description:
-      "Pull the CURRENT content of an open PowerPoint window so you can inspect the live deck before editing it. " +
-      "mode='summary' returns a per-slide outline (index, layout, title, subtitle); mode='raw' (default) returns each slide's full plain text. " +
-      "This is plain text content, NOT editing markup. " +
-      "presentation_id is the presId from slidemind_list_open_presentations; it's optional when exactly one window is open, but required to disambiguate when several are open.",
-    inputSchema: {
-      presentation_id: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("presId from slidemind_list_open_presentations. Optional when only one window is open; required to pick one when several are."),
-      mode: z
-        .enum(["summary", "raw"])
-        .nullable()
-        .optional()
-        .describe("'summary' = per-slide outline; 'raw' (default) = each slide's full plain text."),
-    },
-  },
-  async ({ presentation_id, mode }) => {
-    try {
-      const client = await loadBridgeClient();
-      const registry = await client.requirePaneHost();
-      const entry = client.pickPresentationEntry(registry, presentation_id ?? null);
-      const res = await client.getPresentationContent({
-        presId: entry.presId,
-        mode: mode ?? "raw",
-        backendURL: entry.backendURL ?? null,
-      });
-      if (!res?.ok) {
-        return errorResult(new Error(res?.error ?? "read presentation failed"));
-      }
-      return textResult({
-        presentation_id: entry.presId,
-        mode: res.mode,
-        slideCount: res.slideCount,
-        slides: res.slides ?? [],
-      });
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_push_deck",
-  {
-    title: "Push a built deck into PowerPoint",
-    description:
-      "Build the deck at deck_path and push the resulting slides into the PowerPoint window identified by " +
-      "presentation_id (from slidemind_list_open_presentations). By default slides are appended at the end. " +
-      "Use insert_at to place after a specific 0-based slide index. Use replace=true to delete existing slides " +
-      "first (destructive). slide_ids restricts the push to a subset of the built deck's slide ids and is for " +
-      "the append/insert path only — it CANNOT be combined with replace=true (that combination is rejected, " +
-      "because the bridge would otherwise wipe the whole presentation). " +
-      "The render itself never needs the task pane awake; if the pane is suspended at push time the CLI waits " +
-      "up to ~2 min for it (the user just clicks the pane once) and retries safely. If the result carries " +
-      "paneSuspended=true, the rendered .pptx was saved to fallbackFile instead — nothing was lost.",
-    inputSchema: {
-      deck_path: z
-        .string()
-        .describe("Path to the deck folder (must contain slides/). Absolute or relative to CWD."),
-      presentation_id: z
-        .string()
-        .describe("presId from slidemind_list_open_presentations. Required even when only one window is open."),
-      insert_at: z
-        .number()
-        .int()
-        .nonnegative()
-        .nullable()
-        .optional()
-        .describe("0-based slide index to insert after. Omit or null = append at end. Ignored when replace=true."),
-      replace: z
-        .boolean()
-        .optional()
-        .describe("If true, delete all existing slides before inserting. Destructive."),
-      slide_ids: z
-        .array(z.string())
-        .nullable()
-        .optional()
-        .describe("Optional subset of source slide ids to push. Omit or null = all slides in the built deck."),
-    },
-  },
-  async ({ deck_path, presentation_id, insert_at, replace, slide_ids }, extra) => {
-    try {
-      const { buildAndPush } = await loadBuildAndPush();
-      // Relay per-slide render progress as MCP progress notifications when the
-      // client asked for them (sent a progressToken). Fire-and-forget — a
-      // dropped notification must never fail the push.
-      const progressToken = extra?._meta?.progressToken;
-      const onProgress =
-        progressToken === undefined || typeof extra?.sendNotification !== "function"
-          ? null
-          : (p) => {
-              const message =
-                p.state === "queued"
-                  ? "render queued behind another render"
-                  : p.state === "restarted"
-                    ? "render restarted (backend replica was replaced)"
-                    : p.stage === "assembling"
-                      ? "assembling deck"
-                      : typeof p.total === "number"
-                        ? `rendering slide ${Math.min((p.done ?? 0) + 1, p.total)}/${p.total}`
-                        : null;
-              void extra
-                .sendNotification({
-                  method: "notifications/progress",
-                  params: {
-                    progressToken,
-                    progress: typeof p.done === "number" ? p.done : 0,
-                    ...(typeof p.total === "number" ? { total: p.total } : {}),
-                    ...(message ? { message } : {}),
-                  },
-                })
-                .catch(() => {});
-            };
-      const result = await buildAndPush({
-        deckDir: path.resolve(process.cwd(), deck_path),
-        presentationId: presentation_id,
-        insertAt: insert_at ?? null,
-        replace: replace === true,
-        slideIds: slide_ids ?? null,
-        onProgress,
-      });
-      return textResult(result);
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_search_engine",
-  {
-    title: "Search an engine for imagery or slides",
-    description:
-      "Search the active corporate design's engine over the bridge — image/icon engines OR slide engines. " +
-      "Uses the add-in's server-side bridge, so it returns the SAME results the in-app design agent sees. " +
-      "Returns a searchId and a numbered set of results. For image engines (and visual slide search) you also get a grid image you can view; " +
-      "for content slide search each result carries the extracted slide `text` plus metadata (slideNumber, presentationTitle, score). " +
-      "intent selects the slide search mode: 'content' (text is the signal) or 'visual' (the slide image is the signal); image engines are visual-only. " +
-      "Next: reuse an image with slidemind_download_result, view a slide with slidemind_view_slide, insert a slide live with slidemind_insert_slide, or fold a slide into a deck with slidemind_add_slide_to_deck. " +
-      "engine_id is optional for image search — omit it to use the corporate design's first image engine; slide search requires engine_id (see slidemind_list_engines). " +
-      "presentation_id is OPTIONAL: the engine is not bound to a window, so omit it and the search attaches to any connected window automatically. The window it used is echoed back as `presentation_id` in the result — pass THAT to the follow-up tools (view/insert/add), since the searchId is bound to it.",
-    inputSchema: {
-      presentation_id: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("Optional. Omit to attach to any connected window automatically (the engine isn't window-bound). The window used is returned as `presentation_id`; thread it to slidemind_view_slide / _insert_slide / _add_slide_to_deck."),
-      query: z
-        .string()
-        .describe("Concept query, e.g. 'shield', 'handshake', 'revenue bridge'."),
-      engine_id: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("Engine id from slidemind_list_engines. Omit/null = first image engine (image search only)."),
-      intent: z
-        .enum(["auto", "content", "visual"])
-        .nullable()
-        .optional()
-        .describe("Slide search mode: 'content' (text), 'visual' (image), or 'auto'. Image engines ignore this."),
-      top: z
-        .number()
-        .int()
-        .positive()
-        .nullable()
-        .optional()
-        .describe("Max number of results to return."),
-    },
-  },
-  async ({ presentation_id, query, engine_id, intent, top }) => {
-    try {
-      const client = await loadBridgeClient();
-      // All engine tools hard-require an open host (the truth lives in the
-      // add-in); surface the actionable "open PowerPoint…" message up front.
-      const registry = await client.requirePaneHost();
-      // The engine is per-user, not window-bound: attach to any connected window
-      // when the caller didn't pin one. The chosen presId is echoed back so the
-      // agent threads it to the follow-up tools (the searchId is bound to it).
-      const entry = client.pickAnyPresentationEntry(registry, presentation_id ?? null);
-      const presId = entry.presId;
-      const backendURL = entry.backendURL ?? null;
-      let engineId = engine_id ?? null;
-      const slideIntent = intent === "content" || intent === "visual";
-      // Forward the engine subtype on the wire whenever it's derivable (belt-
-      // and-suspenders against an add-in regression where a missing subtype no
-      // longer defaulted to "image"): an explicit slide intent targets a slide
-      // engine; the pickImageEngine default branch is an image engine. When the
-      // subtype is unknown we omit it and let the add-in resolve it.
-      let subtype = slideIntent ? "slide" : null;
-      if (!engineId) {
-        if (slideIntent) {
-          return errorResult(
-            new Error(
-              "slide search requires engine_id. Call slidemind_list_engines (type='search', subtype='slide') to find one.",
-            ),
-          );
-        }
-        const { materializeBundle, readEnginesFromDir, pickImageEngine } =
-          await loadBundle();
-        const mat = await materializeBundle(presId, { backendURL });
-        const pick = pickImageEngine(readEnginesFromDir(mat.dir));
-        if (!pick) {
-          return errorResult(
-            new Error(
-              "This corporate design has no brand engines to search. Pass engine_id or ask the add-in owner to wire an image engine.",
-            ),
-          );
-        }
-        engineId = pick.id;
-        subtype = "image";
-      }
-      // Window-agnostic: tries the picked pane, then fails over to any other
-      // live window on the same backend if it's suspended/frozen. res.presId is
-      // the window that actually answered — echo THAT back (the searchId is
-      // bound to it) so follow-up view/insert/add target the right pane.
-      const res = await client.engineSearchAnyPane({
-        registry,
-        explicitPresId: presentation_id ?? null,
-        engineId,
-        query,
-        subtype,
-        intent: intent ?? null,
-        top: top ?? null,
-      });
-      const ranPresId = res?.presId ?? presId;
-      const content = [];
-      const grid = imageContentFromDataUri(res?.gridDataUri);
-      if (grid) content.push(grid);
-      // Prefer the new `results` array (image + slide engines); fall back to the
-      // legacy `thumbnails` shape older add-ins still return for image engines.
-      const rawResults = Array.isArray(res?.results)
-        ? res.results
-        : (res?.thumbnails ?? []).map((t, i) => ({ selection: i + 1, title: t.title }));
-      const results = rawResults.map((r, i) => ({
-        selection: r.selection ?? i + 1,
-        title: r.title ?? null,
-        ...(typeof r.score === "number" ? { score: r.score } : {}),
-        ...(r.kind ? { kind: r.kind } : {}),
-        ...(typeof r.text === "string" ? { text: r.text } : {}),
-        ...(typeof r.slideNumber === "number" ? { slideNumber: r.slideNumber } : {}),
-        ...(r.presentationTitle ? { presentationTitle: r.presentationTitle } : {}),
-      }));
-      content.push({
-        type: "text",
-        text: JSON.stringify(
-          {
-            ok: res?.ok ?? false,
-            // The window the search ran on (auto-attached when the caller didn't
-            // pin one; may have failed over from the picked pane). The searchId
-            // is bound to it — pass this presentation_id to slidemind_view_slide
-            // / _insert_slide / _add_slide_to_deck.
-            presentation_id: ranPresId,
-            engineId,
-            subtype: res?.subtype ?? null,
-            intent: res?.intent ?? null,
-            searchId: res?.searchId ?? null,
-            resultCount: res?.resultCount ?? results.length,
-            results,
-          },
-          null,
-          2,
-        ),
-      });
-      return { content };
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_view_draft",
-  {
-    title: "Look at a deck's draft slides (no push)",
-    description:
-      "Render the deck's authored slides/*.jsx to per-slide preview images and return them to you WITHOUT pushing anything — the 'look at my own draft before the user sees it' tool. " +
-      "Use this AFTER authoring/editing slides and BEFORE slidemind_push_deck (and before the human slidemind review gate): look at each screenshot, fix anything visibly wrong in the JSX, then view again until each slide is sound. " +
-      "Renders locally against the materialized bundle, so it needs no awake task pane (and no open host at all once the bundle has been downloaded once). " +
-      "Returns one image per freeform slide; purpose-built layout slides (covers/dividers) and reused native .pptx slides have no draft preview and report as a status line. Nothing is pushed, nothing is written to the deck.",
-    inputSchema: {
-      deck_path: z
-        .string()
-        .describe("Path to the deck folder (must contain slides/). Absolute or relative to CWD."),
-      presentation_id: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("Optional presId — only used to fetch the corporate-design bundle if it isn't cached yet. Omit when the deck's bundle is already materialized (the normal case after authoring)."),
-    },
-  },
-  async ({ deck_path, presentation_id }) => {
-    try {
-      const { viewDraft } = await loadBuildAndPush();
-      const deckDir = path.resolve(process.cwd(), deck_path);
-      const result = await viewDraft(deckDir, {
-        presentationId: presentation_id ?? null,
-      });
-      const images = [];
-      const lines = [];
-      for (const slide of result.slides ?? []) {
-        const image = slide.dataUri ? imageContentFromDataUri(slide.dataUri) : null;
-        if (image) {
-          images.push(image);
-          lines.push(
-            `${slide.fileName} — preview attached (image ${images.length})` +
-              (slide.status === "degraded" && slide.note ? ` — ${slide.note}` : ""),
-          );
-        } else {
-          lines.push(`${slide.fileName} — ${slide.note ?? slide.status}`);
-        }
-      }
-      const header =
-        images.length > 0
-          ? `Rendered ${images.length} draft preview image(s) — NOT pushed to PowerPoint, nothing written to the deck. ` +
-            `Judge each screenshot with your eyes, fix what is visibly wrong in the slide JSX, view the draft again, ` +
-            `then push with slidemind_push_deck (or build-pptx) once each slide is visually sound.`
-          : `No draft preview images were produced — NOTHING was pushed.`;
-      const warnLines = (result.warnings ?? []).map((w) => `  warning: ${w}`);
-      const text = [header, ...lines, ...warnLines].join("\n");
-      return { content: [{ type: "text", text }, ...images] };
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_list_engines",
-  {
-    title: "List available engines",
-    description:
-      "List the LIVE engine catalog for the active corporate design over the bridge (not just the bundle's curated set). " +
-      "Spans every paired add-in environment; each engine carries an `env` tag. " +
-      "Filter by `type` (collection|search) and/or `subtype` (image|slide|template|content). " +
-      "Use the returned engine id with slidemind_search_engine (slide search requires one).",
-    inputSchema: {
-      presentation_id: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("Optional presId — engines are backend-scoped, so this is informational only."),
-      type: z
-        .enum(["collection", "search"])
-        .nullable()
-        .optional()
-        .describe("Filter by engine type."),
-      subtype: z
-        .enum(["image", "slide", "template", "content"])
-        .nullable()
-        .optional()
-        .describe("Filter by engine subtype."),
-    },
-  },
-  async ({ type, subtype }) => {
-    try {
-      const client = await loadBridgeClient();
-      const { engines } = await client.listEngines({
-        type: type ?? null,
-        subtype: subtype ?? null,
-      });
-      return textResult({ engines });
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_view_slide",
-  {
-    title: "View a slide search result",
-    description:
-      "Fetch a chosen slide search result's preview image so you can see it before reusing it. " +
-      "Pass the searchId from slidemind_search_engine and the 1-based selection number. " +
-      "Returns an image content block. Then reuse with slidemind_insert_slide (live) or slidemind_add_slide_to_deck (into a deck).",
-    inputSchema: {
-      presentation_id: z
-        .string()
-        .describe("The presentation_id returned by slidemind_search_engine (the window the search ran on). The searchId is bound to that window, so this must be exactly that presentation_id."),
-      search_id: z
-        .number()
-        .int()
-        .describe("searchId returned by slidemind_search_engine."),
-      selection: z
-        .number()
-        .int()
-        .positive()
-        .describe("1-based result number to view."),
-    },
-  },
-  async ({ presentation_id, search_id, selection }) => {
-    try {
-      const client = await loadBridgeClient();
-      await client.requirePaneHost();
-      const res = await client.viewSlide({
-        presId: presentation_id,
-        searchId: search_id,
-        selection,
-      });
-      if (!res?.ok || !res.dataUri) {
-        return errorResult(new Error(res?.error ?? "slide view returned no image"));
-      }
-      const image = imageContentFromDataUri(res.dataUri);
-      if (!image) {
-        return errorResult(new Error("slide view returned an unparseable data URI"));
-      }
-      return { content: [image] };
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_insert_slide",
-  {
-    title: "Insert reused slide(s) live into PowerPoint",
-    description:
-      "Insert one or more chosen slide search results directly into an open PowerPoint window (the 'reuse → insert live' path). " +
-      "Pass the searchId from slidemind_search_engine and the 1-based selection number(s). " +
-      "By default the slides are appended; use `at` to insert after a specific 0-based slide index. " +
-      "To instead fold reused slides into a deck you are authoring, use slidemind_add_slide_to_deck.",
-    inputSchema: {
-      presentation_id: z
-        .string()
-        .describe("The presentation_id returned by slidemind_search_engine (the window the search ran on). The searchId is bound to that window, so this must be exactly that presentation_id."),
-      search_id: z
-        .number()
-        .int()
-        .describe("searchId returned by slidemind_search_engine."),
-      selections: z
-        .array(z.number().int().positive())
-        .min(1)
-        .describe("1-based result number(s) to insert."),
-      at: z
-        .number()
-        .int()
-        .nonnegative()
-        .nullable()
-        .optional()
-        .describe("0-based slide index to insert after. Omit or null = append at end."),
-    },
-  },
-  async ({ presentation_id, search_id, selections, at }) => {
-    try {
-      const client = await loadBridgeClient();
-      await client.requirePaneHost();
-      const res = await client.insertSlideLive({
-        presId: presentation_id,
-        searchId: search_id,
-        selections,
-        at: at ?? null,
-      });
-      if (!res?.ok) {
-        return errorResult(new Error(res?.error ?? "insert slide failed"));
-      }
-      return textResult({
-        ok: true,
-        insertedCount: res.insertedCount ?? selections.length,
-        insertedSlideIds: res.insertedSlideIds ?? [],
-      });
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-server.registerTool(
-  "slidemind_add_slide_to_deck",
-  {
-    title: "Fold reused slide(s) into a deck",
-    description:
-      "Fold one or more chosen slide search results into a deck as native one-slide .pptx files under <deck>/slides/ (the 'reuse → fold into a deck' path). " +
-      "These native slides survive re-render: every slidemind_push_deck / build-pptx re-includes them, spliced into play order by their numeric filename prefix alongside the deck's .jsx slides. " +
-      "Pass the searchId from slidemind_search_engine and the 1-based selection number(s). " +
-      "By default the slides are appended after the last numeric prefix; `at` sets the numeric prefix the first added slide takes. " +
-      "To instead insert directly into an open window, use slidemind_insert_slide.",
-    inputSchema: {
-      presentation_id: z
-        .string()
-        .describe("The presentation_id returned by slidemind_search_engine (the window the search ran on). The searchId is bound to that window, so this must be exactly that presentation_id."),
-      deck_path: z
-        .string()
-        .describe("Path to the deck folder (slides are written under <deck>/slides/). Absolute or relative to CWD."),
-      search_id: z
-        .number()
-        .int()
-        .describe("searchId returned by slidemind_search_engine."),
-      selections: z
-        .array(z.number().int().positive())
-        .min(1)
-        .describe("1-based result number(s) to fold into the deck."),
-      at: z
-        .number()
-        .int()
-        .nonnegative()
-        .nullable()
-        .optional()
-        .describe("Numeric prefix the first added slide takes. Omit or null = append after the last existing prefix."),
-    },
-  },
-  async ({ presentation_id, deck_path, search_id, selections, at }) => {
-    try {
-      const client = await loadBridgeClient();
-      await client.requirePaneHost();
-      const deckDir = path.resolve(process.cwd(), deck_path);
-      const slidesDir = path.join(deckDir, "slides");
-      fs.mkdirSync(slidesDir, { recursive: true });
-
-      // Extract each picked slide's bytes, then let the shared helper compute
-      // the play-order filenames — the SAME prefix math the CLI's add-slide
-      // uses (src/lib/reused-slides.mjs), so the two paths never diverge.
-      const { reusedSlideTargets } = await loadReusedSlides();
-      const extracted = [];
-      for (const selection of selections) {
-        const res = await client.extractSlide({
-          presId: presentation_id,
-          searchId: search_id,
-          selection,
-        });
-        if (!res?.ok || !res.base64) {
-          return errorResult(
-            new Error(
-              `add slide failed for selection ${selection}: ${res?.error ?? "no slide bytes returned"}`,
-            ),
-          );
-        }
-        extracted.push({ selection, slideId: res.slideId ?? null, base64: res.base64 });
-      }
-      const existing = fs
-        .readdirSync(slidesDir)
-        .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"));
-      const targets = reusedSlideTargets(existing, extracted, at);
-      const written = extracted.map((slide, i) => {
-        const { filename } = targets[i];
-        const target = path.join(slidesDir, filename);
-        fs.writeFileSync(target, Buffer.from(slide.base64, "base64"));
-        return {
-          selection: slide.selection,
-          filename,
-          reference: `./slides/${filename}`,
-          path: target,
-        };
-      });
-      return textResult({ ok: true, deckDir, written });
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-// Fetch one chosen result over the bridge and write it into the deck's
-// assets/. Returns the written reference plus a `recolor` descriptor so the
-// agent never has to open the SVG to learn how it recolours. Throws on a failed
-// download so a batch can record a per-item error without aborting the rest.
-async function downloadOneResult({
-  client,
-  presId,
-  searchId,
-  assetsDir,
-  selection,
-  iconColor,
-}) {
-  const res = await client.engineDownload({
-    presId,
-    searchId,
-    selection,
-    iconColor: iconColor ?? null,
-  });
-  if (!res?.ok) {
-    throw new Error(res?.error ?? "download failed");
-  }
-  const ext = extFromMime(res.mimeType);
-  const filename = `engine-${searchId}-${selection}.${ext}`;
-  const target = path.join(assetsDir, filename);
-  if (res.svgMarkup && ext === "svg") {
-    // The (possibly recoloured) SVG markup is the canonical asset.
-    fs.writeFileSync(target, res.svgMarkup, "utf8");
-  } else if (typeof res.base64 === "string" && res.base64.length > 0) {
-    fs.writeFileSync(target, Buffer.from(res.base64, "base64"));
-  } else if (res.svgMarkup) {
-    // SVG bytes arrived only as markup (mimeType lacked an svg hint).
-    fs.writeFileSync(target, res.svgMarkup, "utf8");
-  } else {
-    throw new Error("engine result carried neither base64 bytes nor svgMarkup");
-  }
-  return {
-    selection,
-    path: target,
-    reference: `./assets/${filename}`,
-    mimeType: res.mimeType,
-    recolor: describeRecolor(res.svgMarkup ?? null, res.mimeType, iconColor ?? null),
-  };
-}
-
-server.registerTool(
-  "slidemind_download_result",
-  {
-    title: "Download chosen engine result(s) into a deck",
-    description:
-      "Fetch the bytes of one or more results from a prior slidemind_search_engine call and write them into the deck's assets/ folder. " +
-      "Reference each from slide JSX as <img src=\"./assets/<file>\">. " +
-      "Each result carries a `recolor` descriptor ({ recolorable, mode, applied, note }) — so you NEVER need to open the SVG to learn how it recolours. " +
-      "To colour an icon, pass icon_color (a hex you resolve from a corporate-design.css token): the bridge bakes it into the saved SVG, correct in BOTH the HTML preview and the .pptx render. " +
-      "Download several icons (each in its own colour) in ONE call via `selections: [{ selection, icon_color? }, …]` — they download concurrently. Use `selection` for one, or `selections` for many (don't pass both).",
-    inputSchema: {
-      presentation_id: z
-        .string()
-        .describe("The presentation_id returned by slidemind_search_engine (the window the search ran on). The searchId is bound to that window, so this must be exactly that presentation_id."),
-      deck_path: z
-        .string()
-        .describe("Path to the deck folder (assets are written under <deck>/assets/)."),
-      search_id: z
-        .number()
-        .int()
-        .describe("searchId returned by slidemind_search_engine."),
-      selection: z
-        .number()
-        .int()
-        .positive()
-        .nullable()
-        .optional()
-        .describe("1-based result number to download (single). Omit when using `selections`."),
-      icon_color: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("Optional hex colour (e.g. '#0000FF') to bake into a single SVG result."),
-      selections: z
-        .array(
-          z.object({
-            selection: z
-              .number()
-              .int()
-              .positive()
-              .describe("1-based result number."),
-            icon_color: z
-              .string()
-              .nullable()
-              .optional()
-              .describe("Optional hex colour to bake into this SVG."),
-          }),
-        )
-        .nullable()
-        .optional()
-        .describe("Batch: several results to download concurrently, each in its own colour."),
-    },
-  },
-  async ({ presentation_id, deck_path, search_id, selection, icon_color, selections }) => {
-    try {
-      const batch = Array.isArray(selections) && selections.length > 0;
-      const jobs = batch
-        ? selections.map((s) => ({
-            selection: s.selection,
-            iconColor: s.icon_color ?? null,
-          }))
-        : typeof selection === "number"
-          ? [{ selection, iconColor: icon_color ?? null }]
-          : [];
-      if (jobs.length === 0) {
-        return errorResult(
-          new Error(
-            "Provide `selection` (one result) or `selections` (a batch). Both are missing.",
-          ),
-        );
-      }
-
-      const client = await loadBridgeClient();
-      await client.requirePaneHost();
-      const deckDir = path.resolve(process.cwd(), deck_path);
-      const assetsDir = path.join(deckDir, "assets");
-      fs.mkdirSync(assetsDir, { recursive: true });
-
-      // Concurrent — each download is its own bridge round-trip, so issuing them
-      // in parallel turns N serial waits into one. allSettled so one bad
-      // selection doesn't sink the rest of the batch.
-      const settled = await Promise.allSettled(
-        jobs.map((job) =>
-          downloadOneResult({
-            client,
-            presId: presentation_id,
-            searchId: search_id,
-            assetsDir,
-            selection: job.selection,
-            iconColor: job.iconColor,
-          }),
-        ),
-      );
-      const results = settled.map((r, i) =>
-        r.status === "fulfilled"
-          ? r.value
-          : {
-              selection: jobs[i].selection,
-              error: r.reason?.message ? r.reason.message : String(r.reason),
-            },
-      );
-
-      // Single-selection calls keep the original flat shape (back-compat);
-      // a batch returns { results: [...] }.
-      if (!batch) {
-        const only = results[0];
-        if (only.error) return errorResult(new Error(only.error));
-        return textResult(only);
-      }
-      return textResult({ results });
-    } catch (err) {
-      return errorResult(err);
-    }
-  },
-);
-
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  // Logging on stdout would corrupt the JSON-RPC stream — keep it on stderr.
-  process.stderr.write("slidemind MCP server running on stdio\n");
-}
-
-main().catch((err) => {
-  process.stderr.write(`slidemind MCP fatal: ${err && err.stack ? err.stack : err}\n`);
-  process.exit(1);
-});