creavit-studio-mcp 1.3.2 → 1.3.3

package/README.md

@@ -213,13 +213,17 @@ composited in.
 
 ### Record a URL walkthrough
 
-`creavit_record_url_walkthrough` is the high-level workflow. By default it opens
+`creavit_record_url_walkthrough` is the high-level, atomic workflow. Use one call
+instead of separate browser/start/interact/stop calls so client round trips and
+retries cannot create gaps or duplicate recordings. By default it opens
 the URL in a frameless site-only capture window (`16:9`, `4:3`, `1:1`, `9:16`,
 or another requested ratio) and waits for the DOM, fonts, and images before
 recording. It then executes ordered semantic actions with the real macOS mouse,
 so the normal Creavit custom-cursor track receives authentic move/click events.
 It trims the timeline to `durationMs`, optionally covers the whole video with a
-perspective preset, mutes it, and saves it.
+perspective preset, mutes it, and saves it. With `export: true`, the tool starts
+the render in the background and returns promptly; `openExport: true` opens the
+video automatically when rendering finishes, without requiring export UI.
 
 It does **not** add zoom ranges: the app records the real clicks and generates
 its own auto-zoom segments in the editor, which land on the actual click times.
@@ -247,7 +251,11 @@ Example input:
   "controlSystemMouse": true,
   "perspective": true,
   "perspectiveTemplate": "minimal-tilt",
-  "mute": true
+  "mute": true,
+  "export": true,
+  "exportResolution": "1080p",
+  "exportFps": 60,
+  "openExport": true
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "creavit-studio-mcp",
-	"version": "1.3.2",
+	"version": "1.3.3",
 	"description": "MCP server that lets AI coding agents (Claude Code, Codex, Cursor) drive the Creavit Studio screen recording app",
 	"keywords": [
 		"mcp",

package/src/protocol.mjs

@@ -6,7 +6,7 @@ export const ENDPOINT_FILENAME = "agent-bridge.json";
 
 export const MCP_PROTOCOL_VERSION = "2024-11-05";
 export const SERVER_NAME = "creavit-studio";
-export const SERVER_VERSION = "1.3.1";
+export const SERVER_VERSION = "1.3.2";
 
 export const JSONRPC_ERRORS = {
 	PARSE_ERROR: -32700,

package/src/rpcServer.mjs

@@ -40,6 +40,8 @@ export function startRpcServer({ listTools, callTool }) {
 				protocolVersion: MCP_PROTOCOL_VERSION,
 				capabilities: { tools: { listChanged: false } },
 				serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+				instructions:
+					"Plan the complete Creavit tool sequence before the first call, then execute it without unnecessary pauses. For any website workflow that includes open + record + multiple interactions + stop, use creavit_record_url_walkthrough once instead of separate browser/recording calls; it can also start export in the background and open the result when ready. Mutating recording/export calls are idempotent, so do not stop/restart merely because a client-side timeout made the result uncertain—check creavit_recording_status or creavit_events.",
 			};
 		},
 

package/src/tools/browserTools.mjs

@@ -135,6 +135,9 @@ function trimSegmentsToDuration(segments, targetDuration) {
 }
 
 export function browserTools() {
+	let activeUrlWalkthroughPromise = null;
+	let recentUrlWalkthrough = null;
+
 	return [
 		bridgeTool({
 			name: "creavit_browser_open",
@@ -165,6 +168,17 @@ export function browserTools() {
 			),
 		}),
 
+		bridgeTool({
+			name: "creavit_browser_activate",
+			command: "browser.activate",
+			description:
+				"Brings the capture window or external browser to the foreground without changing its size or entering fullscreen. Call immediately after recording starts if you are driving the recording manually.",
+			inputSchema: schema({
+				captureWindowId: S.number("Clean capture window ID"),
+				browser: S.string("External browser name when there is no captureWindowId"),
+			}),
+		}),
+
 		bridgeTool({
 			name: "creavit_browser_focus",
 			command: "browser.focusPoint",
@@ -220,7 +234,7 @@ export function browserTools() {
 		{
 			name: "creavit_record_url_walkthrough",
 			description:
-				"Records a site in a clean configurable-ratio window after real page readiness. It can execute ordered semantic steps using the real system mouse, trims to an exact duration, applies optional perspective, and optionally mutes it. Zooms are NOT added: Creavit Studio records the real clicks and generates its own auto-zoom segments in the editor. Only pass autoZoom=true when the user explicitly asks for extra scripted zooms.",
+				"USE THIS SINGLE ATOMIC TOOL for requests that open a website, record several clicks/types, stop, and optionally export/open the video. Do not split that workflow into manual browser + recording calls: this tool prevents duplicate recordings and agent round-trip gaps. It opens a non-fullscreen configurable-ratio window, waits for real page readiness, keeps camera off, defaults microphone/system audio off, executes ordered semantic steps, and can export/open the final video. Zooms are NOT added: Creavit Studio records the real clicks and generates its own auto-zoom segments in the editor. Only pass autoZoom=true when the user explicitly asks for extra scripted zooms.",
 			inputSchema: schema(
 				{
 					url: S.string("http(s) page to record"),
@@ -246,10 +260,27 @@ export function browserTools() {
 					perspective: S.bool("Apply perspective to the complete result"),
 					perspectiveTemplate: S.string("Perspective template id (default minimal-tilt)"),
 					save: S.bool("Save the generated project after editing (default true)"),
+					export: S.bool("Start export in the background after recording/editing (default false)"),
+					exportFilePath: S.string("Optional absolute target .mp4 path; defaults beside the .crvt project"),
+					exportResolution: S.string("Export resolution (default 1080p)"),
+					exportFps: S.number("Export frame rate (default 60)"),
+					exportQuality: S.string("Export quality (default high)", {
+						enum: ["compact", "high", "max"],
+					}),
+					openExport: S.bool("Open the exported video when finished (default true when export=true)"),
 				},
 				["url"],
 			),
-			run: async (args) => {
+			run: (args) => {
+				const requestKey = JSON.stringify(args || {});
+				if (
+					recentUrlWalkthrough?.key === requestKey &&
+					Date.now() < recentUrlWalkthrough.expiresAt
+				) {
+					return Promise.resolve(recentUrlWalkthrough.result);
+				}
+				if (activeUrlWalkthroughPromise) return activeUrlWalkthroughPromise;
+				const operation = (async () => {
 				const browser = canonicalBrowser(args.browser || "Zen Browser");
 				const cleanWindow = args.cleanWindow !== false;
 				const loadWaitMs = Math.max(0, Math.min(60_000, Number(args.loadWaitMs) || 1500));
@@ -329,7 +360,7 @@ export function browserTools() {
 					}
 					const browserWindow = await waitForBrowserWindow(captureWindowId ? "Creavit Studio" : browser, titleHint, 20_000);
 
-					await callCommand("recording.start", {
+					const startResult = await callCommand("recording.start", {
 						options: {
 							startScreen: true,
 							cameraEnabled: false,
@@ -338,7 +369,19 @@ export function browserTools() {
 							recordingSource: { type: "window", windowId: browserWindow.id, windowInfo: browserWindow },
 						},
 					}, 180_000);
+					if (startResult?.started === false) {
+						throw new Error(
+							"A recording is already active. Stop it before starting a URL walkthrough.",
+						);
+					}
 					recordingStarted = true;
+					// recording.start briefly focuses the recorder controls. Restore the
+					// requested browser immediately so the actual walkthrough is visibly
+					// in front from the first recorded frame onward.
+					await callCommand("browser.activate", {
+						captureWindowId,
+						browser: captureWindowId ? undefined : browser,
+					});
 					const recordingStartedAt = Date.now();
 					const contentDeadline = durationMs ? recordingStartedAt + durationMs - tailMs : Number.POSITIVE_INFINITY;
 					await sleep(Math.min(leadInMs, Math.max(0, contentDeadline - Date.now())));
@@ -355,6 +398,7 @@ export function browserTools() {
 								selector: section.selector,
 								text: section.text,
 								value: section.value,
+								useSystemCursor: controlSystemMouse,
 							}, 30_000);
 							if (Number.isFinite(interaction?.x)) focus = { x: interaction.x, y: interaction.y };
 						} else {
@@ -387,6 +431,12 @@ export function browserTools() {
 					}
 					await callCommand("recording.stop", {}, 600_000);
 					recordingStarted = false;
+					// The source is finalized now. Closing it before editor processing/export
+					// avoids leaving a stale capture window over the foreground app.
+					if (captureWindowId) {
+						await callCommand("browser.close", { captureWindowId });
+						captureWindowId = null;
+					}
 
 					const editorState = await waitForEditor(previousEditor?.projectFilePath, 600_000);
 					const applied = {
@@ -396,6 +446,8 @@ export function browserTools() {
 						perspective: null,
 						saved: false,
 						trimmedTo: null,
+						export: null,
+						openedExport: null,
 					};
 					let finalDuration = Number(editorState.duration);
 					if (durationMs) {
@@ -432,7 +484,24 @@ export function browserTools() {
 						await callCommand("editor.saveProject", {}, 180_000);
 						applied.saved = true;
 					}
-					return textResult({ ok: true, url: args.url, browser: cleanWindow ? "Creavit Capture" : browser, cleanWindow, page: openResult, window: browserWindow, duration: finalDuration, rawDuration: editorState.duration, projectFilePath: editorState.projectFilePath, applied });
+					if (args.export === true) {
+						const exportResult = await callCommand(
+							"editor.export.start",
+							{
+								...(args.exportFilePath ? { filePath: args.exportFilePath } : {}),
+								format: "mp4",
+								resolution: args.exportResolution || "1080p",
+								fps: Math.max(1, Math.min(120, Math.round(Number(args.exportFps) || 60))),
+								quality: args.exportQuality || "high",
+								openWhenFinished: args.openExport !== false,
+							},
+							30_000,
+						);
+						applied.export = exportResult;
+						applied.openedExport =
+							args.openExport !== false ? "scheduled when export finishes" : null;
+					}
+					return textResult({ ok: true, url: args.url, browser: cleanWindow ? "Creavit Capture" : browser, cleanWindow, page: openResult, window: browserWindow, duration: finalDuration, rawDuration: editorState.duration, projectFilePath: editorState.projectFilePath, exportStartedInBackground: applied.export?.started === true, exportJob: applied.export?.job || null, applied });
 				} finally {
 					if (recordingStarted) {
 						try { await callCommand("recording.stop", {}, 600_000); } catch (_) {}
@@ -441,6 +510,20 @@ export function browserTools() {
 						try { await callCommand("browser.close", { captureWindowId }); } catch (_) {}
 					}
 				}
+				})();
+				activeUrlWalkthroughPromise = operation;
+				return operation.then((result) => {
+					recentUrlWalkthrough = {
+						key: requestKey,
+						result,
+						expiresAt: Date.now() + 60_000,
+					};
+					return result;
+				}).finally(() => {
+					if (activeUrlWalkthroughPromise === operation) {
+						activeUrlWalkthroughPromise = null;
+					}
+				});
 			},
 		},
 	];

package/src/tools/editorTools.mjs

@@ -314,7 +314,7 @@ export function editorTools() {
 			name: "creavit_editor_export",
 			command: "editor.export",
 			description:
-				"Exports the video. This takes a LONG time (minutes). Follow progress with creavit_events (export.started / export.finished / export.failed). Omitted settings fall back to whatever is selected in the editor.",
+				"Exports the video idempotently; concurrent retries share one render. This takes a LONG time (minutes). Follow progress with creavit_events (export.started / export.finished / export.failed), then use creavit_file_open when the user asks to open/play it. If filePath is omitted, the export is written beside the open .crvt project.",
 			inputSchema: schema({
 				filePath: S.string("Target file path (.mp4)"),
 				format: S.string("mp4 or gif", { enum: ["mp4", "gif"] }),
@@ -325,6 +325,22 @@ export function editorTools() {
 			timeoutMs: 3_600_000,
 		}),
 
+		bridgeTool({
+			name: "creavit_editor_export_start",
+			command: "editor.export.start",
+			description:
+				"Starts one export in the background and returns immediately. Use this when tool latency matters. Progress/completion is reported by creavit_events; set openWhenFinished=true to open/play the result automatically without showing export UI.",
+			inputSchema: schema({
+				filePath: S.string("Target file path (.mp4); omit to export beside the project"),
+				format: S.string("mp4 or gif", { enum: ["mp4", "gif"] }),
+				resolution: S.string("e.g. 720p, 1080p, 4k"),
+				fps: S.number("Frame rate, e.g. 30 or 60"),
+				quality: S.string("compact | high | max"),
+				openWhenFinished: S.bool("Open the exported file automatically when rendering completes"),
+			}),
+			timeoutMs: 30_000,
+		}),
+
 		{
 			name: "creavit_editor_history",
 			description: "Undoes the last editor change, or redoes it.",

package/src/tools/projectTools.mjs

@@ -71,6 +71,14 @@ export function projectTools() {
 			inputSchema: schema({ filePath: S.string("Absolute path to the file") }, ["filePath"]),
 		}),
 
+		bridgeTool({
+			name: "creavit_file_open",
+			command: "project.openFile",
+			description:
+				"Opens an existing exported video or other file with its default macOS application. Use this after creavit_editor_export when the user asks to open/play the result.",
+			inputSchema: schema({ filePath: S.string("Absolute path to the file") }, ["filePath"]),
+		}),
+
 		bridgeTool({
 			name: "creavit_project_save",
 			command: "editor.saveProject",

package/src/tools/systemTools.mjs

@@ -74,7 +74,7 @@ export function systemTools() {
 			name: "creavit_recording_start",
 			command: "recording.start",
 			description:
-				"Starts a screen recording. Get source IDs from creavit_devices_list first. Monitor with creavit_recording_status, and finish with creavit_recording_stop.",
+				"Starts a screen recording idempotently: retries while starting share the same native operation, and calling it while active does not restart. Get source IDs from creavit_devices_list first. For a multi-step website recording, use ONE creavit_record_url_walkthrough call instead of this manual tool.",
 			inputSchema: schema({
 				options: S.object(
 					"Recording options: {sourceType:'display'|'window'|'area', sourceId, cameraEnabled, micEnabled, systemAudioEnabled, delayMs, area:{x,y,width,height}}. cameraEnabled:false also turns the camera off and hides its window, so it does not appear in a screen recording; cameraEnabled:true opens and starts it.",
@@ -88,7 +88,7 @@ export function systemTools() {
 			name: "creavit_recording_stop",
 			command: "recording.stop",
 			description:
-				"Stops the recording. Processing can take a few minutes; the editor opens automatically when it finishes. Track progress with creavit_events (watch for recording.stopped and project.loaded).",
+				"Stops the recording idempotently. Processing can take a few minutes; concurrent retries share the same operation and the editor opens automatically when it finishes. Track progress with creavit_events (watch for recording.stopped and project.loaded).",
 			inputSchema: schema(),
 			timeoutMs: 600_000,
 		}),