@writepanda/mcp 1.180.0 → 1.183.0

package/bin/appConnection.mjs

@@ -0,0 +1,201 @@
+// How the MCP server finds and reaches the running PandaStudio app.
+//
+// Two kinds of caller spawn this server:
+//
+//   • External agents (Claude Desktop, Claude Code, Codex, Cursor…). The app
+//     may not be running, so a call reads the token/port files the app writes
+//     and, when nothing answers, launches the app and waits for it.
+//
+//   • The app's own chat panel (PANDASTUDIO_CALLER=in-app). The app is running
+//     by definition: it spawned us, and it hands us its live port and token in
+//     the environment. Launching "the app" from here is always wrong, and
+//     waiting 60-90 s for it hid every real failure behind the client's
+//     generic "Request timed out". So in-app calls never launch anything and
+//     fail within seconds with the actual reason, prefixed with
+//     IN_APP_UNAVAILABLE so the app can show it (and a Retry) in the chat.
+//
+// Kept free of MCP-sdk imports so the pure parts are unit-testable.
+
+import { readFile } from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+
+/** Prefix of every in-app "can't reach PandaStudio" tool error. The app's
+ *  agent runner matches it (electron/agent/toolsUnavailable.ts). */
+export const IN_APP_UNAVAILABLE = "PANDASTUDIO_TOOLS_UNAVAILABLE";
+
+export function isInAppCaller(env = process.env) {
+	return env.PANDASTUDIO_CALLER === "in-app";
+}
+
+export function configDir(env = process.env, platform = process.platform) {
+	if (env.PANDASTUDIO_CONFIG_DIR) return env.PANDASTUDIO_CONFIG_DIR;
+	if (platform === "win32") {
+		const appData = env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+		return path.join(appData, "pandastudio");
+	}
+	return path.join(os.homedir(), ".config", "pandastudio");
+}
+
+/** A text file's value without whitespace or a UTF-8 byte-order mark (an
+ *  editor or a sync tool on Windows can add one, and Number() of
+ *  "<BOM>7878" is NaN). */
+export function cleanFileValue(raw) {
+	const s = String(raw);
+	return (s.charCodeAt(0) === 0xfeff ? s.slice(1) : s).trim();
+}
+
+/** Credentials the app passed in the environment (in-app spawns only). */
+export function envCredentials(env = process.env) {
+	const port = Number(env.PANDASTUDIO_AUTOMATION_PORT);
+	const token = env.PANDASTUDIO_AUTOMATION_TOKEN;
+	if (!Number.isInteger(port) || port <= 0 || typeof token !== "string" || !token) return null;
+	return { port, token, source: "env" };
+}
+
+/** Credentials from the token/port files. Errors name the file and the cause. */
+export async function fileCredentials(dir = configDir()) {
+	const portFile = path.join(dir, "port");
+	const tokenFile = path.join(dir, "token");
+	let portRaw;
+	let tokenRaw;
+	try {
+		portRaw = await readFile(portFile, "utf-8");
+		tokenRaw = await readFile(tokenFile, "utf-8");
+	} catch (err) {
+		const file = portRaw === undefined ? portFile : tokenFile;
+		throw new Error(`can't read ${file} (${err?.code ?? err?.message ?? err})`);
+	}
+	const port = Number(cleanFileValue(portRaw));
+	const token = cleanFileValue(tokenRaw);
+	if (!Number.isInteger(port) || port <= 0) {
+		throw new Error(`invalid port in ${portFile}: ${JSON.stringify(portRaw.slice(0, 20))}`);
+	}
+	if (!token) throw new Error(`empty token in ${tokenFile}`);
+	return { port, token, source: "files" };
+}
+
+/**
+ * One health probe of the automation server:
+ *   up   — it answered 200
+ *   busy — connected (or still connecting) but no answer within `timeoutMs`:
+ *          the app's main process is stalled
+ *   down — refused / reset / any other socket error: nothing is listening
+ * `detail` says what happened, for error messages.
+ */
+export function probeHealth(port, timeoutMs = 1500) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const done = (state, detail) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			req.destroy();
+			resolve({ state, detail });
+		};
+		const req = http.get({ host: "127.0.0.1", port, path: "/v1/health", agent: false }, (res) => {
+			res.resume();
+			if (res.statusCode === 200) done("up", "HTTP 200");
+			else done("down", `HTTP ${res.statusCode} from /v1/health`);
+		});
+		req.on("error", (err) => done("down", err?.code ?? err?.message ?? String(err)));
+		const timer = setTimeout(() => done("busy", `no answer within ${timeoutMs} ms`), timeoutMs);
+	});
+}
+
+/**
+ * Wait for the automation server, tolerating a stalled main process for up to
+ * `busyWaitMs`. Returns the last probe ({state:"up"} on success).
+ */
+export async function waitForHealth(
+	port,
+	{ probeMs = 1500, busyWaitMs = 30_000, onBusy, probe = probeHealth } = {},
+) {
+	const deadline = Date.now() + busyWaitMs;
+	let warned = false;
+	for (;;) {
+		const r = await probe(port, probeMs);
+		if (r.state === "up" || r.state === "down" || Date.now() >= deadline) return r;
+		if (!warned && onBusy) onBusy();
+		warned = true;
+		probeMs = Math.min(probeMs * 2, 5000);
+	}
+}
+
+function unavailable(reason) {
+	const err = new Error(`${IN_APP_UNAVAILABLE}: ${reason}`);
+	err.inAppUnavailable = true;
+	return err;
+}
+
+/**
+ * Resolve working credentials for an in-app call, or throw an
+ * IN_APP_UNAVAILABLE error with the reason. Never launches anything.
+ *
+ * Order: the credentials the app handed us (env), then the files (the app
+ * restarted its automation server on another port since it spawned us). The
+ * whole thing stays well inside the MCP client's 60 s request timeout.
+ */
+export async function connectInApp({
+	env = process.env,
+	dir = configDir(env),
+	probeMs = 1500,
+	busyWaitMs = 20_000,
+	probe = probeHealth,
+	readFiles = fileCredentials,
+} = {}) {
+	const attempts = [];
+	const candidates = [];
+	const fromEnv = envCredentials(env);
+	if (fromEnv) candidates.push(fromEnv);
+	let fileError = null;
+	try {
+		const fromFiles = await readFiles(dir);
+		if (!fromEnv || fromFiles.port !== fromEnv.port || fromFiles.token !== fromEnv.token) {
+			candidates.push(fromFiles);
+		}
+	} catch (err) {
+		fileError = err?.message ?? String(err);
+	}
+	if (candidates.length === 0) {
+		throw unavailable(
+			`PandaStudio didn't pass its automation address to the tools and ${fileError ?? "the token/port files are missing"}.`,
+		);
+	}
+	for (const c of candidates) {
+		const r = await waitForHealth(c.port, { probeMs, busyWaitMs, probe });
+		if (r.state === "up") return c;
+		attempts.push(
+			r.state === "busy"
+				? `127.0.0.1:${c.port} accepted the connection but didn't answer for ${Math.round(busyWaitMs / 1000)} s (the app is busy or stuck)`
+				: `127.0.0.1:${c.port} (from ${c.source === "env" ? "the app" : dir}) is unreachable: ${r.detail}`,
+		);
+	}
+	throw unavailable(`PandaStudio's automation server didn't answer. ${attempts.join("; ")}.`);
+}
+
+/**
+ * Environment for LAUNCHING the desktop app. This server runs as Electron in
+ * node mode (ELECTRON_RUN_AS_NODE=1), and a child inherits that: spawning
+ * PandaStudio.exe / PandaStudio.app with it set starts a bare Node REPL that
+ * exits at once instead of the app, so an agent's "launch it and wait" always
+ * timed out. Drop it, and everything that only means something to this process.
+ */
+export function appLaunchEnv(env = process.env) {
+	const out = {};
+	for (const [k, v] of Object.entries(env)) {
+		const upper = k.toUpperCase();
+		if (
+			upper === "ELECTRON_RUN_AS_NODE" ||
+			upper === "ELECTRON_NO_ATTACH_CONSOLE" ||
+			upper === "PANDASTUDIO_CALLER" ||
+			upper === "PANDASTUDIO_AUTOMATION_PORT" ||
+			upper === "PANDASTUDIO_AUTOMATION_TOKEN"
+		) {
+			continue;
+		}
+		out[k] = v;
+	}
+	return out;
+}

package/bin/server.mjs

@@ -29,7 +29,6 @@
 
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import fs from "node:fs/promises";
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
@@ -37,78 +36,26 @@ import process from "node:process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import {
+	appLaunchEnv,
+	cleanFileValue,
+	configDir,
+	connectInApp,
+	fileCredentials,
+	IN_APP_UNAVAILABLE,
+	isInAppCaller,
+	probeHealth,
+	waitForHealth,
+} from "./appConnection.mjs";
 
 // ── Credentials + transport ───────────────────────────────────────────
+//
+// Finding and reaching the app lives in appConnection.mjs (unit-tested).
 
-function configDir() {
-	if (process.env.PANDASTUDIO_CONFIG_DIR) return process.env.PANDASTUDIO_CONFIG_DIR;
-	if (process.platform === "win32") {
-		const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
-		return path.join(appData, "pandastudio");
-	}
-	return path.join(os.homedir(), ".config", "pandastudio");
-}
-
-const TOKEN_FILE = path.join(configDir(), "token");
-const PORT_FILE = path.join(configDir(), "port");
+const IN_APP = isInAppCaller();
 
 async function readCredentials() {
-	const port = Number((await fs.readFile(PORT_FILE, "utf-8")).trim());
-	const token = (await fs.readFile(TOKEN_FILE, "utf-8")).trim();
-	if (!Number.isInteger(port) || port <= 0) throw new Error(`invalid port in ${PORT_FILE}`);
-	if (!token) throw new Error(`empty token in ${TOKEN_FILE}`);
-	return { port, token };
-}
-
-async function probeHealth(port, timeoutMs = 1500) {
-	const ctrl = new AbortController();
-	const t = setTimeout(() => ctrl.abort(), timeoutMs);
-	try {
-		const res = await fetch(`http://127.0.0.1:${port}/v1/health`, { signal: ctrl.signal });
-		clearTimeout(t);
-		return res.ok;
-	} catch {
-		clearTimeout(t);
-		return false;
-	}
-}
-
-/**
- * One health probe: "up" (answered), "busy" (the socket is open but no answer
- * within `timeoutMs`: the app's main process is stalled, e.g. creating an
- * editor window on a loaded machine) or "down" (connection refused / reset:
- * not running).
- */
-async function probeHealthState(port, timeoutMs) {
-	const ctrl = new AbortController();
-	const t = setTimeout(() => ctrl.abort(), timeoutMs);
-	try {
-		const res = await fetch(`http://127.0.0.1:${port}/v1/health`, { signal: ctrl.signal });
-		return res.ok ? "up" : "down";
-	} catch {
-		return ctrl.signal.aborted ? "busy" : "down";
-	} finally {
-		clearTimeout(t);
-	}
-}
-
-/**
- * Is the app reachable? A busy app is waited for (up to `busyWaitMs`) rather
- * than reported as not running: a single 1.5 s probe used to fail whenever the
- * main process stalled for longer (window creation takes ~0.4 s idle and
- * several seconds under load), so agents saw "not reachable" at random.
- */
-async function appReachable(port, { probeMs = 1500, busyWaitMs = 30_000, onBusy } = {}) {
-	const deadline = Date.now() + busyWaitMs;
-	let warned = false;
-	for (;;) {
-		const s = await probeHealthState(port, probeMs);
-		if (s === "up") return true;
-		if (s === "down" || Date.now() >= deadline) return false;
-		if (!warned && onBusy) onBusy();
-		warned = true;
-		probeMs = Math.min(probeMs * 2, 5000);
-	}
+	return fileCredentials(configDir());
 }
 
 function findInstalledApp() {
@@ -116,7 +63,7 @@ function findInstalledApp() {
 	// The app records its own location (it can live anywhere on Windows,
 	// and in ~/Applications on a Mac).
 	try {
-		const recorded = readFileSync(path.join(configDir(), "app-path"), "utf-8").trim();
+		const recorded = cleanFileValue(readFileSync(path.join(configDir(), "app-path"), "utf-8"));
 		if (recorded && existsSync(recorded)) return recorded;
 	} catch {
 		/* older app, or never launched */
@@ -159,14 +106,16 @@ async function autoLaunchAndWait(timeoutSec = 60) {
 		const c = await readCredentials();
 		// Busy (stalled main process) is not "not running": wait for it
 		// instead of launching a second copy.
-		if (await appReachable(c.port)) return c;
+		if ((await waitForHealth(c.port)).state === "up") return c;
 	} catch {
 		/* not running */
 	}
 
 	const bin = findInstalledApp();
 	try {
-		const child = spawn(bin, [], { detached: true, stdio: "ignore", env: process.env });
+		// appLaunchEnv drops ELECTRON_RUN_AS_NODE: inherited, it made the
+		// "launch" start a Node REPL that exits instead of PandaStudio.
+		const child = spawn(bin, [], { detached: true, stdio: "ignore", env: appLaunchEnv() });
 		child.unref();
 	} catch (err) {
 		throw new Error(`failed to launch PandaStudio (${bin}): ${err?.message ?? err}`);
@@ -176,7 +125,7 @@ async function autoLaunchAndWait(timeoutSec = 60) {
 	while (Date.now() < deadline) {
 		try {
 			const c = await readCredentials();
-			if (await probeHealth(c.port, 2000)) return c;
+			if ((await probeHealth(c.port, 2000)).state === "up") return c;
 		} catch {
 			/* still booting */
 		}
@@ -211,18 +160,50 @@ function httpRequestLocal(port, pathSuffix, { method = "GET", headers = {}, body
 	});
 }
 
-async function callPandastudio(command, args = {}) {
-	const creds = await autoLaunchAndWait();
-	const res = await httpRequestLocal(creds.port, "/v1/call", {
+async function postCall(creds, command, args) {
+	return httpRequestLocal(creds.port, "/v1/call", {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
 			Authorization: `Bearer ${creds.token}`,
 			// Set by the app when it runs this server for its own chat panel.
-			...(process.env.PANDASTUDIO_CALLER === "in-app" ? { "X-PandaStudio-Caller": "in-app" } : {}),
+			...(IN_APP ? { "X-PandaStudio-Caller": "in-app" } : {}),
 		},
 		body: JSON.stringify({ command, args }),
 	});
+}
+
+async function callPandastudio(command, args = {}) {
+	// In-app: the app is running (it spawned us). Never launch it, and fail in
+	// seconds with the real reason instead of outliving the client's timeout.
+	let creds = IN_APP ? await connectInApp() : await autoLaunchAndWait();
+	let res;
+	try {
+		res = await postCall(creds, command, args);
+	} catch (err) {
+		if (!IN_APP) throw err;
+		throw new Error(
+			`${IN_APP_UNAVAILABLE}: the call to 127.0.0.1:${creds.port} failed (${err?.code ?? err?.message ?? err}).`,
+		);
+	}
+	if (IN_APP && res.status === 401) {
+		// The app restarted its automation server (new token) after it
+		// spawned us. The files hold the current one.
+		try {
+			const fresh = await fileCredentials(configDir());
+			if (fresh.token !== creds.token || fresh.port !== creds.port) {
+				creds = fresh;
+				res = await postCall(creds, command, args);
+			}
+		} catch {
+			/* reported below */
+		}
+		if (res.status === 401) {
+			throw new Error(
+				`${IN_APP_UNAVAILABLE}: PandaStudio rejected the tools' access token (its automation server restarted).`,
+			);
+		}
+	}
 	const text = res.text;
 	let body;
 	try {
@@ -565,7 +546,7 @@ const ASSETS_PROP = {
 };
 const ANCHOR_PROP = {
 	type: "number",
-	description: "SOURCE ms (a transcript word's startMs) to pin to, surviving cuts.",
+	description: "SOURCE ms of a transcript word; survives cuts.",
 };
 const ANCHOR_END_PROP = { type: "number", description: "Anchor end, SOURCE ms." };
 const KEYFRAME_TARGET_DOC =
@@ -1347,6 +1328,11 @@ const TOOLS = [
 				slots: { type: "object", description: "Templates: changed slots only." },
 				background: { type: "string", enum: ["solid", "transparent", "glass"] },
 				html: { type: "string", description: "HTML graphics: full replacement." },
+				durationMs: { type: "number", description: "text-behind length." },
+				templateId: {
+					type: "string",
+					description: "Switch template (e.g. a retired one's replacement); slots map across.",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["overlayId"],
@@ -1545,7 +1531,7 @@ const TOOLS = [
 	{
 		name: "project_add_lower_third",
 		description:
-			"Render an lt-* nameplate and place it at atMs in one call (designs: motion_list category lower-third). ASYNC: { jobId }; job_wait gives result.overlayId once placed.",
+			"Render a nameplate and place it at atMs in one call, laid out for the project's aspect. ASYNC: { jobId }; job_wait gives result.overlayId once placed.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1553,12 +1539,16 @@ const TOOLS = [
 				path: { type: "string" },
 				name: { type: "string" },
 				title: { type: "string", description: "Second line (role / handle)." },
-				templateId: { type: "string", description: "Default lt-vox-marker." },
+				templateId: {
+					type: "string",
+					description:
+						"lt-vox-marker (default, bold marker) | lt-glass-card | lt-minimal-line | lt-bold-bar | lt-logo-name (slots.logo) | lt-duo (slots.name2/title2).",
+				},
 				atMs: { type: "number" },
 				aspectRatio: {
 					type: "string",
 					enum: ["16:9", "9:16", "1:1"],
-					description: "Match the project.",
+					description: "Default: the project's aspect.",
 				},
 				slots: { type: "object", description: "Extra slot values (motion_list)." },
 				soundUrl: { type: "string", description: 'Default bundled:sound/mouse-click; "none".' },
@@ -1575,6 +1565,29 @@ const TOOLS = [
 		},
 		command: "project.add-lower-third",
 	},
+	{
+		name: "project_add_title_behind",
+		description:
+			"1-3 huge words at head height BEHIND the presenter. ASYNC: job_wait gives regionId, face.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				text: { type: "string" },
+				atMs: { type: "number" },
+				style: { type: "string", enum: ["3d", "bold", "serif"] },
+				durationMs: { type: "number", description: "Default 3000." },
+				accentColor: { type: "string" },
+				position: { type: "string", enum: ["auto", "top", "center"] },
+				animation: { type: "string", enum: ["in-out", "in", "none"] },
+				behind: { type: "boolean", description: "false: in front (no face)." },
+				anchorSourceMs: ANCHOR_PROP,
+			},
+			required: ["text", "atMs"],
+		},
+		command: "project.add-title-behind",
+	},
 
 	// ── compose: visual regions ─────────────────────────────────────
 	{
@@ -2062,7 +2075,7 @@ const TOOLS = [
 	{
 		name: "project_render_frame",
 		description:
-			"Render the composited frame at an edited time to a PNG (matches export). Returns { path, timeMs, maskRect (video rect in 0-1 image fractions, for mapping boxes to spotlight coords), warnings? } (tell the user warnings).",
+			"Render the composited frame at an edited time to a PNG (matches export). Returns { path, timeMs (snapped to the export's frame grid, fps), maskRect (video rect in 0-1 image fractions, for mapping boxes to spotlight coords), warnings? } (tell the user warnings).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2792,6 +2805,10 @@ const TOOLS = [
 					type: ["boolean", "string"],
 					description: "streaming / true (-14 LUFS, default), podcast (-16), off / false.",
 				},
+				frameRate: {
+					type: ["number", "string"],
+					description: "auto (default) | 30 | 60 | source (fastest source).",
+				},
 				expectedRevision: { type: "number" },
 			},
 		},
@@ -2893,6 +2910,47 @@ const TOOLS = [
 		},
 		command: "project.add-audio",
 	},
+	{
+		name: "project_add_sound_cues",
+		description:
+			"Place many timed SFX in one write (one undo). Each cue = an audio overlay. Same group again REPLACES its cues ([] clears). Returns overlayIds + warnings.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				cues: {
+					type: "array",
+					maxItems: 500,
+					items: {
+						type: "object",
+						properties: {
+							sound: {
+								type: "string",
+								description: "Bundled id or absolute path.",
+							},
+							atMs: { type: "number", description: "Edited-timeline ms." },
+							volume: { type: "number", description: "0-2." },
+							durationMs: { type: "number" },
+							sourceStartMs: { type: "number" },
+							fadeInMs: { type: "number" },
+							fadeOutMs: { type: "number" },
+							anchorSourceMs: {
+								type: "number",
+								description: "SOURCE ms word anchor; omit for graphics.",
+							},
+						},
+						required: ["sound", "atMs"],
+					},
+				},
+				group: { type: "string", description: 'e.g. "sfx".' },
+				volume: { type: "number", description: "Cue default, 0.8." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["cues"],
+		},
+		command: "project.add-sound-cues",
+	},
 	{
 		name: "project_remove_audio",
 		description:
@@ -3654,6 +3712,28 @@ const TOOLS = [
 		},
 		command: "media.import",
 	},
+	{
+		name: "media_download_url",
+		description:
+			"Download a video or its audio from a page link (YouTube, Vimeo...). Only content the user has rights to. ASYNC: job_wait gives { path, title, durationMs }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				url: { type: "string" },
+				format: { type: "string", enum: ["video", "audio"] },
+				maxHeight: { type: "number", description: "Default 1080." },
+				startMs: { type: "number" },
+				endMs: { type: "number" },
+				maxMinutes: { type: "number", description: "Default 120." },
+				name: { type: "string" },
+				addToProject: { type: "string", description: "Project id." },
+				as: { type: "string", enum: ["clip", "overlay", "audio"] },
+				atMs: { type: "number" },
+			},
+			required: ["url"],
+		},
+		command: "media.download-url",
+	},
 	{
 		name: "media_generate_sound_effect",
 		description:
@@ -3802,8 +3882,22 @@ const TOOLS = [
 	{
 		name: "motion_list",
 		description:
-			"List motion-graphic templates (slots; render with motion_generate) and slot-less registryBlocks (edit htmlPath, render with motion_render_html).",
-		inputSchema: { type: "object", properties: {} },
+			"List motion-graphic templates (slots, family, tags; render with motion_generate) and slot-less registryBlocks (edit htmlPath, render with motion_render_html). Retired templates are hidden unless includeRetired.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				family: {
+					type: "string",
+					description:
+						"titles|text-behind|captions|callouts|lists-steps|stats-data|comparisons|product|panels|social-proof|social|intro-outro|end-cards|lower-thirds (comma-separated ok).",
+				},
+				tags: { type: "string", description: "Any of these tags, comma-separated." },
+				query: { type: "string", description: "Search, e.g. 'subscribe', 'bar chart'." },
+				aspect: { type: "string", enum: ["16:9", "9:16", "1:1"] },
+				includeRetired: { type: "boolean" },
+				includeBlocks: { type: "boolean", description: "Default true." },
+			},
+		},
 		command: "motion.list",
 	},
 	{
@@ -3949,12 +4043,14 @@ const TOOLS = [
 	{
 		name: "motion_screenshot",
 		description:
-			"Capture one PNG frame of an HTML composition, as motion_render_html would. Returns { outputPath, previewPath } (inspect previewPath).",
+			"Capture one PNG frame of an HTML composition (or a template with slots), as motion_render_html / motion_generate would. Returns { outputPath, previewPath } (inspect previewPath).",
 		inputSchema: {
 			type: "object",
 			properties: {
-				html: { type: "string", description: "Or htmlPath." },
+				html: { type: "string", description: "Or htmlPath, or templateId." },
 				htmlPath: { type: "string" },
+				templateId: { type: "string", description: "Template id; fill with slots." },
+				slots: { type: "object" },
 				aspectRatio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
 				width: { type: "number" },
 				height: { type: "number" },
@@ -4005,8 +4101,23 @@ const TOOLS = [
 	},
 	{
 		name: "asset_list_sounds",
-		description: "List bundled sound effects (id, name, category, path).",
-		inputSchema: { type: "object", properties: {} },
+		description:
+			"List bundled SFX (~190: id, category, tags, durationMs, variantGroup, path). Filter; summary=true gives categories + groups only.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				category: {
+					type: "string",
+					description:
+						"ui|notification|motion|digital|impact|typing|outcome|ambience, comma-separated.",
+				},
+				tag: { type: "string", description: 'e.g. "click,soft" (all match).' },
+				mood: { type: "string" },
+				group: { type: "string", description: "Variant group." },
+				query: { type: "string" },
+				summary: { type: "boolean" },
+			},
+		},
 		command: "asset.list-sounds",
 	},
 	{
@@ -4105,6 +4216,10 @@ const TOOLS = [
 					type: ["boolean", "string"],
 					description: "streaming / podcast / off; omit = project setting.",
 				},
+				frameRate: {
+					type: ["number", "string"],
+					description: "30 | 60 | source | auto; omit = project setting.",
+				},
 			},
 		},
 		command: "export.start",
@@ -4478,7 +4593,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 	};
 });
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 	const tool = TOOLS.find((t) => t.name === request.params.name);
 	if (!tool) {
 		return {
@@ -4509,7 +4624,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 	}
 
 	try {
-		const result = await callPandastudio(command, dispatchArgs);
+		const result = await withProgressHeartbeat(request, extra, () =>
+			callPandastudio(command, dispatchArgs),
+		);
 		// Format the response for the MCP client. Default is a text
 		// block carrying the JSON result. For `motion.screenshot` and
 		// `motion.verify-frames` we ALSO inline the downscaled preview
@@ -4559,6 +4676,36 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 	}
 });
 
+/**
+ * Keep a long call alive on the client side. MCP clients time a request out
+ * after 60 s unless progress arrives (opencode, the in-app agent's runtime,
+ * sends every tool call with a progress token and resets its timer on each
+ * notification). job.wait, renders and presenter takes run for minutes, so
+ * while the app works we report progress every 15 s. Clients that sent no
+ * progress token get nothing.
+ */
+const HEARTBEAT_MS = Number(process.env.PANDASTUDIO_MCP_PROGRESS_MS) || 15_000;
+
+async function withProgressHeartbeat(request, extra, run) {
+	const progressToken = request.params?._meta?.progressToken;
+	if (progressToken === undefined || typeof extra?.sendNotification !== "function") return run();
+	let beats = 0;
+	const timer = setInterval(() => {
+		beats += 1;
+		extra
+			.sendNotification({
+				method: "notifications/progress",
+				params: { progressToken, progress: beats, message: "PandaStudio is working" },
+			})
+			.catch(() => undefined);
+	}, HEARTBEAT_MS);
+	try {
+		return await run();
+	} finally {
+		clearInterval(timer);
+	}
+}
+
 /** Decide which (if any) preview PNGs to inline as image content
  *  blocks for a given tool result. Only motion.screenshot (one
  *  preview) and motion.verify-frames (one per frame) qualify today.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@writepanda/mcp",
-	"version": "1.180.0",
+	"version": "1.183.0",
 	"description": "Model Context Protocol server for PandaStudio. Exposes the desktop video editor's automation surface to Cursor, Continue, Cline, Claude Desktop, and any MCP-compliant client.",
 	"keywords": [
 		"pandastudio",