@writepanda/mcp 1.109.0 → 1.116.0

package/README.md

@@ -1,18 +1,29 @@
-# @writepanda/mcp
+# PandaStudio MCP Server
 
-[Model Context Protocol](https://modelcontextprotocol.io) server for [PandaStudio](https://www.writepanda.ai) — a desktop video editor for YouTube creators. Lets AI agents edit videos like a human does: transcribe, delete filler words, drop motion graphics / FX / lower-thirds, generate captions, render the final MP4 — all without the user leaving their chat.
+[![npm](https://img.shields.io/npm/v/@writepanda/mcp)](https://www.npmjs.com/package/@writepanda/mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-Works with **Claude Desktop, Cursor, Continue.dev, Cline, and any MCP-compliant client**.
+[Model Context Protocol](https://modelcontextprotocol.io) server for **[PandaStudio](https://www.writepanda.ai)** — a local-first desktop video editor. It exposes the editor's full automation surface (**148 tools**) to Claude, ChatGPT/Codex, Cursor, Cline, Continue, and any MCP-compliant client.
 
-> **You also need PandaStudio installed.** The MCP server is a thin translator between MCP and PandaStudio's localhost-only automation API. Get the desktop app at [writepanda.ai](https://www.writepanda.ai).
+Most video MCP servers wrap FFmpeg or call a cloud rendering API. This one drives a **real desktop editor** running on your machine: transcript-based cutting, filler-word removal, motion graphics, captions, background removal, thumbnails, and publishing to YouTube/Instagram. Your footage never leaves your computer.
 
-## Install
+```
+"Transcribe the recording, cut the filler words and dead air, add captions,
+ punch in a zoom whenever I click something, and export it."
+```
+
+…and the agent actually does it, end to end.
 
-The MCP server runs on demand via `npx` — no global install needed. Add to your client config:
+## Requirements
 
-### Claude Desktop
+- **[PandaStudio](https://www.writepanda.ai)** installed (macOS or Windows). This server is a thin translator between MCP and PandaStudio's loopback automation API — it needs the app.
+- Node.js ≥ 18.
 
-`~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+## Install
+
+Runs on demand via `npx`; no global install.
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
@@ -25,9 +36,7 @@ The MCP server runs on demand via `npx` — no global install needed. Add to you
 }
 ```
 
-### Cursor
-
-`.cursor/mcp.json` in your workspace:
+**Cursor** — `.cursor/mcp.json`:
 
 ```json
 {
@@ -40,74 +49,70 @@ The MCP server runs on demand via `npx` — no global install needed. Add to you
 }
 ```
 
-### Continue.dev / Cline
+**Cline / Continue / Codex / others** — same shape in their MCP config.
 
-Same shape, in their respective MCP config files.
-
-After adding, restart your client. The MCP server auto-launches PandaStudio if it isn't running and waits for the localhost HTTP server to come up (~5s).
+Restart the client afterwards. The server auto-launches PandaStudio if it isn't running and waits for its local API (~5s).
 
 ## What the agent gets
 
-55 tools covering the full PandaStudio editorial surface — complete UI parity:
-
-| Category | Tools |
-|---|---|
-| Discovery | `system_status`, `system_list_commands` |
-| Project lifecycle | `project_list`, `project_show`, `project_read`, `project_new`, `project_open`, `project_save`, `project_delete` |
-| Clips | `project_add_clip`, `project_remove_clip`, `project_split_clip` |
-| Composition | `project_add_motion_graphic`, `project_add_fx`, `project_add_lower_third`, `project_add_zoom`, `project_add_trim`, `project_add_speed`, `project_add_annotation` |
-| Region editing | `project_remove_region`, `project_update_region` |
-| Canvas & style | `project_set_aspect_ratio`, `project_set_wallpaper`, `project_set_style`, `project_set_crop`, `project_set_webcam_layout`, `project_set_export_settings` |
-| Transcript editing | `transcript_transcribe`, `transcript_get`, `transcript_delete_words`, `transcript_remove_fillers`, `transcript_search`, `transcript_find_replace`, `transcript_remove_silences` |
-| Audio | `audio_clean` (DeepFilter denoising) |
-| Captions | `caption_toggle`, `caption_set_template`, `caption_set_style` |
-| Motion graphics | `motion_list`, `motion_themes`, `motion_generate`, `motion_render_html` |
-| Assets | `asset_list_sounds`, `asset_list_fx` |
-| AI metadata | `llm_generate_title`, `llm_generate_description`, `llm_generate_timestamps` |
-| Export | `export_start`, `export_list` |
-| Preview overlay | `preview_show`, `preview_seek`, `preview_hide` |
-| Async jobs | `job_wait`, `job_get` |
-| Escape hatch | `pandastudio_call` (raw verb.noun dispatch for anything not in the static list) |
-
-## Idiomatic agent prompt
+**148 tools**, full parity with the desktop UI — anything you can do by clicking, an agent can do by asking.
 
-```
-Edit the two videos in /Users/me/Downloads/raw-clips/ — transcribe them,
-remove filler words, add a "How I Built This" intro card, enable bold-yellow
-captions, and export the final MP4. Show me the preview overlay so I can
-watch as you work.
-```
+| Category | Tools | What it covers |
+|---|--:|---|
+| `project_*` | 60 | Project lifecycle, clips, trims, zooms, speed, motion graphics, FX, lower thirds, background removal, spotlight, crop, layouts, aspect ratio, wallpaper, focal point, shorts layouts, podcast composites |
+| `export_*` | 13 | Render to MP4, export library, AI thumbnails (generate/edit/revert), publish to YouTube + Instagram, find shots for shorts |
+| `workspace_*` | 11 | Multi-client workspaces, brand kit, per-workspace project defaults |
+| `transcript_*` | 10 | Transcribe (local, word-level), edit by transcript, remove fillers, remove silences, find bad takes, find/replace, insert/restore words |
+| `system_*` | 9 | Status, command discovery, transcription language, local model management |
+| `motion_*` | 8 | Motion-graphic templates, multi-scene storyboards, custom HTML compositions, frame verification |
+| `youtube_*` / `instagram_*` | 9 | Account connection, channel listing, publishing |
+| `asset_*` | 5 | Bundled music, sound effects, LUTs, transitions, FX |
+| `llm_*` | 4 | Generate titles, descriptions, chapter timestamps from the transcript |
+| `caption_*` | 3 | Toggle, templates, per-style overrides |
+| `media_*` | 3 | Generate images, music, narration |
+| `preview_*` / `job_*` / `agent_*` / `audio_*` / `timeline_*` | 14 | Live preview overlay, async job polling, agent sessions, audio cleanup, time-base conversion |
+
+Plus `pandastudio_call` — a raw `verb.noun` escape hatch for anything not yet a first-class tool.
 
-The agent calls `project_new`, `transcript_transcribe`, `transcript_remove_fillers`, `motion_generate`, `project_add_motion_graphic`, `caption_toggle`, `caption_set_template`, `preview_show`, then `export_start`. ~12 tool calls, fully unattended.
+## Example
+
+> Edit the two clips in `~/Downloads/raw/` — transcribe them, remove filler words,
+> add a "How I Built This" intro card, turn on bold captions, and export the MP4.
+
+The agent chains `project_new` → `transcript_transcribe` → `transcript_remove_fillers` → `motion_generate` → `project_add_motion_graphic` → `caption_toggle` → `caption_set_template` → `export_start`. Roughly a dozen tool calls, unattended.
 
 ## How it works
 
 ```
-MCP client (Cursor / Continue / Cline / Claude Desktop)
+MCP client (Claude Desktop / Cursor / Cline / Codex)
     ↓ JSON-RPC over stdio
-@writepanda/mcp (this server)
+@writepanda/mcp  (this server)
     ↓ HTTP POST 127.0.0.1:7878/v1/call
 PandaStudio desktop app
-    ↓ in-process function calls
-Editorial primitives (transcript, motion graphics, export, ...)
+    ↓ in-process calls
+Editorial engine (transcript, motion graphics, render, publish)
 ```
 
-Every call is bearer-authenticated against the per-launch token PandaStudio writes to `~/.config/pandastudio/token` (Mac/Linux) or `%APPDATA%\pandastudio\token` (Windows). Loopback-only — nothing leaves your machine.
+Every call is bearer-authenticated against the per-launch token PandaStudio writes to `~/.config/pandastudio/token` (macOS/Linux) or `%APPDATA%\pandastudio\token` (Windows). **Loopback only — nothing leaves your machine.** Credentials are discovered automatically from your local install; there is no token to paste.
 
 ## Licensing
 
-The MCP server honours the same license gate the desktop app does. With an expired trial and no license, only diagnostic tools work and every editorial tool returns `{ ok: false, details: { code: "trial_expired" } }`. Activate a license in the desktop app's Settings → License panel.
+The server honours the same license gate as the desktop app. With an expired trial and no license, diagnostic tools still work and editorial tools return `{ ok: false, details: { code: "trial_expired" } }`. Activate in the app under **Settings → License**.
 
 ## Companions
 
-- **[`@writepanda/cli`](https://www.npmjs.com/package/@writepanda/cli)** — same surface as a shell command (`pandastudio system.status`). Use this when scripting from bash / CI.
-- **Bundled Claude Skill** — auto-loaded markdown instructions for Claude Code / Claude Desktop. Install via PandaStudio Settings → Local automation → Install Skill (drops into `~/.claude/skills/pandastudio/`).
+- **[`@writepanda/cli`](https://www.npmjs.com/package/@writepanda/cli)** — the same surface as a shell command (`pandastudio system.status`). Better for bash/CI scripting, and cheaper on context than 148 tool schemas.
+- **[PandaStudio Agent Skill](https://github.com/kamskans/pandastudio-skills)** — `npx skills add kamskans/pandastudio-skills`. The authoritative playbook: which verbs to call, in what order, with what defaults per destination.
 
 ## Documentation
 
-- Full surface + recipes: [writepanda.ai/cli](https://www.writepanda.ai/cli)
-- Source: [github.com/kamskans/openscreen](https://github.com/kamskans/openscreen)
+- Full surface + recipes: **[writepanda.ai/cli](https://www.writepanda.ai/cli)**
+- Desktop app: **[writepanda.ai](https://www.writepanda.ai)**
+
+## Note on this repository
+
+This repo mirrors the published `@writepanda/mcp` package (the server, its README, and license) so the package has a public home for issues and MCP registries. The desktop app's source is private; the MCP server is MIT and published in full here and on npm.
 
 ## License
 
-MIT.
+MIT

package/bin/server.mjs

@@ -1221,6 +1221,72 @@ const TOOLS = [
 		},
 		command: "project.add-zoom",
 	},
+	{
+		name: "project_add_caption_region",
+		description:
+			"Hide captions for a stretch of the timeline. Captions show everywhere by default when enabled, so this carves out an exception — use it when subtitles would cover something on screen, such as during a UI demo. Times are edited-timeline ms. Overlapping regions are fine.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				atMs: { type: "number", description: "Edited-time start (ms)." },
+				durationMs: { type: "number", description: "How long captions stay hidden (ms)." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["atMs", "durationMs"],
+		},
+		command: "project.add-caption-region",
+	},
+	{
+		name: "project_remove_caption_region",
+		description:
+			"Remove a caption-suppression region so captions show there again. Find ids in project_read under editor.captionRegions[].id.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				regionId: { type: "string", description: "Caption region id." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["regionId"],
+		},
+		command: "project.remove-caption-region",
+	},
+	{
+		name: "project_add_mute_region",
+		description:
+			"Silence the video's own audio for a stretch of the timeline (the main voice/screen track). Background music and SFX overlays keep playing — mute touches only the main track, same as the editor. Times are edited-timeline ms; durationMs controls how much is muted. Overlapping regions are fine. Use to drop a cough, a name, or dead air without deleting the footage. Remove with project_remove_mute_region.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				atMs: { type: "number", description: "Edited-time start (ms)." },
+				durationMs: { type: "number", description: "How long the main audio stays silent (ms)." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["atMs", "durationMs"],
+		},
+		command: "project.add-mute-region",
+	},
+	{
+		name: "project_remove_mute_region",
+		description:
+			"Remove a mute region so the main audio is audible there again. Find ids in project_read under editor.muteRegions[].id.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				regionId: { type: "string", description: "Mute region id." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["regionId"],
+		},
+		command: "project.remove-mute-region",
+	},
 	{
 		name: "project_add_spotlight",
 		description:
@@ -1830,6 +1896,44 @@ const TOOLS = [
 		},
 		command: "project.set-webcam-layout",
 	},
+	{
+		name: "project_set_webcam_style",
+		description:
+			"Set the camera tile's APPEARANCE (project-level): shape, border ring, drop shadow. Complements project_set_webcam_layout (position/size/crop). shape: auto (preset's responsive radius — default) | rectangle (square corners) | rounded (use cornerRadius) | circle (circular camera bubble). borderWidth 0-40 px at a 1080p reference (0 removes) + borderColor (CSS color). shadow 0-1 intensity (0 = none; omit = preset default). Fields merge into the current style; reset=true returns to preset defaults. Applies to the camera tile in picture-in-picture / side-by-side / vertical-stack (podcast grids keep co-equal tiles). Preview and export honor it identically.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				shape: {
+					type: "string",
+					description: "auto | rectangle | rounded | circle",
+				},
+				cornerRadius: {
+					type: "number",
+					description: "Corner radius for shape=rounded, px at 1080p reference (0-200).",
+				},
+				borderWidth: {
+					type: "number",
+					description: "Border ring width, px at 1080p reference (0-40). 0 removes the border.",
+				},
+				borderColor: {
+					type: "string",
+					description: 'Border ring CSS color, e.g. "#ffffff".',
+				},
+				shadow: {
+					type: "number",
+					description: "Drop-shadow intensity 0-1. 0 = none. Omit to keep the preset default.",
+				},
+				reset: {
+					type: "boolean",
+					description: "true clears all camera-appearance overrides.",
+				},
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.set-webcam-style",
+	},
 	{
 		name: "project_set_crop",
 		description:
@@ -2116,6 +2220,11 @@ const TOOLS = [
 					description:
 						"Optional anchor end (source ms). When set, the overlay's edited duration tracks the source-time span between anchorSourceMs and anchorSourceEndMs.",
 				},
+				transcribe: {
+					type: "boolean",
+					description:
+						"Transcribe this audio and merge its words into the project transcript at the overlay's position. Use for VOICEOVER / narration so captions and transcript-driven edits work — audio overlays are otherwise never transcribed (only main-track clips are). Do NOT pass for music. Async: response includes transcribeJobId, poll job_get / job_wait.",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["audioPath"],
@@ -2203,6 +2312,30 @@ const TOOLS = [
 		},
 		command: "project.set-webcam-offset",
 	},
+	{
+		name: "project_set_clip_volume",
+		description:
+			"Set a main-track clip's audio VOLUME (linear gain). volume=1 is the original level, 0 silences the clip, 2 is +6 dB (clamped 0-2). volume=1 clears the override. Identify the clip by clipId OR clipIndex (0-based, matching the order clipStates are returned by project_read). Applied in preview AND both export paths — no re-render of the audio file needed. Use to balance loudness across clips (e.g. boost a quiet second recording); for a hard mute pass volume=0.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string", description: "Clip id (or use clipIndex)" },
+				clipIndex: {
+					type: "number",
+					description: "0-based clip position in the main track (alternative to clipId)",
+				},
+				volume: {
+					type: "number",
+					description: "Linear gain 0-2. 1 = original, 0 = silent, 2 = +6 dB.",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["volume"],
+		},
+		command: "project.set-clip-volume",
+	},
 	{
 		name: "project_set_clip_layout",
 		description:
@@ -2433,7 +2566,7 @@ const TOOLS = [
 				thresholdMs: {
 					type: "number",
 					description:
-						"Gaps longer than this are trimmed. Default 500ms — same threshold as the UI Remove Silences button, so the agent removes the same silences a manual click would.",
+						"Gaps longer than this are trimmed. Default 600ms — same threshold as the UI Remove Silences button, so the agent removes the same silences a manual click would.",
 				},
 				expectedRevision: { type: "number" },
 			},
@@ -3004,6 +3137,33 @@ const TOOLS = [
 		inputSchema: { type: "object", properties: {} },
 		command: "export.list",
 	},
+	{
+		name: "export_set_details",
+		description:
+			"Set an export's YouTube-facing details — title, description, and/or chapter timestamps (the fields in the export's Content tab). Pass only what you want to change. Call this when the user asks to update the title/description of an export. `id` is the export-library entry id; when the user is on the export page it is available to the agent as exportPage.entryId in the editor context (else call export_list to find it).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Export-library entry id." },
+				title: { type: "string", description: "New video title." },
+				description: { type: "string", description: "New video description." },
+				timestamps: {
+					type: "array",
+					description:
+						"Chapter timestamps as an array of { timeMs, label } objects, sorted ascending. Omit to leave unchanged.",
+					items: {
+						type: "object",
+						properties: {
+							timeMs: { type: "number" },
+							label: { type: "string" },
+						},
+					},
+				},
+			},
+			required: ["id"],
+		},
+		command: "export.set-details",
+	},
 	{
 		name: "export_generate_thumbnail",
 		description:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@writepanda/mcp",
-	"version": "1.109.0",
+	"version": "1.116.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",
@@ -18,11 +18,10 @@
 	"homepage": "https://www.writepanda.ai/cli",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/kamskans/openscreen.git",
-		"directory": "packages/mcp"
+		"url": "git+https://github.com/kamskans/pandastudio-mcp.git"
 	},
 	"bugs": {
-		"url": "https://github.com/kamskans/openscreen/issues"
+		"url": "https://github.com/kamskans/pandastudio-mcp/issues"
 	},
 	"type": "module",
 	"engines": {