@openvidstudio/mcp-server 1.3.1 → 1.4.0

package/dist/canvasValidate.d.ts

@@ -0,0 +1,76 @@
+import type { SceneFinding } from "./tools/validateScenes";
+/**
+ * validate_canvas_explainer: what validate_scenes does for a Remotion composition, for a canvas explainer. There is
+ * no composition to inspect, so the file is loaded in headless Chromium and driven through window.seek(t). The
+ * checks are the rules that make phone viewing work: a frame is a pure function of t, text is big enough, nothing
+ * sits under the platform's interface, the picture is not blank or still for long, the sound is not a pile-up, and
+ * nothing calls Math.random. Findings have the shape validate_scenes returns (beatId, scene, severity, check, message).
+ */
+/** The text minimums at the reference canvas (720 on the shorter side), in px. Headlines 44, labels 28, key numbers 64. */
+export declare const TEXT_MINIMUMS: {
+    readonly headline: 44;
+    readonly label: 28;
+    readonly number: 64;
+};
+/** The safe areas of a tall canvas: the top share and the bottom share kept clear. */
+export declare const SAFE_TOP = 0.14;
+export declare const SAFE_BOTTOM = 0.22;
+/** More sources than this playing at once is a pile-up. */
+export declare const MAX_SIMULTANEOUS_SOUNDS = 3;
+export interface CanvasValidateInput {
+    projectRoot?: string;
+    htmlPath: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    /** A project video: its beats become window.BEATS and its captions are drawn, as in the render. */
+    videoName?: string;
+    /** Also render the score and judge the sound. Default true. */
+    audio?: boolean;
+    /** Pixels at the reference size are scaled by min(width, height) / 720 unless this says otherwise. */
+    textScale?: number;
+    diagramWarnSeconds?: number;
+    diagramErrorSeconds?: number;
+    staticSeconds?: number;
+}
+export interface CanvasValidateResult {
+    /** False when any finding is an error. */
+    ok: boolean;
+    findings: SceneFinding[];
+    durationSeconds: number;
+    width: number;
+    height: number;
+    /** The scale the text minimums were multiplied by. */
+    textScale: number;
+    framesSampled: number;
+    /** Smallest non-caption text drawn, in px at the canvas size, or null when no text was drawn. */
+    minTextSize: number | null;
+    sound: {
+        maxSimultaneous: number;
+        peakDb: number | null;
+        sources: number;
+    } | null;
+    elapsedMs: number;
+}
+interface TextRecord {
+    text: string;
+    size: number;
+    x: number;
+    y: number;
+    caption: boolean;
+}
+interface SourceRecord {
+    start: number;
+    stop: number | null;
+    duration: number | null;
+    bufferSeconds: number | null;
+    loop: boolean;
+}
+/** Pure: is this text a figure (a number with at most a unit), which is held to the key number minimum when it is drawn big. */
+export declare function isKeyNumber(text: string): boolean;
+/** Pure: the most sources playing at once. A source with no stop and no length plays to `end`. */
+export declare function maxSimultaneous(sources: SourceRecord[], end: number): number;
+/** Pure: the text findings for the texts drawn in the sampled frames. */
+export declare function judgeText(texts: TextRecord[], width: number, height: number, scale: number, scene: string): SceneFinding[];
+export declare function validateCanvasExplainer(input: CanvasValidateInput): Promise<CanvasValidateResult>;
+export {};

package/dist/canvasValidate.js

@@ -0,0 +1,263 @@
+"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.MAX_SIMULTANEOUS_SOUNDS = exports.SAFE_BOTTOM = exports.SAFE_TOP = exports.TEXT_MINIMUMS = void 0;
+exports.isKeyNumber = isKeyNumber;
+exports.maxSimultaneous = maxSimultaneous;
+exports.judgeText = judgeText;
+exports.validateCanvasExplainer = validateCanvasExplainer;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const capture_1 = require("@openvidstudio/capture");
+const canvasExplainer_1 = require("./canvasExplainer");
+const lessonArc_1 = require("./lessonArc");
+const util_1 = require("./util");
+/**
+ * validate_canvas_explainer: what validate_scenes does for a Remotion composition, for a canvas explainer. There is
+ * no composition to inspect, so the file is loaded in headless Chromium and driven through window.seek(t). The
+ * checks are the rules that make phone viewing work: a frame is a pure function of t, text is big enough, nothing
+ * sits under the platform's interface, the picture is not blank or still for long, the sound is not a pile-up, and
+ * nothing calls Math.random. Findings have the shape validate_scenes returns (beatId, scene, severity, check, message).
+ */
+/** The text minimums at the reference canvas (720 on the shorter side), in px. Headlines 44, labels 28, key numbers 64. */
+exports.TEXT_MINIMUMS = { headline: 44, label: 28, number: 64 };
+/** Text this much bigger than the label minimum was meant to be a headline or a number, and is held to its minimum. */
+const DISPLAY_FACTOR = 1.2;
+/** The safe areas of a tall canvas: the top share and the bottom share kept clear. */
+exports.SAFE_TOP = 0.14;
+exports.SAFE_BOTTOM = 0.22;
+/** More sources than this playing at once is a pile-up. */
+exports.MAX_SIMULTANEOUS_SOUNDS = 3;
+/** The shortest gap between frames sampled for the arc checks, and the most frames sampled. */
+const MIN_SAMPLE_GAP_SECONDS = 0.5;
+const MAX_SAMPLES = 120;
+const NUMERIC = /^\s*[-+−~]?\s*[$₹€£]?\s*\d[\d.,\s]*\s*(%|[a-zA-Zµ°/²³^]{0,6})\s*$/;
+/** Pure: is this text a figure (a number with at most a unit), which is held to the key number minimum when it is drawn big. */
+function isKeyNumber(text) {
+    return NUMERIC.test(text);
+}
+/** Pure: the most sources playing at once. A source with no stop and no length plays to `end`. */
+function maxSimultaneous(sources, end) {
+    const events = [];
+    for (const s of sources) {
+        let stop;
+        if (s.stop !== null)
+            stop = s.duration !== null ? Math.min(s.stop, s.start + s.duration) : s.stop;
+        else if (s.duration !== null)
+            stop = s.start + s.duration;
+        else if (s.bufferSeconds !== null && !s.loop)
+            stop = s.start + s.bufferSeconds;
+        else
+            stop = end;
+        if (stop > s.start) {
+            events.push([s.start, 1]);
+            events.push([stop, -1]);
+        }
+    }
+    // At the same instant, what ends counts before what begins.
+    events.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    let now = 0;
+    let max = 0;
+    for (const [, delta] of events) {
+        now += delta;
+        max = Math.max(max, now);
+    }
+    return max;
+}
+/** Pure: the text findings for the texts drawn in the sampled frames. */
+function judgeText(texts, width, height, scale, scene) {
+    // One finding per distinct text and rule, the worst one kept.
+    const found = new Map();
+    const add = (key, severity, check, message) => {
+        const have = found.get(key);
+        if (have && (have.severity === "error" || severity === "warning"))
+            return;
+        found.set(key, { beatId: "*", scene, severity, message, source: "render", check });
+    };
+    const label = exports.TEXT_MINIMUMS.label * scale;
+    const headline = exports.TEXT_MINIMUMS.headline * scale;
+    const number = exports.TEXT_MINIMUMS.number * scale;
+    const portrait = height > width;
+    const shown = (t) => `"${t.length > 36 ? `${t.slice(0, 36)}...` : t}"`;
+    for (const t of texts) {
+        if (t.caption || t.text.trim() === "")
+            continue;
+        const size = Math.round(t.size * 10) / 10;
+        const display = t.size >= label * DISPLAY_FACTOR;
+        const figure = isKeyNumber(t.text);
+        if (display && figure && t.size < number) {
+            add(`size:${t.text}`, t.size < number / 2 ? "error" : "warning", "text-size", `The figure ${shown(t.text)} is drawn at ${size}px, under the ${Math.round(number)}px a key number needs at this canvas size (${width}x${height}).`);
+        }
+        else if (display && !figure && t.size < headline) {
+            add(`size:${t.text}`, t.size < headline / 2 ? "error" : "warning", "text-size", `The headline ${shown(t.text)} is drawn at ${size}px, under the ${Math.round(headline)}px a headline needs at this canvas size (${width}x${height}).`);
+        }
+        else if (!display && t.size < label) {
+            add(`size:${t.text}`, t.size < label / 2 ? "error" : "warning", "text-size", `The label ${shown(t.text)} is drawn at ${size}px, under the ${Math.round(label)}px a label needs at this canvas size (${width}x${height}). On a phone it will not be readable.`);
+        }
+        if (portrait) {
+            const top = t.y - t.size * 0.8;
+            const bottom = t.y + t.size * 0.2;
+            if (top < height * exports.SAFE_TOP) {
+                add(`safe:${t.text}`, "warning", "safe-area", `The text ${shown(t.text)} is drawn at y=${Math.round(t.y)}, inside the top ${Math.round(exports.SAFE_TOP * 100)}% of the canvas that the platform's interface covers. Only captions belong there.`);
+            }
+            else if (bottom > height * (1 - exports.SAFE_BOTTOM)) {
+                add(`safe:${t.text}`, "warning", "safe-area", `The text ${shown(t.text)} is drawn at y=${Math.round(t.y)}, inside the bottom ${Math.round(exports.SAFE_BOTTOM * 100)}% of the canvas that captions and the platform's interface use. Only captions belong there.`);
+            }
+        }
+    }
+    return Array.from(found.values());
+}
+const hash = (b) => crypto.createHash("sha256").update(b).digest("hex");
+async function validateCanvasExplainer(input) {
+    const started = Date.now();
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const htmlPath = path.resolve(projectRoot, input.htmlPath);
+    if (!fs.existsSync(htmlPath))
+        throw new Error(`No explainer at ${htmlPath}.`);
+    const width = input.width ?? canvasExplainer_1.DEFAULT_CANVAS_WIDTH;
+    const height = input.height ?? canvasExplainer_1.DEFAULT_CANVAS_HEIGHT;
+    const fps = input.fps ?? canvasExplainer_1.DEFAULT_CANVAS_FPS;
+    const scale = input.textScale ?? Math.min(width, height) / 720;
+    const scene = path.basename(htmlPath);
+    const audioOn = input.audio !== false;
+    const project = input.videoName !== undefined ? (0, canvasExplainer_1.readCanvasProject)(projectRoot, input.videoName) : null;
+    const voiceover = project !== null && project.narration === "voice";
+    const thresholds = {
+        diagramWarnSeconds: input.diagramWarnSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.diagramWarnSeconds,
+        diagramErrorSeconds: input.diagramErrorSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.diagramErrorSeconds,
+        staticSeconds: input.staticSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.staticSeconds,
+    };
+    const findings = [];
+    const add = (severity, check, message) => findings.push({ beatId: "*", scene, severity, message, source: "render", check });
+    for (const w of (0, canvasExplainer_1.sourceWarnings)(fs.readFileSync(htmlPath, "utf8"), htmlPath))
+        add("warning", "randomness", w);
+    const browser = await (0, capture_1.launchChromium)();
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-canvas-validate-"));
+    try {
+        const opened = await (0, canvasExplainer_1.openExplainer)(browser, htmlPath, { width, height, fps, voiceover, project, probes: true, requireScore: audioOn });
+        const { page, durationSeconds } = opened;
+        const texts = [];
+        const takeTexts = async () => {
+            const got = await page.evaluate(() => {
+                const w = window;
+                const copy = w.__ovsTexts.slice();
+                w.__ovsTexts.length = 0;
+                return copy;
+            });
+            texts.push(...got);
+        };
+        if (opened.resized)
+            add("warning", "canvas-size", `The canvas was not ${width}x${height}. Size it from window.OVS.width and window.OVS.height.`);
+        // A frame is a pure function of t: three times, each drawn twice with another time drawn in between.
+        const probeTimes = [0.2, 0.5, 0.8].map((f) => f * durationSeconds);
+        for (const t of probeTimes) {
+            const first = hash(await (0, canvasExplainer_1.captureFrame)(page, t));
+            await (0, canvasExplainer_1.captureFrame)(page, (t + durationSeconds * 0.37) % durationSeconds);
+            const second = hash(await (0, canvasExplainer_1.captureFrame)(page, t));
+            if (first !== second) {
+                add("error", "purity", `Drawing t=${t.toFixed(2)}s twice gives two different frames. A frame must be a pure function of t: nothing may depend on how many frames were drawn before it, on the clock, or on a random number.`);
+            }
+        }
+        await takeTexts();
+        // Frames across the whole length, for the arc and the text.
+        const gap = Math.max(MIN_SAMPLE_GAP_SECONDS, durationSeconds / MAX_SAMPLES);
+        const times = [];
+        for (let t = 0; t < durationSeconds; t += gap)
+            times.push(t);
+        const samples = [];
+        let previous = null;
+        const beatAt = (t) => project?.beats.find((b) => t >= b.start && t < b.end)?.id ?? "*";
+        for (const [i, t] of times.entries()) {
+            await page.evaluate(() => (window.__ovsCaptionBoxes = []));
+            const png = await (0, canvasExplainer_1.captureFrame)(page, t);
+            const boxes = (await page.evaluate(() => window.__ovsCaptionBoxes));
+            const file = path.join(scratch, `f${i}.png`);
+            fs.writeFileSync(file, png);
+            const m = await (0, lessonArc_1.measureArcFrame)(file, boxes, previous);
+            previous = m.signature;
+            samples.push({ time: t, beatId: beatAt(t), drawn: m.drawn, changedFromPrevious: m.changedFromPrevious });
+            fs.rmSync(file, { force: true });
+        }
+        await takeTexts();
+        findings.push(...judgeText(texts, width, height, scale, scene));
+        for (const f of (0, lessonArc_1.judgeLessonArc)(samples, durationSeconds, thresholds)) {
+            findings.push({ beatId: f.beatId, scene, severity: f.severity, message: f.message, source: "render", check: f.check });
+        }
+        let sound = null;
+        if (audioOn) {
+            await page.evaluate(() => (window.__ovsSources.length = 0));
+            try {
+                const score = await (0, canvasExplainer_1.renderScore)(page, durationSeconds, canvasExplainer_1.AUDIO_SAMPLE_RATE, voiceover);
+                const sources = (await page.evaluate(() => window.__ovsSources));
+                let peak = 0;
+                for (let i = 0; i < score.data.length; i++)
+                    peak = Math.max(peak, Math.abs(score.data[i]));
+                const peakDb = peak > 0 ? 20 * Math.log10(peak) : null;
+                const most = maxSimultaneous(sources, durationSeconds);
+                sound = { maxSimultaneous: most, peakDb: peakDb === null ? null : Math.round(peakDb * 10) / 10, sources: sources.length };
+                if (most > exports.MAX_SIMULTANEOUS_SOUNDS) {
+                    add("warning", "sound-polyphony", `Up to ${most} sounds play at once (a source node each), over ${exports.MAX_SIMULTANEOUS_SOUNDS}. A pile-up of effects is mush under a voice; thin the score.`);
+                }
+                if (peak >= 1)
+                    add("warning", "sound-peak", `The score peaks at ${peakDb.toFixed(1)} dBFS, which clips. Lower the master level.`);
+                if (peak === 0)
+                    add("warning", "sound-silent", "The score renders as silence.");
+            }
+            catch (err) {
+                add("error", "sound-kit", err instanceof Error ? err.message : String(err));
+            }
+        }
+        await page.close().catch(() => undefined);
+        const own = texts.filter((t) => !t.caption && t.text.trim() !== "");
+        return {
+            ok: !findings.some((f) => f.severity === "error"),
+            findings,
+            durationSeconds,
+            width,
+            height,
+            textScale: scale,
+            framesSampled: times.length,
+            minTextSize: own.length === 0 ? null : Math.round(Math.min(...own.map((t) => t.size)) * 10) / 10,
+            sound,
+            elapsedMs: Date.now() - started,
+        };
+    }
+    finally {
+        await browser.close().catch(() => undefined);
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/dist/config.d.ts

@@ -68,6 +68,11 @@ export interface OpenvidstudioConfig {
     narration: NarrationConfig;
     render: RenderConfig;
     production: ProductionConfig;
+    /**
+     * Lines write_description appends, each exactly once, at the end of every lesson description ("Constructed
+     * animation, not footage", an exam-board non-affiliation line). Absent by default, and then the key is not written.
+     */
+    disclaimers?: string[];
 }
 export interface ConfigPatch {
     hasHiggsfield?: boolean;
@@ -77,6 +82,7 @@ export interface ConfigPatch {
     narration?: Partial<NarrationConfig>;
     render?: Partial<RenderConfig>;
     production?: Partial<ProductionConfig>;
+    disclaimers?: string[];
 }
 /**
  * Defaults chosen so a bare request works with no configuration.

package/dist/config.js

@@ -113,6 +113,7 @@ function loadConfig(projectRoot) {
             creativeLevel: raw.production?.creativeLevel ?? exports.DEFAULT_CONFIG.production.creativeLevel,
             timeBudgetMinutes: raw.production?.timeBudgetMinutes ?? exports.DEFAULT_CONFIG.production.timeBudgetMinutes,
         },
+        ...(Array.isArray(raw.disclaimers) ? { disclaimers: raw.disclaimers.filter((d) => typeof d === "string") } : {}),
     };
 }
 /**
@@ -149,6 +150,7 @@ function writeConfig(projectRoot, patch) {
             creativeLevel: patch.production?.creativeLevel ?? existing.production.creativeLevel,
             timeBudgetMinutes: patch.production?.timeBudgetMinutes ?? existing.production.timeBudgetMinutes,
         },
+        ...((patch.disclaimers ?? existing.disclaimers) !== undefined ? { disclaimers: patch.disclaimers ?? existing.disclaimers } : {}),
     };
     fs.mkdirSync(projectRoot, { recursive: true });
     fs.writeFileSync(configPath(projectRoot), JSON.stringify(merged, null, 2) + "\n", "utf8");

package/dist/install.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `npx -y @openvidstudio/mcp-server install <client>`: writes the openvidstudio entry into a client's
+ * own MCP config file, so nobody has to hand-edit JSON (and get the Windows `cmd /c` wrapper wrong).
+ *
+ * It only ever touches the `openvidstudio` key: every other server in the file is left exactly as it
+ * was, an unparsable file is never overwritten, and a backup is written before any change.
+ *
+ * Clients and where their config lives (checked against each vendor's own docs in October 2026):
+ *   claude-desktop  macOS ~/Library/Application Support/Claude/claude_desktop_config.json,
+ *                   Windows %APPDATA%\Claude\claude_desktop_config.json, key "mcpServers"
+ *   cursor          ~/.cursor/mcp.json (global), key "mcpServers"
+ *   vscode          .vscode/mcp.json in the current folder, key "servers", entry has "type": "stdio"
+ *   claude-code     no file: prints the plugin commands (and the `claude mcp add` fallback)
+ */
+export declare const INSTALL_CLIENTS: readonly ["claude-desktop", "cursor", "vscode", "claude-code"];
+export type InstallClient = (typeof INSTALL_CLIENTS)[number];
+export interface InstallEnv {
+    platform: NodeJS.Platform;
+    home: string;
+    /** %APPDATA% on Windows; falls back to <home>/AppData/Roaming. */
+    appData?: string;
+    /** Where `vscode` writes `.vscode/mcp.json`. */
+    cwd: string;
+    /** Used in the backup file name; injectable so tests are stable. */
+    now?: () => Date;
+}
+export interface ServerEntry {
+    type?: "stdio";
+    command: string;
+    args: string[];
+}
+export interface InstallTarget {
+    client: InstallClient;
+    file: string;
+    /** The top-level key the client keeps its servers under. */
+    key: "mcpServers" | "servers";
+    entry: ServerEntry;
+}
+export interface InstallResult {
+    ok: boolean;
+    client: InstallClient | null;
+    action: "created" | "updated" | "unchanged" | "printed" | "refused" | "dry-run";
+    file?: string;
+    backup?: string;
+    /** Lines to show the user, in order. */
+    lines: string[];
+}
+/** The command a client runs to start the server. Windows needs `cmd /c` so `npx` (a .cmd shim) resolves. */
+export declare function serverCommand(platform: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+export declare function installTarget(client: InstallClient, env: InstallEnv): InstallTarget | null;
+/** Pure: merge the openvidstudio entry into the existing file text. Throws if the existing text is not a JSON object. */
+export declare function mergeEntry(existing: string | null, key: "mcpServers" | "servers", entry: ServerEntry): {
+    text: string;
+    changed: boolean;
+    existed: boolean;
+};
+export declare const HELP: string;
+export declare function runInstall(argv: string[], env: InstallEnv): InstallResult;
+/** CLI wrapper used by stdio.ts: runs against the real machine and returns the process exit code. */
+export declare function installCli(argv: string[]): number;

package/dist/install.js

@@ -0,0 +1,225 @@
+"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.HELP = exports.INSTALL_CLIENTS = void 0;
+exports.serverCommand = serverCommand;
+exports.installTarget = installTarget;
+exports.mergeEntry = mergeEntry;
+exports.runInstall = runInstall;
+exports.installCli = installCli;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/**
+ * `npx -y @openvidstudio/mcp-server install <client>`: writes the openvidstudio entry into a client's
+ * own MCP config file, so nobody has to hand-edit JSON (and get the Windows `cmd /c` wrapper wrong).
+ *
+ * It only ever touches the `openvidstudio` key: every other server in the file is left exactly as it
+ * was, an unparsable file is never overwritten, and a backup is written before any change.
+ *
+ * Clients and where their config lives (checked against each vendor's own docs in October 2026):
+ *   claude-desktop  macOS ~/Library/Application Support/Claude/claude_desktop_config.json,
+ *                   Windows %APPDATA%\Claude\claude_desktop_config.json, key "mcpServers"
+ *   cursor          ~/.cursor/mcp.json (global), key "mcpServers"
+ *   vscode          .vscode/mcp.json in the current folder, key "servers", entry has "type": "stdio"
+ *   claude-code     no file: prints the plugin commands (and the `claude mcp add` fallback)
+ */
+exports.INSTALL_CLIENTS = ["claude-desktop", "cursor", "vscode", "claude-code"];
+const SERVER_NAME = "openvidstudio";
+const PACKAGE = "@openvidstudio/mcp-server";
+/** The command a client runs to start the server. Windows needs `cmd /c` so `npx` (a .cmd shim) resolves. */
+function serverCommand(platform) {
+    const args = ["-y", PACKAGE];
+    return platform === "win32" ? { command: "cmd", args: ["/c", "npx", ...args] } : { command: "npx", args };
+}
+function installTarget(client, env) {
+    const { command, args } = serverCommand(env.platform);
+    switch (client) {
+        case "claude-desktop": {
+            let file;
+            if (env.platform === "darwin")
+                file = path.join(env.home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+            else if (env.platform === "win32")
+                file = path.join(env.appData ?? path.join(env.home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+            else
+                return null; // no official Linux build; the caller prints the block instead
+            return { client, file, key: "mcpServers", entry: { command, args } };
+        }
+        case "cursor":
+            return { client, file: path.join(env.home, ".cursor", "mcp.json"), key: "mcpServers", entry: { command, args } };
+        case "vscode":
+            return { client, file: path.join(env.cwd, ".vscode", "mcp.json"), key: "servers", entry: { type: "stdio", command, args } };
+        case "claude-code":
+            return null;
+    }
+}
+/** Pure: merge the openvidstudio entry into the existing file text. Throws if the existing text is not a JSON object. */
+function mergeEntry(existing, key, entry) {
+    let doc = {};
+    if (existing !== null && existing.trim() !== "") {
+        const parsed = JSON.parse(existing);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new Error("the file is not a JSON object");
+        doc = parsed;
+    }
+    const servers = (typeof doc[key] === "object" && doc[key] !== null && !Array.isArray(doc[key]) ? doc[key] : {});
+    const before = JSON.stringify(servers[SERVER_NAME]);
+    const existed = SERVER_NAME in servers;
+    servers[SERVER_NAME] = entry;
+    doc[key] = servers;
+    return { text: JSON.stringify(doc, null, 2) + "\n", changed: before !== JSON.stringify(entry), existed };
+}
+const stamp = (d) => d.toISOString().replace(/[-:]/g, "").replace(/\..*$/, "").replace("T", "-");
+exports.HELP = [
+    "openvidstudio-mcp install <client> [--dry-run] [--print]",
+    "",
+    "Adds the openvidstudio server to a client's MCP config without touching its other servers.",
+    "",
+    "Clients:",
+    "  claude-desktop   Claude Desktop (Chat tab). Restart Claude afterwards.",
+    "  cursor           Cursor, global config (~/.cursor/mcp.json)",
+    "  vscode           VS Code, this folder (.vscode/mcp.json)",
+    "  claude-code      Prints the plugin commands for Claude Code, the desktop Code tab and Cowork",
+    "",
+    "Options:",
+    "  --dry-run        show what would be written, write nothing",
+    "  --print          print the config block and exit",
+].join("\n");
+function runInstall(argv, env) {
+    const flags = new Set(argv.filter((a) => a.startsWith("--")));
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    const client = positional[0];
+    if (flags.has("--help") || positional.length === 0) {
+        return { ok: positional.length > 0 || flags.has("--help"), client: null, action: "printed", lines: [exports.HELP] };
+    }
+    if (!client || !exports.INSTALL_CLIENTS.includes(client)) {
+        return { ok: false, client: null, action: "refused", lines: [`Unknown client "${positional[0]}". Choose one of: ${exports.INSTALL_CLIENTS.join(", ")}.`, "", exports.HELP] };
+    }
+    if (client === "claude-code") {
+        return {
+            ok: true,
+            client,
+            action: "printed",
+            lines: [
+                "Claude Code, the Claude desktop Code tab and Cowork: install the plugin (skills and tools together).",
+                "",
+                "  /plugin marketplace add AnayDhawan/openvidstudio",
+                "  /plugin install openvidstudio@openvidstudio",
+                "",
+                "From a shell, the same:",
+                "",
+                "  claude plugin marketplace add AnayDhawan/openvidstudio",
+                "  claude plugin install openvidstudio@openvidstudio",
+                "",
+                "Tools only, without the plugin:",
+                "",
+                `  claude mcp add ${SERVER_NAME} -- npx -y ${PACKAGE}`,
+                "",
+                "Do not keep both: the plugin already registers the server.",
+            ],
+        };
+    }
+    const target = installTarget(client, env);
+    const { command, args } = serverCommand(env.platform);
+    const block = JSON.stringify({ mcpServers: { [SERVER_NAME]: { command, args } } }, null, 2);
+    if (!target) {
+        return {
+            ok: true,
+            client,
+            action: "printed",
+            lines: [
+                `${client} has no config file this installer knows on ${env.platform}. Add this block to your client's MCP config and restart it:`,
+                "",
+                block,
+            ],
+        };
+    }
+    if (flags.has("--print")) {
+        return { ok: true, client, action: "printed", lines: [JSON.stringify({ [target.key]: { [SERVER_NAME]: target.entry } }, null, 2)] };
+    }
+    let existing = null;
+    if (fs.existsSync(target.file))
+        existing = fs.readFileSync(target.file, "utf8");
+    let merged;
+    try {
+        merged = mergeEntry(existing, target.key, target.entry);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            client,
+            action: "refused",
+            file: target.file,
+            lines: [
+                `Not touching ${target.file}: ${err instanceof Error ? err.message : String(err)}.`,
+                "Fix or move the file, then run this again. Or paste this block in by hand:",
+                "",
+                JSON.stringify({ [target.key]: { [SERVER_NAME]: target.entry } }, null, 2),
+            ],
+        };
+    }
+    if (!merged.changed && existing !== null) {
+        return { ok: true, client, action: "unchanged", file: target.file, lines: [`Already installed in ${target.file}. Nothing changed.`] };
+    }
+    if (flags.has("--dry-run")) {
+        return { ok: true, client, action: "dry-run", file: target.file, lines: [`Would write ${target.file}:`, "", merged.text.trimEnd()] };
+    }
+    let backup;
+    if (existing !== null) {
+        backup = `${target.file}.bak-${stamp((env.now ?? (() => new Date()))())}`;
+        fs.copyFileSync(target.file, backup);
+    }
+    fs.mkdirSync(path.dirname(target.file), { recursive: true });
+    fs.writeFileSync(target.file, merged.text);
+    const lines = [
+        `${merged.existed ? "Updated" : "Added"} the ${SERVER_NAME} server in ${target.file}.`,
+        ...(backup ? [`Backup of the old file: ${backup}`] : []),
+        client === "claude-desktop" ? "Quit Claude Desktop completely and start it again, then check the tools list." : client === "cursor" ? "Restart Cursor (or reload the window), then check the MCP settings." : "Reload VS Code, then check the MCP server list.",
+        "Then ask your agent to run preflight; it checks your machine and names the fix for anything missing.",
+    ];
+    return { ok: true, client, action: existing === null ? "created" : "updated", file: target.file, backup, lines };
+}
+/** CLI wrapper used by stdio.ts: runs against the real machine and returns the process exit code. */
+function installCli(argv) {
+    const result = runInstall(argv, {
+        platform: process.platform,
+        home: os.homedir(),
+        appData: process.env.APPDATA,
+        cwd: process.cwd(),
+    });
+    const out = result.lines.join("\n") + "\n";
+    (result.ok ? process.stdout : process.stderr).write(out);
+    return result.ok ? 0 : 1;
+}