creavit-studio-mcp 1.2.1 → 1.3.0

package/README.md

@@ -118,6 +118,27 @@ files directly and work with the app closed.
 `creavit_editor_add_perspective`, `creavit_editor_update_perspective`,
 `creavit_editor_remove_perspective`
 
+**Motion Studio** — session: `creavit_motion_state`, `creavit_motion_open`,
+`creavit_motion_save`, `creavit_motion_close`, `creavit_motion_scene_get`,
+`creavit_motion_scene_set`, `creavit_motion_playback`,
+`creavit_motion_screenshot`, `creavit_motion_history`, `creavit_motion_export`,
+`creavit_motion_import`
+
+Elements: `creavit_motion_elements`, `creavit_motion_element_get`,
+`creavit_motion_element_add`, `creavit_motion_element_update`,
+`creavit_motion_element_remove`, `creavit_motion_element_arrange`,
+`creavit_motion_select`
+
+Animation: `creavit_motion_presets`, `creavit_motion_action_add`,
+`creavit_motion_action_update`, `creavit_motion_action_remove`
+
+Timeline & assets: `creavit_motion_segments`, `creavit_motion_library`,
+`creavit_motion_templates`
+
+> Motion Studio is a mode **inside** the editor window: open a project first,
+> then `creavit_motion_open`. `creavit_motion_segments` also works with Motion
+> Studio closed.
+
 **Recording** — `creavit_devices_list`, `creavit_recording_status`,
 `creavit_recording_start`, `creavit_recording_stop`
 
@@ -162,6 +183,25 @@ 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.
 
+### Motion Studio
+
+```text
+creavit_motion_segments   action=list            what motion overlays exist
+creavit_motion_open       new=true startTime=2   new scene at 2s on the timeline
+creavit_motion_presets                           the animation catalog
+creavit_motion_element_add kind=text patch={text:"Hello", fontSize:64}
+creavit_motion_action_add  elementId=... presetId=slide-in-up
+creavit_motion_screenshot  time=0.4              VERIFY the animation
+creavit_motion_save                              write back to the segment
+creavit_motion_close                             return to the editor
+creavit_project_save                             persist
+```
+
+`creavit_motion_export` renders the scene on its own (video / gif / json /
+lottie / html) into the Downloads folder — that is separate from
+`creavit_editor_export`, which renders the whole video with the motion overlay
+composited in.
+
 ### Record a URL walkthrough
 
 `creavit_record_url_walkthrough` is the high-level workflow. By default it opens

package/package.json

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

package/src/tools/index.mjs

@@ -2,6 +2,7 @@
 
 import { projectTools } from "./projectTools.mjs";
 import { editorTools } from "./editorTools.mjs";
+import { motionTools } from "./motionTools.mjs";
 import { systemTools } from "./systemTools.mjs";
 import { browserTools } from "./browserTools.mjs";
 import { escapeTools } from "./escapeTools.mjs";
@@ -16,6 +17,7 @@ function buildRegistry() {
 		...systemTools(),
 		...projectTools(),
 		...editorTools(),
+		...motionTools(),
 		...browserTools(),
 		...escapeTools(),
 	];

package/src/tools/motion/elementTools.mjs

@@ -0,0 +1,157 @@
+// MCP araçları — Motion Studio elemanları ve animasyon action'ları.
+
+import { bridgeTool, schema, S, textResult } from "../defineTool.mjs";
+
+export function motionElementTools() {
+	return [
+		bridgeTool({
+			name: "creavit_motion_elements",
+			command: "motion.listElements",
+			description:
+				"Lists every element in the scene tree (group children included) with id, type, name, bounds, visibility and action count. Start here before editing anything.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_element_get",
+			command: "motion.getElement",
+			description:
+				"Returns one element in full: every style property plus its animation actions with ids, start times and params.",
+			inputSchema: schema({ id: S.string("Element ID") }, ["id"]),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_element_add",
+			command: "motion.addElement",
+			description:
+				"Adds an element to the scene, centered by default. Kinds: text, rect, circle, line, image, icon, group. Pass initial properties in `patch` — e.g. text: {text, fontSize, color, fontFamily, align}, shapes: {fill, cornerRadius}, image: {src, fit}, icon: {iconKind, color}. Verify with creavit_motion_screenshot afterwards.",
+			inputSchema: schema(
+				{
+					kind: S.string("Element kind", {
+						enum: ["text", "rect", "circle", "line", "image", "icon", "group"],
+					}),
+					patch: S.object("Initial properties: x, y, width, height, text, fill, color, fontSize..."),
+					parentId: S.string("Group ID to add into (omit for the scene root)"),
+				},
+				["kind"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_element_update",
+			command: "motion.updateElement",
+			description:
+				'Partially updates one element. Only the keys you pass change: {"x":100,"y":40,"opacity":0.5,"visible":false}. Read valid key names with creavit_motion_element_get.',
+			inputSchema: schema(
+				{ id: S.string("Element ID"), patch: S.object("Properties to change") },
+				["id", "patch"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_element_remove",
+			command: "motion.removeElement",
+			description: "Deletes one or more elements. Deleting a group removes its children too.",
+			inputSchema: schema({
+				id: S.string("Element ID"),
+				ids: S.array("Several element IDs", { type: "string" }),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_element_arrange",
+			command: "motion.arrangeElements",
+			description:
+				"Structural element operations: duplicate (ids), group (2+ ids sharing a parent), ungroup (id), reorder (id + targetId + position), moveInto (id + groupId).",
+			inputSchema: schema(
+				{
+					action: S.string("duplicate, group, ungroup, reorder or moveInto", {
+						enum: ["duplicate", "group", "ungroup", "reorder", "moveInto"],
+					}),
+					ids: S.array("Element IDs (duplicate, group)", { type: "string" }),
+					id: S.string("Element ID (ungroup, reorder, moveInto source)"),
+					targetId: S.string("Reference element for reorder"),
+					position: S.string("before or after (reorder)", { enum: ["before", "after"] }),
+					groupId: S.string("Target group for moveInto"),
+				},
+				["action"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_select",
+			command: "motion.select",
+			description:
+				"Sets the Motion Studio selection. Mostly cosmetic for an agent — the element tools take explicit ids — but useful to show the user what you changed.",
+			inputSchema: schema({
+				id: S.string("Element ID"),
+				ids: S.array("Several element IDs", { type: "string" }),
+				clear: S.bool("Clear the selection"),
+				frame: S.bool("Select the scene frame"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_presets",
+			command: "motion.listPresets",
+			description:
+				"Lists the animation preset catalog — in (entrances), out (exits), custom and effects — plus the raw action types and easing names. Read this BEFORE adding animations; preset ids like 'slide-in-up' or 'blur-scale-in' produce the polished multi-action results.",
+			inputSchema: schema({
+				tab: S.string("in, out, custom or effects (omit for all)", {
+					enum: ["in", "out", "custom", "effects"],
+				}),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_action_add",
+			command: "motion.addAction",
+			description:
+				"Animates an element. Preferred: pass `presetId` from creavit_motion_presets. For manual control pass `type` (fade, slide, scale, rotate, blur, pop, bounce, reveal, typewriter, move, maskMove) with `direction`, `duration`, `easing` and type specific `params`. `start` defaults to the playhead; the scene duration is extended to fit.",
+			inputSchema: schema(
+				{
+					elementId: S.string("Element to animate"),
+					presetId: S.string("Preset id from creavit_motion_presets"),
+					type: S.string("Raw action type when no preset is used"),
+					direction: S.string("in or out", { enum: ["in", "out"] }),
+					start: S.number("Start time in seconds (defaults to the playhead)"),
+					duration: S.number("Duration in seconds"),
+					easing: S.string("Easing name from creavit_motion_presets"),
+					params: S.object("Type specific params: distance, axis, angle, startOffset, moveX, moveY..."),
+				},
+				["elementId"],
+			),
+			mapResult: (result) =>
+				textResult({ ...result, note: "Verify the result with creavit_motion_screenshot at a few times." }),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_action_update",
+			command: "motion.updateAction",
+			description:
+				"Updates one animation action: start, duration, easing, direction or params. Get action ids from creavit_motion_element_get.",
+			inputSchema: schema(
+				{
+					elementId: S.string("Element ID"),
+					actionId: S.string("Action ID"),
+					patch: S.object("Fields to change: start, duration, easing, direction, params"),
+				},
+				["elementId", "actionId", "patch"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_action_remove",
+			command: "motion.removeAction",
+			description: "Deletes one animation action from an element, or every action with all=true.",
+			inputSchema: schema(
+				{
+					elementId: S.string("Element ID"),
+					actionId: S.string("Action ID"),
+					all: S.bool("Delete every action on this element"),
+				},
+				["elementId"],
+			),
+		}),
+	];
+}

package/src/tools/motion/sessionTools.mjs

@@ -0,0 +1,151 @@
+// MCP araçları — Motion Studio oturumu: açma/kapama, sahne, oynatma, kare.
+
+import { bridgeTool, schema, S, textResult } from "../defineTool.mjs";
+import { callCommand } from "../../bridgeClient.mjs";
+
+export function motionSessionTools() {
+	return [
+		bridgeTool({
+			name: "creavit_motion_state",
+			command: "motion.getState",
+			description:
+				"Live Motion Studio state: is it open, scene name/size/fps, duration, playhead, element count and timeline motion segment count. Call this FIRST for any motion work — most other motion tools need Motion Studio to be open.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_open",
+			command: "motion.open",
+			description:
+				"Opens Motion Studio inside the editor window. Pass `segmentId` for an existing timeline motion segment (see creavit_motion_segments), `libraryMotionId` for a saved motion, or new=true to start a fresh scene — with `startTime` it also creates a timeline segment there. With no arguments it resumes the previous session.",
+			inputSchema: schema({
+				segmentId: S.string("Timeline motion segment ID"),
+				libraryMotionId: S.string("Saved library motion ID"),
+				new: S.bool("Start a new scene"),
+				startTime: S.number("With new=true: place the segment at this time (seconds)"),
+				duration: S.number("Scene duration in seconds"),
+				name: S.string("Scene name"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_save",
+			command: "motion.save",
+			description:
+				"Writes the scene back to its timeline segment (or library motion) while staying in Motion Studio. Call creavit_project_save afterwards to persist the project file.",
+			inputSchema: schema(),
+			mapResult: (result) =>
+				textResult({ ...result, note: "Saved into the segment. Call creavit_project_save to persist." }),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_close",
+			command: "motion.close",
+			description:
+				"Leaves Motion Studio and returns to the video editor. Saves the scene by default; pass save=false to discard.",
+			inputSchema: schema({ save: S.bool("Save before leaving (default true)") }),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_scene_get",
+			command: "motion.getScene",
+			description:
+				"Reads the scene: settings (size, fps, background, frame offset) plus element summaries. Pass full=true for the COMPLETE element tree with every animation action — that output can be large.",
+			inputSchema: schema({ full: S.bool("Include the complete element tree with actions") }),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_scene_set",
+			command: "motion.setScene",
+			description:
+				"Updates scene settings. background 'transparent' keeps the scene see-through over the video. Duration is clamped to fit the animation content.",
+			inputSchema: schema({
+				width: S.number("Scene width in px"),
+				height: S.number("Scene height in px"),
+				fps: S.number("Frame rate (default 60)"),
+				background: S.string("'transparent' or a CSS color"),
+				workspaceBackground: S.string("Editor workspace background color"),
+				frameOffset: S.object("Frame offset from the viewport center: {x, y}"),
+				name: S.string("Scene name"),
+				duration: S.number("Scene duration in seconds"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_playback",
+			command: "motion.playback",
+			description:
+				"Controls Motion Studio preview playback. Use action='seek' with `time` to move the playhead — new actions are added at the playhead.",
+			inputSchema: schema(
+				{
+					action: S.string("play, pause, toggle, seek or loop", {
+						enum: ["play", "pause", "toggle", "seek", "loop"],
+					}),
+					time: S.number("Target time in seconds (seek)"),
+					loop: S.bool("Loop on/off"),
+				},
+				["action"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_screenshot",
+			command: "motion.screenshot",
+			description:
+				"Renders the motion scene at a given time and returns it as a PNG image. Use this to VERIFY what an animation actually looks like — check a few times across the duration after editing.",
+			inputSchema: schema({
+				time: S.number("Time in seconds (defaults to the playhead)"),
+				scale: S.number("Render scale (default 1)"),
+				maxWidth: S.number("Maximum output width in px (default 1600)"),
+			}),
+			timeoutMs: 120_000,
+			mapResult: (result) => ({
+				content: [
+					{ type: "image", data: result.base64, mimeType: result.mimeType || "image/png" },
+					{ type: "text", text: `Motion frame @ ${Number(result.atTime || 0).toFixed(2)}s` },
+				],
+			}),
+		}),
+
+		{
+			name: "creavit_motion_history",
+			description: "Undoes the last Motion Studio change, or redoes it.",
+			inputSchema: schema(
+				{ action: S.string("undo or redo", { enum: ["undo", "redo"] }) },
+				["action"],
+			),
+			run: async ({ action }) => {
+				if (action !== "undo" && action !== "redo") {
+					throw new Error("`action` must be either 'undo' or 'redo'");
+				}
+				return textResult(await callCommand("motion.history", { action }));
+			},
+		},
+
+		bridgeTool({
+			name: "creavit_motion_export",
+			command: "motion.export",
+			description:
+				"Exports the motion scene. Formats: video (mp4), gif, json, lottie, html (zip). Video/GIF rendering takes minutes and the file is written to the Downloads folder; follow progress with creavit_events (motion.export.started / finished / failed).",
+			inputSchema: schema({
+				format: S.string("video, gif, json, lottie or html", {
+					enum: ["video", "gif", "json", "lottie", "html"],
+				}),
+				scale: S.number("Render scale for video/gif: 0.5, 1, 1.5 or 2"),
+			}),
+			timeoutMs: 1_800_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_import",
+			command: "motion.import",
+			description:
+				"Adds elements from an exported motion JSON / Lottie payload into the open scene. Pass the parsed object as `payload` or raw text as `json`.",
+			inputSchema: schema({
+				payload: S.object("Motion JSON payload object"),
+				json: S.string("Raw JSON text"),
+			}),
+			timeoutMs: 120_000,
+		}),
+	];
+}

package/src/tools/motion/timelineTools.mjs

@@ -0,0 +1,54 @@
+// MCP araçları — ana timeline'daki motion segmentleri, kütüphane ve şablonlar.
+
+import { bridgeTool, schema, S } from "../defineTool.mjs";
+
+export function motionTimelineTools() {
+	return [
+		bridgeTool({
+			name: "creavit_motion_segments",
+			command: "motion.segments",
+			description:
+				"Motion segments on the MAIN editor timeline (the overlays composited on top of the video): action='list' to read them, 'add' to place a new one (opens Motion Studio unless open=false), 'update' to move/resize/transform one, 'remove' to delete. Works with Motion Studio closed.",
+			inputSchema: schema({
+				action: S.string("list, add, update or remove (default list)", {
+					enum: ["list", "add", "update", "remove"],
+				}),
+				id: S.string("Segment ID (update, remove)"),
+				startTime: S.number("Timeline position in seconds (add)"),
+				duration: S.number("Duration in seconds (add)"),
+				name: S.string("Segment name (add)"),
+				open: S.bool("Open Motion Studio on the new segment (default true)"),
+				patch: S.object("Update fields: startTime, duration, name, position, scale, rotation, opacity"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_library",
+			command: "motion.library",
+			description:
+				"Reusable motion library: action='list' saved motions, 'save' the open scene into it, 'rename', 'remove', or 'addToTimeline' to drop a saved motion onto the video timeline at `startTime`.",
+			inputSchema: schema({
+				action: S.string("list, save, rename, remove or addToTimeline (default list)", {
+					enum: ["list", "save", "rename", "remove", "addToTimeline"],
+				}),
+				id: S.string("Library motion ID"),
+				name: S.string("Name (save, rename)"),
+				startTime: S.number("Timeline position in seconds (addToTimeline)"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_motion_templates",
+			command: "motion.templates",
+			description:
+				"Online motion template gallery: action='list' (optionally filtered by `category` or `search`) to browse ready-made animations, action='apply' with `templateId` to add one into the open scene. Applying needs Motion Studio to be open.",
+			inputSchema: schema({
+				action: S.string("list or apply (default list)", { enum: ["list", "apply"] }),
+				templateId: S.string("Template ID (apply)"),
+				category: S.string("Category filter (list)"),
+				search: S.string("Text search across name, description and tags (list)"),
+			}),
+			timeoutMs: 60_000,
+		}),
+	];
+}

package/src/tools/motionTools.mjs

@@ -0,0 +1,11 @@
+// MCP araçları — Motion Studio.
+// Motion Studio editör penceresi içinde bir moddur: önce creavit_project_open ile
+// editör açılır, sonra creavit_motion_open ile motion moduna girilir.
+
+import { motionSessionTools } from "./motion/sessionTools.mjs";
+import { motionElementTools } from "./motion/elementTools.mjs";
+import { motionTimelineTools } from "./motion/timelineTools.mjs";
+
+export function motionTools() {
+	return [...motionSessionTools(), ...motionElementTools(), ...motionTimelineTools()];
+}