@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/scenes/videoDuration.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Real duration of a video file on disk, in whole frames at `fps`, via ffprobe.
+ *
+ * scaffold_scene runs synchronously (like pngSize, a plain fs read), so this shells out
+ * with execFileSync rather than the async spawnCapture the capture tools use -- there is
+ * no concurrent work here for an async call to overlap with. ffprobe is not a new
+ * dependency: capture_screen_recording already requires it alongside ffmpeg for the same
+ * best-effort duration lookup (see its own probeDurationMs).
+ *
+ * Returns null (never throws) when ffprobe is missing or the file can't be probed, so a
+ * beat scaffolded before capture_screen_recording ran, or on a machine without ffmpeg
+ * installed yet, degrades to the old "no hold" behaviour instead of failing scaffold_scene
+ * outright.
+ */
+export declare function probeVideoDurationFrames(filePath: string, fps: number): number | null;

package/dist/scenes/videoDuration.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeVideoDurationFrames = probeVideoDurationFrames;
+const node_child_process_1 = require("node:child_process");
+/**
+ * Real duration of a video file on disk, in whole frames at `fps`, via ffprobe.
+ *
+ * scaffold_scene runs synchronously (like pngSize, a plain fs read), so this shells out
+ * with execFileSync rather than the async spawnCapture the capture tools use -- there is
+ * no concurrent work here for an async call to overlap with. ffprobe is not a new
+ * dependency: capture_screen_recording already requires it alongside ffmpeg for the same
+ * best-effort duration lookup (see its own probeDurationMs).
+ *
+ * Returns null (never throws) when ffprobe is missing or the file can't be probed, so a
+ * beat scaffolded before capture_screen_recording ran, or on a machine without ffmpeg
+ * installed yet, degrades to the old "no hold" behaviour instead of failing scaffold_scene
+ * outright.
+ */
+function probeVideoDurationFrames(filePath, fps) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", filePath], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const seconds = Number.parseFloat(out.trim());
+        if (!Number.isFinite(seconds) || seconds <= 0)
+            return null;
+        return Math.round(seconds * fps);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server.d.ts

@@ -1,7 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { OpenvidstudioConfig } from "./config";
+export * from "./api";
 export declare const SERVER_NAME = "openvidstudio";
-export declare const SERVER_VERSION = "0.1.0";
+export declare const SERVER_VERSION = "1.4.0";
 /**
  * Assembly only, mirrors pepiros/mcp/server.ts's shape: transport lives in the entry
  * point (stdio.ts), not here, so the same server instance could later be served over a

package/dist/server.js

@@ -1,11 +1,28 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_VERSION = exports.SERVER_NAME = void 0;
 exports.createMcpServer = createMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const tools_1 = require("./tools");
+const mcp_1 = require("./tools/mcp");
+// The non-MCP entry points, for callers with no agent in the loop (CI, cron).
+__exportStar(require("./api"), exports);
 exports.SERVER_NAME = "openvidstudio";
-exports.SERVER_VERSION = "0.1.0";
+exports.SERVER_VERSION = "1.4.0";
 /**
  * Assembly only, mirrors pepiros/mcp/server.ts's shape: transport lives in the entry
  * point (stdio.ts), not here, so the same server instance could later be served over a
@@ -32,6 +49,7 @@ function createMcpServer(config) {
                 "init_project copies in from this package's bundled docs.",
         ].join("\n"),
     });
+    (0, mcp_1.rejectUnknownInputs)(server);
     (0, tools_1.registerTools)(server, config);
     return server;
 }

package/dist/stdio.js

@@ -27,7 +27,15 @@ async function main() {
     await server.connect(transport);
     process.stderr.write("openvidstudio-mcp: connected over stdio\n");
 }
-main().catch((err) => {
-    process.stderr.write(`openvidstudio-mcp: fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
-    process.exit(1);
-});
+// `openvidstudio-mcp install <client>` writes the server into a client's MCP config and exits. It is
+// the only mode that prints to stdout; a normal start (no arguments) never does.
+if (process.argv[2] === "install") {
+    const { installCli } = require("./install");
+    process.exit(installCli(process.argv.slice(3)));
+}
+else {
+    main().catch((err) => {
+        process.stderr.write(`openvidstudio-mcp: fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/tools/captureDesktop.d.ts

@@ -0,0 +1,30 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type DesktopPlatform, type LinuxDisplayServer, type Region } from "@openvidstudio/capture";
+export interface CaptureDesktopInput {
+    projectRoot?: string;
+    beatId: string;
+    window?: string;
+    region?: Region;
+    display?: number;
+    durationSeconds: number;
+    framerate?: number;
+    outPath?: string;
+    /** Linux only. Detected from the session when omitted. */
+    displayServer?: LinuxDisplayServer;
+    /** Wayland only: a PipeWire node id from a portal session the caller already negotiated. */
+    pipewireNode?: number;
+    /** Draw the pointer into the recording. Defaults to true. */
+    drawMouse?: boolean;
+}
+export type CaptureBackend = "gdigrab" | "avfoundation" | "x11grab" | "pipewiregrab";
+export interface CaptureDesktopResult {
+    outPath: string;
+    platform: DesktopPlatform;
+    backend: CaptureBackend;
+    durationSeconds: number;
+    framerate: number;
+    window?: string;
+    region?: Region;
+}
+export declare function runCaptureDesktop(input: CaptureDesktopInput): Promise<CaptureDesktopResult>;
+export declare function registerCaptureDesktop(server: McpServer): void;

package/dist/tools/captureDesktop.js

@@ -0,0 +1,225 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCaptureDesktop = runCaptureDesktop;
+exports.registerCaptureDesktop = registerCaptureDesktop;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const capture_1 = require("@openvidstudio/capture");
+const mcp_1 = require("./mcp");
+const facts_1 = require("../facts");
+const regionSchema = zod_1.z.object({
+    x: zod_1.z.number().int().min(0),
+    y: zod_1.z.number().int().min(0),
+    width: zod_1.z.number().int().positive(),
+    height: zod_1.z.number().int().positive(),
+});
+function currentPlatform() {
+    const p = process.platform;
+    if (p === "win32" || p === "darwin" || p === "linux")
+        return p;
+    throw new Error(`capture_desktop does not support platform "${p}". Supported: win32 (gdigrab), darwin (avfoundation), ` +
+        `linux (x11grab on X11, pipewiregrab on Wayland).`);
+}
+/**
+ * Confirms this ffmpeg build can actually capture a Wayland session before starting one.
+ *
+ * pipewiregrab landed in ffmpeg 7.1. Distribution packages lag, and an older build fails
+ * with "No such filter" buried inside a lavfi graph error, which reads as a bug in this
+ * tool rather than as a missing feature in the local ffmpeg.
+ */
+async function assertPipewireAvailable(projectRoot) {
+    const probe = await (0, util_1.spawnCapture)("ffmpeg", (0, capture_1.buildFilterProbeArgs)(), projectRoot);
+    if ((0, capture_1.hasFilter)(probe.stdout + probe.stderr, "pipewiregrab"))
+        return;
+    throw new Error(`This session is Wayland, and the ffmpeg on PATH has no pipewiregrab filter (it was added in ffmpeg 7.1). ` +
+        `Either install a newer ffmpeg built with pipewire support, or run under XWayland and pass ` +
+        `displayServer "x11" to use x11grab. Either way a Wayland capture is not headless: the desktop portal ` +
+        `shows a consent dialog and the surface is chosen there, not by this tool.`);
+}
+/**
+ * The failure modes here are all environmental and all have specific fixes, so they get
+ * specific messages. A generic "ffmpeg exited 1" sends the caller to read an ffmpeg log
+ * for a problem that is usually a permissions dialog or a mistyped window title.
+ */
+function explainFailure(platform, backend, stderr, window) {
+    const tail = stderr.slice(-1200);
+    if (platform === "win32" && window && /Could not find window|gdigrab/i.test(tail)) {
+        return (`No window matched the title "${window}". gdigrab matches the FULL window title exactly, not a substring, ` +
+            `and the window must not be minimized. List candidates with: powershell "Get-Process | Where-Object ` +
+            `{$_.MainWindowTitle} | Select-Object MainWindowTitle". Original ffmpeg output:\n${tail}`);
+    }
+    if (platform === "darwin" && /Operation not permitted|not authorized|avfoundation/i.test(tail)) {
+        return (`macOS refused the screen capture. Grant Screen Recording permission to the terminal or agent process in ` +
+            `System Settings > Privacy & Security > Screen Recording, then restart that process (the permission is ` +
+            `only re-read at launch). Original ffmpeg output:\n${tail}`);
+    }
+    if (platform === "linux" && backend === "pipewiregrab") {
+        return (`pipewiregrab failed. The usual cause is the portal consent dialog being dismissed or timing out: a ` +
+            `Wayland capture always asks, and it cannot run unattended unless you negotiate a portal session ` +
+            `yourself and pass its node id as pipewireNode. Also check that xdg-desktop-portal and a backend for ` +
+            `this desktop (xdg-desktop-portal-gnome, -kde, or -wlr) are installed and running. ` +
+            `Original ffmpeg output:\n${tail}`);
+    }
+    if (platform === "linux" && /Cannot open display|x11grab/i.test(tail)) {
+        return (`x11grab could not open the display. Check that DISPLAY is set. On a Wayland session without XWayland ` +
+            `x11grab cannot work at all: omit displayServer so the session type is detected and the capture goes ` +
+            `through pipewiregrab instead. Original ffmpeg output:\n${tail}`);
+    }
+    return `ffmpeg desktop capture failed:\n${tail}`;
+}
+async function runCaptureDesktop(input) {
+    const result = await captureDesktop(input);
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    (0, facts_1.writeFactRecord)(projectRoot, {
+        tool: "capture_desktop",
+        beatId: (0, util_1.sanitizeSegment)(input.beatId, "beatId"),
+        facts: {
+            kind: "real-capture",
+            outPath: (0, facts_1.relToProject)(projectRoot, result.outPath),
+            bytes: (0, facts_1.fileBytes)(result.outPath),
+            platform: result.platform,
+            backend: result.backend,
+            durationSeconds: result.durationSeconds,
+            window: result.window ?? null,
+        },
+    });
+    return result;
+}
+async function captureDesktop(input) {
+    const beatId = (0, util_1.sanitizeSegment)(input.beatId, "beatId");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const platform = currentPlatform();
+    const framerate = input.framerate ?? 30;
+    const window = input.window ? (0, capture_1.sanitizeWindowTitle)(input.window) : undefined;
+    const displayServer = platform === "linux" ? (input.displayServer ?? (0, capture_1.detectLinuxDisplayServer)()) : undefined;
+    const backend = platform === "win32"
+        ? "gdigrab"
+        : platform === "darwin"
+            ? "avfoundation"
+            : displayServer === "wayland"
+                ? "pipewiregrab"
+                : "x11grab";
+    // Wayland forbids one client from enumerating or addressing another client's windows, by
+    // design. There is no title selector to translate this into, and capturing the whole
+    // screen instead without saying so would be worse than refusing.
+    if (backend === "pipewiregrab" && window) {
+        throw new Error(`Wayland has no window-title selector: a client cannot address another client's surfaces. Omit "window" ` +
+            `and choose the window in the portal's own picker when it appears, or pass a "region" to crop the ` +
+            `captured stream.`);
+    }
+    if (!(input.durationSeconds > 0)) {
+        throw new Error("durationSeconds must be a positive number: a desktop capture has no natural end to detect.");
+    }
+    const outPathRel = input.outPath ?? path.join("public", "video", `${beatId}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const outPathAbs = path.join(projectRoot, outPathRel);
+    fs.mkdirSync(path.dirname(outPathAbs), { recursive: true });
+    if (backend === "pipewiregrab")
+        await assertPipewireAvailable(projectRoot);
+    const args = (0, capture_1.buildDesktopCaptureArgs)({
+        platform,
+        drawMouse: input.drawMouse,
+        displayServer,
+        pipewire: input.pipewireNode !== undefined ? { node: input.pipewireNode } : undefined,
+        window,
+        region: input.region,
+        display: input.display,
+        framerate,
+        durationSeconds: input.durationSeconds,
+        outPath: outPathAbs,
+    });
+    const result = await (0, util_1.spawnCapture)("ffmpeg", args, projectRoot);
+    if (result.code !== 0 || !fs.existsSync(outPathAbs)) {
+        throw new Error(explainFailure(platform, backend, result.stderr, window));
+    }
+    return {
+        outPath: outPathAbs,
+        platform,
+        backend,
+        durationSeconds: input.durationSeconds,
+        framerate,
+        ...(window ? { window } : {}),
+        ...(input.region ? { region: input.region } : {}),
+    };
+}
+function registerCaptureDesktop(server) {
+    server.registerTool("capture_desktop", {
+        title: "Record a desktop application, window, or whole screen",
+        description: "Records real software that has no URL: a desktop app, a native window, an editor, a game, an OS shell. " +
+            "This is the non-browser sibling of capture_screen_recording, and it exists because Playwright can only " +
+            "drive a web page, which meant every beat about a CLI tool or desktop application previously degraded to " +
+            "a hand-authored dom-demo panel. Drives ffmpeg directly (already a dependency) with the right capture " +
+            "device per platform: gdigrab on Windows, avfoundation on macOS, and on Linux either x11grab or, on a "
+            + "Wayland session, pipewiregrab through the desktop portal, chosen automatically from "
+            + "XDG_SESSION_TYPE. A Wayland capture is never headless: the portal shows a consent dialog and the "
+            + "surface is picked there, so `window` is refused on Wayland rather than silently ignored. "
+            + "Pass `window` to " +
+            "record a single window by its title (Windows matches the FULL title exactly and the window must not be " +
+            "minimized), `region` to capture or crop to a rectangle, or neither to record the whole display. " +
+            "`durationSeconds` is required because a screen has no natural end to detect. Output is h264/yuv420p " +
+            "with +faststart and forced-even dimensions, so Remotion's OffthreadVideo can seek it, written by " +
+            "default to public/video/<beatId>.mp4 matching scaffold_scene's real-recording convention. Permission " +
+            "and window-not-found failures return the specific fix for this platform rather than a raw ffmpeg dump. " +
+            "For a terminal session prefer capture_terminal, which produces a themeable, resolution-independent " +
+            "recording rather than pixels.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            beatId: zod_1.z.string().min(1),
+            window: zod_1.z.string().optional().describe("Window title. Windows matches the full title exactly, not a substring."),
+            region: regionSchema.optional().describe("Rectangle to capture, or to crop to when combined with `window`."),
+            display: zod_1.z.number().int().min(0).optional().describe("Display index. Ignored on Windows."),
+            durationSeconds: zod_1.z.number().positive(),
+            framerate: zod_1.z.number().int().positive().optional(),
+            outPath: zod_1.z.string().optional(),
+            drawMouse: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Draw the pointer into the recording. Defaults to true; a desktop demo with no cursor is hard to follow."),
+            displayServer: zod_1.z
+                .enum(["x11", "wayland"])
+                .optional()
+                .describe("Linux only. Detected from XDG_SESSION_TYPE when omitted."),
+            pipewireNode: zod_1.z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Wayland only. A PipeWire node id from a portal session you already negotiated, which skips the consent dialog."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("capture_desktop", () => runCaptureDesktop(input)));
+}

package/dist/tools/captureMobile.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type MobilePlatform = "android" | "ios-simulator";
+export interface CaptureMobileInput {
+    projectRoot?: string;
+    beatId: string;
+    device: MobilePlatform;
+    deviceId?: string;
+    durationSeconds: number;
+    outPath?: string;
+}
+export interface CaptureMobileResult {
+    outPath: string;
+    device: MobilePlatform;
+    deviceId: string;
+    durationSeconds: number;
+}
+export declare function runCaptureMobile(input: CaptureMobileInput): Promise<CaptureMobileResult>;
+export declare function registerCaptureMobile(server: McpServer): void;

package/dist/tools/captureMobile.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCaptureMobile = runCaptureMobile;
+exports.registerCaptureMobile = registerCaptureMobile;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const capture_1 = require("@openvidstudio/capture");
+const mcp_1 = require("./mcp");
+const facts_1 = require("../facts");
+/** `screenrecord` writes to the device, so it needs a device-side path first. */
+const DEVICE_TMP = "/sdcard/openvidstudio-capture.mp4";
+async function captureAndroid(beatId, deviceId, durationSeconds, outPathAbs, projectRoot) {
+    // Android's screenrecord caps at 180s and silently truncates past it rather than failing.
+    if (durationSeconds > 180) {
+        throw new Error(`Android screenrecord has a hard 180 second limit and truncates silently past it. ` +
+            `Requested ${durationSeconds}s. Split this into multiple beats.`);
+    }
+    const record = await (0, util_1.spawnCapture)("adb", (0, capture_1.buildAdbRecordArgs)(DEVICE_TMP, durationSeconds, deviceId), projectRoot);
+    if (record.code !== 0) {
+        const tail = record.stderr.slice(-800);
+        if (/device not found|no devices|unauthorized/i.test(tail)) {
+            throw new Error(`No usable Android device. Run "adb devices" and confirm exactly one shows as "device" (not "unauthorized", ` +
+                `which means the USB debugging prompt on the phone has not been accepted yet). Pass deviceId to pick ` +
+                `between several. Original adb output:\n${tail}`);
+        }
+        if (/not found|is not recognized|ENOENT/i.test(tail)) {
+            throw new Error(`adb is not on PATH. Install Android platform-tools and add it, then re-run. Original error:\n${tail}`);
+        }
+        throw new Error(`adb screenrecord failed:\n${tail}`);
+    }
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-mobile-"));
+    try {
+        const pulled = path.join(tmpDir, "device.mp4");
+        const pull = await (0, util_1.spawnCapture)("adb", (0, capture_1.buildAdbPullArgs)(DEVICE_TMP, pulled, deviceId), projectRoot);
+        if (pull.code !== 0 || !fs.existsSync(pulled)) {
+            throw new Error(`adb pull failed, the recording stayed on the device:\n${pull.stderr.slice(-800)}`);
+        }
+        // screenrecord emits mp4 without a faststart atom, so Remotion can decode it but not seek it.
+        const remux = await (0, util_1.spawnCapture)("ffmpeg", (0, capture_1.buildRemuxArgs)(pulled, outPathAbs), projectRoot);
+        if (remux.code !== 0) {
+            throw new Error(`ffmpeg remux failed:\n${remux.stderr.slice(-800)}`);
+        }
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        await (0, util_1.spawnCapture)("adb", (0, capture_1.buildAdbCleanupArgs)(DEVICE_TMP, deviceId), projectRoot).catch(() => { });
+    }
+}
+async function captureIosSimulator(deviceId, durationSeconds, outPathAbs, projectRoot) {
+    if (process.platform !== "darwin") {
+        throw new Error(`iOS Simulator capture requires macOS and Xcode command line tools; this is ${process.platform}. ` +
+            `A physical iPhone cannot be captured headlessly on any platform, it needs QuickTime on a Mac.`);
+    }
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-mobile-"));
+    try {
+        const raw = path.join(tmpDir, "sim.mp4");
+        // simctl records until interrupted, so the timer IS the duration control and a
+        // timer-triggered stop is the success path, not a failure.
+        const result = await (0, capture_1.spawnForDuration)("xcrun", (0, capture_1.buildSimctlRecordArgs)(raw, deviceId), projectRoot, durationSeconds * 1000);
+        if (!fs.existsSync(raw)) {
+            const tail = result.stderr.slice(-800);
+            if (/No devices are booted|Unable to boot/i.test(tail)) {
+                throw new Error(`No booted simulator. Start one with "xcrun simctl boot <udid>" or open Simulator.app, then re-run. ` +
+                    `Original output:\n${tail}`);
+            }
+            throw new Error(`simctl recordVideo produced no file:\n${tail}`);
+        }
+        const remux = await (0, util_1.spawnCapture)("ffmpeg", (0, capture_1.buildRemuxArgs)(raw, outPathAbs), projectRoot);
+        if (remux.code !== 0) {
+            throw new Error(`ffmpeg remux failed:\n${remux.stderr.slice(-800)}`);
+        }
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+async function runCaptureMobile(input) {
+    const result = await captureMobile(input);
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    (0, facts_1.writeFactRecord)(projectRoot, {
+        tool: "capture_mobile",
+        beatId: (0, util_1.sanitizeSegment)(input.beatId, "beatId"),
+        facts: {
+            kind: "real-capture",
+            outPath: (0, facts_1.relToProject)(projectRoot, result.outPath),
+            bytes: (0, facts_1.fileBytes)(result.outPath),
+            device: result.device,
+            deviceId: result.deviceId,
+            durationSeconds: result.durationSeconds,
+        },
+    });
+    return result;
+}
+async function captureMobile(input) {
+    const beatId = (0, util_1.sanitizeSegment)(input.beatId, "beatId");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const deviceId = input.deviceId ? (0, capture_1.sanitizeDeviceId)(input.deviceId) : undefined;
+    if (!(input.durationSeconds > 0)) {
+        throw new Error("durationSeconds must be a positive number: a screen recording has no natural end to detect.");
+    }
+    const outPathRel = input.outPath ?? path.join("public", "video", `${beatId}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const outPathAbs = path.join(projectRoot, outPathRel);
+    fs.mkdirSync(path.dirname(outPathAbs), { recursive: true });
+    if (input.device === "android") {
+        await captureAndroid(beatId, deviceId, input.durationSeconds, outPathAbs, projectRoot);
+    }
+    else {
+        await captureIosSimulator(deviceId ?? "booted", input.durationSeconds, outPathAbs, projectRoot);
+    }
+    return {
+        outPath: outPathAbs,
+        device: input.device,
+        deviceId: deviceId ?? (input.device === "android" ? "(only device)" : "booted"),
+        durationSeconds: input.durationSeconds,
+    };
+}
+function registerCaptureMobile(server) {
+    server.registerTool("capture_mobile", {
+        title: "Record an Android device or iOS Simulator",
+        description: "Records a real mobile app from a real device, for products that ship on a phone and therefore have no " +
+            "URL a browser can drive. Android goes through adb screenrecord on the device, then pull, then an ffmpeg " +
+            "remux (screenrecord writes mp4 without a faststart atom, which Remotion can decode but not seek); note " +
+            "Android caps recordings at 180 seconds and truncates silently past it, so this tool refuses longer " +
+            "requests rather than returning a short file. iOS uses xcrun simctl against a booted Simulator, stopped " +
+            "on a timer with SIGINT so the container finalizes properly; it requires macOS, and a physical iPhone " +
+            "cannot be captured headlessly on any platform. Pass deviceId (an adb serial or a simulator UDID) to " +
+            "choose between several attached devices. Missing adb, an unauthorized phone, and an unbooted simulator " +
+            "each return the specific command that fixes them. Writes public/video/<beatId>.mp4 by default, matching " +
+            "scaffold_scene's real-recording convention.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            beatId: zod_1.z.string().min(1),
+            device: zod_1.z.enum(["android", "ios-simulator"]),
+            deviceId: zod_1.z.string().optional().describe("adb serial or simulator UDID. Omit when exactly one device is attached."),
+            durationSeconds: zod_1.z.number().positive(),
+            outPath: zod_1.z.string().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("capture_mobile", () => runCaptureMobile(input)));
+}