creavit-studio-mcp 1.0.0 → 1.1.0

package/README.md

@@ -50,14 +50,14 @@ npx creavit-studio-mcp --doctor
 ```
 
 ```
-creavit-studio v1.0.0
+creavit-studio v1.1.0
 
-✓ 34 MCP tools defined
+✓ 46 MCP tools defined
 ✓ Offline project reading available (.crvt files readable without the app)
 ✓ Connected to the app (v3.0.5, pid 61068)
   Open windows: 2
   Agent-connected renderers: main, editor
-✓ 41 bridge commands available
+✓ 52 bridge commands available
 
 Everything looks good.
 ```
@@ -110,9 +110,20 @@ files directly and work with the app closed.
 `creavit_editor_playback`, `creavit_editor_screenshot`,
 `creavit_editor_export`, `creavit_editor_history`
 
+**Appearance** — `creavit_editor_background_get`,
+`creavit_editor_background_set`, `creavit_editor_camera_get`,
+`creavit_editor_camera_set`, `creavit_editor_audio`
+
+**Perspective** — `creavit_editor_perspectives`,
+`creavit_editor_add_perspective`, `creavit_editor_update_perspective`,
+`creavit_editor_remove_perspective`
+
 **Recording** — `creavit_devices_list`, `creavit_recording_status`,
 `creavit_recording_start`, `creavit_recording_stop`
 
+**Browser walkthrough** — `creavit_browser_open`, `creavit_browser_scroll`,
+`creavit_record_url_walkthrough`
+
 **Escape hatches** — `creavit_capabilities`, `creavit_call`, `creavit_ipc`,
 `creavit_eval`, `creavit_logs`
 
@@ -135,6 +146,52 @@ creavit_editor_screenshot     VERIFY the result
 creavit_project_save          persist
 ```
 
+### Background, camera, and mute
+
+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_camera_set      settings={visible,size,radius,shadow,mirror,...}
+creavit_editor_audio           action=mute
+creavit_project_save
+```
+
+`creavit_editor_audio action=mute` changes both preview audio and every clip's
+timeline volume, so the saved project also exports without source audio.
+
+### Record a URL walkthrough
+
+`creavit_record_url_walkthrough` is the high-level workflow. It opens the URL,
+selects that browser window, records a smooth section-by-section scroll, opens
+the generated project, adds scroll-highlight zooms, optionally covers the whole
+video with a perspective preset, mutes it, and saves it.
+
+When the calling agent has inspected the page, it can pass `sections` entries
+(`scrollPages`, `dwellMs`, `zoom`, `scale`, `x`, `y`) to dwell on and frame the
+important parts instead of using the generic evenly spaced scroll plan.
+
+Example input:
+
+```json
+{
+  "url": "https://example.com",
+  "browser": "Zen Browser",
+  "scrollCount": 5,
+  "scrollIntervalMs": 1800,
+  "autoZoom": true,
+  "zoomScale": 1.8,
+  "perspective": true,
+  "perspectiveTemplate": "minimal-tilt",
+  "mute": true
+}
+```
+
+For hand-directed recordings, use `creavit_browser_open`,
+`creavit_recording_start`, and `creavit_browser_scroll` separately, then add
+zooms/perspective with the editor tools.
+
 Two things worth knowing:
 
 - **Wait for the load.** After `creavit_project_open`, poll `creavit_editor_state`
@@ -151,6 +208,8 @@ Two things worth knowing:
 - Every request requires a bearer token, regenerated on each app launch.
 - The endpoint file is written with `0600` permissions.
 - Arbitrary code execution (`creavit_eval`) is **off by default**.
+- Browser scrolling uses macOS Accessibility. Enable Creavit Studio under
+  **System Settings → Privacy & Security → Accessibility** when macOS asks.
 
 ### Environment variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "creavit-studio-mcp",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"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.0.0";
+export const SERVER_VERSION = "1.1.0";
 
 export const JSONRPC_ERRORS = {
 	PARSE_ERROR: -32700,

package/src/tools/browserTools.mjs

@@ -0,0 +1,336 @@
+// MCP araçları — tarayıcı açma/scroll ve uçtan uca URL walkthrough kaydı.
+
+import { bridgeTool, schema, S, textResult } from "./defineTool.mjs";
+import { callCommand } from "../bridgeClient.mjs";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const BROWSER_APP_NAMES = {
+	zen: "Zen Browser",
+	"zen browser": "Zen Browser",
+	safari: "Safari",
+	chrome: "Google Chrome",
+	"google chrome": "Google Chrome",
+	arc: "Arc",
+	firefox: "Firefox",
+	brave: "Brave Browser",
+	"brave browser": "Brave Browser",
+};
+
+function canonicalBrowser(value) {
+	const key = String(value || "zen").trim().toLowerCase();
+	return BROWSER_APP_NAMES[key] || value;
+}
+
+function windowList(result) {
+	if (Array.isArray(result)) return result;
+	if (Array.isArray(result?.windows)) return result.windows;
+	return [];
+}
+
+function searchableWindowText(windowInfo) {
+	return [
+		windowInfo?.appName,
+		windowInfo?.ownerName,
+		windowInfo?.name,
+		windowInfo?.title,
+		windowInfo?.windowTitle,
+	]
+		.filter(Boolean)
+		.join(" ")
+		.toLowerCase();
+}
+
+function findBrowserWindow(windows, browserName, titleContains) {
+	const browserNeedle = String(browserName || "").toLowerCase();
+	const titleNeedle = String(titleContains || "").trim().toLowerCase();
+	const candidates = windows.filter((entry) => {
+		const text = searchableWindowText(entry);
+		return text.includes(browserNeedle) ||
+			(browserNeedle === "google chrome" && text.includes("chrome")) ||
+			(browserNeedle === "zen browser" && text.includes("zen"));
+	});
+	if (titleNeedle) {
+		const titled = candidates.find((entry) => searchableWindowText(entry).includes(titleNeedle));
+		if (titled) return titled;
+	}
+	return candidates.find((entry) => entry?.isOnScreen !== false && Number(entry?.id) > 0) ||
+		candidates.find((entry) => Number(entry?.id) > 0) ||
+		null;
+}
+
+async function waitForBrowserWindow(browserName, titleContains, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	let lastWindows = [];
+	while (Date.now() < deadline) {
+		const devices = await callCommand("devices.list", { kinds: ["windows"] }, 60_000);
+		lastWindows = windowList(devices?.windows);
+		const found = findBrowserWindow(lastWindows, browserName, titleContains);
+		if (found) return found;
+		await sleep(500);
+	}
+	throw new Error(
+		`Could not find a recordable ${browserName} window. Opened windows: ${lastWindows
+			.map((entry) => searchableWindowText(entry))
+			.filter(Boolean)
+			.slice(0, 12)
+			.join(" | ")}`,
+	);
+}
+
+async function waitForEditor(timeoutMs = 300_000) {
+	const deadline = Date.now() + timeoutMs;
+	let lastError = null;
+	while (Date.now() < deadline) {
+		try {
+			const state = await callCommand("editor.getState", {}, 15_000);
+			if (Number(state?.duration) > 0 && state?.playerMounted) return state;
+		} catch (error) {
+			lastError = error;
+		}
+		await sleep(1000);
+	}
+	throw new Error(
+		`Recording finished but the editor did not become ready within ${Math.round(timeoutMs / 1000)}s${
+			lastError ? `: ${lastError.message}` : ""
+		}`,
+	);
+}
+
+async function clearZooms() {
+	const result = await callCommand("editor.listZooms", {});
+	const ranges = Array.isArray(result?.zoomRanges) ? result.zoomRanges : [];
+	for (let index = ranges.length - 1; index >= 0; index -= 1) {
+		await callCommand("editor.removeZoom", { index });
+	}
+	return ranges.length;
+}
+
+export function browserTools() {
+	return [
+		bridgeTool({
+			name: "creavit_browser_open",
+			command: "browser.open",
+			description:
+				"Opens an http(s) URL in Zen Browser, Safari, Chrome, Arc, Firefox, Brave, or the default browser.",
+			inputSchema: schema(
+				{
+					url: S.string("http(s) URL to open"),
+					browser: S.string("Browser name (default: system browser)"),
+				},
+				["url"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_browser_scroll",
+			command: "browser.scroll",
+			description:
+				"Activates a browser and scrolls by page. Useful while recording. Requires macOS Accessibility permission for Creavit Studio.",
+			inputSchema: schema(
+				{
+					browser: S.string("Zen Browser, Safari, Google Chrome, Arc, Firefox, or Brave Browser"),
+					direction: S.string("Scroll direction", {
+						enum: ["down", "up", "top", "bottom"],
+					}),
+					style: S.string("page or smooth (smooth uses small animated steps)", {
+						enum: ["page", "smooth"],
+					}),
+					count: S.number("Number of page-key presses (1-50)"),
+					intervalMs: S.number("Pause after each press in milliseconds"),
+				},
+				["browser"],
+			),
+		}),
+
+		{
+			name: "creavit_record_url_walkthrough",
+			description:
+				"End-to-end website recording: opens a URL, finds that browser window, records it while scrolling, opens the result in Creavit Studio, optionally replaces zooms with automatic scroll-highlight zooms, applies a full-video perspective, and guarantees a muted export timeline. This operation can take several minutes.",
+			inputSchema: schema(
+				{
+					url: S.string("http(s) page to record"),
+					browser: S.string("Browser to use (default: Zen Browser)"),
+					titleContains: S.string("Optional browser window title hint"),
+					loadWaitMs: S.number("Wait for the page to load before recording (default 3000)"),
+					leadInMs: S.number("Still time at the top before scrolling (default 1500)"),
+					scrollCount: S.number("Number of Page Down scrolls (default 4, max 20)"),
+					scrollIntervalMs: S.number("Time between scrolls / section dwell (default 1800)"),
+					sections: S.array(
+						"Optional agent-planned important sections. Each item: {scrollPages,dwellMs,zoom,scale,x,y}. Replaces scrollCount when present.",
+						{ type: "object" },
+					),
+					tailMs: S.number("Still time after the last scroll (default 1500)"),
+					mute: S.bool("Disable microphone/system audio and mute all export clips (default true)"),
+					autoZoom: S.bool("Add zooms around scroll destinations (default true)"),
+					replaceZooms: S.bool("Remove recorder-created zooms first (default true)"),
+					zoomScale: S.number("Automatic zoom scale (default 1.7)"),
+					perspective: S.bool("Apply perspective to the complete result (default false)"),
+					perspectiveTemplate: S.string("Perspective template id (default minimal-tilt)"),
+					save: S.bool("Save the generated project after editing (default true)"),
+				},
+				["url"],
+			),
+			run: async (args) => {
+				const browser = canonicalBrowser(args.browser || "Zen Browser");
+				const loadWaitMs = Math.max(500, Math.min(60_000, Number(args.loadWaitMs) || 3000));
+				const leadInMs = Math.max(300, Math.min(30_000, Number(args.leadInMs) || 1500));
+				const scrollCount = Math.max(
+					0,
+					Math.min(20, Math.round(args.scrollCount === undefined ? 4 : Number(args.scrollCount))),
+				);
+				const scrollIntervalMs = Math.max(
+					400,
+					Math.min(15_000, Number(args.scrollIntervalMs) || 1800),
+				);
+				const tailMs = Math.max(300, Math.min(30_000, Number(args.tailMs) || 1500));
+				const muted = args.mute !== false;
+				const autoZoom = args.autoZoom !== false;
+				const replaceZooms = args.replaceZooms !== false;
+				const zoomScale = Math.max(1, Math.min(5, Number(args.zoomScale) || 1.7));
+				const sectionPlan = Array.isArray(args.sections) && args.sections.length
+					? args.sections.slice(0, 20).map((section) => {
+							const scrollPages = Number(section?.scrollPages);
+							const focusX = Number(section?.x);
+							const focusY = Number(section?.y);
+							return {
+								scrollPages: Math.max(
+									0,
+									Math.min(
+										5,
+										Math.round(Number.isFinite(scrollPages) ? scrollPages : 1),
+									),
+								),
+								dwellMs: Math.max(
+									400,
+									Math.min(15_000, Number(section?.dwellMs) || scrollIntervalMs),
+								),
+								zoom: section?.zoom !== false,
+								scale: Math.max(
+									1,
+									Math.min(5, Number(section?.scale) || zoomScale),
+								),
+								x: Math.max(
+									0,
+									Math.min(1, Number.isFinite(focusX) ? focusX : 0.5),
+								),
+								y: Math.max(
+									0,
+									Math.min(1, Number.isFinite(focusY) ? focusY : 0.5),
+								),
+							};
+						})
+					: Array.from({ length: scrollCount }, (_, index) => ({
+							scrollPages: 1,
+							dwellMs: scrollIntervalMs,
+							zoom: true,
+							scale: zoomScale,
+							x: index % 2 === 0 ? 0.42 : 0.58,
+							y: 0.5,
+						}));
+
+				await callCommand("browser.open", { url: args.url, browser }, 30_000);
+				await sleep(loadWaitMs);
+				await callCommand("browser.scroll", { browser, direction: "top", style: "page", count: 1, intervalMs: 100 });
+				const browserWindow = await waitForBrowserWindow(browser, args.titleContains, 20_000);
+
+				await callCommand(
+					"recording.start",
+					{
+						options: {
+							startScreen: true,
+							cameraEnabled: false,
+							micEnabled: !muted,
+							systemAudioEnabled: !muted,
+							recordingSource: {
+								type: "window",
+								windowId: browserWindow.id,
+								windowInfo: browserWindow,
+							},
+						},
+					},
+					180_000,
+				);
+
+				const recordingStartedAt = Date.now();
+				const zoomWindows = [];
+				await sleep(leadInMs);
+				for (let index = 0; index < sectionPlan.length; index += 1) {
+					const section = sectionPlan[index];
+					if (section.scrollPages > 0) {
+						await callCommand(
+							"browser.scroll",
+							{
+								browser,
+								direction: "down",
+								style: "smooth",
+								count: section.scrollPages,
+								intervalMs: 120,
+							},
+							30_000,
+						);
+					}
+					const arrivedAt = (Date.now() - recordingStartedAt) / 1000;
+					if (section.zoom) {
+						zoomWindows.push({
+							start: Math.max(0, arrivedAt + 0.12),
+							end: Math.max(0.5, arrivedAt + section.dwellMs / 1000 - 0.12),
+							scale: section.scale,
+							x: section.x,
+							y: section.y,
+						});
+					}
+					await sleep(section.dwellMs);
+				}
+				await sleep(tailMs);
+				await callCommand("recording.stop", {}, 600_000);
+
+				const editorState = await waitForEditor(600_000);
+				const applied = { muted: false, zooms: [], perspective: null, saved: false };
+
+				if (muted) {
+					await callCommand("editor.setMuted", { muted: true });
+					applied.muted = true;
+				}
+				if (autoZoom) {
+					if (replaceZooms) applied.removedZooms = await clearZooms();
+					for (let index = 0; index < zoomWindows.length; index += 1) {
+						const window = zoomWindows[index];
+						const start = Math.min(window.start, Math.max(0, editorState.duration - 0.25));
+						const end = Math.min(window.end, editorState.duration);
+						if (end - start < 0.25) continue;
+						const result = await callCommand("editor.addZoom", {
+							start,
+							end,
+							scale: window.scale,
+							x: window.x,
+							y: window.y,
+						});
+						applied.zooms.push(result?.added || result);
+					}
+				}
+				if (args.perspective === true) {
+					const result = await callCommand("editor.addPerspective", {
+						fullDuration: true,
+						templateId: args.perspectiveTemplate || "minimal-tilt",
+					});
+					applied.perspective = result?.added || result;
+				}
+				if (args.save !== false) {
+					await callCommand("editor.saveProject", {}, 180_000);
+					applied.saved = true;
+				}
+
+				return textResult({
+					ok: true,
+					url: args.url,
+					browser,
+					window: browserWindow,
+					duration: editorState.duration,
+					projectFilePath: editorState.projectFilePath,
+					applied,
+				});
+			},
+		},
+	];
+}

package/src/tools/editorTools.mjs

@@ -49,6 +49,81 @@ export function editorTools() {
 				}),
 		}),
 
+		bridgeTool({
+			name: "creavit_editor_background_get",
+			command: "editor.getBackground",
+			description:
+				"Reads the complete canvas background configuration: solid color, gradient, image, blur, and dynamic pattern values.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			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.",
+			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"),
+					blur: S.number("Image blur amount"),
+					gradient: S.object(
+						"Gradient configuration: {type, direction, colors:[{color,position}]}.",
+					),
+					dynamic: S.object("Dynamic pattern configuration"),
+				},
+				["type"],
+			),
+			mapResult: (result) =>
+				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_camera_get",
+			command: "editor.getCamera",
+			description: "Reads all camera overlay settings.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_camera_set",
+			command: "editor.setCamera",
+			description:
+				"Partially updates camera overlay settings: visible, size, radius, shadow, position crop, cropZoom, followMouse, oscillationMovement, mirror, aspectRatio, border, background removal, mergeWithCursor, lockSizeOnZoom and sizeOnZoom. Call creavit_project_save afterwards.",
+			inputSchema: schema(
+				{ settings: S.object("Camera settings to update") },
+				["settings"],
+			),
+			mapResult: (result) =>
+				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
+		}),
+
+		{
+			name: "creavit_editor_audio",
+			description:
+				"Reads audio state or mutes/unmutes both preview and every timeline clip used by export. Use action='mute' to guarantee that the exported video has no source audio.",
+			inputSchema: schema(
+				{
+					action: S.string("status, mute, or unmute", {
+						enum: ["status", "mute", "unmute"],
+					}),
+				},
+				["action"],
+			),
+			run: async ({ action }) => {
+				if (action === "status") return textResult(await callCommand("editor.getAudio", {}));
+				if (action !== "mute" && action !== "unmute") {
+					throw new Error("`action` must be status, mute, or unmute");
+				}
+				return textResult(
+					await callCommand("editor.setMuted", { muted: action === "mute" }),
+				);
+			},
+		},
+
 		bridgeTool({
 			name: "creavit_editor_list_zooms",
 			command: "editor.listZooms",
@@ -99,6 +174,52 @@ export function editorTools() {
 			}),
 		}),
 
+		bridgeTool({
+			name: "creavit_editor_perspectives",
+			command: "editor.listPerspectives",
+			description: "Lists all perspective (3D animation) ranges on the timeline.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_add_perspective",
+			command: "editor.addPerspective",
+			description:
+				"Adds a Creavit perspective range. Set fullDuration=true to cover the complete video. Templates include slant-left, slant-right, hero, lift, corner-left, corner-right, floating, perspective-left, perspective-right, minimal-tilt and cinematic-wide.",
+			inputSchema: schema({
+				start: S.number("Start time in seconds"),
+				end: S.number("End time in seconds"),
+				fullDuration: S.bool("Cover the complete video, ignoring start/end"),
+				templateId: S.string("Perspective template id"),
+				settings: S.object("Optional overrides for the perspective range"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_update_perspective",
+			command: "editor.updatePerspective",
+			description: "Updates an existing perspective range by id or zero-based index.",
+			inputSchema: schema(
+				{
+					id: S.string("Perspective range ID"),
+					index: S.number("Perspective range index"),
+					patch: S.object("Fields to update"),
+				},
+				["patch"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_remove_perspective",
+			command: "editor.removePerspective",
+			description: "Deletes a perspective range by id/index, or all perspective ranges with all=true.",
+			inputSchema: schema({
+				id: S.string("Perspective range ID"),
+				index: S.number("Perspective range index"),
+				all: S.bool("Delete every perspective range"),
+			}),
+		}),
+
 		bridgeTool({
 			name: "creavit_editor_segments",
 			command: "editor.listSegments",

package/src/tools/index.mjs

@@ -3,6 +3,7 @@
 import { projectTools } from "./projectTools.mjs";
 import { editorTools } from "./editorTools.mjs";
 import { systemTools } from "./systemTools.mjs";
+import { browserTools } from "./browserTools.mjs";
 import { escapeTools } from "./escapeTools.mjs";
 import { errorResult } from "./defineTool.mjs";
 import { BridgeUnavailableError } from "../bridgeClient.mjs";
@@ -11,7 +12,13 @@ let registry = null;
 
 function buildRegistry() {
 	if (registry) return registry;
-	const all = [...systemTools(), ...projectTools(), ...editorTools(), ...escapeTools()];
+	const all = [
+		...systemTools(),
+		...projectTools(),
+		...editorTools(),
+		...browserTools(),
+		...escapeTools(),
+	];
 
 	const byName = new Map();
 	for (const tool of all) {