@openvidstudio/mcp-server 0.1.0 → 1.3.1

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;

package/dist/tools/musicCues.js

@@ -0,0 +1,252 @@
+"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.runMusicCues = runMusicCues;
+exports.registerMusicCues = registerMusicCues;
+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 SAMPLE_RATE = 22050;
+function cuesPathFor(trackAbs) {
+    const dir = path.dirname(trackAbs);
+    const stem = path.basename(trackAbs).replace(/\.[^.]+$/, "");
+    return path.join(dir, `${stem}.cues.json`);
+}
+/**
+ * Decodes to a temp raw-PCM file rather than piping through stdout: spawnCapture buffers
+ * stdout as a JS string (`chunk.toString()`), which is the right contract for every other
+ * caller (ffmpeg/ffprobe text output) but would corrupt raw s16le sample bytes. Writing to
+ * disk and reading the file back with fs (binary-safe) sidesteps that without changing a
+ * shared primitive several other tools depend on.
+ */
+async function decodeMonoPcm16(trackAbs, projectRoot) {
+    const tmpPath = path.join(path.dirname(trackAbs), `.${path.basename(trackAbs)}.${process.pid}.analyze.raw`);
+    try {
+        const res = await (0, util_1.spawnCapture)("ffmpeg", ["-v", "error", "-y", "-i", trackAbs, "-ac", "1", "-ar", String(SAMPLE_RATE), "-f", "s16le", tmpPath], projectRoot);
+        if (res.code !== 0) {
+            throw new Error(`ffmpeg could not decode "${trackAbs}" for analysis:\n${res.stderr.slice(-800)}`);
+        }
+        const buf = fs.readFileSync(tmpPath);
+        if (buf.length < SAMPLE_RATE) {
+            throw new Error(`"${trackAbs}" decoded to less than one second of audio. Is the file real audio?`);
+        }
+        // Copy out of the file-backed buffer before the temp file is removed underneath it.
+        const copy = Buffer.from(buf);
+        return new Int16Array(copy.buffer, copy.byteOffset, Math.floor(copy.length / 2));
+    }
+    finally {
+        fs.rmSync(tmpPath, { force: true });
+    }
+}
+/** Short-window RMS envelope. Hop and window chosen for ~10-15ms resolution at 22050hz. */
+function rmsEnvelope(samples) {
+    const windowSize = 512;
+    const hopSize = 256;
+    const frames = Math.max(0, Math.floor((samples.length - windowSize) / hopSize) + 1);
+    const values = new Float64Array(frames);
+    for (let f = 0; f < frames; f++) {
+        const start = f * hopSize;
+        let sum = 0;
+        for (let i = 0; i < windowSize; i++) {
+            const s = samples[start + i] / 32768;
+            sum += s * s;
+        }
+        values[f] = Math.sqrt(sum / windowSize);
+    }
+    return { hopSeconds: hopSize / SAMPLE_RATE, values };
+}
+/** Positive first difference of the envelope: energy rising, not just energy present. */
+function onsetFlux(env) {
+    const flux = new Float64Array(env.length);
+    for (let i = 1; i < env.length; i++)
+        flux[i] = Math.max(0, env[i] - env[i - 1]);
+    return flux;
+}
+function mean(xs) {
+    let s = 0;
+    for (const x of xs)
+        s += x;
+    return xs.length ? s / xs.length : 0;
+}
+function stddev(xs, m) {
+    let s = 0;
+    for (const x of xs)
+        s += (x - m) * (x - m);
+    return xs.length ? Math.sqrt(s / xs.length) : 0;
+}
+/** Local maxima above threshold, with a refractory gap so one transient isn't double-picked. */
+function pickPeaks(flux, hopSeconds, minGapSeconds) {
+    const m = mean(flux);
+    const sd = stddev(flux, m);
+    const threshold = m + 1.3 * sd;
+    const minGapFrames = Math.max(1, Math.round(minGapSeconds / hopSeconds));
+    const peaks = [];
+    let lastPeak = -Infinity;
+    for (let i = 1; i < flux.length - 1; i++) {
+        if (flux[i] < threshold)
+            continue;
+        if (flux[i] < flux[i - 1] || flux[i] < flux[i + 1])
+            continue;
+        if (i - lastPeak < minGapFrames) {
+            if (peaks.length > 0 && flux[i] > peaks[peaks.length - 1].strength) {
+                peaks[peaks.length - 1] = { index: i, strength: flux[i] };
+                lastPeak = i;
+            }
+            continue;
+        }
+        peaks.push({ index: i, strength: flux[i] });
+        lastPeak = i;
+    }
+    return peaks;
+}
+/**
+ * Autocorrelate the onset envelope over a plausible tempo range to estimate BPM, then
+ * build an evenly-spaced beat grid at that tempo anchored to the first strong peak.
+ */
+function estimateTempoAndGrid(flux, hopSeconds, peaks, durationSeconds) {
+    const minBpm = 70;
+    const maxBpm = 180;
+    const minLag = Math.round(60 / maxBpm / hopSeconds);
+    const maxLag = Math.round(60 / minBpm / hopSeconds);
+    let bestLag = minLag;
+    let bestScore = -Infinity;
+    for (let lag = minLag; lag <= Math.min(maxLag, flux.length - 1); lag++) {
+        let score = 0;
+        for (let i = 0; i + lag < flux.length; i++)
+            score += flux[i] * flux[i + lag];
+        if (score > bestScore) {
+            bestScore = score;
+            bestLag = lag;
+        }
+    }
+    const beatSeconds = bestLag * hopSeconds;
+    const bpm = Math.round((60 / beatSeconds) * 10) / 10;
+    const anchor = peaks.length > 0 ? peaks[0].index * hopSeconds : 0;
+    const beats = [];
+    // Walk backward from the anchor to cover the track from t=0, then forward to the end.
+    let t = anchor;
+    while (t > 0)
+        t -= beatSeconds;
+    for (; t <= durationSeconds; t += beatSeconds) {
+        if (t >= 0)
+            beats.push(Number(t.toFixed(3)));
+    }
+    return { bpm, beats };
+}
+async function runMusicCues(input) {
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, input.track, "track");
+    const trackAbs = path.join(projectRoot, input.track);
+    if (!fs.existsSync(trackAbs)) {
+        throw new Error(`"${input.track}" does not exist under ${projectRoot}.`);
+    }
+    const cuesAbs = cuesPathFor(trackAbs);
+    const existing = fs.existsSync(cuesAbs)
+        ? JSON.parse(fs.readFileSync(cuesAbs, "utf8"))
+        : null;
+    // A "generated" cues file (written at synth time by compose_score) is exact by
+    // construction. force is for re-running the
+    // estimator against a track that was itself only ever estimated; it must never let a
+    // noisier re-analysis silently replace ground truth.
+    if (existing?.source === "generated") {
+        if (input.force) {
+            throw new Error(`${cuesAbs} is a generated cue file (exact by construction), not an estimated one. ` +
+                `force is for re-analyzing a track whose cues were themselves only ever estimated; ` +
+                `it refuses to overwrite generated ground truth.`);
+        }
+        return {
+            ...existing,
+            source: "cached",
+            cuesPath: path.relative(projectRoot, cuesAbs).replace(/\\/g, "/"),
+        };
+    }
+    if (!input.force && existing) {
+        return {
+            ...existing,
+            source: "cached",
+            cuesPath: path.relative(projectRoot, cuesAbs).replace(/\\/g, "/"),
+        };
+    }
+    const samples = await decodeMonoPcm16(trackAbs, projectRoot);
+    const durationSeconds = samples.length / SAMPLE_RATE;
+    const { hopSeconds, values: env } = rmsEnvelope(samples);
+    const flux = onsetFlux(env);
+    const peaks = pickPeaks(flux, hopSeconds, 0.15);
+    const { bpm, beats } = estimateTempoAndGrid(flux, hopSeconds, peaks, durationSeconds);
+    // strongCues: the loudest quarter of picked onsets, sorted back into time order. This is
+    // deliberately sparser than beats[], matching compose_score's strongCues-are-bar-downbeats
+    // shape: a handful of moments worth cutting on, not every detected transient.
+    const sortedByStrength = [...peaks].sort((a, b) => b.strength - a.strength);
+    const strongCount = Math.max(1, Math.round(peaks.length * 0.25));
+    const strongCues = sortedByStrength
+        .slice(0, strongCount)
+        .map((p) => Number((p.index * hopSeconds).toFixed(3)))
+        .sort((a, b) => a - b);
+    const result = {
+        track: input.track.replace(/\\/g, "/"),
+        bpm,
+        durationSeconds: Number(durationSeconds.toFixed(3)),
+        beats,
+        strongCues,
+        source: "analyzed",
+    };
+    fs.writeFileSync(cuesAbs, JSON.stringify(result, null, 2) + "\n", "utf8");
+    return { ...result, cuesPath: path.relative(projectRoot, cuesAbs).replace(/\\/g, "/") };
+}
+function registerMusicCues(server) {
+    server.registerTool("plan_music_cues", {
+        title: "Detect or read beat and strong-cue timestamps for a music track",
+        description: "Returns beats (the full beat grid) and strongCues (bar downbeats or the loudest onsets, a sparser " +
+            "set) for a music track, in seconds, so scene cuts can be beat-locked instead of landing at an " +
+            "arbitrary second. For a track compose_score wrote, this is a file read of the exact cue grid " +
+            "computed when the track was synthesized. For any other track it decodes the audio and estimates " +
+            "a grid from an RMS onset " +
+            "envelope and one autocorrelation pass: a real but simple detector, good enough to plan cuts against, " +
+            "not a substitute for listening to the track. Results are cached next to the track as " +
+            "<stem>.cues.json, so call again with force to re-analyze. force refuses to run against a generated " +
+            "cues file (compose_score's own): that grid is exact by construction, so force exists to redo an " +
+            "estimate, never to overwrite ground truth with a noisier one. See STYLE.md's \"Beat-locked cuts\" " +
+            "section for how to use the result: snap at most a handful of major reveals to strongCues within " +
+            "about 0.15s, snap sequential reveals (cards, stats arriving one by one) to consecutive beats within " +
+            "about 0.10s, and ignore a cue outright when honoring it would hurt readability or pacing.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            track: zod_1.z.string().min(1).describe('Path relative to projectRoot, e.g. "public/audio/music-bed.mp3".'),
+            force: zod_1.z.boolean().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("plan_music_cues", () => runMusicCues(input)));
+}