@openvidstudio/mcp-server 0.1.0

package/dist/scenes/templates.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Scene templates.
+ *
+ * scaffold_scene used to emit a TODO comment and an empty fragment for dom-demo
+ * beats, which meant the calling agent had to invent a scene from primitives for
+ * every beat in the video. Building one real 20 beat video that way took over two
+ * thousand lines of hand written React. Agents edit a working thing far better than
+ * they compose one from nothing, so every template here renders on its own with no
+ * edits, and the agent's job becomes changing content rather than building structure.
+ *
+ * Templates only use what `@openvidstudio/core` exports, because that is all a
+ * scaffolded project has.
+ *
+ * Two things encoded here that are easy to get wrong and expensive to discover:
+ *
+ * 1. Camera scale. The visible area is the stage divided by the camera scale, so at
+ *    1.4 only 1371x771 of the 1920x1080 stage is on screen. Panels built at stage
+ *    size get cropped at the frame edge with no warning. Constructed scenes
+ *    therefore use a gentle push (1.04 to 1.15) and keep content inside a safe box.
+ *    STYLE.md's 120-250% rule is about not showing flat full screen screenshots,
+ *    which is a capture-beat concern, and capture templates do use it.
+ *
+ * 2. Real captures get their frame size from the file on disk, not from a guess.
+ */
+export type SceneKind = "real-screenshot" | "real-recording" | "dom-demo" | "higgsfield-clip";
+export type TemplateName = "browser-capture" | "recording" | "terminal" | "split-panel" | "checklist" | "stat" | "code" | "comparison" | "cta" | "title";
+export interface SceneContext {
+    beatId: string;
+    componentName: string;
+    /** The beat's `visual.description`, used as on-screen copy so the first render says something. */
+    description: string;
+    /** The beat's narration line, used for the caption. */
+    vo: string;
+    durationFrames: number;
+    /** For capture templates. */
+    url?: string;
+    captureWidth?: number;
+    captureHeight?: number;
+}
+/** Pick a template from the beat's capture method and what its description talks about. */
+export declare function pickTemplate(kind: SceneKind, description: string): TemplateName;
+export declare function renderTemplate(template: TemplateName, ctx: SceneContext, kind: SceneKind): string;

package/dist/scenes/templates.js

@@ -0,0 +1,468 @@
+"use strict";
+/**
+ * Scene templates.
+ *
+ * scaffold_scene used to emit a TODO comment and an empty fragment for dom-demo
+ * beats, which meant the calling agent had to invent a scene from primitives for
+ * every beat in the video. Building one real 20 beat video that way took over two
+ * thousand lines of hand written React. Agents edit a working thing far better than
+ * they compose one from nothing, so every template here renders on its own with no
+ * edits, and the agent's job becomes changing content rather than building structure.
+ *
+ * Templates only use what `@openvidstudio/core` exports, because that is all a
+ * scaffolded project has.
+ *
+ * Two things encoded here that are easy to get wrong and expensive to discover:
+ *
+ * 1. Camera scale. The visible area is the stage divided by the camera scale, so at
+ *    1.4 only 1371x771 of the 1920x1080 stage is on screen. Panels built at stage
+ *    size get cropped at the frame edge with no warning. Constructed scenes
+ *    therefore use a gentle push (1.04 to 1.15) and keep content inside a safe box.
+ *    STYLE.md's 120-250% rule is about not showing flat full screen screenshots,
+ *    which is a capture-beat concern, and capture templates do use it.
+ *
+ * 2. Real captures get their frame size from the file on disk, not from a guess.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickTemplate = pickTemplate;
+exports.renderTemplate = renderTemplate;
+/** Content wider or taller than this gets cropped once the camera pushes in. */
+const SAFE_W = 1560;
+const HEADER = (beatId, template, direction = "") => `// Scene for beat "${beatId}", generated by scaffold_scene from the "${template}" template.
+//
+// This renders as-is. Edit the copy and the timings; the structure, camera and
+// safe-area sizing are already correct.${direction ? `
+//
+// The beat asks for: ${direction.replace(/\s+/g, " ").slice(0, 240)}` : ""}`;
+/**
+ * Heading text.
+ *
+ * Deliberately not `visual.description`. That field is a stage direction written for
+ * whoever builds the scene ("two labelled panels built from this project's tokens"),
+ * and putting it on screen reads as instructions leaking into the video. The beat id
+ * is short, already names the beat's subject, and title-cases into a usable heading.
+ */
+function headline(ctx) {
+    const words = ctx.beatId.replace(/[-_]+/g, " ").trim().split(/\s+/);
+    const text = words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+    return esc(text || "Untitled beat");
+}
+/** First sentence of the narration, for supporting copy under a heading. */
+function leadLine(ctx, max = 150) {
+    const first = (ctx.vo || "").split(/(?<=[.!?])\s/)[0]?.trim() ?? "";
+    const text = first || ctx.description || "";
+    return esc(text.length > max ? `${text.slice(0, max - 3).trimEnd()}...` : text);
+}
+function esc(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, " ");
+}
+/** Caption timing: in after the opening settle, out before the cut. */
+function captionWindow(frames) {
+    return { at: Math.round(frames * 0.18), out: Math.max(24, Math.round(frames * 0.82)) };
+}
+/* ------------------------------------------------------------------ capture */
+function browserCapture(ctx) {
+    const w = ctx.captureWidth ?? 1440;
+    const h = ctx.captureHeight ?? 900;
+    // BrowserFrame adds a chrome bar above the page.
+    const frameW = Math.min(1600, w + 80);
+    const frameH = Math.round(frameW * (h / w)) + 56;
+    const mid = Math.round(ctx.durationFrames * 0.55);
+    const cap = captionWindow(ctx.durationFrames);
+    return `${HEADER(ctx.beatId, "browser-capture", ctx.description)}
+//
+// Frame size comes from the real capture on disk (${w}x${h}), not a guess, so the
+// page is not letterboxed or stretched. Camera sits inside the UI and keeps moving.
+
+import React from "react";
+import { Img, staticFile } from "remotion";
+import { CinematicScene, Layer, BrowserFrame, Caption, E } from "@openvidstudio/core";
+
+const FRAME_W = ${frameW};
+const FRAME_H = ${frameH};
+const LEFT = (1920 - FRAME_W) / 2;
+const TOP = (1080 - FRAME_H) / 2;
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+      camera={[
+        { frame: 0, x: 960, y: 470, scale: 1.35, rotZ: -0.5 },
+        { frame: ${mid}, x: 960, y: 560, scale: 1.62, rotZ: 0.4, easing: E.cinematic },
+        { frame: ${ctx.durationFrames}, x: 985, y: 620, scale: 1.78, rotZ: 0.8, easing: E.drift },
+      ]}
+      overlay={<Caption text="${esc(ctx.vo).slice(0, 70)}" at={${cap.at}} out={${cap.out}} fontSize={30} />}
+    >
+      <Layer depth={0}>
+        <div style={{ position: "absolute", left: LEFT, top: TOP }}>
+          <BrowserFrame url="${esc(ctx.url ?? "localhost:3000")}" width={FRAME_W} height={FRAME_H}>
+            <Img
+              src={staticFile("images/${ctx.beatId}.png")}
+              style={{ width: "100%", height: "100%", objectFit: "cover", objectPosition: "top" }}
+            />
+          </BrowserFrame>
+        </div>
+      </Layer>
+    </CinematicScene>
+  );
+};
+`;
+}
+function recording(ctx, higgsfield) {
+    const note = higgsfield
+        ? `// The asset comes from import_higgsfield_clip. Composited as a bare Layer and
+// OffthreadVideo, never a BrowserFrame: an AI generated clip must not carry the
+// visual signature of real captured UI (STYLE.md's provenance rule).`
+        : `// Composited as a bare Layer and OffthreadVideo, per STYLE.md's convention for
+// recordings. The camera moves over the recording exactly as it would over a still.`;
+    const cap = captionWindow(ctx.durationFrames);
+    return `${HEADER(ctx.beatId, "recording", ctx.description)}
+//
+${note}
+
+import React from "react";
+import { OffthreadVideo, staticFile } from "remotion";
+import { CinematicScene, Layer, Caption, E } from "@openvidstudio/core";
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+      camera={[
+        { frame: 0, x: 960, y: 520, scale: 1.28, rotZ: 0.4 },
+        { frame: ${ctx.durationFrames}, x: 960, y: 560, scale: 1.5, rotZ: -0.3, easing: E.drift },
+      ]}
+      overlay={<Caption text="${esc(ctx.vo).slice(0, 70)}" at={${cap.at}} out={${cap.out}} fontSize={30} />}
+    >
+      <Layer depth={0}>
+        <OffthreadVideo
+          src={staticFile("video/${ctx.beatId}.mp4")}
+          style={{ width: "100%", height: "100%", objectFit: "cover" }}
+        />
+      </Layer>
+    </CinematicScene>
+  );
+};
+`;
+}
+/* ------------------------------------------------------------- constructed */
+const SAFE_WRAP = (inner) => `      <Layer depth={0}>
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            padding: "0 ${(1920 - SAFE_W) / 2}px",
+          }}
+        >
+${inner}
+        </div>
+      </Layer>`;
+const GENTLE_CAMERA = (frames, a = 1.04, b = 1.15) => `      camera={[
+        { frame: 0, x: 960, y: 540, scale: ${a}, rotZ: -0.4 },
+        { frame: ${frames}, x: 960, y: 548, scale: ${b}, rotZ: 0.35, easing: E.drift },
+      ]}`;
+function terminal(ctx) {
+    return `${HEADER(ctx.beatId, "terminal", ctx.description)}
+
+import React from "react";
+import { CinematicScene, Layer, TerminalReplay, color, E } from "@openvidstudio/core";
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+${GENTLE_CAMERA(ctx.durationFrames, 1.05, 1.16)}
+    >
+${SAFE_WRAP(`          <TerminalReplay
+            title="Project"
+            width={1400}
+            fontSize={27}
+            cps={24}
+            steps={[
+              { type: "cmd", text: "echo replace me with the real command" },
+              {
+                type: "out",
+                lines: [
+                  { text: "replace with the real output", color: color.textSecondary },
+                  { text: "done", color: color.success, glow: true },
+                ],
+              },
+            ]}
+          />`)}
+    </CinematicScene>
+  );
+};
+`;
+}
+function splitPanel(ctx) {
+    return `${HEADER(ctx.beatId, "split-panel", ctx.description)}
+
+import React from "react";
+import { CinematicScene, Layer, color, font, radius, panelShadow, E } from "@openvidstudio/core";
+
+const MONO = \`"\${font.mono}", ui-monospace, monospace\`;
+const UI = \`"\${font.ui}", system-ui, sans-serif\`;
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+${GENTLE_CAMERA(ctx.durationFrames)}
+    >
+${SAFE_WRAP(`          <div style={{ display: "flex", alignItems: "center", gap: 72, width: "100%" }}>
+            <div style={{ display: "flex", flexDirection: "column", gap: 20, flex: "0 0 560px" }}>
+              <span style={{ fontFamily: MONO, fontSize: 20, letterSpacing: 4, textTransform: "uppercase", color: color.accent }}>
+                ${esc(ctx.beatId.replace(/[-_]/g, " "))}
+              </span>
+              <h2 style={{ margin: 0, fontFamily: MONO, fontSize: 60, fontWeight: 700, lineHeight: 1.1, color: color.textPrimary }}>
+                ${headline(ctx)}
+              </h2>
+              <p style={{ margin: 0, fontFamily: UI, fontSize: 26, lineHeight: 1.5, color: color.textSecondary }}>
+                ${leadLine(ctx, 150)}
+              </p>
+            </div>
+            <div
+              style={{
+                flex: 1,
+                minHeight: 460,
+                borderRadius: radius.window,
+                background: "#10141D",
+                border: \`1px solid \${color.panelBorder}\`,
+                boxShadow: panelShadow(true),
+                padding: 30,
+                fontFamily: UI,
+                fontSize: 24,
+                color: color.textSecondary,
+              }}
+            >
+              ${leadLine(ctx, 180)}
+            </div>
+          </div>`)}
+    </CinematicScene>
+  );
+};
+`;
+}
+function checklist(ctx) {
+    const step = Math.max(20, Math.floor(ctx.durationFrames / 6));
+    return `${HEADER(ctx.beatId, "checklist", ctx.description)}
+
+import React from "react";
+import { CinematicScene, Layer, ChecklistPanel, E } from "@openvidstudio/core";
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+${GENTLE_CAMERA(ctx.durationFrames)}
+    >
+${SAFE_WRAP(`          <ChecklistPanel
+            title="${headline(ctx)}"
+            width={860}
+            fontSize={27}
+            items={[
+              { label: "First item", flipAt: ${step} },
+              { label: "Second item", flipAt: ${step * 2} },
+              { label: "Third item", flipAt: ${step * 3} },
+              { label: "Fourth item", flipAt: ${step * 4} },
+            ]}
+          />`)}
+    </CinematicScene>
+  );
+};
+`;
+}
+function stat(ctx) {
+    return `${HEADER(ctx.beatId, "stat", ctx.description)}
+
+import React from "react";
+import { CinematicScene, Layer, color, font, glow, E } from "@openvidstudio/core";
+
+const MONO = \`"\${font.mono}", ui-monospace, monospace\`;
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+${GENTLE_CAMERA(ctx.durationFrames, 1.06, 1.18)}
+    >
+${SAFE_WRAP(`          <div style={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 24 }}>
+            <span style={{ fontFamily: MONO, fontSize: 190, fontWeight: 700, lineHeight: 1, color: color.accent, ...glow(color.accent, 0.8) }}>
+              0
+            </span>
+            <span style={{ fontFamily: MONO, fontSize: 34, color: color.textSecondary, textAlign: "center", maxWidth: 900 }}>
+              ${headline(ctx)}
+            </span>
+          </div>`)}
+    </CinematicScene>
+  );
+};
+`;
+}
+function code(ctx) {
+    return `${HEADER(ctx.beatId, "code", ctx.description)}
+
+import React from "react";
+import { CinematicScene, Layer, CodePanel, E } from "@openvidstudio/core";
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+${GENTLE_CAMERA(ctx.durationFrames)}
+    >
+${SAFE_WRAP(`          <CodePanel
+            title="${esc(ctx.beatId)}"
+            width={1000}
+            height={560}
+            fontSize={24}
+            highlight={[1]}
+            lines={[
+              [{ t: "{", c: "plain" }],
+              [{ t: "  \\"replace\\"", c: "str" }, { t: ": ", c: "plain" }, { t: "\\"me\\"", c: "str" }],
+              [{ t: "}", c: "plain" }],
+            ]}
+          />`)}
+    </CinematicScene>
+  );
+};
+`;
+}
+function comparison(ctx) {
+    return `${HEADER(ctx.beatId, "comparison", ctx.description)}
+
+import React from "react";
+import { CinematicScene, Layer, color, font, radius, panelShadow, E } from "@openvidstudio/core";
+
+const MONO = \`"\${font.mono}", ui-monospace, monospace\`;
+const UI = \`"\${font.ui}", system-ui, sans-serif\`;
+
+const Side: React.FC<{ tag: string; title: string; accent: string; body: string }> = ({
+  tag, title, accent, body,
+}) => (
+  <div
+    style={{
+      flex: 1,
+      borderRadius: radius.window,
+      background: "#10141D",
+      border: \`1px solid \${accent}55\`,
+      boxShadow: panelShadow(true),
+      padding: 34,
+      display: "flex",
+      flexDirection: "column",
+      gap: 16,
+    }}
+  >
+    <span style={{ fontFamily: MONO, fontSize: 20, color: accent }}>{tag}</span>
+    <span style={{ fontFamily: MONO, fontSize: 34, color: color.textPrimary }}>{title}</span>
+    <span style={{ fontFamily: UI, fontSize: 24, lineHeight: 1.45, color: color.textSecondary }}>{body}</span>
+  </div>
+);
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+${GENTLE_CAMERA(ctx.durationFrames)}
+    >
+${SAFE_WRAP(`          <div style={{ display: "flex", gap: 44, width: "100%", alignItems: "stretch" }}>
+            <Side tag="option one" title="Replace me" accent={color.danger} body="Replace with the first option" />
+            <Side tag="option two" title="Replace me" accent={color.accent} body="${leadLine(ctx, 110)}" />
+          </div>`)}
+    </CinematicScene>
+  );
+};
+`;
+}
+function cta(ctx) {
+    return `${HEADER(ctx.beatId, "cta", ctx.description)}
+//
+// RepoCta ships without a star action by default, per OVERVIEW.md.
+
+import React from "react";
+import { RepoCta } from "@openvidstudio/core";
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <RepoCta
+      owner="your-org"
+      name="your-repo"
+      description="${leadLine(ctx, 110)}"
+      chips={["open source", "MIT"]}
+      titleText="${headline(ctx)}"
+      durationInFrames={${ctx.durationFrames}}
+    />
+  );
+};
+`;
+}
+function title(ctx) {
+    return `${HEADER(ctx.beatId, "title", ctx.description)}
+
+import React from "react";
+import { CinematicScene, Layer, color, font, E } from "@openvidstudio/core";
+
+const MONO = \`"\${font.mono}", ui-monospace, monospace\`;
+const UI = \`"\${font.ui}", system-ui, sans-serif\`;
+
+export const ${ctx.componentName}: React.FC = () => {
+  return (
+    <CinematicScene
+${GENTLE_CAMERA(ctx.durationFrames, 1.05, 1.17)}
+    >
+${SAFE_WRAP(`          <div style={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 28, textAlign: "center" }}>
+            <h2 style={{ margin: 0, fontFamily: MONO, fontSize: 72, fontWeight: 700, lineHeight: 1.1, color: color.textPrimary, maxWidth: 1300 }}>
+              ${headline(ctx)}
+            </h2>
+            <p style={{ margin: 0, fontFamily: UI, fontSize: 30, lineHeight: 1.5, color: color.textSecondary, maxWidth: 1000 }}>
+              ${leadLine(ctx, 160)}
+            </p>
+          </div>`)}
+    </CinematicScene>
+  );
+};
+`;
+}
+/* -------------------------------------------------------------- selection */
+const KEYWORDS = [
+    [/\bterminal|command|shell|cli\b|npm |npx |install|clone|build\b/i, "terminal"],
+    [/\bchecklist|requirement|prereq|steps?\b|tick|verify\b/i, "checklist"],
+    [/\bconfig|json|code panel|snippet|mcp\.json|package\.json\b/i, "code"],
+    [/\bversus|vs\.?\b|compare|comparison|two (options|panels|tiers)|either\b/i, "comparison"],
+    [/\bcta|call to action|repo|github|star\b/i, "cta"],
+    [/\bstat|number|percent|count|figure|\$\d/i, "stat"],
+    [/\bpanel|split|beside|alongside|left|right\b/i, "split-panel"],
+];
+/** Pick a template from the beat's capture method and what its description talks about. */
+function pickTemplate(kind, description) {
+    if (kind === "real-screenshot")
+        return "browser-capture";
+    if (kind === "real-recording" || kind === "higgsfield-clip")
+        return "recording";
+    for (const [re, name] of KEYWORDS) {
+        if (re.test(description))
+            return name;
+    }
+    return "title";
+}
+function renderTemplate(template, ctx, kind) {
+    switch (template) {
+        case "browser-capture":
+            return browserCapture(ctx);
+        case "recording":
+            return recording(ctx, kind === "higgsfield-clip");
+        case "terminal":
+            return terminal(ctx);
+        case "split-panel":
+            return splitPanel(ctx);
+        case "checklist":
+            return checklist(ctx);
+        case "stat":
+            return stat(ctx);
+        case "code":
+            return code(ctx);
+        case "comparison":
+            return comparison(ctx);
+        case "cta":
+            return cta(ctx);
+        case "title":
+        default:
+            return title(ctx);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OpenvidstudioConfig } from "./config";
+export declare const SERVER_NAME = "openvidstudio";
+export declare const SERVER_VERSION = "0.1.0";
+/**
+ * Assembly only, mirrors pepiros/mcp/server.ts's shape: transport lives in the entry
+ * point (stdio.ts), not here, so the same server instance could later be served over a
+ * different transport without touching the tool layer.
+ *
+ * Unlike pepiros, there is no auth/token layer -- this is a local process a dev's
+ * coding agent spawns directly (like Playwright MCP or context7's MCP), operating on
+ * the local filesystem and local processes (remotion CLI, ffmpeg). `config` (loaded by
+ * stdio.ts from process.cwd() at startup) is threaded through to registerTools, whose
+ * only use of it is gating import_higgsfield_clip's registration on hasHiggsfield.
+ */
+export declare function createMcpServer(config?: OpenvidstudioConfig): McpServer;

package/dist/server.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_VERSION = exports.SERVER_NAME = void 0;
+exports.createMcpServer = createMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const tools_1 = require("./tools");
+exports.SERVER_NAME = "openvidstudio";
+exports.SERVER_VERSION = "0.1.0";
+/**
+ * Assembly only, mirrors pepiros/mcp/server.ts's shape: transport lives in the entry
+ * point (stdio.ts), not here, so the same server instance could later be served over a
+ * different transport without touching the tool layer.
+ *
+ * Unlike pepiros, there is no auth/token layer -- this is a local process a dev's
+ * coding agent spawns directly (like Playwright MCP or context7's MCP), operating on
+ * the local filesystem and local processes (remotion CLI, ffmpeg). `config` (loaded by
+ * stdio.ts from process.cwd() at startup) is threaded through to registerTools, whose
+ * only use of it is gating import_higgsfield_clip's registration on hasHiggsfield.
+ */
+function createMcpServer(config) {
+    const server = new mcp_js_1.McpServer({ name: exports.SERVER_NAME, version: exports.SERVER_VERSION }, {
+        instructions: [
+            "openvidstudio exposes the mechanical half of the video pipeline: project scaffolding, beats.json " +
+                "validation and writes, scene stubs, composition stitching, rendering, and QC frame extraction.",
+            "",
+            "This server does not call an LLM and does not draft content. Reasoning (PLANNING.md's intake " +
+                "questions, beat wording, scene JSX content, and the mandatory human-approval gate before " +
+                "write_beats_file) stays with you, the calling agent.",
+            "",
+            "Read PLANNING.md and PIPELINE.md before drafting a beats.json: in this monorepo that's " +
+                "packages/docs/; in a scaffolded project it's the project's own docs/ directory, which " +
+                "init_project copies in from this package's bundled docs.",
+        ].join("\n"),
+    });
+    (0, tools_1.registerTools)(server, config);
+    return server;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const server_1 = require("./server");
+const config_1 = require("./config");
+/**
+ * stdio entry point -- `openvidstudio-mcp` once installed, or wired directly into an
+ * agent's MCP config as a command.
+ *
+ * Nothing may be written to stdout except protocol frames: stdout IS the transport.
+ * Any diagnostic goes to stderr, or it corrupts the JSON-RPC stream and the client
+ * disconnects with a parse error. This is the single most important constraint in this
+ * package -- violate it anywhere (a stray console.log, a library that logs to stdout
+ * by default) and the whole server breaks silently from the calling agent's perspective.
+ *
+ * Loads openvidstudio.config.json from process.cwd() (the calling agent's project root,
+ * same default resolveProjectRoot uses everywhere else in this package) once, here, at
+ * startup: this is what gives registerTools' hasHiggsfield gate something to read.
+ * loadConfig fills in defaults for a missing file, so an un-initialized project still
+ * starts cleanly with import_higgsfield_clip simply absent.
+ */
+async function main() {
+    const config = (0, config_1.loadConfig)(process.cwd());
+    const server = (0, server_1.createMcpServer)(config);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("openvidstudio-mcp: connected over stdio\n");
+}
+main().catch((err) => {
+    process.stderr.write(`openvidstudio-mcp: fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
+    process.exit(1);
+});

package/dist/tools/captureScreenRecording.d.ts

@@ -0,0 +1,28 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Interaction, type Viewport } from "../capture";
+export interface CaptureScreenRecordingInput {
+    projectRoot?: string;
+    beatId: string;
+    url: string;
+    viewport?: Viewport;
+    interactions?: Interaction[];
+    outPath?: string;
+}
+export interface CaptureScreenRecordingResult {
+    outPath: string;
+    width: number;
+    height: number;
+    zoom: number;
+    durationMs?: number;
+}
+/**
+ * Pure argv builder, unit-testable without spawning ffmpeg. Remotion's
+ * OffthreadVideo needs a seekable format, so Playwright's webm output gets
+ * transcoded to mp4 (h264/yuv420p, +faststart) -- same spawn/argv-array
+ * discipline as render_video/qc_extract_frames.
+ */
+export declare function buildFfmpegTranscodeArgs(inputPath: string, outputPath: string): string[];
+/** Pure argv builder for the best-effort ffprobe duration lookup. */
+export declare function buildFfprobeDurationArgs(filePath: string): string[];
+export declare function runCaptureScreenRecording(input: CaptureScreenRecordingInput): Promise<CaptureScreenRecordingResult>;
+export declare function registerCaptureScreenRecording(server: McpServer): void;