@openvidstudio/mcp-server 0.1.0

package/dist/tools/generateNarration.js

@@ -0,0 +1,185 @@
+"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.runGenerateNarration = runGenerateNarration;
+exports.registerGenerateNarration = registerGenerateNarration;
+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 mcp_1 = require("./mcp");
+/** Beyond this, a pitch-preserving stretch starts to sound processed. */
+const TEMPO_FLOOR = 0.9;
+const TEMPO_CEIL = 1.12;
+const DEFAULT_VOICE = {
+    "edge-tts": "en-US-AndrewNeural",
+    say: "Alex",
+    espeak: "en-us",
+};
+function probeDuration(file) {
+    const r = (0, node_child_process_1.spawnSync)("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", file], { encoding: "utf8" });
+    const v = Number.parseFloat((r.stdout ?? "").trim());
+    return Number.isFinite(v) ? v : 0;
+}
+function synthesize(engine, voice, text, out) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        fs.rmSync(out, { force: true });
+        let r;
+        if (engine === "edge-tts") {
+            r = (0, node_child_process_1.spawnSync)("edge-tts", ["--voice", voice, "--text", text, "--write-media", out], {
+                encoding: "utf8",
+            });
+            if (r.error) {
+                // Not on PATH as a binary in every install; the module entrypoint always is.
+                r = (0, node_child_process_1.spawnSync)("python", ["-m", "edge_tts", "--voice", voice, "--text", text, "--write-media", out], { encoding: "utf8" });
+            }
+        }
+        else if (engine === "say") {
+            r = (0, node_child_process_1.spawnSync)("say", ["-v", voice, "-o", out, "--data-format=LEF32@22050", text], {
+                encoding: "utf8",
+            });
+        }
+        else {
+            r = (0, node_child_process_1.spawnSync)("espeak", ["-v", voice, "-w", out, text], { encoding: "utf8" });
+        }
+        // A size check alone is not enough: a truncated download can clear it and still
+        // be undecodable, so this validates by actually probing the file.
+        if (!r.error && fs.existsSync(out) && probeDuration(out) > 0.3)
+            return { ok: true };
+    }
+    return { ok: false, error: `no usable audio after 3 attempts` };
+}
+function runGenerateNarration(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const engine = input.engine ?? "edge-tts";
+    const voice = input.voice ?? DEFAULT_VOICE[engine];
+    const pad = input.padSeconds ?? 0.45;
+    const beatsFile = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsFile)) {
+        throw new Error(`No beats.json at ${beatsFile}. Run write_beats_file first.`);
+    }
+    const doc = JSON.parse(fs.readFileSync(beatsFile, "utf8"));
+    const fps = doc.fps || 30;
+    const outDir = path.join(projectRoot, "public", "audio", "vo");
+    fs.mkdirSync(outDir, { recursive: true });
+    const workDir = path.join(projectRoot, ".openvidstudio", "narration");
+    fs.mkdirSync(workDir, { recursive: true });
+    const written = [];
+    const skipped = [];
+    const missing = [];
+    const warnings = [];
+    for (const beat of doc.beats) {
+        if (input.beatIds && !input.beatIds.includes(beat.id))
+            continue;
+        const finalPath = path.join(outDir, `${beat.id}.mp3`);
+        if (!beat.vo || !beat.vo.trim()) {
+            missing.push(beat.id);
+            continue;
+        }
+        if (fs.existsSync(finalPath) && !input.overwrite) {
+            skipped.push(beat.id);
+            continue;
+        }
+        const raw = path.join(workDir, `${beat.id}.raw`);
+        const res = synthesize(engine, voice, beat.vo, raw);
+        if (!res.ok) {
+            missing.push(beat.id);
+            warnings.push(`${beat.id}: ${res.error}`);
+            continue;
+        }
+        const spoken = probeDuration(raw);
+        const beatSeconds = beat.duration / fps;
+        const target = beatSeconds - pad;
+        const wanted = spoken / target;
+        const tempo = Math.min(TEMPO_CEIL, Math.max(TEMPO_FLOOR, wanted));
+        const r = (0, node_child_process_1.spawnSync)("ffmpeg", ["-v", "error", "-i", raw, "-filter:a", `atempo=${tempo.toFixed(4)}`,
+            "-c:a", "libmp3lame", "-q:a", "3", finalPath, "-y"], { encoding: "utf8" });
+        if (r.status !== 0) {
+            missing.push(beat.id);
+            warnings.push(`${beat.id}: ffmpeg failed writing the fitted clip`);
+            continue;
+        }
+        const finalSeconds = probeDuration(finalPath);
+        const overruns = finalSeconds > beatSeconds;
+        const clip = {
+            beatId: beat.id,
+            path: finalPath,
+            beatSeconds: Number(beatSeconds.toFixed(2)),
+            spokenSeconds: Number(spoken.toFixed(2)),
+            finalSeconds: Number(finalSeconds.toFixed(2)),
+            tempo: Number(tempo.toFixed(3)),
+            needsAttention: overruns || Math.abs(wanted - tempo) > 0.001,
+        };
+        if (overruns) {
+            clip.note =
+                `Runs ${(finalSeconds - beatSeconds).toFixed(2)}s past the beat. Shorten the line or ` +
+                    `lengthen the beat; stretching further would sound processed.`;
+            warnings.push(`${beat.id}: narration overruns its beat by ${(finalSeconds - beatSeconds).toFixed(2)}s`);
+        }
+        else if (clip.needsAttention) {
+            const slack = (target - finalSeconds).toFixed(2);
+            clip.note =
+                `Fits with ${slack}s of silence left over. Stretching was clamped to keep the voice ` +
+                    `natural; add a few words to the line if the gap is noticeable.`;
+        }
+        written.push(clip);
+    }
+    return { engine, voice, written, skipped, missing, warnings };
+}
+function registerGenerateNarration(server) {
+    server.registerTool("generate_narration", {
+        title: "Generate narration audio for every beat",
+        description: "Reads beats.json and writes one narration mp3 per beat to public/audio/vo/<beatId>.mp3, which is " +
+            "exactly where stitch_composition looks. Defaults to edge-tts; 'say' on macOS and 'espeak' also " +
+            "work. Each clip is fitted to its beat, but stretching is clamped to a range that stays natural: a " +
+            "pitch-preserving stretch past about ten percent is audible and is the main reason generated " +
+            "voiceover sounds synthetic. When a line genuinely does not fit, the tool says so and names the beat " +
+            "rather than stretching it into something processed, because the real fix is the script or the beat " +
+            "duration. Reports which beats got audio, which were skipped as already present, and which are still " +
+            "missing, so a partially generated narration cannot slip through and render silent. Resumable: pass " +
+            "overwrite to redo clips that already exist.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            engine: zod_1.z.enum(["edge-tts", "say", "espeak"]).optional(),
+            voice: zod_1.z.string().optional(),
+            padSeconds: zod_1.z.number().positive().optional(),
+            overwrite: zod_1.z.boolean().optional(),
+            beatIds: zod_1.z.array(zod_1.z.string()).optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("generate_narration", () => runGenerateNarration(input)));
+}

package/dist/tools/importHiggsfieldClip.d.ts

@@ -0,0 +1,41 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * `import_higgsfield_clip` does NOT call Higgsfield itself. See HIGGSFIELD.md and
+ * task-5-report.md for why: an MCP server has no clean, spec-supported way to reach into
+ * a *different*, already-authorized MCP connection the calling agent holds (Higgsfield's,
+ * in this case) -- there is no server-to-server tool-call primitive in the protocol, only
+ * sampling/elicitation/roots as server-to-client requests. The calling agent already has
+ * its own Higgsfield MCP connection and calls generate_video/jobs_wait on it directly;
+ * this tool's only job is taking whatever result that produced (a URL or a local file
+ * path) and landing it at this project's own asset-path convention.
+ */
+export type HiggsfieldClipSource = {
+    type: "url";
+    url: string;
+} | {
+    type: "path";
+    path: string;
+};
+export interface ImportHiggsfieldClipInput {
+    projectRoot?: string;
+    beatId: string;
+    source: HiggsfieldClipSource;
+    outPath?: string;
+}
+export interface ImportHiggsfieldClipResult {
+    outPath: string;
+    beatId: string;
+}
+/** Injectable so tests can supply a fake fetch instead of hitting a real network. */
+export interface ImportHiggsfieldClipDeps {
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetches or copies `input.source` into public/video/<beatId>.mp4 under projectRoot --
+ * the same convention capture_screen_recording and scaffold_scene's higgsfield-clip kind
+ * use, so a scaffolded higgsfield-clip scene's <OffthreadVideo src=...> finds the asset
+ * regardless of which tool produced it. Never reimplements video generation: the bytes
+ * are trusted as-is from whichever source the calling agent already produced.
+ */
+export declare function runImportHiggsfieldClip(input: ImportHiggsfieldClipInput, deps?: ImportHiggsfieldClipDeps): Promise<ImportHiggsfieldClipResult>;
+export declare function registerImportHiggsfieldClip(server: McpServer): void;

package/dist/tools/importHiggsfieldClip.js

@@ -0,0 +1,108 @@
+"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.runImportHiggsfieldClip = runImportHiggsfieldClip;
+exports.registerImportHiggsfieldClip = registerImportHiggsfieldClip;
+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");
+async function fetchToBuffer(url, fetchImpl) {
+    let response;
+    try {
+        response = await fetchImpl(url);
+    }
+    catch (err) {
+        throw new Error(`Failed to fetch source URL "${url}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!response.ok) {
+        throw new Error(`Source URL "${url}" returned ${response.status} ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+function readLocalFile(sourcePath) {
+    if (!fs.existsSync(sourcePath)) {
+        throw new Error(`Source path "${sourcePath}" does not exist.`);
+    }
+    if (!fs.statSync(sourcePath).isFile()) {
+        throw new Error(`Source path "${sourcePath}" is not a file.`);
+    }
+    return fs.readFileSync(sourcePath);
+}
+/**
+ * Fetches or copies `input.source` into public/video/<beatId>.mp4 under projectRoot --
+ * the same convention capture_screen_recording and scaffold_scene's higgsfield-clip kind
+ * use, so a scaffolded higgsfield-clip scene's <OffthreadVideo src=...> finds the asset
+ * regardless of which tool produced it. Never reimplements video generation: the bytes
+ * are trusted as-is from whichever source the calling agent already produced.
+ */
+async function runImportHiggsfieldClip(input, deps = {}) {
+    const beatId = (0, util_1.sanitizeSegment)(input.beatId, "beatId");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const outPathRel = input.outPath ?? path.join("public", "video", `${beatId}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const outPathAbs = path.join(projectRoot, outPathRel);
+    const buffer = input.source.type === "url"
+        ? await fetchToBuffer(input.source.url, deps.fetchImpl ?? fetch)
+        : readLocalFile(input.source.path);
+    fs.mkdirSync(path.dirname(outPathAbs), { recursive: true });
+    fs.writeFileSync(outPathAbs, buffer);
+    return { outPath: outPathAbs, beatId };
+}
+const sourceSchema = zod_1.z.union([
+    zod_1.z.object({ type: zod_1.z.literal("url"), url: zod_1.z.string().min(1) }),
+    zod_1.z.object({ type: zod_1.z.literal("path"), path: zod_1.z.string().min(1) }),
+]);
+function registerImportHiggsfieldClip(server) {
+    server.registerTool("import_higgsfield_clip", {
+        title: "Import an already-generated Higgsfield clip into this project's asset convention",
+        description: "Only registered when openvidstudio.config.json has hasHiggsfield: true. Does NOT call Higgsfield's " +
+            "generate_video/jobs_wait tools itself -- MCP servers have no server-to-server tool-call mechanism, " +
+            "so the calling agent must call those on its own already-authorized Higgsfield MCP connection first, " +
+            "then hand this tool the result. Accepts either a downloadable URL or a local file path, fetches/reads " +
+            "it, and writes the bytes to public/video/<beatId>.mp4 under projectRoot (default outPath override " +
+            "available for non-default layouts), matching capture_screen_recording's and scaffold_scene's " +
+            "higgsfield-clip convention exactly. Returns { outPath, beatId } on success; a structured error " +
+            "(never an uncaught throw) on a bad URL, a missing local file, or a failed download.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            beatId: zod_1.z.string().min(1),
+            source: sourceSchema,
+            outPath: zod_1.z.string().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("import_higgsfield_clip", () => runImportHiggsfieldClip(input)));
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OpenvidstudioConfig } from "../config";
+/**
+ * Registers all of this package's tools. All but one need no server-startup config: each
+ * resolves a project's own openvidstudio.config.json itself, per call, off projectRoot.
+ * import_higgsfield_clip is the one exception -- its registration itself is gated on
+ * config.hasHiggsfield, decided once at server-startup time (stdio.ts reads
+ * openvidstudio.config.json from process.cwd() before calling createMcpServer). Config is
+ * a static file read at startup here, not a live-toggleable runtime setting, so simply not
+ * calling registerImportHiggsfieldClip when the gate fails is sufficient: the tool is
+ * absent from the tool list entirely, not present-but-erroring.
+ */
+export declare function registerTools(server: McpServer, config?: OpenvidstudioConfig): void;

package/dist/tools/index.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTools = registerTools;
+const initProject_1 = require("./initProject");
+const validateBeats_1 = require("./validateBeats");
+const writeBeatsFile_1 = require("./writeBeatsFile");
+const scaffoldScene_1 = require("./scaffoldScene");
+const stitchComposition_1 = require("./stitchComposition");
+const renderVideo_1 = require("./renderVideo");
+const qcExtractFrames_1 = require("./qcExtractFrames");
+const captureScreenshot_1 = require("./captureScreenshot");
+const captureScreenRecording_1 = require("./captureScreenRecording");
+const importHiggsfieldClip_1 = require("./importHiggsfieldClip");
+const generateNarration_1 = require("./generateNarration");
+const preflight_1 = require("./preflight");
+const planBeats_1 = require("./planBeats");
+const validateScenes_1 = require("./validateScenes");
+const contactSheet_1 = require("./contactSheet");
+/**
+ * Registers all of this package's tools. All but one need no server-startup config: each
+ * resolves a project's own openvidstudio.config.json itself, per call, off projectRoot.
+ * import_higgsfield_clip is the one exception -- its registration itself is gated on
+ * config.hasHiggsfield, decided once at server-startup time (stdio.ts reads
+ * openvidstudio.config.json from process.cwd() before calling createMcpServer). Config is
+ * a static file read at startup here, not a live-toggleable runtime setting, so simply not
+ * calling registerImportHiggsfieldClip when the gate fails is sufficient: the tool is
+ * absent from the tool list entirely, not present-but-erroring.
+ */
+function registerTools(server, config) {
+    (0, initProject_1.registerInitProject)(server);
+    (0, validateBeats_1.registerValidateBeats)(server);
+    (0, writeBeatsFile_1.registerWriteBeatsFile)(server);
+    (0, scaffoldScene_1.registerScaffoldScene)(server);
+    (0, stitchComposition_1.registerStitchComposition)(server);
+    (0, renderVideo_1.registerRenderVideo)(server);
+    (0, qcExtractFrames_1.registerQcExtractFrames)(server);
+    (0, captureScreenshot_1.registerCaptureScreenshot)(server);
+    (0, captureScreenRecording_1.registerCaptureScreenRecording)(server);
+    (0, generateNarration_1.registerGenerateNarration)(server);
+    (0, preflight_1.registerPreflight)(server);
+    (0, planBeats_1.registerPlanBeats)(server);
+    (0, validateScenes_1.registerValidateScenes)(server);
+    (0, contactSheet_1.registerContactSheet)(server);
+    if (config?.hasHiggsfield === true) {
+        (0, importHiggsfieldClip_1.registerImportHiggsfieldClip)(server);
+    }
+}

package/dist/tools/initProject.d.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type OpenvidstudioConfig, type VideoConfig } from "../config";
+export interface InitProjectInput {
+    name: string;
+    projectRoot?: string;
+    targetDurationSeconds?: number;
+    hasHiggsfield?: boolean;
+    videoConfig?: Partial<VideoConfig>;
+    appUrl?: string;
+    demo?: boolean;
+}
+export interface InitProjectResult {
+    projectRoot: string;
+    videoDir: string;
+    configPath: string;
+    templateShellCopied: boolean;
+    docsDir: string;
+    config: OpenvidstudioConfig;
+    demo: boolean;
+    nextSteps: string[];
+}
+/**
+ * Scaffolds `src/videos/<name>/` in `projectRoot`, copying the bundled project shell
+ * (package.json, tsconfig, remotion.config.ts, Root.tsx, public/sfx/, the vendored
+ * openvidstudio-core/ -- everything in TEMPLATE_DIR) into the project root on first
+ * use, copying the bundled pipeline docs (PLANNING.md, PIPELINE.md, STYLE.md,
+ * CAPTURE.md, SCRIPT.md, OVERVIEW.md, HIGGSFIELD.md -- everything in DOCS_DIR) into
+ * `<projectRoot>/docs/`, then writing/merging openvidstudio.config.json.
+ *
+ * `TEMPLATE_DIR`/`DOCS_DIR` (src/paths.ts) resolve relative to this package's own
+ * compiled dist/ output, i.e. the copies bundled into packages/mcp-server/templates/
+ * and packages/mcp-server/docs/ at build time -- never a monorepo-relative path,
+ * which would not exist once this package is installed standalone in someone else's
+ * project (see task-3-report.md for how that's verified).
+ */
+export declare function runInitProject(input: InitProjectInput): InitProjectResult;
+export declare function registerInitProject(server: McpServer): void;

package/dist/tools/initProject.js

@@ -0,0 +1,166 @@
+"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.runInitProject = runInitProject;
+exports.registerInitProject = registerInitProject;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const paths_1 = require("../paths");
+const config_1 = require("../config");
+const util_1 = require("../util");
+const mcp_1 = require("./mcp");
+/**
+ * Scaffolds `src/videos/<name>/` in `projectRoot`, copying the bundled project shell
+ * (package.json, tsconfig, remotion.config.ts, Root.tsx, public/sfx/, the vendored
+ * openvidstudio-core/ -- everything in TEMPLATE_DIR) into the project root on first
+ * use, copying the bundled pipeline docs (PLANNING.md, PIPELINE.md, STYLE.md,
+ * CAPTURE.md, SCRIPT.md, OVERVIEW.md, HIGGSFIELD.md -- everything in DOCS_DIR) into
+ * `<projectRoot>/docs/`, then writing/merging openvidstudio.config.json.
+ *
+ * `TEMPLATE_DIR`/`DOCS_DIR` (src/paths.ts) resolve relative to this package's own
+ * compiled dist/ output, i.e. the copies bundled into packages/mcp-server/templates/
+ * and packages/mcp-server/docs/ at build time -- never a monorepo-relative path,
+ * which would not exist once this package is installed standalone in someone else's
+ * project (see task-3-report.md for how that's verified).
+ */
+function runInitProject(input) {
+    const name = (0, util_1.sanitizeSegment)(input.name, "name");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    fs.mkdirSync(projectRoot, { recursive: true });
+    // copyTemplateTree never overwrites a file that's already there, so this is safe to
+    // call again for a second video in an already-scaffolded project.
+    const alreadyScaffolded = fs.existsSync(path.join(projectRoot, "package.json"));
+    (0, util_1.copyTemplateTree)(paths_1.TEMPLATE_DIR, projectRoot);
+    const docsDir = path.join(projectRoot, "docs");
+    (0, util_1.copyTemplateTree)(paths_1.DOCS_DIR, docsDir);
+    const videoDir = path.join(projectRoot, "src", "videos", name);
+    fs.mkdirSync(path.join(videoDir, "scenes"), { recursive: true });
+    const config = (0, config_1.writeConfig)(projectRoot, {
+        hasHiggsfield: input.hasHiggsfield,
+        targetDurationSeconds: input.targetDurationSeconds,
+        videoConfig: input.videoConfig,
+        capture: input.appUrl ? { appUrl: input.appUrl } : undefined,
+    });
+    // A demo project ships a ready beats.json so the very next call can be
+    // scaffold_scene. Without it a new user has nothing to run and no worked example
+    // to copy, and any failure in ffmpeg or capture surfaces several steps later.
+    const nextSteps = [];
+    if (input.demo) {
+        const fps = config.videoConfig.fps;
+        const url = config.capture.appUrl;
+        const demoBeats = {
+            fps,
+            title: `${name} demo`,
+            beats: [
+                {
+                    id: "hook",
+                    start: 0,
+                    duration: fps * 6,
+                    visual: {
+                        captureMethod: "screenshot",
+                        url,
+                        interactions: [{ type: "wait", ms: config.capture.settleMs }],
+                        description: "The app's own first screen, camera pushing in.",
+                    },
+                    vo: "This is the app, captured from the real thing rather than described to a model.",
+                },
+                {
+                    id: "cta",
+                    start: fps * 6,
+                    duration: fps * 5,
+                    visual: { captureMethod: "dom-demo", description: "Repo call to action." },
+                    vo: "Built with openvidstudio, which turns a running app into a demo video.",
+                },
+            ],
+        };
+        fs.writeFileSync(path.join(videoDir, "beats.json"), JSON.stringify(demoBeats, null, 2) + "\n", "utf8");
+        nextSteps.push(`A two beat, 11 second beats.json is ready at src/videos/${name}/beats.json.`, `Next: capture_screenshot for the "hook" beat against ${url},`, `then scaffold_scene for both beats, then stitch_composition, then render_video with draft: true.`, `That whole path should take about two minutes and proves the install works end to end.`);
+    }
+    return {
+        projectRoot,
+        videoDir,
+        configPath: path.join(projectRoot, "openvidstudio.config.json"),
+        templateShellCopied: !alreadyScaffolded,
+        docsDir,
+        config,
+        demo: Boolean(input.demo),
+        nextSteps,
+    };
+}
+function registerInitProject(server) {
+    server.registerTool("init_project", {
+        title: "Initialize an openvidstudio project",
+        description: "Scaffolds a video's src/videos/<name>/ directory in the calling agent's current project " +
+            "(process.cwd() unless projectRoot is given). On first use also copies the bundled openvidstudio " +
+            "project shell (package.json, tsconfig.json, remotion.config.ts, src/Root.tsx, src/index.ts, " +
+            "public/sfx/, a vendored openvidstudio-core/ that the shell's package.json depends on via a " +
+            "relative file: reference) into the project root, copies the bundled pipeline docs (PLANNING.md, " +
+            "PIPELINE.md, STYLE.md, CAPTURE.md, SCRIPT.md, OVERVIEW.md, HIGGSFIELD.md) into <projectRoot>/docs/, " +
+            "and writes/merges openvidstudio.config.json there (merges field-by-field, never clobbers a value " +
+            "the patch doesn't mention). Never overwrites a file that already exists, so calling this again for " +
+            "a second video in the same project is safe. Pass demo: true to also write a ready two beat " +
+            "beats.json, so the next call can be capture_screenshot and a new user reaches a rendered video in " +
+            "about two minutes instead of authoring a beats file first. Only `name` is required; duration, fps, " +
+            "dimensions, capture viewport and the settle delay before a screenshot all have defaults that work.",
+        inputSchema: {
+            name: zod_1.z
+                .string()
+                .min(1)
+                .describe("Video name: letters, numbers, '-', or '_'. Used for src/videos/<name>/."),
+            projectRoot: zod_1.z
+                .string()
+                .optional()
+                .describe("Absolute path to the target project root. Defaults to process.cwd()."),
+            targetDurationSeconds: zod_1.z.number().positive().optional(),
+            hasHiggsfield: zod_1.z.boolean().optional(),
+            appUrl: zod_1.z
+                .string()
+                .optional()
+                .describe("The running app to film. Stored as capture.appUrl and used as the default for captures."),
+            demo: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Also write a ready two beat beats.json, as a two minute end to end smoke test."),
+            videoConfig: zod_1.z
+                .object({
+                fps: zod_1.z.number().positive().optional(),
+                width: zod_1.z.number().positive().optional(),
+                height: zod_1.z.number().positive().optional(),
+            })
+                .optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("init_project", () => runInitProject(input)));
+}

package/dist/tools/mcp.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export declare function json(value: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorText(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * 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.
+ */
+export declare function runTool<T>(toolName: string, fn: () => T | Promise<T>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;