@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/tools/visualRegression.d.ts

@@ -0,0 +1,72 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * A video diff of your own UI.
+ *
+ * Half of this already existed: qc_extract_frames pulls frames and contact_sheet lays them
+ * out. What was missing was the comparison, the threshold, and something to report. Without
+ * those, a render on every merge tells you only that the render still works, which is the
+ * least interesting thing it could tell you.
+ *
+ * With them, a merge that changes what the product looks like says so, with the beat named
+ * and a diff image showing where. That is the thing nothing else does well: plenty of tools
+ * diff a screenshot, almost nothing diffs the moving picture of a product against the last
+ * one that shipped.
+ *
+ * The first run has no baseline, so it writes one and says that is what it did. A tool that
+ * fails its first run because nothing to compare against exists yet gets turned off.
+ */
+export interface VisualRegressionInput {
+    projectRoot?: string;
+    videoName: string;
+    videoPath?: string;
+    baselineDir?: string;
+    outDir?: string;
+    /** Fraction of pixels allowed to move before a beat counts as changed. Defaults to 0.02. */
+    changedRatioThreshold?: number;
+    meanDeltaThreshold?: number;
+    /** Accept the current render as the new baseline. */
+    updateBaseline?: boolean;
+    /**
+     * Gate on ANY pixel difference instead of the tolerance thresholds above: pixelThreshold
+     * 0 (any per-channel move counts), changedRatio/meanDelta limits of 0, and the comparison
+     * run at the baseline's own resolution rather than downscaled. Only meaningful
+     * once the beats being diffed were captured with `deterministic: true` (and, for a video
+     * beat, an encoder that is itself pixel-deterministic run to run) -- against an ordinary
+     * capture this will flag encoder noise and antialiasing jitter on every run, which is
+     * exactly the false-positive rate the tolerance thresholds exist to avoid. Ignores
+     * changedRatioThreshold/meanDeltaThreshold when set.
+     */
+    exact?: boolean;
+}
+export interface BeatRegression {
+    beatId: string;
+    status: "unchanged" | "changed" | "new";
+    reason: string;
+    changedRatio: number;
+    meanDelta: number;
+    currentFrame: string;
+    baselineFrame?: string;
+    diffFrame?: string;
+}
+export interface VisualRegressionResult {
+    ok: boolean;
+    baselineCreated: boolean;
+    baselineUpdated: boolean;
+    beats: BeatRegression[];
+    changedBeats: string[];
+    /** Ready to post as a PR comment. */
+    markdown: string;
+}
+/**
+ * The PR comment.
+ *
+ * Written to be readable when nothing changed, which is most of the time: a check that
+ * dumps a table of zeroes onto every pull request trains people to collapse it.
+ */
+export declare function buildRegressionMarkdown(result: {
+    videoName: string;
+    beats: BeatRegression[];
+    baselineCreated: boolean;
+}): string;
+export declare function runVisualRegression(input: VisualRegressionInput): Promise<VisualRegressionResult>;
+export declare function registerVisualRegression(server: McpServer): void;

package/dist/tools/visualRegression.js

@@ -0,0 +1,192 @@
+"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.buildRegressionMarkdown = buildRegressionMarkdown;
+exports.runVisualRegression = runVisualRegression;
+exports.registerVisualRegression = registerVisualRegression;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const frameDiff_1 = require("../frameDiff");
+const exportRendition_1 = require("./exportRendition");
+const mcp_1 = require("./mcp");
+/**
+ * The PR comment.
+ *
+ * Written to be readable when nothing changed, which is most of the time: a check that
+ * dumps a table of zeroes onto every pull request trains people to collapse it.
+ */
+function buildRegressionMarkdown(result) {
+    if (result.baselineCreated) {
+        return (`**Visual baseline created for \`${result.videoName}\`** (${result.beats.length} beats).\n\n` +
+            `There was nothing to compare against yet. The next run diffs against this render.`);
+    }
+    const changed = result.beats.filter((b) => b.status !== "unchanged");
+    if (changed.length === 0) {
+        return `**No visual change in \`${result.videoName}\`** across ${result.beats.length} beats.`;
+    }
+    const rows = changed
+        .map((b) => `| \`${b.beatId}\` | ${b.status} | ${(b.changedRatio * 100).toFixed(2)}% | ` +
+        `${(b.meanDelta * 100).toFixed(2)}% | ${b.reason} |`)
+        .join("\n");
+    return (`**${changed.length} of ${result.beats.length} beats changed visually in \`${result.videoName}\`.**\n\n` +
+        `| beat | status | pixels moved | mean delta | why |\n| --- | --- | --- | --- | --- |\n${rows}\n\n` +
+        `Diff images are in the run's artifacts. If the change is intended, re-run with ` +
+        `\`updateBaseline\` to accept it.`);
+}
+async function runVisualRegression(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const beatsPath = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsPath))
+        throw new Error(`${beatsPath} does not exist.`);
+    const doc = JSON.parse(fs.readFileSync(beatsPath, "utf8"));
+    const beats = doc.beats;
+    if (!Array.isArray(beats) || beats.length === 0)
+        throw new Error(`${beatsPath} has no beats.`);
+    const fps = doc.fps ?? 30;
+    const videoRel = input.videoPath ?? path.join("output", `${videoName}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, videoRel, "videoPath");
+    if (!fs.existsSync(path.join(projectRoot, videoRel))) {
+        throw new Error(`${videoRel} does not exist. Render the video before diffing it.`);
+    }
+    const baselineRel = input.baselineDir ?? path.join("output", "visual-baseline", videoName);
+    const outRel = input.outDir ?? path.join("output", "visual-diff", videoName);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, baselineRel, "baselineDir");
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outRel, "outDir");
+    const baselineAbs = path.join(projectRoot, baselineRel);
+    const outAbs = path.join(projectRoot, outRel);
+    fs.mkdirSync(baselineAbs, { recursive: true });
+    fs.mkdirSync(outAbs, { recursive: true });
+    // Extract this render's frames first, whatever happens next: they become either the
+    // comparison set or the new baseline.
+    const current = [];
+    for (const beat of beats) {
+        const rel = path.join(outRel, `${beat.id}.png`);
+        const shot = await (0, util_1.spawnCapture)("ffmpeg", (0, exportRendition_1.buildFrameArgs)(videoRel, (0, exportRendition_1.beatMidpointSeconds)(beat, fps), rel), projectRoot);
+        if (shot.code !== 0)
+            throw new Error(`frame extraction failed for "${beat.id}":\n${shot.stderr.slice(-800)}`);
+        current.push({ beat, rel });
+    }
+    const baselineExists = beats.some((b) => fs.existsSync(path.join(baselineAbs, `${b.id}.png`)));
+    const acceptAll = input.updateBaseline === true || !baselineExists;
+    const results = [];
+    for (const { beat, rel } of current) {
+        const baselineFileRel = path.join(baselineRel, `${beat.id}.png`);
+        const baselineFileAbs = path.join(projectRoot, baselineFileRel);
+        if (!fs.existsSync(baselineFileAbs)) {
+            fs.copyFileSync(path.join(projectRoot, rel), baselineFileAbs);
+            results.push({
+                beatId: beat.id,
+                status: baselineExists ? "new" : "unchanged",
+                reason: baselineExists ? "this beat has no baseline yet, so one was written" : "baseline written",
+                changedRatio: 0,
+                meanDelta: 0,
+                currentFrame: rel,
+                baselineFrame: baselineFileRel,
+            });
+            continue;
+        }
+        const diffRel = path.join(outRel, `${beat.id}.diff.png`);
+        // exact compares at the baseline's own resolution. compareFrames otherwise resamples
+        // both frames to DEFAULT_COMPARE_WIDTH first, which is what keeps an ordinary diff
+        // stable, and is also what would let a single changed pixel average away entirely: a
+        // gate that claims to catch ANY difference cannot be looking at a 640px thumbnail of
+        // a 2560px render.
+        const comparison = await (0, frameDiff_1.compareFrames)(baselineFileAbs, path.join(projectRoot, rel), {
+            diffPath: path.join(projectRoot, diffRel),
+            ...(input.exact ? { pixelThreshold: 0, compareWidth: await (0, frameDiff_1.imageWidth)(baselineFileAbs) } : {}),
+        });
+        const verdict = (0, frameDiff_1.judgeDrift)(comparison, input.exact
+            ? { changedRatio: 0, meanDelta: 0 }
+            : { changedRatio: input.changedRatioThreshold, meanDelta: input.meanDeltaThreshold });
+        results.push({
+            beatId: beat.id,
+            status: verdict.drifted ? "changed" : "unchanged",
+            reason: verdict.reason,
+            changedRatio: comparison.changedRatio,
+            meanDelta: comparison.meanDelta,
+            currentFrame: rel,
+            baselineFrame: baselineFileRel,
+            diffFrame: diffRel,
+        });
+        if (input.updateBaseline === true) {
+            fs.copyFileSync(path.join(projectRoot, rel), baselineFileAbs);
+        }
+    }
+    const changedBeats = results.filter((r) => r.status === "changed").map((r) => r.beatId);
+    const baselineCreated = !baselineExists;
+    return {
+        ok: changedBeats.length === 0,
+        baselineCreated,
+        baselineUpdated: acceptAll && !baselineCreated,
+        beats: results,
+        changedBeats,
+        markdown: buildRegressionMarkdown({ videoName, beats: results, baselineCreated }),
+    };
+}
+function registerVisualRegression(server) {
+    server.registerTool("visual_regression", {
+        title: "Diff this render's beats against the last accepted one",
+        description: "Extracts the midpoint frame of every beat from a finished render and compares it against a stored " +
+            "baseline, so a merge that changes what the product looks like says so, with the beat named and a " +
+            "diff image showing where. Two numbers, because they catch different changes: the fraction of pixels " +
+            "that moved past a per-pixel threshold catches a local repaint (one button, one line of text) that " +
+            "barely moves the average, and the mean delta catches a global shift (a palette change) that barely " +
+            "moves the pixel count. Frames are downscaled before comparison, which is what makes the result " +
+            "stable rather than flagging encoder noise and subpixel antialiasing on every run. The first run has " +
+            "no baseline, so it writes one and says so instead of failing. Returns a per-beat verdict plus " +
+            "markdown ready to post as a PR comment. Pass updateBaseline to accept the current render. Pass " +
+            "exact to gate on ANY pixel difference (pixelThreshold/changedRatio/meanDelta all 0) instead of the " +
+            "tolerance thresholds -- only meaningful against beats captured with deterministic: true, since " +
+            "otherwise ordinary encoder noise and antialiasing jitter will flag on every run.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            videoPath: zod_1.z.string().optional(),
+            baselineDir: zod_1.z.string().optional(),
+            outDir: zod_1.z.string().optional(),
+            changedRatioThreshold: zod_1.z.number().positive().optional(),
+            meanDeltaThreshold: zod_1.z.number().positive().optional(),
+            updateBaseline: zod_1.z.boolean().optional(),
+            exact: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Gate on ANY pixel difference instead of the tolerance thresholds. Only meaningful against beats " +
+                "captured with deterministic: true -- otherwise encoder noise alone will flag every run."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("visual_regression", () => runVisualRegression(input)));
+}

package/dist/tools/writeBeatsFile.d.ts

@@ -8,6 +8,7 @@ export interface WriteBeatsFileInput {
 export type WriteBeatsFileResult = {
     written: true;
     path: string;
+    warnings: string[];
 } | ValidateBeatsResult;
 /**
  * Runs validate_beats' own logic directly (no MCP round-trip) and refuses to write

package/dist/tools/writeBeatsFile.js

@@ -59,7 +59,7 @@ function runWriteBeatsFile(input) {
     fs.mkdirSync(videoDir, { recursive: true });
     const filePath = path.join(videoDir, "beats.json");
     fs.writeFileSync(filePath, JSON.stringify(input.beatsJson, null, 2) + "\n", "utf8");
-    return { written: true, path: filePath };
+    return { written: true, path: filePath, warnings: validation.warnings };
 }
 function registerWriteBeatsFile(server) {
     server.registerTool("write_beats_file", {
@@ -67,7 +67,9 @@ function registerWriteBeatsFile(server) {
         description: "Runs validate_beats' own validation logic internally first (a direct function call, not an MCP " +
             "round-trip) and refuses to write anything invalid, returning the same { valid: false, errors } " +
             "shape instead. On success writes src/videos/<videoName>/beats.json (pretty-printed, 2-space indent) " +
-            "and returns { written: true, path }. IMPORTANT: this tool only enforces schema validity. It does " +
+            "and returns { written: true, path, warnings }: a successful write can still carry warnings (for example " +
+            "that the shot lengths are nearly uniform), which never block the write but are worth acting on. " +
+            "IMPORTANT: this tool only enforces schema validity. It does " +
             "NOT enforce PLANNING.md's mandatory human-approval gate -- the calling agent must show the dev the " +
             "full drafted beats.json (not a summary) and get explicit approval before ever calling this tool, " +
             "even for a small, obviously-fine-looking draft. Passing this tool's validation is necessary but " +

package/dist/tools/writeBrief.d.ts

@@ -0,0 +1,155 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * brief.json's shape (C1). Written alongside brief.md (free-form prose, not validated here)
+ * by write_brief, before any beat gets written -- see PLANNING.md's new section documenting
+ * when/how this gets authored. Every string field is checked for em dashes, same writing
+ * rule as beats.json (validateBeats.ts), since a brief is a real written artifact too, not
+ * just internal scratch.
+ */
+export interface StoryDevice {
+    /** A ticking clock, a before/after, a character's day, a mystery reveal, a build-up
+     * montage, a "made with itself" twist, or something else entirely -- freeform on purpose,
+     * the point is picking one deliberately, not choosing from a closed list. */
+    device: string;
+    /** Why this device fits this product, specifically. */
+    reason: string;
+}
+export interface Arc {
+    /** Must land within 2 seconds (STYLE.md's "The hook" rule) -- a text description of the
+     * hook's idea, not a timing value; the 2s budget is enforced later, on the actual beat. */
+    hook: string;
+    tension: string;
+    turn: string;
+    proof: string;
+    /** Must resolve the hook. */
+    payoff: string;
+    cta: string;
+}
+/**
+ * Why design.ts's choices were made, not a copy of the values themselves (those live in
+ * design.ts, see packages/core/src/designSystem.ts's defineDesignSystem). One fact in one
+ * place: this is the reasoning, design.ts is the value.
+ */
+export interface DesignRationale {
+    /** Repo-relative path to this video's design.ts, e.g. "src/videos/loomcard/design.ts". */
+    path: string;
+    /** Why these palette roles: what extract_brand found, plus the brief's own mood words. */
+    paletteRationale: string;
+    /** Mirrors designSystem.ts's Motif union. Kept as a local literal copy (mcp-server does
+     * not depend on @openvidstudio/core) -- update MOTIFS here if that union ever changes. */
+    motif: "pixel-grid" | "rounded-soft" | "geometric" | "editorial" | "void-spark";
+    motifRationale: string;
+    motionRationale: string;
+}
+/** A video score's section vocabulary. Doubles as the section's identity and its intensity. */
+declare const INTENSITY_LABELS: readonly ["intro", "tension", "reveal", "groove", "break", "peak", "outro"];
+export interface MusicSection {
+    label: (typeof INTENSITY_LABELS)[number];
+    startBar: number;
+    endBar: number;
+}
+export interface MusicImpactPoint {
+    /** e.g. "reveal". */
+    name: string;
+    bar: number;
+    /** e.g. "beat 'reveal' starts at bar 12". */
+    note: string;
+}
+export interface MusicPlan {
+    bpm: number;
+    key: string;
+    sectionMap: MusicSection[];
+    impactPoints: MusicImpactPoint[];
+}
+export interface ShotListEntry {
+    beatId: string;
+    /** True: a real capture or another tool's real output backs this shot. False: hand-built. */
+    real: boolean;
+    /** When real: which capture/tool ("capture_screenshot of /review", "plan_shots pick #2").
+     * When constructed: what's being built instead ("dom-demo panel reusing the review card style"). */
+    provenance: string;
+    /** Required when real is false: why this couldn't be a real capture. */
+    whyConstructed?: string;
+    /** The one thing in this shot that matters (STYLE.md's "one focal point per shot" rule). */
+    focalPoint: string;
+    /**
+     * True when this beat is meant to hold still (a title card the music breathes under, a
+     * deliberate beat of silence). validate_scenes's render mode treats a beat whose frames never
+     * change as a dead-frames finding; this is the brief saying that, for this beat, it is intended.
+     */
+    deliberateHold?: boolean;
+}
+export interface StyleOverride {
+    /** Which STYLE.md default changed, and to what, e.g. "grain: 0% instead of the 4-6% default". */
+    rule: string;
+    reason: string;
+}
+/**
+ * Discloses a beat whose "real" capture is of constructed sample content (a fictional app,
+ * dataset, or repo built specifically to film) rather than the actual product -- same
+ * pattern as this repo's own reference/acme-tasks. Consumed by write_description (C9), which
+ * refuses to let this go unmentioned: it surfaces in output/<video>-DESCRIPTION.md whenever
+ * this array is non-empty.
+ */
+export interface SampleContentEntry {
+    beatId: string;
+    /** What the sample content actually is, e.g. "Acme Tasks, a fictional task board app". */
+    whatItIs: string;
+    /** Why it had to be constructed rather than captured from the real product. */
+    whyConstructed: string;
+}
+export interface BriefJson {
+    /** Mirrors openvidstudio.config.json's production.creativeLevel (PLANNING.md §0). Recorded
+     * here too because the brief is authored before beats.json exists, so this is the only
+     * place on disk that says which level this brief was written under. */
+    creativeLevel?: "peak" | "mid" | "literal";
+    /** Mirrors production.mode. Omitted means "standard"; "supernova" marks a STEM lesson. */
+    mode?: "standard" | "supernova";
+    logline: string;
+    audience: string;
+    /** The one feeling the viewer should leave with. */
+    feeling: string;
+    storyDevice: StoryDevice;
+    arc: Arc;
+    designSystem: DesignRationale;
+    music: MusicPlan;
+    shotList: ShotListEntry[];
+    /** Optional: STYLE.md defaults this video overrides, with why. Omit or [] if none. */
+    styleOverrides?: StyleOverride[];
+    /** Optional: constructed sample content this video discloses. Omit or [] if none. */
+    sampleContent?: SampleContentEntry[];
+}
+export interface ValidateBriefResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Mechanically validates a drafted brief.json against the shape this file documents (and
+ * PLANNING.md's new creative-brief section mirrors). Shape only, same philosophy as
+ * validateBeatsLogic: a literal-mode brief being "honest about having nothing to add" is
+ * about what the agent writes into these fields, not a different schema for that level.
+ */
+export declare function validateBriefLogic(briefJson: unknown): ValidateBriefResult;
+export interface WriteBriefInput {
+    projectRoot?: string;
+    videoName: string;
+    /** Free-form prose: the actual creative reasoning. Written verbatim, not validated. */
+    briefMarkdown: string;
+    briefJson: unknown;
+}
+export type WriteBriefResult = {
+    written: true;
+    briefMdPath: string;
+    briefJsonPath: string;
+} | ValidateBriefResult;
+/**
+ * Mirrors write_beats_file's pattern: runs validateBriefLogic internally (a direct function
+ * call, not an MCP round-trip) and refuses to write anything invalid, returning the same
+ * { valid: false, errors } shape instead. On success writes BOTH src/videos/<videoName>/
+ * brief.md (the raw briefMarkdown string, as given) and brief.json (pretty-printed). Neither
+ * file is written unless both inputs are present and briefJson passes validation -- this is
+ * one write, not two independent ones.
+ */
+export declare function runWriteBrief(input: WriteBriefInput): WriteBriefResult;
+export declare function registerWriteBrief(server: McpServer): void;
+export {};