@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/writeBrief.js

@@ -0,0 +1,344 @@
+"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.validateBriefLogic = validateBriefLogic;
+exports.runWriteBrief = runWriteBrief;
+exports.registerWriteBrief = registerWriteBrief;
+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");
+/** One of defineDesignSystem's five motifs (packages/core/src/designSystem.ts). */
+const MOTIFS = ["pixel-grid", "rounded-soft", "geometric", "editorial", "void-spark"];
+/** A video score's section vocabulary. Doubles as the section's identity and its intensity. */
+const INTENSITY_LABELS = ["intro", "tension", "reveal", "groove", "break", "peak", "outro"];
+const EM_DASH = "—";
+const CREATIVE_LEVELS = ["peak", "mid", "literal"];
+const ARC_KEYS = ["hook", "tension", "turn", "proof", "payoff", "cta"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(obj, key, label, errors) {
+    const val = obj[key];
+    if (typeof val !== "string" || val.trim().length === 0) {
+        errors.push(`${label}${key} must be a non-empty string`);
+    }
+}
+/** Recursively scans every string value (object values, array entries) for an em dash, so a
+ * nested field doesn't need its own hand-written check to be caught -- same writing rule
+ * (no em dashes) validateBeats.ts enforces field by field, applied here in one sweep. */
+function collectEmDashErrors(value, label, errors) {
+    if (typeof value === "string") {
+        if (value.includes(EM_DASH)) {
+            errors.push(`${label} contains an em dash, rewrite with commas/periods`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => collectEmDashErrors(item, `${label}[${i}]`, errors));
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [k, v] of Object.entries(value)) {
+            collectEmDashErrors(v, label ? `${label}.${k}` : k, errors);
+        }
+    }
+}
+/**
+ * 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.
+ */
+function validateBriefLogic(briefJson) {
+    const errors = [];
+    if (!isPlainObject(briefJson)) {
+        return { valid: false, errors: ["briefJson must be an object"] };
+    }
+    const b = briefJson;
+    // A lesson has no creative level (that scale is for product videos), so it is required only
+    // outside supernova mode, and still checked if a lesson brief gives one.
+    const creativeLevelOptional = b.mode === "supernova" && b.creativeLevel === undefined;
+    if (!creativeLevelOptional && (typeof b.creativeLevel !== "string" || !CREATIVE_LEVELS.includes(b.creativeLevel))) {
+        errors.push(`creativeLevel must be one of ${CREATIVE_LEVELS.map((l) => `"${l}"`).join(", ")}`);
+    }
+    if (b.mode !== undefined && b.mode !== "standard" && b.mode !== "supernova") {
+        errors.push(`mode must be "standard" or "supernova" (omit for "standard")`);
+    }
+    requireNonEmptyString(b, "logline", "", errors);
+    requireNonEmptyString(b, "audience", "", errors);
+    requireNonEmptyString(b, "feeling", "", errors);
+    if (!isPlainObject(b.storyDevice)) {
+        errors.push(`storyDevice must be an object: { device, reason }`);
+    }
+    else {
+        requireNonEmptyString(b.storyDevice, "device", "storyDevice.", errors);
+        requireNonEmptyString(b.storyDevice, "reason", "storyDevice.", errors);
+    }
+    if (!isPlainObject(b.arc)) {
+        errors.push(`arc must be an object: { ${ARC_KEYS.join(", ")} }`);
+    }
+    else {
+        for (const key of ARC_KEYS) {
+            requireNonEmptyString(b.arc, key, "arc.", errors);
+        }
+    }
+    if (!isPlainObject(b.designSystem)) {
+        errors.push(`designSystem must be an object: { path, paletteRationale, motif, motifRationale, motionRationale }`);
+    }
+    else {
+        const ds = b.designSystem;
+        requireNonEmptyString(ds, "path", "designSystem.", errors);
+        requireNonEmptyString(ds, "paletteRationale", "designSystem.", errors);
+        requireNonEmptyString(ds, "motifRationale", "designSystem.", errors);
+        requireNonEmptyString(ds, "motionRationale", "designSystem.", errors);
+        if (typeof ds.motif !== "string" || !MOTIFS.includes(ds.motif)) {
+            errors.push(`designSystem.motif must be one of ${MOTIFS.map((m) => `"${m}"`).join(", ")}`);
+        }
+    }
+    if (!isPlainObject(b.music)) {
+        errors.push(`music must be an object: { bpm, key, sectionMap, impactPoints }`);
+    }
+    else {
+        const music = b.music;
+        if (typeof music.bpm !== "number" || music.bpm <= 0) {
+            errors.push(`music.bpm must be a positive number`);
+        }
+        requireNonEmptyString(music, "key", "music.", errors);
+        if (!Array.isArray(music.sectionMap) || music.sectionMap.length === 0) {
+            errors.push(`music.sectionMap must be a non-empty array of { label, startBar, endBar }`);
+        }
+        else {
+            music.sectionMap.forEach((raw, i) => {
+                const prefix = `music.sectionMap[${i}]`;
+                if (!isPlainObject(raw)) {
+                    errors.push(`${prefix} must be an object: { label, startBar, endBar }`);
+                    return;
+                }
+                if (typeof raw.label !== "string" || !INTENSITY_LABELS.includes(raw.label)) {
+                    errors.push(`${prefix}.label must be one of ${INTENSITY_LABELS.map((l) => `"${l}"`).join(", ")}`);
+                }
+                const hasStart = typeof raw.startBar === "number" && raw.startBar > 0;
+                if (!hasStart)
+                    errors.push(`${prefix}.startBar must be a positive number`);
+                const hasEnd = typeof raw.endBar === "number" && raw.endBar > 0;
+                if (!hasEnd)
+                    errors.push(`${prefix}.endBar must be a positive number`);
+                if (hasStart && hasEnd && raw.endBar <= raw.startBar) {
+                    errors.push(`${prefix}.endBar (${raw.endBar}) must be greater than startBar (${raw.startBar})`);
+                }
+            });
+            // compose_score consumes this map as consecutive section lengths and rejects a gap or an
+            // overlap, so a brief that passes here has to be one it can compose. endBar is the first bar
+            // of the next section, not the last bar of this one.
+            const sections = music.sectionMap;
+            sections.forEach((raw, i) => {
+                if (i === 0 || !isPlainObject(raw))
+                    return;
+                const prev = sections[i - 1];
+                if (!isPlainObject(prev))
+                    return;
+                if (typeof prev.endBar === "number" && typeof raw.startBar === "number" && prev.endBar !== raw.startBar) {
+                    errors.push(`music.sectionMap[${i}].startBar (${raw.startBar}) must equal music.sectionMap[${i - 1}].endBar (${prev.endBar}): ` +
+                        `sections connect exactly, and endBar is the first bar of the next section (compose_score rejects a gap or overlap)`);
+                }
+            });
+        }
+        if (music.impactPoints !== undefined) {
+            if (!Array.isArray(music.impactPoints)) {
+                errors.push(`music.impactPoints must be an array of { name, bar, note } when present`);
+            }
+            else {
+                music.impactPoints.forEach((raw, i) => {
+                    const prefix = `music.impactPoints[${i}]`;
+                    if (!isPlainObject(raw)) {
+                        errors.push(`${prefix} must be an object: { name, bar, note }`);
+                        return;
+                    }
+                    requireNonEmptyString(raw, "name", `${prefix}.`, errors);
+                    if (typeof raw.bar !== "number" || raw.bar <= 0)
+                        errors.push(`${prefix}.bar must be a positive number`);
+                    requireNonEmptyString(raw, "note", `${prefix}.`, errors);
+                });
+            }
+        }
+    }
+    // A lesson has no real product to be real or constructed about: everything in it is drawn on purpose, so
+    // the real/constructed split and the reasons for it do not apply. A shot list is optional there, and an
+    // entry only has to say which beat it is about.
+    const lesson = b.mode === "supernova";
+    if (lesson) {
+        if (b.shotList !== undefined && !Array.isArray(b.shotList)) {
+            errors.push(`shotList must be an array of { beatId } when present`);
+        }
+        else if (Array.isArray(b.shotList)) {
+            b.shotList.forEach((raw, i) => {
+                if (!isPlainObject(raw))
+                    errors.push(`shotList[${i}] must be an object: { beatId }`);
+                else
+                    requireNonEmptyString(raw, "beatId", `shotList[${i}].`, errors);
+            });
+        }
+    }
+    else if (!Array.isArray(b.shotList) || b.shotList.length === 0) {
+        errors.push(`shotList must be a non-empty array of { beatId, real, provenance, focalPoint }`);
+    }
+    else {
+        b.shotList.forEach((raw, i) => {
+            const prefix = `shotList[${i}]`;
+            if (!isPlainObject(raw)) {
+                errors.push(`${prefix} must be an object: { beatId, real, provenance, focalPoint }`);
+                return;
+            }
+            requireNonEmptyString(raw, "beatId", `${prefix}.`, errors);
+            if (typeof raw.real !== "boolean") {
+                errors.push(`${prefix}.real must be a boolean`);
+            }
+            requireNonEmptyString(raw, "provenance", `${prefix}.`, errors);
+            requireNonEmptyString(raw, "focalPoint", `${prefix}.`, errors);
+            if (raw.deliberateHold !== undefined && typeof raw.deliberateHold !== "boolean") {
+                errors.push(`${prefix}.deliberateHold must be a boolean when present`);
+            }
+            if (raw.real === false) {
+                requireNonEmptyString(raw, "whyConstructed", `${prefix}.`, errors);
+            }
+        });
+    }
+    if (b.styleOverrides !== undefined) {
+        if (!Array.isArray(b.styleOverrides)) {
+            errors.push(`styleOverrides must be an array of { rule, reason } when present`);
+        }
+        else {
+            b.styleOverrides.forEach((raw, i) => {
+                const prefix = `styleOverrides[${i}]`;
+                if (!isPlainObject(raw)) {
+                    errors.push(`${prefix} must be an object: { rule, reason }`);
+                    return;
+                }
+                requireNonEmptyString(raw, "rule", `${prefix}.`, errors);
+                requireNonEmptyString(raw, "reason", `${prefix}.`, errors);
+            });
+        }
+    }
+    if (b.sampleContent !== undefined) {
+        if (!Array.isArray(b.sampleContent)) {
+            errors.push(`sampleContent must be an array of { beatId, whatItIs, whyConstructed } when present`);
+        }
+        else {
+            b.sampleContent.forEach((raw, i) => {
+                const prefix = `sampleContent[${i}]`;
+                if (!isPlainObject(raw)) {
+                    errors.push(`${prefix} must be an object: { beatId, whatItIs, whyConstructed }`);
+                    return;
+                }
+                requireNonEmptyString(raw, "beatId", `${prefix}.`, errors);
+                requireNonEmptyString(raw, "whatItIs", `${prefix}.`, errors);
+                requireNonEmptyString(raw, "whyConstructed", `${prefix}.`, errors);
+            });
+        }
+    }
+    collectEmDashErrors(b, "briefJson", errors);
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * 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.
+ */
+function runWriteBrief(input) {
+    const validation = validateBriefLogic(input.briefJson);
+    if (!validation.valid) {
+        return validation;
+    }
+    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);
+    fs.mkdirSync(videoDir, { recursive: true });
+    const briefMdPath = path.join(videoDir, "brief.md");
+    const md = input.briefMarkdown.endsWith("\n") ? input.briefMarkdown : `${input.briefMarkdown}\n`;
+    fs.writeFileSync(briefMdPath, md, "utf8");
+    const briefJsonPath = path.join(videoDir, "brief.json");
+    fs.writeFileSync(briefJsonPath, `${JSON.stringify(input.briefJson, null, 2)}\n`, "utf8");
+    return { written: true, briefMdPath, briefJsonPath };
+}
+function registerWriteBrief(server) {
+    server.registerTool("write_brief", {
+        title: "Write a validated creative brief (brief.md + brief.json) to disk",
+        description: "Writes the creative brief that PLANNING.md's new creative-brief section requires before any beat " +
+            "gets written: BOTH src/videos/<videoName>/brief.md (free-form prose, the actual creative reasoning " +
+            "-- written verbatim, exactly the string given, no validation of prose content) AND " +
+            "src/videos/<videoName>/brief.json (structured, validated). Mirrors write_beats_file's pattern: runs " +
+            "its own shape validation internally first (a direct function call, not an MCP round-trip) and " +
+            "refuses to write anything invalid, returning { valid: false, errors } naming exactly what's missing " +
+            "or wrong instead. Neither file is written unless briefJson passes validation in full. " +
+            "briefJson's required shape: creativeLevel (\"peak\"/\"mid\"/\"literal\", mirrors PLANNING.md §0's " +
+            "intake); logline, audience, feeling (non-empty strings); storyDevice ({ device, reason }, a " +
+            "deliberately chosen device such as 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, never " +
+            "defaulted); arc ({ hook, tension, turn, proof, payoff, cta }, the hook must land within 2 seconds " +
+            "per STYLE.md and the payoff must resolve the hook); designSystem ({ path, paletteRationale, motif " +
+            "[\"pixel-grid\"/\"rounded-soft\"/\"geometric\"/\"editorial\"/\"void-spark\", mirrors defineDesignSystem's Motif " +
+            "union], motifRationale, motionRationale } -- the WHY behind this video's src/videos/<name>/design.ts, " +
+            "never a duplicate copy of its actual color/type/motion values, which live only in design.ts); music " +
+            "({ bpm, key, sectionMap: non-empty array of { label [\"intro\"/\"tension\"/\"reveal\"/\"groove\"/" +
+            "\"break\"/\"peak\"/\"outro\", whatever subset applies], startBar, endBar }, impactPoints: array of " +
+            "{ name, bar, note } }); shotList (non-empty array of { beatId, real [boolean], provenance [which " +
+            "real capture/tool's output, or what was constructed instead], whyConstructed [required when real " +
+            "is false], focalPoint [the one thing in this shot that matters], deliberateHold [optional boolean: this beat is meant to hold still, so validate_scenes does not report its unchanging frames as dead] }). Optional: styleOverrides (array " +
+            "of { rule, reason } for any STYLE.md default this video overrides) and sampleContent (array of " +
+            "{ beatId, whatItIs, whyConstructed }, disclosing any beat whose real capture is of constructed " +
+            "sample content -- a fictional app/dataset/repo built specifically to film -- rather than the actual " +
+            "product; consumed by write_description, which surfaces this in the video's description file). Every " +
+            "string field, at any depth, is checked for an em dash. In literal mode the brief is still shaped " +
+            "the same way, but should be honest about having nothing to add: it restates the user's own spec " +
+            "rather than inventing a story device or arc beyond what was asked for. IMPORTANT: like " +
+            "write_beats_file, this tool only enforces schema validity, not dev approval -- show the dev the " +
+            "full brief (both files) and get explicit approval before calling this, same protocol as beats.json's " +
+            "approval gate (PLANNING.md §5).",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            briefMarkdown: zod_1.z
+                .string()
+                .min(1)
+                .describe("Free-form prose: the actual creative reasoning. Written verbatim, not a file path."),
+            briefJson: zod_1.z.unknown().describe("The drafted brief.json content (an object), not a file path."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("write_brief", () => runWriteBrief(input)));
+}

package/dist/tools/writeDescription.d.ts

@@ -0,0 +1,58 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface WriteDescriptionInput {
+    projectRoot?: string;
+    videoName: string;
+}
+export interface WriteDescriptionResult {
+    written: true;
+    path: string;
+    /** beatIds whose sample-content disclosure was written and round-trip verified against the file on disk. */
+    sampleContentDisclosed: string[];
+    /** The YouTube chapter lines written ("0:00 Hook"), or [] when the video is too short to have chapters. */
+    chapters: string[];
+    /** Credit lines written, so a caller can show them without re-reading the file. */
+    credits: string[];
+    /** Lesson with a practiceQuestion and an answer: the ANSWER.md written next to the description (the pinned comment). Absent otherwise. */
+    answerPath?: string;
+    /** Lesson with a practiceQuestion and an answer: the question put in the description. Absent otherwise. */
+    practiceQuestion?: string;
+    /** The config's `disclaimers` appended to a lesson description, each once, in order. Absent when none were. */
+    disclaimers?: string[];
+}
+/** YouTube lists chapters only when there are at least three and each is at least ten seconds. */
+export declare const MIN_CHAPTERS = 3;
+export declare const MIN_CHAPTER_SECONDS = 10;
+interface BeatLike {
+    id: string;
+    duration: number;
+    vo: string;
+    /** An optional human title for the beat's chapter. Without it the beat id is made readable. */
+    chapter?: string;
+}
+/** "demo-search" -> "Demo search". A beat id is a slug, not a title, but it is the only name a beat has by default. */
+export declare function humanizeBeatId(id: string): string;
+/** 75 -> "1:15", 3725 -> "1:02:05". YouTube reads m:ss, or h:mm:ss from an hour on. */
+export declare function chapterTimestamp(seconds: number): string;
+export interface Chapter {
+    seconds: number;
+    label: string;
+}
+/**
+ * Chapters from the real beats, in YouTube's terms: the first at 0:00, each at least ten seconds,
+ * at least three of them. Beats are merged forward into one chapter until it reaches ten seconds
+ * (named after its first beat), and a short tail folds into the chapter before it, so a video of
+ * many two-second beats still gets sensible chapters. Fewer than three chapters means YouTube
+ * would ignore the list, so none are written and the caller says why instead.
+ */
+export declare function buildChapters(beats: BeatLike[], fps: number): {
+    chapters: Chapter[];
+    skippedBecause?: string;
+};
+/**
+ * Writes output/<videoName>-DESCRIPTION.md and refuses to report success if a constructed
+ * shot's disclosure went missing from the file it just wrote (see the round-trip check below).
+ * See ShotListEntry/readBrief above for the brief.json shape this reads.
+ */
+export declare function runWriteDescription(input: WriteDescriptionInput): WriteDescriptionResult;
+export declare function registerWriteDescription(server: McpServer): void;
+export {};