@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/jobs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * In-memory job tracking for tools whose real work can outlast an MCP client's own request
+ * timeout (Claude Code's MCP_TOOL_TIMEOUT defaults well under the 40+ minutes a full render
+ * can take on a modest machine). A tool that accepts `async: true` starts its real work
+ * without awaiting it in the request handler, records it here, and returns a jobId
+ * immediately; `job_status` (jobStatus.ts) polls this store.
+ *
+ * Deliberately in-memory, not persisted: a job dies with the server process, same as the
+ * render it's tracking would. This process is a long-lived stdio server for the duration of
+ * one MCP connection, so a promise kicked off here and never awaited by its caller keeps
+ * running on the same event loop while later requests (including job_status polls) are
+ * handled -- that's what makes "return now, finish later" work at all.
+ */
+export type JobStatus = "running" | "done" | "error";
+export interface JobProgress {
+    framesRendered: number;
+    totalFrames: number;
+    currentBeat: string | null;
+    /** Most recent lines first isn't the point here; insertion order, capped, is. */
+    logTail: string[];
+}
+export interface JobRecord<T = unknown> {
+    id: string;
+    tool: string;
+    status: JobStatus;
+    startedAt: string;
+    updatedAt: string;
+    progress: JobProgress;
+    result?: T;
+    error?: string;
+}
+export declare function createJob<T>(tool: string, totalFrames?: number): JobRecord<T>;
+export declare function updateJobProgress(jobId: string, patch: Partial<Pick<JobProgress, "framesRendered" | "totalFrames" | "currentBeat">>): void;
+export declare function appendJobLog(jobId: string, line: string): void;
+export declare function completeJob<T>(jobId: string, result: T): void;
+export declare function failJob(jobId: string, error: string): void;
+export declare function getJob(jobId: string): JobRecord | undefined;

package/dist/jobs.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * In-memory job tracking for tools whose real work can outlast an MCP client's own request
+ * timeout (Claude Code's MCP_TOOL_TIMEOUT defaults well under the 40+ minutes a full render
+ * can take on a modest machine). A tool that accepts `async: true` starts its real work
+ * without awaiting it in the request handler, records it here, and returns a jobId
+ * immediately; `job_status` (jobStatus.ts) polls this store.
+ *
+ * Deliberately in-memory, not persisted: a job dies with the server process, same as the
+ * render it's tracking would. This process is a long-lived stdio server for the duration of
+ * one MCP connection, so a promise kicked off here and never awaited by its caller keeps
+ * running on the same event loop while later requests (including job_status polls) are
+ * handled -- that's what makes "return now, finish later" work at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJob = createJob;
+exports.updateJobProgress = updateJobProgress;
+exports.appendJobLog = appendJobLog;
+exports.completeJob = completeJob;
+exports.failJob = failJob;
+exports.getJob = getJob;
+const MAX_LOG_LINES = 20;
+const jobs = new Map();
+function newJobId(tool) {
+    return `${tool}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function createJob(tool, totalFrames = 0) {
+    const now = new Date().toISOString();
+    const record = {
+        id: newJobId(tool),
+        tool,
+        status: "running",
+        startedAt: now,
+        updatedAt: now,
+        progress: { framesRendered: 0, totalFrames, currentBeat: null, logTail: [] },
+    };
+    jobs.set(record.id, record);
+    return record;
+}
+function updateJobProgress(jobId, patch) {
+    const job = jobs.get(jobId);
+    if (!job)
+        return;
+    Object.assign(job.progress, patch);
+    job.updatedAt = new Date().toISOString();
+}
+function appendJobLog(jobId, line) {
+    const job = jobs.get(jobId);
+    if (!job)
+        return;
+    job.progress.logTail = [...job.progress.logTail, line].slice(-MAX_LOG_LINES);
+    job.updatedAt = new Date().toISOString();
+}
+function completeJob(jobId, result) {
+    const job = jobs.get(jobId);
+    if (!job)
+        return;
+    job.status = "done";
+    job.result = result;
+    job.updatedAt = new Date().toISOString();
+}
+function failJob(jobId, error) {
+    const job = jobs.get(jobId);
+    if (!job)
+        return;
+    job.status = "error";
+    job.error = error;
+    job.updatedAt = new Date().toISOString();
+}
+function getJob(jobId) {
+    return jobs.get(jobId);
+}

package/dist/lessonArc.d.ts

@@ -0,0 +1,68 @@
+/** With no caption element in the frame, the bottom of the frame is assumed to hold the captions: the Reels safe zone. */
+export declare const DEFAULT_CAPTION_BAND = 0.22;
+export interface ArcThresholds {
+    /** The first drawn element after this many seconds is a warning. */
+    diagramWarnSeconds: number;
+    /** After this many seconds it is an error. */
+    diagramErrorSeconds: number;
+    /** A run of identical sampled frames longer than this is a warning. */
+    staticSeconds: number;
+}
+export declare const DEFAULT_ARC_THRESHOLDS: ArcThresholds;
+/** A rectangle in frame pixels. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** What one sampled frame contributes to the arc checks. */
+export interface ArcSample {
+    /** Seconds from the start of the lesson. */
+    time: number;
+    beatId: string;
+    /** Share of the unmasked pixels drawn beyond the background, 0 to 1. */
+    drawn: number;
+    /** Share of the unmasked pixels that moved since the previous sample, or null for the first one. */
+    changedFromPrevious: number | null;
+}
+/** What is kept of a frame so the next one can be compared with it. */
+export interface ArcSignature {
+    data: Buffer;
+    mask: Uint8Array;
+    width: number;
+    height: number;
+}
+export interface ArcFinding {
+    beatId: string;
+    check: "diagram-late" | "static-stretch";
+    severity: "warning" | "error";
+    message: string;
+}
+/** Rectangles to ignore in a frame: the captions' own boxes when the page has them, otherwise the bottom band. */
+export declare function captionMaskRects(found: Rect[], frame: {
+    width: number;
+    height: number;
+}): Rect[];
+/** Pure: the share of unmasked pixels that sit further than DRAWN_DISTANCE from the frame's background colour. */
+export declare function drawnShare(data: Buffer, mask: Uint8Array, width: number, height: number): number;
+/** Pure: the share of pixels, unmasked in both frames, that moved by more than MOVED_DISTANCE. */
+export declare function movedShare(a: ArcSignature, b: ArcSignature): number;
+/**
+ * Reads one screenshot into what the arc checks need. `previous` is the signature of the sample before it, so
+ * the caller keeps one frame in memory, not all of them.
+ */
+export declare function measureArcFrame(shot: string, captionRects: Rect[], previous: ArcSignature | null): Promise<{
+    drawn: number;
+    changedFromPrevious: number | null;
+    signature: ArcSignature;
+}>;
+/**
+ * Pure: the findings, given the samples in lesson order and the lesson's length.
+ *
+ * `diagram-late` reads the first sampled frame with anything drawn. `static-stretch` finds each run of sampled
+ * frames that did not change, and estimates how long the hold really lasted: the true edges lie between a held
+ * sample and its changed neighbour, so each is taken as the midpoint, and the lesson's own start and end bound a
+ * run that touches them. A 6 s hold sampled twice is therefore still about 6 s, not the 4 s between its samples.
+ */
+export declare function judgeLessonArc(samples: ArcSample[], lessonSeconds: number, thresholds?: ArcThresholds): ArcFinding[];

package/dist/lessonArc.js

@@ -0,0 +1,188 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ARC_THRESHOLDS = exports.DEFAULT_CAPTION_BAND = void 0;
+exports.captionMaskRects = captionMaskRects;
+exports.drawnShare = drawnShare;
+exports.movedShare = movedShare;
+exports.measureArcFrame = measureArcFrame;
+exports.judgeLessonArc = judgeLessonArc;
+const sharp_1 = __importDefault(require("sharp"));
+/**
+ * The two rules of a lesson's shape (SCRIPT.md, "The arc") that are about the picture, not the words:
+ * the diagram is on screen early, and the viewer never waits long with nothing changing.
+ *
+ * Both are judged from the frames validate_scenes already samples in render mode, so there is no extra
+ * render pass. Each sampled frame is reduced to two numbers, taken with the caption region masked:
+ * how much of it is drawn beyond the background, and how much of it moved since the previous sample.
+ */
+/** Frame width the "has anything been drawn" measure runs at: wide enough that a thin axis line survives. */
+const CONTENT_WIDTH = 540;
+/** Frame width two samples are compared at; averaging away encoder noise is the point of the small size. */
+const SIGNATURE_WIDTH = 270;
+/** A pixel counts as drawn when it differs from the frame's background colour by more than this in any channel. The Void's 5% hairline grid is about 13, so it does not count. */
+const DRAWN_DISTANCE = 40;
+/** Share of the unmasked pixels that must be drawn before a frame counts as having a diagram, about 250 pixels of a 540x960 frame. */
+const DRAWN_MIN_SHARE = 0.0005;
+/** Per-channel change that counts as a moved pixel, and the share of moved pixels below which two samples are identical (frameDiff's numbers). */
+const MOVED_DISTANCE = 12;
+const IDENTICAL_MAX_SHARE = 0.002;
+/** With no caption element in the frame, the bottom of the frame is assumed to hold the captions: the Reels safe zone. */
+exports.DEFAULT_CAPTION_BAND = 0.22;
+exports.DEFAULT_ARC_THRESHOLDS = { diagramWarnSeconds: 15, diagramErrorSeconds: 25, staticSeconds: 8 };
+/** Rectangles to ignore in a frame: the captions' own boxes when the page has them, otherwise the bottom band. */
+function captionMaskRects(found, frame) {
+    if (found.length > 0)
+        return found;
+    const band = Math.round(frame.height * exports.DEFAULT_CAPTION_BAND);
+    return [{ x: 0, y: frame.height - band, width: frame.width, height: band }];
+}
+function maskFor(rects, scale, width, height) {
+    const mask = new Uint8Array(width * height);
+    for (const r of rects) {
+        const x0 = Math.max(0, Math.floor(r.x * scale));
+        const y0 = Math.max(0, Math.floor(r.y * scale));
+        const x1 = Math.min(width, Math.ceil((r.x + r.width) * scale));
+        const y1 = Math.min(height, Math.ceil((r.y + r.height) * scale));
+        for (let y = y0; y < y1; y++)
+            mask.fill(1, y * width + x0, y * width + x1);
+    }
+    return mask;
+}
+/** The background colour of a frame: the most common colour once each channel is rounded to a multiple of 8. */
+function backgroundOf(data, mask, pixels) {
+    const counts = new Map();
+    let best = 0;
+    let bestCount = 0;
+    for (let p = 0; p < pixels; p++) {
+        if (mask[p])
+            continue;
+        const key = ((data[p * 3] >> 3) << 10) | ((data[p * 3 + 1] >> 3) << 5) | (data[p * 3 + 2] >> 3);
+        const n = (counts.get(key) ?? 0) + 1;
+        counts.set(key, n);
+        if (n > bestCount) {
+            best = key;
+            bestCount = n;
+        }
+    }
+    return [((best >> 10) & 31) * 8 + 4, ((best >> 5) & 31) * 8 + 4, (best & 31) * 8 + 4];
+}
+/** Pure: the share of unmasked pixels that sit further than DRAWN_DISTANCE from the frame's background colour. */
+function drawnShare(data, mask, width, height) {
+    const pixels = width * height;
+    const [br, bg, bb] = backgroundOf(data, mask, pixels);
+    let considered = 0;
+    let drawn = 0;
+    for (let p = 0; p < pixels; p++) {
+        if (mask[p])
+            continue;
+        considered++;
+        const i = p * 3;
+        if (Math.max(Math.abs(data[i] - br), Math.abs(data[i + 1] - bg), Math.abs(data[i + 2] - bb)) > DRAWN_DISTANCE)
+            drawn++;
+    }
+    return considered === 0 ? 0 : drawn / considered;
+}
+/** Pure: the share of pixels, unmasked in both frames, that moved by more than MOVED_DISTANCE. */
+function movedShare(a, b) {
+    if (a.width !== b.width || a.height !== b.height)
+        return 1;
+    const pixels = a.width * a.height;
+    let considered = 0;
+    let moved = 0;
+    for (let p = 0; p < pixels; p++) {
+        if (a.mask[p] || b.mask[p])
+            continue;
+        considered++;
+        const i = p * 3;
+        if (Math.abs(a.data[i] - b.data[i]) > MOVED_DISTANCE ||
+            Math.abs(a.data[i + 1] - b.data[i + 1]) > MOVED_DISTANCE ||
+            Math.abs(a.data[i + 2] - b.data[i + 2]) > MOVED_DISTANCE) {
+            moved++;
+        }
+    }
+    return considered === 0 ? 0 : moved / considered;
+}
+/**
+ * Reads one screenshot into what the arc checks need. `previous` is the signature of the sample before it, so
+ * the caller keeps one frame in memory, not all of them.
+ */
+async function measureArcFrame(shot, captionRects, previous) {
+    const meta = await (0, sharp_1.default)(shot).metadata();
+    const frame = { width: meta.width ?? CONTENT_WIDTH, height: meta.height ?? CONTENT_WIDTH };
+    const rects = captionMaskRects(captionRects, frame);
+    const wide = await (0, sharp_1.default)(shot).removeAlpha().resize({ width: CONTENT_WIDTH }).raw().toBuffer({ resolveWithObject: true });
+    const wideMask = maskFor(rects, wide.info.width / frame.width, wide.info.width, wide.info.height);
+    const drawn = drawnShare(wide.data, wideMask, wide.info.width, wide.info.height);
+    const small = await (0, sharp_1.default)(shot).removeAlpha().resize({ width: SIGNATURE_WIDTH }).raw().toBuffer({ resolveWithObject: true });
+    const signature = {
+        data: small.data,
+        mask: maskFor(rects, small.info.width / frame.width, small.info.width, small.info.height),
+        width: small.info.width,
+        height: small.info.height,
+    };
+    return { drawn, changedFromPrevious: previous ? movedShare(previous, signature) : null, signature };
+}
+const seconds = (s) => `${Math.round(s * 10) / 10} s`;
+/**
+ * Pure: the findings, given the samples in lesson order and the lesson's length.
+ *
+ * `diagram-late` reads the first sampled frame with anything drawn. `static-stretch` finds each run of sampled
+ * frames that did not change, and estimates how long the hold really lasted: the true edges lie between a held
+ * sample and its changed neighbour, so each is taken as the midpoint, and the lesson's own start and end bound a
+ * run that touches them. A 6 s hold sampled twice is therefore still about 6 s, not the 4 s between its samples.
+ */
+function judgeLessonArc(samples, lessonSeconds, thresholds = exports.DEFAULT_ARC_THRESHOLDS) {
+    const findings = [];
+    if (samples.length === 0)
+        return findings;
+    const firstDrawn = samples.find((s) => s.drawn >= DRAWN_MIN_SHARE);
+    if (!firstDrawn) {
+        findings.push({
+            beatId: "*",
+            check: "diagram-late",
+            severity: "error",
+            message: `No sampled frame has anything drawn beyond the background and the captions, so the diagram never ` +
+                `appears. The arc wants its first element on screen inside ${thresholds.diagramWarnSeconds} s.`,
+        });
+    }
+    else if (firstDrawn.time > thresholds.diagramWarnSeconds) {
+        const error = firstDrawn.time > thresholds.diagramErrorSeconds;
+        findings.push({
+            beatId: firstDrawn.beatId,
+            check: "diagram-late",
+            severity: error ? "error" : "warning",
+            message: `The first thing drawn beyond the background and the captions is in a frame ${seconds(firstDrawn.time)} into the ` +
+                `lesson. The arc wants the diagram's first element inside ${thresholds.diagramWarnSeconds} s (an error past ` +
+                `${thresholds.diagramErrorSeconds} s): a viewer facing an empty frame that long scrolls on.`,
+        });
+    }
+    let i = 1;
+    while (i < samples.length) {
+        const held = (n) => samples[n].changedFromPrevious !== null && samples[n].changedFromPrevious <= IDENTICAL_MAX_SHARE;
+        if (!held(i)) {
+            i++;
+            continue;
+        }
+        const first = i - 1;
+        let last = i;
+        while (last + 1 < samples.length && held(last + 1))
+            last++;
+        const start = first > 0 ? (samples[first - 1].time + samples[first].time) / 2 : 0;
+        const end = last < samples.length - 1 ? (samples[last].time + samples[last + 1].time) / 2 : lessonSeconds;
+        if (end - start > thresholds.staticSeconds) {
+            findings.push({
+                beatId: samples[first].beatId,
+                check: "static-stretch",
+                severity: "warning",
+                message: `Nothing changes for about ${seconds(end - start)} (from about ${seconds(start)} to ${seconds(end)}; frames sampled ` +
+                    `across it match, captions aside). The arc wants something to move at least every ${thresholds.staticSeconds} s: ` +
+                    `bring the next element in sooner, add a Spark move, or split the beat.`,
+            });
+        }
+        i = last + 1;
+    }
+    return findings;
+}

package/dist/paths.d.ts

@@ -18,3 +18,13 @@ export declare const TEMPLATE_DIR: string;
  * these into a scaffolded project's own docs/ folder (see tools/initProject.ts).
  */
 export declare const DOCS_DIR: string;
+/**
+ * Bundled copy of packages/mcp-server/py/*.py, produced by this package's own build
+ * step (the directory is listed in package.json's "files", no separate copy script
+ * needed since it is already inside the package root) and shipped inside the
+ * published npm package. Same __dirname-relative reasoning as TEMPLATE_DIR and
+ * DOCS_DIR above: resolves to <package root>/py at runtime, whether this package is
+ * installed standalone or run from inside this monorepo. compose_score
+ * (tools/composeScore.ts) spawns packages/mcp-server/py/compose-score.py from here.
+ */
+export declare const PY_DIR: string;

package/dist/paths.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DOCS_DIR = exports.TEMPLATE_DIR = void 0;
+exports.PY_DIR = exports.DOCS_DIR = exports.TEMPLATE_DIR = void 0;
 const path = __importStar(require("node:path"));
 /**
  * Bundled copy of templates/default, produced by scripts/copy-template.mjs at build
@@ -55,3 +55,13 @@ exports.TEMPLATE_DIR = path.join(__dirname, "..", "templates", "default");
  * these into a scaffolded project's own docs/ folder (see tools/initProject.ts).
  */
 exports.DOCS_DIR = path.join(__dirname, "..", "docs");
+/**
+ * Bundled copy of packages/mcp-server/py/*.py, produced by this package's own build
+ * step (the directory is listed in package.json's "files", no separate copy script
+ * needed since it is already inside the package root) and shipped inside the
+ * published npm package. Same __dirname-relative reasoning as TEMPLATE_DIR and
+ * DOCS_DIR above: resolves to <package root>/py at runtime, whether this package is
+ * installed standalone or run from inside this monorepo. compose_score
+ * (tools/composeScore.ts) spawns packages/mcp-server/py/compose-score.py from here.
+ */
+exports.PY_DIR = path.join(__dirname, "..", "py");

package/dist/primitives/registry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The motion primitives catalog.
+ *
+ * scaffold_scene's 10 templates are whole scenes. Below that level there was nothing: a
+ * scene that wants a count-up number, a fanned card stack, or a typewriter line had to have
+ * that animation hand-written from motion.ts's tween/pop/spring primitives every single
+ * time (the "stat" template's own counter is a literal hardcoded "0" for exactly this
+ * reason -- it never got an animation because writing one inline wasn't worth it for one
+ * template). A small, tested, searchable set of these -- catalog_motion_primitives to find
+ * one, add_motion_primitive to drop its real source into the project -- means composing a
+ * scene from proven pieces instead of re-deriving the tween math each time.
+ *
+ * Local and bundled on purpose: a hosted registry/account is not what makes this useful, a
+ * first working batch is. Each entry's `source` is a real, self-contained .tsx component
+ * using only "react", "remotion" and "@openvidstudio/core" -- the same constraint
+ * scaffold_scene's own templates follow -- so it drops into any scene unmodified.
+ */
+export interface MotionPrimitive {
+    /** kebab-case id, e.g. "count-up-stat". Stable: add_motion_primitive looks up by this. */
+    name: string;
+    title: string;
+    description: string;
+    /** Extra terms a query might use that the title/description don't already contain. */
+    keywords: string[];
+    /** The component's exported name inside `source`. */
+    componentName: string;
+    /** Self-contained .tsx source, ready to write to disk as-is. */
+    source: string;
+}
+export declare const MOTION_PRIMITIVES: MotionPrimitive[];
+export interface PrimitiveMatch {
+    primitive: MotionPrimitive;
+    score: number;
+}
+/**
+ * Ranks the catalog against a free-text query: every query token found in the primitive's
+ * name/title/description/keywords adds a point, an exact or prefix match on `name` adds a
+ * strong bonus (so searching the id itself always wins), and an empty query returns every
+ * primitive in catalog order rather than nothing -- mirroring find_music_bed's "no query
+ * means browse everything" behaviour.
+ */
+export declare function searchMotionPrimitives(query: string | undefined, limit?: number): PrimitiveMatch[];
+export declare function findMotionPrimitive(name: string): MotionPrimitive | undefined;