@writepanda/mcp 1.205.0 → 1.210.0

package/bin/server.mjs

@@ -577,7 +577,7 @@ const MOTION_ELEMENT_PROPS = {
 	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? (<=320 chars, wraps), look?: plate|plain|typewriter }; endCard { lines: [a, b] }; progress { label?, fromMs?, toMs? }; iconPop { emoji } | { icon }; frame { look: viewfinder | selection | corners, label? }; sticker { image: transparent PNG path, label? }; ticker { text (one story per line, <=2000 chars), label?, speed? (40-600 px/s) }; credits { title?, entries: [{ role?, name }] | "Role: Name" strings (<=200) }; crawl { title?, text (<=6000 chars), tilt? (0-80), turn? (-60..60) }. Any script, symbols and emoji draw.',
+			'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? (<=320 chars, wraps), look?: plate|plain|typewriter, typeSpeed? (typewriter pace, 5-80 chars/s, default ~22) }; endCard { lines: [a, b] }; progress { label?, fromMs?, toMs? }; iconPop { emoji } | { icon }; frame { look: viewfinder | selection | corners, label? }; sticker { image: transparent PNG path, label? }; ticker { text (one story per line, <=2000 chars), label?, speed? (40-600 px/s) }; credits { title?, entries: [{ role?, name }] | "Role: Name" strings (<=200) }; crawl { title?, text (<=6000 chars), tilt? (0-80), turn? (-60..60) }. Any script, symbols and emoji draw.',
 	},
 	atMs: { type: "number", description: "Start, edited ms. Or wordId." },
 	wordId: {
@@ -627,7 +627,11 @@ const MOTION_ELEMENT_PROPS = {
 		enum: ["auto", "none", "pop", "whoosh", "hit", "tick", "bell"],
 		description: "Role for project_compose_soundtrack.",
 	},
-	zIndex: { type: "number" },
+	zIndex: {
+		type: "number",
+		description:
+			"Stack order, higher on top (default 0). Front elements share one stack with media overlays and annotations at group base + zIndex (B-roll 0, overlays 1000, annotations 2000, front elements 3000), so by default they draw over both; -2500 drops one under the default overlays.",
+	},
 	anchor: { type: "string", enum: ["auto", "free"] },
 };
 const TOOLS = [
@@ -635,7 +639,7 @@ const TOOLS = [
 	{
 		name: "system_status",
 		description:
-			"App version and license; automationGated true = trial expired, every other tool fails; license.socialPublishing.allowed false = the plan has no Instagram/TikTok/social publishing (Creator, Team, Pro only). Call first.",
+			"App version and license; automationGated true = trial expired, or the Solo plan (license.agentEditing.allowed false: no agent editing, relay license.agentEditing.message to the user), and every other tool fails; license.socialPublishing.allowed false = the plan has no Instagram/TikTok/social publishing (Creator, Team, Pro only); license.exportQuality.allowed = the export_start qualities that work (free trial: draft 720p only; standard/high/ultra need a license). Call first.",
 		inputSchema: { type: "object", properties: {} },
 		command: "system.status",
 	},
@@ -725,7 +729,7 @@ const TOOLS = [
 	{
 		name: "system_get_transcription_language",
 		description:
-			"Workspace transcription language (auto = Parakeet, English + 25 European languages).",
+			"Workspace transcription language. auto = Parakeet TDT v3, which detects the language itself across 25 languages, English included: Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian. Anything else names a Whisper language.",
 		inputSchema: { type: "object", properties: {} },
 		command: "system.get-transcription-language",
 	},
@@ -752,7 +756,7 @@ const TOOLS = [
 	{
 		name: "system_set_transcription_language",
 		description:
-			"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).",
+			"Set the workspace transcription language. auto = Parakeet TDT v3, which detects the language itself across 25 languages, English included: Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian. For any of those (e.g. Romanian) use auto; their names are accepted and saved as auto. The other values use Whisper, a ~1.1 GB download: tell the user first (system.is-whisper-model-downloaded via pandastudio_call).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -762,6 +766,30 @@ const TOOLS = [
 						"auto",
 						"english",
 						"en",
+						"bulgarian",
+						"croatian",
+						"czech",
+						"danish",
+						"dutch",
+						"estonian",
+						"finnish",
+						"french",
+						"german",
+						"greek",
+						"hungarian",
+						"italian",
+						"latvian",
+						"lithuanian",
+						"maltese",
+						"polish",
+						"portuguese",
+						"romanian",
+						"russian",
+						"slovak",
+						"slovenian",
+						"spanish",
+						"swedish",
+						"ukrainian",
 						"chinese",
 						"japanese",
 						"korean",
@@ -1048,8 +1076,14 @@ const TOOLS = [
 	},
 	{
 		name: "youtube_connect",
-		description: "Connect a YouTube account via browser sign-in (only when the user asks).",
-		inputSchema: { type: "object", properties: {} },
+		description:
+			"Connect a YouTube account via browser sign-in (only when the user asks). Pass email to reconnect an existing account. permissionIssue set = the user unticked a Google permission: relay its message.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				email: { type: "string", description: "Reconnect: that account's email." },
+			},
+		},
 		command: "youtube.connect",
 	},
 	{
@@ -1065,13 +1099,15 @@ const TOOLS = [
 	},
 	{
 		name: "youtube_list_accounts",
-		description: "Connected YouTube accounts and channels (pick before export_publish_youtube).",
+		description:
+			"Connected YouTube accounts and channels (pick before export_publish_youtube). issues[] = accounts missing a Google permission (code youtube_permission_missing): relay message, follow howToFix (the user reconnects in Settings > YouTube, leaving every box ticked; you can't do the sign-in).",
 		inputSchema: { type: "object", properties: {} },
 		command: "youtube.list-accounts",
 	},
 	{
 		name: "youtube_list_channels",
-		description: "Refresh an account's channel list from YouTube (bypasses cache).",
+		description:
+			"Refresh an account's channel list from YouTube (bypasses cache). Error code youtube_permission_missing = channel permission unticked on Google's screen: relay message, follow howToFix; canStillPublish true = publish without channelId.",
 		inputSchema: {
 			type: "object",
 			properties: { accountId: { type: "string" } },
@@ -1082,7 +1118,7 @@ const TOOLS = [
 	{
 		name: "export_publish_youtube",
 		description:
-			"Publish an export entry to YouTube. Slow. Check the entry's youtubeVideoId before republishing. Returns { videoUrl }.",
+			"Publish an export entry to YouTube. Slow. Check the entry's youtubeVideoId before republishing. channelId optional (uploads go to the account's own channel; omit when channels can't be listed). Error code youtube_permission_missing: relay message, follow howToFix. Returns { videoUrl, channelId }.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1096,7 +1132,7 @@ const TOOLS = [
 				privacyStatus: { type: "string", enum: ["public", "unlisted", "private"] },
 				setThumbnail: { type: "boolean" },
 			},
-			required: ["id", "accountId", "channelId", "title"],
+			required: ["id", "accountId", "title"],
 		},
 		command: "export.publish-youtube",
 	},
@@ -1300,7 +1336,8 @@ const TOOLS = [
 	},
 	{
 		name: "project_current",
-		description: "The project open in the editor, or null.",
+		description:
+			"The project open in the editor, or null, plus the editor's LIVE playhead read at call time: playhead { ms, timeBase: 'edited', durationMs, inCut, playing } (null + playheadNote when unavailable). playhead.ms is EDITED (output) ms, what add-* atMs takes. Call it when the user says 'here' / 'at the playhead' / 'now': the chat context's playhead is from when the message was sent.",
 		inputSchema: { type: "object", properties: {} },
 		command: "project.current",
 	},
@@ -1379,7 +1416,7 @@ const TOOLS = [
 	{
 		name: "project_add_clip",
 		description:
-			"Append or insert a video clip, or a still image shown for durationMs, on the main track (later content moves with it). Mid-recording: project_split_clip, then atIndex = rightClipIndex.",
+			"Append or insert a video clip, or a still image shown for durationMs, on the main track (later content moves with it). atMs (edited time) inserts at that moment, splitting the clip under it; add replaceToMs to replace [atMs, replaceToMs) with the clip (e.g. a re-recorded take).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1390,6 +1427,14 @@ const TOOLS = [
 				fill: { type: "boolean", description: "Images: cover the frame (default true)." },
 				webcam: { type: "string", description: "Guest source: a two-speaker podcast clip." },
 				atIndex: { type: "number", description: "0-based; omit = append." },
+				atMs: {
+					type: "number",
+					description: "Insert at this edited ms (splits the clip there; not with atIndex).",
+				},
+				replaceToMs: {
+					type: "number",
+					description: "With atMs: cut [atMs, replaceToMs) (a trim) and put the clip there.",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["media"],
@@ -1432,6 +1477,66 @@ const TOOLS = [
 		},
 		command: "project.add-podcast-clip",
 	},
+	{
+		name: "podcast_open_host",
+		description: "Open or focus the live podcast host window. Call podcast_status for the session code and guest link once it loads.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sessionCode: { type: "string", description: "Resume an existing session." },
+				projectPath: { type: "string", description: "Matching podcast project when resuming." },
+			},
+		},
+		command: "podcast.open-host",
+	},
+	...[
+		["status", "Read the live podcast session code, guest link, participants, recording, and sharing state."],
+		["start-recording", "Start recording the host and signal connected guests to record. Returns once recording has really started; fails with the reason otherwise."],
+		["stop-recording", "Stop recording and finalize podcast media. Check podcast_status for finalization and guest uploads."],
+		["start-screen-share", "Open the desktop picker to share and record the host screen during a podcast. Waits for the host to choose; fails if the picker is cancelled or capture fails."],
+		["stop-screen-share", "Stop and finalize the host's podcast screen share."],
+		["open-in-editor", "Open the finished podcast in the editor when guest media has arrived."],
+	].map(([noun, description]) => ({
+		name: `podcast_${noun.replaceAll("-", "_")}`,
+		description,
+		inputSchema: { type: "object", properties: {} },
+		command: `podcast.${noun}`,
+	})),
+	{
+		name: "project_set_podcast_source_crop",
+		description:
+			"Frame one podcast camera or screen-share source independently. Use source=host|guest|guest-2|guest-3|share:0; normalized x,y,width,height. 0,0,1,1 resets the crop. Preview and export use the same framing.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string" },
+				source: { type: "string", description: "host, guest, guest-2, guest-3, or share:<index>." },
+				x: { type: "number", description: "Left edge, 0-1." },
+				y: { type: "number", description: "Top edge, 0-1." },
+				width: { type: "number", description: "Crop width, >0 to 1." },
+				height: { type: "number", description: "Crop height, >0 to 1." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["clipId", "source", "x", "y", "width", "height"],
+		},
+		command: "project.set-podcast-source-crop",
+	},
+	{
+		name: "project_list_podcast_screen_shares",
+		description:
+			"List the screen-share intervals shown on the podcast editor timeline. Returns speaker, clip-local and merged-source timing, edited timing after trims/speed, and whether each interval is visible. Read-only.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string", description: "Optional podcast clip filter." },
+			},
+		},
+		command: "project.list-podcast-screen-shares",
+	},
 	{
 		name: "project_set_participant_offset",
 		description: "Nudge one guest's A/V sync on a podcast composite (host is the reference).",
@@ -1560,7 +1665,7 @@ const TOOLS = [
 	{
 		name: "project_add_designed_segment",
 		description:
-			"Designed segment: host live on one half, a graphic panel on the other, in one call. The panel is a full-frame transparent render with the camera's half left empty (skill 'Designed segments').",
+			"Designed segment: host live on one half, a graphic panel on the other, in one call. The panel is a full-frame transparent render with the camera's half left empty (skill_read file='motion-templates' section='designed segments').",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2922,7 +3027,7 @@ const TOOLS = [
 	{
 		name: "project_update_region",
 		description:
-			"Patch a region; unspecified fields are kept. Patchable: zoom (depth, focusX, focusY, focusMode static|auto), trim / speed (startMs, endMs, speed, rampIn, rampOut, preservePitch, freezeMs, reverse, reverseAudio), fx (atMs, durationMs, opacity, blendMode, speed), annotation, overlay (x, y, width, height in canvas %, layer, opacity, blendMode, muted, volume, loop, motionBlur), adjustment (startMs, endMs, blendMode), motion (motionBlur), clip-transform (startMs, endMs, preset, transitionMs, easing, bezier), background-effect (as project_add_background_effect), audio-overlay (startMs, endMs, sourceStartMs, volume 0-2, fadeIn, fadeOut).",
+			"Patch a region; unspecified fields are kept. Patchable: zoom (depth, focusX, focusY, focusMode static|auto), trim / speed (startMs, endMs, speed, rampIn, rampOut, preservePitch, freezeMs, reverse, reverseAudio), fx (atMs, durationMs, opacity, blendMode, speed, zIndex), annotation (zIndex), overlay (x, y, width, height in canvas %, layer, opacity, blendMode, muted, volume, loop, motionBlur, zIndex), adjustment (startMs, endMs, blendMode), motion (motionBlur), clip-transform (startMs, endMs, preset, transitionMs, easing, bezier), background-effect (as project_add_background_effect), audio-overlay (startMs, endMs, sourceStartMs, volume 0-2, fadeIn, fadeOut).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2931,7 +3036,11 @@ const TOOLS = [
 				path: { type: "string" },
 				regionType: { type: "string", enum: REGION_TYPES },
 				regionId: { type: "string" },
-				patch: { type: "object", description: "e.g. { depth: 4 }; null clears a value." },
+				patch: {
+					type: "object",
+					description:
+						"e.g. { depth: 4 }; null clears a value. zIndex (overlay / annotation / fx): stack order, higher on top; overlays, annotations and front motion elements share one stack at group base + zIndex (B-roll 0, overlays 1000, annotations 2000, motion elements 3000).",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["regionType", "regionId", "patch"],
@@ -3140,13 +3249,19 @@ const TOOLS = [
 	},
 	{
 		name: "project_set_export_settings",
-		description: "Project export defaults (Export dialog and export_start).",
+		description:
+			"Project export defaults (Export dialog and export_start). quality good and source need a license: a free trial gets quality_requires_license, use medium.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				quality: { type: "string", enum: ["medium", "good", "source"] },
+				quality: {
+					type: "string",
+					enum: ["medium", "good", "source"],
+					description:
+						"medium 720p, good 1080p, source = source resolution (good/source license only).",
+				},
 				format: { type: "string", enum: ["mp4"] },
 				normalizeLoudness: {
 					type: ["boolean", "string"],
@@ -3574,7 +3689,7 @@ const TOOLS = [
 	{
 		name: "transcript_transcribe",
 		description:
-			"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.",
+			"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). Each clip is transcribed only over the part it plays (head trim to out-point, e.g. one half of a split; result transcribedRanges[]). ASYNC: { jobId }, job_wait.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4520,6 +4635,24 @@ const TOOLS = [
 		},
 		command: "recipe.list",
 	},
+	{
+		name: "recipe_prepare_reference",
+		description:
+			"Prepare evidence for learning a reference video's editing style, without editing any project. Async job: whole-video contact sheets, dense motion samples, transition candidates and mixed-audio excerpts. Inspect the evidence and save a portable reference-specific recipe; do not assume generic effects or exact source sound files.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				file: {
+					type: "string",
+					description: "Absolute local video path (download links with media_download_url first).",
+				},
+				title: { type: "string" },
+				sourceUrl: { type: "string" },
+			},
+			required: ["file"],
+		},
+		command: "recipe.prepare-reference",
+	},
 	{
 		name: "recipe_pick",
 		description:
@@ -4732,7 +4865,8 @@ const TOOLS = [
 	},
 	{
 		name: "motion_craft",
-		description: "Launch / promo motion craft library: no id lists topics; id returns the doc.",
+		description:
+			"Launch / promo film craft library (story arcs, blueprints, GSAP rules, design presets): no id lists topics; id returns the doc. An unknown id fails with the closest ids and every valid id. Not the custom motion-graphic HTML contract: that is skill_read section='custom motion graphics'.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4782,7 +4916,7 @@ const TOOLS = [
 	{
 		name: "motion_render_html",
 		description:
-			"Render custom HTML to video when no template fits. Contract (skill 'Custom motion graphics'): a paused GSAP timeline at window.__timelines[<data-composition-id>] and a root with data-composition-id / width / height / duration. Lint and STATIC_RENDER failures must be fixed, never placed. ASYNC: { jobId }.",
+			"Render custom HTML to video when no template fits. Contract (skill_read section='custom motion graphics'; render details in skill_read file='custom-html'): a paused GSAP timeline at window.__timelines[<data-composition-id>] and a root with data-composition-id / width / height / duration. Lint and STATIC_RENDER failures must be fixed, never placed. ASYNC: { jobId }.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4862,6 +4996,44 @@ const TOOLS = [
 	},
 
 	// ── assets ──────────────────────────────────────────────────────
+	{
+		name: "asset_list_sound_patterns",
+		description:
+			"List shared motion sound recipes: counted entrances, scroll ratchets, slides, swipes and presses. Use asset_plan_sound_pattern with actual animation timings.",
+		inputSchema: { type: "object", properties: { query: { type: "string" } } },
+		command: "asset.list-sound-patterns",
+	},
+	{
+		name: "asset_plan_sound_pattern",
+		description:
+			"Plan motion-synced sounds without writing a project. Returns cues for project_add_sound_cues; use a unique group per animation. One cue per actual event, variant rotation, quiet starting gain, tails bounded by settle. Preview below narration.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				pattern: { type: "string", description: "Id from asset_list_sound_patterns." },
+				atMs: { type: "integer", minimum: 0, description: "Edited-timeline motion start." },
+				endMs: { type: "integer", description: "Edited-timeline motion end/settle." },
+				eventOffsetsMs: {
+					type: "array",
+					items: { type: "integer", minimum: 0 },
+					minItems: 1,
+					maxItems: 500,
+					description:
+						"Actual entrance/crossing/gesture offsets relative to atMs; strictly increasing. Follow easing, not an assumed uniform stagger.",
+				},
+				volume: { type: "number", minimum: 0, maximum: 2 },
+				sounds: {
+					type: "array",
+					items: { type: "string" },
+					minItems: 1,
+					maxItems: 500,
+					description: "Optional alternate ids/paths, rotated.",
+				},
+			},
+			required: ["pattern", "atMs", "endMs", "eventOffsetsMs"],
+		},
+		command: "asset.plan-sound-pattern",
+	},
 	{
 		name: "asset_list_emoji",
 		description: "List animated emoji for project_add_emoji.",
@@ -4985,14 +5157,19 @@ const TOOLS = [
 	{
 		name: "export_start",
 		description:
-			"Render the project to MP4. ASYNC: { jobId, outputPath }; job_wait. Tell the user any warning and the result's loudness before / after.",
+			"Render the project to MP4. ASYNC: { jobId, outputPath, quality }; job_wait. Tell the user any warning and the result's loudness before / after. Free trial: draft (720p) only (system_status license.exportQuality); standard/high/ultra fail with quality_requires_license.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
 				outputPath: { type: "string" },
-				quality: { type: "string", enum: ["draft", "standard", "high", "ultra"] },
+				quality: {
+					type: "string",
+					enum: ["draft", "standard", "high", "ultra"],
+					description:
+						"draft 720p, standard 1080p, high/ultra source resolution (standard and up: license only). Omit = high, or draft on a trial.",
+				},
 				normalizeLoudness: {
 					type: ["boolean", "string"],
 					description: "streaming / podcast / off; omit = project setting.",
@@ -5107,7 +5284,7 @@ const TOOLS = [
 	{
 		name: "clips_export",
 		description:
-			"Export a clip set's finished clips to MP4 (all, or clipIds) into Movies/PandaStudio Clips/<video>/. Async: returns { jobId, outputDir }; job_wait for { exported[] }.",
+			"Export a clip set's finished clips to MP4 (all, or clipIds) into Movies/PandaStudio Clips/<video>/, at standard quality (1080p; 720p on a free trial). Async: returns { jobId, outputDir }; job_wait for { exported[] }.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -5425,6 +5602,8 @@ const INSTRUCTIONS = `PandaStudio is a desktop video editor; these tools drive t
 
 Start with system_status. Unknown arguments are rejected. Verbs without a tool of their own (system_list_commands) go through pandastudio_call.
 
+Read-only tools (project_read, transcript_get / _search / _find_issues, audio_probe, project_render_frame / _render_sheet, timeline_*, ...) use the project open in the editor when you pass no id or path; edits always need the id.
+
 Before an editing pass, read the skill's "Which tool for which moment" section (skill_read section="Which tool for which moment").
 
 "Edit my video" / "make this a Short" with no specifics = this pipeline, in order. Confirm scope once ("full polish, or just part of it?"), then run it all:

package/package.json

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