creavit-studio-mcp 1.3.0 → 1.3.2

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
@@ -209,9 +218,13 @@ 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.
+
+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,8 +245,6 @@ Example input:
     { "action": "click", "text": "Get Started", "dwellMs": 3000 }
   ],
   "controlSystemMouse": true,
-  "autoZoom": true,
-  "zoomScale": 1.8,
   "perspective": true,
   "perspectiveTemplate": "minimal-tilt",
   "mute": true

package/package.json

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

package/src/bridgeClient.mjs

@@ -12,6 +12,9 @@ import { ensureAppRunning, isAutoLaunchEnabled } from "./appLauncher.mjs";
 const DEFAULT_ENDPOINT_DIRS = [
 	path.join(os.homedir(), "Library", "Application Support", "creavit-studio"),
 	path.join(os.homedir(), "Library", "Application Support", "Creavit Studio"),
+	// `npm run electron:dev` paketlenmemiş çalıştığı için userData "Electron"
+	// altına düşer. Bu olmadan MCP dev build'i hiç göremez.
+	path.join(os.homedir(), "Library", "Application Support", "Electron"),
 ];
 
 export class BridgeUnavailableError extends Error {

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.1";
 
 export const JSONRPC_ERRORS = {
 	PARSE_ERROR: -32700,

package/src/tools/browserTools.mjs

@@ -220,7 +220,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.",
+				"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.",
 			inputSchema: schema(
 				{
 					url: S.string("http(s) page to record"),
@@ -240,8 +240,8 @@ 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)"),
@@ -259,8 +259,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;
@@ -385,7 +389,14 @@ export function browserTools() {
 					recordingStarted = false;
 
 					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,
+					};
 					let finalDuration = Number(editorState.duration);
 					if (durationMs) {
 						const targetDuration = durationMs / 1000;

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"),

package/src/tools/index.mjs

@@ -5,6 +5,7 @@ import { editorTools } from "./editorTools.mjs";
 import { motionTools } from "./motionTools.mjs";
 import { systemTools } from "./systemTools.mjs";
 import { browserTools } from "./browserTools.mjs";
+import { inputTools } from "./inputTools.mjs";
 import { escapeTools } from "./escapeTools.mjs";
 import { errorResult } from "./defineTool.mjs";
 import { BridgeUnavailableError } from "../bridgeClient.mjs";
@@ -19,6 +20,7 @@ function buildRegistry() {
 		...editorTools(),
 		...motionTools(),
 		...browserTools(),
+		...inputTools(),
 		...escapeTools(),
 	];
 

package/src/tools/inputTools.mjs

@@ -0,0 +1,134 @@
+// MCP araçları — sistem faresi ve klavyesi.
+// browser_* araçlarından farkı: izole capture penceresine bağlı değiller,
+// ekrandaki herhangi bir uygulamayı sürerler.
+
+import { bridgeTool, schema, S } from "./defineTool.mjs";
+
+const STEP_SCHEMA = S.object(
+	"One step: {action:'move',x,y,durationMs} | {action:'click',clickCount} | {action:'down'|'up'} | {action:'type',text,perCharMs} | {action:'key',key,modifiers} | {action:'wait',ms}",
+);
+
+export function inputTools() {
+	return [
+		bridgeTool({
+			name: "creavit_input_click",
+			command: "input.click",
+			description:
+				"Moves the real system mouse to a screen coordinate and clicks. For a point inside a window use creavit_input_window_click instead — it does the coordinate math for you.",
+			inputSchema: schema(
+				{
+					x: S.number("Screen X"),
+					y: S.number("Screen Y"),
+					durationMs: S.number("Travel time for the move (default 450)"),
+					clickCount: S.number("1 = click, 2 = double-click"),
+				},
+				["x", "y"],
+			),
+			timeoutMs: 30_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_input_move",
+			command: "input.moveMouse",
+			description: "Moves the real system mouse to a screen coordinate, without clicking.",
+			inputSchema: schema(
+				{
+					x: S.number("Screen X"),
+					y: S.number("Screen Y"),
+					durationMs: S.number("Travel time (default 450)"),
+				},
+				["x", "y"],
+			),
+			timeoutMs: 30_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_input_window_click",
+			command: "input.windowClick",
+			description:
+				"Clicks inside a window from creavit_devices_list, using window-relative coordinates (or 0-1 with normalized:true). Brings the window's owner app to the front first — this is the click to use while recording a window.",
+			inputSchema: schema(
+				{
+					windowId: S.number("Window id from creavit_devices_list"),
+					x: S.number("Window-relative X (px, or 0-1 when normalized)"),
+					y: S.number("Window-relative Y"),
+					normalized: S.bool("Treat x/y as 0-1 fractions of the window (default false)"),
+					durationMs: S.number("Travel time (default 450)"),
+					clickCount: S.number("1 = click, 2 = double-click"),
+					activate: S.bool("Bring the owner app to the front first (default true)"),
+				},
+				["windowId", "x", "y"],
+			),
+			timeoutMs: 60_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_input_type",
+			command: "input.type",
+			description:
+				"Types text into whatever is focused. Click the field first. perCharMs types character by character, which looks natural in a recording.",
+			inputSchema: schema(
+				{
+					text: S.string("Text to type (UTF-8; Turkish characters are fine)"),
+					perCharMs: S.number("Delay per character, 0 = all at once (default 0)"),
+					pressEnter: S.bool("Press Return afterwards (default false)"),
+				},
+				["text"],
+			),
+			timeoutMs: 120_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_input_key",
+			command: "input.key",
+			description:
+				"Presses a single key with optional modifiers. Keys: return, tab, space, delete, escape, left/right/up/down, home, end, pageup, pagedown. Modifiers: cmd, shift, alt, ctrl.",
+			inputSchema: schema(
+				{
+					key: S.string("Key name"),
+					modifiers: S.array("Modifiers held down", S.string("cmd|shift|alt|ctrl")),
+				},
+				["key"],
+			),
+			timeoutMs: 30_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_record_walkthrough",
+			command: "recording.walkthrough",
+			description:
+				"Records a walkthrough in ONE call: starts recording, runs the input steps, stops. USE THIS to record an interaction — the recorded length is leadMs + steps + tailMs and nothing else. Driving it by hand (start, then sequence, then stop) adds your own round-trip time to the video; measured, an 8.7s scenario became a 22.5s recording. With sourceType 'window' the step coordinates are window-relative by default.",
+			inputSchema: schema(
+				{
+					options: S.object(
+						"Recording options, same as creavit_recording_start: {sourceType:'display'|'window'|'area', sourceId, cameraEnabled, micEnabled, systemAudioEnabled, area}",
+					),
+					steps: S.array("Input steps, executed in order", STEP_SCHEMA),
+					leadMs: S.number("Idle time before the first step (default 800)"),
+					tailMs: S.number("Idle time after the last step (default 1200)"),
+					normalized: S.bool("Treat move x/y as 0-1 fractions of the window (default false)"),
+					windowRelative: S.bool("Step coordinates are window-relative (default true for window recordings)"),
+				},
+				["options", "steps"],
+			),
+			timeoutMs: 900_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_input_sequence",
+			command: "input.sequence",
+			description:
+				"Runs a whole input scenario inside the app in ONE native process, so its wall-clock duration is exactly what you asked for. USE THIS WHILE RECORDING — driving a recording with separate click/type calls adds each round-trip to the recorded video. Pass windowId to write move steps in window-relative coordinates.",
+			inputSchema: schema(
+				{
+					steps: S.array("Steps, executed in order", STEP_SCHEMA),
+					windowId: S.number("Window id — makes move steps window-relative"),
+					normalized: S.bool("Treat move x/y as 0-1 fractions of the window (default false)"),
+					activate: S.bool("Bring the owner app to the front first (default true)"),
+				},
+				["steps"],
+			),
+			timeoutMs: 600_000,
+		}),
+	];
+}