creavit-studio-mcp 1.3.1 → 1.3.3

package/README.md

@@ -111,9 +111,15 @@ files directly and work with the app closed.
 `creavit_editor_export`, `creavit_editor_history`
 
 **Appearance** — `creavit_editor_background_get`,
-`creavit_editor_background_set`, `creavit_editor_camera_get`,
+`creavit_editor_background_set`, `creavit_editor_wallpapers`,
+`creavit_editor_wallpaper_set`, `creavit_editor_camera_get`,
 `creavit_editor_camera_set`, `creavit_editor_audio`
 
+> Zoom ranges are normally **not** something you add. Creavit Studio records the
+> real mouse clicks and builds its own auto-zoom segments in the editor; use
+> `creavit_editor_add_zoom` only when the user asks for a zoom at a specific
+> moment.
+
 **Perspective** — `creavit_editor_perspectives`,
 `creavit_editor_add_perspective`, `creavit_editor_update_perspective`,
 `creavit_editor_remove_perspective`
@@ -175,6 +181,9 @@ Use the typed tools instead of guessing generic setting keys:
 ```text
 creavit_editor_background_set  type=solid color=#10131a
 creavit_editor_background_set  type=gradient gradient={type, direction, colors}
+creavit_editor_wallpapers                             categories + sample names
+creavit_editor_wallpapers      category=macos         that category's full list
+creavit_editor_wallpaper_set   name=sonoma-dark       ready-made CMS wallpaper
 creavit_editor_camera_set      settings={visible,size,radius,shadow,mirror,...}
 creavit_editor_audio           action=mute
 creavit_project_save
@@ -204,14 +213,22 @@ 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`, adds
-scroll-highlight zooms, optionally covers the whole video with a perspective
-preset, mutes it, and saves it.
+It trims the timeline to `durationMs`, optionally covers the whole video with a
+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.
+`autoZoom: true` (plus `replaceZooms: true` to wipe the app's own ones) is
+opt-in, for when the user explicitly wants scripted zooms.
 
 When the calling agent has inspected the page, it can pass ordered `steps`
 (`scrollPages`, `dwellMs`, `zoom`, `scale`, `x`, `y`, and optionally
@@ -232,11 +249,13 @@ Example input:
     { "action": "click", "text": "Get Started", "dwellMs": 3000 }
   ],
   "controlSystemMouse": true,
-  "autoZoom": true,
-  "zoomScale": 1.8,
   "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.1",
+	"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.2.0";
+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, adds zooms, optional perspective, and optionally mutes it.",
+				"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"),
@@ -240,16 +254,33 @@ export function browserTools() {
 					tailMs: S.number("Still time after the last scroll (default 800)"),
 					controlSystemMouse: S.bool("Move/click the real macOS mouse so Creavit records native cursor data (default true)"),
 					mute: S.bool("Disable recording audio and mute export clips (default true)"),
-					autoZoom: S.bool("Add zooms around section destinations (default true)"),
-					replaceZooms: S.bool("Remove recorder-created zooms first (default true)"),
+					autoZoom: S.bool("Add scripted zooms around step destinations (default FALSE — the app already creates zooms from the real clicks; only enable when the user asks for it)"),
+					replaceZooms: S.bool("Delete the app's own click-based zooms before adding scripted ones (default false; only meaningful with autoZoom=true)"),
 					zoomScale: S.number("Automatic zoom scale (default 1.7)"),
 					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));
@@ -259,8 +290,12 @@ export function browserTools() {
 				const scrollIntervalMs = Math.max(300, Math.min(15_000, Number(args.scrollIntervalMs) || 1400));
 				const tailMs = Math.max(200, Math.min(30_000, Number(args.tailMs) || 800));
 				const muted = args.mute !== false;
-				const autoZoom = args.autoZoom !== false;
-				const replaceZooms = args.replaceZooms !== false;
+				// Zoom'ları KENDİMİZ eklemiyoruz: Creavit Studio gerçek tıklamaları
+				// kaydedip editörde otomatik zoom segmentlerini kendi üretiyor. Bizim
+				// tahmini zamanlamayla eklediğimiz zoom'lar onların üstüne yanlış oturuyordu.
+				// Sadece kullanıcı açıkça isterse (autoZoom=true) devreye girer.
+				const autoZoom = args.autoZoom === true;
+				const replaceZooms = autoZoom && args.replaceZooms === true;
 				const controlSystemMouse = args.controlSystemMouse !== false;
 				const zoomScale = Math.max(1, Math.min(5, Number(args.zoomScale) || 1.7));
 				const requestedSteps = Array.isArray(args.steps) && args.steps.length ? args.steps : args.sections;
@@ -325,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,
@@ -334,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())));
@@ -351,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 {
@@ -383,9 +431,24 @@ 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 = { muted: false, zooms: [], perspective: null, saved: false, trimmedTo: null };
+					const applied = {
+						muted: false,
+						zooms: [],
+						zoomSource: autoZoom ? "scripted (autoZoom=true)" : "editor auto-zoom from the recorded clicks",
+						perspective: null,
+						saved: false,
+						trimmedTo: null,
+						export: null,
+						openedExport: null,
+					};
 					let finalDuration = Number(editorState.duration);
 					if (durationMs) {
 						const targetDuration = durationMs / 1000;
@@ -421,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 (_) {}
@@ -430,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

@@ -61,14 +61,15 @@ export function editorTools() {
 			name: "creavit_editor_background_set",
 			command: "editor.setBackground",
 			description:
-				"Sets the canvas background. For solid use type='solid' and color. For gradient pass at least two stops as {type:'linear'|'radial', direction:'to-right', colors:[{color:'#...',position:0},...]}. Call creavit_project_save afterwards.",
+				"Sets the canvas background. For solid use type='solid' and color. For gradient pass at least two stops as {type:'linear'|'radial', direction:'to-right', colors:[{color:'#...',position:0},...]}. For a ready-made wallpaper use type='image' with `wallpaper` (name from creavit_editor_wallpapers) — or use creavit_editor_wallpaper_set directly. Call creavit_project_save afterwards.",
 			inputSchema: schema(
 				{
 					type: S.string("Background type", {
 						enum: ["solid", "color", "gradient", "image", "dynamic"],
 					}),
 					color: S.string("CSS color for a solid background"),
-					image: S.string("Image URL or local path"),
+					image: S.string("Image URL, local path, or a CMS wallpaper name"),
+					wallpaper: S.string("CMS wallpaper name (see creavit_editor_wallpapers)"),
 					blur: S.number("Image blur amount"),
 					gradient: S.object(
 						"Gradient configuration: {type, direction, colors:[{color,position}]}.",
@@ -81,6 +82,35 @@ export function editorTools() {
 				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
 		}),
 
+		bridgeTool({
+			name: "creavit_editor_wallpapers",
+			command: "editor.listWallpapers",
+			description:
+				"Lists the ready-made wallpapers (background images from the Creavit CMS) grouped by category. Without arguments it returns the categories with a small sample of names — pass `category` for that category's complete list, or `search` to look a name up. Feed the name to creavit_editor_wallpaper_set.",
+			inputSchema: schema({
+				category: S.string("Only this category, e.g. 'macos'"),
+				search: S.string("Find wallpapers whose name contains this text"),
+				limit: S.number("Maximum number of names to return"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_wallpaper_set",
+			command: "editor.setWallpaper",
+			description:
+				"Sets the canvas background to a CMS wallpaper — exactly what picking one in the UI does. Select it by `name` (from creavit_editor_wallpapers), by `category` + `index`, or with random=true. Call creavit_project_save afterwards.",
+			inputSchema: schema({
+				name: S.string("Wallpaper name, e.g. 'sonoma-dark'"),
+				category: S.string("Category to pick from, e.g. 'macos'"),
+				index: S.number("Zero-based position inside the category"),
+				random: S.bool("Pick a random wallpaper"),
+				blur: S.number("Background blur amount (optional)"),
+			}),
+			timeoutMs: 60_000,
+			mapResult: (result) =>
+				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
+		}),
+
 		bridgeTool({
 			name: "creavit_editor_camera_get",
 			command: "editor.getCamera",
@@ -136,7 +166,7 @@ export function editorTools() {
 			name: "creavit_editor_add_zoom",
 			command: "editor.addZoom",
 			description:
-				"Adds a zoom range. start/end are in seconds and end must be greater than start. scale defaults to 2 (1 means no zoom), x/y default to 0.5 (center). Get the video duration from creavit_editor_state.",
+				"Adds a zoom range MANUALLY. Do NOT use this to 'zoom on the clicks' after a recording — Creavit Studio records the real mouse clicks and builds its own auto-zoom segments in the editor, and hand-added ranges land on estimated times instead. Only call it when the user explicitly asks for a zoom at a specific moment. start/end are in seconds and end must be greater than start. scale defaults to 2 (1 means no zoom), x/y default to 0.5 (center). Get the video duration from creavit_editor_state.",
 			inputSchema: schema(
 				{
 					start: S.number("Start time in seconds"),
@@ -284,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"] }),
@@ -295,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,
 		}),