@writepanda/mcp 1.18.0 → 1.21.0

package/bin/server.mjs

@@ -354,7 +354,7 @@ const TOOLS = [
 	{
 		name: "project_add_zoom",
 		description:
-			"Add a zoom region — highlight a UI moment. Typical pattern: find 'click X' in transcript, drop zoom there. Ships with a short swoosh SFX by default; pass soundUrl=\"none\" for silent.",
+			"Add a zoom region — highlight a UI moment. Typical pattern: find 'click X' in transcript, drop zoom there. ALWAYS pass anchorSourceMs (= the same source-time value you use for atMs) when picking from a transcript word — without it, the zoom drifts off the moment as soon as any trim is added (which the YouTube editing playbook always does via remove-fillers / remove-silences). Ships with a short swoosh SFX by default; pass soundUrl=\"none\" for silent.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -374,6 +374,16 @@ const TOOLS = [
 					type: "number",
 					description: "Sound volume 0–1. Default 1.",
 				},
+				anchorSourceMs: {
+					type: "number",
+					description:
+						"Anchor the zoom to a moment in the original recording (a transcript word's startMs, a click in cursor telemetry). When set, the zoom's edited-time position is recomputed automatically every time a trim or speed region is added/removed. STRONGLY RECOMMENDED when atMs comes from the transcript — otherwise the zoom will drift off the moment as soon as any trim is added.",
+				},
+				anchorSourceEndMs: {
+					type: "number",
+					description:
+						"Optional anchor end (source ms). When set, the zoom's duration tracks the source-time span instead of preserving the original visible duration. Useful for zooms covering a multi-word phrase.",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["atMs", "durationMs"],
@@ -548,7 +558,7 @@ const TOOLS = [
 	{
 		name: "project_remove_region",
 		description:
-			"Delete an existing region (zoom, trim, speed, annotation, fx, lower-third, overlay) by its UUID. Use project_read to find region IDs. Returns the updated project.",
+			"Delete an existing region (zoom, trim, speed, annotation, fx, lower-third, overlay, audio-overlay) by its id. Use project_read to find region ids — visual regions live under editor.*Regions; audio overlays live under audioOverlays[]. Returns the updated project.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -556,9 +566,10 @@ const TOOLS = [
 				path: { type: "string" },
 				regionType: {
 					type: "string",
-					description: "zoom | trim | speed | annotation | fx | lower-third | overlay",
+					description:
+						"zoom | trim | speed | annotation | fx | lower-third | overlay | audio-overlay",
 				},
-				regionId: { type: "string", description: "UUID of the region to delete" },
+				regionId: { type: "string", description: "id of the region to delete" },
 				expectedRevision: { type: "number" },
 			},
 			required: ["regionType", "regionId"],
@@ -568,7 +579,7 @@ const TOOLS = [
 	{
 		name: "project_update_region",
 		description:
-			"Patch fields on an existing region without replacing it. Accepts any subset of the region's own properties — only the supplied fields are changed, everything else is preserved. Works on zoom (depth, focusX, focusY), trim (startMs, endMs), speed (startMs, endMs, speed), lower-third (content, subtitle, atMs, durationMs, designType, accentColor, textColor, backgroundColor, backgroundRadius, fontSize, fontFamily), fx (atMs, durationMs), annotation, and overlay regions.",
+			"Patch fields on an existing region without replacing it. Accepts any subset of the region's own properties — only the supplied fields are changed, everything else is preserved. Works on zoom (depth, focusX, focusY), trim (startMs, endMs), speed (startMs, endMs, speed), lower-third (content, subtitle, atMs, durationMs, designType, accentColor, textColor, backgroundColor, backgroundRadius, fontSize, fontFamily), fx (atMs, durationMs), annotation, overlay, and audio-overlay (startMs, endMs, sourceStartMs, volume — lets you drag-trim an audio overlay without removing it).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -576,13 +587,14 @@ const TOOLS = [
 				path: { type: "string" },
 				regionType: {
 					type: "string",
-					description: "zoom | trim | speed | annotation | fx | lower-third | overlay",
+					description:
+						"zoom | trim | speed | annotation | fx | lower-third | overlay | audio-overlay",
 				},
-				regionId: { type: "string", description: "UUID of the region to update" },
+				regionId: { type: "string", description: "id of the region to update" },
 				patch: {
 					type: "object",
 					description:
-						"Fields to update (partial). E.g. { depth: 4 } to change zoom depth, or { content: 'New Name' } on a lower-third.",
+						"Fields to update (partial). E.g. { depth: 4 } to change zoom depth, { content: 'New Name' } on a lower-third, or { startMs: 2000, endMs: 15000, sourceStartMs: 4000 } to shift + trim an audio overlay (play seconds 4–17 of the source from the 2s mark on the timeline).",
 				},
 				expectedRevision: { type: "number" },
 			},
@@ -748,7 +760,7 @@ const TOOLS = [
 	{
 		name: "project_add_audio",
 		description:
-			"Add a background audio track (music, VO, ambient sound) to the project. The audio plays over the full mix from startMs and is exported automatically. Use project_remove_audio to remove it. Returns { overlayId } — save this to remove it later.",
+			"Add a background audio overlay (music, VO, ambient) as a first-class timeline region. Plays from startMs to endMs on the edited timeline; sourceStartMs is the in-point into the source file. Waveform peaks are extracted automatically and stored on the overlay for the timeline UI. Use project_update_region (regionType=audio-overlay) to drag/trim it afterward. Returns { overlayId } — save this to trim/remove later.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -760,12 +772,27 @@ const TOOLS = [
 				},
 				startMs: {
 					type: "number",
-					description: "Where in the edited timeline playback starts. Default 0.",
+					description: "Where on the edited timeline playback starts. Default 0.",
+				},
+				endMs: {
+					type: "number",
+					description:
+						"Where on the edited timeline playback ends. Precedence: endMs > maxDurationMs > durationMs. If all are omitted, defaults to the source file's real duration.",
+				},
+				sourceStartMs: {
+					type: "number",
+					description:
+						"In-point into the source file in ms. Default 0. Combine with endMs-startMs to play a window of the source (e.g. startMs=2000, endMs=15000, sourceStartMs=4000 plays seconds 4–17 of the source at timeline position 2–15s).",
+				},
+				durationMs: {
+					type: "number",
+					description: "Fallback duration when neither endMs nor maxDurationMs is given.",
 				},
 				volume: { type: "number", description: "Volume multiplier 0–2. Default 0.8." },
 				maxDurationMs: {
 					type: "number",
-					description: "Clip the audio at this duration. Omit to play the full file.",
+					description:
+						"[Legacy] Sets endMs = startMs + maxDurationMs when endMs is absent. Prefer endMs.",
 				},
 				expectedRevision: { type: "number" },
 			},
@@ -1048,7 +1075,7 @@ const TOOLS = [
 	{
 		name: "motion_render_html",
 		description:
-			"Render arbitrary HTML/CSS/JS to video. Use this when the bundled motion-graphic templates don't fit the brief — you write the HTML, the Chromium → capturePage → FFmpeg pipeline does the rest. Pass either inline `html` or a `htmlPath`. Animations should auto-start on DOMContentLoaded. Set `transparent: true` to get a WebM with alpha channel for overlays (lower thirds, watermarks, name plates) that composite over existing video. IMPORTANT: renders are sequential — call job_wait to completion before starting another render, or you'll get a RENDER_BUSY error. Async — returns { jobId, outputPath }; poll job_wait for the final file.",
+			"Render arbitrary HTML/CSS/JS to video via the HyperFrames engine — frame-perfect, seekable capture through chrome-headless-shell's BeginFrame API. Use this when the bundled motion-graphic templates don't fit the brief. The HTML MUST expose a paused GSAP timeline registered as `window.__timelines[<data-composition-id>] = tl` — NOT CSS keyframes, NOT setTimeout, NOT `window.__hf.seek` (that lower-level protocol skips the compositor invalidation wrapper and renders with 1-second stalls). See the SKILL.md `Custom motion graphics — HTML authoring` section for the required `data-composition-id`/`data-width`/`data-height`/`data-duration` root element, the canonical template, and pacing rules. Pass either inline `html` or `htmlPath`. Set `transparent: true` for a WebM+alpha overlay (lower thirds, watermarks). IMPORTANT: renders are sequential — call job_wait to completion before starting another render, or you'll get a RENDER_BUSY error. Async — returns { jobId, outputPath }; poll job_wait for the final file.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1167,7 +1194,7 @@ const TOOLS = [
 	{
 		name: "asset_list_music",
 		description:
-			"List every bundled background music track (id, title, category, mood, durationMs, absolutePath). Use absolutePath with project_add_audio to attach a track to a project.",
+			"List every bundled background music track. Each track has: id, title, category, mood, durationMs, absolutePath, and agent-routing hints `intents` (e.g. product_video, kinetic_text, promo, intro, outro, tech_review, vlog, generic) and `recommendedFor` (youtube-long | shorts | linkedin | loom). Match on intents first when picking a track — use mood/category as tiebreakers. Use absolutePath with project_add_audio to attach a track to a project.",
 		inputSchema: { type: "object", properties: {} },
 		command: "asset.list-music",
 	},

package/package.json

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