creavit-studio-mcp 1.2.0 → 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.0",
+	"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/appLauncher.mjs

@@ -0,0 +1,104 @@
+// MCP sunucusu — uygulama kapalıysa başlatma.
+//
+// Köprü yalnızca uygulama çalışırken vardır. Ajanın "önce uygulamayı sen aç"
+// diyememesi her oturumun başında elle müdahale gerektiriyordu. Burası
+// uygulamayı bulur, açar ve köprü hazır olana kadar bekler.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const APP_BUNDLE_NAME = "Creavit Studio.app";
+
+const DEFAULT_APP_PATHS = [
+	path.join("/Applications", APP_BUNDLE_NAME),
+	path.join(os.homedir(), "Applications", APP_BUNDLE_NAME),
+];
+
+/** Açılışın tamamlanması için verilen süre; soğuk başlangıç yavaş olabilir. */
+export const DEFAULT_LAUNCH_TIMEOUT_MS = 45_000;
+const POLL_INTERVAL_MS = 500;
+
+export class AppLaunchError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AppLaunchError";
+	}
+}
+
+/** Uygulama paketinin yolu: env override > /Applications > ~/Applications */
+export function resolveAppPath() {
+	const fromEnv = process.env.CREAVIT_APP_PATH;
+	const candidates = fromEnv ? [fromEnv, ...DEFAULT_APP_PATHS] : DEFAULT_APP_PATHS;
+
+	for (const candidate of candidates) {
+		try {
+			if (candidate && fs.existsSync(candidate)) return candidate;
+		} catch (_) {}
+	}
+	return null;
+}
+
+/** Otomatik başlatma kapatılabilir olmalı (CI, kısıtlı ortam). */
+export function isAutoLaunchEnabled() {
+	return process.env.CREAVIT_MCP_AUTOLAUNCH !== "0";
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Uygulamayı açar (beklemez). macOS'ta `open` kullanılır: zaten açıksa yeni
+ * kopya başlatmaz, kapalıysa başlatır.
+ */
+export function launchApp() {
+	if (process.platform !== "darwin") {
+		throw new AppLaunchError(
+			"Automatic launch is only supported on macOS. Start Creavit Studio manually.",
+		);
+	}
+
+	const appPath = resolveAppPath();
+	if (!appPath) {
+		throw new AppLaunchError(
+			`Could not find ${APP_BUNDLE_NAME} in /Applications or ~/Applications. ` +
+				"Set CREAVIT_APP_PATH to the bundle path, or start the app manually.",
+		);
+	}
+
+	const child = spawn("open", ["-a", appPath], {
+		detached: true,
+		stdio: "ignore",
+	});
+	child.unref();
+	return appPath;
+}
+
+/**
+ * Uygulama çalışmıyorsa başlatır ve köprü yanıt verene kadar bekler.
+ *
+ * @param {object} options
+ * @param {() => Promise<boolean>} options.isRunning Köprü sağlık kontrolü
+ * @param {number} [options.timeoutMs]
+ * @returns {Promise<{ launched: boolean, appPath: string|null }>}
+ */
+export async function ensureAppRunning({
+	isRunning,
+	timeoutMs = DEFAULT_LAUNCH_TIMEOUT_MS,
+}) {
+	if (await isRunning()) return { launched: false, appPath: null };
+
+	const appPath = launchApp();
+	const deadline = Date.now() + timeoutMs;
+
+	while (Date.now() < deadline) {
+		await delay(POLL_INTERVAL_MS);
+		if (await isRunning()) return { launched: true, appPath };
+	}
+
+	throw new AppLaunchError(
+		`Launched ${appPath} but its agent bridge did not become ready within ` +
+			`${Math.round(timeoutMs / 1000)}s. The app may still be starting, or the ` +
+			"bridge may be disabled (CREAVIT_AGENT_BRIDGE=0).",
+	);
+}

package/src/bridgeClient.mjs

@@ -7,6 +7,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { ENDPOINT_FILENAME, APP_NOT_RUNNING_HINT } from "./protocol.mjs";
+import { ensureAppRunning, isAutoLaunchEnabled } from "./appLauncher.mjs";
 
 const DEFAULT_ENDPOINT_DIRS = [
 	path.join(os.homedir(), "Library", "Application Support", "creavit-studio"),
@@ -107,12 +108,39 @@ async function request(route, { method = "GET", body, timeoutMs = 120_000 } = {}
 	return payload.result;
 }
 
+// Otomatik başlatma süreç başına EN FAZLA BİR KEZ denenir. Her başarısız
+// çağrıda yeniden denemek, uygulama gerçekten açılamıyorsa her aracı
+// dakikalarca bekletirdi.
+let autoLaunchAttempt = null;
+
+async function tryAutoLaunch() {
+	if (!isAutoLaunchEnabled()) return false;
+	if (!autoLaunchAttempt) {
+		autoLaunchAttempt = ensureAppRunning({ isRunning: isAppRunning })
+			.then(() => true)
+			.catch(() => false);
+	}
+	return autoLaunchAttempt;
+}
+
 export async function callCommand(command, params, timeoutMs) {
-	return request("/rpc", {
-		method: "POST",
-		body: { command, params: params || {}, timeoutMs },
-		timeoutMs: timeoutMs || 120_000,
-	});
+	const send = () =>
+		request("/rpc", {
+			method: "POST",
+			body: { command, params: params || {}, timeoutMs },
+			timeoutMs: timeoutMs || 120_000,
+		});
+
+	try {
+		return await send();
+	} catch (error) {
+		// Uygulama kapalıysa aç ve komutu bir kez tekrarla; ajanın "önce
+		// uygulamayı elle başlat" demek zorunda kalmaması için.
+		if (!(error instanceof BridgeUnavailableError)) throw error;
+		const launched = await tryAutoLaunch();
+		if (!launched) throw error;
+		return send();
+	}
 }
 
 export async function health() {

package/src/tools/browserTools.mjs

@@ -178,7 +178,8 @@ export function browserTools() {
 		bridgeTool({
 			name: "creavit_browser_interact",
 			command: "browser.interact",
-			description: "Finds a page element by CSS selector or visible text, scrolls to it, moves the real system mouse, and performs a real hover/click/type action.",
+			description:
+				"Finds a page element by CSS selector or visible text, scrolls to it, and performs a hover/click/type action. By default it moves the REAL system mouse, which looks natural in a recording. Set useSystemCursor:false when the user asks you not to touch their cursor — the click is still delivered to the page, the pointer just never moves.",
 			inputSchema: schema(
 				{
 					captureWindowId: S.number("Capture window ID"),
@@ -187,6 +188,9 @@ export function browserTools() {
 					text: S.string("Visible text fallback"),
 					value: S.string("Text to enter for type"),
 					moveDurationMs: S.number("Real mouse travel duration (default 520)"),
+					useSystemCursor: S.bool(
+						"Move the real system cursor (default true). false = never touch the user's pointer; clicks are sent synthetically.",
+					),
 				},
 				["captureWindowId", "action"],
 			),

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()];
+}

package/src/tools/systemTools.mjs

@@ -1,10 +1,38 @@
 // MCP araçları — uygulama durumu, kayıt akışı, cihazlar ve olay akışı.
 
 import { bridgeTool, schema, S, textResult } from "./defineTool.mjs";
-import { callCommand } from "../bridgeClient.mjs";
+import { callCommand, isAppRunning } from "../bridgeClient.mjs";
+import {
+	ensureAppRunning,
+	resolveAppPath,
+	DEFAULT_LAUNCH_TIMEOUT_MS,
+} from "../appLauncher.mjs";
 
 export function systemTools() {
 	return [
+		{
+			name: "creavit_app_launch",
+			description:
+				"Starts Creavit Studio if it is not already running, then waits until its agent bridge is ready. Looks for the app in /Applications and ~/Applications (override with CREAVIT_APP_PATH). Other tools also auto-launch on first use, so call this only when you want to start the app explicitly or check where it was found.",
+			inputSchema: schema({
+				timeoutMs: S.number(
+					`How long to wait for the bridge after launching (default ${DEFAULT_LAUNCH_TIMEOUT_MS})`,
+				),
+			}),
+			run: async (args) => {
+				const appPath = resolveAppPath();
+				const { launched } = await ensureAppRunning({
+					isRunning: isAppRunning,
+					timeoutMs: args?.timeoutMs || DEFAULT_LAUNCH_TIMEOUT_MS,
+				});
+				return textResult({
+					launched,
+					alreadyRunning: !launched,
+					appPath,
+				});
+			},
+		},
+
 		bridgeTool({
 			name: "creavit_app_info",
 			description:
@@ -49,7 +77,7 @@ export function systemTools() {
 				"Starts a screen recording. Get source IDs from creavit_devices_list first. Monitor with creavit_recording_status, and finish with creavit_recording_stop.",
 			inputSchema: schema({
 				options: S.object(
-					"Recording options: {sourceType:'display'|'window'|'area', sourceId, cameraEnabled, micEnabled, systemAudioEnabled, delayMs, area:{x,y,width,height}}",
+					"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.",
 				),
 			}),
 			timeoutMs: 180_000,