@writepanda/mcp 1.222.0 → 1.224.0

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:
@@ -1955,6 +2039,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 +2174,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 ─────────────────────────────────────
 	{
@@ -3346,7 +3482,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: {
@@ -4681,6 +4817,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 +5318,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:

package/package.json

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