creavit-studio-mcp 1.0.0

package/src/rpcServer.mjs

@@ -0,0 +1,118 @@
+// MCP sunucusu — stdio JSON-RPC taşıma katmanı.
+// MCP stdio taşıması satır-sınırlı JSON kullanır: her mesaj tek satır.
+// stdout SADECE protokol mesajları içindir; log'lar stderr'e gider.
+
+import { JSONRPC_ERRORS, MCP_PROTOCOL_VERSION, SERVER_NAME, SERVER_VERSION } from "./protocol.mjs";
+
+export function log(...args) {
+	// stdout protokole ait; teşhis çıktısı stderr'e.
+	console.error("[creavit-mcp]", ...args);
+}
+
+function write(message) {
+	process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function respond(id, result) {
+	if (id === undefined || id === null) return; // bildirim: cevap yok
+	write({ jsonrpc: "2.0", id, result });
+}
+
+function respondError(id, code, message, data) {
+	if (id === undefined || id === null) return;
+	write({ jsonrpc: "2.0", id, error: { code, message, ...(data ? { data } : {}) } });
+}
+
+/**
+ * @param {object} opts
+ * @param {() => Promise<Array>} opts.listTools
+ * @param {(name: string, args: object) => Promise<object>} opts.callTool
+ */
+export function startRpcServer({ listTools, callTool }) {
+	let buffer = "";
+	let initialized = false;
+
+	const handlers = {
+		initialize: async (params) => {
+			initialized = true;
+			log(`initialize (client: ${params?.clientInfo?.name || "unknown"})`);
+			return {
+				protocolVersion: MCP_PROTOCOL_VERSION,
+				capabilities: { tools: { listChanged: false } },
+				serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+			};
+		},
+
+		ping: async () => ({}),
+
+		"tools/list": async () => ({ tools: await listTools() }),
+
+		"tools/call": async (params) => {
+			const name = params?.name;
+			if (!name) {
+				const error = new Error("`name` is required");
+				error.rpcCode = JSONRPC_ERRORS.INVALID_PARAMS;
+				throw error;
+			}
+			return callTool(name, params?.arguments || {});
+		},
+
+		// Bu sunucu kaynak/prompt sunmuyor; istemciler yine de sorabiliyor.
+		"resources/list": async () => ({ resources: [] }),
+		"prompts/list": async () => ({ prompts: [] }),
+	};
+
+	async function handleMessage(message) {
+		const { id, method, params } = message || {};
+
+		if (!method) return; // cevap mesajı — bu sunucu istemci değil, yok say
+
+		if (method.startsWith("notifications/")) {
+			if (method === "notifications/initialized") log("client ready");
+			return;
+		}
+
+		const handler = handlers[method];
+		if (!handler) {
+			respondError(id, JSONRPC_ERRORS.METHOD_NOT_FOUND, `Unknown method: ${method}`);
+			return;
+		}
+
+		if (!initialized && method !== "initialize") {
+			respondError(id, JSONRPC_ERRORS.INVALID_REQUEST, "initialize must be called first");
+			return;
+		}
+
+		try {
+			respond(id, await handler(params));
+		} catch (error) {
+			respondError(
+				id,
+				error?.rpcCode || JSONRPC_ERRORS.INTERNAL_ERROR,
+				error?.message || String(error),
+			);
+		}
+	}
+
+	process.stdin.setEncoding("utf8");
+	process.stdin.on("data", (chunk) => {
+		buffer += chunk;
+		let newlineIndex;
+		while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+			const line = buffer.slice(0, newlineIndex).trim();
+			buffer = buffer.slice(newlineIndex + 1);
+			if (!line) continue;
+			try {
+				handleMessage(JSON.parse(line));
+			} catch (_) {
+				respondError(null, JSONRPC_ERRORS.PARSE_ERROR, "Invalid JSON");
+			}
+		}
+	});
+
+	process.stdin.on("end", () => process.exit(0));
+	process.on("SIGINT", () => process.exit(0));
+	process.on("SIGTERM", () => process.exit(0));
+
+	log(`ready (MCP ${MCP_PROTOCOL_VERSION})`);
+}

package/src/tools/defineTool.mjs

@@ -0,0 +1,59 @@
+// MCP sunucusu — araç tanımı yardımcıları.
+// Her araç bir köprü komutuna karşılık gelir; burada MCP şeması + sonuç
+// biçimlendirmesi standartlaştırılır.
+
+import { callCommand } from "../bridgeClient.mjs";
+
+export const S = {
+	string: (description, extra = {}) => ({ type: "string", description, ...extra }),
+	number: (description, extra = {}) => ({ type: "number", description, ...extra }),
+	bool: (description) => ({ type: "boolean", description }),
+	object: (description, extra = {}) => ({ type: "object", description, ...extra }),
+	array: (description, items = {}) => ({ type: "array", description, items }),
+};
+
+export function schema(properties = {}, required = []) {
+	return {
+		type: "object",
+		properties,
+		...(required.length ? { required } : {}),
+		additionalProperties: false,
+	};
+}
+
+export function textResult(value) {
+	const text =
+		typeof value === "string" ? value : JSON.stringify(value ?? null, null, 2);
+	return { content: [{ type: "text", text }] };
+}
+
+export function errorResult(error) {
+	const parts = [error?.message || String(error)];
+	if (error?.code) parts.push(`code: ${error.code}`);
+	if (error?.details) parts.push(`details: ${JSON.stringify(error.details)}`);
+	return { content: [{ type: "text", text: parts.join("\n") }], isError: true };
+}
+
+/**
+ * Köprü komutunu doğrudan saran araç.
+ * @param {object} def
+ * @param {string} def.name        MCP araç adı
+ * @param {string} def.command     Köprü komutu
+ * @param {string} def.description
+ * @param {object} def.inputSchema
+ * @param {(args:object)=>object} [def.mapParams]  MCP argümanları → komut parametreleri
+ * @param {(result:object, args:object)=>object} [def.mapResult]
+ * @param {number} [def.timeoutMs]
+ */
+export function bridgeTool(def) {
+	return {
+		name: def.name,
+		description: def.description,
+		inputSchema: def.inputSchema || schema(),
+		run: async (args) => {
+			const params = def.mapParams ? def.mapParams(args || {}) : args || {};
+			const result = await callCommand(def.command, params, def.timeoutMs);
+			return def.mapResult ? def.mapResult(result, args || {}) : textResult(result);
+		},
+	};
+}

package/src/tools/editorTools.mjs

@@ -0,0 +1,192 @@
+// MCP araçları — editör kontrolü.
+// Hepsi editör penceresinin açık olmasını gerektirir (creavit_project_open).
+
+import { bridgeTool, schema, S, textResult } from "./defineTool.mjs";
+import { callCommand } from "../bridgeClient.mjs";
+
+export function editorTools() {
+	return [
+		bridgeTool({
+			name: "creavit_editor_state",
+			description:
+				"Live editor state: open project, duration, playhead position, playback state, video resolution, segment count. Call this before editing and wait until duration is greater than 0 — the project is still loading otherwise, and edits made too early get overwritten.",
+			command: "editor.getState",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_get_settings",
+			command: "editor.getSettings",
+			description:
+				"Reads player settings: background (type/color/image/blur/gradient), padding, radius, shadow, camera settings, cursor settings, zoom ranges, CRT effect and more. Without `keys` it returns EVERYTHING (very large) — read selectively.",
+			inputSchema: schema({
+				keys: S.array(
+					"Return only these settings. e.g. ['padding','radius','backgroundType','backgroundColor','zoomRanges','cameraSettings']",
+					{ type: "string" },
+				),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_set_settings",
+			command: "editor.setSettings",
+			description:
+				'Changes player settings and refreshes the canvas. Partial update: only the keys you pass change. e.g. {"padding": 80, "radius": 24, "backgroundType": "gradient"}. Discover valid key names with creavit_editor_get_settings. The response echoes the values read back after writing — check `verified`. Call creavit_project_save afterwards to persist.',
+			inputSchema: schema(
+				{
+					settings: S.object(
+						"Settings to change. Key names must match creavit_editor_get_settings output.",
+					),
+				},
+				["settings"],
+			),
+			mapResult: (result) =>
+				textResult({
+					...result,
+					note: result?.rejected?.length
+						? "Some keys could not be written — confirm the exact name with creavit_editor_get_settings."
+						: "Applied. Call creavit_project_save to persist.",
+				}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_list_zooms",
+			command: "editor.listZooms",
+			description:
+				"Lists zoom ranges on the timeline: id, start/end (seconds), scale, focus x/y (normalized 0-1).",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			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.",
+			inputSchema: schema(
+				{
+					start: S.number("Start time in seconds"),
+					end: S.number("End time in seconds, greater than start"),
+					scale: S.number("Zoom factor, typically 1.5-3 (default 2)"),
+					x: S.number("Horizontal focus 0-1 (default 0.5)"),
+					y: S.number("Vertical focus 0-1 (default 0.5)"),
+				},
+				["start", "end"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_update_zoom",
+			command: "editor.updateZoom",
+			description:
+				"Updates an existing zoom range. Target it by id (from creavit_editor_list_zooms) or by index.",
+			inputSchema: schema(
+				{
+					id: S.string("ID of the zoom range"),
+					index: S.number("Or its position in the list (0-based)"),
+					patch: S.object("Fields to change: start, end, scale, x, y"),
+				},
+				["patch"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_remove_zoom",
+			command: "editor.removeZoom",
+			description: "Deletes a zoom range, targeted by id or index.",
+			inputSchema: schema({
+				id: S.string("ID of the zoom range"),
+				index: S.number("Or its position in the list (0-based)"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_segments",
+			command: "editor.listSegments",
+			description:
+				"Lists timeline segments (cuts/trims). To edit them, read this output, modify it, and write it back with creavit_editor_set_segments.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_set_segments",
+			command: "editor.setSegments",
+			description:
+				"Replaces all timeline segments at once (cutting, trimming, reordering). Read the current structure with creavit_editor_segments FIRST — a malformed list can make the project unplayable.",
+			inputSchema: schema(
+				{ segments: S.array("The complete segment list", { type: "object" }) },
+				["segments"],
+			),
+		}),
+
+		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"]),
+		}),
+
+		{
+			name: "creavit_editor_playback",
+			description: "Starts or pauses preview playback.",
+			inputSchema: schema(
+				{ action: S.string("play or pause", { enum: ["play", "pause"] }) },
+				["action"],
+			),
+			// Komut adı argümana göre değiştiği için bridgeTool yerine elle yönlendiriyoruz.
+			run: async ({ action }) => {
+				if (action !== "play" && action !== "pause") {
+					throw new Error("`action` must be either 'play' or 'pause'");
+				}
+				return textResult(await callCommand(`editor.${action}`, {}));
+			},
+		},
+
+		bridgeTool({
+			name: "creavit_editor_screenshot",
+			command: "editor.screenshot",
+			description:
+				"Returns the current editor canvas frame as a PNG image. Pass `time` to seek there first. Use this to VERIFY how a change actually looks — always take a look after changing settings.",
+			inputSchema: schema({
+				time: S.number("Seek to this time in seconds first (optional)"),
+			}),
+			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` },
+				],
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_export",
+			command: "editor.export",
+			description:
+				"Exports the video. This takes a LONG time (minutes). Follow progress with creavit_events (export.started / export.finished / export.failed). Omitted settings fall back to whatever is selected in the editor.",
+			inputSchema: schema({
+				filePath: S.string("Target file path (.mp4)"),
+				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"),
+			}),
+			timeoutMs: 3_600_000,
+		}),
+
+		{
+			name: "creavit_editor_history",
+			description: "Undoes the last editor 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(`editor.${action}`, {}));
+			},
+		},
+	];
+}

package/src/tools/escapeTools.mjs

@@ -0,0 +1,112 @@
+// MCP araçları — kaçış kapıları.
+// Tipli araçlar uygulamanın tamamını kapsayamaz; bu araçlar ajanın kalan her
+// şeye ulaşmasını sağlar: komut keşfi, ham IPC ve (izin verilirse) serbest kod.
+
+import { schema, S, textResult } from "./defineTool.mjs";
+import { callCommand, listBridgeCommands } from "../bridgeClient.mjs";
+
+export function escapeTools() {
+	return [
+		{
+			name: "creavit_capabilities",
+			description:
+				"Lists EVERY command and editor action the app exposes to agents. When the typed tools (creavit_editor_*, creavit_recording_* …) do not cover what you need, look here and then invoke it with creavit_call. This is the app's real capability surface.",
+			inputSchema: schema({
+				filter: S.string("Filter by name (substring match, e.g. 'zoom')"),
+				includeEditorActions: S.bool(
+					"Also fetch actions registered in the editor window (default true)",
+				),
+			}),
+			run: async ({ filter, includeEditorActions }) => {
+				const { commands } = await listBridgeCommands();
+				let editorActions = null;
+
+				if (includeEditorActions !== false) {
+					try {
+						const result = await callCommand("editor.listActions", {}, 10_000);
+						editorActions = result?.actions || null;
+					} catch (error) {
+						editorActions = { unavailable: error?.message || String(error) };
+					}
+				}
+
+				const match = (name) =>
+					!filter || String(name).toLowerCase().includes(String(filter).toLowerCase());
+
+				return textResult({
+					commands: commands.filter((c) => match(c.name)),
+					editorActions: Array.isArray(editorActions)
+						? editorActions.filter((a) => match(a.name))
+						: editorActions,
+					howToUse:
+						"Invoke a command with creavit_call: {command:'<name>', params:{...}}. " +
+						"For entries in editorActions use command='editor.callAction' with " +
+						"params={action:'<name>', params:{...}}.",
+				});
+			},
+		},
+
+		{
+			name: "creavit_call",
+			description:
+				"Invokes any agent command the app exposes — the general-purpose door for anything the typed tools do not cover. Confirm the command name with creavit_capabilities first.",
+			inputSchema: schema(
+				{
+					command: S.string("Command name, e.g. 'editor.getSettings' or 'ipc.invoke'"),
+					params: S.object("Command parameters"),
+					timeoutMs: S.number("Timeout in milliseconds. Raise it for long operations."),
+				},
+				["command"],
+			),
+			run: async ({ command, params, timeoutMs }) =>
+				textResult(await callCommand(command, params || {}, timeoutMs)),
+		},
+
+		{
+			name: "creavit_ipc",
+			description:
+				"Calls one of the app's raw IPC channels — the lowest level of access: file operations, screen/window queries, settings read-write, FFmpeg operations. Omit `channel` to list every known channel name.",
+			inputSchema: schema({
+				channel: S.string(
+					"IPC channel name, e.g. 'GET_MAC_SCREENS'. Omit to get the list of channels.",
+				),
+				args: S.array("Arguments passed to the channel", {}),
+				timeoutMs: S.number("Timeout in milliseconds"),
+			}),
+			run: async ({ channel, args, timeoutMs }) => {
+				if (!channel) {
+					return textResult(await callCommand("ipc.channels", {}, 10_000));
+				}
+				return textResult(
+					await callCommand("ipc.invoke", { channel, args: args || [] }, timeoutMs || 120_000),
+				);
+			},
+		},
+
+		{
+			name: "creavit_eval",
+			description:
+				"Runs JavaScript inside an app window — LAST RESORT. Disabled by default; the app must be started with CREAVIT_AGENT_BRIDGE_EVAL=1. Try the typed tools and creavit_capabilities first.",
+			inputSchema: schema(
+				{
+					code: S.string("JavaScript to run. Use `return` to produce a value."),
+					windowId: S.number("Target window (defaults to the focused window)"),
+				},
+				["code"],
+			),
+			run: async ({ code, windowId }) =>
+				textResult(await callCommand("debug.eval", { code, windowId }, 60_000)),
+		},
+
+		{
+			name: "creavit_logs",
+			description:
+				"Returns buffered console output from an app window. Use it to diagnose when something behaves unexpectedly.",
+			inputSchema: schema({
+				limit: S.number("How many lines (default 100)"),
+				level: S.string("log | warn | error", { enum: ["log", "warn", "error"] }),
+			}),
+			run: async (args) => textResult(await callCommand("debug.consoleLogs", args || {}, 15_000)),
+		},
+	];
+}

package/src/tools/index.mjs

@@ -0,0 +1,53 @@
+// MCP araçları — birleştirme ve çağrı yönlendirme.
+
+import { projectTools } from "./projectTools.mjs";
+import { editorTools } from "./editorTools.mjs";
+import { systemTools } from "./systemTools.mjs";
+import { escapeTools } from "./escapeTools.mjs";
+import { errorResult } from "./defineTool.mjs";
+import { BridgeUnavailableError } from "../bridgeClient.mjs";
+
+let registry = null;
+
+function buildRegistry() {
+	if (registry) return registry;
+	const all = [...systemTools(), ...projectTools(), ...editorTools(), ...escapeTools()];
+
+	const byName = new Map();
+	for (const tool of all) {
+		if (byName.has(tool.name)) {
+			throw new Error(`Duplicate tool name: ${tool.name}`);
+		}
+		byName.set(tool.name, tool);
+	}
+	registry = byName;
+	return registry;
+}
+
+export async function listTools() {
+	return Array.from(buildRegistry().values()).map(({ name, description, inputSchema }) => ({
+		name,
+		description,
+		inputSchema,
+	}));
+}
+
+export async function callTool(name, args) {
+	const tool = buildRegistry().get(name);
+	if (!tool) {
+		return errorResult(
+			new Error(
+				`Unknown tool: ${name}. Available tools: ${Array.from(buildRegistry().keys()).join(", ")}`,
+			),
+		);
+	}
+
+	try {
+		return await tool.run(args || {});
+	} catch (error) {
+		// Uygulama kapalıysa ajanın ne yapması gerektiğini net söyle; sessizce
+		// "hata" demek yerine yönlendir.
+		if (error instanceof BridgeUnavailableError) return errorResult(error);
+		return errorResult(error);
+	}
+}

package/src/tools/projectTools.mjs

@@ -0,0 +1,90 @@
+// MCP araçları — proje (.crvt) işlemleri.
+// Salt-okunur araçlar önce dosya sisteminden okur; uygulama kapalıyken de
+// çalışsın diye. Özetleme daima yerelde yapılır (manifestSummary.mjs).
+
+import { bridgeTool, schema, S, textResult } from "./defineTool.mjs";
+import { callCommand } from "../bridgeClient.mjs";
+import { canReadOffline, listProjectsOffline, readManifestOffline } from "../crvtReader.mjs";
+import { summarizeManifest } from "../manifestSummary.mjs";
+
+// Manifest'i önce yerelden, olmazsa çalışan uygulamadan al.
+async function loadManifest(filePath) {
+	if (canReadOffline()) {
+		try {
+			return await readManifestOffline(filePath);
+		} catch (error) {
+			// Dosya yoksa köprü de bulamaz; boşuna tur atma.
+			if (String(error?.message || "").includes("ENOENT")) throw error;
+		}
+	}
+	const result = await callCommand("project.readManifest", { filePath });
+	return result?.manifest;
+}
+
+export function projectTools() {
+	return [
+		{
+			name: "creavit_project_list",
+			description:
+				"Lists Creavit Studio projects (.crvt): name, file path, duration, size, modified date. Newest first. Works even when the app is closed. Start here — take the file path for every other project tool from this list.",
+			inputSchema: schema({
+				dir: S.string("Folder to scan. Defaults to ~/Downloads/Creavit Studio"),
+				limit: S.number("Maximum number of projects to return (default 100)"),
+			}),
+			run: async (args) => {
+				if (canReadOffline()) return textResult(await listProjectsOffline(args));
+				return textResult(await callCommand("project.list", args));
+			},
+		},
+
+		{
+			name: "creavit_project_summary",
+			description:
+				"Readable summary of a .crvt project: duration, resolution, background, clip/zoom/segment counts, active effects, media paths. Works even when the app is closed. Call THIS first to understand a project — the full manifest is very large.",
+			inputSchema: schema({ filePath: S.string("Absolute path to the .crvt file") }, ["filePath"]),
+			run: async ({ filePath }) =>
+				textResult(summarizeManifest(await loadManifest(filePath), filePath)),
+		},
+
+		{
+			name: "creavit_project_manifest",
+			description:
+				"Returns the FULL manifest.json of a .crvt project (all player settings, zoom ranges, clips, segments, cursor data). Works even when the app is closed. Can be very large — try creavit_project_summary first.",
+			inputSchema: schema({ filePath: S.string("Absolute path to the .crvt file") }, ["filePath"]),
+			run: async ({ filePath }) =>
+				textResult({ filePath, manifest: await loadManifest(filePath) }),
+		},
+
+		bridgeTool({
+			name: "creavit_project_open",
+			command: "project.open",
+			description:
+				"Opens a .crvt project in the app's editor. Required before any creavit_editor_* tool will work. Loading takes a few seconds — afterwards poll creavit_editor_state until duration is greater than 0 before making changes, otherwise your edits get overwritten when loading finishes.",
+			inputSchema: schema({ filePath: S.string("Absolute path to the .crvt file") }, ["filePath"]),
+			timeoutMs: 120_000,
+		}),
+
+		bridgeTool({
+			name: "creavit_project_reveal",
+			command: "project.reveal",
+			description: "Reveals a file in macOS Finder.",
+			inputSchema: schema({ filePath: S.string("Absolute path to the file") }, ["filePath"]),
+		}),
+
+		bridgeTool({
+			name: "creavit_project_save",
+			command: "editor.saveProject",
+			description:
+				"Saves the project currently open in the editor. Pass filePath to save as a copy, omit it to overwrite the current file. Call this after changing settings to make them permanent.",
+			inputSchema: schema({
+				filePath: S.string("Target .crvt path (omit to overwrite in place)"),
+			}),
+			timeoutMs: 300_000,
+			mapResult: (result) =>
+				textResult({
+					...result,
+					note: "Save complete. Verify what landed on disk with creavit_project_summary.",
+				}),
+		}),
+	];
+}