@writepanda/mcp 1.183.0 → 1.191.0

package/bin/server.mjs

@@ -552,6 +552,69 @@ const ANCHOR_END_PROP = { type: "number", description: "Anchor end, SOURCE ms."
 const KEYFRAME_TARGET_DOC =
 	"main = motion region (its target decides fields); overlay: x y scale rotation opacity backdropBlur keyStrength; annotation: x y scale rotation opacity; adjustment: effects, amount, lookIntensity; focus: x y width height roundness feathering blurAmount pixelSize maskOpacity; background-effect: amount strength; mask (regionId = overlay id): x y width height roundness feather expand.";
 
+const MOTION_ELEMENT_TYPES = [
+	"keyword",
+	"chip",
+	"stamp",
+	"count",
+	"steps",
+	"slam",
+	"behind",
+	"lowerThird",
+	"highlight",
+	"endCard",
+	"progress",
+	"iconPop",
+	"frame",
+	"sticker",
+];
+const MOTION_ELEMENT_PROPS = {
+	type: { type: "string", enum: MOTION_ELEMENT_TYPES },
+	content: {
+		type: ["object", "string", "array"],
+		description:
+			'keyword/chip/stamp/slam/behind/highlight { text } (or a bare string); count { value, to?, prefix?, suffix?, label?, decimals? } (value "20-30" = range); steps { items[], cues? (ms offsets from start) }; lowerThird { title, subtitle? }; endCard { lines: [a, b] }; progress { label?, fromMs?, toMs? }; iconPop { emoji } | { icon }; frame { look: viewfinder | selection | corners, label? }; sticker { image: transparent PNG path, label? }. Latin script only.',
+	},
+	atMs: { type: "number", description: "Start, edited ms. Or wordId." },
+	wordId: {
+		type: "string",
+		description: "Start on this transcript word; follows it through cuts.",
+	},
+	offsetMs: { type: "number", description: "Shift from atMs/wordId (may be negative)." },
+	durationMs: { type: "number", description: "Default endWordId, else the type's length." },
+	endWordId: { type: "string", description: "Run to the end of this word." },
+	cueWordIds: {
+		type: "array",
+		items: { type: "string" },
+		description: "steps: one word id per item.",
+	},
+	style: {
+		type: "object",
+		properties: {
+			family: { type: "string", enum: ["bold", "editorial", "clean", "playful", "paper"] },
+			accent: { type: "string" },
+			highlight: { type: "string" },
+			text: { type: "string" },
+			font: { type: "string" },
+			size: { type: "string", enum: ["s", "m", "l", "xl"] },
+			outline: { type: "boolean" },
+		},
+		description: "Default: the brand kit.",
+	},
+	zone: {
+		type: ["string", "object"],
+		description:
+			"auto (clear of the face) | top | upper | center | lower | bottom | { x, y, w? } (% of frame; x,y = centre).",
+	},
+	layer: { type: "string", enum: ["front", "behind"] },
+	sound: {
+		type: "string",
+		enum: ["auto", "none", "pop", "whoosh", "hit", "tick", "bell"],
+		description: "Role for project_compose_soundtrack.",
+	},
+	zIndex: { type: "number" },
+	anchor: { type: "string", enum: ["auto", "free"] },
+};
 const TOOLS = [
 	// ── system + discovery ──────────────────────────────────────────
 	{
@@ -641,7 +704,7 @@ const TOOLS = [
 	{
 		name: "system_set_transcription_language",
 		description:
-			"Set the workspace transcription language. Non-auto uses Whisper, a ~1.1 GB download: tell the user first (system.is-whisper-model-downloaded via pandastudio_call).",
+			"Set the workspace transcription language. English = auto (english/en are saved as auto). Non-auto uses Whisper, a ~1.1 GB download: tell the user first (system.is-whisper-model-downloaded via pandastudio_call).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -649,6 +712,8 @@ const TOOLS = [
 					type: "string",
 					enum: [
 						"auto",
+						"english",
+						"en",
 						"chinese",
 						"japanese",
 						"korean",
@@ -1512,16 +1577,33 @@ const TOOLS = [
 	},
 	{
 		name: "project_add_transition",
-		description: "Place a transition centred on a cut (atMs = a clip boundary).",
+		description:
+			"Place a transition centred on a cut (a clip boundary or a jump cut). kind overlay (fade-black, flash, glitch, torn-paper…) draws a WebM over the cut; kind native (zoom-blur, whip-left, whip-right, whip-up, spin) moves the footage itself (captions/graphics stay put), 350 ms default. Snaps atMs to a cut within snapMs (default 500) and places the transition's default sound.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				transitionId: { type: "string", description: "asset_list_transitions id." },
-				file: { type: "string", description: "Instead of transitionId." },
-				atMs: { type: "number" },
-				durationMs: { type: "number", description: "Default 1000." },
+				transitionId: {
+					type: "string",
+					description: "asset_list_transitions id (overlay or native kind).",
+				},
+				file: { type: "string", description: "Custom overlay WebM, instead of transitionId." },
+				atMs: { type: "number", description: "The cut (edited ms)." },
+				durationMs: {
+					type: "number",
+					description: "Default: the catalog's (1000 overlays, 900 torn-paper, 350 native).",
+				},
+				snapMs: {
+					type: "number",
+					description: "Snap to the nearest cut within this many ms. Default 500; 0 = exact.",
+				},
+				sound: {
+					type: "string",
+					description:
+						"Bundled sound id / path. Default: the transition's defaultSoundId. none = silent.",
+				},
+				soundVolume: { type: "number", description: "0-1." },
 				expectedRevision: { type: "number" },
 			},
 			required: ["atMs"],
@@ -2477,13 +2559,14 @@ const TOOLS = [
 	// ── compose: edit existing regions ─────────────────────────────
 	{
 		name: "project_remove_region",
-		description: "Delete a region by id (editor.*Regions or audioOverlays); linked peers go too.",
+		description:
+			"Delete a region by id (editor.*Regions, motion-element = editor.motionElements, or audioOverlays); linked peers go too.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				regionType: { type: "string", enum: REGION_TYPES },
+				regionType: { type: "string", enum: [...REGION_TYPES, "motion-element"] },
 				regionId: { type: "string" },
 				expectedRevision: { type: "number" },
 			},
@@ -2513,6 +2596,7 @@ const TOOLS = [
 						"spotlight",
 						"motion",
 						"adjustment",
+						"motion-element",
 						"audio-overlay",
 					],
 				},
@@ -2662,12 +2746,14 @@ const TOOLS = [
 	},
 	{
 		name: "project_set_crop",
-		description: "Crop the main video's source frame (0-1 fractions). Default 0,0,1,1 (no crop).",
+		description:
+			"Crop the main video's source frame (0-1 fractions), e.g. to cut baked-in black bars. Without clipId it applies to the project and every clip (a clip's own crop, like auto-reframe's, wins otherwise). Default 0,0,1,1 (no crop).",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
+				clipId: { type: "string", description: "Crop only this clip." },
 				x: { type: "number" },
 				y: { type: "number" },
 				width: { type: "number" },
@@ -3227,13 +3313,14 @@ const TOOLS = [
 	{
 		name: "transcript_transcribe",
 		description:
-			"Transcribe clips with word timestamps. ASYNC: { jobId }, job_wait. Tell the user about result droppedWordEdits[] (fixes that may need redoing).",
+			"Transcribe clips with word timestamps (default: only clips without words). To REDO a transcript (wrong language, bad run) fix the language first, then force: true (all clips) or clipId. Word fixes are re-applied; tell the user about result droppedWordEdits[] (fixes that may need redoing). ASYNC: { jobId }, job_wait.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				clipId: { type: "string" },
+				clipId: { type: "string", description: "Only this clip, even if already transcribed." },
+				force: { type: "boolean", description: "Re-transcribe clips that already have words." },
 			},
 		},
 		command: "transcript.transcribe",
@@ -3422,7 +3509,8 @@ const TOOLS = [
 	},
 	{
 		name: "caption_set_template",
-		description: "Pick a caption template (default glowStack).",
+		description:
+			"Pick a caption template (default glowStack); clears style overrides. Emphasis templates (hormoziEmphasis, tiltedBox, serifItalic, condensedCaps, scriptKeyword) style the IMPORTANT word of each phrase, not the spoken one; emphasis is detected on apply when missing (result.emphasis).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3447,6 +3535,11 @@ const TOOLS = [
 						"matrixDecode",
 						"glitchRgb",
 						"blendDifference",
+						"hormoziEmphasis",
+						"tiltedBox",
+						"serifItalic",
+						"condensedCaps",
+						"scriptKeyword",
 					],
 				},
 				expectedRevision: { type: "number" },
@@ -3458,7 +3551,8 @@ const TOOLS = [
 
 	{
 		name: "caption_set_style",
-		description: "Override caption style fields (template kept); pass only what changes.",
+		description:
+			"Override caption style fields (template kept); pass only what changes. highlightMode emphasis/both detects emphasis words when missing (result.emphasis).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3475,11 +3569,45 @@ const TOOLS = [
 				strokeWidth: { type: "number" },
 				fontSize: { type: "string", description: "e.g. '2.6rem' (1-5rem)." },
 				uppercase: { type: "boolean" },
+				highlightMode: {
+					type: "string",
+					enum: ["spoken", "emphasis", "both"],
+					description: "spoken = word being said; emphasis = key words all group long.",
+				},
+				emphasisColor: { type: "string" },
+				emphasisBackgroundColor: { type: "string", description: "'transparent' = no box." },
+				emphasisScale: { type: "number", description: "0.5-2." },
+				emphasisItalic: { type: "boolean" },
+				emphasisFontFamily: {
+					type: "string",
+					description: "Engine font, e.g. Great Vibes, Playfair Display, Bebas Neue, Anton.",
+				},
+				boxRotation: { type: "number", description: "Box tilt degrees 0-15." },
 				expectedRevision: { type: "number" },
 			},
 		},
 		command: "caption.set-style",
 	},
+	{
+		name: "caption_mark_emphasis",
+		description:
+			"Set the key words emphasis caption styles mark. No wordIds: detect from the speech map (strong moments + numbers; hand marks kept unless reset). wordIds: mark (emphasis true) or unmark (false). Returns { emphasizedWords, words }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				wordIds: { type: "array", items: { type: "string" }, description: "From transcript_get." },
+				emphasis: { type: "boolean", description: "With wordIds; default true." },
+				detect: { type: "boolean" },
+				reset: { type: "boolean", description: "Detection replaces hand marks too." },
+				minGapMs: { type: "number", description: "Default 1200." },
+				everyMs: { type: "number", description: "Default 2500; lower = more words." },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "caption.mark-emphasis",
+	},
 	{
 		name: "caption_move",
 		description:
@@ -3513,14 +3641,20 @@ const TOOLS = [
 	{
 		name: "media_generate_image",
 		description:
-			"Generate one image (Replicate gpt-image-2, needs Replicate connected). Returns { imagePath }. 3:2 for 16:9, 2:3 for 9:16.",
+			"Generate one image on the user's own image connector (auto: Replicate, else Higgsfield; their credits). Returns { imagePath, provider, model, transparent }. transparent=true: trimmed PNG sticker. No connector: code NO_IMAGE_CONNECTOR, so ask the user for their own images. Each call is a paid generation.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				prompt: { type: "string", description: "Keep text out of the image." },
-				aspectRatio: { type: "string", enum: ["1:1", "3:2", "2:3"] },
+				aspectRatio: {
+					type: "string",
+					enum: ["1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16"],
+					description: "Default 3:2. 16:9 / 9:16 for full-frame video stills.",
+				},
 				quality: { type: "string", enum: ["low", "medium", "high"] },
 				referenceImagePath: { type: "string", description: "Style reference (path or URL)." },
+				transparent: { type: "boolean", description: "Background removed (sticker PNG)." },
+				provider: { type: "string", enum: ["auto", "replicate", "higgsfield"] },
 				outputName: { type: "string" },
 			},
 			required: ["prompt"],
@@ -3671,6 +3805,350 @@ const TOOLS = [
 		},
 		command: "media.generate-presenter",
 	},
+	{
+		name: "project_inspect_footage",
+		description:
+			"Import checks before styling camera footage: flat/log (needs a grade), a flat green/blue backdrop (key it), rotation (vertical phone/camera clips). Returns per clip { flat, backdrop, rotation, contrast, blackLevel, saturation, suggestions:[{ why, verb, args }] }; run the suggested verbs.",
+		inputSchema: {
+			type: "object",
+			properties: { id: { type: "string" }, path: { type: "string" }, clipId: { type: "string" } },
+		},
+		command: "project.inspect-footage",
+	},
+	{
+		name: "project_speech_map",
+		description:
+			"The words the speaker STRESSES and where they land on the edited timeline (any language, incl. code-switched speech): measured from the audio (louder, sharp attack, pause before, drawn out) plus numbers and English key terms. Returns { durationMs, moments:[{ atMs, text, phrase, strength 1-3, emphasis, reasons, suggest }] }. Use as cues: zooms on strength 2-3, keyword graphics on the phrase, hits on strength 3. Needs a transcript.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				minGapMs: { type: "number", description: "Default 2500." },
+				everyMs: {
+					type: "number",
+					description:
+						"~one moment per this long. Default 5000; Shorts 3000-4000; long-form 8000-15000.",
+				},
+				words: { type: "boolean", description: "Also return every word's emphasis." },
+			},
+		},
+		command: "project.speech-map",
+	},
+	{
+		name: "project_compose_soundtrack",
+		description:
+			"Score this edit: music + sound design composed FROM THE PROJECT'S OWN TIMELINE (zooms, graphics, pops, cuts, speech, stressed words) and placed under the voice with ducking; takes over zoom/overlay default sounds; replaces the previous score on re-run. Call LAST, after cuts/zooms/graphics. dryRun returns the score for media_compose_soundtrack. Returns { audioPath, scorePath, events, heroMoments, acts, soundsTakenOver, replaced }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				style: { type: "string", enum: ["talking-head", "short", "promo", "calm"] },
+				mood: { type: "string", enum: ["minor", "major"] },
+				bpm: { type: "number" },
+				sfx: { type: "boolean", description: "Default true." },
+				useSpeech: {
+					type: "boolean",
+					description: "Hero hits on the most stressed words. Default true.",
+				},
+				cues: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							atMs: { type: "number" },
+							strength: { type: "number" },
+							label: { type: "string" },
+						},
+						required: ["atMs"],
+					},
+					description: "Extra moments, e.g. a graphic's own cue times.",
+				},
+				musicVolume: { type: "number", description: "0-2. Default by style." },
+				takeOverSounds: { type: "boolean", description: "Default true." },
+				dryRun: { type: "boolean" },
+				seed: { type: "number" },
+			},
+		},
+		command: "project.compose-soundtrack",
+	},
+	// ── native motion elements ──────────────────────────────────────
+	{
+		name: "project_add_motion_element",
+		description:
+			"Native motion element: an editable, word-timed graphic the engine draws (preview = export, no HTML render): keyword headline, chip, stamp, count (number/range rolls up), steps, slam (+ camera kick), behind (word behind the speaker), lowerThird, highlight, endCard, progress, iconPop, frame (viewfinder / selection box / corners around the speaker). Anchor with wordId (follows the word through cuts) or atMs. Brand kit by default. Returns { elementId, element }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				...MOTION_ELEMENT_PROPS,
+				expectedRevision: { type: "number" },
+			},
+			required: ["type", "content"],
+		},
+		command: "project.add-motion-element",
+	},
+	{
+		name: "project_add_motion_elements",
+		description:
+			"Add many native motion elements in one edit (one revision). All or nothing: an invalid one rejects the batch with 'element <i>: <reason>'. Returns { elementIds, elements }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				elements: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: MOTION_ELEMENT_PROPS,
+						required: ["type", "content"],
+					},
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["elements"],
+		},
+		command: "project.add-motion-elements",
+	},
+	{
+		name: "project_update_motion_element",
+		description:
+			"Change a native motion element; pass only what changes. style merges (field null = default); zone/layer/sound/zIndex null = default; atMs/wordId re-anchors and keeps the length. Editing a style-edit element makes it yours (re-runs keep it).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				elementId: { type: "string" },
+				...MOTION_ELEMENT_PROPS,
+				expectedRevision: { type: "number" },
+			},
+			required: ["elementId"],
+		},
+		command: "project.update-motion-element",
+	},
+	{
+		name: "project_remove_motion_element",
+		description: "Remove a native motion element by id.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				elementId: { type: "string" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["elementId"],
+		},
+		command: "project.remove-motion-element",
+	},
+	{
+		name: "project_list_motion_elements",
+		description:
+			"List placed native motion elements (id, type, span, content, style, zone, layer, sound, wordId, origin) with one-line summaries. catalog=true adds every type's content shape and defaults.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				type: { type: "string", enum: MOTION_ELEMENT_TYPES },
+				catalog: { type: "boolean" },
+			},
+		},
+		command: "project.list-motion-elements",
+	},
+	{
+		name: "project_style_edit",
+		description:
+			"Style a talking-head / Short in one call: inspect-footage (applyFixes applies grade/key), speech-map, native motion elements on the stressed moments (numbers → count, strength-3 English statement → slam, other heroes → keyword/stamp, code-switch key terms → chip, first moment → hook, last 4 s → end card, long-form topic turns → lower third) + silent zooms (1.5x/1.25x, 1.8x hero), then compose-soundtrack. paper-cut = the Vox paper-cut look (serif ink on torn paper strips, newsprint backdrop, speaker cut out with a white keyline in the lower half, paper foley, no zooms; look=false keeps your background/framing). Latin text only: for non-Latin speech pass texts { wordId: 'English keyword' } (else zoom only). Re-runs replace only what style-edit placed. Run after cuts. dryRun returns the plan.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				style: {
+					type: "string",
+					enum: ["bold-short", "editorial-long", "clean-tutorial", "paper-cut"],
+				},
+				format: {
+					type: "string",
+					enum: ["short", "long"],
+					description: "Density; default from aspect (9:16 = short).",
+				},
+				applyFixes: { type: "boolean", description: "Apply inspect-footage fixes. Default false." },
+				backdrop: {
+					type: "string",
+					description:
+						"Background behind a keyed-out speaker (applyFixes) and the paper-cut backdrop: wallpaper id, colour or CSS gradient. Default: the style's studio gradient when no background is set; paper-cut uses /wallpapers/paper-cream.jpg.",
+				},
+				look: {
+					type: "boolean",
+					description:
+						"paper-cut only: also set the look (paper backdrop, speaker cutout + white keyline, lower-half framing). Default true.",
+				},
+				texts: {
+					type: "object",
+					additionalProperties: { type: "string" },
+					description: "{ [wordId]: 'English keyword' } overrides.",
+				},
+				endCard: {
+					type: "array",
+					items: { type: "string" },
+					description: "[line1, line2]. Default: hook + hero line.",
+				},
+				accent: { type: "string", description: "Accent colour for every element; default brand." },
+				highlight: { type: "string", description: "Emphasis colour; default brand." },
+				zooms: { type: "boolean", description: "Default true." },
+				score: { type: "boolean", description: "Run compose-soundtrack. Default true." },
+				mood: { type: "string", enum: ["minor", "major"] },
+				dryRun: { type: "boolean" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.style-edit",
+	},
+	{
+		name: "media_compose_soundtrack",
+		description:
+			"Compose + render an original soundtrack (music, beats, SFX) from a score on the SAME timeline as the edit, so hits land on their moments. Synthesized locally: no key, no licensing, ~1 s per 15 s. Plan cues from the edit first, set bpm so cuts land on beats, then place sounds on cues. Returns { audioPath, scorePath, durationMs, lufs, truePeakDb, events, cues, warnings }; place with project_add_audio. Format + recipes: skill reference/soundtrack.md.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				score: {
+					type: "object",
+					description: "The score. Pass score or scorePath.",
+					properties: {
+						duration: { type: "number", description: "Seconds (max 600)." },
+						seed: { type: "number" },
+						cues: {
+							type: "object",
+							description: 'Named moments: { "slam": 3.0, "logo": "slam+9.95" }.',
+							additionalProperties: { type: ["number", "string"] },
+						},
+						events: {
+							type: "array",
+							items: {
+								type: "object",
+								properties: {
+									at: { type: ["number", "string"], description: 'Seconds, a cue, or "cue+0.2".' },
+									sound: {
+										type: "string",
+										enum: [
+											"kick",
+											"snare",
+											"clap",
+											"hat",
+											"openhat",
+											"tick",
+											"click",
+											"blip",
+											"pop",
+											"typing",
+											"whoosh",
+											"riser",
+											"downlifter",
+											"impact",
+											"boom",
+											"subdrop",
+											"shimmer",
+											"bass",
+											"pluck",
+											"pad",
+											"lead",
+											"bell",
+											"keys",
+										],
+									},
+									gain: { type: "number" },
+									pan: { type: "number", description: "-1 left .. 1 right" },
+									dur: { type: "number" },
+									note: { type: ["string", "number"], description: '"A3" or MIDI' },
+									notes: { type: "array", items: { type: ["string", "number"] } },
+									chord: { type: "string", description: '"Am", "Fmaj7"' },
+									from: { type: "number", description: "Sweep start Hz" },
+									to: { type: "number", description: "Sweep end Hz" },
+									bright: { type: "number", description: "0 dark .. 1 bright" },
+									reverb: { type: "number", description: "0..1 send" },
+									repeat: {
+										type: "object",
+										properties: {
+											count: { type: "number" },
+											every: { type: "number" },
+											gainStep: { type: "number" },
+											alternatePan: { type: "boolean" },
+											jitter: { type: "number" },
+										},
+									},
+								},
+								required: ["at", "sound"],
+							},
+						},
+						sections: {
+							type: "array",
+							items: {
+								type: "object",
+								properties: {
+									from: { type: ["number", "string"] },
+									to: { type: ["number", "string"] },
+									bpm: { type: "number" },
+									chords: { type: "array", items: { type: "string" } },
+									chordBeats: { type: "number", description: "Beats per chord, default 4." },
+									drums: {
+										type: "string",
+										enum: ["four-on-floor", "backbeat", "half-time", "breakbeat", "none"],
+									},
+									hats: { type: "string", enum: ["16ths", "8ths", "offbeat", "none"] },
+									bass: { type: "string", enum: ["pulse", "octave", "root", "sustain", "none"] },
+									arp: { type: "string", enum: ["up", "down", "updown", "none"] },
+									arpRate: { type: "string", enum: ["4ths", "8ths", "16ths"] },
+									pad: { type: ["boolean", "number"] },
+									whooshOnChange: { type: "boolean" },
+									melody: {
+										type: "object",
+										properties: {
+											notes: { type: "array", items: { type: ["string", "number", "null"] } },
+											rate: { type: "string", enum: ["4ths", "8ths", "16ths"] },
+											sound: { type: "string", enum: ["pluck", "lead", "bell", "keys"] },
+											gain: { type: "number" },
+											length: { type: "number" },
+											reverb: { type: "number" },
+										},
+									},
+									gain: { type: "number" },
+									mix: {
+										type: "object",
+										description: "Per-part levels 0-2: drums, hats, bass, arp, pad, melody.",
+									},
+								},
+								required: ["from", "to", "bpm"],
+							},
+						},
+						master: {
+							type: "object",
+							properties: {
+								lufs: { type: "number", description: "Default -14." },
+								ceiling: { type: "number", description: "True-peak dBFS, default -1." },
+								fadeIn: { type: "number" },
+								fadeOut: { type: "number" },
+								drive: { type: "number", description: "1 clean .. 4 heavy, default 1.3." },
+								room: { type: "number", description: "Reverb size 0..1." },
+							},
+						},
+					},
+					required: ["duration"],
+				},
+				scorePath: {
+					type: "string",
+					description: "Absolute path to a score JSON (e.g. a previous scorePath).",
+				},
+				name: { type: "string", description: "File name stem." },
+			},
+		},
+		command: "media.compose-soundtrack",
+	},
 	{
 		name: "media_generate_music",
 		description:
@@ -3823,7 +4301,7 @@ const TOOLS = [
 				recipe: {
 					type: "object",
 					description:
-						"{ id?, title, description, category, footage?, aspectRatio?, fields: [{ key, label, type: text|longtext|select|color, default?, options?, required?, help? }], prompt, style?: { aspectRatio?, colorCorrection?, lut?: { preset, intensity? }, background?: { mode, image? }, cameraLayout?, captions?: { enabled, templateId? }, wallpaper? }, checklist: string[] }",
+						"{ id?, title, description, category, footage?, aspectRatio?, fields: [{ key, label, type: text|longtext|select|color|images, default?, options?, required?, help?, minCount?, maxCount?, optional? }], prompt, style?: { aspectRatio?, colorCorrection?, lut?: { preset, intensity? }, background?: { mode, image? }, cameraLayout?, captions?: { enabled, templateId? }, wallpaper? }, checklist: string[] }",
 				},
 			},
 			required: ["recipe"],
@@ -4029,7 +4507,11 @@ const TOOLS = [
 				aspectRatio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
 				width: { type: "number" },
 				height: { type: "number" },
-				durationMs: { type: "number", description: "Default 2500." },
+				durationMs: {
+					type: "number",
+					description:
+						"Omit when the root declares data-duration (that is the length rendered; a mismatch warns). Else default 2500. Max 600000 (10 min).",
+				},
 				frameRate: { type: "number" },
 				outputName: { type: "string" },
 				audioPath: { type: "string", description: "Muxed in (not when transparent)." },
@@ -4054,7 +4536,10 @@ const TOOLS = [
 				aspectRatio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
 				width: { type: "number" },
 				height: { type: "number" },
-				atMs: { type: "number", description: "Max 30000." },
+				atMs: {
+					type: "number",
+					description: "Clamped to the composition's data-duration; result atMs = time captured.",
+				},
 				transparent: { type: "boolean" },
 				assets: ASSETS_PROP,
 				outputName: { type: "string" },
@@ -4129,7 +4614,7 @@ const TOOLS = [
 	{
 		name: "asset_list_transitions",
 		description:
-			"List bundled transitions (id, title, category, durationSeconds) for project_add_transition.",
+			"List bundled transitions (id, title, kind overlay|native, effect, category, durationSeconds, defaultSoundId) for project_add_transition.",
 		inputSchema: { type: "object", properties: {} },
 		command: "asset.list-transitions",
 	},
@@ -4290,7 +4775,7 @@ const TOOLS = [
 	{
 		name: "export_generate_thumbnail",
 		description:
-			"Generate a YouTube thumbnail for an export (Replicate, spends credits). Pass subject + hook, or omit to derive from the transcript. Returns { imagePath }.",
+			"Generate a YouTube thumbnail for an export (user's image connector: Replicate, else Higgsfield; spends their credits). Pass subject + hook, or omit to derive from the transcript. Returns { imagePath }.",
 		inputSchema: {
 			type: "object",
 			properties: {

package/package.json

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