slides-studio-mcp 0.1.0-beta.3 → 0.1.0-beta.4

package/README.md

@@ -6,6 +6,29 @@ Local-first MCP companion for the hosted [Slide Studio test editor](https://slid
 npx slides-studio-mcp@beta setup
 ```
 
+If an agent is doing the setup itself, it should select its current client and run non-interactively:
+
+```bash
+npx slides-studio-mcp@beta setup --client=codex --yes
+```
+
+Replace `codex` with `claude`, `hermes`, `opencode`, or `openclaw` for the agent doing the setup. OpenCode prints the version-appropriate JSON to merge into its config. Other detected clients are configured through their official CLI.
+
+## Use it immediately without restarting
+
+Some clients do not add a newly configured MCP server to the tool catalog of the already-running session. The same validated tool surface is available through the package CLI, so the current agent can continue immediately:
+
+```bash
+npx -y slides-studio-mcp@beta call get_design_guidance
+npx -y slides-studio-mcp@beta call list_editors
+npx -y slides-studio-mcp@beta call list_tools --json '{"names":["add_slide","add_text"]}'
+npx -y slides-studio-mcp@beta call create_project --json '{"name":"My presentation"}'
+```
+
+Every MCP tool name and JSON argument shape works with `call`. The CLI-only `list_tools` helper lists all names compactly, or returns schemas for the requested names. The CLI automatically applies the guidance gate for each invocation and prints compact JSON. `render_slide` writes image output to a temporary `previewPath` instead of dumping base64 into the terminal.
+
+Hermes can refresh native tools without restarting by running `/reload-mcp`, then `/reload-skills`. Claude may still need a new session to register a newly added plain stdio server, but its current session can use the CLI fallback instead of stopping.
+
 The companion binds only to `127.0.0.1`. There is no hosted relay: projects remain in browser IndexedDB and local images remain on the user's computer.
 
 Any MCP client can launch it with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slides-studio-mcp",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Local-first MCP companion for the hosted Slide Studio editor",
   "type": "module",
   "license": "MIT",

package/skill/slide-studio/SKILL.md

@@ -7,6 +7,17 @@ description: Create, edit, visually inspect, and export Slide Studio carousel sl
 
 Use the Slide Studio MCP tools for all presentation changes. The hosted browser editor is the live visual surface; local files and rendered images pass only through the local companion.
 
+If the native MCP tools are not registered in the current session, do not stop or ask for a restart. Use the same validated tools through the local CLI fallback:
+
+```bash
+npx -y slides-studio-mcp@beta call get_design_guidance
+npx -y slides-studio-mcp@beta call list_editors
+npx -y slides-studio-mcp@beta call list_tools --json '{"names":["add_slide","add_text"]}'
+npx -y slides-studio-mcp@beta call create_project --json '{"name":"My presentation"}'
+```
+
+Every tool accepts the same JSON arguments as MCP. Use `list_tools` without arguments for compact discovery or pass `{"names":[...]}` to retrieve selected schemas. Prefer `apply_operations` for batches. `render_slide` writes its returned image to a temporary local `previewPath`; inspect that file and remove the temporary directory after the review. Hermes can load the native tools in place with `/reload-mcp` and refresh this skill with `/reload-skills`.
+
 Before the first mutation in a task, call `get_design_guidance`. The server intentionally rejects mutations until this guidance has been read.
 
 Inspect the editor before editing and keep the returned IDs. Work on the requested project and slide; do not infer targets when multiple editors or projects are ambiguous. Prefer `apply_operations` for compact related changes, while preserving logical edit order.

package/src/call.mjs

@@ -0,0 +1,124 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const CLI_PATH = fileURLToPath(new URL("cli.mjs", import.meta.url));
+
+async function stdinText() {
+  if (process.stdin.isTTY) return "";
+  let value = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) value += chunk;
+  return value.trim();
+}
+
+async function parseArguments(arguments_) {
+  const [toolName, ...rest] = arguments_;
+  if (!toolName) throw new Error("Usage: slides-studio-mcp call <tool> [--json '{\"key\":\"value\"}']");
+  const inline = rest.find((value) => value.startsWith("--json="));
+  const flagIndex = rest.indexOf("--json");
+  const raw = inline?.slice("--json=".length)
+    || (flagIndex >= 0 ? rest[flagIndex + 1] : rest.find((value) => !value.startsWith("--")))
+    || (rest.includes("--stdin") ? await stdinText() : "")
+    || "{}";
+  let args;
+  try { args = JSON.parse(raw); }
+  catch { throw new Error("--json must be a valid JSON object."); }
+  if (!args || Array.isArray(args) || typeof args !== "object") throw new Error("--json must be a JSON object.");
+  return { toolName, args };
+}
+
+async function printableResult(toolName, result) {
+  const error = result.isError && result.content?.find((item) => item.type === "text")?.text;
+  if (error) throw new Error(error);
+  if (toolName === "get_design_guidance") return { guidance: result.content?.find((item) => item.type === "text")?.text || "" };
+  const image = result.content?.find((item) => item.type === "image" && item.data);
+  if (!image) return result.structuredContent ?? { content: result.content || [] };
+  const extension = image.mimeType === "image/jpeg" ? "jpg" : "png";
+  const directory = await mkdtemp(join(tmpdir(), "slide-studio-preview-"));
+  const previewPath = join(directory, `slide.${extension}`);
+  await writeFile(previewPath, Buffer.from(image.data, "base64"));
+  return { ...(result.structuredContent || {}), previewPath, temporary: true };
+}
+
+function createRpc(child) {
+  let input = "";
+  let id = 0;
+  const pending = new Map();
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    input += chunk;
+    let newline;
+    while ((newline = input.indexOf("\n")) >= 0) {
+      const line = input.slice(0, newline).trim();
+      input = input.slice(newline + 1);
+      if (!line) continue;
+      const message = JSON.parse(line);
+      const waiter = pending.get(message.id);
+      if (!waiter) continue;
+      pending.delete(message.id);
+      clearTimeout(waiter.timer);
+      message.error ? waiter.reject(new Error(message.error.message)) : waiter.resolve(message.result);
+    }
+  });
+  child.once("exit", (code) => {
+    for (const waiter of pending.values()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error(`Local MCP process exited before replying${code == null ? "" : ` (${code})`}.`));
+    }
+    pending.clear();
+  });
+  return {
+    notify(method, params = {}) { child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`); },
+    request(method, params = {}) {
+      const requestId = ++id;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(requestId); reject(new Error(`Timed out waiting for ${method}.`)); }, 120_000);
+        pending.set(requestId, { resolve, reject, timer });
+        child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: requestId, method, params })}\n`);
+      });
+    },
+  };
+}
+
+async function stopChild(child) {
+  if (child.exitCode != null) return;
+  child.stdin.end();
+  const exited = new Promise((resolve) => child.once("exit", resolve));
+  const timeout = new Promise((resolve) => { const timer = setTimeout(resolve, 2000); timer.unref(); });
+  await Promise.race([exited, timeout]);
+  if (child.exitCode == null) child.kill("SIGTERM");
+}
+
+export async function runCall(arguments_) {
+  const { toolName, args } = await parseArguments(arguments_);
+  const child = spawn(process.execPath, [CLI_PATH, "serve"], { cwd: process.cwd(), env: process.env, stdio: ["pipe", "pipe", "pipe"] });
+  let errors = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => { errors = `${errors}${chunk}`.slice(-4000); });
+  const rpc = createRpc(child);
+  try {
+    await rpc.request("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "Slide Studio CLI fallback", version: "1" } });
+    rpc.notify("notifications/initialized");
+    if (toolName === "list_tools") {
+      const listed = await rpc.request("tools/list");
+      const requested = Array.isArray(args.names) ? new Set(args.names.map(String)) : null;
+      const tools = listed.tools.filter((tool) => !requested || requested.has(tool.name)).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        ...(requested ? { inputSchema: tool.inputSchema } : {}),
+      }));
+      process.stdout.write(`${JSON.stringify({ tools }, null, 2)}\n`);
+      return;
+    }
+    if (toolName !== "get_design_guidance") await rpc.request("tools/call", { name: "get_design_guidance", arguments: {} });
+    const result = await rpc.request("tools/call", { name: toolName, arguments: args });
+    process.stdout.write(`${JSON.stringify(await printableResult(toolName, result), null, 2)}\n`);
+  } catch (error) {
+    throw new Error(`${error.message}${errors ? `\n${errors.trim()}` : ""}`);
+  } finally {
+    await stopChild(child);
+  }
+}

package/src/cli.mjs

@@ -15,6 +15,11 @@ async function main() {
     await runSetup(arguments_);
     return;
   }
+  if (command === "call") {
+    const { runCall } = await import("./call.mjs");
+    await runCall(arguments_);
+    return;
+  }
   if (command === "doctor") {
     const health = await companionDoctor();
     process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, packageVersion: PACKAGE_VERSION, editor: TEST_EDITOR_URL, daemon: health }, null, 2)}\n`);
@@ -25,7 +30,7 @@ async function main() {
     return;
   }
   if (command === "help" || command === "--help" || command === "-h") {
-    process.stdout.write(`Slide Studio MCP ${PACKAGE_VERSION}\n\nUsage:\n  slides-studio-mcp serve\n  slides-studio-mcp setup [--client=claude,codex,hermes,opencode,openclaw] [--yes] [--dry-run]\n  slides-studio-mcp doctor\n  slides-studio-mcp version\n`);
+    process.stdout.write(`Slide Studio MCP ${PACKAGE_VERSION}\n\nUsage:\n  slides-studio-mcp serve\n  slides-studio-mcp setup [--client=claude,codex,hermes,opencode,openclaw] [--yes] [--dry-run]\n  slides-studio-mcp call <tool> [--json '{"key":"value"}'] [--stdin]\n  slides-studio-mcp doctor\n  slides-studio-mcp version\n`);
     return;
   }
   throw new Error(`Unknown command: ${command}`);

package/src/mcp-server.mjs

@@ -33,7 +33,7 @@ function textResult(value, summary = value) {
 }
 
 function compactMutation(value) {
-  const keys = ["projectId", "slideId", "revision", "createdSlideId", "createdTextId", "createdImageId", "assetId", "deletedProjectId", "deletedSlideId", "deletedLayerIds", "updatedTextIds", "updatedImageIds", "applied", "path", "bytes"];
+  const keys = ["projectId", "slideId", "revision", "opened", "createdSlideId", "createdTextId", "createdImageId", "assetId", "deletedProjectId", "deletedSlideId", "deletedLayerIds", "updatedTextIds", "updatedImageIds", "applied", "path", "bytes"];
   return Object.fromEntries(keys.flatMap((key) => value?.[key] == null ? [] : [[key, value[key]]]));
 }
 
@@ -141,7 +141,7 @@ export async function createSlideStudioMcpServer(companion) {
   register("inspect_editor", "Inspect projects, slides, assets, and every text/image layer without returning image bytes.", z.object({ ...targetSlide, includeAllProjects: z.boolean().default(true) }).strict(), (args) => browserOperation(companion, "inspect_editor", args), { readOnlyHint: true });
   register("show_notification", "Show a short visual notification in the connected editor for status or marketing demos.", z.object({ message: z.string().min(1).max(240), tone: z.enum(["agent", "success", "info", "error"]).default("agent") }).strict(), (args) => companion.call("notify", args), { destructiveHint: false, idempotentHint: false });
 
-  register("create_project", "Create and open an empty project.", z.object({ name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "create_project", args), { destructiveHint: false });
+  register("create_project", "Create an empty project. If the dashboard is visible, its card appears live; adding the first slide opens the editor.", z.object({ name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "create_project", args), { destructiveHint: false });
   register("open_project", "Open a project and optionally a specific slide without changing content.", z.object({ projectId: id, slideId: optionalId }).strict(), (args) => browserOperation(companion, "open_project", args), { destructiveHint: false, idempotentHint: true });
   register("update_project", "Rename a project.", z.object({ ...targetProject, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "update_project", args), { destructiveHint: true });
   register("delete_project", "Delete a project from browser storage.", z.object({ ...targetProject, projectId: id }).strict(), (args) => browserOperation(companion, "delete_project", args), { destructiveHint: true });

package/src/setup.mjs

@@ -89,7 +89,10 @@ export async function runSetup(arguments_) {
     else process.stderr.write(`Could not configure ${client}; its command is printed above for manual setup.\n`);
   }
   const skillTargets = await installSkill();
-  process.stdout.write(`\nConfigured: ${configured.join(", ") || "none automatically"}\nSkill installed in:\n${skillTargets.map((value) => `  ${value}`).join("\n")}\n\nOpen ${TEST_EDITOR_URL}, click Connect AI, and restart the configured agent.\n`);
+  process.stdout.write(`\nConfigured: ${configured.join(", ") || "none automatically"}\nSkill installed in:\n${skillTargets.map((value) => `  ${value}`).join("\n")}\n\nOpen ${TEST_EDITOR_URL} and click Connect AI.\n`);
+  process.stdout.write(`Current-session fallback (no restart): npx -y ${specifier} call list_editors\n`);
+  if (clients.includes("hermes")) process.stdout.write("Hermes can also refresh native tools in place with /reload-mcp and /reload-skills.\n");
+  if (clients.includes("claude")) process.stdout.write("Claude may require a new session for native MCP registration; use the CLI fallback immediately instead of stopping.\n");
   if (clients.includes("opencode")) process.stdout.write("OpenCode currently uses its JSON config; merge the snippet printed above into opencode.json.\n");
   return { clients, configured, skillTargets };
 }

package/src/stdio-server.mjs

@@ -18,6 +18,6 @@ export async function serveMcp() {
   process.once("SIGINT", () => void close().finally(() => process.exit()));
   process.once("SIGTERM", () => void close().finally(() => process.exit()));
   process.once("SIGHUP", () => void close().finally(() => process.exit()));
-  process.stdin.once("end", () => void close());
+  process.stdin.once("end", () => void close().finally(() => process.exit()));
   return { handle, companion, close };
 }