@writepanda/mcp 1.222.0 → 1.225.0

package/README.md

@@ -71,6 +71,7 @@ Restart the client afterwards. The server auto-launches PandaStudio if it isn't
 | `caption_*` | 3 | Toggle, templates, per-style overrides |
 | `media_*` | 3 | Generate images, music, narration |
 | `preview_*` / `job_*` / `agent_*` / `audio_*` / `timeline_*` | 14 | Live preview overlay, async job polling, agent sessions, audio cleanup, time-base conversion |
+| `review_*` | 5 | The pins, drawings and picked graphics the user marked on the preview: list them (with frame crops), resolve them when done, add / update / delete |
 
 Plus `pandastudio_call` — a raw `verb.noun` escape hatch for anything not yet a first-class tool.
 

package/bin/appConnection.mjs

@@ -16,7 +16,7 @@
 //
 // Kept free of MCP-sdk imports so the pure parts are unit-testable.
 
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
@@ -239,3 +239,171 @@ export function appLaunchEnv(env = process.env) {
 	}
 	return out;
 }
+
+// ── Launching the app (external agents only) ─────────────────────────────
+//
+// Jared (Windows, 2.1.15): "PandaStudio seemed to restart with every
+// request". Every call that didn't find a healthy server at the port file's
+// address launched PandaStudio.exe again: while the app was busy for longer
+// than the busy wait, while it was still booting, and after another process
+// had replaced or deleted the token/port files. Now a launch happens only
+// when nothing says PandaStudio is running, and at most once per
+// LAUNCH_DEBOUNCE_MS across every MCP server / CLI process on the machine.
+
+/** Default automation port (Settings → Automation). */
+export const DEFAULT_AUTOMATION_PORT = 7878;
+/** An instance.json heartbeat older than this is a dead (or hung) app. */
+export const INSTANCE_STALE_MS = 20_000;
+/** Don't launch again within this long of the last launch, from anywhere. */
+export const LAUNCH_DEBOUNCE_MS = 90_000;
+
+/** Is a process with this pid running? (EPERM: it exists, owned by someone else.) */
+export function pidAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err?.code === "EPERM";
+	}
+}
+
+/** The running app's instance.json (pid + heartbeat), or null. */
+export async function readInstanceRecord(dir = configDir()) {
+	try {
+		const v = JSON.parse(cleanFileValue(await readFile(path.join(dir, "instance.json"), "utf-8")));
+		return v && typeof v === "object" ? v : null;
+	} catch {
+		return null;
+	}
+}
+
+/** A fresh heartbeat from a process that still exists. */
+export function instanceAlive(record, now = Date.now(), isAlive = pidAlive) {
+	if (!record || !Number.isInteger(record.pid)) return false;
+	const beat = Number(record.heartbeatAt);
+	if (!Number.isFinite(beat) || now - beat > INSTANCE_STALE_MS) return false;
+	return isAlive(record.pid);
+}
+
+function launchMarkerPath(dir) {
+	return path.join(dir, "launch-requested");
+}
+
+/** Milliseconds since any process last launched the app, or null. */
+export async function lastLaunchAgeMs(dir = configDir(), now = Date.now()) {
+	try {
+		const at = Number(cleanFileValue(await readFile(launchMarkerPath(dir), "utf-8")));
+		if (!Number.isFinite(at) || at > now) return null;
+		return now - at;
+	} catch {
+		return null;
+	}
+}
+
+export async function recordLaunch(dir = configDir(), now = Date.now()) {
+	try {
+		await mkdir(dir, { recursive: true });
+		await writeFile(launchMarkerPath(dir), String(now), "utf-8");
+	} catch {
+		/* best-effort: the in-process flag still stops a second launch */
+	}
+}
+
+/**
+ * What to do this round:
+ *   use    — the port file's server answered
+ *   wait   — a PandaStudio is running (busy, booting, files being rewritten,
+ *            or Local automation off) or one was launched moments ago
+ *   launch — nothing is running and nobody launched it recently
+ *
+ * healthState / preferredState: probe of the port file's address / of the
+ * default port ("up" | "busy" | "down", or null when not probed).
+ */
+export function launchDecision({
+	healthState = null,
+	preferredState = null,
+	instanceIsAlive = false,
+	launchAgeMs = null,
+	debounceMs = LAUNCH_DEBOUNCE_MS,
+}) {
+	if (healthState === "up") return "use";
+	if (healthState === "busy") return "wait";
+	if (instanceIsAlive) return "wait";
+	if (preferredState === "up" || preferredState === "busy") return "wait";
+	if (launchAgeMs !== null && launchAgeMs < debounceMs) return "wait";
+	return "launch";
+}
+
+/**
+ * Reach the running app, launching it only when none is running. Returns the
+ * credentials whose server answered. `launch()` starts the app (throws when
+ * it can't). Everything else is injectable for tests.
+ */
+export async function ensureApp({
+	dir = configDir(),
+	launch,
+	timeoutMs = 60_000,
+	pollMs = 500,
+	preferredPort = DEFAULT_AUTOMATION_PORT,
+	probe = probeHealth,
+	readFiles = fileCredentials,
+	readInstance = readInstanceRecord,
+	isAlive = pidAlive,
+	launchAge = lastLaunchAgeMs,
+	markLaunch = recordLaunch,
+	now = Date.now,
+	sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+} = {}) {
+	const start = now();
+	let launched = false;
+	let last = { healthState: null, instanceIsAlive: false, recentLaunch: false };
+	for (;;) {
+		let creds = null;
+		let healthState = null;
+		try {
+			creds = await readFiles(dir);
+			healthState = (await probe(creds.port, 1500)).state;
+		} catch {
+			/* no files yet: not running, booting, or they're being rewritten */
+		}
+		if (healthState === "up") return creds;
+		const alive = instanceAlive(await readInstance(dir), now(), isAlive);
+		let preferredState = null;
+		if (!alive && healthState !== "busy" && creds?.port !== preferredPort) {
+			preferredState = (await probe(preferredPort, 1000)).state;
+		}
+		const age = launched ? 0 : await launchAge(dir, now());
+		const decision = launchDecision({
+			healthState,
+			preferredState,
+			instanceIsAlive: alive,
+			launchAgeMs: age,
+		});
+		last = { healthState, preferredState, instanceIsAlive: alive };
+		if (decision === "launch") {
+			await markLaunch(dir, now());
+			launched = true;
+			await launch();
+		}
+		if (now() - start >= timeoutMs) throw new Error(notReadyMessage(last, launched, timeoutMs));
+		await sleep(pollMs);
+	}
+}
+
+function notReadyMessage({ healthState, preferredState, instanceIsAlive }, launched, timeoutMs) {
+	const secs = Math.round(timeoutMs / 1000);
+	if (preferredState === "up" && !instanceIsAlive) {
+		return `A PandaStudio is answering on 127.0.0.1:${DEFAULT_AUTOMATION_PORT} but its access files in ${configDir()} are missing or stale. Quit PandaStudio completely and open it again.`;
+	}
+	if (healthState === "busy") {
+		return `PandaStudio is running but busy: it didn't answer for ${secs}s (a heavy export or import can do this). Try again in a moment; nothing was relaunched.`;
+	}
+	if (instanceIsAlive) {
+		return `PandaStudio is running but its automation server didn't answer within ${secs}s. In PandaStudio open Settings → Automation and make sure Local automation is on.`;
+	}
+	if (launched) {
+		return `PandaStudio did not become ready within ${secs}s. Open PandaStudio, go to Settings → Automation and turn on Local automation.`;
+	}
+	return `PandaStudio was started moments ago and isn't ready yet (waited ${secs}s). Open PandaStudio and check Settings → Automation → Local automation is on.`;
+}

package/bin/server.mjs

@@ -42,11 +42,10 @@ import {
 	cleanFileValue,
 	configDir,
 	connectInApp,
+	ensureApp,
 	fileCredentials,
 	IN_APP_UNAVAILABLE,
 	isInAppCaller,
-	probeHealth,
-	waitForHealth,
 } from "./appConnection.mjs";
 import { portableSchema } from "./portableSchema.mjs";
 
@@ -56,10 +55,6 @@ import { portableSchema } from "./portableSchema.mjs";
 
 const IN_APP = isInAppCaller();
 
-async function readCredentials() {
-	return fileCredentials(configDir());
-}
-
 function findInstalledApp() {
 	if (process.env.PANDASTUDIO_BIN) return process.env.PANDASTUDIO_BIN;
 	// The app records its own location (it can live anywhere on Windows,
@@ -102,46 +97,34 @@ function findInstalledApp() {
 	return candidates.find((c) => existsSync(c)) ?? candidates[0];
 }
 
+// Reach the running app; launch it only when nothing says it is running
+// (ensureApp in appConnection.mjs: port-file health, instance.json heartbeat,
+// the default port, and a machine-wide launch debounce). Launching on every
+// call that missed the server restarted PandaStudio "with every request".
 async function autoLaunchAndWait(timeoutSec = 60) {
-	// Try a fast probe in case the user already has it running.
-	try {
-		const c = await readCredentials();
-		// Busy (stalled main process) is not "not running": wait for it
-		// instead of launching a second copy.
-		if ((await waitForHealth(c.port)).state === "up") return c;
-	} catch {
-		/* not running */
-	}
-
-	const bin = findInstalledApp();
-	try {
-		// appLaunchEnv drops ELECTRON_RUN_AS_NODE: inherited, it made the
-		// "launch" start a Node REPL that exits instead of PandaStudio.
-		// windowsHide: false: this is the desktop app, whose window must show.
-		const child = spawn(bin, [], {
-			detached: true,
-			stdio: "ignore",
-			env: appLaunchEnv(),
-			windowsHide: false,
-		});
-		child.unref();
-	} catch (err) {
-		throw new Error(`failed to launch PandaStudio (${bin}): ${err?.message ?? err}`);
-	}
-
-	const deadline = Date.now() + timeoutSec * 1000;
-	while (Date.now() < deadline) {
-		try {
-			const c = await readCredentials();
-			if ((await probeHealth(c.port, 2000)).state === "up") return c;
-		} catch {
-			/* still booting */
-		}
-		await new Promise((r) => setTimeout(r, 500));
-	}
-	throw new Error(
-		`PandaStudio did not become ready within ${timeoutSec}s. Open PandaStudio, go to Settings → Automation and turn on Local automation.`,
-	);
+	return ensureApp({
+		timeoutMs: timeoutSec * 1000,
+		launch: async () => {
+			const bin = findInstalledApp();
+			try {
+				// appLaunchEnv drops ELECTRON_RUN_AS_NODE: inherited, it made the
+				// "launch" start a Node REPL that exits instead of PandaStudio.
+				// windowsHide: false: this is the desktop app, whose window must show.
+				const child = spawn(bin, [], {
+					detached: true,
+					stdio: "ignore",
+					env: appLaunchEnv(),
+					windowsHide: false,
+				});
+				child.on("error", () => {
+					/* reported by the readiness wait */
+				});
+				child.unref();
+			} catch (err) {
+				throw new Error(`failed to launch PandaStudio (${bin}): ${err?.message ?? err}`);
+			}
+		},
+	});
 }
 
 // The app answers /v1/call when the command finishes, and some commands run
@@ -1057,6 +1040,77 @@ const TOOLS = [
 		},
 		command: "workspace.contents",
 	},
+	{
+		name: "brand_list_assets",
+		description: "List reusable assets in the active workspace brand library.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: [],
+		},
+		command: "brand.list-assets",
+	},
+	{
+		name: "brand_add_asset",
+		description: "Copy a local image, video or audio file into the workspace brand library.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+				},
+				name: {
+					type: "string",
+				},
+				role: {
+					type: "string",
+					enum: ["logo", "outro", "intro", "cta", "watermark", "other"],
+				},
+			},
+			required: ["path"],
+		},
+		command: "brand.add-asset",
+	},
+	{
+		name: "brand_remove_asset",
+		description: "Remove an asset from the library. Existing timeline media remains available.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: {
+					type: "string",
+				},
+			},
+			required: ["id"],
+		},
+		command: "brand.remove-asset",
+	},
+	{
+		name: "project_add_brand_asset",
+		description:
+			"Insert a brand asset at edited atMs (default 0). Images are overlays, videos clips, audio tracks. Outros append.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: {
+					type: "string",
+				},
+				assetId: {
+					type: "string",
+				},
+				atMs: {
+					type: "number",
+					minimum: 0,
+				},
+				placement: {
+					type: "string",
+					enum: ["clip", "overlay", "append"],
+				},
+			},
+			required: ["id", "assetId"],
+		},
+		command: "project.add-brand-asset",
+	},
 	{
 		name: "workspace_get_brand",
 		description:
@@ -1074,6 +1128,7 @@ const TOOLS = [
 				brand: {
 					type: ["object", "null"],
 					properties: {
+						savedColors: { type: "array", items: { type: "string" }, maxItems: 24 },
 						name: { type: "string" },
 						tagline: { type: "string" },
 						colors: {
@@ -1524,6 +1579,35 @@ const TOOLS = [
 		},
 		command: "matte.bake",
 	},
+	{
+		name: "matte_export_cutout",
+		description:
+			"Export the person cut out of a clip as a transparent file for other tools (bakes the matte first if needed). format webm (VP9 + alpha, default; OBS, web), mov (ProRes 4444 + alpha; Premiere, Final Cut, Resolve, After Effects, Keynote) or png (one frame at atMs; thumbnails, Canva). Source size, follows the edit (cuts skipped, 1x speed), clip audio unless audio=false; inverse also writes the background plate. Returns jobId; job_wait gives outputPath, backgroundPath, durationMs, usedIn.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clip: {
+					type: "string",
+					description: "Clip id. Default: the camera clip / first clip with a person.",
+				},
+				source: { type: "string", enum: ["camera", "main"] },
+				format: { type: "string", enum: ["webm", "mov", "png"] },
+				startMs: { type: "number", description: "Edited-timeline start; default the clip start." },
+				endMs: { type: "number", description: "Edited-timeline end; default the clip end." },
+				atMs: { type: "number", description: "png: edited-timeline time of the frame." },
+				inverse: {
+					type: "boolean",
+					description: "Also write the background with the person removed.",
+				},
+				audio: { type: "boolean", description: "webm/mov: include the clip audio (default true)." },
+				outPath: { type: "string", description: "Absolute output path. Default: beside exports." },
+			},
+			required: ["id"],
+		},
+		command: "matte.export-cutout",
+	},
 	{
 		name: "project_read",
 		description:
@@ -1787,6 +1871,15 @@ const TOOLS = [
 				path: { type: "string" },
 				overlayId: { type: "string" },
 				slots: { type: "object", description: "Templates: changed slots only." },
+				variables: {
+					type: "object",
+					description:
+						"Typed values by id (motion_variables lists them). Validated by type/range/step/options; template slots and HyperFrames HTML declarations alike. Images embedded.",
+				},
+				preset: {
+					type: "string",
+					description: "Saved variable preset name (motion_list_presets); variables apply on top.",
+				},
 				background: { type: "string", enum: ["solid", "transparent", "glass"] },
 				html: { type: "string", description: "HTML graphics: full replacement." },
 				durationMs: { type: "number", description: "text-behind length." },
@@ -1955,6 +2048,24 @@ const TOOLS = [
 		},
 		command: "project.set-overlay-chroma-key",
 	},
+	{
+		name: "project_remove_overlay_background",
+		description:
+			"Cut the subject out of an IMAGE overlay (on-device; any background). Swaps its source to <name>-cutout.png at the same size and remembers the original; restore=true puts it back.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				regionId: { type: "string" },
+				restore: { type: "boolean" },
+				engine: { type: "string", enum: ["auto", "vision", "birefnet"] },
+				expectedRevision: { type: "number" },
+			},
+			required: ["regionId"],
+		},
+		command: "project.remove-overlay-background",
+	},
 	{
 		name: "project_add_fx",
 		description: "Add an FX overlay (bundled fxId or custom src).",
@@ -2072,6 +2183,40 @@ const TOOLS = [
 		},
 		command: "project.add-title-behind",
 	},
+	{
+		name: "project_add_3d_captions",
+		description:
+			"3D camera captions on a talking-head HOOK (5-20 s, 16:9, locked medium shot): the camera whips in and trucks between caption groups at different depths, a hero word hides behind the head, an optional ring of words turns in front of the speaker, a staircase finale. Rendered from the clip's footage, matte and transcript; placed over [startMs, endMs] (editor captions hidden there). Do it after the cuts. Refuses a moving camera or extreme close-up. ASYNC: job_wait gives overlayId, beats[].still (look at each), qc, warnings. Re-run replaces; reference/3d-captions.md.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				startMs: {
+					type: "number",
+					description: "Edited-timeline start (a pause between sentences).",
+				},
+				endMs: { type: "number", description: "Edited-timeline end, 5-20 s after startMs." },
+				style: { type: "string", enum: ["bold", "editorial"], description: "Default bold." },
+				heroWords: {
+					type: "array",
+					items: { type: "string" },
+					description:
+						"Words/short phrases to feature big. Default: the most stressed word per beat.",
+				},
+				accent: { type: "string", description: "Hero colour, CSS hex." },
+				grade: { type: "boolean", description: "Film finish (curves, grain). Default true." },
+				hideCaptions: {
+					type: "boolean",
+					description: "Hide editor captions over the range. Default true.",
+				},
+				force: { type: "boolean", description: "Run despite a moving camera or extreme close-up." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["id", "startMs", "endMs"],
+		},
+		command: "project.add-3d-captions",
+	},
 
 	// ── compose: visual regions ─────────────────────────────────────
 	{
@@ -2968,6 +3113,28 @@ const TOOLS = [
 		},
 		command: "project.add-freeze-frame",
 	},
+	{
+		name: "project_close_gap",
+		description:
+			"Close a gap on the timeline (the editor's right-click Close gap), one undo step. Times are EDITED ms (project_read / timeline_source_to_edited). lane main (default): ripple-delete startMs..endMs from the video; later content, captions and anchored graphics move back with their words; inserted pauses in the range are shortened or removed. lane media[:i] / audio[:i] / effects[:i] (zero-based sub-lane, packed by start time like the timeline rows): the range must be empty in that lane; every later item in that lane shifts left by the gap. Speed changes never move.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Project id (or pass path)." },
+				path: { type: "string", description: "Project file path (or pass id)." },
+				startMs: { type: "number", description: "Gap start, edited ms." },
+				endMs: { type: "number", description: "Gap end, edited ms (> startMs)." },
+				lane: {
+					type: "string",
+					description: "main (default), or media[:i], audio[:i], effects[:i] for a sub-lane.",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["startMs", "endMs"],
+		},
+		command: "project.close-gap",
+	},
+
 	{
 		name: "project_remove_pause",
 		description:
@@ -3240,7 +3407,7 @@ const TOOLS = [
 	{
 		name: "project_remove_region",
 		description:
-			"Delete a region by id (editor.*Regions, motion-element = editor.motionElements, or audioOverlays); linked peers go too.",
+			"Delete a region by id (editor.*Regions, motion-element = editor.motionElements, or audioOverlays); only this region is removed by default. Pass group=true to also remove linked peers.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3248,6 +3415,7 @@ const TOOLS = [
 				path: { type: "string" },
 				regionType: { type: "string", enum: [...REGION_TYPES, "motion-element"] },
 				regionId: { type: "string" },
+				group: { type: "boolean", description: "Remove all linked peers too. Default false." },
 				expectedRevision: { type: "number" },
 			},
 			required: ["regionType", "regionId"],
@@ -3346,7 +3514,7 @@ const TOOLS = [
 	{
 		name: "project_update_region",
 		description:
-			"Patch a region; unspecified fields are kept. Patchable: zoom (depth, focusX, focusY, focusMode static|auto), trim / speed (startMs, endMs, speed, rampIn, rampOut, preservePitch, freezeMs, reverse, reverseAudio), fx (startMs, endMs, opacity, blendMode, speed, zIndex), annotation (startMs, endMs, text = the words shown (content / textContent also work), x, y, width, height, the style fields below, zIndex), overlay (x, y, width, height in canvas %, layer, opacity, blendMode, muted, volume, loop, motionBlur, zIndex), adjustment (startMs, endMs, blendMode), motion (motionBlur), clip-transform (startMs, endMs, preset, transitionMs, easing, bezier), background-effect (as project_add_background_effect), audio-overlay (startMs, endMs, sourceStartMs, volume 0-2, fadeIn, fadeOut). A key the region type doesn't have is not applied: the result lists it in ignoredKeys with a warning, and the call fails when nothing in the patch applies.",
+			"Patch a region; unspecified fields are kept. Put the fields in patch. Every type takes startMs, endMs (edited ms; trim and speed are source ms); a retimed region is re-anchored at its new place, so later cuts and editor reloads keep it there. Patchable: zoom (depth, focusX, focusY, followCursor, focusMode static|auto), trim (startMs, endMs), speed (speed, rampIn, rampOut, preservePitch, freezeMs, holdMs, reverse, reverseAudio), fx (opacity, blendMode, speed, zIndex), annotation (text = the words shown, content, textContent, x, y, width, height, fontSize, fontFamily, textColor, color, backgroundColor, fontWeight, fontStyle, textDecoration, textAlign, style, zIndex), overlay (x, y, width, height in canvas %, layer, opacity, blendMode, muted, volume, loop, motionBlur, zIndex), adjustment (blendMode, fadeIn, fadeOut), motion (motionBlur), clip-transform (preset, transitionMs, easing, bezier, cameraFit, backgroundColor), background-effect (mode, strength, backgroundImage, backgroundFit, outline, outlineWidth, outlineColor, outlineShadow, matteContract, matteFeather), audio-overlay (sourceStartMs, volume 0-2, fadeIn, fadeOut in ms, 0 or null removes; fadeInMs, fadeOutMs are aliases). A key the region type doesn't have is not applied: the result lists it in ignoredKeys with a warning, and the call fails when nothing in the patch applies.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3975,6 +4143,97 @@ const TOOLS = [
 		},
 		command: "project.remove-volume-keyframe",
 	},
+	{
+		name: "project_set_audio_carve",
+		description:
+			"Voiceover carve on a music bed (audio overlay): while the main voice or a voiceover speaks, dip the bed's speech band (default 1000-4000 Hz) instead of lowering the whole track. amount 0..1 = deepest cut 2..18 dB (default 0.25 = 6 dB). Combine with a lighter project_set_audio_ducking. Omitted fields keep their value. Export accurate; the editor preview does not carve.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				trackId: { type: "string", description: "The music bed's audio overlay id, e.g. audio-1." },
+				enabled: { type: "boolean", description: "Carve on (default) or off." },
+				amount: { type: "number", minimum: 0, maximum: 1 },
+				lowHz: {
+					type: "number",
+					minimum: 160,
+					maximum: 6000,
+					description: "Band low edge (default 1000).",
+				},
+				highHz: {
+					type: "number",
+					minimum: 160,
+					maximum: 6000,
+					description: "Band high edge, above lowHz (default 4000).",
+				},
+				remove: { type: "boolean", description: "Delete the carve settings." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["trackId"],
+		},
+		command: "project.set-audio-carve",
+	},
+	{
+		name: "project_set_audio_fx",
+		description:
+			'Replace a track\'s ordered FX rack. trackId = audio overlay id or "main" (the main voice, one rack for all clips). fx = [{type, enabled?, params?}], [] clears. Types (params, ranges): highpass/lowpass (frequency Hz, q 0.1-20, poles "1"|"2"); lowshelf/highshelf (frequency, gain -40..40 dB); peaking (frequency, gain, q; a 3-band EQ = three peaking at 200/1000/4000 Hz); compressor (threshold -60..0 dB, ratio 1-20, attack 0.01-2000 ms, release 0.01-9000 ms, knee 1-8, makeup 0-36 dB, mix 0-1); deesser (intensity 0-1, frequency 0-1); reverb (size 0.05-1, damping 0-1, wet 0-1, dry 0-1); gain (gain -60..12 dB). Export applies all; preview: overlays hear EQ/gain/reverb, compressor approximated, de-esser export only; main voice previews gain only.',
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				trackId: { type: "string", description: 'Audio overlay id, or "main".' },
+				main: { type: "boolean", description: 'Same as trackId "main".' },
+				fx: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							type: {
+								type: "string",
+								enum: [
+									"highpass",
+									"lowpass",
+									"lowshelf",
+									"highshelf",
+									"peaking",
+									"compressor",
+									"deesser",
+									"reverb",
+									"gain",
+								],
+							},
+							enabled: { type: "boolean" },
+							params: { type: "object" },
+						},
+						required: ["type"],
+					},
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["fx"],
+		},
+		command: "project.set-audio-fx",
+	},
+	{
+		name: "project_set_audio_buses",
+		description:
+			"Mix group gains in dB (-60..12): voice (main track, voiceovers, overlay video sound), music (music beds), sfx (sound effects). Multiplies every track in the group after its own volume, ducking and FX. Omitted buses keep their value; reset sets all to 0 first. Preview and export match (preview caps each track at 100%).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				voice: { type: "number", minimum: -60, maximum: 12 },
+				music: { type: "number", minimum: -60, maximum: 12 },
+				sfx: { type: "number", minimum: -60, maximum: 12 },
+				reset: { type: "boolean" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.set-audio-buses",
+	},
 	{
 		name: "project_set_audio_ducking",
 		description:
@@ -4681,6 +4940,24 @@ const TOOLS = [
 		inputSchema: {
 			type: "object",
 			properties: {
+				area: {
+					type: "object",
+					description: "Display-local points. Native region capture. Minimum 32 x 32 points.",
+					properties: {
+						displayId: { type: "number" },
+						x: { type: "number" },
+						y: { type: "number" },
+						width: { type: "number", minimum: 32 },
+						height: { type: "number", minimum: 32 },
+					},
+					required: ["displayId", "x", "y", "width", "height"],
+					additionalProperties: false,
+				},
+				aspectRatio: {
+					type: "string",
+					enum: ["Free", "16:9", "9:16", "1:1", "4:3"],
+					description: "Lock area aspect. Without area, fit on the selected display.",
+				},
 				source: { type: "string", description: "From recording_list_sources." },
 				fps: { type: "number", description: "1-60, default 30." },
 				systemAudio: { type: "boolean", description: "Mic is never captured." },
@@ -5164,6 +5441,25 @@ const TOOLS = [
 		},
 		command: "media.generate-music",
 	},
+	{
+		name: "media_remove_background",
+		description:
+			"Remove a still image's background on this computer (people, products, pets, objects, logos). Writes <name>-cutout.png next to it; returns { path, width, height, engine }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: { type: "string", description: "Absolute image path." },
+				trim: {
+					type: "boolean",
+					description: "Crop the empty margin (default true); false keeps the canvas size.",
+				},
+				outPath: { type: "string", description: "Optional absolute .png path." },
+				engine: { type: "string", enum: ["auto", "vision", "birefnet"] },
+			},
+			required: ["path"],
+		},
+		command: "media.remove-background",
+	},
 	{
 		name: "media_import",
 		description:
@@ -5387,7 +5683,7 @@ const TOOLS = [
 	{
 		name: "motion_list",
 		description:
-			"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.",
+			"List motion-graphic templates (each with typed variables: type, default, min/max/step, options; plus slots, family, tags) and registryBlocks (with any declared variables). Render templates with motion_generate, blocks with motion_render_html. Retired templates are hidden unless includeRetired.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -5405,6 +5701,58 @@ const TOOLS = [
 		},
 		command: "motion.list",
 	},
+	{
+		name: "motion_variables",
+		description:
+			"Typed variables of a graphic (text, multiline, number, color, image, font, boolean, enum, list) with defaults/constraints, its current values and preset templateKey. source = an overlay's generatedFrom from project_read (template or HyperFrames HTML).",
+		inputSchema: {
+			type: "object",
+			properties: { source: { type: "object" } },
+			required: ["source"],
+		},
+		command: "motion.variables",
+	},
+	{
+		name: "motion_list_presets",
+		description:
+			"List the active workspace's saved variable presets {name, templateKey, values}. Pass source or templateId to list only those for that graphic.",
+		inputSchema: {
+			type: "object",
+			properties: { source: { type: "object" }, templateId: { type: "string" } },
+		},
+		command: "motion.list-presets",
+	},
+	{
+		name: "motion_save_preset",
+		description:
+			"Save a named variable set (e.g. 'Client A lower third') for graphics of the same template in this workspace; same name replaces. Images are embedded.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				source: { type: "object" },
+				name: { type: "string" },
+				variables: { type: "object" },
+			},
+			required: ["source", "name", "variables"],
+		},
+		command: "motion.save-preset",
+	},
+	{
+		name: "motion_delete_preset",
+		description:
+			"Delete a saved variable preset by name; identify its template with source, templateId or templateKey.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: { type: "string" },
+				source: { type: "object" },
+				templateId: { type: "string" },
+				templateKey: { type: "string" },
+			},
+			required: ["name"],
+		},
+		command: "motion.delete-preset",
+	},
 	{
 		name: "motion_generate",
 		description:
@@ -5414,6 +5762,15 @@ const TOOLS = [
 			properties: {
 				templateId: { type: "string" },
 				slots: { type: "object", description: "By key; image slots take a file path." },
+				variables: {
+					type: "object",
+					description:
+						"Typed values by id (templates[].variables from motion_list), validated, overriding slots. Images: path, URL or {url}; fonts: name or {name}.",
+				},
+				preset: {
+					type: "string",
+					description: "Saved variable preset name for this template (motion_list_presets).",
+				},
 				aspectRatio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
 				background: {
 					type: "string",
@@ -5426,7 +5783,7 @@ const TOOLS = [
 					description: "Length for templates with a durationRangeMs (clamped); ignored otherwise.",
 				},
 			},
-			required: ["templateId", "slots"],
+			required: ["templateId"],
 		},
 		command: "motion.generate",
 	},
@@ -5469,7 +5826,8 @@ const TOOLS = [
 	},
 	{
 		name: "motion_catalog_item",
-		description: "One catalog item: variables, htmlPath, demoPath and a mount snippet.",
+		description:
+			"One catalog item: variables (raw and typedVariables), htmlPath, demoPath and a mount snippet.",
 		inputSchema: {
 			type: "object",
 			properties: { name: { type: "string" } },
@@ -5527,6 +5885,23 @@ const TOOLS = [
 		},
 		command: "motion.render-film",
 	},
+	{
+		name: "motion_edit_element",
+		description:
+			'Edit one graphic element, write stored HTML and re-render in place with the same timeline timing. Async jobId. selector: #id or [data-panda-element="handle"]. patch: text, x/y (paired translation in px), width/height (px), rotation (degrees), layer (z-index), styles (color, background-color, font-family, font-size, font-weight, border-radius, opacity). Mapped text-only edits preserve template slots; structural edits become custom HTML.',
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				regionId: { type: "string" },
+				selector: { type: "string" },
+				patch: { type: "object" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["id", "regionId", "selector", "patch"],
+		},
+		command: "motion.edit-element",
+	},
 	{
 		name: "motion_render_html",
 		description:
@@ -6190,6 +6565,83 @@ const TOOLS = [
 		command: "job.get",
 	},
 
+	// ── review items (pins / drawings the user placed on the preview) ──
+	{
+		name: "review_list",
+		description:
+			"The review items the user marked on the preview (numbered pins and drawings, each with the graphic or element under it), open ones by default. Each: id, timeMs and optional range (edited ms), position {x,y} (0..1 of the frame), drawing points, targetIds (graphic / element / region / clip ids), note, sentAt, and imagePath: a PNG crop of the frame with the drawing burned in. Defaults to the open project.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Project id. Omit for the open project." },
+				path: { type: "string" },
+				includeResolved: { type: "boolean", description: "Also list resolved items." },
+			},
+		},
+		command: "review.list",
+	},
+	{
+		name: "review_resolve",
+		description:
+			"Mark review items done after you applied them: their pins leave the preview and the Pending edits tray. Needs the project id (or path) and the item ids.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				annotationIds: { type: "array", items: { type: "string" } },
+			},
+			required: ["annotationIds"],
+		},
+		command: "review.resolve",
+	},
+
+	{
+		name: "review_add",
+		description:
+			"Add a review item (numbered pin) to the project. annotation: { timeMs (edited ms), position {x,y} 0..1, note, kind comment|freehand, targetIds?, range? {startMs,endMs}, drawing? [{x,y}], id? }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				annotation: { type: "object" },
+			},
+			required: ["annotation"],
+		},
+		command: "review.add",
+	},
+	{
+		name: "review_update",
+		description:
+			"Change a review item's fields (note, range, position, targetIds, resolved); other fields are kept.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				annotationId: { type: "string" },
+				annotation: { type: "object", description: "Fields to change." },
+			},
+			required: ["annotationId", "annotation"],
+		},
+		command: "review.update",
+	},
+	{
+		name: "review_delete",
+		description: "Delete a review item. Use review_resolve for items you completed.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				annotationId: { type: "string" },
+			},
+			required: ["annotationId"],
+		},
+		command: "review.delete",
+	},
+
 	// ── timeline helpers ────────────────────────────────────────────
 	{
 		name: "timeline_source_to_edited",
@@ -6221,6 +6673,35 @@ const TOOLS = [
 		command: "timeline.edited-to-source",
 	},
 
+	{
+		name: "agent_run_list",
+		description:
+			"List a project's agent runs that changed it (newest last): runId, sessionId, prompt, and whether each is currently undone.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				projectId: { type: "string" },
+				sessionId: { type: "string", description: "Only runs from this chat" },
+			},
+			required: ["projectId"],
+		},
+		command: "agent.run-list",
+	},
+	{
+		name: "agent_run_restore",
+		description:
+			"Undo an agent run (restore the whole project as it was before the run), or redo it when it is undone. If edits were made after the run it changes nothing and answers confirmationRequired with laterEdits and a revision: show the user what would be lost, and only after they agree call again with confirmRevision set to that revision.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				projectId: { type: "string" },
+				runId: { type: "string" },
+				confirmRevision: { type: "number" },
+			},
+			required: ["projectId", "runId"],
+		},
+		command: "agent.run-restore",
+	},
 	...["read", "search"].map((action) => ({
 		name: `agent_session_${action}`,
 		description:
@@ -6302,6 +6783,8 @@ Publishing has daily limits (YouTube uploads and updates per license, social pos
 
 PandaStudio problems (a capability gap like an imported font the export can't draw, a command failing unexpectedly, a render not matching the project): call system_report_issue yourself, then tell the user you reported it. Not for user mistakes, missing keys or taste.
 
+Review items: the user can pin notes and drawings on the preview and send them in one turn (listed in the editor context and the message, crops attached in item order). Apply each one, then review_resolve with its id. review_list shows the open ones with a crop image path.
+
 Destination decides everything: infer it (Shorts/TikTok/vertical/<=90s: shorts; YouTube/tutorial/>8 min: youtube-long; LinkedIn; Loom/internal), else ask once.
 
 Full playbook (per-destination defaults, motion graphics, recipes, publishing): the PandaStudio skill. If you can't load it as a skill, call skill_read with no arguments at the start, then read the sections and reference docs the task needs. The rules above are only a summary.`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@writepanda/mcp",
-	"version": "1.222.0",
+	"version": "1.225.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",