@writepanda/mcp 1.275.0 → 1.284.0

package/bin/server.mjs

@@ -53,7 +53,6 @@ import {
 	IN_APP_UNAVAILABLE,
 	isInAppCaller,
 } from "./appConnection.mjs";
-import { frameUntrusted } from "./untrusted.mjs";
 import {
 	APP_TOOLS,
 	clientSupportsUi,
@@ -63,6 +62,7 @@ import {
 	toolUiMeta,
 } from "./apps/index.mjs";
 import { portableSchema } from "./portableSchema.mjs";
+import { frameUntrusted } from "./untrusted.mjs";
 
 // ── Credentials + transport ───────────────────────────────────────────
 //
@@ -1032,7 +1032,7 @@ const TOOLS = [
 	{
 		name: "connector_list",
 		description:
-			'List MCP connectors and their state. If the one needed isn\'t connected, tell the user its howToConnect line; you cannot connect connectors. status "connected, last check failed" (connected:false, lastCheck with reason, host and fix) means PandaStudio\'s own last use of it failed. needsReconnect:true (state needs_auth, status "needs sign-in again", HTTP 401) = the service refused its sign-in (e.g. a stale Replicate API token): nothing on it runs until the user presses Reconnect in Settings; relay howToConnect, don\'t retry. auth "api-key" + needsKey: the user must paste a key in Settings (never ask for it in chat).',
+			'List MCP connectors and their state. If the one needed isn\'t connected, tell the user its howToConnect line; you cannot connect connectors. status "connected, last check failed" (connected:false, lastCheck with reason, host and fix) means PandaStudio\'s own last use of it failed. needsReconnect:true (state needs_auth, status "needs sign-in again", HTTP 401) = the service refused its sign-in (e.g. a stale Replicate API token): nothing on it runs until the user presses Reconnect in Settings; relay howToConnect, don\'t retry. auth "api-key" + needsKey: the user must paste a key in Settings (never ask for it in chat). native:true (fal): no connector_tools/connector_call; use its usedThrough tools (fal: media_generate_video).',
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1648,6 +1648,34 @@ const TOOLS = [
 		},
 		command: "project.duplicate",
 	},
+	{
+		name: "project_versions",
+		description:
+			"A project's earlier versions, newest first (a snapshot about every 10 min of editing, kept up to 30 days). For lost edits or 'go back to how it was'. Then project_open_version.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+			},
+		},
+		command: "project.versions",
+	},
+	{
+		name: "project_open_version",
+		description:
+			"Bring back an earlier version (from project_versions) as a NEW project beside the original, named '<name> (<date, time>)'. Never changes the original. Returns { id, path, name, savedAt }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				versionId: { type: "string", description: "From project_versions" },
+			},
+			required: ["versionId"],
+		},
+		command: "project.open-version",
+	},
 	{
 		name: "project_locate",
 		description:
@@ -3005,6 +3033,11 @@ const TOOLS = [
 		inputSchema: {
 			type: "object",
 			properties: {
+				still: {
+					type: "boolean",
+					description:
+						"The graphic is MEANT to hold still (no entrance, no motion): skip the frozen-render check, kept for re-renders. Never fake a slow drift instead.",
+				},
 				id: { type: "string" },
 				path: { type: "string" },
 				overlayId: { type: "string" },
@@ -4107,10 +4140,31 @@ const TOOLS = [
 		},
 		command: "project.detect-face",
 	},
+	{
+		name: "project_review_moment",
+		description:
+			"LOOK AND LISTEN to a moment of the edit as the viewer gets it: a contact sheet of the frames around atMs (edited ms) or wordId, the EXPORTED mix of that stretch transcribed and compared with what the edit should play (extra = leftover of a cut word or line, missing = clipped word), whether each cut lands in quiet or speech, nearby edits and stutters, plus a plain verdict. Use after every cut / pause / insert fix BEFORE telling the user it's fixed, and when the user names a moment ('at 16 seconds'). ASYNC: { jobId }; job_wait.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				atMs: { type: "number", description: "Edited ms at the centre. Or wordId." },
+				wordId: { type: "string", description: "Centre on this word (transcript id or prefix)." },
+				spanMs: {
+					type: "number",
+					description: "Each side of the centre, ms. Default 1500, max 5000.",
+				},
+				frames: { type: "number", description: "Frames on the sheet. Default 12, max 24." },
+				listen: { type: "boolean", description: "Default true; false = frames and edits only." },
+			},
+		},
+		command: "project.review-moment",
+	},
 	{
 		name: "project_render_sheet",
 		description:
-			"Render N frames across an edited-time range into one contact-sheet PNG (row-major). Returns { sheetPath, frames[{atMs, path}] }; sheetPath null = read frames[].path.",
+			"Render N frames across an edited-time range into one contact-sheet PNG (row-major). Returns { sheetPath, frames[{atMs, path}] }; sheetPath null (see sheetWarning) = read frames[].path.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4128,7 +4182,7 @@ const TOOLS = [
 	{
 		name: "project_apply_edit_plan",
 		description:
-			'Apply many trim / zoom / speed ops atomically (any invalid op aborts). Ops: {"op":"add-trim",startMs,endMs} | {"op":"add-zoom",atMs,durationMs,depth?,focusX?,focusY?,soundUrl?,anchorSourceMs?} | {"op":"add-speed",startMs,endMs,speed}.',
+			'Apply many trim / zoom / speed ops atomically (any invalid op aborts). Ops: {"op":"add-trim",startMs,endMs} (SOURCE ms) or by word {"op":"add-trim",afterWordId|fromWordId,beforeWordId|throughWordId}, edges snapped to the audio like project_add_trim | {"op":"add-zoom",atMs,durationMs,depth?,focusX?,focusY?,soundUrl?,anchorSourceMs?} | {"op":"add-speed",startMs,endMs,speed}.',
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4348,17 +4402,32 @@ const TOOLS = [
 	},
 	{
 		name: "project_add_trim",
-		description: "Mark a span the exporter skips (manual cut).",
+		description:
+			"Cut a span the exporter skips. Name the edges by WORD (afterWordId / fromWordId for the start, beforeWordId / throughWordId for the end): no ms maths, no clock mix-ups. Or startMs/endMs in SOURCE ms (a transcript word's sourceStartMs). Every edge snaps to the quietest point nearby without clipping a kept word; result.edges says where each landed and notes say when an edge inside a word cut it. Check the spot with project_review_moment before telling the user it's fixed.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				startMs: { type: "number" },
-				endMs: { type: "number" },
+				startMs: { type: "number", description: "SOURCE ms. Or afterWordId / fromWordId." },
+				endMs: { type: "number", description: "SOURCE ms. Or beforeWordId / throughWordId." },
+				afterWordId: {
+					type: "string",
+					description: "Cut STARTS right after this word (kept). Instead of startMs.",
+				},
+				fromWordId: { type: "string", description: "Cut STARTS at this word (cut too)." },
+				beforeWordId: {
+					type: "string",
+					description: "Cut ENDS right before this word (kept). Instead of endMs.",
+				},
+				throughWordId: { type: "string", description: "Cut ENDS after this word (cut too)." },
+				snapToAudio: {
+					type: "boolean",
+					description:
+						"Default true: edges snap to the quietest point nearby without clipping a kept word. false = exact ms.",
+				},
 				expectedRevision: { type: "number" },
 			},
-			required: ["startMs", "endMs"],
 		},
 		command: "project.add-trim",
 	},
@@ -4407,6 +4476,11 @@ const TOOLS = [
 		inputSchema: {
 			type: "object",
 			properties: {
+				snapToAudio: {
+					type: "boolean",
+					description:
+						"lane main: default true, each edge snaps to the quietest point nearby without clipping a kept word (result.edges). false = exact.",
+				},
 				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." },
@@ -4838,10 +4912,25 @@ const TOOLS = [
 	{
 		name: "project_update_region",
 		description:
-			"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.",
+			"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, afterWordId, fromWordId, beforeWordId, throughWordId), 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: {
+				afterWordId: {
+					type: "string",
+					description: "Cut STARTS right after this word (kept). Instead of startMs.",
+				},
+				fromWordId: { type: "string", description: "Cut STARTS at this word (cut too)." },
+				beforeWordId: {
+					type: "string",
+					description: "Cut ENDS right before this word (kept). Instead of endMs.",
+				},
+				throughWordId: { type: "string", description: "Cut ENDS after this word (cut too)." },
+				snapToAudio: {
+					type: "boolean",
+					description:
+						"Default true: edges snap to the quietest point nearby without clipping a kept word. false = exact ms.",
+				},
 				id: { type: "string" },
 				loop: { type: "boolean", description: "overlay: loop, or hold the last frame." },
 				path: { type: "string" },
@@ -5821,7 +5910,7 @@ const TOOLS = [
 	{
 		name: "transcript_transcribe",
 		description:
-			"Transcribe clips with word timestamps (default: only clips without words). Engine: language auto/english = Parakeet; any other named language = local Whisper LOCKED to it (engine override). Returns { jobId, plan } (plan = engine + reason, ranges, totalAudioMs: the audio that will be processed, estimate/estimatedMs: how long on this computer, advice: faster options for a long Whisper run; tell the user for long jobs). Long Whisper runs are saved chunk by chunk: stalls restart from the last chunk automatically; after job_cancel, a crash or an app restart, transcribing again resumes there. Progress is real (audio decoded); time left in progress.message and progress.data.etaMs. To REDO a transcript (wrong language, bad run) confirm language, pass per-run language and provider overrides, then force: true (all clips) or clipId. Word fixes are re-applied; tell the user about result droppedWordEdits[] (fixes that may need redoing). Each clip is transcribed only over the part it plays (head trim to tail trim, e.g. one half of a split; only the kept parts when cuts hide most of a long recording; result transcribedRanges[]). Clips with no audio track are skipped (result noAudioClips), not failed. Result warnings[] flags words that can't cover the audio (sound with no words, too few words: music, noise, another language) and a re-run with the same words as before: surface it, and get a second reading with engine whisper or a cloud provider (Parakeet isn't locked by language english, so retrying the same way repeats it). ASYNC: { jobId }, job_wait. Concurrent saves are merged and retried (three attempts). Exhausted conflicts report code revision_conflict / status 409 (job.errorDetails for async jobs).",
+			"Transcribe clips with word timestamps (default: only clips without words). Asking again while the same transcription is still running returns that job (alreadyRunning: true), never a second run: keep waiting on it. Engine: language auto/english = Parakeet; any other named language = local Whisper LOCKED to it (engine override). Returns { jobId, plan } (plan = engine + reason, ranges, totalAudioMs: the audio that will be processed, estimate/estimatedMs: how long on this computer, advice: faster options for a long Whisper run; tell the user for long jobs). Long Whisper runs are saved chunk by chunk: stalls restart from the last chunk automatically; after job_cancel, a crash or an app restart, transcribing again resumes there. Progress is real (audio decoded); time left in progress.message and progress.data.etaMs. To REDO a transcript (wrong language, bad run) confirm language, pass per-run language and provider overrides, then force: true (all clips) or clipId. Word fixes are re-applied; tell the user about result droppedWordEdits[] (fixes that may need redoing). Each clip is transcribed only over the part it plays (head trim to tail trim, e.g. one half of a split; only the kept parts when cuts hide most of a long recording; result transcribedRanges[]). Clips with no audio track are skipped (result noAudioClips), not failed. Result warnings[] flags words that can't cover the audio (sound with no words, too few words: music, noise, another language) and a re-run with the same words as before: surface it, and get a second reading with engine whisper or a cloud provider (Parakeet isn't locked by language english, so retrying the same way repeats it). ASYNC: { jobId }, job_wait. Concurrent saves are merged and retried (three attempts). Exhausted conflicts report code revision_conflict / status 409 (job.errorDetails for async jobs).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -5921,7 +6010,7 @@ const TOOLS = [
 	{
 		name: "transcript_get",
 		description:
-			"Transcript (default: open project). compact: segments of [id, text, startMs SOURCE, editedStartMs (null = cut)]; ids are unique prefixes, accepted wherever word ids are. text: '[m:ss.s] line' per segment, cheapest to read. words: full ids, end times, speaker. full: legacy.",
+			"Transcript (default: open project). compact: segments of [id, text, editedStartMs, editedEndMs, sourceStartMs] (edited = as it plays, the playhead's clock, null = cut; sourceStartMs for anchorSourceMs; cut by word id, not ms); ids are unique prefixes, accepted wherever word ids are. text: '[m:ss.s] line' per segment, cheapest to read. words: full ids, end times, speaker. full: legacy.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -6906,6 +6995,54 @@ const TOOLS = [
 		},
 		command: "media.generate-presenter",
 	},
+	{
+		name: "media_generate_video",
+		description:
+			"Generate an AI video clip with MiniMax H3 on the user's OWN fal account (connect fal in Settings > Connectors; their credits). Text to video, or image to video from a first frame (image) and optional last frame (endImage). PAID: only after the user agreed; never retry a failed job yourself. ASYNC: { jobId, estimatedCostUsd }; job_wait timeoutMs 600000 for { videoPath, durationMs, width, height, model, requestId }. Place with project_add_motion_graphic (overlay, moving B-roll) or project_add_clip (main track). FAL_NOT_CONNECTED: ask the user to connect fal (never ask for the key in chat).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				prompt: {
+					type: "string",
+					description:
+						"The shot: subject, action, camera, light, mood. With an image, describe the motion.",
+				},
+				image: {
+					type: "string",
+					description: "First frame: absolute path (PNG/JPEG/WebP) or https URL.",
+				},
+				endImage: { type: "string", description: "Last frame, same forms. Image to video only." },
+				model: {
+					type: "string",
+					enum: ["h3", "h3-max", "h3-max-turbo"],
+					description: "Default h3. h3-max for 1080P; h3-max-turbo is faster and cheaper.",
+				},
+				durationSec: {
+					type: "number",
+					description: "Default 5. h3: whole seconds 5-15; h3-max/turbo: 0.92-15.",
+				},
+				resolution: {
+					type: "string",
+					enum: ["480P", "768P", "1080P", "2K", "4K"],
+					description: "Default 768P. h3: 480P/768P/2K/4K; h3-max/turbo: 480P/768P/1080P.",
+				},
+				aspectRatio: {
+					type: "string",
+					enum: ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"],
+					description: "Text to video only (default 16:9); image to video follows the image.",
+				},
+				promptExpansion: {
+					type: "string",
+					enum: ["balanced", "fast", "quality", "disabled"],
+					description: "fal's prompt rewriting. Default balanced; disabled = word for word.",
+				},
+				seed: { type: "number" },
+				outputDir: { type: "string", description: "Default <userData>/generated-videos." },
+			},
+			required: ["prompt"],
+		},
+		command: "media.generate-video",
+	},
 	{
 		name: "project_inspect_footage",
 		description:
@@ -8179,6 +8316,11 @@ const TOOLS = [
 		inputSchema: {
 			type: "object",
 			properties: {
+				still: {
+					type: "boolean",
+					description:
+						"The graphic is MEANT to hold still (no entrance, no motion): skip the frozen-render check, kept for re-renders. Never fake a slow drift instead.",
+				},
 				templateId: { type: "string" },
 				slots: { type: "object", description: "By key; image slots take a file path." },
 				variables: {
@@ -8328,6 +8470,11 @@ const TOOLS = [
 		inputSchema: {
 			type: "object",
 			properties: {
+				still: {
+					type: "boolean",
+					description:
+						"The graphic is MEANT to hold still (no entrance, no motion): skip the frozen-render check, kept for re-renders. Never fake a slow drift instead.",
+				},
 				html: { type: "string", description: "Or htmlPath." },
 				htmlPath: { type: "string" },
 				aspectRatio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
@@ -8484,7 +8631,8 @@ const TOOLS = [
 	},
 	{
 		name: "asset_list_music",
-		description: "List bundled music (pick by intents; add absolutePath with project_add_audio).",
+		description:
+			"List bundled music (pick by intents; add absolutePath with project_add_audio). Cleared for commercial use in the user's videos, paid ads included (see `license` in the reply): don't flag it as a licensing risk.",
 		inputSchema: { type: "object", properties: {} },
 		command: "asset.list-music",
 	},
@@ -9707,6 +9855,7 @@ 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.
 
+Fixing a cut, pause or insert the user points at ("at 16 s it's sloppy"): look and listen with project_review_moment (frames + the exported mix transcribed + whether each cut lands in quiet), fix by WORD (project_add_trim / project_update_region with afterWordId / beforeWordId, never ms worked out by hand; edges snap to the audio), then review again before saying it's fixed. A few frames off is quicker for the user to drag in the timeline: tell them. A stutter in a result's warnings (picture changes a few frames apart) means put them on one frame or keep one.
 Views: in chat apps that show MCP views, preview_show, project_render_frame / _render_sheet and project_edit_summary also show the frames and what the edit contains, and clips_get / clips_make show the clips as cards the user can open, export or remove. Summarise in a line instead of describing each frame or clip; what the user does in a view arrives as context, don't redo it.
 
 Share links: when the user asks to send a video for feedback, share_status then share_create on a finished export gives a link anyone can watch and comment on (async, job_wait; storage is capped per plan, quota_exceeded means ask which link to delete). share_comments brings viewer comments into the project as review pins: apply each, review_resolve it, and it shows as Done to viewers. Never share, delete a link or reply to viewers without the user asking.

package/package.json

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