@writepanda/mcp 1.9.5 → 1.11.1

package/README.md

@@ -48,17 +48,20 @@ After adding, restart your client. The MCP server auto-launches PandaStudio if i
 
 ## What the agent gets
 
-30+ tools covering the full PandaStudio editorial surface:
+55 tools covering the full PandaStudio editorial surface — complete UI parity:
 
 | Category | Tools |
 |---|---|
 | Discovery | `system_status`, `system_list_commands` |
-| Project lifecycle | `project_list`, `project_show`, `project_read`, `project_new`, `project_open` |
-| Composition | `project_add_clip`, `project_add_motion_graphic`, `project_add_fx`, `project_add_lower_third`, `project_add_zoom`, `project_add_trim`, `project_add_speed` |
-| Transcript editing | `transcript_transcribe`, `transcript_get`, `transcript_delete_words`, `transcript_remove_fillers`, `transcript_search` |
+| Project lifecycle | `project_list`, `project_show`, `project_read`, `project_new`, `project_open`, `project_save`, `project_delete` |
+| Clips | `project_add_clip`, `project_remove_clip`, `project_split_clip` |
+| Composition | `project_add_motion_graphic`, `project_add_fx`, `project_add_lower_third`, `project_add_zoom`, `project_add_trim`, `project_add_speed`, `project_add_annotation` |
+| Region editing | `project_remove_region`, `project_update_region` |
+| Canvas & style | `project_set_aspect_ratio`, `project_set_wallpaper`, `project_set_style`, `project_set_crop`, `project_set_webcam_layout`, `project_set_export_settings` |
+| Transcript editing | `transcript_transcribe`, `transcript_get`, `transcript_delete_words`, `transcript_remove_fillers`, `transcript_search`, `transcript_find_replace`, `transcript_remove_silences` |
 | Audio | `audio_clean` (DeepFilter denoising) |
-| Captions | `caption_toggle`, `caption_set_template` |
-| Motion graphics | `motion_list`, `motion_themes`, `motion_generate` |
+| Captions | `caption_toggle`, `caption_set_template`, `caption_set_style` |
+| Motion graphics | `motion_list`, `motion_themes`, `motion_generate`, `motion_render_html` |
 | Assets | `asset_list_sounds`, `asset_list_fx` |
 | AI metadata | `llm_generate_title`, `llm_generate_description`, `llm_generate_timestamps` |
 | Export | `export_start`, `export_list` |

package/bin/server.mjs

@@ -187,7 +187,7 @@ const TOOLS = [
 	{
 		name: "project_read",
 		description:
-			"Read a project's full JSON. Returns { path, project }. Pass `project.revision` back as `expectedRevision` on subsequent writes for conflict-safe edits.",
+			"Read a project's full JSON. Returns { path, project, clipStates }. `clipStates` is a per-clip summary: { clipId, mediaPath, durationMs, transcribed, wordCount, audioCleaned, cleanedAudioPath? } — use it to decide whether to call transcript_transcribe or audio_clean before editing. Pass `project.revision` back as `expectedRevision` on subsequent writes for conflict-safe edits.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -232,13 +232,19 @@ const TOOLS = [
 	// ── compose: clips, motion graphics, FX, lower-thirds ──────────
 	{
 		name: "project_add_clip",
-		description: "Append a video clip to the project's main track. Probes duration via FFmpeg.",
+		description:
+			"Append (or insert) a video clip into the project's main track. Probes duration via FFmpeg.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
 				media: { type: "string", description: "Absolute path to video file" },
+				atIndex: {
+					type: "number",
+					description:
+						"Insert before this zero-based clip index. Omit to append at the end.",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["media"],
@@ -301,7 +307,18 @@ const TOOLS = [
 					description:
 						"name-bar | slash-reveal | center-stack | minimal-underline | box-reveal | corner-brackets | border-frame | split-horizontal",
 				},
-				accentColor: { type: "string" },
+				accentColor: { type: "string", description: "Hex accent/background color" },
+				textColor: { type: "string", description: "Hex text color. Default #ffffff" },
+				backgroundColor: {
+					type: "string",
+					description: "Hex background fill. Default matches accentColor",
+				},
+				backgroundRadius: {
+					type: "number",
+					description: "Corner radius in pixels. Default 8",
+				},
+				fontSize: { type: "number", description: "Primary text font size in px. Default 28" },
+				fontFamily: { type: "string", description: "CSS font family name. Default Inter" },
 				expectedRevision: { type: "number" },
 			},
 			required: ["content", "atMs"],
@@ -364,6 +381,309 @@ const TOOLS = [
 		command: "project.add-speed",
 	},
 
+	{
+		name: "project_add_annotation",
+		description:
+			"Drop a text or figure annotation overlay on the canvas for a given time range. Position and size are in percent (0-100) of the canvas dimensions.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				startMs: { type: "number" },
+				endMs: { type: "number" },
+				type: {
+					type: "string",
+					description: "text | figure",
+				},
+				text: { type: "string", description: "Required when type is 'text'" },
+				x: { type: "number", description: "Horizontal center, percent 0-100. Default 50." },
+				y: { type: "number", description: "Vertical center, percent 0-100. Default 50." },
+				width: { type: "number", description: "Width, percent 0-100. Default 30." },
+				height: { type: "number", description: "Height, percent 0-100. Default 20." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["startMs", "endMs", "type"],
+		},
+		command: "project.add-annotation",
+	},
+
+	// ── project lifecycle (extended) ───────────────────────────────
+	{
+		name: "project_save",
+		description:
+			"Overwrite a project with the full JSON you supply. Use this when you've built or mutated a project object client-side and want to persist it. Always pass `expectedRevision` (the revision you read) — the server will reject the write if a concurrent edit happened between your read and save, returning { ok: false, details: { code: 'revision_conflict' } }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				project: { type: "object", description: "Full project JSON to persist" },
+				expectedRevision: {
+					type: "number",
+					description: "Revision from your last project_read. Strongly recommended.",
+				},
+			},
+			required: ["project"],
+		},
+		command: "project.save",
+	},
+	{
+		name: "project_delete",
+		description:
+			"Permanently delete a project file from disk. There is no trash — this is irreversible. Use project_list to confirm the id before deleting.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+			},
+		},
+		command: "project.delete",
+	},
+	{
+		name: "project_remove_clip",
+		description:
+			"Remove a clip from the main track by its clip id. Use project_read → clipStates to find clip ids. All regions whose time falls within the removed clip are also removed.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: {
+					type: "string",
+					description: "Clip id to remove (e.g. clip-1). From clipStates in project_read.",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["clipId"],
+		},
+		command: "project.remove-clip",
+	},
+	{
+		name: "project_split_clip",
+		description:
+			"Split a clip in two at a position in source time (milliseconds from the start of that clip). Produces two clips: the portion before the split point and the portion after. Useful for inserting a motion graphic between two halves of a recording.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string", description: "Clip to split" },
+				atSourceMs: {
+					type: "number",
+					description: "Split position in milliseconds from the clip's own start (source time)",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["clipId", "atSourceMs"],
+		},
+		command: "project.split-clip",
+	},
+
+	// ── compose: edit existing regions ─────────────────────────────
+	{
+		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.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				regionType: {
+					type: "string",
+					description: "zoom | trim | speed | annotation | fx | lower-third | overlay",
+				},
+				regionId: { type: "string", description: "UUID of the region to delete" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["regionType", "regionId"],
+		},
+		command: "project.remove-region",
+	},
+	{
+		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.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				regionType: {
+					type: "string",
+					description: "zoom | trim | speed | annotation | fx | lower-third | overlay",
+				},
+				regionId: { type: "string", description: "UUID 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.",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["regionType", "regionId", "patch"],
+		},
+		command: "project.update-region",
+	},
+
+	// ── compose: webcam + crop + export settings ────────────────────
+	{
+		name: "project_set_webcam_layout",
+		description:
+			"Set the webcam layout preset and optional position/scale for the current project. Use 'none' to hide the webcam overlay entirely.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				preset: {
+					type: "string",
+					description:
+						"picture-in-picture | vertical-stack | side-by-side | none. 'none' hides the webcam.",
+				},
+				cx: {
+					type: "number",
+					description:
+						"Horizontal center of the webcam overlay, normalised 0-1. Only for picture-in-picture.",
+				},
+				cy: {
+					type: "number",
+					description:
+						"Vertical center of the webcam overlay, normalised 0-1. Only for picture-in-picture.",
+				},
+				scale: {
+					type: "number",
+					description: "Size multiplier for the webcam overlay. Default 1.0.",
+				},
+				cropX: { type: "number", description: "Webcam crop left edge, normalised 0-1." },
+				cropY: { type: "number", description: "Webcam crop top edge, normalised 0-1." },
+				cropWidth: { type: "number", description: "Webcam crop width, normalised 0-1." },
+				cropHeight: { type: "number", description: "Webcam crop height, normalised 0-1." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["preset"],
+		},
+		command: "project.set-webcam-layout",
+	},
+	{
+		name: "project_set_crop",
+		description:
+			"Set the main video crop region for the project. All values are normalised 0-1 relative to the source frame dimensions. Default is { x:0, y:0, width:1, height:1 } (no crop).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				x: { type: "number", description: "Left edge, normalised 0-1" },
+				y: { type: "number", description: "Top edge, normalised 0-1" },
+				width: { type: "number", description: "Crop width, normalised 0-1" },
+				height: { type: "number", description: "Crop height, normalised 0-1" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["x", "y", "width", "height"],
+		},
+		command: "project.set-crop",
+	},
+	{
+		name: "project_set_export_settings",
+		description:
+			"Pre-configure the project's export defaults (quality, format, resolution). These are the settings the Export dialog opens with — they don't affect the CLI export_start quality flag.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				quality: {
+					type: "string",
+					description: "medium | good | source. Controls CRF/bitrate preset.",
+				},
+				format: {
+					type: "string",
+					description: "mp4 | webm | gif. Default mp4.",
+				},
+				resolution: {
+					type: "string",
+					description:
+						"Output resolution: 4k | 1080p | 720p | 480p | source. Default source.",
+				},
+				gifFrameRate: {
+					type: "number",
+					description: "GIF frame rate (fps). Only used when format is gif. Default 15.",
+				},
+				gifSize: {
+					type: "string",
+					description:
+						"GIF size preset: small | medium | large. Only used when format is gif.",
+				},
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.set-export-settings",
+	},
+
+	{
+		name: "project_set_aspect_ratio",
+		description:
+			"Change the project's output aspect ratio. Affects the canvas size and how the video is cropped/letterboxed on export. Pick based on the target platform: 16:9 for YouTube/desktop, 9:16 for Shorts/Reels/TikTok, 1:1 for Instagram feed.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				ratio: {
+					type: "string",
+					description: "16:9 | 9:16 | 1:1 | 4:3 | 3:4",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["ratio"],
+		},
+		command: "project.set-aspect-ratio",
+	},
+	{
+		name: "project_set_wallpaper",
+		description:
+			"Set the project's background wallpaper. Pass a bundled wallpaper id (e.g. 'gradient-blue', 'dark-mesh') or 'none' to remove the background. The available wallpaper ids match the filenames in the app's /public/wallpapers/ directory.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				wallpaper: {
+					type: "string",
+					description: "Bundled wallpaper id or 'none' to remove background",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["wallpaper"],
+		},
+		command: "project.set-wallpaper",
+	},
+	{
+		name: "project_set_style",
+		description:
+			"Adjust the project's cinematic framing style: padding around the recording (0-200), drop shadow intensity (0-100), border radius (0-100), motion blur amount (0-100), and whether to show blur behind the recording. Pass only the fields you want to change — others are left as-is.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				padding: { type: "number", description: "Padding around the recording in px. 0-200." },
+				shadowIntensity: { type: "number", description: "Drop shadow strength. 0-100." },
+				borderRadius: { type: "number", description: "Corner rounding. 0-100." },
+				motionBlurAmount: { type: "number", description: "Motion blur strength. 0-100." },
+				showBlur: {
+					type: "boolean",
+					description: "Whether to show a blurred background behind the recording.",
+				},
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.set-style",
+	},
+
 	// ── transcript-based editing ────────────────────────────────────
 	{
 		name: "transcript_transcribe",
@@ -442,6 +762,41 @@ const TOOLS = [
 		},
 		command: "transcript.search",
 	},
+	{
+		name: "transcript_find_replace",
+		description:
+			"Find the first occurrence of a phrase in the transcript and replace it with new text. Useful for correcting mis-transcribed names, technical terms, or brand names without re-transcribing. Returns { matched, replacements } — matched is false if the phrase wasn't found.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				find: { type: "string", description: "Phrase to search for (case-insensitive)" },
+				replace: { type: "string", description: "Replacement text (replaces the whole phrase)" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["find", "replace"],
+		},
+		command: "transcript.find-replace",
+	},
+	{
+		name: "transcript_remove_silences",
+		description:
+			"Detect and trim silent gaps in the recording — leading silence before the first word, trailing silence after the last word, and inter-word gaps longer than `thresholdMs`. Bulk-creates trim regions. Returns { removed, totalTrimmedMs }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				thresholdMs: {
+					type: "number",
+					description: "Gaps longer than this are trimmed. Default 700ms.",
+				},
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "transcript.remove-silences",
+	},
 
 	// ── audio ───────────────────────────────────────────────────────
 	{
@@ -492,6 +847,39 @@ const TOOLS = [
 		command: "caption.set-template",
 	},
 
+	{
+		name: "caption_set_style",
+		description:
+			"Override specific style properties of the caption overlay without changing the template. All fields are optional — pass only what you want to change. positionY controls vertical placement (0=top, 100=bottom, default 85). fontSize accepts CSS values like '28px' or '1.5em'.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				wordsPerLine: {
+					type: "number",
+					description: "Max words shown at once. Default varies by template.",
+				},
+				positionY: { type: "number", description: "Vertical position 0-100. Default 85." },
+				color: { type: "string", description: "Caption text color (hex/CSS)" },
+				backgroundColor: { type: "string", description: "Caption background color" },
+				highlightColor: {
+					type: "string",
+					description: "Color of the currently-spoken word highlight",
+				},
+				highlightBackgroundColor: {
+					type: "string",
+					description: "Background of the currently-spoken word",
+				},
+				strokeColor: { type: "string", description: "Text stroke/outline color" },
+				strokeWidth: { type: "number", description: "Text stroke width in px" },
+				fontSize: { type: "string", description: "CSS font-size value, e.g. '28px'" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "caption.set-style",
+	},
+
 	// ── motion graphics ─────────────────────────────────────────────
 	{
 		name: "motion_list",
@@ -719,7 +1107,7 @@ const TOOLS = [
 const server = new Server(
 	{
 		name: "pandastudio",
-		version: "1.9.5",
+		version: "1.11.0",
 	},
 	{
 		capabilities: {

package/package.json

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