slides-studio-mcp 0.1.0-beta.1

package/README.md

@@ -0,0 +1,24 @@
+# Slide Studio MCP
+
+Local-first MCP companion for the hosted [Slide Studio test editor](https://slides-mcp-poc-0821.pages.dev). It exposes complete project, slide, text, image, layer, history, rendering, and export controls to any stdio MCP client while the editor remains in the browser.
+
+```bash
+npx slides-studio-mcp@beta setup
+```
+
+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:
+
+```bash
+npx -y slides-studio-mcp@beta serve
+```
+
+Useful commands:
+
+```bash
+npx slides-studio-mcp@beta setup --dry-run
+npx slides-studio-mcp@beta doctor
+```
+
+Open the test editor, click **Connect AI**, and call `get_design_guidance` before editing. The server enforces that one-time read and provides `render_slide` so agents can inspect actual pixels without permanently storing previews.

package/guidance/design.md

@@ -0,0 +1,44 @@
+# Slide Studio design guidance
+
+Read this before creating or editing slides. Use it as a compact quality bar, then inspect the rendered slide instead of assuming code values look good.
+
+## Defaults that usually look good
+
+- Build for a 9:16 phone canvas and keep one clear idea per slide.
+- Prefer `boxed` text with `backgroundShape: "lines"` for highlighted copy. The per-line treatment is the product's strongest default.
+- Avoid `backgroundShape: "full"` unless a deliberate large label or card is required. A large rectangular text box usually looks heavy.
+- Use plain or outlined text for supporting copy. Use no more than two text treatments on one slide.
+- Start headlines around 64–88 px and supporting text around 42–60 px. Adjust after rendering.
+- Keep important content inside roughly `x: 0.06..0.86` and `y: 0.08..0.78` when the TikTok overlay matters. The right and bottom edges are occupied by interface controls and captions.
+- Give text boxes generous width and height. Leave at least 0.04 of canvas width beyond the visible longest line and enough height for every line plus its background. Never let glyphs or rounded backgrounds touch a box edge.
+- Use short lines. Two to four lines for a headline is usually stronger than one dense paragraph.
+- Keep strong contrast between copy and the image. Use black boxed backgrounds with white text or white boxed backgrounds with near-black text.
+- Preserve an obvious focal image. Do not cover faces or the main subject unless the composition intentionally calls for it.
+- Align related text layers consistently. Center is a safe default; use left alignment for editorial layouts.
+- Use rotation sparingly. Small intentional angles can add energy; arbitrary angles make carousels feel inconsistent.
+- Reuse a small palette and consistent type scale across the project.
+
+## Working method
+
+1. Inspect the editor and use the returned project, slide, asset, and layer IDs.
+2. Create or update one slide at a time. The editor automatically switches to the most recently changed slide.
+3. Use `apply_operations` when several related edits can be expressed compactly; the browser still shows each operation live.
+4. Call `render_slide` after a meaningful composition change and look at the returned image.
+5. Correct clipping, collisions, weak contrast, unsafe placement, inconsistent spacing, and visual imbalance before continuing.
+6. Render the complete set at least once before exporting.
+
+## Text-box clipping checklist
+
+- Increase width before shrinking type when a line almost fits.
+- Increase height when multiline text or per-line backgrounds approach the top or bottom edge.
+- Keep `x + width` and `y + height` within the canvas unless an off-canvas effect is intentional.
+- With boxed text, keep `backgroundShape: "lines"` and do not size the box tightly around the letters; rounded pills need breathing room.
+- If the result is uncertain, render it. Numeric state is not a visual review.
+
+## Agent behavior
+
+- Do not delete projects, slides, assets, or layers unless the request calls for it.
+- Do not overwrite an existing export unless explicitly requested.
+- Keep tool responses and progress messages concise.
+- Prefer IDs returned by tools over guessed names or array positions.
+- Do not claim a slide looks good until you have inspected a rendered image.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "slides-studio-mcp",
+  "version": "0.1.0-beta.1",
+  "description": "Local-first MCP companion for the hosted Slide Studio editor",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexgusevski/tiktokslideeditor.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://slides-mcp-poc-0821.pages.dev",
+  "bugs": "https://github.com/alexgusevski/tiktokslideeditor/issues",
+  "bin": {
+    "slides-studio-mcp": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "guidance",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skill/slide-studio/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: slide-studio
+description: Create, edit, visually inspect, and export Slide Studio carousel slides through the local Slide Studio MCP companion.
+---
+
+# Slide Studio
+
+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.
+
+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.
+
+After each meaningful composition or after a short batch, call `render_slide` and inspect the returned image. Fix clipping, spacing, contrast, unsafe TikTok-overlay placement, and weak hierarchy before claiming the slide is finished. Use `export_slide` or `export_project` only when local files are requested; do not overwrite existing files unless authorized.
+
+The browser automatically opens the latest slide changed by an agent. Use `show_notification` only for short, useful status messages.

package/src/cli.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { companionDoctor } from "./companion.mjs";
+import { PACKAGE_NAME, PACKAGE_VERSION, TEST_EDITOR_URL } from "./config.mjs";
+import { runSetup } from "./setup.mjs";
+import { serveMcp } from "./stdio-server.mjs";
+
+const [command = "serve", ...arguments_] = process.argv.slice(2);
+
+async function main() {
+  if (command === "serve") {
+    await serveMcp();
+    return;
+  }
+  if (command === "setup") {
+    await runSetup(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`);
+    return;
+  }
+  if (command === "version" || command === "--version" || command === "-v") {
+    process.stdout.write(`${PACKAGE_VERSION}\n`);
+    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`);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(1);
+});

package/src/companion.mjs

@@ -0,0 +1,97 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BRIDGE_URL, DAEMON_STATE_PATH, PACKAGE_VERSION, PROTOCOL_VERSION } from "./config.mjs";
+
+const DAEMON_ENTRY = fileURLToPath(new URL("daemon.mjs", import.meta.url));
+
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function readState() {
+  try { return JSON.parse(await readFile(DAEMON_STATE_PATH, "utf8")); }
+  catch { return null; }
+}
+
+async function daemonRequest(state, path, init = {}) {
+  const response = await fetch(`${BRIDGE_URL}${path}`, {
+    ...init,
+    headers: { "Authorization": `Bearer ${state.secret}`, "Content-Type": "application/json", ...(init.headers || {}) },
+  });
+  const value = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(value.error || `Local companion returned ${response.status}.`);
+  return value;
+}
+
+async function healthyState() {
+  const state = await readState();
+  if (!state?.secret || state.port == null) return null;
+  try {
+    const result = await daemonRequest(state, "/internal/health");
+    if (result.protocolVersion !== PROTOCOL_VERSION) throw new Error(`Local companion protocol ${result.protocolVersion} is incompatible with package protocol ${PROTOCOL_VERSION}. Restart all Slide Studio MCP clients.`);
+    return state;
+  } catch (error) {
+    if (String(error.message).includes("incompatible")) throw error;
+    return null;
+  }
+}
+
+async function ensureDaemon() {
+  const existing = await healthyState();
+  if (existing) return existing;
+  const child = spawn(process.execPath, [DAEMON_ENTRY], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline) {
+    await wait(100);
+    const state = await healthyState();
+    if (state) return state;
+  }
+  throw new Error("Could not start the local Slide Studio companion. Run `npx slides-studio-mcp doctor` for details.");
+}
+
+export async function createCompanion(initialName = "MCP agent", initialVersion = null) {
+  const state = await ensureDaemon();
+  const clientId = randomUUID();
+  let clientName = initialName;
+  let clientVersion = initialVersion;
+  let closed = false;
+
+  const post = (path, body) => daemonRequest(state, path, { method: "POST", body: JSON.stringify(body) });
+  const register = () => post("/internal/client/connect", { clientId, name: clientName, version: clientVersion });
+  await register();
+  const heartbeat = setInterval(() => {
+    if (!closed) void post("/internal/client/heartbeat", { clientId }).catch(() => {});
+  }, 15_000);
+  heartbeat.unref();
+
+  return {
+    clientId,
+    daemon: { pid: state.pid, url: BRIDGE_URL, version: state.version, packageVersion: PACKAGE_VERSION },
+    async identify(name, version) {
+      clientName = name || clientName;
+      clientVersion = version || clientVersion;
+      await register();
+    },
+    async call(action, body = {}) {
+      const response = await post("/internal/call", { clientId, action, ...body });
+      return response.result;
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      clearInterval(heartbeat);
+      await post("/internal/client/disconnect", { clientId }).catch(() => {});
+    },
+  };
+}
+
+export async function companionDoctor() {
+  const state = await ensureDaemon();
+  const health = await daemonRequest(state, "/internal/health");
+  return { ...health, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH };
+}

package/src/config.mjs

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+export const PACKAGE_JSON = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+export const PACKAGE_NAME = PACKAGE_JSON.name;
+export const PACKAGE_VERSION = PACKAGE_JSON.version;
+export const PROTOCOL_VERSION = 1;
+export const BRIDGE_HOST = "127.0.0.1";
+export const BRIDGE_PORT = Number(process.env.SLIDE_STUDIO_BRIDGE_PORT) || 43117;
+export const BRIDGE_URL = `http://${BRIDGE_HOST}:${BRIDGE_PORT}`;
+export const TEST_EDITOR_URL = "https://slides-mcp-poc-0821.pages.dev";
+export const ALLOWED_ORIGINS = new Set((process.env.SLIDE_STUDIO_ALLOWED_ORIGINS || [
+  TEST_EDITOR_URL,
+  "http://127.0.0.1:4173",
+  "http://localhost:4173",
+].join(",")).split(",").map((value) => value.trim()).filter(Boolean));
+export const GUIDANCE_PATH = join(PACKAGE_ROOT, "guidance", "design.md");
+
+function defaultStateDirectory() {
+  if (process.env.SLIDE_STUDIO_STATE_DIR) return process.env.SLIDE_STUDIO_STATE_DIR;
+  if (platform() === "win32") return join(process.env.LOCALAPPDATA || homedir(), "SlideStudioMCP");
+  if (platform() === "darwin") return join(homedir(), "Library", "Caches", "SlideStudioMCP");
+  return join(process.env.XDG_RUNTIME_DIR || join(homedir(), ".cache"), "slides-studio-mcp");
+}
+
+export const STATE_DIRECTORY = defaultStateDirectory();
+export const DAEMON_STATE_PATH = join(STATE_DIRECTORY, `daemon-${BRIDGE_PORT}.json`);
+export const DAEMON_LOCK_PATH = join(STATE_DIRECTORY, `daemon-${BRIDGE_PORT}.lock`);

package/src/daemon.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { randomBytes, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import {
+  ALLOWED_ORIGINS, BRIDGE_HOST, BRIDGE_PORT, BRIDGE_URL, DAEMON_LOCK_PATH,
+  DAEMON_STATE_PATH, PACKAGE_NAME, PACKAGE_VERSION, PROTOCOL_VERSION, STATE_DIRECTORY,
+} from "./config.mjs";
+
+const MAX_JSON_BYTES = 40 * 1024 * 1024;
+const MAX_MEDIA_BYTES = 25 * 1024 * 1024;
+const EDITOR_TTL_MS = 45_000;
+const CLIENT_TTL_MS = 45_000;
+const MEDIA_TTL_MS = 5 * 60_000;
+const COMMAND_TIMEOUT_MS = 90_000;
+const daemonSecret = randomBytes(32).toString("base64url");
+const editors = new Map();
+const clients = new Map();
+const inflight = new Map();
+const media = new Map();
+let focusedEditorId = null;
+let lockHandle = null;
+let idleSince = null;
+
+function log(message) {
+  process.stderr.write(`[slide-studio-daemon] ${message}\n`);
+}
+
+function activeEditors() {
+  const cutoff = Date.now() - EDITOR_TTL_MS;
+  return [...editors.values()].filter((editor) => editor.lastSeen >= cutoff);
+}
+
+function activeClients() {
+  const cutoff = Date.now() - CLIENT_TTL_MS;
+  return [...clients.values()].filter((client) => client.lastSeen >= cutoff);
+}
+
+function publicClient(client) {
+  return { id: client.id, name: client.name || "MCP agent", version: client.version || null };
+}
+
+function browserCors(origin) {
+  if (!origin || !ALLOWED_ORIGINS.has(origin)) return null;
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Authorization, Content-Type",
+    "Access-Control-Expose-Headers": "X-Slide-Studio-Filename",
+    "Access-Control-Allow-Private-Network": "true",
+    "Access-Control-Max-Age": "600",
+    "Cache-Control": "no-store",
+    Vary: "Origin",
+  };
+}
+
+function sendJson(response, statusCode, value, headers = {}) {
+  const body = JSON.stringify(value);
+  response.writeHead(statusCode, { "Content-Type": "application/json; charset=utf-8", "Content-Length": Buffer.byteLength(body), "Cache-Control": "no-store", ...headers });
+  response.end(body);
+}
+
+function readJson(request) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    request.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_JSON_BYTES) {
+        reject(new Error("Request body is too large."));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on("end", () => {
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}")); }
+      catch { reject(new Error("Request body must be valid JSON.")); }
+    });
+    request.on("error", reject);
+  });
+}
+
+function bearer(request) {
+  const value = request.headers.authorization || "";
+  return value.startsWith("Bearer ") ? value.slice(7) : null;
+}
+
+function requireInternal(request, response) {
+  if (bearer(request) === daemonSecret) return true;
+  sendJson(response, 401, { error: "Unauthorized." });
+  return false;
+}
+
+function requireEditor(request, response, editorId, cors) {
+  const editor = editors.get(editorId);
+  if (!editor || bearer(request) !== editor.sessionToken) {
+    sendJson(response, 401, { error: "Editor session is not authorized." }, cors);
+    return null;
+  }
+  editor.lastSeen = Date.now();
+  return editor;
+}
+
+function queueEditorEvent(editor, event) {
+  editor.queue.push(event);
+  if (editor.queue.length > 100) editor.queue.splice(0, editor.queue.length - 100);
+  deliverNext(editor);
+}
+
+function deliverNext(editor) {
+  if (!editor?.poll || !editor.queue.length) return;
+  const response = editor.poll;
+  editor.poll = null;
+  sendJson(response, 200, editor.queue.shift(), editor.cors);
+}
+
+function broadcastAgents() {
+  const event = { kind: "system", type: "agents.changed", agents: activeClients().map(publicClient) };
+  for (const editor of activeEditors()) queueEditorEvent(editor, event);
+}
+
+function selectEditor(clientId) {
+  const connected = activeEditors();
+  const client = clients.get(clientId);
+  const selected = client?.selectedEditorId && connected.find((editor) => editor.id === client.selectedEditorId);
+  if (selected) return selected;
+  const focused = focusedEditorId && connected.find((editor) => editor.id === focusedEditorId);
+  if (focused) return focused;
+  if (connected.length === 1) return connected[0];
+  if (!connected.length) throw new Error("No Slide Studio editor is connected. Open the test editor and click Connect AI.");
+  throw new Error("Multiple editors are connected and none is selected. Call list_editors, then select_editor.");
+}
+
+function callBrowser(clientId, toolName, operation, label) {
+  const editor = selectEditor(clientId);
+  const client = clients.get(clientId) || { id: clientId, name: "MCP agent" };
+  const requestId = randomUUID();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      inflight.delete(requestId);
+      reject(new Error("The browser did not answer within 90 seconds."));
+    }, COMMAND_TIMEOUT_MS);
+    inflight.set(requestId, { resolve, reject, timer, editorId: editor.id });
+    queueEditorEvent(editor, { kind: "command", requestId, toolName, operation, label, agent: publicClient(client) });
+  });
+}
+
+function detectedMime(buffer, filename) {
+  if (buffer.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return "image/png";
+  if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return "image/jpeg";
+  if (["GIF87a", "GIF89a"].includes(buffer.subarray(0, 6).toString("ascii"))) return "image/gif";
+  if (buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP") return "image/webp";
+  const header = buffer.subarray(0, 64).toString("ascii");
+  if (/ftyp(?:avif|avis)/.test(header)) return "image/avif";
+  const text = buffer.subarray(0, 1024).toString("utf8").trimStart();
+  if (/^(?:<\?xml[^>]*>\s*)?<svg[\s>]/i.test(text)) return "image/svg+xml";
+  const extension = extname(filename).toLowerCase();
+  if (extension === ".jpg" || extension === ".jpeg") return "image/jpeg";
+  return null;
+}
+
+async function prepareMedia(filePath) {
+  const metadata = await stat(filePath);
+  if (!metadata.isFile()) throw new Error("Image path must point to a regular file.");
+  if (metadata.size > MAX_MEDIA_BYTES) throw new Error("Image is larger than the 25 MB local-transfer limit.");
+  const buffer = await readFile(filePath);
+  const mimeType = detectedMime(buffer, filePath);
+  if (!mimeType) throw new Error("Unsupported image. Use PNG, JPEG, WebP, GIF, SVG, or AVIF.");
+  const id = randomUUID();
+  media.set(id, { id, buffer, mimeType, filename: basename(filePath), expiresAt: Date.now() + MEDIA_TTL_MS });
+  return { mediaId: id, filename: basename(filePath), mimeType, size: buffer.length };
+}
+
+async function writeExport(filePath, data, overwrite) {
+  const buffer = Buffer.from(data, "base64");
+  const handle = await open(filePath, overwrite ? "w" : "wx", 0o600).catch((error) => {
+    if (error.code === "EEXIST") throw new Error(`Export already exists: ${filePath}. Set overwrite=true only when intended.`);
+    throw error;
+  });
+  try { await handle.writeFile(buffer); } finally { await handle.close(); }
+  return { path: filePath, bytes: buffer.length };
+}
+
+async function handleInternalCall(body) {
+  const client = clients.get(body.clientId);
+  if (!client) throw new Error("MCP client session is not registered.");
+  client.lastSeen = Date.now();
+  if (body.action === "list_editors") {
+    return {
+      selectedEditorId: client.selectedEditorId || focusedEditorId || null,
+      editors: activeEditors().map((editor) => ({ id: editor.id, selected: editor.id === client.selectedEditorId, focused: editor.id === focusedEditorId, pageUrl: editor.pageUrl, state: editor.state })),
+    };
+  }
+  if (body.action === "select_editor") {
+    const editor = activeEditors().find((item) => item.id === body.editorId);
+    if (!editor) throw new Error(`Editor is not connected: ${body.editorId}`);
+    client.selectedEditorId = editor.id;
+    return { editorId: editor.id, pageUrl: editor.pageUrl, state: editor.state };
+  }
+  if (body.action === "prepare_media") return prepareMedia(body.path);
+  if (body.action === "write_export") return writeExport(body.path, body.data, Boolean(body.overwrite));
+  if (body.action === "notify") {
+    const editor = selectEditor(body.clientId);
+    queueEditorEvent(editor, { kind: "system", type: "notification", message: body.message, tone: body.tone, agent: publicClient(client) });
+    return { shown: true, editorId: editor.id };
+  }
+  if (body.action === "browser") return callBrowser(body.clientId, body.toolName, body.operation, body.label);
+  if (body.action === "batch") {
+    const results = [];
+    for (const item of body.items) results.push(await callBrowser(body.clientId, "apply_operations", item.operation, item.label));
+    return { applied: results.length, results };
+  }
+  throw new Error(`Unknown internal action: ${body.action}`);
+}
+
+const server = createServer(async (request, response) => {
+  const host = request.headers.host || "";
+  if (![`${BRIDGE_HOST}:${BRIDGE_PORT}`, `localhost:${BRIDGE_PORT}`].includes(host)) return sendJson(response, 421, { error: "Invalid Host header." });
+  const url = new URL(request.url || "/", BRIDGE_URL);
+  const origin = request.headers.origin;
+  const cors = browserCors(origin);
+
+  if (request.method === "OPTIONS") {
+    if (!cors) return sendJson(response, 403, { error: "Origin not allowed." });
+    response.writeHead(204, cors);
+    response.end();
+    return;
+  }
+  if (url.pathname === "/health" && request.method === "GET") {
+    if (origin && !cors) return sendJson(response, 403, { error: "Origin not allowed." });
+    return sendJson(response, 200, { ok: true, service: PACKAGE_NAME, version: PACKAGE_VERSION, protocolVersion: PROTOCOL_VERSION, editors: activeEditors().length, agents: activeClients().length }, cors || {});
+  }
+
+  try {
+    if (url.pathname.startsWith("/internal/")) {
+      if (!requireInternal(request, response)) return;
+      if (url.pathname === "/internal/health" && request.method === "GET") return sendJson(response, 200, { ok: true, pid: process.pid, version: PACKAGE_VERSION, protocolVersion: PROTOCOL_VERSION });
+      const body = await readJson(request);
+      if (url.pathname === "/internal/client/connect" && request.method === "POST") {
+        const existing = clients.get(body.clientId) || { id: body.clientId };
+        Object.assign(existing, { name: body.name || existing.name || "MCP agent", version: body.version || existing.version || null, lastSeen: Date.now() });
+        clients.set(existing.id, existing);
+        broadcastAgents();
+        return sendJson(response, 200, { ok: true, client: publicClient(existing) });
+      }
+      if (url.pathname === "/internal/client/disconnect" && request.method === "POST") {
+        clients.delete(body.clientId);
+        broadcastAgents();
+        return sendJson(response, 200, { ok: true });
+      }
+      if (url.pathname === "/internal/client/heartbeat" && request.method === "POST") {
+        const client = clients.get(body.clientId);
+        if (client) client.lastSeen = Date.now();
+        return sendJson(response, 200, { ok: Boolean(client) });
+      }
+      if (url.pathname === "/internal/call" && request.method === "POST") return sendJson(response, 200, { ok: true, result: await handleInternalCall(body) });
+      return sendJson(response, 404, { error: "Internal endpoint not found." });
+    }
+
+    if (!cors) return sendJson(response, 403, { error: "Origin not allowed." });
+    if (url.pathname === "/connect" && request.method === "POST") {
+      const body = await readJson(request);
+      if (!body.editorId || typeof body.editorId !== "string") return sendJson(response, 400, { error: "editorId is required." }, cors);
+      if (body.protocolVersion !== PROTOCOL_VERSION) return sendJson(response, 409, { error: `Protocol mismatch. Browser=${body.protocolVersion}; companion=${PROTOCOL_VERSION}.`, protocolVersion: PROTOCOL_VERSION }, cors);
+      const previous = editors.get(body.editorId);
+      if (previous?.poll) { previous.poll.writeHead(204, previous.cors); previous.poll.end(); }
+      const editor = {
+        id: body.editorId, queue: previous?.queue || [], poll: null, pageUrl: body.pageUrl,
+        state: body.state, lastSeen: Date.now(), cors, sessionToken: randomBytes(32).toString("base64url"),
+      };
+      editors.set(editor.id, editor);
+      if (body.hasFocus && body.visibilityState === "visible") focusedEditorId = editor.id;
+      log(`Editor connected (${editor.id.slice(0, 8)})`);
+      return sendJson(response, 200, { ok: true, editorId: editor.id, sessionToken: editor.sessionToken, protocolVersion: PROTOCOL_VERSION, agents: activeClients().map(publicClient) }, cors);
+    }
+    if (url.pathname === "/activate" && request.method === "POST") {
+      const body = await readJson(request);
+      const editor = requireEditor(request, response, body.editorId, cors);
+      if (!editor) return;
+      focusedEditorId = editor.id;
+      return sendJson(response, 200, { ok: true, editorId: editor.id }, cors);
+    }
+    if (url.pathname === "/events" && request.method === "GET") {
+      const editor = requireEditor(request, response, url.searchParams.get("editorId"), cors);
+      if (!editor) return;
+      editor.cors = cors;
+      if (editor.poll) { editor.poll.writeHead(204, editor.cors); editor.poll.end(); }
+      editor.poll = response;
+      deliverNext(editor);
+      if (editor.poll) setTimeout(() => {
+        if (editor.poll !== response) return;
+        editor.poll = null;
+        response.writeHead(204, cors);
+        response.end();
+      }, 20_000).unref();
+      return;
+    }
+    if (url.pathname === "/result" && request.method === "POST") {
+      const body = await readJson(request);
+      const editor = requireEditor(request, response, body.editorId, cors);
+      if (!editor) return;
+      const pending = inflight.get(body.requestId);
+      if (!pending || pending.editorId !== editor.id) return sendJson(response, 404, { error: "Unknown request." }, cors);
+      inflight.delete(body.requestId);
+      clearTimeout(pending.timer);
+      if (body.ok) {
+        if (body.result?.project || body.result?.projects) editor.state = body.result;
+        pending.resolve(body.result);
+      } else pending.reject(new Error(body.error || "Browser operation failed."));
+      return sendJson(response, 200, { ok: true }, cors);
+    }
+    if (url.pathname.startsWith("/media/") && request.method === "GET") {
+      const editor = requireEditor(request, response, url.searchParams.get("editorId"), cors);
+      if (!editor) return;
+      const id = decodeURIComponent(url.pathname.slice("/media/".length));
+      const item = media.get(id);
+      if (!item || item.expiresAt < Date.now()) return sendJson(response, 404, { error: "Local image transfer expired." }, cors);
+      media.delete(id);
+      response.writeHead(200, { ...cors, "Content-Type": item.mimeType, "Content-Length": item.buffer.length, "X-Slide-Studio-Filename": encodeURIComponent(item.filename) });
+      response.end(item.buffer);
+      return;
+    }
+    return sendJson(response, 404, { error: "Not found." }, cors);
+  } catch (error) {
+    const headers = cors || {};
+    const statusCode = error.code === "ENOENT" ? 404 : error.code === "EACCES" ? 403 : 400;
+    return sendJson(response, statusCode, { error: error.message }, headers);
+  }
+});
+
+async function acquireDaemonLock() {
+  await mkdir(STATE_DIRECTORY, { recursive: true, mode: 0o700 });
+  try {
+    lockHandle = await open(DAEMON_LOCK_PATH, "wx", 0o600);
+    await lockHandle.writeFile(String(process.pid));
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    try {
+      const lockPid = Number(await readFile(DAEMON_LOCK_PATH, "utf8"));
+      if (!Number.isInteger(lockPid) || lockPid <= 0) throw Object.assign(new Error("Invalid daemon lock."), { code: "ESTALE" });
+      process.kill(lockPid, 0);
+      const running = new Error(`Slide Studio daemon is already running or starting (pid ${lockPid}).`);
+      running.code = "EALREADY";
+      throw running;
+    } catch (checkError) {
+      if (checkError.code === "EALREADY") throw checkError;
+      if (!["ESRCH", "ENOENT", "ESTALE"].includes(checkError.code)) throw checkError;
+      await unlink(DAEMON_LOCK_PATH).catch(() => {});
+      lockHandle = await open(DAEMON_LOCK_PATH, "wx", 0o600);
+      await lockHandle.writeFile(String(process.pid));
+    }
+  }
+}
+
+async function writeDaemonState() {
+  const temporary = `${DAEMON_STATE_PATH}.${process.pid}.tmp`;
+  await writeFile(temporary, JSON.stringify({ pid: process.pid, port: BRIDGE_PORT, secret: daemonSecret, version: PACKAGE_VERSION, protocolVersion: PROTOCOL_VERSION }), { mode: 0o600 });
+  await rename(temporary, DAEMON_STATE_PATH);
+}
+
+async function cleanup() {
+  for (const editor of editors.values()) {
+    if (editor.poll) { editor.poll.writeHead(204, editor.cors || {}); editor.poll.end(); }
+  }
+  for (const pending of inflight.values()) { clearTimeout(pending.timer); pending.reject(new Error("Local companion is shutting down.")); }
+  server.closeAllConnections?.();
+  await new Promise((resolve) => server.close(resolve));
+  const state = await readFile(DAEMON_STATE_PATH, "utf8").then(JSON.parse).catch(() => null);
+  if (state?.pid === process.pid) await unlink(DAEMON_STATE_PATH).catch(() => {});
+  await lockHandle?.close().catch(() => {});
+  await unlink(DAEMON_LOCK_PATH).catch(() => {});
+}
+
+setInterval(() => {
+  const now = Date.now();
+  for (const [id, item] of media) if (item.expiresAt < now) media.delete(id);
+  let clientsChanged = false;
+  for (const [id, client] of clients) if (client.lastSeen < now - CLIENT_TTL_MS) { clients.delete(id); clientsChanged = true; }
+  if (clientsChanged) broadcastAgents();
+  if (activeClients().length || activeEditors().length) idleSince = null;
+  else if (!idleSince) idleSince = now;
+  else if (now - idleSince > 10 * 60_000) void shutdown();
+}, 15_000).unref();
+
+async function main() {
+  await acquireDaemonLock();
+  server.on("error", (error) => { log(`Bridge failed: ${error.message}`); process.exitCode = 1; });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(BRIDGE_PORT, BRIDGE_HOST, resolve);
+  });
+  await writeDaemonState();
+  log(`Listening on ${BRIDGE_URL}`);
+}
+
+let shuttingDown = false;
+async function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  await cleanup().catch((error) => log(`Cleanup failed: ${error.message}`));
+  process.exit();
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+process.on("SIGHUP", shutdown);
+
+main().catch(async (error) => {
+  log(error.message);
+  await lockHandle?.close().catch(() => {});
+  process.exit(1);
+});

package/src/mcp-server.mjs

@@ -0,0 +1,214 @@
+import { mkdir, readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+import { GUIDANCE_PATH, PACKAGE_NAME, PACKAGE_VERSION, TEST_EDITOR_URL } from "./config.mjs";
+
+const id = z.string().min(1).max(160);
+const optionalId = id.optional();
+const color = z.string().regex(/^#?[0-9a-f]{3}(?:[0-9a-f]{3})?$/i, "Use a 3- or 6-digit hex color.");
+const unit = z.number().min(-0.5).max(1.5);
+const positiveUnit = z.number().min(0.01).max(2.4);
+const expectedRevision = z.number().int().min(0).optional().describe("Optional optimistic-concurrency guard from inspect_editor.");
+const targetProject = { projectId: optionalId, expectedRevision };
+const targetSlide = { projectId: optionalId, slideId: optionalId, expectedRevision };
+const textFields = {
+  text: z.string().max(4000).optional(), x: unit.optional(), y: unit.optional(), width: positiveUnit.optional(), height: positiveUnit.optional(),
+  size: z.number().min(20).max(180).optional(), style: z.enum(["plain", "outline", "boxed"]).optional(),
+  outlineWidth: z.number().min(0).max(40).optional(), color: color.optional(), background: z.enum(["white", "black"]).optional(),
+  backgroundShape: z.enum(["lines", "full"]).optional(), align: z.enum(["left", "center", "right"]).optional(),
+  rotation: z.number().min(-720).max(720).optional(), z: z.number().optional(),
+};
+const imageFields = {
+  x: unit.optional(), y: unit.optional(), width: positiveUnit.optional(), height: positiveUnit.optional(),
+  rotation: z.number().min(-720).max(720).optional(), z: z.number().optional(),
+  cropX: z.number().min(0).max(0.95).optional(), cropY: z.number().min(0).max(0.95).optional(),
+  cropW: z.number().min(0.05).max(1).optional(), cropH: z.number().min(0.05).max(1).optional(),
+};
+
+const definitions = new Map();
+
+function textResult(value, summary = value) {
+  return { content: [{ type: "text", text: typeof summary === "string" ? summary : JSON.stringify(summary) }], structuredContent: value };
+}
+
+function compactMutation(value) {
+  const keys = ["projectId", "slideId", "revision", "createdSlideId", "createdTextId", "createdImageId", "assetId", "deletedProjectId", "deletedSlideId", "deletedLayerIds", "updatedTextIds", "updatedImageIds", "applied", "path", "bytes"];
+  return Object.fromEntries(keys.flatMap((key) => value?.[key] == null ? [] : [[key, value[key]]]));
+}
+
+function clientIdentity(context, server) {
+  return context?.mcpReq?.envelope?.clientInfo || server.server.getClientVersion?.() || null;
+}
+
+function absolutePath(value) {
+  return isAbsolute(value) ? value : resolve(process.cwd(), value);
+}
+
+async function pathExists(value) {
+  try { await stat(value); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+
+function operationLabel(toolName) {
+  return ({
+    create_project: "Creating a project…", update_project: "Updating the project…", delete_project: "Deleting a project…",
+    open_project: "Opening a project…", add_slide: "Adding a slide…", update_slide: "Updating a slide…",
+    duplicate_slide: "Duplicating a slide…", reorder_slides: "Reordering slides…", delete_slide: "Deleting a slide…",
+    add_text: "Adding text…", update_text: "Updating text…", import_asset: "Importing a local image…",
+    update_asset: "Updating an image asset…", delete_asset: "Deleting an image asset…", add_image: "Placing an image…",
+    update_image: "Updating an image…", delete_layers: "Deleting layers…", duplicate_layers: "Duplicating layers…",
+    reorder_layers: "Reordering layers…", undo: "Undoing the last edit…", redo: "Redoing the last edit…",
+    set_view: "Updating the editor view…", render_slide: "Rendering the slide…",
+  })[toolName] || "Editing in Slide Studio…";
+}
+
+async function browserOperation(companion, toolName, args) {
+  const operation = await prepareOperation(companion, toolName, args);
+  return companion.call("browser", { toolName, operation, label: operationLabel(toolName) });
+}
+
+async function prepareOperation(companion, toolName, args) {
+  const operation = { ...args };
+  if (operation.backgroundPath) {
+    const prepared = await companion.call("prepare_media", { path: absolutePath(operation.backgroundPath) });
+    operation.mediaId = prepared.mediaId;
+    delete operation.backgroundPath;
+  }
+  if (toolName === "import_asset") {
+    const prepared = await companion.call("prepare_media", { path: absolutePath(operation.path) });
+    operation.mediaId = prepared.mediaId;
+    delete operation.path;
+  }
+  const type = ({
+    create_project: "project.create", open_project: "project.open", update_project: "project.update", delete_project: "project.delete",
+    add_slide: "slide.add", update_slide: "slide.update", duplicate_slide: "slide.duplicate", reorder_slides: "slide.reorder", delete_slide: "slide.delete",
+    add_text: "text.add", update_text: "text.update", import_asset: "asset.import", update_asset: "asset.update", delete_asset: "asset.delete",
+    add_image: "image.add", update_image: "image.update", delete_layers: "layer.delete", duplicate_layers: "layer.duplicate", reorder_layers: "layer.reorder",
+    undo: "history.undo", redo: "history.redo", set_view: "view.update", render_slide: "slide.render", inspect_editor: "editor.inspect",
+  })[toolName];
+  if (!type) throw new Error(`Unsupported operation tool: ${toolName}`);
+  return { type, ...operation };
+}
+
+export async function createSlideStudioMcpServer(companion) {
+  const guidance = await readFile(GUIDANCE_PATH, "utf8");
+  let guidanceRead = false;
+  let identifiedAs = null;
+  const server = new McpServer({ name: PACKAGE_NAME, version: PACKAGE_VERSION }, {
+    instructions: `Open ${TEST_EDITOR_URL}, click Connect AI, then call get_design_guidance before editing. Mutations are intentionally blocked until the design guidance is read. Use render_slide to inspect actual pixels.`,
+    capabilities: { tools: {}, resources: {} },
+  });
+
+  async function identify(context) {
+    const info = clientIdentity(context, server);
+    const signature = info ? `${info.name || "MCP agent"}@${info.version || "unknown"}` : null;
+    if (signature && signature !== identifiedAs) {
+      identifiedAs = signature;
+      await companion.identify(info.name, info.version);
+    }
+  }
+
+  function register(name, description, inputSchema, handler, annotations = {}) {
+    const guidanceExempt = new Set(["select_editor", "open_project", "set_view", "show_notification"]);
+    definitions.set(name, { inputSchema, handler, mutating: !annotations.readOnlyHint && !guidanceExempt.has(name) });
+    server.registerTool(name, { title: name.split("_").map((part) => part[0].toUpperCase() + part.slice(1)).join(" "), description, inputSchema, annotations }, async (args, context) => {
+      await identify(context);
+      if (definitions.get(name).mutating && !guidanceRead) throw new Error("Call get_design_guidance before changing slides. This one-time step prevents avoidable clipping and unattractive defaults.");
+      const value = await handler(args, context);
+      if (value?.__rawMcpResult) {
+        const { __rawMcpResult, ...result } = value;
+        return result;
+      }
+      return textResult(value, annotations.readOnlyHint ? value : compactMutation(value));
+    });
+  }
+
+  server.registerResource("slide-studio-design-guidance", "slide-studio://guidance/design", {
+    title: "Slide Studio design guidance", description: "Required visual-quality and text-box safety guidance.", mimeType: "text/markdown",
+  }, async (uri) => {
+    guidanceRead = true;
+    return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: guidance }] };
+  });
+
+  register("get_design_guidance", "Read the required compact design and clipping guidance. Call once before any mutation.", z.object({}).strict(), async () => {
+    guidanceRead = true;
+    return { __rawMcpResult: true, content: [{ type: "text", text: guidance }], structuredContent: { read: true } };
+  }, { readOnlyHint: true, idempotentHint: true });
+
+  register("list_editors", "List connected browser tabs and show which tab this MCP session targets.", z.object({}).strict(), () => companion.call("list_editors"), { readOnlyHint: true });
+  register("select_editor", "Select a connected browser tab for this MCP session.", z.object({ editorId: id }).strict(), ({ editorId }) => companion.call("select_editor", { editorId }), { idempotentHint: true });
+  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), { 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));
+  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), { 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));
+  register("delete_project", "Delete a project from browser storage.", z.object({ ...targetProject, projectId: id }).strict(), (args) => browserOperation(companion, "delete_project", args), { destructiveHint: true });
+
+  register("add_slide", "Add and open a slide using a solid color or local background image path.", z.object({ ...targetProject, name: z.string().max(160).optional(), index: z.number().int().min(0).optional(), backgroundColor: color.optional(), backgroundPath: z.string().min(1).optional() }).strict(), (args) => browserOperation(companion, "add_slide", args));
+  register("update_slide", "Rename a slide, replace its background, or change background pan/zoom. The browser opens this slide.", z.object({ ...targetSlide, name: z.string().max(160).optional(), backgroundColor: color.optional(), backgroundPath: z.string().min(1).optional(), imageScale: z.number().min(1).max(3).optional(), imageX: unit.optional(), imageY: unit.optional() }).strict(), (args) => browserOperation(companion, "update_slide", args));
+  register("duplicate_slide", "Duplicate a slide with all layers and open the copy.", z.object({ ...targetSlide, name: z.string().max(160).optional() }).strict(), (args) => browserOperation(companion, "duplicate_slide", args));
+  register("reorder_slides", "Set the complete slide order using every slide ID exactly once.", z.object({ ...targetProject, slideIds: z.array(id).min(1) }).strict(), (args) => browserOperation(companion, "reorder_slides", args));
+  register("delete_slide", "Delete one slide.", z.object({ ...targetSlide, slideId: id }).strict(), (args) => browserOperation(companion, "delete_slide", args), { destructiveHint: true });
+
+  register("add_text", "Add a text layer. Coordinates and dimensions are normalized to the 9:16 canvas; attractive defaults use generous bounds and per-line boxes.", z.object({ ...targetSlide, ...textFields, text: z.string().min(1).max(4000) }).strict(), (args) => browserOperation(companion, "add_text", args));
+  register("update_text", "Update one or more text layers, including content, geometry, color, style, alignment, rotation, and stacking.", z.object({ ...targetSlide, updates: z.array(z.object({ id, ...textFields }).strict()).min(1).max(100) }).strict(), (args) => browserOperation(companion, "update_text", args));
+
+  register("import_asset", "Import a local image file into the active project's reusable asset library. Image bytes stay local.", z.object({ ...targetSlide, path: z.string().min(1), name: z.string().max(160).optional() }).strict(), (args) => browserOperation(companion, "import_asset", args));
+  register("update_asset", "Rename a reusable image asset.", z.object({ ...targetProject, assetId: id, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "update_asset", args));
+  register("delete_asset", "Delete an asset and every placed instance that references it.", z.object({ ...targetProject, assetId: id }).strict(), (args) => browserOperation(companion, "delete_asset", args), { destructiveHint: true });
+  register("add_image", "Place an imported asset as an image layer and optionally set geometry, crop, rotation, and stacking.", z.object({ ...targetSlide, assetId: id, ...imageFields }).strict(), (args) => browserOperation(companion, "add_image", args));
+  register("update_image", "Update one or more placed image layers, including geometry, crop, rotation, and stacking.", z.object({ ...targetSlide, updates: z.array(z.object({ id, ...imageFields }).strict()).min(1).max(100) }).strict(), (args) => browserOperation(companion, "update_image", args));
+
+  register("delete_layers", "Delete text and/or image layers by ID.", z.object({ ...targetSlide, layerIds: z.array(id).min(1).max(200) }).strict(), (args) => browserOperation(companion, "delete_layers", args), { destructiveHint: true });
+  register("duplicate_layers", "Duplicate text and/or image layers with an optional normalized offset.", z.object({ ...targetSlide, layerIds: z.array(id).min(1).max(100), offsetX: z.number().min(-1).max(1).optional(), offsetY: z.number().min(-1).max(1).optional() }).strict(), (args) => browserOperation(companion, "duplicate_layers", args));
+  register("reorder_layers", "Set the complete back-to-front layer order using every layer ID exactly once.", z.object({ ...targetSlide, layerIds: z.array(id).min(1).max(300) }).strict(), (args) => browserOperation(companion, "reorder_layers", args));
+  register("undo", "Undo the latest project edit.", z.object(targetSlide).strict(), (args) => browserOperation(companion, "undo", args));
+  register("redo", "Redo the latest undone project edit.", z.object(targetSlide).strict(), (args) => browserOperation(companion, "redo", args));
+  register("set_view", "Open a project/slide and control editor-only canvas zoom or TikTok safe-area overlay.", z.object({ ...targetSlide, canvasZoom: z.number().min(0.2).max(3).optional(), showTikTokOverlay: z.boolean().optional() }).strict(), (args) => browserOperation(companion, "set_view", args), { idempotentHint: true });
+
+  register("render_slide", "Render and return the actual slide image for visual inspection. This does not persist the rendered file.", z.object({ ...targetSlide, width: z.number().int().min(180).max(1080).default(540), format: z.enum(["png", "jpeg"]).default("png"), quality: z.number().min(0.4).max(1).default(0.9) }).strict(), async (args) => {
+    const rendered = await browserOperation(companion, "render_slide", args);
+    return {
+      content: [{ type: "image", data: rendered.data, mimeType: rendered.mimeType }, { type: "text", text: JSON.stringify({ slideId: args.slideId || null, width: rendered.width, height: rendered.height, temporary: true }) }],
+      structuredContent: { slideId: args.slideId || null, width: rendered.width, height: rendered.height, mimeType: rendered.mimeType, temporary: true },
+      __rawMcpResult: true,
+    };
+  }, { readOnlyHint: true });
+
+  register("export_slide", "Render a full-resolution PNG and write it to a local path. Existing files are protected unless overwrite=true.", z.object({ ...targetSlide, outputPath: z.string().min(1), overwrite: z.boolean().default(false) }).strict(), async ({ outputPath, overwrite, ...target }) => {
+    const rendered = await browserOperation(companion, "render_slide", { ...target, width: 1080, format: "png", quality: 1 });
+    const path = absolutePath(outputPath);
+    await mkdir(dirname(path), { recursive: true });
+    return companion.call("write_export", { path, data: rendered.data, overwrite });
+  });
+
+  register("export_project", "Render every slide at full resolution into a local directory. Existing files are protected unless overwrite=true.", z.object({ ...targetProject, outputDirectory: z.string().min(1), overwrite: z.boolean().default(false) }).strict(), async ({ outputDirectory, overwrite, ...target }) => {
+    const inspected = await browserOperation(companion, "inspect_editor", { ...target, includeAllProjects: false });
+    if (!inspected.project?.slides?.length) throw new Error("The project has no slides to export.");
+    const directory = absolutePath(outputDirectory);
+    await mkdir(directory, { recursive: true });
+    const files = [];
+    for (const slide of inspected.project.slides) {
+      const rendered = await browserOperation(companion, "render_slide", { projectId: inspected.project.id, slideId: slide.id, width: 1080, format: "png", quality: 1 });
+      const path = join(directory, `${String(slide.index + 1).padStart(2, "0")}-${rendered.filename}`);
+      if (!overwrite && await pathExists(path)) throw new Error(`Export already exists: ${path}. Set overwrite=true only when intended.`);
+      files.push(await companion.call("write_export", { path, data: rendered.data, overwrite }));
+    }
+    return { projectId: inspected.project.id, outputDirectory: directory, fileCount: files.length, files };
+  });
+
+  const batchTools = [...definitions.entries()].filter(([, definition]) => definition.mutating).map(([name]) => name).filter((name) => !["export_slide", "export_project"].includes(name));
+  register("apply_operations", "Apply many ordered editing operations in one compact tool call. Each edit still appears live in the browser.", z.object({ operations: z.array(z.object({ tool: z.enum(batchTools), arguments: z.record(z.string(), z.unknown()).default({}) }).strict()).min(1).max(100) }).strict(), async ({ operations }) => {
+    const items = [];
+    for (const item of operations) {
+      const definition = definitions.get(item.tool);
+      if (!definition?.mutating) throw new Error(`Tool cannot be batched: ${item.tool}`);
+      const args = definition.inputSchema.parse(item.arguments);
+      items.push({ operation: await prepareOperation(companion, item.tool, args), label: operationLabel(item.tool) });
+    }
+    return companion.call("batch", { items });
+  });
+
+  return server;
+}

package/src/setup.mjs

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process";
+import { cp, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { PACKAGE_NAME, PACKAGE_ROOT, PACKAGE_VERSION, TEST_EDITOR_URL } from "./config.mjs";
+
+const supported = ["claude", "codex", "hermes", "opencode", "openclaw"];
+
+function commandExists(command) {
+  return spawnSync(command, ["--version"], { stdio: "ignore" }).error?.code !== "ENOENT";
+}
+
+function commandVersion(command) {
+  const result = spawnSync(command, ["--version"], { encoding: "utf8" });
+  return `${result.stdout || ""}${result.stderr || ""}`.match(/\d+\.\d+(?:\.\d+)?/)?.[0] || null;
+}
+
+function shellCommand(client, specifier) {
+  if (client === "claude") return ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "slide-studio", "--", "npx", "-y", specifier, "serve"];
+  if (client === "codex") return ["codex", "mcp", "add", "slide-studio", "--", "npx", "-y", specifier, "serve"];
+  if (client === "hermes") return ["hermes", "mcp", "add", "slide-studio", "--command", "npx", "--args", "-y", specifier, "serve"];
+  if (client === "openclaw") return ["openclaw", "mcp", "add", "slide-studio", "--command", "npx", "--arg", "-y", "--arg", specifier, "--arg", "serve"];
+  return null;
+}
+
+function quote(value) {
+  return /^[A-Za-z0-9_@./:-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function openCodeSnippet(specifier, version = commandVersion("opencode")) {
+  const server = { type: "local", command: ["npx", "-y", specifier, "serve"] };
+  return JSON.stringify(Number(version?.split(".")[0]) >= 2
+    ? { mcp: { servers: { "slide-studio": server } } }
+    : { mcp: { "slide-studio": { ...server, enabled: true } } }, null, 2);
+}
+
+async function installSkill() {
+  const source = join(PACKAGE_ROOT, "skill", "slide-studio");
+  const targets = [
+    join(homedir(), ".agents", "skills", "slide-studio"),
+    join(homedir(), ".hermes", "skills", "slide-studio"),
+  ];
+  for (const target of targets) {
+    await mkdir(target, { recursive: true });
+    await cp(source, target, { recursive: true, force: true });
+  }
+  return targets;
+}
+
+export async function runSetup(arguments_) {
+  const flags = new Set(arguments_);
+  const clientArgument = arguments_.find((value) => value.startsWith("--client="))?.slice("--client=".length);
+  const requested = clientArgument ? clientArgument.split(",").map((value) => value.trim().toLowerCase()) : supported.filter(commandExists);
+  const clients = [...new Set(requested)].filter((client) => supported.includes(client));
+  const specifier = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
+  const dryRun = flags.has("--dry-run");
+  const assumeYes = flags.has("--yes") || flags.has("-y");
+  if (!clients.length) throw new Error("No supported agent CLI was detected. Use --client=claude,codex,hermes,opencode,openclaw or copy the generic stdio config below.");
+
+  process.stdout.write(`Slide Studio MCP ${PACKAGE_VERSION}\nDetected: ${clients.join(", ")}\nEditor: ${TEST_EDITOR_URL}\n\n`);
+  for (const client of clients) {
+    const command = shellCommand(client, specifier);
+    if (command) process.stdout.write(`${client}: ${command.map(quote).join(" ")}\n`);
+    else process.stdout.write(`opencode config:\n${openCodeSnippet(specifier)}\n`);
+  }
+  process.stdout.write(`\nGeneric stdio: npx -y ${specifier} serve\n`);
+  if (dryRun) return { clients, dryRun: true };
+
+  let approved = assumeYes;
+  if (!approved && process.stdin.isTTY) {
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await prompt.question("\nAdd Slide Studio to the detected agent configs and install its skill? [y/N] ");
+    prompt.close();
+    approved = /^y(?:es)?$/i.test(answer.trim());
+  }
+  if (!approved) {
+    process.stdout.write("\nNo configuration changed. Re-run with --yes when ready.\n");
+    return { clients, installed: false };
+  }
+
+  const configured = [];
+  for (const client of clients) {
+    const command = shellCommand(client, specifier);
+    if (!command) continue;
+    const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+    if (result.status === 0) configured.push(client);
+    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`);
+  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

@@ -0,0 +1,23 @@
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { createCompanion } from "./companion.mjs";
+import { createSlideStudioMcpServer } from "./mcp-server.mjs";
+
+export async function serveMcp() {
+  const companion = await createCompanion();
+  const handle = serveStdio(() => createSlideStudioMcpServer(companion), {
+    legacy: "serve",
+    onerror: (error) => process.stderr.write(`[slides-studio-mcp] ${error.message}\n`),
+  });
+  let closing = false;
+  const close = async () => {
+    if (closing) return;
+    closing = true;
+    await handle.close().catch(() => {});
+    await companion.close();
+  };
+  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());
+  return { handle, companion, close };
+}