creavit-studio-mcp 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "creavit-studio-mcp",
-	"version": "1.2.0",
+	"version": "1.2.1",
 	"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/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,