slidemind 0.1.3 → 0.1.5

package/src/mcp/server.mjs

@@ -14,12 +14,26 @@
 //     Renders a deck server-side via the add-in and pushes its slides into one
 //     open PowerPoint window.
 //
+//   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 brand engine (icons/images today,
-//     slide engines later) over the bridge.
+//     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 search result's bytes and writes them into a deck's
+//     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
@@ -55,6 +69,10 @@ 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);
@@ -69,9 +87,11 @@ function errorResult(err) {
   // task-pane reconnect. Normal backgrounded PowerPoint should not reach this.
   if (code === "pane_suspended") {
     text +=
-      "\n\nRecoverable: the render is already done, but the task-pane bridge did " +
-      "not reconnect before the wait timeout. Ask the user to click the slidemind " +
-      "task pane once so it reconnects, then retry this same call.";
+      "\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 " +
@@ -134,6 +154,9 @@ const server = new McpServer(
       "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.",
   },
 );
@@ -170,7 +193,10 @@ server.registerTool(
       "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).",
+      "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()
@@ -196,15 +222,46 @@ server.registerTool(
         .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 }) => {
+  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) {
@@ -216,38 +273,75 @@ server.registerTool(
 server.registerTool(
   "slidemind_search_engine",
   {
-    title: "Search the brand engine for imagery",
+    title: "Search an engine for imagery or slides",
     description:
-      "Search the active corporate design's brand engine over the bridge (icons/images today; slide engines later). " +
-      "Uses the add-in's server-side bridge when available, 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.",
+      "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()
-        .describe("presId from slidemind_list_open_presentations."),
+        .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', 'data pipeline'."),
+        .describe("Concept query, e.g. 'shield', 'handshake', 'revenue bridge'."),
       engine_id: z
         .string()
         .nullable()
         .optional()
-        .describe("Engine id from the design bundle's engines[]. Omit/null = first image engine."),
+        .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 }) => {
+  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.
-      await client.requireHost();
+      const registry = await client.requireHost();
+      // 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(presentation_id);
+        const mat = await materializeBundle(presId, { backendURL });
         const pick = pickImageEngine(readEnginesFromDir(mat.dir));
         if (!pick) {
           return errorResult(
@@ -257,27 +351,55 @@ server.registerTool(
           );
         }
         engineId = pick.id;
+        subtype = "image";
       }
-      const res = await client.engineSearch({
-        presId: presentation_id,
+      // 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 ?? (res?.thumbnails?.length ?? 0),
-            results: (res?.thumbnails ?? []).map((t, i) => ({
-              selection: i + 1,
-              title: t.title ?? null,
-            })),
+            resultCount: res?.resultCount ?? results.length,
+            results,
           },
           null,
           2,
@@ -290,6 +412,231 @@ server.registerTool(
   },
 );
 
+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.requireHost();
+      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.requireHost();
+      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.requireHost();
+      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
@@ -347,7 +694,7 @@ server.registerTool(
     inputSchema: {
       presentation_id: z
         .string()
-        .describe("presId — must match the slidemind_search_engine call."),
+        .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/)."),