@viralspin/mcp 0.2.0 → 0.2.2

package/dist/tools/timeline-edit.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keepWindowsTool = exports.removeSpansTool = exports.getTranscriptTool = exports.trimSilencesTool = exports.renderProjectTool = exports.reorderScenesTool = exports.removeSpanTool = exports.trimClipTool = void 0;
+/**
+ * Granular timeline edit verbs for a HOSTED Swap & Refine project (a narrative
+ * job). These widen Claude's editing vocabulary beyond swap — trim a cutaway,
+ * cut a span out of the cut, and reorder the A-roll's backbone scenes — each
+ * mapped to an already-deployed narrative endpoint, so the edit lands in the
+ * same project the web editor shows (and streams in live via realtime).
+ *
+ * All are hosted-only: they take a `job_id` (or VIRALSPIN_HOSTED_JOB_ID). There
+ * is no local-engine equivalent for these ops.
+ */
+const hosted_js_1 = require("../hosted.js");
+function fmt(sec) {
+    const m = Math.floor(sec / 60);
+    const s = Math.round(sec % 60);
+    return `${m}:${s.toString().padStart(2, "0")}`;
+}
+exports.trimClipTool = {
+    name: "trim_clip",
+    description: "Shorten (or restore) how long ONE B-roll cutaway stays on screen in a hosted Swap & Refine project, " +
+        "freeing that time back to the A-roll. Audio-safe — total video length is preserved. " +
+        "Get the segment id from suggest_clips. Instant timeline edit by default (no render); call render_project when done.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            segment_id: { type: "string", description: "The cutaway to trim (from suggest_clips)." },
+            duration_sec: { type: "number", description: "New on-screen duration in seconds (e.g. 1.5)." },
+            render: { type: "boolean", description: "Re-render now (costs credits). Default false = instant timeline-only edit." },
+        },
+        required: ["segment_id", "duration_sec"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "trim_clip is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        await (0, hosted_js_1.setClipDuration)(jobId, args.segment_id, args.duration_sec);
+        if (args.render) {
+            await (0, hosted_js_1.rerender)(jobId);
+            return `Trimmed segment ${args.segment_id} to ${args.duration_sec}s and started a re-render. ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        }
+        return (`Trimmed segment ${args.segment_id} to ${args.duration_sec}s (instant, no render). ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `Call render_project(job_id: "${jobId}") when the cut is final.`);
+    },
+};
+exports.removeSpanTool = {
+    name: "remove_span",
+    description: "Cut a span of time [from_sec, to_sec] out of a hosted Swap & Refine video — e.g. a duplicated opening " +
+        "sentence or a dead pause. The backbone A-roll is trimmed and the rest shifts up; reuses cached B-roll. " +
+        "Re-renders; streams into the editor.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            from_sec: { type: "number", description: "Start of the span to remove (seconds)." },
+            to_sec: { type: "number", description: "End of the span to remove (seconds)." },
+        },
+        required: ["from_sec", "to_sec"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "remove_span is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        if (!(args.to_sec > args.from_sec))
+            return "to_sec must be greater than from_sec.";
+        await (0, hosted_js_1.removeSpan)(jobId, args.from_sec, args.to_sec, true);
+        return (`Removing ${fmt(args.from_sec)}–${fmt(args.to_sec)} and re-rendering.\n` +
+            `Updating live: ${(0, hosted_js_1.editorUrl)(jobId)}`);
+    },
+};
+exports.reorderScenesTool = {
+    name: "reorder_scenes",
+    description: "See or reorder the A-roll's backbone scenes in a hosted Swap & Refine project. " +
+        "Call with no `order` to LIST the scenes (id + label + time) — the reorderable building blocks. " +
+        "Call with `order` (the scene ids in the new running order; omit ids to drop them) to apply it and re-render.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            order: {
+                type: "array",
+                items: { type: "string" },
+                description: "New running order as scene ids. Any scene id omitted here is removed from the cut. Omit `order` entirely to just list the scenes.",
+            },
+            render: { type: "boolean", description: "Re-render now (costs credits). Default false = instant timeline-only edit." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "reorder_scenes is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const { scenes } = await (0, hosted_js_1.detectScenes)(jobId);
+        if (!scenes.length)
+            return `No backbone scenes detected for project ${jobId} yet. Open it: ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        if (!args.order || !args.order.length) {
+            const lines = [...scenes]
+                .sort((a, b) => a.order - b.order)
+                .map((s) => `- ${s.id}${s.label ? ` — "${s.label}"` : ""}${s.src_start != null ? ` (${fmt(s.src_start)}${s.src_end != null ? `–${fmt(s.src_end)}` : ""})` : ""}`);
+            return [
+                `Backbone scenes in ${(0, hosted_js_1.editorUrl)(jobId)} :`,
+                ...lines,
+                ``,
+                `Reorder with: reorder_scenes(job_id: "${jobId}", order: ["${scenes[0].id}", …]). Omit a scene id to drop it.`,
+            ].join("\n");
+        }
+        const known = new Set(scenes.map((s) => s.id));
+        const wanted = args.order.filter((id) => known.has(id));
+        if (!wanted.length)
+            return "None of the given ids matched this project's scenes — call reorder_scenes with no `order` to list valid ids.";
+        const payload = scenes.map((s) => {
+            const idx = wanted.indexOf(s.id);
+            return { id: s.id, order: idx === -1 ? 9999 : idx, removed: idx === -1 };
+        });
+        await (0, hosted_js_1.saveSceneOrder)(jobId, payload);
+        const dropped = scenes.length - wanted.length;
+        if (args.render) {
+            await (0, hosted_js_1.rerender)(jobId);
+            return `Reordered to ${wanted.length} scene(s)${dropped ? ` (dropped ${dropped})` : ""} and started a re-render. ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        }
+        return (`Reordered to ${wanted.length} scene(s)${dropped ? ` (dropped ${dropped})` : ""} (instant, no render). ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `Call render_project(job_id: "${jobId}") when the cut is final.`);
+    },
+};
+exports.renderProjectTool = {
+    name: "render_project",
+    description: "Bake the current hosted Swap & Refine timeline into a final MP4 — the ONE cloud render after a batch of " +
+        "instant timeline edits (swap_clip / trim_clip / reorder_scenes). Captions, hook, overlays and motion are " +
+        "applied here. Costs a render/credits. Returns immediately; the finished preview lands on the project, then " +
+        "publish with publish_now or schedule_post.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "render_project is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        await (0, hosted_js_1.rerender)(jobId);
+        return (`Rendering the final cut for project ${jobId}.\n` +
+            `Watch it in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `When it finishes, publish with publish_now or schedule_post.`);
+    },
+};
+exports.trimSilencesTool = {
+    name: "trim_silences",
+    description: "Edit out the dead air / empty pauses in a hosted Swap & Refine project. Reads the transcript word " +
+        "timings, finds the silent gaps between spoken words (plus a long lead-in / trailing pause), and removes " +
+        "them to tighten the cut. It re-cuts the A-roll once per gap, so it can take a couple of minutes on a " +
+        "long clip — it does the BIGGEST gaps first (capped by max_cuts). Needs a transcribed talking-head A-roll.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            min_gap_sec: { type: "number", description: "Smallest pause to treat as dead air (default 0.7s). Lower = tighter." },
+            max_cuts: { type: "number", description: "Safety cap on how many gaps to remove this pass (default 12, biggest first)." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "trim_silences is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const minGap = args.min_gap_sec ?? 0.7;
+        const maxCuts = args.max_cuts ?? 12;
+        const PAD = 0.1;
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const tl = job.timeline || {};
+        const words = Array.isArray(tl.words) ? tl.words : [];
+        if (words.length < 2) {
+            return "No transcript word-timings on this project, so I can't detect silences (needs a transcribed talking-head A-roll).";
+        }
+        const total = Number(tl.total_duration_sec) || Number(words[words.length - 1]?.end) || 0;
+        const gaps = [];
+        // long lead-in pause
+        const firstStart = Number(words[0]?.start) || 0;
+        if (firstStart >= minGap + PAD)
+            gaps.push({ from: PAD, to: +(firstStart - PAD).toFixed(2), len: firstStart });
+        // gaps between words
+        for (let i = 0; i < words.length - 1; i++) {
+            const a = Number(words[i]?.end), b = Number(words[i + 1]?.start);
+            if (!Number.isFinite(a) || !Number.isFinite(b))
+                continue;
+            const len = b - a;
+            if (len >= minGap)
+                gaps.push({ from: +(a + PAD).toFixed(2), to: +(b - PAD).toFixed(2), len });
+        }
+        // trailing pause
+        const lastEnd = Number(words[words.length - 1]?.end) || 0;
+        if (total - lastEnd >= minGap + PAD)
+            gaps.push({ from: +(lastEnd + PAD).toFixed(2), to: +total.toFixed(2), len: total - lastEnd });
+        const valid = gaps.filter((g) => g.to - g.from >= 0.2);
+        if (!valid.length)
+            return `No silences ≥ ${minGap}s found — the cut is already tight.`;
+        // biggest gaps first (within the cap), then remove latest→earliest so each
+        // removal doesn't invalidate the earlier gaps' timestamps.
+        const chosen = [...valid].sort((a, b) => b.len - a.len).slice(0, maxCuts).sort((a, b) => b.from - a.from);
+        let removed = 0;
+        let ok = 0;
+        for (const g of chosen) {
+            try {
+                await (0, hosted_js_1.removeSpan)(jobId, g.from, g.to, false);
+                removed += g.to - g.from;
+                ok++;
+            }
+            catch (e) {
+                process.stderr.write(`[trim_silences] span ${g.from}-${g.to} failed: ${e instanceof Error ? e.message : e}\n`);
+            }
+        }
+        if (!ok)
+            return "Couldn't trim the silences — the backend rejected the spans. The project may not allow span removal yet.";
+        await (0, hosted_js_1.rerender)(jobId);
+        const more = valid.length > chosen.length ? ` (${valid.length - chosen.length} smaller pause(s) left — run again or lower min_gap_sec)` : "";
+        return (`Trimmed ${ok} silent gap(s) — about ${removed.toFixed(1)}s of dead air${more} — and started a re-render.\n` +
+            `Watch it tighten in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}`);
+    },
+};
+exports.getTranscriptTool = {
+    name: "get_transcript",
+    description: "Get the timestamped transcript of a hosted Swap & Refine project so YOU (the agent) can spot what to cut " +
+        "— bad takes, restarts ('let me start over'), repeated sentences, filler — or which moments are worth " +
+        "highlighting in a long talking/narrated video. Returns spoken segments with start/end times. Then act: " +
+        "remove_spans to cut bad parts, or keep_windows to keep only the highlight moments.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "get_transcript is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const tl = job.timeline || {};
+        let segs = [];
+        if (Array.isArray(tl.transcript) && tl.transcript.length) {
+            segs = tl.transcript.map((s) => ({ a: Number(s.start_sec ?? s.start ?? 0), b: Number(s.end_sec ?? s.end ?? 0), text: String(s.text ?? "").trim() }));
+        }
+        else if (Array.isArray(tl.words) && tl.words.length) {
+            // group words into phrases on pauses > 0.5s
+            let cur = null;
+            for (const w of tl.words) {
+                const a = Number(w.start), b = Number(w.end), t = String(w.word ?? w.text ?? "");
+                if (!Number.isFinite(a))
+                    continue;
+                if (cur && a - cur.b > 0.5) {
+                    segs.push(cur);
+                    cur = null;
+                }
+                if (!cur)
+                    cur = { a, b, text: t };
+                else {
+                    cur.b = b;
+                    cur.text += (t.startsWith("'") ? "" : " ") + t;
+                }
+            }
+            if (cur)
+                segs.push(cur);
+        }
+        if (!segs.length)
+            return "No transcript on this project (needs a transcribed talking-head/narrated A-roll).";
+        const lines = segs.map((s) => `[${s.a.toFixed(1)}–${s.b.toFixed(1)}] ${s.text}`);
+        return [
+            `Transcript for ${jobId} (spot restarts / repeats / filler to cut, or highlight moments to keep):`,
+            ...lines,
+            ``,
+            `Cut bad spans: remove_spans(job_id: "${jobId}", spans: [{from_sec, to_sec}, …]).`,
+            `Keep only highlights: keep_windows(job_id: "${jobId}", windows: [{from_sec, to_sec}, …]).`,
+        ].join("\n");
+    },
+};
+/** Remove several spans (latest→earliest so earlier coords stay valid), one render. */
+async function removeMany(jobId, spans) {
+    const ordered = [...spans].filter((s) => s.to - s.from >= 0.15).sort((a, b) => b.from - a.from);
+    let ok = 0, removed = 0;
+    for (const s of ordered) {
+        try {
+            await (0, hosted_js_1.removeSpan)(jobId, +s.from.toFixed(2), +s.to.toFixed(2), false);
+            removed += s.to - s.from;
+            ok++;
+        }
+        catch (e) {
+            process.stderr.write(`[removeMany] ${s.from}-${s.to} failed: ${e instanceof Error ? e.message : e}\n`);
+        }
+    }
+    return { ok, removed };
+}
+exports.removeSpansTool = {
+    name: "remove_spans",
+    description: "Cut SEVERAL time spans out of a hosted project in one pass (e.g. bad takes / restarts you found via " +
+        "get_transcript), then re-render once. Spans are seconds of the current cut. Re-cuts the A-roll per span, " +
+        "so several takes a minute or two.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "Project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            spans: {
+                type: "array",
+                items: { type: "object", properties: { from_sec: { type: "number" }, to_sec: { type: "number" } }, required: ["from_sec", "to_sec"] },
+                description: "Spans to cut, each { from_sec, to_sec }.",
+            },
+        },
+        required: ["spans"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "remove_spans is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const spans = (args.spans || []).filter((s) => s && s.to_sec > s.from_sec).map((s) => ({ from: +s.from_sec, to: +s.to_sec }));
+        if (!spans.length)
+            return "No valid spans (each needs to_sec > from_sec).";
+        const { ok, removed } = await removeMany(jobId, spans);
+        if (!ok)
+            return "Couldn't remove the spans — the backend rejected them.";
+        await (0, hosted_js_1.rerender)(jobId);
+        return `Removed ${ok} span(s) — about ${removed.toFixed(1)}s — and started a re-render.\n${(0, hosted_js_1.editorUrl)(jobId)}`;
+    },
+};
+exports.keepWindowsTool = {
+    name: "keep_windows",
+    description: "Turn a long video into a highlight reel: KEEP only the given time windows and cut everything else, then " +
+        "re-render. Great for 'find the worth-highlighting moments in this 10-min recording' — get_transcript, " +
+        "pick the punchy windows, then keep_windows. Windows are seconds of the current cut.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "Project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            windows: {
+                type: "array",
+                items: { type: "object", properties: { from_sec: { type: "number" }, to_sec: { type: "number" } }, required: ["from_sec", "to_sec"] },
+                description: "The moments to KEEP, each { from_sec, to_sec }. Everything outside them is cut.",
+            },
+        },
+        required: ["windows"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "keep_windows is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const wins = (args.windows || []).filter((w) => w && w.to_sec > w.from_sec).map((w) => ({ from: +w.from_sec, to: +w.to_sec })).sort((a, b) => a.from - b.from);
+        if (!wins.length)
+            return "No valid windows to keep (each needs to_sec > from_sec).";
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const total = Number(job.timeline?.total_duration_sec) || wins[wins.length - 1].to;
+        // complement = everything outside the kept windows
+        const cuts = [];
+        if (wins[0].from > 0.15)
+            cuts.push({ from: 0, to: wins[0].from });
+        for (let i = 0; i < wins.length - 1; i++) {
+            if (wins[i + 1].from - wins[i].to > 0.15)
+                cuts.push({ from: wins[i].to, to: wins[i + 1].from });
+        }
+        if (total - wins[wins.length - 1].to > 0.15)
+            cuts.push({ from: wins[wins.length - 1].to, to: total });
+        if (!cuts.length)
+            return "The windows already cover the whole video — nothing to cut.";
+        const { ok, removed } = await removeMany(jobId, cuts);
+        if (!ok)
+            return "Couldn't trim to the windows — the backend rejected the spans.";
+        await (0, hosted_js_1.rerender)(jobId);
+        const kept = wins.reduce((s, w) => s + (w.to - w.from), 0);
+        return `Kept ${wins.length} highlight window(s) (~${kept.toFixed(1)}s), cut ~${removed.toFixed(1)}s, and started a re-render.\n${(0, hosted_js_1.editorUrl)(jobId)}`;
+    },
+};

package/dist/tools/video-assembly.js

@@ -5,17 +5,58 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createVideoAssemblyTool = void 0;
 const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const client_js_1 = require("../client.js");
-// The assembly engine ships inside this package (mcp/engine). Override with env if needed.
-// __dirname at runtime = mcp/dist/tools → ../../engine = mcp/engine.
-const ENGINE_DIR = process.env.VIRALSPIN_ASSEMBLY_DIR || path_1.default.resolve(__dirname, "../../engine");
+const hosted_js_1 = require("../hosted.js");
+const engine_js_1 = require("../engine.js");
+const MEDIA_EXT = new Set([".mp4", ".mov", ".webm", ".m4v", ".jpg", ".jpeg", ".png", ".gif", ".webp"]);
+/** Split B-roll entries into local files (expanding folders) and public URLs.
+ *  Runs on the MCP host, so it can read the user's disk to expand a folder. */
+function partitionBroll(entries) {
+    const localFiles = [];
+    const urls = [];
+    for (const e of entries) {
+        if (/^https?:\/\//i.test(e)) {
+            urls.push(e);
+            continue;
+        }
+        try {
+            const st = fs_1.default.statSync(e);
+            if (st.isDirectory()) {
+                for (const name of fs_1.default.readdirSync(e)) {
+                    if (MEDIA_EXT.has(path_1.default.extname(name).toLowerCase()))
+                        localFiles.push(path_1.default.join(e, name));
+                }
+            }
+            else if (st.isFile()) {
+                localFiles.push(e);
+            }
+        }
+        catch { /* unreadable path — skip */ }
+    }
+    return { localFiles, urls };
+}
+const VIDEO_EXT = /\.(mp4|mov|webm|m4v)(\?|$)/i;
+function brollKind(url) {
+    return VIDEO_EXT.test(url) ? "video" : "image";
+}
 const BROLL_STYLE_KEYS = ["sketchbook", "cinematic_minimal", "dark_studio", "vibrant_illustrated"];
 const CAPTION_STYLE_KEYS = ["auto", "default", "hormozi", "glow_neon", "minimalist", "whiteboard"];
+/** Baked template recipes (mirrors src/data/videoTemplates.ts). Selecting one from
+ *  the gallery seeds these defaults so the user doesn't describe the style. */
+const VIDEO_TEMPLATES = {
+    screen_demo: {
+        output_format: "9x16",
+        caption_style: "hormozi",
+        direction: "Screen-demo style: fast caption-driven cuts on the beat, punch-in zoom to exactly where the on-screen " +
+            "action is each cut, meme captions, brand end card.",
+    },
+};
 /** Run the engine orchestrator, streaming its logs to stderr, and capture RESULT:<path>. */
 function runEngine(args, extraEnv = {}) {
     return new Promise((resolve, reject) => {
-        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(ENGINE_DIR, "assemble.mjs"), ...args], { cwd: ENGINE_DIR, env: { ...process.env, ...extraEnv } });
+        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(engine_js_1.ENGINE_DIR, "assemble.mjs"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env, ...extraEnv } });
         let stdout = "";
         child.stdout.on("data", (d) => { stdout += d.toString(); });
         child.stderr.on("data", (d) => process.stderr.write(d)); // progress → MCP server log
@@ -76,6 +117,14 @@ exports.createVideoAssemblyTool = {
                 enum: ["user_provided", "ai_generated"],
                 description: "B-roll source mode. 'user_provided' (default) = use local files or Google Photos. 'ai_generated' = AI reads the transcript and generates stylized cinematic B-roll images — no local footage needed. Requires the 'style' param.",
             },
+            destination: {
+                type: "string",
+                enum: ["local", "hosted"],
+                description: "Where the project lives. 'local' (default) = render on this machine, return an MP4 path (no upload; reads local disk). " +
+                    "'hosted' = create a Swap & Refine project on the user's ViralSpin account: local A-roll/B-roll are uploaded, the project " +
+                    "opens in the web editor, and follow-up swap_clip/suggest_clips (with its job_id) drive that same project. Use 'hosted' " +
+                    "when the user wants to refine in the browser or keep the project in their account.",
+            },
             style: {
                 type: "string",
                 enum: BROLL_STYLE_KEYS,
@@ -91,6 +140,14 @@ exports.createVideoAssemblyTool = {
                     "When set, long-form videos (>2 min) in the broll folder are searched semantically " +
                     "instead of being clipped from their start. Requires TWELVE_LABS_API_KEY in the MCP env.",
             },
+            template: {
+                type: "string",
+                enum: ["screen_demo"],
+                description: "Optional baked template (from the preview-and-select gallery). 'screen_demo' = the viral build-in-public " +
+                    "product-demo style: 9x16, fast beat-synced cuts, punch-in zoom to the on-screen action, meme captions, brand " +
+                    "end card. Seeds output_format + caption_style + creative direction so you don't describe the style; combine " +
+                    "with find_moments mode:'screen' snippets as the footage.",
+            },
             caption_style: {
                 type: "string",
                 enum: CAPTION_STYLE_KEYS,
@@ -106,6 +163,16 @@ exports.createVideoAssemblyTool = {
         required: ["aroll"],
     },
     async execute(args) {
+        // Baked template selected in the gallery → seed its recipe defaults (user's
+        // explicit args always win). The style intent rides `prompt`; the beat-grid +
+        // preset audio live engine-side (VIRALSPIN_VIDEO_TEMPLATE), consumed by the
+        // screen-demo assembly path.
+        if (args.template && VIDEO_TEMPLATES[args.template]) {
+            const t = VIDEO_TEMPLATES[args.template];
+            args.output_format = args.output_format ?? t.output_format;
+            args.caption_style = args.caption_style ?? t.caption_style;
+            args.prompt = args.prompt ? `${t.direction}\n${args.prompt}` : t.direction;
+        }
         // AI-generated B-roll mode: delegate to the cloud narrative pipeline.
         if (args.broll_mode === "ai_generated") {
             if (!args.style) {
@@ -135,6 +202,61 @@ exports.createVideoAssemblyTool = {
                 `Download: ${result.download_url ?? "—"}\n` +
                 `Publish it with publish_now or schedule_post.`);
         }
+        // Hosted project: create a Swap & Refine project (narrative job) on the
+        // user's account instead of rendering locally. Local files are uploaded to
+        // public URLs, then the web editor + the hosted swap_clip/suggest_clips verbs
+        // take over. This is the path that "merges" Claude with the web platform.
+        if (args.destination === "hosted") {
+            // Upload the A-roll (local path → public URL). A URL passes straight through.
+            const arollUrl = /^https?:\/\//i.test(args.aroll)
+                ? args.aroll
+                : (await (0, client_js_1.uploadFiles)([args.aroll])).urls[0];
+            // Resolve local B-roll (expand folders, upload files) + keep URL B-roll.
+            const { localFiles, urls } = partitionBroll(args.broll ?? []);
+            const uploadedUrls = localFiles.length ? (await (0, client_js_1.uploadFiles)(localFiles)).urls : [];
+            const brollItems = [...uploadedUrls, ...urls].map((url) => ({ url, kind: brollKind(url) }));
+            // Create the project. NOTE (verified against the live backend): a hosted
+            // user_provided job picks its INITIAL B-roll from the user's synced library
+            // / Google Photos picker — NOT from ad-hoc local files. (Contextual
+            // selection over an arbitrary local folder is the LOCAL engine's job.) So
+            // local/URL B-roll here is attached as a refine pool the editor + the
+            // swap verbs draw from, once the timeline is built.
+            const job = await (0, client_js_1.post)("/v1/narrative/jobs", {
+                aroll_paths: [arollUrl],
+                prompt: args.prompt,
+                output_format: args.output_format ?? "9x16",
+                broll_mode: "user_provided",
+                ...(args.template ? { template: args.template } : {}),
+                ...(args.google_picker_session ? { picker_session_id: args.google_picker_session } : {}),
+            });
+            // Attach local/URL B-roll once the build produces a timeline (the uploads
+            // endpoint 409s before then). Best-effort + bounded so we don't hang.
+            let attachNote = "";
+            if (brollItems.length) {
+                const r = await (0, hosted_js_1.attachUploadsWhenReady)(job.job_id, brollItems);
+                attachNote = r.attached
+                    ? `Attached ${brollItems.length} local/URL B-roll source(s) to the project's refine pool.\n`
+                    : `Queued ${brollItems.length} local/URL B-roll source(s), but they weren't attached yet (${r.detail}); add them in the editor's Upload tab.\n`;
+            }
+            const creditNote = job.credits_charged != null ? `Charged ${job.credits_charged} credits (${job.credits_remaining} left).\n` : "";
+            return (`Created a hosted Swap & Refine project (job ${job.job_id}).\n` +
+                creditNote +
+                `Open / refine it in the editor: ${(0, hosted_js_1.editorUrl)(job.job_id)}\n` +
+                attachNote +
+                (args.google_picker_session ? "" : "Heads up: initial B-roll is picked from your synced library / Google Photos — pass a Google Photos picker session for richer hosted B-roll.\n") +
+                `From here: suggest_clips(job_id: "${job.job_id}") to see the cutaways, then ` +
+                `swap_clip(job_id: "${job.job_id}", …) to change one — edits show up live in the editor.\n` +
+                `Tip: set VIRALSPIN_HOSTED_JOB_ID=${job.job_id} to make the swap verbs target this project by default.`);
+        }
+        // Local assembly shells out to the bundled engine. The public npm package
+        // ships WITHOUT it (the closed magic), so route the user to the hosted cloud
+        // pipeline instead of failing with an opaque spawn error.
+        if (!(0, engine_js_1.engineAvailable)()) {
+            return ("Local video assembly needs the ViralSpin engine, which isn't bundled in this install.\n" +
+                "Use the cloud pipeline instead: call create_video_assembly again with destination: \"hosted\" " +
+                "— it renders in the cloud and opens in the web Swap & Refine editor.\n" +
+                "(Advanced: set VIRALSPIN_ASSEMBLY_DIR to a local engine checkout to enable local rendering.)");
+        }
         const broll = [...(args.broll ?? [])];
         // Pull in Google Photos picks (re-hosted to public URLs by the backend), if any.
         if (args.google_picker_session) {
@@ -175,6 +297,11 @@ exports.createVideoAssemblyTool = {
         if (process.env.TWELVE_LABS_API_KEY) {
             extraEnv.TWELVE_LABS_API_KEY = process.env.TWELVE_LABS_API_KEY;
         }
+        if (args.template) {
+            // Engine reads this to apply the baked recipe (beat grid + preset audio +
+            // punch-in) in the screen-demo assembly path.
+            extraEnv.VIRALSPIN_VIDEO_TEMPLATE = args.template;
+        }
         const outPath = await runEngine(cli, extraEnv);
         return (`Video assembly complete.\n` +
             `Output: ${outPath}\n` +

package/package.json

@@ -1,29 +1,41 @@
-{
-  "name": "@viralspin/mcp",
-  "version": "0.2.0",
-  "description": "ViralSpin MCP server — publish local videos and carousels to TikTok, Instagram, and YouTube from Claude Code",
-  "main": "dist/index.js",
-  "bin": {
-    "viralspin-mcp": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "ts-node src/index.ts",
-    "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": ["mcp", "viralspin", "tiktok", "instagram", "youtube", "social-media"],
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "form-data": "^4.0.0"
-  },
-  "devDependencies": {
-    "@types/form-data": "^2.5.0",
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "@viralspin/mcp",
+  "version": "0.2.2",
+  "description": "ViralSpin MCP server — publish local videos and carousels to TikTok, Instagram, and YouTube from Claude Code",
+  "main": "dist/index.js",
+  "bin": {
+    "viralspin-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "viralspin",
+    "tiktok",
+    "instagram",
+    "youtube",
+    "social-media"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "form-data": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/form-data": "^2.5.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}