@writepanda/mcp 1.207.0 → 1.210.0

package/bin/server.mjs

@@ -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, 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). 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",
 	},
@@ -1380,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: {
@@ -1391,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"],
@@ -1433,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).",
@@ -2923,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: {
@@ -2932,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"],
@@ -3141,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"],
@@ -3575,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: {
@@ -5043,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.",
@@ -5165,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: {
@@ -5483,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.207.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",