@writepanda/mcp 1.276.0 → 1.285.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" },
@@ -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"] },
@@ -8528,7 +8675,8 @@ const TOOLS = [
 	// ── project-aware LLM ──────────────────────────────────────────
 	{
 		name: "llm_generate_title",
-		description: "Generate a YouTube title from the project transcript (local LLM).",
+		description:
+			"Generate a YouTube title from what the EDITED video says (cut words left out) with the local LLM. Returns { title }: one complete phrase within maxChars, never cut mid-word.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -8541,7 +8689,8 @@ const TOOLS = [
 	},
 	{
 		name: "llm_generate_description",
-		description: "Generate a 3-5 sentence YouTube description from the transcript.",
+		description:
+			"Generate a 3-5 sentence YouTube description from what the EDITED video says, with the local LLM. Returns { description, warnings? }: a warning means it repeated the transcript, so write the description yourself.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -8554,7 +8703,8 @@ const TOOLS = [
 	},
 	{
 		name: "llm_generate_caption",
-		description: "Generate an Instagram Reel caption with hashtags from the transcript.",
+		description:
+			"Generate an Instagram Reel caption with hashtags from what the EDITED video says.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -8568,7 +8718,7 @@ const TOOLS = [
 	{
 		name: "llm_generate_timestamps",
 		description:
-			"Generate YouTube chapter timestamps for the edited video: edited-timeline times from the words that survive the cuts (first 0:00, each >= 10 s, all before the end); the local LLM only writes labels.",
+			"Generate YouTube chapter timestamps for the edited video: edited-timeline times from the words that survive the cuts (first 0:00, each >= 30 s, starting where a sentence starts, all before the end); the local LLM only writes each label from its own chapter's words.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -8856,7 +9006,7 @@ const TOOLS = [
 	{
 		name: "ideas_research",
 		description:
-			"Find outliers (videos beating their own channel's median views) across a niche: searches YouTube for the topic (comma-separate several angles) and/or expands from a seed channel the target audience watches, reads every channel found and ranks their recent uploads by multiplier. For what's trending, pass period month and maxAgeDays 30. Async: returns { researchId, jobId }; job.wait the jobId (~20-40 s), then ideas.get.",
+			"Find outliers (videos beating their own channel's median views) across a niche: searches YouTube for the topic (comma-separate several angles) and/or expands from a seed channel the target audience watches, reads every channel found and ranks their recent uploads by multiplier. For what's trending, pass period month and maxAgeDays 30. With maxAgeDays set, an outlier the listing left undated (Shorts, premieres) is kept only once its real publish date is under the limit; ones YouTube won't date are left out and counted in stats.undatedSkipped. Async: returns { researchId, jobId }; job.wait the jobId (~20-40 s), then ideas.get.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -9708,6 +9858,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.276.0",
+	"version": "1.285.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",