creavit-studio-mcp 1.3.7 → 1.3.9

package/README.md

@@ -7,6 +7,11 @@ and **see the canvas** to verify the result.
 
 macOS only (Creavit Studio is a macOS app). Requires Node 18+.
 
+> This MCP server is client-agnostic — any MCP client can drive the app.
+> That is separate from the **in-app Agent panel**, which shells out to a CLI
+> installed on your Mac and detects only Claude Code and Codex
+> (see `electron/aiAgent/agentCatalog.cjs`).
+
 ## Install
 
 ### Claude Code
@@ -50,9 +55,9 @@ npx creavit-studio-mcp --doctor
 ```
 
 ```
-creavit-studio v1.2.0
+creavit-studio v1.3.9
 
-✓ 50 MCP tools defined
+✓ 104 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
@@ -106,7 +111,8 @@ files directly and work with the app closed.
 `creavit_editor_set_settings`, `creavit_editor_list_zooms`,
 `creavit_editor_add_zoom`, `creavit_editor_update_zoom`,
 `creavit_editor_remove_zoom`, `creavit_editor_segments`,
-`creavit_editor_set_segments`, `creavit_editor_seek`,
+`creavit_editor_set_segments`, `creavit_editor_timeline`,
+`creavit_editor_canvas_elements`, `creavit_editor_seek`,
 `creavit_editor_playback`, `creavit_editor_screenshot`,
 `creavit_editor_export`, `creavit_editor_history`
 
@@ -162,6 +168,24 @@ Timeline & assets: `creavit_motion_segments`, `creavit_motion_library`,
 **Recording** — `creavit_devices_list`, `creavit_recording_status`,
 `creavit_recording_start`, `creavit_recording_stop`
 
+`creavit_recording_start` treats `cameraEnabled`, `micEnabled`, and
+`systemAudioEnabled` as authoritative. Passing `false` updates both capture and
+the recorder UI; disabling the camera also stops and hides its live window.
+
+### Every timeline track and canvas element
+
+`creavit_editor_segments` remains the compact clip/cut API. For the complete
+editor use `creavit_editor_timeline action=list`: it discovers clips, steps,
+zooms, layouts, perspectives, titles, sounds, shortcuts, masks, motion scenes,
+code snippets, media/GIFs, subtitles, and manual-cursor segments. Pass
+`detail=full` to read complete objects, then use get/add/update/remove/replace on
+one returned track type.
+
+`creavit_editor_canvas_elements action=list` returns every transformable item on
+the main canvas. Each item advertises its exact `supports` array and coordinate
+units. Updating the advertised fields can move, resize/scale, rotate, change
+opacity, or hide an element without guessing its internal state shape.
+
 **Browser walkthrough** — `creavit_browser_open`, `creavit_browser_inspect`,
 `creavit_browser_focus`, `creavit_browser_interact`, `creavit_browser_scroll`,
 `creavit_browser_close`, `creavit_record_url_walkthrough`

package/package.json

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

package/src/tools/editorTools.mjs

@@ -69,7 +69,9 @@ export function editorTools() {
 					}),
 					color: S.string("CSS color for a solid background"),
 					image: S.string("Image URL, local path, or a CMS wallpaper name"),
-					wallpaper: S.string("CMS wallpaper name (see creavit_editor_wallpapers)"),
+					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}]}.",
@@ -79,7 +81,10 @@ export function editorTools() {
 				["type"],
 			),
 			mapResult: (result) =>
-				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
+				textResult({
+					...result,
+					note: "Applied. Call creavit_project_save to persist.",
+				}),
 		}),
 
 		bridgeTool({
@@ -108,7 +113,10 @@ export function editorTools() {
 			}),
 			timeoutMs: 60_000,
 			mapResult: (result) =>
-				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
+				textResult({
+					...result,
+					note: "Applied. Call creavit_project_save to persist.",
+				}),
 		}),
 
 		bridgeTool({
@@ -119,16 +127,65 @@ export function editorTools() {
 		}),
 
 		bridgeTool({
-			name: "creavit_editor_camera_set",
-			command: "editor.setCamera",
+			name: "creavit_editor_perspective_poses",
+			command: "editor.listPerspectivePoses",
 			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.",
+				"Lists the balanced perspective poses (flat, desk, hero, peek-up, lean/iso/float left-right) with their angles. Read this before setting a pose so you pick a real one.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_perspective_pose",
+			command: "editor.setPerspectivePose",
+			description:
+				"Gives a perspective range a balanced camera angle and computes its pivot from a focus point — prefer this over writing raw tiltX/tiltY/skew, which is how lopsided angles happen. `pose` picks the look, `strength` (0..2) makes it subtle or dramatic, `focus` is the canvas point the tilt pivots around as {x,y} in 0..1 (e.g. the UI element the viewer should look at). Add `endPose`/`focusEnd` to animate from one angle/pivot to another across the range. Call creavit_project_save afterwards.",
+			inputSchema: schema({
+				id: S.string("Perspective range id"),
+				index: S.number("Range index when id is unknown (default 0)"),
+				pose: S.string("flat | desk | hero | peek-up | lean-left | lean-right | iso-left | iso-right | float-left | float-right"),
+				endPose: S.string("Pose the range animates towards"),
+				strength: S.number("0..2, default 1"),
+				focus: S.object("Pivot point {x,y} normalized 0..1"),
+				focusEnd: S.object("Pivot point the origin travels to"),
+				scale: S.number("Plane scale at the start"),
+				scaleEnd: S.number("Plane scale at the end"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_reframe",
+			command: "editor.reframe",
+			description:
+				"Re-frames the whole composition for another aspect ratio in ONE call — use this for \"make it vertical / for mobile / a story\" requests instead of setting the ratio and then nudging padding, camera and zooms by hand. Ask the user which format they want first (9:16 story, 4:5 or 1:1 feed, 3:4) when they did not say. It sets the ratio, refits padding/radius so the content stays as large as possible, enlarges the camera and anchors it bottom-center so it reads on a narrow frame, and scales the cursor. Existing zooms are preserved untouched unless tightenZooms is true. Call creavit_project_save afterwards.",
 			inputSchema: schema(
-				{ settings: S.object("Camera settings to update") },
-				["settings"],
+				{
+					ratio: S.string("16:9, 9:16, 1:1, 4:3, 3:4, or empty string for auto", {
+						enum: ["", "16:9", "9:16", "1:1", "4:3", "3:4"],
+					}),
+					cameraPlacement: S.string("bottom | top | keep", {
+						enum: ["bottom", "top", "keep"],
+					}),
+					tightenZooms: S.bool(
+						"Raise low zoom scales so text stays readable on a phone (default false)",
+					),
+				},
+				["ratio"],
 			),
+		}),
+
+		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. Background removal is a real toggle: pass removeBackground (or optimizedBackgroundRemoval) true/false and the app loads the segmentation engine and starts the pipeline, exactly like the settings panel does — optionally tune it with optimizedBackgroundRemovalSettings. 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." }),
+				textResult({
+					...result,
+					note: "Applied. Call creavit_project_save to persist.",
+				}),
 		}),
 
 		{
@@ -144,7 +201,8 @@ export function editorTools() {
 				["action"],
 			),
 			run: async ({ action }) => {
-				if (action === "status") return textResult(await callCommand("editor.getAudio", {}));
+				if (action === "status")
+					return textResult(await callCommand("editor.getAudio", {}));
 				if (action !== "mute" && action !== "unmute") {
 					throw new Error("`action` must be status, mute, or unmute");
 				}
@@ -207,7 +265,8 @@ export function editorTools() {
 		bridgeTool({
 			name: "creavit_editor_perspectives",
 			command: "editor.listPerspectives",
-			description: "Lists all perspective (3D animation) ranges on the timeline.",
+			description:
+				"Lists all perspective (3D animation) ranges on the timeline.",
 			inputSchema: schema(),
 		}),
 
@@ -228,7 +287,8 @@ export function editorTools() {
 		bridgeTool({
 			name: "creavit_editor_update_perspective",
 			command: "editor.updatePerspective",
-			description: "Updates an existing perspective range by id or zero-based index.",
+			description:
+				"Updates an existing perspective range by id or zero-based index.",
 			inputSchema: schema(
 				{
 					id: S.string("Perspective range ID"),
@@ -242,7 +302,8 @@ export function editorTools() {
 		bridgeTool({
 			name: "creavit_editor_remove_perspective",
 			command: "editor.removePerspective",
-			description: "Deletes a perspective range by id/index, or all perspective ranges with all=true.",
+			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"),
@@ -269,12 +330,56 @@ export function editorTools() {
 			),
 		}),
 
+		bridgeTool({
+			name: "creavit_editor_timeline",
+			command: "editor.timelineSegments",
+			description:
+				"Unified access to EVERY editor timeline track, not just video clips: clips, steps, zooms, layouts, perspectives, titles, sound effects, shortcuts, sensitive masks, motion scenes, code snippets, media/GIFs, subtitles and manual-cursor segments. action='list' discovers track types/counts; use detail='full' to read complete objects. get/add/update/remove/replace target one `type`. Updates are deep-merged so nested transform/style objects are preserved. Call creavit_project_save afterwards.",
+			inputSchema: schema({
+				action: S.string("list, get, add, update, remove or replace (default list)", {
+					enum: ["list", "get", "add", "update", "remove", "replace"],
+				}),
+				types: S.array("Track types to include when listing", { type: "string" }),
+				type: S.string("Target track type for get/add/update/remove/replace"),
+				id: S.string("Segment id"),
+				index: S.number("Zero-based segment index when it has no id"),
+				segment: S.object("Complete segment object to add"),
+				patch: S.object("Fields to update; nested objects are deep-merged"),
+				segments: S.array("Complete replacement list", { type: "object" }),
+				detail: S.string("summary or full (list only)", {
+					enum: ["summary", "full"],
+				}),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_canvas_elements",
+			command: "editor.canvasElements",
+			description:
+				"Lists or transforms every editable element on the MAIN editor canvas: screen, camera, captured windows, GIF/image/video overlays, code snippets, titles, motion scenes and sensitive masks. action='list' returns each element's id, transform, units and exact `supports` fields. action='update' can move (x/y), resize (width/height/size/scale), rotate and change opacity where that element advertises support. Motion Studio's internal layers remain available through creavit_motion_elements / creavit_motion_element_update.",
+			inputSchema: schema({
+				action: S.string("list, get or update (default list)", {
+					enum: ["list", "get", "update"],
+				}),
+				type: S.string(
+					"screen, camera, window, gif, media, codeSnippet, title, motion or sensitive",
+				),
+				id: S.string("Canvas element id"),
+				index: S.number("Index among elements of that type"),
+				patch: S.object(
+					"Transform fields advertised by the element's supports array, e.g. {x,y,width,height,scale,size,rotation,opacity,visible}",
+				),
+			}),
+		}),
+
 		bridgeTool({
 			name: "creavit_editor_seek",
 			command: "editor.seek",
 			description:
 				"Moves the playhead to the given time and renders that frame. Combine with creavit_editor_screenshot to inspect a specific moment.",
-			inputSchema: schema({ time: S.number("Target time in seconds") }, ["time"]),
+			inputSchema: schema({ time: S.number("Target time in seconds") }, [
+				"time",
+			]),
 		}),
 
 		{
@@ -304,8 +409,15 @@ export function editorTools() {
 			timeoutMs: 120_000,
 			mapResult: (result) => ({
 				content: [
-					{ type: "image", data: result.base64, mimeType: result.mimeType || "image/png" },
-					{ type: "text", text: `Canvas frame @ ${Number(result.atTime || 0).toFixed(2)}s` },
+					{
+						type: "image",
+						data: result.base64,
+						mimeType: result.mimeType || "image/png",
+					},
+					{
+						type: "text",
+						text: `Canvas frame @ ${Number(result.atTime || 0).toFixed(2)}s`,
+					},
 				],
 			}),
 		}),
@@ -314,7 +426,7 @@ export function editorTools() {
 			name: "creavit_editor_export",
 			command: "editor.export",
 			description:
-				"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.",
+				"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. Exporting requires an active Creavit Studio license, or a remaining free export credit. When neither is available the export is REFUSED before any rendering starts and the error explains why (expired license / free credits used up); relay that message to the user in their own language and point them at the purchase page instead of retrying.",
 			inputSchema: schema({
 				filePath: S.string("Target file path (.mp4)"),
 				format: S.string("mp4 or gif", { enum: ["mp4", "gif"] }),
@@ -329,14 +441,18 @@ export function editorTools() {
 			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.",
+				"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. Exporting requires an active Creavit Studio license, or a remaining free export credit. When neither is available the export is REFUSED before any rendering starts and the error explains why (expired license / free credits used up); relay that message to the user in their own language and point them at the purchase page instead of retrying.",
 			inputSchema: schema({
-				filePath: S.string("Target file path (.mp4); omit to export beside the project"),
+				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"),
+				openWhenFinished: S.bool(
+					"Open the exported file automatically when rendering completes",
+				),
 			}),
 			timeoutMs: 30_000,
 		}),

package/src/tools/systemTools.mjs

@@ -74,7 +74,7 @@ export function systemTools() {
 			name: "creavit_recording_start",
 			command: "recording.start",
 			description:
-				"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.",
+				"Starts a screen recording idempotently: retries while starting share the same native operation, and calling it while active does not restart. cameraEnabled, micEnabled and systemAudioEnabled are authoritative booleans: false also updates the recorder UI/state and cameraEnabled:false stops/hides the live camera window before capture. 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.",