@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/collectFacts.js

@@ -0,0 +1,210 @@
+"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.buildFactsDocument = buildFactsDocument;
+exports.runCollectFacts = runCollectFacts;
+exports.registerCollectFacts = registerCollectFacts;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const facts_1 = require("../facts");
+const mcp_1 = require("./mcp");
+/** beats.json captureMethod values that promise a real, captured visual. */
+const CAPTURE_METHODS = new Set(["screenshot", "recording", "higgsfield"]);
+const CAPTURE_TOOLS = new Set([
+    "capture_screenshot",
+    "capture_screen_recording",
+    "capture_terminal",
+    "capture_desktop",
+    "capture_mobile",
+    "import_higgsfield_clip",
+]);
+function latestBy(items, key) {
+    const map = new Map();
+    for (const item of items)
+        map.set(key(item), item); // input is oldest first, so the last write wins
+    return [...map.values()];
+}
+/** Pure: builds the document from records and a beats list. File checks go through `fileExists`. */
+function buildFactsDocument(opts) {
+    const { videoName, beats, records, fileExists } = opts;
+    const beatIds = new Set(beats.map((b) => b.id));
+    // A record belongs to this video when it names it, or when it is a per-beat record (a
+    // capture takes no video name) for a beat this video has.
+    const mine = records.filter((r) => r.videoName !== undefined ? r.videoName === videoName : r.beatId !== undefined && beatIds.has(r.beatId));
+    const captureRecords = mine.filter((r) => CAPTURE_TOOLS.has(r.tool) && r.beatId);
+    const validations = mine.filter((r) => r.tool === "validate_scenes" || r.tool === "validate_beats");
+    const renders = mine.filter((r) => r.tool === "render_video");
+    const latestRender = renders[renders.length - 1] ?? null;
+    const latestStitch = [...mine].reverse().find((r) => r.tool === "stitch_composition") ?? null;
+    const latestFinal = [...mine].reverse().find((r) => r.tool === "finalize_video") ?? null;
+    const discrepancies = [];
+    const beatFacts = {};
+    for (const beat of beats) {
+        const method = beat.visual?.captureMethod ?? null;
+        const captures = latestBy(captureRecords.filter((r) => r.beatId === beat.id), (r) => r.tool).map((r) => ({ tool: r.tool, recordedAt: r.recordedAt, ...r.facts }));
+        let provenance;
+        if (captures.length > 0)
+            provenance = "capture";
+        else if (method !== null && !CAPTURE_METHODS.has(method))
+            provenance = "construction";
+        else
+            provenance = "unverified";
+        if (method !== null && CAPTURE_METHODS.has(method) && captures.length === 0) {
+            discrepancies.push({
+                beatId: beat.id,
+                kind: "claimed-capture-without-record",
+                detail: `beats.json says captureMethod "${method}" but no capture tool left a run record for this beat.`,
+            });
+        }
+        for (const c of captures) {
+            const out = typeof c.outPath === "string" ? c.outPath : null;
+            if (out && !fileExists(out)) {
+                discrepancies.push({
+                    beatId: beat.id,
+                    kind: "capture-file-missing",
+                    detail: `${String(c.tool)} recorded ${out} but that file is not on disk now.`,
+                });
+            }
+        }
+        let render = null;
+        if (latestRender) {
+            const f = latestRender.facts;
+            if (f.success !== false) {
+                const status = f.reusedBeats?.includes(beat.id)
+                    ? "reused"
+                    : f.renderedBeats?.includes(beat.id) || (!f.renderedBeats && !f.reusedBeats)
+                        ? "rendered"
+                        : "unknown";
+                render = { status, recordedAt: latestRender.recordedAt };
+            }
+        }
+        const validation = [];
+        for (const tool of ["validate_scenes", "validate_beats"]) {
+            const rec = [...validations].reverse().find((r) => r.tool === tool);
+            if (!rec)
+                continue;
+            const all = rec.facts.findings ?? [];
+            validation.push({ tool, recordedAt: rec.recordedAt, findings: all.filter((f) => f.beatId === beat.id) });
+        }
+        beatFacts[beat.id] = {
+            claimed: { captureMethod: method, source: beat.visual?.source ?? null },
+            provenance,
+            captures,
+            render,
+            validation,
+        };
+    }
+    const videoValidation = {};
+    for (const tool of ["validate_scenes", "validate_beats"]) {
+        const rec = [...validations].reverse().find((r) => r.tool === tool);
+        if (!rec)
+            continue;
+        const { findings: _findings, ...summary } = rec.facts;
+        void _findings;
+        videoValidation[tool] = {
+            recordedAt: rec.recordedAt,
+            ...summary,
+            // Findings with no beat (a video-level problem) have nowhere else to live.
+            videoLevel: (rec.facts.findings ?? []).filter((f) => !f.beatId || !beatIds.has(String(f.beatId))),
+        };
+    }
+    return {
+        schemaVersion: facts_1.FACT_SCHEMA_VERSION,
+        videoName,
+        collectedAt: (opts.now ?? new Date()).toISOString(),
+        recordsRead: records.length,
+        recordsUsed: mine.length,
+        beats: beatFacts,
+        video: {
+            composition: latestStitch ? { recordedAt: latestStitch.recordedAt, ...latestStitch.facts } : null,
+            render: latestRender ? { recordedAt: latestRender.recordedAt, ...latestRender.facts } : null,
+            final: latestFinal ? { recordedAt: latestFinal.recordedAt, ...latestFinal.facts } : null,
+            validation: videoValidation,
+        },
+        discrepancies,
+    };
+}
+function runCollectFacts(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const videoDir = path.join(projectRoot, "src", "videos", videoName);
+    const beatsFile = path.join(videoDir, "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 records = (0, facts_1.readFactRecords)(projectRoot);
+    if (records.length === 0) {
+        throw new Error(`No run records in ${path.join(projectRoot, facts_1.RUNS_DIR_REL)}. Tools write one each time they capture, ` +
+            `render, validate or stitch, so run the pipeline first.`);
+    }
+    const facts = buildFactsDocument({
+        videoName,
+        beats: doc.beats ?? [],
+        records,
+        fileExists: (rel) => fs.existsSync(path.join(projectRoot, rel)),
+    });
+    const factsPath = path.join(videoDir, "facts.json");
+    fs.writeFileSync(factsPath, JSON.stringify(facts, null, 2) + "\n", "utf8");
+    return {
+        factsPath,
+        recordsRead: facts.recordsRead,
+        recordsUsed: facts.recordsUsed,
+        beatsWithCapture: Object.entries(facts.beats)
+            .filter(([, b]) => b.provenance === "capture")
+            .map(([id]) => id),
+        discrepancies: facts.discrepancies,
+    };
+}
+function registerCollectFacts(server) {
+    server.registerTool("collect_facts", {
+        title: "Merge a video's run records into facts.json",
+        description: "Reads the run records tools leave in .openvidstudio/runs/ (capture_screenshot, " +
+            "capture_screen_recording, capture_terminal, capture_desktop, capture_mobile, " +
+            "import_higgsfield_clip, stitch_composition, render_video, finalize_video, validate_scenes, validate_beats) and merges " +
+            "the ones belonging to this video into src/videos/<videoName>/facts.json, keyed by beat id: what " +
+            "captured it and when, whether the last render rendered or reused it, what each validator flagged. " +
+            "Then compares that with beats.json and lists discrepancies, such as a beat that claims a real " +
+            "capture with no capture record behind it, or a captured file that is gone. This is how a claim " +
+            "gets checked against what actually ran rather than against the plan's own text. Errors if there " +
+            "are no run records yet.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+        },
+    }, async (input) => (0, mcp_1.runTool)("collect_facts", () => runCollectFacts(input)));
+}

package/dist/tools/composeScore.d.ts

@@ -0,0 +1,156 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * compose_score builds an original, arc-matched score for a video: it turns the
+ * music plan a brief already carries (or a direct override) into a spec.json, spawns
+ * packages/mcp-server/py/compose-score.py to actually compose and master it, and wires
+ * the result into the rest of the pipeline the same way every other music path does.
+ * This file owns none of the DSP: key/harmony, the arrangement engine, mastering, and
+ * the diagnostic checks all live in that script, per its own module docstring (read in
+ * full before writing this). This is the glue around it: spec.json in, public/audio/
+ * mp3 plus cues.json plus a spectrogram PNG out.
+ *
+ * The script's real spec.json contract (its field names, not inferred):
+ *   bpm, key, sections: [{label, bars}], impacts: [{label, atBar, atBeat}],
+ *   mode: "bed" | "music" (loudness target, -15 LUFS under narration vs -14 for
+ *   music-only), trackName (the `track` field it records), outWav / outCues /
+ *   outSpectrogram (absolute paths this tool chooses and the script writes to
+ *   directly). The script already sets `source: "generated"` and `generatedBy` on
+ *   its own cues object; this tool re-asserts both when it reads the file back
+ *   anyway (see runComposeScore below), partly for certainty and partly because the
+ *   script's own hardcoded generatedBy string says "scripts/compose-score.py", which
+ *   is stale against its real location in py/ -- not this file's place to patch the
+ *   .py source, but worth correcting in the file this tool actually ships.
+ *
+ * Progress lines go to the script's stdout as plain text (see its own print() calls
+ * near the end of main()), never JSON; the only reporting channel of substance is
+ * outCues, a file. There is nothing to parse from stdout here.
+ *
+ * The cues.json integration point (the part that matters most): a music track at
+ * public/audio/<stem>.mp3 has a cues file next to it at public/audio/<stem>.cues.json,
+ * shaped like MusicCuesResult (see musicCues.ts). `source: "generated"` means "exact by
+ * construction", and plan_music_cues treats a generated cues file as ground truth,
+ * returning it directly with no re-analysis. compose-score.py's own cues fields already
+ * use matching names (beats, strongCues, bpm) for exactly this reason.
+ *
+ * WAV handling: compose-score.py masters to a 24-bit PCM wav, a transient intermediate,
+ * not a shipped artifact. It is written to a temp path, transcoded to mp3 with ffmpeg,
+ * then deleted. The diagnostic spectrogram PNG is kept permanently next to the mp3,
+ * written there directly by the script (outSpectrogram points at its final home from
+ * the start, no separate move step needed).
+ */
+export interface MusicSection {
+    label: string;
+    startBar: number;
+    endBar: number;
+}
+export interface MusicImpactPoint {
+    name: string;
+    bar: number;
+    note?: string;
+}
+/**
+ * Matches brief.json's `music` field (writeBrief.ts's MusicPlan), reproduced here as a
+ * local type rather than imported: packages/mcp-server/src/tools/writeBrief.ts does not
+ * exist in this worktree (checked with `git log --all` across every branch, not just a
+ * stale checkout, unlike compose-score.py which did exist uncommitted elsewhere and was
+ * copied in as-is). If the real writeBrief.ts lands with different field names, this is
+ * the one type to reconcile.
+ */
+export interface MusicPlan {
+    bpm: number;
+    key: string;
+    sectionMap: MusicSection[];
+    impactPoints?: MusicImpactPoint[];
+}
+export interface ComposeScoreInput {
+    projectRoot?: string;
+    videoName: string;
+    /** Direct override. If omitted, read from src/videos/<videoName>/brief.json's `music` field. */
+    music?: MusicPlan;
+    /** Bare filename under public/audio/, ending in .mp3. Defaults to "music-bed.mp3". */
+    outFile?: string;
+    /**
+     * "bed": -15 LUFS, mastered to sit under narration, matching MusicBed's own
+     * quiet-by-design convention (see NARRATION.md). "music": -14 LUFS, for a music-only
+     * video (narration: "none") where the score is the only thing on the audio track.
+     */
+    mode: "bed" | "music";
+    /**
+     * "none" (default): no kick, clap, hat or tick, and the bass and arp play uneven
+     * rhythms with small timing and level variation, so nothing repeats identically on a
+     * fixed grid. A perfectly even, short-decay hit reads as a ticking clock under a
+     * voiceover. "full": the old drum-machine arrangement, kept as an opt-in.
+     */
+    percussion?: "none" | "full";
+}
+export interface ComposeScoreResult {
+    /** Relative to projectRoot, forward slashes. */
+    mp3Path: string;
+    /** Relative to projectRoot, forward slashes. */
+    cuesPath: string;
+    /** Relative to projectRoot, forward slashes. */
+    spectrogramPath: string;
+    bpm: number;
+    key: string;
+    durationSeconds: number;
+    /**
+     * Populated from the script's own checks rather than left buried in the written cues
+     * file: a band-balance verdict that is not "ok", any detected clicks, a true peak over
+     * the limiter's ceiling, or an integrated loudness far from target all surface here.
+     */
+    warnings: string[];
+    /** The full cues object exactly as written to cuesPath. */
+    cues: Record<string, unknown>;
+}
+/** Same python-then-python3 fallback order preflight.ts's "compose-score-deps" check uses. */
+export declare function resolvePythonCommand(): string | null;
+/**
+ * brief's sectionMap: [{label, startBar, endBar}] becomes compose-score.py's
+ * sections: [{label, bars}]. Validated contiguous and strictly in order first, so a
+ * gap or overlap the brief didn't intend to have is caught here rather than silently
+ * producing a score whose structure doesn't match what the brief actually described.
+ */
+export declare function sectionsToPythonSections(sectionMap: MusicSection[]): {
+    label: string;
+    bars: number;
+}[];
+/**
+ * impactPoints: [{name, bar, note}] to spec's impacts: [{label, atBar, atBeat}]. The
+ * brief has no beat-level granularity, so atBeat is 0, which main() itself treats as
+ * the default (`imp.get("atBeat", 0)`).
+ */
+export declare function impactPointsToPythonImpacts(impactPoints: MusicImpactPoint[] | undefined): {
+    label: string;
+    atBar: number;
+    atBeat: number;
+}[];
+interface ComposeScoreSpec {
+    bpm: number;
+    key: string;
+    sections: {
+        label: string;
+        bars: number;
+    }[];
+    impacts: {
+        label: string;
+        atBar: number;
+        atBeat: number;
+    }[];
+    mode: "bed" | "music";
+    percussion: "none" | "full";
+    trackName: string;
+    outWav: string;
+    outCues: string;
+    outSpectrogram: string;
+}
+export declare function buildComposeScoreSpec(music: MusicPlan, trackName: string, outWav: string, outCues: string, outSpectrogram: string, mode: "bed" | "music", percussion?: "none" | "full"): ComposeScoreSpec;
+/**
+ * Surfaces the script's own diagnostic checks as actionable warnings instead of leaving
+ * them readable only by opening the written cues file. Any of: a band-balance verdict
+ * that isn't "ok", a detected click, a true peak over the limiter's own ceiling, or an
+ * integrated loudness far from the mastering target.
+ */
+export declare function computeWarnings(cues: Record<string, unknown>): string[];
+export declare function runComposeScore(input: ComposeScoreInput): ComposeScoreResult;
+export declare function registerComposeScore(server: McpServer): void;
+export {};