@openvidstudio/mcp-server 0.1.0

package/dist/tools/mcp.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * MCP content + error-wrapping helpers, matching pepiros/mcp/tools/index.ts's pattern:
+ * MCP wants `{ content: [...] }`, JSON text content keeps it parseable on the model's side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.json = json;
+exports.errorText = errorText;
+exports.runTool = runTool;
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function errorText(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/**
+ * Every tool handler routes through this: run the pure logic function, wrap a
+ * successful result as MCP JSON content, and turn any thrown error into MCP
+ * error content instead of letting it escape uncaught. A "no, this is invalid"
+ * result (validate_beats' `{ valid: false, errors }`, scaffold_scene refusing an
+ * existing file) is handled by the logic function returning/throwing normally --
+ * this wrapper is what guarantees neither path ever reaches the transport as an
+ * unhandled rejection. The diagnostic also goes to stderr: this process's own
+ * stdout carries nothing but MCP protocol frames.
+ */
+async function runTool(toolName, fn) {
+    try {
+        const result = await fn();
+        return json(result);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`openvidstudio-mcp: ${toolName} failed: ${message}\n`);
+        return errorText(message);
+    }
+}

package/dist/tools/planBeats.d.ts

@@ -0,0 +1,40 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type ArcName = "simple" | "packed" | "tutorial";
+export interface PlanBeatsInput {
+    projectRoot?: string;
+    targetDurationSeconds: number;
+    arc?: ArcName;
+    /** One demo beat is planned per feature named here. */
+    features?: string[];
+    appUrl?: string;
+    fps?: number;
+}
+export interface PlannedBeat {
+    id: string;
+    start: number;
+    duration: number;
+    seconds: number;
+    captureMethod: "screenshot" | "recording" | "dom-demo" | "higgsfield";
+    /** Inclusive word count range that will pass validate_beats for this duration. */
+    wordBudget: {
+        min: number;
+        max: number;
+        suggested: number;
+    };
+    purpose: string;
+}
+export interface PlanBeatsResult {
+    fps: number;
+    totalFrames: number;
+    totalSeconds: number;
+    arc: ArcName;
+    totalWordBudget: {
+        min: number;
+        max: number;
+        suggested: number;
+    };
+    beats: PlannedBeat[];
+    notes: string[];
+}
+export declare function runPlanBeats(input: PlanBeatsInput): PlanBeatsResult;
+export declare function registerPlanBeats(server: McpServer): void;

package/dist/tools/planBeats.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPlanBeats = runPlanBeats;
+exports.registerPlanBeats = registerPlanBeats;
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const config_1 = require("../config");
+const mcp_1 = require("./mcp");
+/**
+ * validate_beats enforces SCRIPT.md's 2.3-2.9 words/sec as a hard floor and ceiling,
+ * per beat. SCRIPT.md reads like guidance, so the usual first draft gets rejected,
+ * and often for being too *sparse*, which is not the failure anyone expects from a
+ * pacing rule. The other repeat rejection is `screenshot` beats missing `url` and
+ * `interactions`, which no doc states up front.
+ *
+ * This hands back a skeleton that already satisfies both, with the word budget stated
+ * per beat, so narration is written to a number instead of guessed and revised.
+ */
+const PACE_MIN = 2.3;
+const PACE_MAX = 2.9;
+function slotsFor(arc, features) {
+    const demo = features.length ? features : ["feature"];
+    if (arc === "simple") {
+        return [
+            { id: "hook", weight: 8, method: "screenshot", purpose: "What it is, in one line, over the real product" },
+            { id: "problem", weight: 11, method: "dom-demo", purpose: "What is broken today" },
+            ...demo.slice(0, 3).map((f, i) => ({
+                id: `demo-${slug(f) || i + 1}`,
+                weight: 13,
+                method: "screenshot",
+                purpose: `Show ${f} working`,
+            })),
+            { id: "differentiator", weight: 10, method: "dom-demo", purpose: "Why this rather than the obvious alternative" },
+            { id: "cta", weight: 9, method: "dom-demo", purpose: "Where to get it" },
+        ];
+    }
+    if (arc === "tutorial") {
+        return [
+            { id: "hook", weight: 8, method: "screenshot", purpose: "What the viewer will be able to do by the end" },
+            { id: "prereqs", weight: 8, method: "dom-demo", purpose: "What must exist first" },
+            { id: "install", weight: 9, method: "dom-demo", purpose: "Getting it onto the machine" },
+            { id: "setup", weight: 9, method: "dom-demo", purpose: "Wiring it up" },
+            ...demo.map((f, i) => ({
+                id: `step-${slug(f) || i + 1}`,
+                weight: 11,
+                method: "screenshot",
+                purpose: `Walk through ${f}`,
+            })),
+            { id: "result", weight: 7, method: "dom-demo", purpose: "The finished artefact" },
+            { id: "recap", weight: 6, method: "dom-demo", purpose: "The steps as one reference card" },
+            { id: "cta", weight: 6, method: "dom-demo", purpose: "Where to get it" },
+        ];
+    }
+    // packed: one dense hero beat that states everything, then one demo per claim.
+    return [
+        { id: "hook", weight: 15, method: "screenshot", purpose: "Everything the product does, stated once, for a cold viewer" },
+        ...demo.map((f, i) => ({
+            id: `demo-${slug(f) || i + 1}`,
+            weight: 12,
+            method: "screenshot",
+            purpose: `Back the hook's claim about ${f}`,
+        })),
+        { id: "differentiator", weight: 10, method: "dom-demo", purpose: "The one thing nothing else does" },
+        { id: "cta", weight: 8, method: "dom-demo", purpose: "Where to get it" },
+    ];
+}
+function slug(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 24);
+}
+function runPlanBeats(input) {
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const config = (0, config_1.loadConfig)(projectRoot);
+    const fps = input.fps ?? config.videoConfig.fps ?? 30;
+    const arc = input.arc ?? "simple";
+    const appUrl = input.appUrl ?? config.capture.appUrl;
+    const totalFrames = Math.round(input.targetDurationSeconds * fps);
+    const slots = slotsFor(arc, input.features ?? []);
+    const weightTotal = slots.reduce((a, s) => a + s.weight, 0);
+    const beats = [];
+    let start = 0;
+    slots.forEach((slot, i) => {
+        // Last beat absorbs the rounding so the total lands exactly on target.
+        const raw = Math.round((slot.weight / weightTotal) * totalFrames);
+        const duration = i === slots.length - 1 ? totalFrames - start : raw;
+        const seconds = duration / fps;
+        const min = Math.ceil(PACE_MIN * seconds);
+        const max = Math.floor(PACE_MAX * seconds);
+        beats.push({
+            id: slot.id,
+            start,
+            duration,
+            seconds: Number(seconds.toFixed(2)),
+            captureMethod: slot.method,
+            wordBudget: { min, max, suggested: Math.round((min + max) / 2) },
+            purpose: slot.purpose,
+        });
+        start += duration;
+    });
+    const notes = [
+        `Word budgets are the range validate_beats will accept for each duration. Write to the suggested ` +
+            `number: it sits mid band, so a small edit later does not push the beat out of range.`,
+        `Every beat with captureMethod "screenshot" also needs visual.url and visual.interactions (an array, ` +
+            `which may be empty). validate_beats rejects the beat without them, and no other doc states this up front.`,
+        `Capture beats default to ${appUrl}. Change capture.appUrl in openvidstudio.config.json, or set a url ` +
+            `per beat.`,
+        `Beats must stay contiguous: each start equals the previous start plus its duration. These already are.`,
+    ];
+    const totalBudget = beats.reduce((a, b) => ({
+        min: a.min + b.wordBudget.min,
+        max: a.max + b.wordBudget.max,
+        suggested: a.suggested + b.wordBudget.suggested,
+    }), { min: 0, max: 0, suggested: 0 });
+    return {
+        fps,
+        totalFrames,
+        totalSeconds: Number((totalFrames / fps).toFixed(2)),
+        arc,
+        totalWordBudget: totalBudget,
+        beats,
+        notes,
+    };
+}
+function registerPlanBeats(server) {
+    server.registerTool("plan_beats", {
+        title: "Plan a beat skeleton with word budgets before writing narration",
+        description: "Given a target duration and the features to show, returns a contiguous beat skeleton with a " +
+            "capture method and a narration word budget per beat. The budget is the range validate_beats will " +
+            "actually accept, which matters because SCRIPT.md's 2.3 to 2.9 words per second reads like guidance " +
+            "but is enforced as a hard floor and ceiling per beat, and first drafts are commonly rejected for " +
+            "being too sparse rather than too long. Writing to a stated number avoids that round trip. Three " +
+            "arcs: simple (single feature, hook to CTA), packed (one dense hero beat then one demo per claim), " +
+            "tutorial (prerequisites, install, setup, steps, recap). Output feeds straight into validate_beats " +
+            "once narration is written in.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            targetDurationSeconds: zod_1.z.number().positive(),
+            arc: zod_1.z.enum(["simple", "packed", "tutorial"]).optional(),
+            features: zod_1.z.array(zod_1.z.string()).optional(),
+            appUrl: zod_1.z.string().optional(),
+            fps: zod_1.z.number().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("plan_beats", () => runPlanBeats(input)));
+}

package/dist/tools/preflight.d.ts

@@ -0,0 +1,30 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * The pipeline assumes its environment. Without this, a missing ffmpeg or an
+ * undownloaded Chromium surfaces several steps in, as a symptom rather than a fix,
+ * often after a long render has already started.
+ *
+ * Every failing check states the fix, with the command for the caller's platform.
+ */
+export interface PreflightInput {
+    projectRoot?: string;
+    /** Overrides the app url in openvidstudio.config.json. */
+    appUrl?: string;
+}
+export interface Check {
+    name: string;
+    ok: boolean;
+    detail: string;
+    /** Present when the check failed: what to actually run. */
+    fix?: string;
+    /** A failure that stops the pipeline, versus one that only limits it. */
+    blocking: boolean;
+}
+export interface PreflightResult {
+    ok: boolean;
+    platform: string;
+    checks: Check[];
+    blockers: string[];
+}
+export declare function runPreflight(input: PreflightInput): Promise<PreflightResult>;
+export declare function registerPreflight(server: McpServer): void;

package/dist/tools/preflight.js

@@ -0,0 +1,170 @@
+"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.runPreflight = runPreflight;
+exports.registerPreflight = registerPreflight;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const config_1 = require("../config");
+const mcp_1 = require("./mcp");
+function which(cmd) {
+    const probe = process.platform === "win32" ? "where" : "which";
+    const r = (0, node_child_process_1.spawnSync)(probe, [cmd], { encoding: "utf8" });
+    if (r.status !== 0)
+        return null;
+    return (r.stdout ?? "").split(/\r?\n/)[0]?.trim() || null;
+}
+function platformFix(win, mac, linux) {
+    if (process.platform === "win32")
+        return win;
+    if (process.platform === "darwin")
+        return mac;
+    return linux;
+}
+async function urlResponds(url, timeoutMs = 4000) {
+    try {
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), timeoutMs);
+        const res = await fetch(url, { signal: ctl.signal, redirect: "follow" });
+        clearTimeout(t);
+        return res.ok || (res.status >= 200 && res.status < 500);
+    }
+    catch {
+        return false;
+    }
+}
+async function runPreflight(input) {
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const config = (0, config_1.loadConfig)(projectRoot);
+    const appUrl = input.appUrl ?? config.capture.appUrl;
+    const checks = [];
+    const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    checks.push({
+        name: "node",
+        ok: nodeMajor >= 18,
+        detail: `node ${process.versions.node}`,
+        fix: nodeMajor >= 18 ? undefined : "Install Node 18 or newer from nodejs.org.",
+        blocking: true,
+    });
+    const ffmpeg = which("ffmpeg");
+    checks.push({
+        name: "ffmpeg",
+        ok: Boolean(ffmpeg),
+        detail: ffmpeg ? `found at ${ffmpeg}` : "not on PATH",
+        fix: ffmpeg
+            ? undefined
+            : platformFix("winget install --id Gyan.FFmpeg -e", "brew install ffmpeg", "sudo apt update && sudo apt install -y ffmpeg"),
+        blocking: true,
+    });
+    // Playwright keeps its browsers in a per-user cache; the surest check is asking it.
+    const pw = (0, node_child_process_1.spawnSync)(process.platform === "win32" ? "npx.cmd" : "npx", ["playwright", "--version"], { cwd: projectRoot, encoding: "utf8" });
+    const pwOk = pw.status === 0;
+    checks.push({
+        name: "playwright",
+        ok: pwOk,
+        detail: pwOk ? (pw.stdout ?? "").trim() : "playwright not resolvable in this project",
+        fix: pwOk ? undefined : "npm install playwright && npx playwright install chromium",
+        blocking: true,
+    });
+    const cacheDirs = [
+        path.join(process.env.LOCALAPPDATA ?? "", "ms-playwright"),
+        path.join(process.env.HOME ?? "", ".cache", "ms-playwright"),
+        path.join(process.env.HOME ?? "", "Library", "Caches", "ms-playwright"),
+    ].filter(Boolean);
+    const chromium = cacheDirs.some((d) => fs.existsSync(d) && fs.readdirSync(d).some((e) => e.startsWith("chromium")));
+    checks.push({
+        name: "chromium",
+        ok: chromium,
+        detail: chromium ? "browser binaries present" : "no chromium build in the Playwright cache",
+        fix: chromium ? undefined : "npx playwright install chromium",
+        blocking: true,
+    });
+    const responds = await urlResponds(appUrl);
+    checks.push({
+        name: "app",
+        ok: responds,
+        detail: responds ? `${appUrl} responds` : `${appUrl} did not respond`,
+        fix: responds
+            ? undefined
+            : `Start the app you want to film, then set capture.appUrl in openvidstudio.config.json if the port differs.`,
+        blocking: true,
+    });
+    let writable = false;
+    try {
+        const probe = path.join(projectRoot, ".openvidstudio-write-probe");
+        fs.writeFileSync(probe, "");
+        fs.rmSync(probe);
+        writable = true;
+    }
+    catch {
+        writable = false;
+    }
+    checks.push({
+        name: "writable",
+        ok: writable,
+        detail: writable ? `${projectRoot} is writable` : `cannot write to ${projectRoot}`,
+        fix: writable ? undefined : "Check permissions on the project directory.",
+        blocking: true,
+    });
+    const narrationCmd = config.narration.engine === "edge-tts" ? "edge-tts" : config.narration.engine;
+    const narration = Boolean(which(narrationCmd)) || Boolean(which("python"));
+    checks.push({
+        name: "narration",
+        ok: narration,
+        detail: narration ? `${config.narration.engine} available` : `${config.narration.engine} not found`,
+        fix: narration ? undefined : "pip install edge-tts",
+        blocking: false,
+    });
+    const blockers = checks.filter((c) => !c.ok && c.blocking).map((c) => `${c.name}: ${c.fix ?? c.detail}`);
+    return { ok: blockers.length === 0, platform: process.platform, checks, blockers };
+}
+function registerPreflight(server) {
+    server.registerTool("preflight", {
+        title: "Check the machine can actually run the pipeline",
+        description: "Verifies node, ffmpeg, Playwright and its Chromium build, that the app you want to film is " +
+            "responding, that the project directory is writable, and that a narration engine is available. " +
+            "Every failure names the fix with the command for this platform, rather than describing a symptom. " +
+            "Run it before init_project on a new machine: without it a missing dependency surfaces several " +
+            "steps later, often after a long render has already started. Narration is reported as non blocking, " +
+            "since a silent video still renders.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            appUrl: zod_1.z.string().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("preflight", () => runPreflight(input)));
+}

package/dist/tools/qcExtractFrames.d.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface QcExtractFramesInput {
+    projectRoot?: string;
+    videoName: string;
+    videoPath?: string;
+}
+export interface QcFrame {
+    beatId: string;
+    midPath: string;
+    endPath: string;
+}
+export interface QcExtractFramesResult {
+    frames: QcFrame[];
+}
+/** Pure argv builder, unit-testable without spawning ffmpeg. */
+export declare function buildFfmpegFrameArgs(videoPath: string, timestampSeconds: number, outFile: string): string[];
+/**
+ * Wraps PIPELINE.md's QC frame-extraction step. For every beat, computes both its
+ * midpoint frame AND its end frame (a static crop that looks fine early can push
+ * content off-frame once the camera has zoomed in, so the end matters too, not just
+ * the midpoint), converts to timestamps using the beats file's fps, and shells out to
+ * ffmpeg via spawn with an argv array.
+ */
+export declare function runQcExtractFrames(input: QcExtractFramesInput): Promise<QcExtractFramesResult>;
+export declare function registerQcExtractFrames(server: McpServer): void;

package/dist/tools/qcExtractFrames.js

@@ -0,0 +1,129 @@
+"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.buildFfmpegFrameArgs = buildFfmpegFrameArgs;
+exports.runQcExtractFrames = runQcExtractFrames;
+exports.registerQcExtractFrames = registerQcExtractFrames;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const mcp_1 = require("./mcp");
+/** Pure argv builder, unit-testable without spawning ffmpeg. */
+function buildFfmpegFrameArgs(videoPath, timestampSeconds, outFile) {
+    return [
+        "-nostdin",
+        "-ss",
+        timestampSeconds.toFixed(3),
+        "-i",
+        videoPath,
+        "-frames:v",
+        "1",
+        "-q:v",
+        "3",
+        outFile,
+        "-y",
+    ];
+}
+/**
+ * Wraps PIPELINE.md's QC frame-extraction step. For every beat, computes both its
+ * midpoint frame AND its end frame (a static crop that looks fine early can push
+ * content off-frame once the camera has zoomed in, so the end matters too, not just
+ * the midpoint), converts to timestamps using the beats file's fps, and shells out to
+ * ffmpeg via spawn with an argv array.
+ */
+async function runQcExtractFrames(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const videoDir = path.join(projectRoot, "src", "videos", videoName);
+    const beatsPath = path.join(videoDir, "beats.json");
+    if (!fs.existsSync(beatsPath)) {
+        throw new Error(`${beatsPath} does not exist. Call write_beats_file for "${videoName}" first.`);
+    }
+    const beatsData = JSON.parse(fs.readFileSync(beatsPath, "utf8"));
+    const beats = beatsData.beats;
+    if (!Array.isArray(beats) || beats.length === 0) {
+        throw new Error(`${beatsPath} has no beats.`);
+    }
+    const fps = beatsData.fps ?? 30;
+    const videoPathRel = input.videoPath ?? path.join("out", `${videoName}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, videoPathRel, "videoPath");
+    const videoPathAbs = path.join(projectRoot, videoPathRel);
+    if (!fs.existsSync(videoPathAbs)) {
+        throw new Error(`${videoPathAbs} does not exist. Call render_video first (or pass an explicit videoPath).`);
+    }
+    const outDirRel = path.join("out", "qc", videoName);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outDirRel, "outDir");
+    const outDirAbs = path.join(projectRoot, outDirRel);
+    fs.mkdirSync(outDirAbs, { recursive: true });
+    const frames = [];
+    const failures = [];
+    for (const beat of beats) {
+        const midFrame = beat.start + beat.duration / 2;
+        const endFrame = beat.start + beat.duration - 1;
+        const midPath = path.join(outDirAbs, `${beat.id}-mid.jpg`);
+        const endPath = path.join(outDirAbs, `${beat.id}-end.jpg`);
+        const midResult = await (0, util_1.spawnCapture)("ffmpeg", buildFfmpegFrameArgs(videoPathAbs, midFrame / fps, midPath), projectRoot);
+        if (midResult.code !== 0) {
+            failures.push(`${beat.id} (mid): ffmpeg exited ${midResult.code}: ${midResult.stderr.slice(-500)}`);
+        }
+        const endResult = await (0, util_1.spawnCapture)("ffmpeg", buildFfmpegFrameArgs(videoPathAbs, endFrame / fps, endPath), projectRoot);
+        if (endResult.code !== 0) {
+            failures.push(`${beat.id} (end): ffmpeg exited ${endResult.code}: ${endResult.stderr.slice(-500)}`);
+        }
+        frames.push({ beatId: beat.id, midPath, endPath });
+    }
+    if (failures.length > 0) {
+        throw new Error(`ffmpeg frame extraction failed for:\n${failures.join("\n")}`);
+    }
+    return { frames };
+}
+function registerQcExtractFrames(server) {
+    server.registerTool("qc_extract_frames", {
+        title: "Extract QC frames for every beat",
+        description: "Wraps PIPELINE.md's QC frame-extraction step. Reads beats.json, and for every beat computes its " +
+            "midpoint frame AND its end frame (PIPELINE.md's QC checklist specifically calls out checking the " +
+            "end of every real-screenshot/recording beat, not just the midpoint), converts frame numbers to " +
+            "timestamps using the beats file's fps, and shells out to ffmpeg per beat via child_process.spawn " +
+            "with an argv array (never a shell string). Default videoPath is out/<videoName>.mp4, default " +
+            "output dir is out/qc/<videoName>/. Returns { frames: [{ beatId, midPath, endPath }] } so the " +
+            "calling agent knows exactly which paths to Read as images for its own visual QC pass.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            videoPath: zod_1.z.string().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("qc_extract_frames", () => runQcExtractFrames(input)));
+}

package/dist/tools/renderVideo.d.ts

@@ -0,0 +1,43 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface RenderVideoInput {
+    projectRoot?: string;
+    videoName: string;
+    compositionId?: string;
+    outPath?: string;
+    /**
+     * Draft renders at half resolution with a cheaper encode. A five minute video is
+     * 9000 frames and tens of minutes at full quality, which is far too slow a loop
+     * for checking whether the video is right.
+     */
+    draft?: boolean;
+    /**
+     * Parallel render workers. Left unset, Remotion takes as much of the machine as it
+     * can: one render here spawned 25 Chrome workers and starved everything else on the
+     * box, including a second pipeline step running at the same time.
+     */
+    concurrency?: number;
+}
+export interface RenderVideoResult {
+    success: boolean;
+    outPath: string;
+    draft: boolean;
+    elapsedSeconds: number;
+    stdout: string;
+    stderr: string;
+}
+export interface RenderCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * Pure argv builder, unit-testable without spawning a real process. On Windows, npx is
+ * a .cmd shim -- Node's spawn() can only execute that via an internal cmd.exe hop even
+ * with shell:false, which is why compositionId/outPath both get sanitized against
+ * cmd.exe metacharacters before ever reaching this function (see util.ts).
+ */
+export declare function buildRenderCommand(compositionId: string, outPath: string, opts?: {
+    draft?: boolean;
+    concurrency?: number;
+}): RenderCommand;
+export declare function runRenderVideo(input: RenderVideoInput): Promise<RenderVideoResult>;
+export declare function registerRenderVideo(server: McpServer): void;