@writepanda/mcp 1.9.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamala Kannan Sankarraj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @writepanda/mcp
+
+[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.
+
+Works with **Claude Desktop, Cursor, Continue.dev, Cline, 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).
+
+## Install
+
+The MCP server runs on demand via `npx` — no global install needed. Add to your client config:
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "pandastudio": {
+      "command": "npx",
+      "args": ["-y", "@writepanda/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+`.cursor/mcp.json` in your workspace:
+
+```json
+{
+  "mcpServers": {
+    "pandastudio": {
+      "command": "npx",
+      "args": ["-y", "@writepanda/mcp"]
+    }
+  }
+}
+```
+
+### Continue.dev / Cline
+
+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).
+
+## What the agent gets
+
+30+ tools covering the full PandaStudio editorial surface:
+
+| Category | Tools |
+|---|---|
+| Discovery | `system_status`, `system_list_commands` |
+| Project lifecycle | `project_list`, `project_show`, `project_read`, `project_new`, `project_open` |
+| Composition | `project_add_clip`, `project_add_motion_graphic`, `project_add_fx`, `project_add_lower_third`, `project_add_zoom`, `project_add_trim`, `project_add_speed` |
+| Transcript editing | `transcript_transcribe`, `transcript_get`, `transcript_delete_words`, `transcript_remove_fillers`, `transcript_search` |
+| Audio | `audio_clean` (DeepFilter denoising) |
+| Captions | `caption_toggle`, `caption_set_template` |
+| Motion graphics | `motion_list`, `motion_themes`, `motion_generate` |
+| 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
+
+```
+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.
+```
+
+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.
+
+## How it works
+
+```
+MCP client (Cursor / Continue / Cline / Claude Desktop)
+    ↓ JSON-RPC over stdio
+@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, ...)
+```
+
+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.
+
+## 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.
+
+## 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/`).
+
+## Documentation
+
+- Full surface + recipes: [writepanda.ai/cli](https://www.writepanda.ai/cli)
+- Source: [github.com/kamskans/openscreen](https://github.com/kamskans/openscreen)
+
+## License
+
+MIT.

package/bin/server.mjs

@@ -0,0 +1,755 @@
+#!/usr/bin/env node
+// PandaStudio MCP server — translates Model Context Protocol tool
+// calls into HTTP requests against the desktop app's localhost
+// automation API.
+//
+// Architecture:
+//
+//   MCP client (Cursor / Continue / Cline / Claude Desktop)
+//     ↓ JSON-RPC over stdio (MCP protocol)
+//   this server (writepanda-mcp)
+//     ↓ HTTP POST localhost:7878/v1/call
+//   PandaStudio desktop app's automation server
+//     ↓ in-process function calls
+//   Editorial primitives (transcript, motion graphics, export, ...)
+//
+// Tool exposure strategy:
+//   - 30+ STATIC tools mirror the high-value verbs (every editorial
+//     primitive an agent needs for the canonical workflow). Static
+//     because MCP clients cache tool schemas at connect time and
+//     don't re-fetch them mid-session — a dynamic registry would go
+//     stale in the client cache.
+//   - One ESCAPE HATCH tool: `pandastudio_call` takes
+//     `{ command: "verb.noun", args: {...} }` so agents can hit any
+//     verb that lands in PandaStudio after this MCP version shipped.
+//     Long tail covered without a re-publish.
+//
+// Naming convention: MCP tool names use underscores (snake_case);
+// PandaStudio CLI uses verb.noun. Translation is verb_noun ↔ verb.noun.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+	CallToolRequestSchema,
+	ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ── Credentials + transport ───────────────────────────────────────────
+
+function configDir() {
+	if (process.env.PANDASTUDIO_CONFIG_DIR) return process.env.PANDASTUDIO_CONFIG_DIR;
+	if (process.platform === "win32") {
+		const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+		return path.join(appData, "pandastudio");
+	}
+	return path.join(os.homedir(), ".config", "pandastudio");
+}
+
+const TOKEN_FILE = path.join(configDir(), "token");
+const PORT_FILE = path.join(configDir(), "port");
+
+async function readCredentials() {
+	const port = Number((await fs.readFile(PORT_FILE, "utf-8")).trim());
+	const token = (await fs.readFile(TOKEN_FILE, "utf-8")).trim();
+	if (!Number.isInteger(port) || port <= 0) throw new Error(`invalid port in ${PORT_FILE}`);
+	if (!token) throw new Error(`empty token in ${TOKEN_FILE}`);
+	return { port, token };
+}
+
+async function probeHealth(port, timeoutMs = 1500) {
+	const ctrl = new AbortController();
+	const t = setTimeout(() => ctrl.abort(), timeoutMs);
+	try {
+		const res = await fetch(`http://127.0.0.1:${port}/v1/health`, { signal: ctrl.signal });
+		clearTimeout(t);
+		return res.ok;
+	} catch {
+		clearTimeout(t);
+		return false;
+	}
+}
+
+function findInstalledApp() {
+	if (process.env.PANDASTUDIO_BIN) return process.env.PANDASTUDIO_BIN;
+	if (process.platform === "darwin") {
+		return "/Applications/PandaStudio.app/Contents/MacOS/PandaStudio";
+	}
+	if (process.platform === "win32") {
+		const programFiles = process.env["ProgramFiles"] ?? "C:\\Program Files";
+		return path.join(programFiles, "PandaStudio", "PandaStudio.exe");
+	}
+	return "/opt/PandaStudio/pandastudio";
+}
+
+async function autoLaunchAndWait(timeoutSec = 60) {
+	// Try a fast probe in case the user already has it running.
+	try {
+		const c = await readCredentials();
+		if (await probeHealth(c.port)) return c;
+	} catch {
+		/* not running */
+	}
+
+	const bin = findInstalledApp();
+	try {
+		const child = spawn(bin, [], { detached: true, stdio: "ignore", env: process.env });
+		child.unref();
+	} catch (err) {
+		throw new Error(`failed to launch PandaStudio (${bin}): ${err?.message ?? err}`);
+	}
+
+	const deadline = Date.now() + timeoutSec * 1000;
+	while (Date.now() < deadline) {
+		try {
+			const c = await readCredentials();
+			if (await probeHealth(c.port, 2000)) return c;
+		} catch {
+			/* still booting */
+		}
+		await new Promise((r) => setTimeout(r, 500));
+	}
+	throw new Error(
+		`PandaStudio did not become ready within ${timeoutSec}s. Open the app and enable "Allow local automation" in Settings.`,
+	);
+}
+
+async function callPandastudio(command, args = {}) {
+	const creds = await autoLaunchAndWait();
+	const res = await fetch(`http://127.0.0.1:${creds.port}/v1/call`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${creds.token}`,
+		},
+		body: JSON.stringify({ command, args }),
+	});
+	const text = await res.text();
+	let body;
+	try {
+		body = text.length === 0 ? null : JSON.parse(text);
+	} catch {
+		body = { raw: text };
+	}
+	if (res.status >= 400) {
+		throw new Error(`HTTP ${res.status}: ${body?.error ?? text.slice(0, 200)}`);
+	}
+	return body;
+}
+
+// ── Tool catalogue ────────────────────────────────────────────────────
+//
+// Static MCP tool schemas. Each tool name uses snake_case (MCP
+// convention); the `command` field is the underlying verb.noun the
+// HTTP server expects. Keep this list focused on the editorial
+// workflow — the `pandastudio_call` escape hatch covers the long
+// tail and any post-publish additions.
+
+const TOOLS = [
+	// ── system + discovery ──────────────────────────────────────────
+	{
+		name: "system_status",
+		description:
+			"Probe PandaStudio's automation server. Returns app version, license state, and `automationGated` (true if trial expired and no license — every other tool will fail). ALWAYS call this first.",
+		inputSchema: { type: "object", properties: {} },
+		command: "system.status",
+	},
+	{
+		name: "system_list_commands",
+		description:
+			"List every verb.noun command the desktop app's automation server exposes — including ones added after this MCP version shipped. Use the long-tail ones via the `pandastudio_call` escape hatch.",
+		inputSchema: { type: "object", properties: {} },
+		command: "system.list",
+	},
+
+	// ── project lifecycle ───────────────────────────────────────────
+	{
+		name: "project_list",
+		description:
+			"List every project on disk (id, name, path, modifiedAt, clipCount, revision). Returns the project UUID — pass it as `id` to most other tools.",
+		inputSchema: { type: "object", properties: {} },
+		command: "project.list",
+	},
+	{
+		name: "project_show",
+		description: "Resolve a project's path + summary metadata by id or path. Cheaper than project_read.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Project UUID (preferred)" },
+				path: { type: "string", description: "Project file path" },
+			},
+		},
+		command: "project.show",
+	},
+	{
+		name: "project_read",
+		description:
+			"Read a project's full JSON. Returns { path, project }. Pass `project.revision` back as `expectedRevision` on subsequent writes for conflict-safe edits.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+			},
+		},
+		command: "project.read",
+	},
+	{
+		name: "project_new",
+		description:
+			"Create a new project. `withMedia` (array of absolute video file paths) imports them as clips; FFmpeg probes each duration. Returns { id, path, project }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: { type: "string", description: "Display name" },
+				withMedia: {
+					type: "array",
+					items: { type: "string" },
+					description: "Absolute paths to video files to import as clips",
+				},
+			},
+			required: ["name"],
+		},
+		command: "project.new",
+	},
+	{
+		name: "project_open",
+		description: "Open the desktop editor focused on a specific project (so the user can take over).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+			},
+		},
+		command: "project.open",
+	},
+
+	// ── compose: clips, motion graphics, FX, lower-thirds ──────────
+	{
+		name: "project_add_clip",
+		description: "Append a video clip to the project's main track. Probes duration via FFmpeg.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				media: { type: "string", description: "Absolute path to video file" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["media"],
+		},
+		command: "project.add-clip",
+	},
+	{
+		name: "project_add_motion_graphic",
+		description:
+			"Drop a motion-graphic MP4 (typically the output of motion_generate) onto the timeline.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				file: { type: "string", description: "Absolute path to MP4" },
+				durationMs: { type: "number" },
+				atMs: { type: "number", description: "Default: end of timeline" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["file", "durationMs"],
+		},
+		command: "project.add-motion-graphic",
+	},
+	{
+		name: "project_add_fx",
+		description: "Drop an FX overlay (bundled fxId or custom video URL) onto the timeline.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				fxId: { type: "string", description: "Bundled FX id (e.g. film-burn). Use asset_list_fx to discover." },
+				src: { type: "string", description: "Direct path/URL (alternative to fxId)" },
+				atMs: { type: "number" },
+				durationMs: { type: "number", description: "Default 2500ms for bundled FX" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["atMs"],
+		},
+		command: "project.add-fx",
+	},
+	{
+		name: "project_add_lower_third",
+		description: "Drop a lower-third name plate onto the timeline.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				content: { type: "string", description: "Primary text (name)" },
+				subtitle: { type: "string", description: "Secondary text (title)" },
+				atMs: { type: "number" },
+				durationMs: { type: "number", description: "Default 5000ms" },
+				designType: {
+					type: "string",
+					description: "name-bar | slash-reveal | center-stack | minimal-underline | box-reveal | corner-brackets | border-frame | split-horizontal",
+				},
+				accentColor: { type: "string" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["content", "atMs"],
+		},
+		command: "project.add-lower-third",
+	},
+
+	// ── compose: visual regions ─────────────────────────────────────
+	{
+		name: "project_add_zoom",
+		description: "Add a zoom region — highlight a UI moment. Typical pattern: find 'click X' in transcript, drop zoom there.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				atMs: { type: "number" },
+				durationMs: { type: "number" },
+				depth: { type: "number", description: "1 (mild) - 6 (extreme). Default 3" },
+				focusX: { type: "number", description: "Normalised 0-1 horizontal center. Default 0.5" },
+				focusY: { type: "number", description: "Normalised 0-1 vertical center. Default 0.5" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["atMs", "durationMs"],
+		},
+		command: "project.add-zoom",
+	},
+	{
+		name: "project_add_trim",
+		description: "Mark a span the exporter SKIPS. Use directly for manual cuts.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				startMs: { type: "number" },
+				endMs: { type: "number" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["startMs", "endMs"],
+		},
+		command: "project.add-trim",
+	},
+	{
+		name: "project_add_speed",
+		description: "Mark a span to play at a different speed. Useful for fast-forwarding setup.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				startMs: { type: "number" },
+				endMs: { type: "number" },
+				speed: { type: "number", description: "0.25, 0.5, 0.75, 1.25, 1.5, 1.75, or 2" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["startMs", "endMs", "speed"],
+		},
+		command: "project.add-speed",
+	},
+
+	// ── transcript-based editing ────────────────────────────────────
+	{
+		name: "transcript_transcribe",
+		description:
+			"Transcribe each clip's audio with word-level timestamps via the bundled Parakeet TDT model. ASYNC — returns { jobId }; call job_wait. After this, transcript_get returns the merged edited-time transcript.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string", description: "Optional - transcribe only this clip" },
+			},
+		},
+		command: "transcript.transcribe",
+	},
+	{
+		name: "transcript_get",
+		description:
+			"Return the merged edited-time transcript: every word with id, text, startMs, endMs in EDITED-TIMELINE coordinates. Use word IDs as input to transcript_delete_words.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+			},
+		},
+		command: "transcript.get",
+	},
+	{
+		name: "transcript_delete_words",
+		description:
+			"Delete words from the project — internally translates each word's [startMs, endMs] into a trim region the exporter skips. THIS is the editor's 'click word, hit delete' workflow, callable from MCP.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				wordIds: {
+					type: "array",
+					items: { type: "string" },
+					description: "Word IDs from transcript_get",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["wordIds"],
+		},
+		command: "transcript.delete-words",
+	},
+	{
+		name: "transcript_remove_fillers",
+		description: "Auto-detect filler words ('um', 'uh', 'like', 'you know', ...) plus immediately-repeated words and bulk-trim them.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				includeRepeats: { type: "boolean", description: "Default true" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "transcript.remove-fillers",
+	},
+	{
+		name: "transcript_search",
+		description: "Find every occurrence of a phrase in the merged transcript. Returns matches with their word IDs.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				query: { type: "string" },
+			},
+			required: ["query"],
+		},
+		command: "transcript.search",
+	},
+
+	// ── audio ───────────────────────────────────────────────────────
+	{
+		name: "audio_clean",
+		description:
+			"Run DeepFilter denoising on each clip's audio. ASYNC. Writes a sibling .cleaned.wav and points clip.cleanedAudioPath at it; export auto-uses it.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string", description: "Optional - clean only this clip" },
+			},
+		},
+		command: "audio.clean",
+	},
+
+	// ── captions ────────────────────────────────────────────────────
+	{
+		name: "caption_toggle",
+		description: "Enable or disable captions for the whole project. Requires transcript first.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				enabled: { type: "boolean" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["enabled"],
+		},
+		command: "caption.toggle",
+	},
+	{
+		name: "caption_set_template",
+		description: "Pick a caption template: classic, modern, minimal, bold, spotlight, boxed, neon, or colored.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				templateId: { type: "string" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["templateId"],
+		},
+		command: "caption.set-template",
+	},
+
+	// ── motion graphics ─────────────────────────────────────────────
+	{
+		name: "motion_list",
+		description: "List every motion-graphic template (id, name, slots, defaults, aspectRatios). 19 templates ship today.",
+		inputSchema: { type: "object", properties: {} },
+		command: "motion.list",
+	},
+	{
+		name: "motion_themes",
+		description: "List every style-pack theme (color overrides). default, mr-beast, mkbhd, kurzgesagt, veritasium.",
+		inputSchema: { type: "object", properties: {} },
+		command: "motion.themes",
+	},
+	{
+		name: "motion_generate",
+		description:
+			"Render a motion graphic asynchronously. Returns { jobId, outputPath }; call job_wait. Output is an MP4 you can pass to project_add_motion_graphic.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				templateId: { type: "string", description: "From motion_list" },
+				slots: { type: "object", description: "Slot values (theme already resolved)" },
+				aspectRatio: { type: "string", description: "16:9 | 9:16 | 1:1" },
+				outputName: { type: "string", description: "Optional filename stem" },
+			},
+			required: ["templateId", "slots"],
+		},
+		command: "motion.generate",
+	},
+
+	// ── assets ──────────────────────────────────────────────────────
+	{
+		name: "asset_list_sounds",
+		description: "List every bundled sound effect (id, name, category, absolute path).",
+		inputSchema: { type: "object", properties: {} },
+		command: "asset.list-sounds",
+	},
+	{
+		name: "asset_list_fx",
+		description: "List every bundled FX video overlay (id, title, blendMode, defaults, absolute path).",
+		inputSchema: { type: "object", properties: {} },
+		command: "asset.list-fx",
+	},
+
+	// ── project-aware LLM ──────────────────────────────────────────
+	{
+		name: "llm_generate_title",
+		description: "Generate a YouTube-ready title from the project's merged transcript using the bundled local LLM.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				maxChars: { type: "number", description: "Default 70" },
+			},
+		},
+		command: "llm.generate-title",
+	},
+	{
+		name: "llm_generate_description",
+		description: "Generate a YouTube description (3-5 sentences) from the merged transcript.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				maxChars: { type: "number", description: "Default 400" },
+			},
+		},
+		command: "llm.generate-description",
+	},
+	{
+		name: "llm_generate_timestamps",
+		description: "Generate YouTube-style chapter timestamps from the merged transcript.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				maxChapters: { type: "number", description: "Default 8" },
+			},
+		},
+		command: "llm.generate-timestamps",
+	},
+
+	// ── export (the centerpiece) ────────────────────────────────────
+	{
+		name: "export_start",
+		description:
+			"Render the project to MP4 via the same Skia native render-helper the editor's Export button uses. ASYNC — returns { jobId, outputPath }; call job_wait. Honours every region/style/caption/FX/lower-third/motion-graphic.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				outputPath: { type: "string", description: "Where to write the MP4. Default: recordings dir" },
+				quality: { type: "string", description: "draft | standard | high | ultra. Default high" },
+			},
+		},
+		command: "export.start",
+	},
+	{
+		name: "export_list",
+		description: "List every entry in the export library, newest-first.",
+		inputSchema: { type: "object", properties: {} },
+		command: "export.list",
+	},
+
+	// ── preview overlay (v1.9.2) ────────────────────────────────────
+	{
+		name: "preview_show",
+		description:
+			"Pop up a small floating, always-on-top window showing the project's live preview. ~1-2s boot. Singleton — second call reuses the window. Lets you show the user what you just did without them leaving the chat.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				atMs: { type: "number", description: "Start playhead here. Default 0" },
+				autoplay: { type: "boolean", description: "Default true" },
+			},
+		},
+		command: "preview.show",
+	},
+	{
+		name: "preview_seek",
+		description: "Move the open preview overlay's playhead.",
+		inputSchema: {
+			type: "object",
+			properties: { atMs: { type: "number" } },
+			required: ["atMs"],
+		},
+		command: "preview.seek",
+	},
+	{
+		name: "preview_hide",
+		description: "Close the preview overlay.",
+		inputSchema: { type: "object", properties: {} },
+		command: "preview.hide",
+	},
+
+	// ── async jobs ─────────────────────────────────────────────────
+	{
+		name: "job_wait",
+		description:
+			"Block server-side until an async job (transcribe, audio_clean, motion_generate, export_start) reaches a terminal state. Default timeout 60s, max 5 min. Always call this after kicking off async work.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string", description: "Job id from the async tool's response" },
+				timeoutMs: { type: "number", description: "Max wait. Default 60_000, hard-capped at 300_000" },
+			},
+			required: ["id"],
+		},
+		command: "job.wait",
+	},
+	{
+		name: "job_get",
+		description: "Snapshot a job's current status + progress + result without blocking.",
+		inputSchema: {
+			type: "object",
+			properties: { id: { type: "string" } },
+			required: ["id"],
+		},
+		command: "job.get",
+	},
+
+	// ── escape hatch ────────────────────────────────────────────────
+	{
+		name: "pandastudio_call",
+		description:
+			"Generic dispatch — call ANY verb.noun including ones added to PandaStudio after this MCP server version shipped. Use system_list_commands first to discover available commands. Args object is passed through unchanged.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				command: { type: "string", description: "verb.noun, e.g. project.split-clip" },
+				args: { type: "object", description: "Arguments object" },
+			},
+			required: ["command"],
+		},
+		command: null, // handled specially in dispatch
+	},
+];
+
+// ── MCP server boot ───────────────────────────────────────────────────
+
+const server = new Server(
+	{
+		name: "pandastudio",
+		version: "1.9.3",
+	},
+	{
+		capabilities: {
+			tools: {},
+		},
+	},
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+	return {
+		tools: TOOLS.map((t) => ({
+			name: t.name,
+			description: t.description,
+			inputSchema: t.inputSchema,
+		})),
+	};
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+	const tool = TOOLS.find((t) => t.name === request.params.name);
+	if (!tool) {
+		return {
+			content: [{ type: "text", text: `unknown tool: ${request.params.name}` }],
+			isError: true,
+		};
+	}
+
+	const args = request.params.arguments ?? {};
+	let command;
+	let dispatchArgs;
+
+	if (tool.name === "pandastudio_call") {
+		// Escape hatch — caller supplies command + args directly
+		command = args.command;
+		dispatchArgs = args.args ?? {};
+		if (typeof command !== "string" || !command.includes(".")) {
+			return {
+				content: [{ type: "text", text: "pandastudio_call requires `command` of the form 'verb.noun'" }],
+				isError: true,
+			};
+		}
+	} else {
+		command = tool.command;
+		dispatchArgs = args;
+	}
+
+	try {
+		const result = await callPandastudio(command, dispatchArgs);
+		// Format the response for the MCP client. Every tool returns
+		// JSON; we wrap it in a text block so the agent can read it
+		// in their context window. For tools where a structured
+		// content block matters (e.g. preview_show returning an
+		// image), we'd add a richer content array — for now text is
+		// sufficient and matches what `pandastudio --json` returns.
+		return {
+			content: [
+				{
+					type: "text",
+					text: JSON.stringify(result, null, 2),
+				},
+			],
+			isError: result?.ok === false,
+		};
+	} catch (err) {
+		return {
+			content: [{ type: "text", text: `tool error: ${err?.message ?? String(err)}` }],
+			isError: true,
+		};
+	}
+});
+
+// Start stdio transport (the MCP standard for local subprocess
+// servers). For HTTP/SSE transports there's @modelcontextprotocol/
+// sdk/server/sse — overkill for our use case since this server is
+// always spawned by an MCP client (Cursor / Continue / Claude
+// Desktop) on the same machine.
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@writepanda/mcp",
+	"version": "1.9.3",
+	"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",
+		"mcp",
+		"model-context-protocol",
+		"video-editor",
+		"agent",
+		"cursor",
+		"continue",
+		"cline",
+		"claude-desktop"
+	],
+	"author": "Kamala Kannan Sankarraj",
+	"license": "MIT",
+	"homepage": "https://www.writepanda.ai/cli",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kamskans/openscreen.git",
+		"directory": "packages/mcp"
+	},
+	"bugs": {
+		"url": "https://github.com/kamskans/openscreen/issues"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=18"
+	},
+	"bin": {
+		"writepanda-mcp": "./bin/server.mjs"
+	},
+	"files": [
+		"bin",
+		"README.md",
+		"LICENSE"
+	],
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.0.4"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}