@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/facts.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Run records: a small JSON file per tool call that did something worth verifying later.
+ *
+ * "A claim needs a visual" is a rule this pipeline can only follow by convention while the
+ * only record of what happened is beats.json and brief.json, which say what was intended.
+ * A run record is the other half: what a tool actually did (this beat was a real capture of
+ * that URL, that render reused three cached beats and rendered two, this validator flagged
+ * these findings). collect_facts merges them into src/videos/<name>/facts.json so a check, or
+ * a person, can hold a claim up against what really ran.
+ *
+ * Writing a record is best effort and never fails the tool that calls it: a read-only project
+ * directory must not turn a successful capture into an error.
+ */
+export declare const FACT_SCHEMA_VERSION = 1;
+/** Where records go, relative to the project root. Gitignored: they are evidence, not source. */
+export declare const RUNS_DIR_REL: string;
+export interface FactRecord {
+    schemaVersion: number;
+    tool: string;
+    /** ISO timestamp the record was written. */
+    recordedAt: string;
+    /** Set when the tool is scoped to one video (render, validate, stitch). */
+    videoName?: string;
+    /** Set when the tool is scoped to one beat (every capture). */
+    beatId?: string;
+    facts: Record<string, unknown>;
+}
+export interface FactRecordInput {
+    tool: string;
+    videoName?: string;
+    beatId?: string;
+    facts: Record<string, unknown>;
+}
+/** A project-relative path with forward slashes, so a record reads the same on every platform. */
+export declare function relToProject(projectRoot: string, abs: string): string;
+/**
+ * Writes one record and returns its absolute path, or null when it could not be written. The
+ * `wx` flag plus a counter keeps two records from the same millisecond (a batch of captures)
+ * from overwriting each other.
+ */
+export declare function writeFactRecord(projectRoot: string, input: FactRecordInput): string | null;
+/** Every readable record in the runs directory, oldest first. A malformed file is skipped, not fatal. */
+export declare function readFactRecords(projectRoot: string): FactRecord[];
+/** Size in bytes of a file that should exist, or null. Records state what is on disk, not what was asked for. */
+export declare function fileBytes(abs: string): number | null;

package/dist/facts.js

@@ -0,0 +1,124 @@
+"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.RUNS_DIR_REL = exports.FACT_SCHEMA_VERSION = void 0;
+exports.relToProject = relToProject;
+exports.writeFactRecord = writeFactRecord;
+exports.readFactRecords = readFactRecords;
+exports.fileBytes = fileBytes;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Run records: a small JSON file per tool call that did something worth verifying later.
+ *
+ * "A claim needs a visual" is a rule this pipeline can only follow by convention while the
+ * only record of what happened is beats.json and brief.json, which say what was intended.
+ * A run record is the other half: what a tool actually did (this beat was a real capture of
+ * that URL, that render reused three cached beats and rendered two, this validator flagged
+ * these findings). collect_facts merges them into src/videos/<name>/facts.json so a check, or
+ * a person, can hold a claim up against what really ran.
+ *
+ * Writing a record is best effort and never fails the tool that calls it: a read-only project
+ * directory must not turn a successful capture into an error.
+ */
+exports.FACT_SCHEMA_VERSION = 1;
+/** Where records go, relative to the project root. Gitignored: they are evidence, not source. */
+exports.RUNS_DIR_REL = path.join(".openvidstudio", "runs");
+/** A project-relative path with forward slashes, so a record reads the same on every platform. */
+function relToProject(projectRoot, abs) {
+    return path.relative(projectRoot, abs).split(path.sep).join("/");
+}
+function fileSafeTimestamp(iso) {
+    return iso.replace(/[:.]/g, "-");
+}
+/**
+ * Writes one record and returns its absolute path, or null when it could not be written. The
+ * `wx` flag plus a counter keeps two records from the same millisecond (a batch of captures)
+ * from overwriting each other.
+ */
+function writeFactRecord(projectRoot, input) {
+    try {
+        const recordedAt = new Date().toISOString();
+        const record = { schemaVersion: exports.FACT_SCHEMA_VERSION, recordedAt, ...input };
+        const dir = path.join(projectRoot, exports.RUNS_DIR_REL);
+        fs.mkdirSync(dir, { recursive: true });
+        const stem = `${input.tool}-${fileSafeTimestamp(recordedAt)}`;
+        for (let n = 0; n < 1000; n++) {
+            const file = path.join(dir, `${stem}${n === 0 ? "" : `-${n}`}.json`);
+            try {
+                fs.writeFileSync(file, JSON.stringify(record, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
+                return file;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        process.stderr.write(`openvidstudio-mcp: could not write a ${input.tool} run record: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+/** Every readable record in the runs directory, oldest first. A malformed file is skipped, not fatal. */
+function readFactRecords(projectRoot) {
+    const dir = path.join(projectRoot, exports.RUNS_DIR_REL);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const rec = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+            if (rec && typeof rec.tool === "string" && typeof rec.recordedAt === "string" && rec.facts)
+                out.push(rec);
+        }
+        catch {
+            // Half-written or hand-edited; not this tool's job to diagnose.
+        }
+    }
+    return out.sort((a, b) => a.recordedAt.localeCompare(b.recordedAt));
+}
+/** Size in bytes of a file that should exist, or null. Records state what is on disk, not what was asked for. */
+function fileBytes(abs) {
+    try {
+        return fs.statSync(abs).size;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/frameDiff.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Frame comparison, shared by visual regression and docs-drift detection.
+ *
+ * Both answer the same question, "has this picture changed enough to care", and both have
+ * the same failure mode if done naively: a strict byte comparison reports a difference on
+ * every run, because an encoder is not deterministic at the pixel level and antialiasing
+ * moves under a font update. A comparison that is useful has to separate "a few pixels
+ * shifted by one value" from "this panel is a different colour now".
+ *
+ * So there are two numbers, and they say different things. `meanDelta` is the average
+ * per-pixel difference across the frame, which catches a global change (a palette swap, a
+ * brightness shift) that moves everything slightly. `changedRatio` is the fraction of
+ * pixels that moved more than a per-pixel threshold, which catches a local change (one
+ * button, one line of text) that leaves the mean almost untouched. A threshold on either
+ * alone misses half the real cases.
+ */
+export interface FrameComparison {
+    /** Average absolute per-channel difference, 0 to 1. */
+    meanDelta: number;
+    /** Fraction of pixels whose worst channel moved past the per-pixel threshold, 0 to 1. */
+    changedRatio: number;
+    /** The size both frames were normalized to before comparing. */
+    width: number;
+    height: number;
+    /** True when the inputs were not the same size, which is itself usually the finding. */
+    resized: boolean;
+}
+export interface CompareOptions {
+    /**
+     * Per-channel difference, 0-255, above which a pixel counts as changed. 12 ignores
+     * encoder noise and subpixel antialiasing while still catching any real repaint.
+     */
+    pixelThreshold?: number;
+    /**
+     * Frames are compared at this width. Downscaling first is not a shortcut: it is what
+     * makes the comparison stable, since it averages away the single-pixel antialiasing
+     * differences that are not what anyone means by "the page changed".
+     */
+    compareWidth?: number;
+    /** When set, a PNG highlighting the changed pixels in red is written here. */
+    diffPath?: string;
+}
+export declare const DEFAULT_PIXEL_THRESHOLD = 12;
+export declare const DEFAULT_COMPARE_WIDTH = 640;
+/**
+ * An image's own width in pixels, for a caller that needs to compare at native resolution
+ * rather than at DEFAULT_COMPARE_WIDTH. visual_regression's `exact` mode is the one case:
+ * downscaling first is what makes an ordinary comparison stable, and it is exactly what a
+ * gate claiming to catch ANY pixel difference must not do.
+ */
+export declare function imageWidth(file: string): Promise<number>;
+/**
+ * Compares two image files and, optionally, writes a diff image.
+ *
+ * The second frame is forced to the first's dimensions rather than refused. A page that
+ * got taller has genuinely changed, and reporting that as an error instead of as a
+ * difference would hide the finding behind a crash.
+ */
+export declare function compareFrames(beforePath: string, afterPath: string, opts?: CompareOptions): Promise<FrameComparison>;
+export interface DriftVerdict {
+    drifted: boolean;
+    reason: string;
+}
+/**
+ * Turns the two numbers into one answer.
+ *
+ * Either signal alone is enough, because they catch different shapes of change: a
+ * repainted button barely moves the mean, and a palette shift barely moves the changed
+ * pixel count.
+ */
+export declare function judgeDrift(comparison: FrameComparison, thresholds?: {
+    changedRatio?: number;
+    meanDelta?: number;
+}): DriftVerdict;

package/dist/frameDiff.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_COMPARE_WIDTH = exports.DEFAULT_PIXEL_THRESHOLD = void 0;
+exports.imageWidth = imageWidth;
+exports.compareFrames = compareFrames;
+exports.judgeDrift = judgeDrift;
+const sharp_1 = __importDefault(require("sharp"));
+exports.DEFAULT_PIXEL_THRESHOLD = 12;
+exports.DEFAULT_COMPARE_WIDTH = 640;
+/**
+ * An image's own width in pixels, for a caller that needs to compare at native resolution
+ * rather than at DEFAULT_COMPARE_WIDTH. visual_regression's `exact` mode is the one case:
+ * downscaling first is what makes an ordinary comparison stable, and it is exactly what a
+ * gate claiming to catch ANY pixel difference must not do.
+ */
+async function imageWidth(file) {
+    const { width } = await (0, sharp_1.default)(file).metadata();
+    if (!width)
+        throw new Error(`Could not read the pixel width of "${file}".`);
+    return width;
+}
+async function normalize(input, width, height) {
+    const pipeline = (0, sharp_1.default)(input).removeAlpha();
+    const resized = height ? pipeline.resize(width, height, { fit: "fill" }) : pipeline.resize({ width });
+    const { data, info } = await resized.raw().toBuffer({ resolveWithObject: true });
+    return { data, width: info.width, height: info.height };
+}
+/**
+ * Compares two image files and, optionally, writes a diff image.
+ *
+ * The second frame is forced to the first's dimensions rather than refused. A page that
+ * got taller has genuinely changed, and reporting that as an error instead of as a
+ * difference would hide the finding behind a crash.
+ */
+async function compareFrames(beforePath, afterPath, opts = {}) {
+    const threshold = opts.pixelThreshold ?? exports.DEFAULT_PIXEL_THRESHOLD;
+    const compareWidth = opts.compareWidth ?? exports.DEFAULT_COMPARE_WIDTH;
+    const before = await normalize(beforePath, compareWidth);
+    const beforeMeta = await (0, sharp_1.default)(beforePath).metadata();
+    const afterMeta = await (0, sharp_1.default)(afterPath).metadata();
+    const after = await normalize(afterPath, before.width, before.height);
+    const pixels = before.width * before.height;
+    const channels = 3;
+    let sum = 0;
+    let changed = 0;
+    const diff = opts.diffPath ? Buffer.alloc(pixels * channels) : null;
+    for (let p = 0; p < pixels; p++) {
+        const i = p * channels;
+        const dr = Math.abs(before.data[i] - after.data[i]);
+        const dg = Math.abs(before.data[i + 1] - after.data[i + 1]);
+        const db = Math.abs(before.data[i + 2] - after.data[i + 2]);
+        sum += dr + dg + db;
+        const worst = Math.max(dr, dg, db);
+        const isChanged = worst > threshold;
+        if (isChanged)
+            changed++;
+        if (diff) {
+            if (isChanged) {
+                diff[i] = 255;
+                diff[i + 1] = 32;
+                diff[i + 2] = 32;
+            }
+            else {
+                // Unchanged pixels stay visible but dimmed, so the highlight reads as a mark on
+                // the page rather than as a red shape floating on nothing.
+                const grey = Math.round((after.data[i] + after.data[i + 1] + after.data[i + 2]) / 3 / 3);
+                diff[i] = grey;
+                diff[i + 1] = grey;
+                diff[i + 2] = grey;
+            }
+        }
+    }
+    if (diff && opts.diffPath) {
+        await (0, sharp_1.default)(diff, { raw: { width: before.width, height: before.height, channels: 3 } })
+            .png()
+            .toFile(opts.diffPath);
+    }
+    return {
+        meanDelta: sum / (pixels * channels) / 255,
+        changedRatio: changed / pixels,
+        width: before.width,
+        height: before.height,
+        resized: beforeMeta.width !== afterMeta.width || beforeMeta.height !== afterMeta.height,
+    };
+}
+/**
+ * Turns the two numbers into one answer.
+ *
+ * Either signal alone is enough, because they catch different shapes of change: a
+ * repainted button barely moves the mean, and a palette shift barely moves the changed
+ * pixel count.
+ */
+function judgeDrift(comparison, thresholds = {}) {
+    const changedLimit = thresholds.changedRatio ?? 0.02;
+    const meanLimit = thresholds.meanDelta ?? 0.01;
+    if (comparison.resized) {
+        return {
+            drifted: true,
+            reason: "the frame is a different size than the reference, which is a layout change by itself",
+        };
+    }
+    if (comparison.changedRatio > changedLimit) {
+        return {
+            drifted: true,
+            reason: `${(comparison.changedRatio * 100).toFixed(2)}% of pixels moved, past the ` +
+                `${(changedLimit * 100).toFixed(2)}% limit`,
+        };
+    }
+    if (comparison.meanDelta > meanLimit) {
+        return {
+            drifted: true,
+            reason: `the average pixel moved ${(comparison.meanDelta * 100).toFixed(2)}%, past the ` +
+                `${(meanLimit * 100).toFixed(2)}% limit, which is the shape of a palette or brightness change`,
+        };
+    }
+    return { drifted: false, reason: "within both thresholds" };
+}

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;
+}