@writepanda/mcp 1.92.0 → 1.99.0

package/bin/server.mjs

@@ -155,6 +155,26 @@ const TOOLS = [
 		inputSchema: { type: "object", properties: {} },
 		command: "system.status",
 	},
+	{
+		name: "agent_session_list",
+		description:
+			"List the embedded in-app agent's opencode sessions (id, title, created/updated timestamps). Observational only — never starts the agent server; returns running:false when it isn't up. Use before agent_session_stop to find the session to kill.",
+		inputSchema: { type: "object", properties: {} },
+		command: "agent.session-list",
+	},
+	{
+		name: "agent_session_stop",
+		description:
+			"Abort an in-app agent session by id (from agent_session_list), or every session with all:true. Stops that session's tool execution immediately; the transcript survives for replay. The kill switch for a runaway/ghost in-app agent session.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sessionId: { type: "string", description: "Session id to abort." },
+				all: { type: "boolean", description: "Abort every session instead of one." },
+			},
+		},
+		command: "agent.session-stop",
+	},
 	{
 		name: "system_list_commands",
 		description:
@@ -834,7 +854,7 @@ const TOOLS = [
 	{
 		name: "project_add_motion_graphic",
 		description:
-			"Drop a motion-graphic MP4/WebM onto the timeline. PREFERRED: pass `fromJob` (the jobId from motion_render_html / motion_generate / motion_concat) — the server resolves the outputPath internally, so you never handle the path string at all. Fallback: pass `file` (an absolute path) only for external/uploaded files. **Defaults to a `bundled:sound/mouse-click` SFX as the graphic appears** — pass `soundUrl: null` to make it silent, or any other `bundled:sound/<id>` to swap the sound.",
+			"Drop a motion-graphic MP4/WebM onto the timeline. PREFERRED: pass `fromJob` (the jobId from motion_render_html / motion_generate / motion_concat) — the server resolves the outputPath internally, so you never handle the path string at all. Fallback: pass `file` (an absolute path) only for external/uploaded files. Also accepts `file: 'bundled:transition/<id>'` (ids from asset_list_transitions) — the house-opener pattern: a bundled transition placed as an overlay auto-stamps transitionId so it COVER-fits any canvas (a 16:9 sweep fills a 9:16 frame) and carries its SFX via soundUrl. Image files (png/jpg/webp/gif/avif) are detected and render as image overlays; pair `file: <image>` with `layer: 'background'` for a timed BACKGROUND-IMAGE underlay (cover-fills the canvas behind the camera — with a background-effect remove region over the same span, the image replaces the speaker's real background for just that duration). **Defaults to a `bundled:sound/mouse-click` SFX as the graphic appears** — pass `soundUrl: null` to make it silent, or any other `bundled:sound/<id>` to swap the sound.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1203,6 +1223,48 @@ const TOOLS = [
 		},
 		command: "project.add-spotlight",
 	},
+	{
+		name: "project_add_background_effect",
+		description:
+			"Add a BACKGROUND EFFECT region on the camera video: AI person segmentation runs between startMs and endMs and either BLURS the background behind the speaker (mode 'blur' — video-call style) or REMOVES it so the project wallpaper shows through behind them (mode 'remove'). Behaves exactly like a zoom region on the timeline: draggable, trimmable, source-anchored (pass anchorSourceMs when placing from a transcript word so it survives later trims). Camera / talking-head footage only. Preview and export render it identically. Find placed regions via project_read under editor.backgroundEffectRegions[]; retime/restyle with project_update_region (regionType 'background-effect'), delete with project_remove_region.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				atMs: { type: "number", description: "Edited-time start (ms). Or pass startMs." },
+				startMs: { type: "number", description: "Alias for atMs (edited-time start, ms)." },
+				endMs: { type: "number", description: "Edited-time end (ms). Alternative to durationMs." },
+				durationMs: {
+					type: "number",
+					description: "Duration in ms. Default 5000 when neither durationMs nor endMs given.",
+				},
+				mode: {
+					type: "string",
+					enum: ["blur", "remove"],
+					description:
+						'"blur" = person sharp, background gaussian-blurred. "remove" = background cut away; the project wallpaper/background shows through behind the person.',
+				},
+				strength: {
+					type: "number",
+					description:
+						"Blur strength in px sigma at 1080p (mode='blur' only; ignored for 'remove'). 1-120, default 18.",
+				},
+				anchorSourceMs: {
+					type: "number",
+					description:
+						"Anchor to a SOURCE-time moment (transcript word startMs). The region then re-anchors automatically on subsequent trim/speed edits.",
+				},
+				anchorSourceEndMs: {
+					type: "number",
+					description: "Optional anchor end (source ms) for ranged anchoring.",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["mode"],
+		},
+		command: "project.add-background-effect",
+	},
 	{
 		name: "project_update_spotlight",
 		description:
@@ -1281,6 +1343,60 @@ const TOOLS = [
 		},
 		command: "project.render-frame",
 	},
+	{
+		name: "project_render_sheet",
+		description:
+			"Render N preview frames sampled across an edited-time range and tile them into ONE contact-sheet PNG (row-major grid). THE verification tool for pacing and motion: one call + one image read shows caption changes, zoom ramps, overlay mutations, and dead stretches — use this instead of N sequential project_render_frame calls. Returns { sheetPath, cols, rows, frames: [{index,row,col,atMs,timeMs,path}] }; per-cell timestamps come from the frames array (cell k = frames[k], left-to-right then top-to-bottom). Every frame's seek is verified — no stale frames. If tiling is unavailable, sheetPath is null and frames[].path are readable individually.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				fromMs: { type: "number", description: "Range start, edited ms. Default 0." },
+				toMs: { type: "number", description: "Range end, edited ms. Default: edited end." },
+				count: { type: "number", description: "Frames sampled evenly. Default 12, max 24." },
+				cols: { type: "number", description: "Grid columns. Default 4." },
+				outPath: { type: "string", description: "Optional sheet PNG output path." },
+			},
+		},
+		command: "project.render-sheet",
+	},
+	{
+		name: "project_apply_edit_plan",
+		description:
+			'Apply a whole editing plan in ONE call: a JSON array of timeline ops, applied atomically (single read, all ops, single save; any invalid op aborts with nothing written). Supported ops: {"op":"add-trim","startMs","endMs"} | {"op":"add-zoom","atMs","durationMs","depth?","focusX?","focusY?","soundUrl?","anchorSourceMs?"} | {"op":"add-speed","startMs","endMs","speed"}. ALWAYS prefer this over sequential project_add_trim/zoom/speed calls when executing a beat map — it replaces 20+ round-trips with one.',
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				plan: {
+					type: "string",
+					description:
+						'JSON array of ops, e.g. [{"op":"add-trim","startMs":1000,"endMs":1400},{"op":"add-zoom","atMs":5000,"durationMs":2500,"depth":2}]',
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["plan"],
+		},
+		command: "project.apply-edit-plan",
+	},
+	{
+		name: "audio_probe",
+		description:
+			'EARS without exporting: per-clip audio stats from the export-relevant track (cleanedAudioPath when present, else source). Returns hasAudio, mean/max volume (dB), detected silence spans (clip-SOURCE time), and the project audio overlays (music beds) — verify "is there dead air / is the level sane / did my music land" before export. Synchronous, a few seconds per clip.',
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string", description: "Optional — probe only this clip." },
+				noiseDb: { type: "number", description: "Silence threshold dBFS. Default -30." },
+				minSilenceSec: { type: "number", description: "Min silence to report, sec. Default 0.5." },
+			},
+		},
+		command: "audio.probe",
+	},
 	{
 		name: "project_set_region_sound",
 		description:
@@ -1460,7 +1576,8 @@ const TOOLS = [
 				},
 				expectedRevision: {
 					type: "number",
-					description: "Revision from your last project_read. Strongly recommended in overwrite mode.",
+					description:
+						"Revision from your last project_read. Strongly recommended in overwrite mode.",
 				},
 			},
 		},
@@ -1549,7 +1666,7 @@ const TOOLS = [
 	{
 		name: "project_remove_region",
 		description:
-			"Delete an existing region (zoom, trim, speed, annotation, fx, overlay, clip-transform, audio-overlay) by its id. Use project_read to find region ids — visual regions live under editor.*Regions; audio overlays live under audioOverlays[]. If the region belongs to a link group (designed-segment pair: a clip-transform parking the camera into one half + the panel motion-graphic on the other half), deleting either half also removes its peer so the pair stays coherent. Returns the updated project.",
+			"Delete an existing region (zoom, trim, speed, annotation, fx, overlay, clip-transform, background-effect, audio-overlay) by its id. Use project_read to find region ids — visual regions live under editor.*Regions; audio overlays live under audioOverlays[]. If the region belongs to a link group (designed-segment pair: a clip-transform parking the camera into one half + the panel motion-graphic on the other half), deleting either half also removes its peer so the pair stays coherent. Returns the updated project.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1558,7 +1675,7 @@ const TOOLS = [
 				regionType: {
 					type: "string",
 					description:
-						"zoom | trim | speed | annotation | fx | overlay | clip-transform | audio-overlay",
+						"zoom | trim | speed | annotation | fx | overlay | clip-transform | background-effect | audio-overlay",
 				},
 				regionId: { type: "string", description: "id of the region to delete" },
 				expectedRevision: { type: "number" },
@@ -1589,7 +1706,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, focusMode: 'static'|'auto' — set 'auto' for the cursor-follow camera), trim (startMs, endMs), speed (startMs, endMs, speed), fx (atMs, durationMs, opacity, blendMode, speed), annotation, overlay, clip-transform (startMs, endMs, preset, transitionMs), and audio-overlay (startMs, endMs, sourceStartMs, volume — lets you drag-trim an audio overlay without removing it). Time shifts on a link-grouped region (e.g. one half of a designed segment) propagate to every peer in the group so the pair stays coherent.",
+			"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. Overlay geometry (x/y/width/height) is PERCENT of canvas 0-100; values <= 1 are treated as 0-1 fractions and scaled. Works on zoom (depth, focusX, focusY, focusMode: 'static'|'auto' — set 'auto' for the cursor-follow camera), trim (startMs, endMs), speed (startMs, endMs, speed), fx (atMs, durationMs, opacity, blendMode, speed), annotation, overlay, clip-transform (startMs, endMs, preset, transitionMs), background-effect (startMs, endMs, mode: 'blur'|'remove', strength), and audio-overlay (startMs, endMs, sourceStartMs, volume — lets you drag-trim an audio overlay without removing it). Time shifts on a link-grouped region (e.g. one half of a designed segment) propagate to every peer in the group so the pair stays coherent.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1598,7 +1715,7 @@ const TOOLS = [
 				regionType: {
 					type: "string",
 					description:
-						"zoom | trim | speed | annotation | fx | overlay | clip-transform | audio-overlay",
+						"zoom | trim | speed | annotation | fx | overlay | clip-transform | background-effect | audio-overlay",
 				},
 				regionId: { type: "string", description: "id of the region to update" },
 				patch: {
@@ -2012,7 +2129,7 @@ const TOOLS = [
 	{
 		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. For a PODCAST composite, each word also carries `speaker` ('host' = speaker 1 / mediaPath, 'guest' = speaker 2 / webcamPath) — use these spans to drive project_set_clip_layout (cut to whoever is talking).",
+			"Return the merged transcript. Each word carries BOTH time bases: startMs/endMs are SOURCE time (the raw recording; use for anchorSourceMs), and editedStartMs/editedEndMs are EDITED-timeline time with trims/speeds applied (null = the word sits inside a trim). Read the base you need; no conversion calls required. Word IDs feed transcript_delete_words. For a PODCAST composite, each word also carries `speaker` ('host' = speaker 1 / mediaPath, 'guest' = speaker 2 / webcamPath) — use these spans to drive project_set_clip_layout (cut to whoever is talking).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2100,7 +2217,7 @@ const TOOLS = [
 	{
 		name: "transcript_find_issues",
 		description:
-			"Scan the transcript for editorial problems the speaker created and recovered from: **duplicate-take** (a line re-recorded later — keep the cleaner second take, cut the first), **false-start** (an abandoned fragment before a restart), and **adjacent-repeat** (a stutter like 'the the'). Returns candidate `issues`, each with `type`, `severity`, the `wordIds` of the DISCARDED attempt (pass straight to transcript.delete-words), the edited-time span, the offending `text`, and a `note` explaining what's kept. CONSERVATIVE and read-only — it never edits; review each candidate against context before deleting, since some repeats are intentional. Run this after transcribe + remove-fillers as the content-cleanup pass. Filter with `types` (comma-separated) and cap with `limit`.",
+			"Scan the transcript for editorial problems the speaker created and recovered from: **duplicate-take** (a line re-recorded later — keep the cleaner second take, cut the first), **false-start** (an abandoned fragment before a restart), and **adjacent-repeat** (a stutter like 'the the'). Returns candidate `issues`, each with `type`, `severity`, the `wordIds` of the DISCARDED attempt (pass straight to transcript.delete-words), the edited-time span, the offending `text`, and a `note` explaining what's kept. CONSERVATIVE and read-only — it never edits. Deliberate parallel structure ('one for transcription, one for outreach') is NOT flagged as a false start, and lone stopword repeats across pause tokens are skipped. A `severity: \"low\"` false-start is a REVIEW candidate (the restart diverges from the fragment — possibly an intentional list): KEEP it by default unless context clearly shows a flubbed take. Review every candidate against context before deleting. Run this after transcribe + remove-fillers as the content-cleanup pass. Filter with `types` (comma-separated) and cap with `limit`.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2119,7 +2236,7 @@ const TOOLS = [
 	{
 		name: "transcript_find_replace",
 		description:
-			"Find the first occurrence of a phrase in the transcript and replace it with new text. Useful for correcting mis-transcribed names, technical terms, or brand names without re-transcribing. Returns { matched, replacements } — matched is false if the phrase wasn't found.",
+			"Find every occurrence of a phrase in the transcript and replace it with new text. Useful for correcting mis-transcribed names, technical terms, or brand names without re-transcribing. Timing is preserved — only the displayed/exported text changes. Returns { replacedCount, wordsPatched }; replacedCount is 0 if the phrase wasn't found.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2128,7 +2245,7 @@ const TOOLS = [
 				find: {
 					type: "string",
 					description:
-						'Phrase to search for. Case-insensitive; digits and punctuation are ignored on both sides, so "than60" and "than" both match the word "than60". A pure-number/punctuation phrase can\'t be targeted (it normalizes to empty) — include a letter word.',
+						'Phrase to search for. Case-insensitive; punctuation is ignored. Digits are SIGNIFICANT when the phrase contains them ("try30" matches only the token "try30") and ignored otherwise ("than" also matches "than60"). A multi-word phrase also matches a single merged STT token ("Wispr Flow" as one token; "of $499" matches "of$499"), and a phrase equal to a token\'s raw text always matches — so space/digit/punctuation-bearing tokens (even pure numbers like "30%") are all targetable.',
 				},
 				replace: { type: "string", description: "Replacement text (replaces the whole phrase)" },
 				expectedRevision: { type: "number" },
@@ -2222,7 +2339,7 @@ const TOOLS = [
 	{
 		name: "caption_set_style",
 		description:
-			"Override specific style properties of the caption overlay without changing the template. All fields are optional — pass only what you want to change. positionY controls vertical placement (0=top, 100=bottom, default 85). fontFamily sets the caption font (a system font like 'Georgia' or a loaded custom font; unloaded fonts fall back). fontSize is in REM (e.g. '2.6rem'), matching the editor's Font size slider; it is clamped to 1.0–5.0rem (a px value is converted to rem), so you can't exceed the editor's max.",
+			"Override specific style properties of the caption overlay without changing the template. All fields are optional — pass only what you want to change. positionY controls vertical placement in PERCENT of frame height (0=top, 100=bottom, default 85; a 0-1 fraction like 0.85 is auto-converted to percent). fontFamily sets the caption font (a system font like 'Georgia' or a loaded custom font; unloaded fonts fall back). fontSize is in REM (e.g. '2.6rem'), matching the editor's Font size slider; it is clamped to 1.0–5.0rem (a px value is converted to rem), so you can't exceed the editor's max.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2232,7 +2349,11 @@ const TOOLS = [
 					type: "number",
 					description: "Max words shown at once. Default varies by template.",
 				},
-				positionY: { type: "number", description: "Vertical position 0-100. Default 85." },
+				positionY: {
+					type: "number",
+					description:
+						"Vertical position as percent of frame height from the top (0-100). Default 85. Fractions \u2264 1.0 (e.g. 0.85) are treated as 0-1 and converted to percent.",
+				},
 				fontFamily: {
 					type: "string",
 					description:
@@ -2384,7 +2505,7 @@ const TOOLS = [
 	{
 		name: "motion_generate",
 		description:
-			"Render a bundled template by id with your own slot values (text, colors, list items) and a background mode, then add the result to the timeline with project_add_motion_graphic (or project_add_designed_segment for split-panel). Async — returns { jobId, outputPath }; call job_wait, then pass that jobId as `fromJob` to the add tool. Discover templates + slots with motion_list. Prefer this over motion_render_html whenever a bundled template fits the brief — it's faster and already designed.",
+			"Render a bundled template by id with your own slot values (text, colors, list items) and a background mode, then add the result to the timeline with project_add_motion_graphic (or project_add_designed_segment for split-panel). Async — returns { jobId, outputPath }; call job_wait, then pass that jobId as `fromJob` to the add tool. Discover templates + slots with motion_list. Prefer this over motion_render_html whenever a bundled template fits the brief — it's faster and already designed. The same automatic quality gates as motion_render_html apply (pre-render contract lint; STATIC_RENDER on frozen output).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2457,7 +2578,7 @@ const TOOLS = [
 	{
 		name: "motion_render_html",
 		description:
-			"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.",
+			"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). Renders queue automatically and execute serially in submission order — fire multiple renders back-to-back without waiting, then job_wait each. RENDER_BUSY appears only past a 16-deep runaway ceiling. Two automatic quality gates apply: a pre-render lint rejects contract violations (unpaused timeline, repeat:-1, Math.random, missing __timelines registration, shadow/blur radii over 500px), and a post-render check fails any clip frozen for 90%+ of its duration with STATIC_RENDER (fix the composition; never place a gated clip). Async — returns { jobId, outputPath }; poll job_wait for the final file.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2933,7 +3054,7 @@ const TOOLS = [
 const server = new Server(
 	{
 		name: "pandastudio",
-		version: "1.71.0",
+		version: "1.72.0",
 	},
 	{
 		capabilities: {

package/package.json

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