@writepanda/mcp 1.224.0 → 1.226.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/server.mjs

@@ -1871,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." },
@@ -2177,7 +2186,7 @@ const TOOLS = [
 	{
 		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.",
+			"3D camera captions on a talking-head HOOK (5-20 s, 16:9 or vertical 9:16, also 1:1 / 4:5; locked medium shot; in 9:16 built from the crop the Short shows, laid out inside the Shorts-safe area): 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: {
@@ -3104,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:
@@ -3376,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: {
@@ -3384,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"],
@@ -4111,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:
@@ -5560,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: {
@@ -5578,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:
@@ -5587,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",
@@ -5599,7 +5783,7 @@ const TOOLS = [
 					description: "Length for templates with a durationRangeMs (clamped); ignored otherwise.",
 				},
 			},
-			required: ["templateId", "slots"],
+			required: ["templateId"],
 		},
 		command: "motion.generate",
 	},
@@ -5642,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" } },
@@ -5700,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:
@@ -6363,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",
@@ -6394,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:
@@ -6469,12 +6777,16 @@ Before an editing pass, read the skill's "Which tool for which moment" section (
 Report the real count each step returned. No music, intro/outro cards or FX overlays unless the recipe or the user asks for them.
 A single named operation ("just add captions", "remove the silences") is exactly that: no recipe.
 
+End every turn that changed a project with a plain summary: what changed (with the counts the tools returned), what you tried and put back or skipped and why, and what is left. Say so plainly when the work is only partly done or a step failed. To take a run back: agent_run_restore (works from inside your current turn), or the chat's Undo this run button.
+
 Destructive actions need the user's own confirmation: project_delete, workspace_delete, recipe_delete, memory_forget, export_delete, export_clear_thumbnail, youtube_disconnect, social_disconnect. Ask plainly in chat first ("Delete project 'Demo'? This can't be undone.") and call only after they agree. PandaStudio then confirms with them itself: in its own chat the call returns confirmation_required and changes nothing while a Delete / Cancel card waits (tell them to press it; don't call again; the outcome arrives as their next message); from other apps a dialog asks, and the call is refused when nobody is at the app. Nothing you send can approve it.
 
 Publishing has daily limits (YouTube uploads and updates per license, social posts per workspace, and PandaStudio's shared YouTube quota). A failure with code daily_limit or youtube_quota_exceeded carries resetsAt: tell the user when it resets and do not retry, loop or switch accounts to get around it before then. It is not a bug to report.
 
 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.224.0",
+	"version": "1.226.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",