@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/index.js

@@ -4,18 +4,46 @@ exports.registerTools = registerTools;
 const initProject_1 = require("./initProject");
 const validateBeats_1 = require("./validateBeats");
 const writeBeatsFile_1 = require("./writeBeatsFile");
+const writeBrief_1 = require("./writeBrief");
 const scaffoldScene_1 = require("./scaffoldScene");
 const stitchComposition_1 = require("./stitchComposition");
 const renderVideo_1 = require("./renderVideo");
+const jobStatus_1 = require("./jobStatus");
 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 planProduction_1 = require("./planProduction");
 const planBeats_1 = require("./planBeats");
 const validateScenes_1 = require("./validateScenes");
+const qcCapture_1 = require("./qcCapture");
 const contactSheet_1 = require("./contactSheet");
+const soundEffects_1 = require("./soundEffects");
+const extractBrand_1 = require("./extractBrand");
+const diffBeats_1 = require("./diffBeats");
+const captureDesktop_1 = require("./captureDesktop");
+const captureMobile_1 = require("./captureMobile");
+const captureTerminal_1 = require("./captureTerminal");
+const reformatVertical_1 = require("./reformatVertical");
+const exportRendition_1 = require("./exportRendition");
+const visualRegression_1 = require("./visualRegression");
+const docsDrift_1 = require("./docsDrift");
+const planShots_1 = require("./planShots");
+const releaseDiff_1 = require("./releaseDiff");
+const musicCues_1 = require("./musicCues");
+const musicLibrary_1 = require("./musicLibrary");
+const composeScore_1 = require("./composeScore");
+const motionPrimitives_1 = require("./motionPrimitives");
+const writeDescription_1 = require("./writeDescription");
+const renderStills_1 = require("./renderStills");
+const collectFacts_1 = require("./collectFacts");
+const finalizeVideo_1 = require("./finalizeVideo");
+const checkScript_1 = require("./checkScript");
+const fitBeats_1 = require("./fitBeats");
+const renderCanvasExplainer_1 = require("./renderCanvasExplainer");
+const validateCanvasExplainer_1 = require("./validateCanvasExplainer");
 /**
  * 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.
@@ -30,17 +58,46 @@ function registerTools(server, config) {
     (0, initProject_1.registerInitProject)(server);
     (0, validateBeats_1.registerValidateBeats)(server);
     (0, writeBeatsFile_1.registerWriteBeatsFile)(server);
+    (0, writeBrief_1.registerWriteBrief)(server);
     (0, scaffoldScene_1.registerScaffoldScene)(server);
     (0, stitchComposition_1.registerStitchComposition)(server);
     (0, renderVideo_1.registerRenderVideo)(server);
+    (0, jobStatus_1.registerJobStatus)(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, planProduction_1.registerPlanProduction)(server);
     (0, planBeats_1.registerPlanBeats)(server);
     (0, validateScenes_1.registerValidateScenes)(server);
+    (0, qcCapture_1.registerQcCapture)(server);
     (0, contactSheet_1.registerContactSheet)(server);
+    (0, soundEffects_1.registerSoundEffects)(server);
+    (0, extractBrand_1.registerExtractBrand)(server);
+    (0, diffBeats_1.registerDiffBeats)(server);
+    (0, captureDesktop_1.registerCaptureDesktop)(server);
+    (0, captureMobile_1.registerCaptureMobile)(server);
+    (0, captureTerminal_1.registerCaptureTerminal)(server);
+    (0, reformatVertical_1.registerReformatVertical)(server);
+    (0, exportRendition_1.registerExportRendition)(server);
+    (0, visualRegression_1.registerVisualRegression)(server);
+    (0, docsDrift_1.registerDocsDrift)(server);
+    (0, planShots_1.registerPlanShots)(server);
+    (0, releaseDiff_1.registerReleaseDiff)(server);
+    (0, musicCues_1.registerMusicCues)(server);
+    (0, musicLibrary_1.registerMusicLibrary)(server);
+    (0, composeScore_1.registerComposeScore)(server);
+    (0, motionPrimitives_1.registerCatalogMotionPrimitives)(server);
+    (0, motionPrimitives_1.registerAddMotionPrimitive)(server);
+    (0, writeDescription_1.registerWriteDescription)(server);
+    (0, renderStills_1.registerRenderStills)(server);
+    (0, collectFacts_1.registerCollectFacts)(server);
+    (0, finalizeVideo_1.registerFinalizeVideo)(server);
+    (0, checkScript_1.registerCheckScript)(server);
+    (0, fitBeats_1.registerFitBeats)(server);
+    (0, renderCanvasExplainer_1.registerRenderCanvasExplainer)(server);
+    (0, validateCanvasExplainer_1.registerValidateCanvasExplainer)(server);
     if (config?.hasHiggsfield === true) {
         (0, importHiggsfieldClip_1.registerImportHiggsfieldClip)(server);
     }

package/dist/tools/initProject.d.ts

@@ -1,5 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type OpenvidstudioConfig, type VideoConfig } from "../config";
+import { type OpenvidstudioConfig, type ProductionMode, type VideoConfig } from "../config";
 export interface InitProjectInput {
     name: string;
     projectRoot?: string;
@@ -8,6 +8,12 @@ export interface InitProjectInput {
     videoConfig?: Partial<VideoConfig>;
     appUrl?: string;
     demo?: boolean;
+    /**
+     * "standard" (the default) or "supernova", a STEM lesson. A supernova project also gets
+     * @openvidstudio/stem (vendored, with its display font), is stored as production.mode, and
+     * defaults to a 1080x1920 frame. A standard project's files and config do not change at all.
+     */
+    mode?: ProductionMode;
 }
 export interface InitProjectResult {
     projectRoot: string;
@@ -18,6 +24,11 @@ export interface InitProjectResult {
     config: OpenvidstudioConfig;
     demo: boolean;
     nextSteps: string[];
+    runtime: {
+        node: string;
+        pnpm: string | null;
+        warnings: string[];
+    };
 }
 /**
  * Scaffolds `src/videos/<name>/` in `projectRoot`, copying the bundled project shell

package/dist/tools/initProject.js

@@ -41,7 +41,46 @@ const zod_1 = require("zod");
 const paths_1 = require("../paths");
 const config_1 = require("../config");
 const util_1 = require("../util");
+const stitchComposition_1 = require("./stitchComposition");
 const mcp_1 = require("./mcp");
+const STEM_DIR = "openvidstudio-stem";
+const STEM_DEPENDENCY = "@openvidstudio/stem";
+/** output/ collects renders on the maintainer's machine; only its two tracked files belong in a new project. */
+const OUTPUT_FILES = new Set(["output/README.md", "output/.gitignore"]);
+function isStrayOutputFile(rel) {
+    return rel.startsWith("output/") && !OUTPUT_FILES.has(rel);
+}
+const SUPERNOVA_VIDEO_CONFIG = { fps: 30, width: 1080, height: 1920 };
+/** Adds or removes the stem dependency in the project's package.json, leaving the rest as it is. */
+function setStemDependency(projectRoot, present) {
+    const file = path.join(projectRoot, "package.json");
+    if (!fs.existsSync(file))
+        return;
+    const pkg = JSON.parse(fs.readFileSync(file, "utf8"));
+    const has = pkg.dependencies !== undefined && STEM_DEPENDENCY in pkg.dependencies;
+    if (present === has)
+        return;
+    pkg.dependencies = pkg.dependencies ?? {};
+    if (present)
+        pkg.dependencies[STEM_DEPENDENCY] = `file:./${STEM_DIR}`;
+    else
+        delete pkg.dependencies[STEM_DEPENDENCY];
+    fs.writeFileSync(file, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+}
+/**
+ * Makes @openvidstudio/stem importable from a supernova project: the vendored package, the
+ * dependency on it, its display font in public/fonts/ (where the project's local font loader looks)
+ * and the maths renderer's runtime in public/mathjax/. Safe on a project that already has any of them.
+ */
+function installStem(projectRoot) {
+    (0, util_1.copyTemplateTree)(path.join(paths_1.TEMPLATE_DIR, STEM_DIR), path.join(projectRoot, STEM_DIR));
+    setStemDependency(projectRoot, true);
+    const stemPublic = path.join(projectRoot, STEM_DIR, "public");
+    for (const dir of ["fonts", "mathjax"]) {
+        if (fs.existsSync(path.join(stemPublic, dir)))
+            (0, util_1.copyTemplateTree)(path.join(stemPublic, dir), path.join(projectRoot, "public", dir));
+    }
+}
 /**
  * Scaffolds `src/videos/<name>/` in `projectRoot`, copying the bundled project shell
  * (package.json, tsconfig, remotion.config.ts, Root.tsx, public/sfx/, the vendored
@@ -63,16 +102,45 @@ function runInitProject(input) {
     // 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 supernova = input.mode === "supernova";
+    const configExisted = fs.existsSync((0, config_1.configPath)(projectRoot));
+    // The vendored stem package is part of the bundled shell but belongs only to supernova projects.
+    (0, util_1.copyTemplateTree)(paths_1.TEMPLATE_DIR, projectRoot, (rel) => (!supernova && rel === STEM_DIR) || isStrayOutputFile(rel));
+    if (supernova)
+        installStem(projectRoot);
+    else if (!alreadyScaffolded)
+        setStemDependency(projectRoot, false);
     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 });
+    // Seeds preflight's render-benchmark composition into the registry (idempotent: a
+    // second init_project call, or one against an already-scaffolded project, just finds
+    // the entry already there and does nothing). This is what lets preflight time a real
+    // render before any real video has been planned or stitched -- Root.tsx otherwise stays
+    // `return null;` (the bare template) until the first stitch_composition call.
+    const registry = (0, stitchComposition_1.readRegistry)(projectRoot);
+    if (!registry.some((e) => e.videoName === stitchComposition_1.PREFLIGHT_BENCHMARK_VIDEO_NAME)) {
+        registry.push({
+            id: stitchComposition_1.PREFLIGHT_BENCHMARK_COMPOSITION_ID,
+            videoName: stitchComposition_1.PREFLIGHT_BENCHMARK_VIDEO_NAME,
+            componentName: "PreflightBenchmark",
+            importPath: "./PreflightBenchmark",
+            durationInFrames: 150,
+            fps: 30,
+            width: 1920,
+            height: 1080,
+        });
+        (0, stitchComposition_1.writeRegistry)(projectRoot, registry);
+        fs.writeFileSync(path.join(projectRoot, "src", "Root.tsx"), (0, stitchComposition_1.renderRootTsx)(registry, fs.existsSync(path.join(projectRoot, "src", "brand.ts"))), "utf8");
+    }
     const config = (0, config_1.writeConfig)(projectRoot, {
         hasHiggsfield: input.hasHiggsfield,
         targetDurationSeconds: input.targetDurationSeconds,
-        videoConfig: input.videoConfig,
+        // A lesson is a vertical video unless the caller (or an existing config) says otherwise.
+        videoConfig: input.videoConfig ?? (supernova && !configExisted ? { ...SUPERNOVA_VIDEO_CONFIG } : undefined),
         capture: input.appUrl ? { appUrl: input.appUrl } : undefined,
+        production: supernova ? { mode: "supernova" } : 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
@@ -118,6 +186,11 @@ function runInitProject(input) {
         config,
         demo: Boolean(input.demo),
         nextSteps,
+        runtime: {
+            node: process.version,
+            pnpm: process.env.npm_config_user_agent?.match(/pnpm\/(\S+)/)?.[1] ?? null,
+            warnings: Number.parseInt(process.versions.node, 10) < 20 ? ["Node 20 or newer is supported."] : [],
+        },
     };
 }
 function registerInitProject(server) {
@@ -154,6 +227,11 @@ function registerInitProject(server) {
                 .boolean()
                 .optional()
                 .describe("Also write a ready two beat beats.json, as a two minute end to end smoke test."),
+            mode: zod_1.z
+                .enum(["standard", "supernova"])
+                .optional()
+                .describe("\"standard\" (default) or \"supernova\", a STEM lesson: also installs @openvidstudio/stem and its " +
+                "display font, records production.mode, and defaults the frame to 1080x1920."),
             videoConfig: zod_1.z
                 .object({
                 fps: zod_1.z.number().positive().optional(),

package/dist/tools/jobStatus.d.ts

@@ -0,0 +1,14 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type JobRecord } from "../jobs";
+export interface JobStatusInput {
+    jobId: string;
+}
+/**
+ * Poll target for a job started with { async: true } on a tool that supports it
+ * (render_video today). Returns the job record as-is: status, progress (frames rendered,
+ * current beat, a log tail), and result once status is "done" or error once "error".
+ * Jobs live only in this server process's memory, so a job from before a server restart is
+ * simply gone -- the error message says so rather than pretending the jobId never existed.
+ */
+export declare function runJobStatus(input: JobStatusInput): JobRecord;
+export declare function registerJobStatus(server: McpServer): void;

package/dist/tools/jobStatus.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runJobStatus = runJobStatus;
+exports.registerJobStatus = registerJobStatus;
+const zod_1 = require("zod");
+const jobs_1 = require("../jobs");
+const mcp_1 = require("./mcp");
+/**
+ * Poll target for a job started with { async: true } on a tool that supports it
+ * (render_video today). Returns the job record as-is: status, progress (frames rendered,
+ * current beat, a log tail), and result once status is "done" or error once "error".
+ * Jobs live only in this server process's memory, so a job from before a server restart is
+ * simply gone -- the error message says so rather than pretending the jobId never existed.
+ */
+function runJobStatus(input) {
+    const job = (0, jobs_1.getJob)(input.jobId);
+    if (!job) {
+        throw new Error(`No job found for jobId "${input.jobId}". Jobs live only in this server process's memory for the ` +
+            `duration of the connection; if the server restarted since the job was started, it's gone.`);
+    }
+    return job;
+}
+function registerJobStatus(server) {
+    server.registerTool("job_status", {
+        title: "Poll an async job's progress and result",
+        description: "Poll target for a job started with { async: true } on a tool that supports it (render_video " +
+            "today). Returns { id, tool, status, startedAt, updatedAt, progress, result?, error? }: status is " +
+            "\"running\", \"done\", or \"error\"; progress carries framesRendered, totalFrames, currentBeat, " +
+            "and logTail (the most recent output lines); result appears once status is \"done\" and is exactly " +
+            "what the tool would have returned synchronously (e.g. a RenderVideoResult); error appears once " +
+            "status is \"error\". Jobs live only in this server process's memory for the connection's lifetime, " +
+            "so a jobId from before a restart is gone, not just stale.",
+        inputSchema: {
+            jobId: zod_1.z.string().min(1),
+        },
+    }, async ({ jobId }) => (0, mcp_1.runTool)("job_status", () => runJobStatus({ jobId })));
+}

package/dist/tools/mcp.d.ts

@@ -1,3 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /**
  * 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.
@@ -31,3 +32,11 @@ export declare function runTool<T>(toolName: string, fn: () => T | Promise<T>):
         text: string;
     }[];
 }>;
+/**
+ * The MCP SDK builds a zod object from a tool's input shape, and zod strips keys it does not know,
+ * so a call like render_video { quality: "draft" } (the option is `draft`) silently ran a full
+ * render. This makes every tool registered on `server` strict instead: an unknown key is an input
+ * error that names it, lists the valid keys, and suggests the closest one. Call it before the
+ * tools are registered.
+ */
+export declare function rejectUnknownInputs(server: McpServer): void;

package/dist/tools/mcp.js

@@ -1,12 +1,14 @@
 "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;
+exports.rejectUnknownInputs = rejectUnknownInputs;
+const zod_1 = require("zod");
+/**
+ * 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.
+ */
 function json(value) {
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
 }
@@ -34,3 +36,63 @@ async function runTool(toolName, fn) {
         return errorText(message);
     }
 }
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length];
+}
+function closestKey(unknown, valid) {
+    const squash = (k) => k.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const target = squash(unknown);
+    let best;
+    for (const key of valid) {
+        const distance = editDistance(target, squash(key));
+        if (distance <= 2 && (best === undefined || distance < best.distance))
+            best = { key, distance };
+    }
+    return best?.key;
+}
+function isRawShape(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !("_zod" in value) &&
+        Object.values(value).every((v) => typeof v === "object" && v !== null && "_zod" in v));
+}
+/**
+ * The MCP SDK builds a zod object from a tool's input shape, and zod strips keys it does not know,
+ * so a call like render_video { quality: "draft" } (the option is `draft`) silently ran a full
+ * render. This makes every tool registered on `server` strict instead: an unknown key is an input
+ * error that names it, lists the valid keys, and suggests the closest one. Call it before the
+ * tools are registered.
+ */
+function rejectUnknownInputs(server) {
+    const register = server.registerTool.bind(server);
+    server.registerTool = (name, config, cb) => {
+        const shape = config.inputSchema;
+        if (!isRawShape(shape))
+            return register(name, config, cb);
+        const valid = Object.keys(shape);
+        const strict = zod_1.z.strictObject(shape, {
+            error: (issue) => {
+                if (issue.code !== "unrecognized_keys")
+                    return undefined;
+                const unknown = issue.keys;
+                const hints = unknown.map((key) => {
+                    const near = closestKey(key, valid);
+                    return near ? ` (did you mean \`${near}\`?)` : "";
+                });
+                return (`Unknown input ${unknown.map((k, i) => `\`${k}\`${hints[i]}`).join(", ")} for ${name}, ` +
+                    `nothing was run. Valid inputs: ${valid.length > 0 ? valid.join(", ") : "(none)"}.`);
+            },
+        });
+        return register(name, { ...config, inputSchema: strict }, cb);
+    };
+}

package/dist/tools/motionPrimitives.d.ts

@@ -0,0 +1,46 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * A searchable catalog of small, tested motion primitives, and a way to drop one's real
+ * source into a project. See registry.ts for why this exists: scaffold_scene's 10
+ * templates are whole scenes, and below that level there was nothing reusable, so every
+ * count-up number or fanned card layout got hand-derived from motion.ts's tween/pop math
+ * again for every beat that wanted one.
+ */
+export interface CatalogMotionPrimitivesInput {
+    /** Free-text search over name/title/description/keywords. Omit to browse the whole catalog. */
+    query?: string;
+    limit?: number;
+}
+export interface CatalogedPrimitive {
+    name: string;
+    title: string;
+    description: string;
+    keywords: string[];
+    componentName: string;
+}
+export interface CatalogMotionPrimitivesResult {
+    query: string;
+    matchedQuery: boolean;
+    total: number;
+    primitives: CatalogedPrimitive[];
+}
+export declare function runCatalogMotionPrimitives(input: CatalogMotionPrimitivesInput): CatalogMotionPrimitivesResult;
+export declare function registerCatalogMotionPrimitives(server: McpServer): void;
+export interface AddMotionPrimitiveInput {
+    projectRoot?: string;
+    videoName: string;
+    /** The catalog entry's `name`, as returned by catalog_motion_primitives. */
+    name: string;
+    outPath?: string;
+    overwrite?: boolean;
+}
+export interface AddMotionPrimitiveResult {
+    written: true;
+    path: string;
+    name: string;
+    componentName: string;
+    /** A ready-to-paste relative import, for the scene that will use this primitive. */
+    importHint: string;
+}
+export declare function runAddMotionPrimitive(input: AddMotionPrimitiveInput): AddMotionPrimitiveResult;
+export declare function registerAddMotionPrimitive(server: McpServer): void;

package/dist/tools/motionPrimitives.js

@@ -0,0 +1,128 @@
+"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.runCatalogMotionPrimitives = runCatalogMotionPrimitives;
+exports.registerCatalogMotionPrimitives = registerCatalogMotionPrimitives;
+exports.runAddMotionPrimitive = runAddMotionPrimitive;
+exports.registerAddMotionPrimitive = registerAddMotionPrimitive;
+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");
+const registry_1 = require("../primitives/registry");
+function runCatalogMotionPrimitives(input) {
+    const limit = input.limit && input.limit > 0 ? input.limit : 10;
+    const matches = (0, registry_1.searchMotionPrimitives)(input.query, limit);
+    return {
+        query: input.query ?? "",
+        matchedQuery: Boolean(input.query) && matches.length > 0,
+        total: registry_1.MOTION_PRIMITIVES.length,
+        primitives: matches.map(({ primitive }) => ({
+            name: primitive.name,
+            title: primitive.title,
+            description: primitive.description,
+            keywords: primitive.keywords,
+            componentName: primitive.componentName,
+        })),
+    };
+}
+function registerCatalogMotionPrimitives(server) {
+    server.registerTool("catalog_motion_primitives", {
+        title: "Search the motion primitives catalog",
+        description: "Searches a small, bundled catalog of reusable motion primitives (a count-up stat card, a fanned " +
+            "card stack, a logo outro, a typewriter line, a beat-timeline strip) by free-text query over each " +
+            "primitive's name/title/description/keywords. No query returns the whole catalog, for browsing. " +
+            "Local and bundled: no network call, no hosted registry, no account. Returns { query, matchedQuery, " +
+            "total, primitives: [{ name, title, description, keywords, componentName }] } ranked best match " +
+            "first. Pass a primitive's `name` to add_motion_primitive to write its real source into the project.",
+        inputSchema: {
+            query: zod_1.z.string().optional(),
+            limit: zod_1.z.number().int().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("catalog_motion_primitives", () => runCatalogMotionPrimitives(input)));
+}
+function runAddMotionPrimitive(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const primitive = (0, registry_1.findMotionPrimitive)(input.name);
+    if (!primitive) {
+        const known = registry_1.MOTION_PRIMITIVES.map((p) => p.name).join(", ");
+        throw new Error(`No motion primitive named "${input.name}". Known primitives: ${known}.`);
+    }
+    const primitivesDir = path.join(projectRoot, "src", "videos", videoName, "primitives");
+    if (input.outPath)
+        (0, util_1.sanitizeRelativeOutPath)(projectRoot, input.outPath, "outPath");
+    const filePath = input.outPath
+        ? path.join(projectRoot, input.outPath)
+        : path.join(primitivesDir, `${primitive.componentName}.tsx`);
+    if (fs.existsSync(filePath) && !input.overwrite) {
+        throw new Error(`${filePath} already exists. Pass overwrite: true to replace a copy the calling agent or dev has ` +
+            `already started editing.`);
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, primitive.source, "utf8");
+    const importRel = path
+        .relative(path.join(projectRoot, "src", "videos", videoName, "scenes"), filePath)
+        .replace(/\\/g, "/")
+        .replace(/\.tsx$/, "");
+    return {
+        written: true,
+        path: filePath,
+        name: primitive.name,
+        componentName: primitive.componentName,
+        importHint: `import { ${primitive.componentName} } from "${importRel.startsWith(".") ? importRel : `./${importRel}`}";`,
+    };
+}
+function registerAddMotionPrimitive(server) {
+    server.registerTool("add_motion_primitive", {
+        title: "Copy a catalog motion primitive's source into the project",
+        description: "Writes the named catalog entry's real .tsx source (found via catalog_motion_primitives) to " +
+            "src/videos/<videoName>/primitives/<ComponentName>.tsx by default, so it can be imported into a " +
+            "scaffolded or hand-written scene and used as-is or edited freely -- it is your copy, not a live " +
+            "reference back to the catalog. Every primitive uses only \"react\", \"remotion\" and " +
+            "\"@openvidstudio/core\", the same constraint scaffold_scene's own templates follow, so it drops in " +
+            "with no extra dependency. Refuses to overwrite an existing file unless overwrite: true. Returns " +
+            "{ written, path, name, componentName, importHint } -- importHint is a ready-to-paste relative " +
+            "import for a scene living in the video's scenes/ directory.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            name: zod_1.z.string().min(1).describe("The catalog entry's name, e.g. \"count-up-stat\" (see catalog_motion_primitives)."),
+            outPath: zod_1.z.string().optional().describe("Override the default src/videos/<videoName>/primitives/<ComponentName>.tsx path."),
+            overwrite: zod_1.z.boolean().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("add_motion_primitive", () => runAddMotionPrimitive(input)));
+}

package/dist/tools/musicCues.d.ts

@@ -0,0 +1,43 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Beat and strong-cue timestamps for a music track, so a video's scene cuts can land on
+ * the music instead of at an arbitrary second. See STYLE.md's "Beat-locked cuts" section
+ * for the snap tolerances this is meant to feed: major reveals within ~0.15s of a
+ * strongCue, sequential reveals within ~0.10s of a beat.
+ *
+ * Two paths, chosen by whether the track already carries a cue file:
+ *
+ * 1. A track from compose_score has a <stem>.cues.json written next to it at the moment it
+ *    was synthesized, with source "generated". Since the track is generated, not recorded,
+ *    its beat grid is exact by construction: this path is a file read, not an analysis.
+ *
+ * 2. Any other track -- an imported one, or a hand-made music bed -- has no such file, so
+ *    this decodes it and estimates a beat grid: RMS energy envelope, peak-picked
+ *    onsets as strongCues, and a BPM estimate from autocorrelating the onset envelope to
+ *    build an evenly-spaced beats[] grid. This is a real but simple detector (energy-based
+ *    onset picking plus one autocorrelation pass), not the equivalent of a dedicated music
+ *    information retrieval library: treat the result as planning guidance, the same
+ *    "optional timing hint, ignore it where it hurts readability" posture the STYLE.md
+ *    section already asks for, not as ground truth.
+ *
+ * The result is cached next to the track as <stem>.cues.json (the same shape compose_score
+ * writes), so a second call against the same file is a read, not a re-analysis.
+ */
+export interface MusicCuesInput {
+    projectRoot?: string;
+    /** Path to the audio file, relative to projectRoot. e.g. "public/audio/music-bed.mp3". */
+    track: string;
+    /** Re-run analysis even if a cues file is already cached next to the track. */
+    force?: boolean;
+}
+export interface MusicCuesResult {
+    track: string;
+    bpm: number;
+    durationSeconds: number;
+    beats: number[];
+    strongCues: number[];
+    source: "generated" | "analyzed" | "cached";
+    cuesPath: string;
+}
+export declare function runMusicCues(input: MusicCuesInput): Promise<MusicCuesResult>;
+export declare function registerMusicCues(server: McpServer): void;