@writepanda/mcp 1.58.0 → 1.66.0

package/bin/server.mjs

@@ -575,7 +575,7 @@ const TOOLS = [
 		command: "project.open",
 	},
 
-	// ── compose: clips, motion graphics, FX, lower-thirds ──────────
+	// ── compose: clips, motion graphics, FX ────────────────────────
 	{
 		name: "project_add_clip",
 		description:
@@ -646,6 +646,12 @@ const TOOLS = [
 					description:
 						"Optional CSS color string composited over the blurred backdrop. Editor default: 'rgba(10,10,10,0.18)' (slight dark glass). Only applied when backdropBlurStrength > 0.",
 				},
+				layer: {
+					type: "string",
+					enum: ["overlay", "background"],
+					description:
+						"'background' renders this full-frame graphic BEHIND the camera (graphic-background + talking-head-card layout) — pair it with a CARD camera clip-transform (cam-right-portrait / cam-bottom-right-quarter) over the same span. The camera card composites on top in preview AND export. Default 'overlay' (on top).",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["durationMs"],
@@ -780,54 +786,71 @@ const TOOLS = [
 				src: { type: "string", description: "Direct path/URL (alternative to fxId)" },
 				atMs: { type: "number" },
 				durationMs: { type: "number", description: "Default 2500ms for bundled FX" },
+				speed: {
+					type: "number",
+					description:
+						"Playback-speed multiplier for the looping FX (0.25-4, default 1). 2 = twice as fast, 0.5 = half. Speeds up / slows down a film burn, light leak, etc. without re-rendering.",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["atMs"],
 		},
 		command: "project.add-fx",
 	},
+	{
+		name: "project_add_transition",
+		description:
+			"Place a transition at a cut between two clips. Drops a bundled transition overlay (a full-frame transparent WebM that goes opaque at its midpoint) CENTERED on atMs, so the opaque peak masks the cut and reads as a scene change. No render step. Pass atMs = the cut time (a clip boundary from project_read). Ids (asset_list_transitions): fade-black, fade-white, flash, light-sweep, film-burn, glitch.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				transitionId: { type: "string", description: "Bundled id, e.g. fade-black. From asset_list_transitions." },
+				file: { type: "string", description: "Custom transition video (path / file:// URL). Use instead of transitionId." },
+				atMs: { type: "number", description: "Edited-timeline CUT time to center the transition on." },
+				durationMs: { type: "number", description: "Total length. Default 1000 (native length of the bundled set)." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["atMs"],
+		},
+		command: "project.add-transition",
+	},
 	{
 		name: "project_add_lower_third",
-		description: "Drop a lower-third name plate onto the timeline.",
+		description:
+			"One-call lower third: renders an lt-* nameplate motion template (hyperframes) with your name/title and places it on the timeline as a transparent overlay at atMs. ASYNC — returns { jobId, outputPath }; call job_wait — it resolves once the region is PLACED (result: { path, revision, outputPath, durationMs }), no separate project_add_motion_graphic call needed. Designs (see motion_list, category lower-third): lt-vox-marker (default, highlighter swipe), lt-broadcast-bar (news chyron), lt-glass-card (frosted), lt-kinetic-stack (bold word-by-word), lt-minimal-line (editorial), lt-corner-plate (documentary bracket + kicker slot), lt-accent-slab (knockout name), lt-avatar-pill (creator pill), lt-typewriter-tag (mono typing), lt-gradient-sweep (gradient glow).",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				content: { type: "string", description: "Primary text (name)" },
-				subtitle: { type: "string", description: "Secondary text (title)" },
-				atMs: { type: "number" },
-				durationMs: { type: "number", description: "Default 5000ms" },
-				designType: {
+				name: { type: "string", description: "Primary text (person/brand name)" },
+				title: { type: "string", description: "Secondary line (role / handle / tagline)" },
+				templateId: {
 					type: "string",
-					description:
-						"slash-reveal | center-stack | split-horizontal | name-bar | border-frame | minimal-underline | box-reveal | corner-brackets. Default: slash-reveal.",
+					description: "lt-* design id. Default lt-vox-marker.",
 				},
-				accentColor: { type: "string", description: "Hex accent/background color" },
-				textColor: { type: "string", description: "Hex text color. Default #ffffff" },
-				backgroundColor: {
+				atMs: { type: "number", description: "Edited timeline time" },
+				aspectRatio: {
 					type: "string",
-					description: "Hex background fill. Default matches accentColor",
+					description: "16:9 | 9:16 | 1:1. Default 16:9 — match the project's aspect.",
 				},
-				backgroundRadius: {
-					type: "number",
-					description: "Corner radius in pixels. Default 8",
+				slots: {
+					type: "object",
+					description:
+						"Optional extra slot overrides (colors like accentColor/inkColor, or kicker for lt-corner-plate). Keys from motion_list. name/title args win over same-key entries.",
 				},
-				fontSize: { type: "number", description: "Primary text font size in px. Default 28" },
-				fontFamily: { type: "string", description: "CSS font family name. Default Inter" },
 				soundUrl: {
 					type: "string",
 					description:
-						'SFX played when the lower third enters. Bundled id (bundled:sound/<id>). Default bundled:sound/mouse-click. Pass "none" for silent.',
-				},
-				soundVolume: {
-					type: "number",
-					description: "Sound volume 0–1. Default 0.8.",
+						'SFX on enter. Bundled id (bundled:sound/<id>). Default bundled:sound/mouse-click. Pass "none" for silent.',
 				},
+				soundVolume: { type: "number", description: "Sound volume 0–1. Default 1." },
 				anchorSourceMs: {
 					type: "number",
 					description:
-						"Anchor the lower third to a SOURCE-time moment. Pass when atMs was derived from a transcript word's startMs — the lower third re-anchors automatically on subsequent transcript edits. Without it, the lower third drifts after any trim. Omit for free-floating placement.",
+						"Anchor to a SOURCE-time moment. Pass when atMs comes from a transcript word's startMs so the region survives later trims.",
 				},
 				anchorSourceEndMs: {
 					type: "number",
@@ -835,7 +858,7 @@ const TOOLS = [
 				},
 				expectedRevision: { type: "number" },
 			},
-			required: ["content", "atMs"],
+			required: ["name", "atMs"],
 		},
 		command: "project.add-lower-third",
 	},
@@ -887,7 +910,7 @@ const TOOLS = [
 	{
 		name: "project_set_region_sound",
 		description:
-			'Set or clear the sound effect on an existing region (zoom / motionGraphic / lowerThird / fx). Use to swap the default zoom swoosh, add a ding to a motion graphic, or mute a lower-third click. Pass soundUrl="none" to clear.',
+			'Set or clear the sound effect on an existing region (zoom / motionGraphic / fx). Use to swap the default zoom swoosh, add a ding to a motion graphic, or mute an effect sound. Pass soundUrl="none" to clear.',
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -896,7 +919,7 @@ const TOOLS = [
 				regionId: { type: "string", description: "Target region id" },
 				regionType: {
 					type: "string",
-					enum: ["zoom", "motionGraphic", "lowerThird", "fx"],
+					enum: ["zoom", "motionGraphic", "fx"],
 					description: "Region kind that owns the id",
 				},
 				soundUrl: {
@@ -1001,6 +1024,7 @@ const TOOLS = [
 						"cam-bottom-half",
 						"cam-top-half",
 						"cam-right-portrait",
+						"cam-right-portrait-sm",
 						"cam-left-portrait",
 						"cam-bottom-right-quarter",
 						"cam-bottom-left-quarter",
@@ -1014,7 +1038,7 @@ const TOOLS = [
 						"layout-guest-full",
 					],
 					description:
-						"cam-* (camera reposition into a sub-rect): cam-bottom-half / cam-top-half (9:16); cam-right-portrait / cam-left-portrait (16:9 ~35% card); cam-bottom-right-quarter / cam-bottom-left-quarter (corner card); cam-right-55/left-55/right-50/left-50 (designed splits). layout-* (PODCAST ONLY — whole-composite swap over time): layout-side-by-side, layout-podcast (two equal tiles), layout-host-full (speaker 1 only), layout-guest-full (speaker 2 only). IMPORTANT: layout-* presets only do anything on a PODCAST clip (kind='podcast' — a clip with BOTH a host and a guest source). On any other clip there is no second speaker, so they are a no-op; use cam-* there. Check clip.kind via project_read before using layout-*.",
+						"cam-* (camera reposition into a sub-rect): cam-bottom-half / cam-top-half (9:16); cam-right-portrait / cam-left-portrait (16:9 ~35% card); cam-right-portrait-sm (small ~25% host card — for a full-frame graphic background); cam-bottom-right-quarter / cam-bottom-left-quarter (corner card); cam-right-55/left-55/right-50/left-50 (designed splits). layout-* (PODCAST ONLY — whole-composite swap over time): layout-side-by-side, layout-podcast (two equal tiles), layout-host-full (speaker 1 only), layout-guest-full (speaker 2 only). IMPORTANT: layout-* presets only do anything on a PODCAST clip (kind='podcast' — a clip with BOTH a host and a guest source). On any other clip there is no second speaker, so they are a no-op; use cam-* there. Check clip.kind via project_read before using layout-*.",
 				},
 				transitionMs: {
 					type: "number",
@@ -1110,7 +1134,7 @@ const TOOLS = [
 	{
 		name: "project_move_clip",
 		description:
-			"Reorder a clip on the main track. `clipId` identifies the clip; `toIndex` is its new 0-based position after the move. Project-level regions (zooms, trims, speeds, annotations, FX, lower-thirds, media overlays, clip transforms) automatically migrate to follow their original clips so the user-perceived edits stay attached to the same content — a zoom that was 'into the explanation in clip 2' is still pointing at the same explanation after clip 2 moves to position 0. Per-clip transcripts ride on the clips themselves and don't need separate migration.",
+			"Reorder a clip on the main track. `clipId` identifies the clip; `toIndex` is its new 0-based position after the move. Project-level regions (zooms, trims, speeds, annotations, FX, media overlays, clip transforms) automatically migrate to follow their original clips so the user-perceived edits stay attached to the same content — a zoom that was 'into the explanation in clip 2' is still pointing at the same explanation after clip 2 moves to position 0. Per-clip transcripts ride on the clips themselves and don't need separate migration.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1133,7 +1157,7 @@ const TOOLS = [
 	{
 		name: "project_remove_region",
 		description:
-			"Delete an existing region (zoom, trim, speed, annotation, fx, lower-third, overlay, clip-transform, audio-overlay) by its id. Use project_read to find region ids — visual regions live under editor.*Regions; audio overlays live under audioOverlays[]. If the region belongs to a link group (designed-segment pair: a clip-transform parking the camera into one half + the panel motion-graphic on the other half), deleting either half also removes its peer so the pair stays coherent. Returns the updated project.",
+			"Delete an existing region (zoom, trim, speed, annotation, fx, overlay, clip-transform, audio-overlay) by its id. Use project_read to find region ids — visual regions live under editor.*Regions; audio overlays live under audioOverlays[]. If the region belongs to a link group (designed-segment pair: a clip-transform parking the camera into one half + the panel motion-graphic on the other half), deleting either half also removes its peer so the pair stays coherent. Returns the updated project.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1142,7 +1166,7 @@ const TOOLS = [
 				regionType: {
 					type: "string",
 					description:
-						"zoom | trim | speed | annotation | fx | lower-third | overlay | clip-transform | audio-overlay",
+						"zoom | trim | speed | annotation | fx | overlay | clip-transform | audio-overlay",
 				},
 				regionId: { type: "string", description: "id of the region to delete" },
 				expectedRevision: { type: "number" },
@@ -1173,7 +1197,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, overlay, clip-transform (startMs, endMs, preset, transitionMs), and audio-overlay (startMs, endMs, sourceStartMs, volume — lets you drag-trim an audio overlay without removing it). Time shifts on a link-grouped region (e.g. one half of a designed segment) propagate to every peer in the group so the pair stays coherent.",
+			"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), fx (atMs, durationMs, opacity, blendMode, speed), annotation, overlay, clip-transform (startMs, endMs, preset, transitionMs), and audio-overlay (startMs, endMs, sourceStartMs, volume — lets you drag-trim an audio overlay without removing it). Time shifts on a link-grouped region (e.g. one half of a designed segment) propagate to every peer in the group so the pair stays coherent.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1182,13 +1206,13 @@ const TOOLS = [
 				regionType: {
 					type: "string",
 					description:
-						"zoom | trim | speed | annotation | fx | lower-third | overlay | clip-transform | audio-overlay",
+						"zoom | trim | speed | annotation | fx | overlay | clip-transform | audio-overlay",
 				},
 				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, { 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).",
+						"Fields to update (partial). E.g. { depth: 4 } to change zoom depth, 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" },
 			},
@@ -1843,7 +1867,7 @@ const TOOLS = [
 				slots: {
 					type: "object",
 					description:
-						"Editable values keyed by slot key (see motion_list / the SKILL catalog): text strings, color hex strings, or list arrays. Omitted slots fall back to the template default.",
+						"Editable values keyed by slot key (see motion_list / the SKILL catalog): text strings, color hex strings, or list arrays. An 'image'-typed slot (see its `type` in motion_list) takes an ABSOLUTE FILE PATH to an image — the server stages the file into the render, so you can pass a project-media path or a generated image (e.g. from media_generate_image). Omitted slots fall back to the template default.",
 				},
 				aspectRatio: {
 					type: "string",
@@ -1862,6 +1886,43 @@ const TOOLS = [
 		},
 		command: "motion.generate",
 	},
+	// Video templates ("storyboards") — multi-scene, parameterized videos that
+	// render several templates and concatenate them into one finished clip.
+	{
+		name: "motion_list_storyboards",
+		description:
+			"List the bundled VIDEO templates (storyboards). Unlike single-scene templates (motion_list), a storyboard is a whole short video: an ordered set of scenes plus a `params` brief you fill in once. Returns each storyboard's id, name, audience (youtube|podcaster|course), description, aspectRatios, and `params` (the brief: key, label, type string|color|asset, required, default — color params default to the workspace brand kit via brand.* sentinels). Use a storyboard when the user wants a finished intro/outro/episode-open/lesson-open rather than a single overlay. Render one with motion_generate_storyboard.",
+		inputSchema: { type: "object", properties: {} },
+		command: "motion.list-storyboards",
+	},
+	{
+		name: "motion_generate_storyboard",
+		description:
+			"Render a multi-scene VIDEO template (storyboard) by id. Fill the brief via `params`; missing color params fall back to the workspace brand kit, missing required text params fail fast. The server renders each scene and concatenates them into one MP4. Async — returns { jobId, outputPath, sceneCount }; call job_wait, then pass that jobId as `fromJob` to project_add_motion_graphic. Discover storyboards + their params with motion_list_storyboards.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				storyboardId: {
+					type: "string",
+					description:
+						"Storyboard id from motion_list_storyboards (e.g. youtube-creator-intro, podcast-episode-open, course-lesson-open).",
+				},
+				params: {
+					type: "object",
+					description:
+						"The brief, keyed by param key (see motion_list_storyboards). Text and color values. Omitted color params fall back to the workspace brand kit; omitted required text params cause a fast failure.",
+				},
+				aspectRatio: {
+					type: "string",
+					enum: ["16:9", "9:16", "1:1"],
+					description: "Defaults to the storyboard's first listed aspect.",
+				},
+				outputName: { type: "string", description: "Optional filename stem (no extension)." },
+			},
+			required: ["storyboardId"],
+		},
+		command: "motion.generate-storyboard",
+	},
 	// Custom HTML authoring path is `motion_render_html` (for briefs no
 	// bundled template fits).
 	{
@@ -2016,6 +2077,13 @@ const TOOLS = [
 		inputSchema: { type: "object", properties: {} },
 		command: "asset.list-fx",
 	},
+	{
+		name: "asset_list_transitions",
+		description:
+			"List every bundled transition (id, title, category, durationSeconds). Use the id with project_add_transition, centered on a cut.",
+		inputSchema: { type: "object", properties: {} },
+		command: "asset.list-transitions",
+	},
 	{
 		name: "asset_list_music",
 		description:
@@ -2077,7 +2145,7 @@ const TOOLS = [
 	{
 		name: "export_start",
 		description:
-			"Render the project to MP4 via the same Tier-3 PixiJS pipeline the editor's Export Video button uses (v1.24+ — convergence release). When an editor window is already open on the target project, the agent reuses it. Otherwise the agent spawns a hidden editor window for the duration of the render and closes it after. ASYNC — returns { jobId, outputPath }; call job_wait. Honours every region/style/caption/FX/lower-third/motion-graphic in the project. Video overlays (motion graphics added via project_add_motion_graphic) — opaque MP4 and transparent WebM/VP9+alpha — composite inline in the export pipeline; no extra call needed.",
+			"Render the project to MP4 via the same Tier-3 PixiJS pipeline the editor's Export Video button uses (v1.24+ — convergence release). When an editor window is already open on the target project, the agent reuses it. Otherwise the agent spawns a hidden editor window for the duration of the render and closes it after. ASYNC — returns { jobId, outputPath }; call job_wait. Honours every region/style/caption/FX/motion-graphic in the project. Video overlays (motion graphics added via project_add_motion_graphic) — opaque MP4 and transparent WebM/VP9+alpha — composite inline in the export pipeline; no extra call needed.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2304,7 +2372,7 @@ const TOOLS = [
 const server = new Server(
 	{
 		name: "pandastudio",
-		version: "1.58.0",
+		version: "1.66.0",
 	},
 	{
 		capabilities: {

package/package.json

@@ -1,45 +1,45 @@
 {
-	"name": "@writepanda/mcp",
-	"version": "1.58.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",
-		"mcp",
-		"model-context-protocol",
-		"video-editor",
-		"agent",
-		"cursor",
-		"continue",
-		"cline",
-		"claude-desktop"
-	],
-	"author": "Kamala Kannan Sankarraj",
-	"license": "MIT",
-	"homepage": "https://www.writepanda.ai/cli",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/kamskans/openscreen.git",
-		"directory": "packages/mcp"
-	},
-	"bugs": {
-		"url": "https://github.com/kamskans/openscreen/issues"
-	},
-	"type": "module",
-	"engines": {
-		"node": ">=18"
-	},
-	"bin": {
-		"writepanda-mcp": "./bin/server.mjs"
-	},
-	"files": [
-		"bin",
-		"README.md",
-		"LICENSE"
-	],
-	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.0.4"
-	},
-	"publishConfig": {
-		"access": "public"
-	}
+  "name": "@writepanda/mcp",
+  "version": "1.66.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",
+    "mcp",
+    "model-context-protocol",
+    "video-editor",
+    "agent",
+    "cursor",
+    "continue",
+    "cline",
+    "claude-desktop"
+  ],
+  "author": "Kamala Kannan Sankarraj",
+  "license": "MIT",
+  "homepage": "https://www.writepanda.ai/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kamskans/openscreen.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/kamskans/openscreen/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "writepanda-mcp": "./bin/server.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }