slidemind 0.0.27

package/src/mcp/server.mjs

@@ -0,0 +1,476 @@
+// 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 that have the slidemind add-in connected to
+//     the local bridge.
+//
+//   slidemind_push_deck
+//     Renders a deck server-side via the add-in and pushes its slides into one
+//     open PowerPoint window.
+//
+//   slidemind_search_engine
+//     Searches the active corporate design's brand engine (icons/images today,
+//     slide engines later) over the bridge — proxied to the open task pane.
+//
+//   slidemind_download_result
+//     Fetches a chosen 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 local bridge at
+// https://127.0.0.1:3001/local/* with a shared token the add-in writes to
+// `${XDG_STATE_HOME:-~/.local/state}/slidemind/bridge-token`
+// (Windows: `%LOCALAPPDATA%\\slidemind\\bridge-token`). 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);
+}
+
+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 so it pauses for a pane focus instead of
+  // aborting the deck.
+  if (code === "pane_suspended") {
+    text +=
+      "\n\nRecoverable: ask the user to click the slidemind task pane to bring " +
+      "PowerPoint to the foreground, then retry this call — nothing needs rebuilding.";
+  } 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. " +
+      "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 that currently have the slidemind add-in connected to the local bridge. " +
+      "Each entry has a stable presId — pass it as `presentation_id` to slidemind_push_deck. " +
+      "If the list is empty the user has no PowerPoint open with the add-in loaded.",
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const { listOpenPresentations } = await loadBridgeClient();
+      const list = await listOpenPresentations();
+      return textResult({ presentations: list });
+    } 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).",
+    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 }) => {
+    try {
+      const { buildAndPush } = await loadBuildAndPush();
+      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,
+      });
+      if (result.paneSuspended) {
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                "PowerPoint is backgrounded, so the rendered slides couldn't be " +
+                "inserted yet. The render succeeded and was saved to " +
+                `${result.fallbackFile}. Ask the user to click the slidemind task ` +
+                "pane to bring PowerPoint to the foreground, then call " +
+                "slidemind_push_deck again — the deck is already built, so this " +
+                "just retries the insert.",
+            },
+          ],
+          isError: true,
+        };
+      }
+      return textResult(result);
+    } catch (err) {
+      return errorResult(err);
+    }
+  },
+);
+
+server.registerTool(
+  "slidemind_search_engine",
+  {
+    title: "Search the brand engine for imagery",
+    description:
+      "Search the active corporate design's brand engine over the bridge (icons/images today; slide engines later). " +
+      "Proxied to the open PowerPoint task pane, so it returns the SAME results the in-app design agent sees. " +
+      "Returns a searchId and a numbered set of result thumbnails (and a grid image you can view). " +
+      "Pick a number, then call slidemind_download_result with the searchId + selection. " +
+      "engine_id is optional — omit it to use the corporate design's first image engine.",
+    inputSchema: {
+      presentation_id: z
+        .string()
+        .describe("presId from slidemind_list_open_presentations."),
+      query: z
+        .string()
+        .describe("Concept query, e.g. 'shield', 'handshake', 'data pipeline'."),
+      engine_id: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Engine id from the design bundle's engines[]. Omit/null = first image engine."),
+    },
+  },
+  async ({ presentation_id, query, engine_id }) => {
+    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.
+      await client.requireHost();
+      let engineId = engine_id ?? null;
+      if (!engineId) {
+        const { materializeBundle, readEnginesFromDir, pickImageEngine } =
+          await loadBundle();
+        const mat = await materializeBundle(presentation_id);
+        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;
+      }
+      const res = await client.engineSearch({
+        presId: presentation_id,
+        engineId,
+        query,
+      });
+      const content = [];
+      const grid = imageContentFromDataUri(res?.gridDataUri);
+      if (grid) content.push(grid);
+      content.push({
+        type: "text",
+        text: JSON.stringify(
+          {
+            ok: res?.ok ?? false,
+            engineId,
+            searchId: res?.searchId ?? null,
+            resultCount: res?.resultCount ?? (res?.thumbnails?.length ?? 0),
+            results: (res?.thumbnails ?? []).map((t, i) => ({
+              selection: i + 1,
+              title: t.title ?? null,
+            })),
+          },
+          null,
+          2,
+        ),
+      });
+      return { content };
+    } 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("presId — must match the slidemind_search_engine call."),
+      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.requireHost();
+      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);
+});