@writepanda/mcp 1.19.0 → 1.22.0

package/bin/server.mjs

@@ -163,6 +163,208 @@ const TOOLS = [
 		command: "system.list",
 	},
 
+	// ── workspaces (v1.19) ──────────────────────────────────────────
+	// Multi-workspace isolation: each workspace has its own projects,
+	// exports, Replicate key, and (v1.19.0+) YouTube connections.
+	// Agents managing an agency account can switch workspaces mid-
+	// flow to operate inside a specific client's bucket.
+	{
+		name: "workspace_list",
+		description:
+			"List every workspace on this machine. Returns `currentWorkspaceId` + a `limit` object describing the plan's cap (`max: null` for unlimited on Team, 1 on Starter/Trial, 3 on Creator). Call this first to see what workspaces exist and which one every other query defaults to.",
+		inputSchema: { type: "object", properties: {} },
+		command: "workspace.list",
+	},
+	{
+		name: "workspace_current",
+		description: "Return the active workspace (what every workspace-scoped query defaults to).",
+		inputSchema: { type: "object", properties: {} },
+		command: "workspace.current",
+	},
+	{
+		name: "workspace_create",
+		description:
+			"Create a new workspace. On plan cap: returns `{ ok: false, details: { code: 'workspace_limit_reached', upgradeTo: 'Creator' | 'Team' | null } }` — surface that to the user instead of retrying. Pass `switchTo: true` to make the new workspace active immediately.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: { type: "string", description: "Display name, max 80 chars." },
+				switchTo: {
+					type: "boolean",
+					description: "Switch to the new workspace immediately. Default false.",
+				},
+			},
+			required: ["name"],
+		},
+		command: "workspace.create",
+	},
+	{
+		name: "workspace_rename",
+		description: "Rename a workspace. No cross-workspace side effects.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				name: { type: "string", description: "New name, max 80 chars." },
+			},
+			required: ["id", "name"],
+		},
+		command: "workspace.rename",
+	},
+	{
+		name: "workspace_delete",
+		description:
+			"Hard-delete a workspace and everything inside it: project rows (on-disk .pandastudio files remain), exports, shots, Replicate key + YouTube connections. Refuses to delete the last remaining workspace. Call `workspace.contents` first and show the user what they'll lose.",
+		inputSchema: {
+			type: "object",
+			properties: { id: { type: "string" } },
+			required: ["id"],
+		},
+		command: "workspace.delete",
+	},
+	{
+		name: "workspace_switch",
+		description:
+			"Change the active workspace. All subsequent project.*/export.*/motion.* queries operate inside the target until the next switch.",
+		inputSchema: {
+			type: "object",
+			properties: { id: { type: "string" } },
+			required: ["id"],
+		},
+		command: "workspace.switch",
+	},
+	{
+		name: "workspace_contents",
+		description:
+			"Count projects / exports / published YouTube videos in a workspace. Use before `workspace.delete` for the 'you will lose N items' warning.",
+		inputSchema: {
+			type: "object",
+			properties: { id: { type: "string" } },
+			required: ["id"],
+		},
+		command: "workspace.contents",
+	},
+
+	// ── YouTube publishing (v1.19) ──────────────────────────────────
+	// Connect Google accounts per workspace, publish exports, edit
+	// already-published videos. All verbs operate on the active
+	// workspace unless the agent switches first.
+	{
+		name: "youtube_is_configured",
+		description:
+			"Return whether this PandaStudio build has Google OAuth credentials baked in. When false, every other `youtube.*` verb will fail — tell the user this build can't publish to YouTube.",
+		inputSchema: { type: "object", properties: {} },
+		command: "youtube.is-configured",
+	},
+	{
+		name: "youtube_connect",
+		description:
+			"Start Google OAuth in the user's system browser. Long-running: waits up to 5 minutes for consent. On success, stores refresh token encrypted under the active workspace and returns the account + its channels. INTERACTIVE — only call when the user explicitly asks to connect a YouTube account.",
+		inputSchema: { type: "object", properties: {} },
+		command: "youtube.connect",
+	},
+	{
+		name: "youtube_disconnect",
+		description:
+			"Revoke and delete a YouTube account from the active workspace. Published videos stay on YouTube; only the local connection + cached channels + encrypted refresh token are removed.",
+		inputSchema: {
+			type: "object",
+			properties: { accountId: { type: "string" } },
+			required: ["accountId"],
+		},
+		command: "youtube.disconnect",
+	},
+	{
+		name: "youtube_list_accounts",
+		description:
+			"List connected Google accounts in the active workspace + cached YouTube channels. Call this before `export.publish-youtube` so the user can pick account + channel.",
+		inputSchema: { type: "object", properties: {} },
+		command: "youtube.list-accounts",
+	},
+	{
+		name: "youtube_list_channels",
+		description:
+			"Re-pull the channel list for a connected account from YouTube (bypasses local cache). Useful if the user just created a new channel under the same Google account.",
+		inputSchema: {
+			type: "object",
+			properties: { accountId: { type: "string" } },
+			required: ["accountId"],
+		},
+		command: "youtube.list-channels",
+	},
+	{
+		name: "export_publish_youtube",
+		description:
+			"Upload an export-library entry to YouTube via resumable upload. Stamps title/description/tags/privacy on the video and (optionally) pushes the entry's thumbnail. Returns `{ videoId, videoUrl }`. LONG-RUNNING (expect ~30 s per 100 MB). The export row is marked `youtubeVideoId` on success, so repeated calls on an already-published entry should check that field first.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Export entry id." },
+				accountId: { type: "string" },
+				channelId: { type: "string" },
+				title: { type: "string" },
+				description: { type: "string" },
+				tags: { type: "array", items: { type: "string" } },
+				categoryId: { type: "string" },
+				privacyStatus: {
+					type: "string",
+					description: "public | unlisted | private. Default unlisted.",
+				},
+				setThumbnail: { type: "boolean" },
+			},
+			required: ["id", "accountId", "channelId", "title"],
+		},
+		command: "export.publish-youtube",
+	},
+	{
+		name: "export_list_youtube",
+		description:
+			"List recently-published videos on a connected account (includes videos not published via PandaStudio). Dashboard data.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				accountId: { type: "string" },
+				max: { type: "number", description: "Default 25, max 50." },
+			},
+			required: ["accountId"],
+		},
+		command: "export.list-youtube",
+	},
+	{
+		name: "export_update_youtube",
+		description:
+			"Update an already-published video's metadata (title / description / tags / category / privacyStatus). Pass only the fields you want to change. Cannot replace the video file — YouTube requires deleting and re-uploading for that.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				accountId: { type: "string" },
+				videoId: { type: "string" },
+				title: { type: "string" },
+				description: { type: "string" },
+				tags: { type: "array", items: { type: "string" } },
+				categoryId: { type: "string" },
+				privacyStatus: { type: "string" },
+			},
+			required: ["accountId", "videoId"],
+		},
+		command: "export.update-youtube",
+	},
+	{
+		name: "export_update_youtube_thumbnail",
+		description:
+			"Replace an already-published video's thumbnail on YouTube via thumbnails.set. Expects a local 1280×720 image (no auto-crop — pre-process or use `export.generate-thumbnail` output).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				accountId: { type: "string" },
+				videoId: { type: "string" },
+				imagePath: { type: "string" },
+			},
+			required: ["accountId", "videoId", "imagePath"],
+		},
+		command: "export.update-youtube-thumbnail",
+	},
+
 	// ── project lifecycle ───────────────────────────────────────────
 	{
 		name: "project_list",
@@ -558,7 +760,7 @@ const TOOLS = [
 	{
 		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.",
+			"Delete an existing region (zoom, trim, speed, annotation, fx, lower-third, overlay, audio-overlay) by its id. Use project_read to find region ids — visual regions live under editor.*Regions; audio overlays live under audioOverlays[]. Returns the updated project.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -566,9 +768,10 @@ const TOOLS = [
 				path: { type: "string" },
 				regionType: {
 					type: "string",
-					description: "zoom | trim | speed | annotation | fx | lower-third | overlay",
+					description:
+						"zoom | trim | speed | annotation | fx | lower-third | overlay | audio-overlay",
 				},
-				regionId: { type: "string", description: "UUID of the region to delete" },
+				regionId: { type: "string", description: "id of the region to delete" },
 				expectedRevision: { type: "number" },
 			},
 			required: ["regionType", "regionId"],
@@ -578,7 +781,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, and overlay regions.",
+			"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, and audio-overlay (startMs, endMs, sourceStartMs, volume — lets you drag-trim an audio overlay without removing it).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -586,13 +789,14 @@ const TOOLS = [
 				path: { type: "string" },
 				regionType: {
 					type: "string",
-					description: "zoom | trim | speed | annotation | fx | lower-third | overlay",
+					description:
+						"zoom | trim | speed | annotation | fx | lower-third | overlay | audio-overlay",
 				},
-				regionId: { type: "string", description: "UUID of the region to update" },
+				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, or { content: 'New Name' } on a lower-third.",
+						"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).",
 				},
 				expectedRevision: { type: "number" },
 			},
@@ -758,7 +962,7 @@ const TOOLS = [
 	{
 		name: "project_add_audio",
 		description:
-			"Add a background audio track (music, VO, ambient sound) to the project. The audio plays over the full mix from startMs and is exported automatically. Use project_remove_audio to remove it. Returns { overlayId } — save this to remove it later.",
+			"Add a background audio overlay (music, VO, ambient) as a first-class timeline region. Plays from startMs to endMs on the edited timeline; sourceStartMs is the in-point into the source file. Waveform peaks are extracted automatically and stored on the overlay for the timeline UI. Use project_update_region (regionType=audio-overlay) to drag/trim it afterward. Returns { overlayId } — save this to trim/remove later.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -770,12 +974,27 @@ const TOOLS = [
 				},
 				startMs: {
 					type: "number",
-					description: "Where in the edited timeline playback starts. Default 0.",
+					description: "Where on the edited timeline playback starts. Default 0.",
+				},
+				endMs: {
+					type: "number",
+					description:
+						"Where on the edited timeline playback ends. Precedence: endMs > maxDurationMs > durationMs. If all are omitted, defaults to the source file's real duration.",
+				},
+				sourceStartMs: {
+					type: "number",
+					description:
+						"In-point into the source file in ms. Default 0. Combine with endMs-startMs to play a window of the source (e.g. startMs=2000, endMs=15000, sourceStartMs=4000 plays seconds 4–17 of the source at timeline position 2–15s).",
+				},
+				durationMs: {
+					type: "number",
+					description: "Fallback duration when neither endMs nor maxDurationMs is given.",
 				},
 				volume: { type: "number", description: "Volume multiplier 0–2. Default 0.8." },
 				maxDurationMs: {
 					type: "number",
-					description: "Clip the audio at this duration. Omit to play the full file.",
+					description:
+						"[Legacy] Sets endMs = startMs + maxDurationMs when endMs is absent. Prefer endMs.",
 				},
 				expectedRevision: { type: "number" },
 			},
@@ -1058,7 +1277,7 @@ const TOOLS = [
 	{
 		name: "motion_render_html",
 		description:
-			"Render arbitrary HTML/CSS/JS to video. Use this when the bundled motion-graphic templates don't fit the brief — you write the HTML, the Chromium → capturePage → FFmpeg pipeline does the rest. Pass either inline `html` or a `htmlPath`. Animations should auto-start on DOMContentLoaded. Set `transparent: true` to get a WebM with alpha channel for overlays (lower thirds, watermarks, name plates) that composite over existing video. IMPORTANT: renders are sequential — call job_wait to completion before starting another render, or you'll get a RENDER_BUSY error. Async — returns { jobId, outputPath }; poll job_wait for the final file.",
+			"Render arbitrary HTML/CSS/JS to video via the HyperFrames engine — frame-perfect, seekable capture through chrome-headless-shell's BeginFrame API. Use this when the bundled motion-graphic templates don't fit the brief. The HTML MUST expose a paused GSAP timeline registered as `window.__timelines[<data-composition-id>] = tl` — NOT CSS keyframes, NOT setTimeout, NOT `window.__hf.seek` (that lower-level protocol skips the compositor invalidation wrapper and renders with 1-second stalls). See the SKILL.md `Custom motion graphics — HTML authoring` section for the required `data-composition-id`/`data-width`/`data-height`/`data-duration` root element, the canonical template, and pacing rules. Pass either inline `html` or `htmlPath`. Set `transparent: true` for a WebM+alpha overlay (lower thirds, watermarks). IMPORTANT: renders are sequential — call job_wait to completion before starting another render, or you'll get a RENDER_BUSY error. Async — returns { jobId, outputPath }; poll job_wait for the final file.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1177,7 +1396,7 @@ const TOOLS = [
 	{
 		name: "asset_list_music",
 		description:
-			"List every bundled background music track (id, title, category, mood, durationMs, absolutePath). Use absolutePath with project_add_audio to attach a track to a project.",
+			"List every bundled background music track. Each track has: id, title, category, mood, durationMs, absolutePath, and agent-routing hints `intents` (e.g. product_video, kinetic_text, promo, intro, outro, tech_review, vlog, generic) and `recommendedFor` (youtube-long | shorts | linkedin | loom). Match on intents first when picking a track — use mood/category as tiebreakers. Use absolutePath with project_add_audio to attach a track to a project.",
 		inputSchema: { type: "object", properties: {} },
 		command: "asset.list-music",
 	},
@@ -1256,6 +1475,96 @@ const TOOLS = [
 		inputSchema: { type: "object", properties: {} },
 		command: "export.list",
 	},
+	{
+		name: "export_generate_thumbnail",
+		description:
+			"Generate a YouTube thumbnail for an export-library entry via Replicate's gpt-image-2 model. If `prompt` isn't supplied, the local LLM writes one from the transcript (an opinionated YouTube-thumbnail art-director prompt targeting 3:2 aspect, photorealistic or bold-graphic, high contrast, optional short overlay text). Requires the user's Replicate API key to be set in Settings → Integrations (the key is stored encrypted via OS keychain; PandaStudio never sees the user's OpenAI bill). Returns { imagePath, prompt, iterations } on success.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Export entry id." },
+				prompt: {
+					type: "string",
+					description:
+						"Optional explicit prompt. If omitted, the local LLM auto-writes one from the transcript.",
+				},
+				referenceImagePath: {
+					type: "string",
+					description:
+						"Optional reference image (absolute path or https URL) passed as gpt-image-2 `input_images`.",
+				},
+				quality: {
+					type: "string",
+					description: "gpt-image-2 quality. 'low' | 'medium' (default) | 'high'.",
+				},
+			},
+			required: ["id"],
+		},
+		command: "export.generate-thumbnail",
+	},
+	{
+		name: "export_edit_thumbnail",
+		description:
+			"Iterate on the existing thumbnail via natural-language edit prompt ('make it more red', 'add bold text at top', 'remove the logo'). The current thumbnail is passed to gpt-image-2 as input_images, and the result replaces it. The previous thumbnail is pushed onto `entry.thumbnailIterations` so the user can revert. Quality is fixed at 'low' on edits — fast and cheap, suitable for rapid iteration.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Export entry id." },
+				editPrompt: {
+					type: "string",
+					description: "What to change. One-sentence natural-language instruction.",
+				},
+			},
+			required: ["id", "editPrompt"],
+		},
+		command: "export.edit-thumbnail",
+	},
+	{
+		name: "export_set_thumbnail",
+		description:
+			"Attach a manually-chosen image file (PNG / JPEG / WebP) as the thumbnail. Use this when the user provides a ready-made image, or when an agent has already generated one elsewhere. Copies the file into the managed thumbnails directory; iteration history is cleared. Prefer `export.generate-thumbnail` for AI-generated thumbnails so iteration history is preserved.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Export entry id." },
+				sourcePath: {
+					type: "string",
+					description: "Absolute path to the local image file (PNG / JPEG / WebP).",
+				},
+			},
+			required: ["id", "sourcePath"],
+		},
+		command: "export.set-thumbnail",
+	},
+	{
+		name: "export_clear_thumbnail",
+		description: "Remove the current thumbnail and wipe its iteration history.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Export entry id." },
+			},
+			required: ["id"],
+		},
+		command: "export.clear-thumbnail",
+	},
+	{
+		name: "export_revert_thumbnail",
+		description:
+			"Revert to a previous thumbnail from the iteration history (`entry.thumbnailIterations[].id`). The current image gets pushed onto history, so the revert itself is undoable.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Export entry id." },
+				iterationId: {
+					type: "string",
+					description: "id of the iteration entry from `entry.thumbnailIterations`.",
+				},
+			},
+			required: ["id", "iterationId"],
+		},
+		command: "export.revert-thumbnail",
+	},
 
 	// ── preview overlay (v1.9.2) ────────────────────────────────────
 	{

package/package.json

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