@viralspin/mcp 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ViralSpin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# ViralSpin MCP — the video editor your AI agent operates
+
+[![MCP Registry](https://img.shields.io/badge/MCP-registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=viralspin)
+[![npm](https://img.shields.io/badge/npm-%40viralspin%2Fmcp-red)](https://www.npmjs.com/package/@viralspin/mcp)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+Turn a talking-head clip + a folder of B-roll into a polished vertical short — and **let Claude do the edit**. Point it at your footage in plain English; it transcribes, picks B-roll cutaways matched to what's said, adds captions + a hook, and renders a 9:16 short. Then publishes to TikTok, Instagram, or YouTube. No timeline-wrangling required.
+
+> **The agent operates a real timeline.** Swap a clip, trim it, reorder scenes, cut a span — all by asking. Edits are instant; you render once when the cut is right.
+
+![demo](docs/demo.gif) <!-- TODO: the split-screen "Claude edits, clips stream onto the timeline" clip -->
+
+## Quick start
+
+```bash
+# Claude Code
+claude mcp add viralspin -- npx -y @viralspin/mcp
+
+# or Claude Desktop — add to claude_desktop_config.json:
+{
+  "mcpServers": {
+    "viralspin": { "command": "npx", "args": ["-y", "@viralspin/mcp"] }
+  }
+}
+```
+
+Then just ask:
+
+```
+Turn my A-roll at C:/clips/talk.mp4 into a 9:16 short, using B-roll
+from C:/my-broll and my Google Photos.
+
+Publish that to TikTok and Instagram with the caption: posting through the chaos.
+```
+
+## What the agent can do
+
+| Tool | What it does |
+|---|---|
+| `create_video_assembly` | A-roll + B-roll (local files, a folder, URLs, or Google Photos) → a rendered vertical short. Local or hosted. |
+| `suggest_clips` / `swap_clip` | See the cutaways; swap one for better-fitting B-roll (with a `reason`). |
+| `trim_clip` / `remove_span` / `reorder_scenes` | Granular timeline edits — instant, no re-render. |
+| `render_project` | Bake captions/overlays into the final MP4 (the one render). |
+| `publish_now` / `schedule_post` / `send_to_drafts` | Post to TikTok / Instagram / YouTube. |
+| `generate_caption`, `create_kinetic_text`, carousels, image ads | The rest of the content pipeline. |
+
+Edits are **instant and free** (they patch the timeline); `render_project` is the single cloud render. Iterate the cut as much as you like, then finalize once.
+
+## Open source
+
+The MCP server, the editor, and the agent verbs are **MIT** — use them free. Cloud generation (AI B-roll, rendering, publishing) runs on ViralSpin's infrastructure and is metered as credits; sign in at [viralspin.ai](https://www.viralspin.ai). You never paste an API key for the AI — the heavy lifting is server-side.
+
+- Listed in the official **MCP registry**: `ai.viralspin/viralspin`
+- Hosted connector (no install, for URL / Google Photos workflows): `https://mcp.viralspin.ai/mcp`
+
+## Local vs hosted
+
+- **Hosted (the default):** the cloud pipeline does the heavy lifting — assembly, AI B-roll, rendering — and every edit opens in the web Swap & Refine editor. B-roll from Google Photos / URLs / your synced library. Needs a [viralspin.ai](https://www.viralspin.ai) account (generation is metered as credits); no API keys to paste. The `mcp.viralspin.ai/mcp` hosted connector is the same, zero-install.
+- **Local (advanced):** point `VIRALSPIN_ASSEMBLY_DIR` at a local engine checkout to read your disk — index a folder of clips, select B-roll contextually, and render locally. The npm package ships without the engine, so the local-render tools route you to the hosted path until that env var is set.
+
+Either way, the agent reads local files *to upload them* (A-roll, a B-roll folder); only on-disk rendering needs the local engine.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.get = get;
 exports.post = post;
+exports.patch = patch;
 exports.pyGet = pyGet;
 exports.pyPost = pyPost;
 exports.del = del;
@@ -56,6 +57,13 @@ function post(endpoint, body) {
         body: JSON.stringify(body),
     });
 }
+function patch(endpoint, body) {
+    return apiFetch(endpoint, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
 /** Python backend helpers — for routes that live in viralspin-api (Higgsfield, OAuth, etc.) */
 function pyGet(endpoint) {
     return apiFetch(endpoint, { method: "GET" }, PY_API_URL);

package/dist/engine.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGINE_DIR = void 0;
+exports.engineAvailable = engineAvailable;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * The local Remotion assembly engine ships INSIDE this package (mcp/engine).
+ * At runtime __dirname = mcp/dist, so ../engine = mcp/engine. Override with
+ * VIRALSPIN_ASSEMBLY_DIR to point at a different engine checkout.
+ *
+ * NOTE: the published npm package ships WITHOUT the engine (it's the closed
+ * render/selection "magic" — see the OSS launch plan). Local-engine tools must
+ * therefore check engineAvailable() and degrade to a friendly message rather
+ * than failing with an opaque spawn error.
+ */
+exports.ENGINE_DIR = process.env.VIRALSPIN_ASSEMBLY_DIR || path_1.default.resolve(__dirname, "../engine");
+/** True when the local engine (with the given entry script) is present. */
+function engineAvailable(entry = "assemble.mjs") {
+    try {
+        return fs_1.default.existsSync(path_1.default.join(exports.ENGINE_DIR, entry));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/hosted.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editorUrl = editorUrl;
+exports.hostedJobId = hostedJobId;
+exports.getJob = getJob;
+exports.pollJob = pollJob;
+exports.attachUploadsWhenReady = attachUploadsWhenReady;
+exports.swapSegment = swapSegment;
+exports.setClipDuration = setClipDuration;
+exports.removeSpan = removeSpan;
+exports.detectScenes = detectScenes;
+exports.saveSceneOrder = saveSceneOrder;
+exports.rerender = rerender;
+exports.searchLibrary = searchLibrary;
+exports.listSegments = listSegments;
+/**
+ * Hosted Swap & Refine integration.
+ *
+ * The web Swap & Refine editor is the *narrative jobs* system: a "project" is a
+ * narrative job (`job_id`), its edit state lives in `job.timeline`, and B-roll
+ * swaps + re-renders go through endpoints that are ALREADY deployed and used by
+ * the browser editor (`/v1/narrative/jobs/...`). These helpers let the MCP edit
+ * verbs drive that same hosted project instead of the local on-disk engine, so a
+ * swap done from Claude shows up in the web editor (and the render lands in the
+ * user's Swap & Refine list). Local-engine behavior is untouched — the hosted
+ * path is opt-in (a `job_id` arg or the VIRALSPIN_HOSTED_JOB_ID env).
+ */
+const client_js_1 = require("./client.js");
+const APP_URL = (process.env.VIRALSPIN_APP_URL || "https://app.viralspin.ai").replace(/\/$/, "");
+/** Deep link to the project in the web Swap & Refine editor. */
+function editorUrl(jobId) {
+    return `${APP_URL}/swap-refine/${jobId}`;
+}
+/**
+ * The hosted project the edit verbs act on: an explicit `job_id` wins, else the
+ * VIRALSPIN_HOSTED_JOB_ID env (set after a hosted create_video_assembly), else
+ * null → the caller falls back to the local engine. This is the single switch
+ * that keeps existing local behavior the default.
+ */
+function hostedJobId(explicit) {
+    return explicit || process.env.VIRALSPIN_HOSTED_JOB_ID || null;
+}
+function getJob(jobId) {
+    return (0, client_js_1.get)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}`);
+}
+/** Poll until the job reaches a terminal state (complete/failed) or times out. */
+async function pollJob(jobId, timeoutMs = 15 * 60 * 1000) {
+    const deadline = Date.now() + timeoutMs;
+    let job = { id: jobId, status: "queued" };
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 6000));
+        job = await getJob(jobId);
+        if (job.status === "complete" || job.status === "failed")
+            break;
+    }
+    return job;
+}
+/**
+ * Attach B-roll uploads to a hosted project's refine pool, waiting for the
+ * pipeline to build a timeline first. The uploads endpoint 409s with
+ * "job has no timeline yet" until the build stage finishes (verified against the
+ * live backend 2026-06-22), so a fresh create can't attach immediately. Bounded
+ * poll; returns whether the attach landed.
+ */
+async function attachUploadsWhenReady(jobId, items, timeoutMs = 90000) {
+    if (!items.length)
+        return { attached: false, detail: "no items" };
+    const deadline = Date.now() + timeoutMs;
+    let lastDetail = "timed out before the project's timeline was ready";
+    while (Date.now() < deadline) {
+        const job = await getJob(jobId);
+        if (job.status === "failed")
+            return { attached: false, detail: "job failed before attach" };
+        const hasTimeline = !!(job.timeline && (job.timeline.aroll_url || (job.timeline.timeline?.length ?? 0)));
+        if (hasTimeline) {
+            try {
+                await (0, client_js_1.post)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}/uploads`, { items });
+                return { attached: true };
+            }
+            catch (e) {
+                lastDetail = e instanceof Error ? e.message : String(e);
+                if (!/no timeline yet/i.test(lastDetail))
+                    return { attached: false, detail: lastDetail };
+            }
+        }
+        await new Promise((r) => setTimeout(r, 5000));
+    }
+    return { attached: false, detail: lastDetail };
+}
+/** Replace one cutaway's B-roll in the stored timeline (same PATCH the editor
+ *  uses). `reason` is optional provenance — why the agent placed this clip; the
+ *  backend persists it when supported, and it's echoed back regardless. */
+function swapSegment(jobId, segmentId, assetUrl, assetKind, reason) {
+    return (0, client_js_1.patch)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}/swap`, {
+        segment_id: segmentId,
+        asset_url: assetUrl,
+        asset_kind: assetKind,
+        ...(reason ? { reason } : {}),
+    });
+}
+/** Shorten/restore a cutaway's on-screen duration (audio-safe — the backend
+ *  pairs the trim with A-roll filler so total length is preserved). */
+function setClipDuration(jobId, segmentId, durationSec) {
+    return (0, client_js_1.patch)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}/segment-duration`, {
+        segment_id: segmentId,
+        duration_sec: durationSec,
+    });
+}
+/** Cut a boundary-aligned span [fromSec,toSec] out of the output (e.g. a
+ *  duplicate opening line); backend trims the A-roll bed + re-renders. */
+function removeSpan(jobId, fromSec, toSec, render = true) {
+    return (0, client_js_1.post)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}/remove-span`, {
+        from_sec: fromSec,
+        to_sec: toSec,
+        render,
+    });
+}
+/** Detect (cached) the A-roll's backbone scenes — the reorderable building blocks. */
+function detectScenes(jobId) {
+    return (0, client_js_1.post)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}/scenes/detect`, {});
+}
+/** Persist a new running order / soft-removals for the backbone scenes. */
+function saveSceneOrder(jobId, scenes) {
+    return (0, client_js_1.post)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}/scenes/order`, { scenes });
+}
+/** Re-render the stored timeline after one or more swaps. Returns immediately. */
+function rerender(jobId) {
+    return (0, client_js_1.post)(`/v1/narrative/jobs/${encodeURIComponent(jobId)}/rerender`, {});
+}
+/**
+ * Text-search the user's analyzed B-roll library (matches each asset's Gemini
+ * tags — notes/subjects/emotion). The match is the "why this clip fits" signal
+ * we surface to the user when proposing a swap.
+ */
+function searchLibrary(q, limit = 12) {
+    return (0, client_js_1.get)(`/v1/assembly/search?q=${encodeURIComponent(q)}&limit=${limit}`);
+}
+/**
+ * Best-effort list of the timeline's B-roll cutaways (id + current asset + the
+ * beat text it covers) so the user/agent can see what to swap. Tolerant of the
+ * exact timeline JSON shape: tries the common array fields and degrades to [].
+ */
+function listSegments(timeline) {
+    if (!timeline || typeof timeline !== "object")
+        return [];
+    // The live shape stores the cut at `timeline.timeline` (an array that mixes the
+    // A-roll bed + B-roll cutaways); older/other shapes use segments/brolls/overlays.
+    const arr = timeline.timeline || timeline.segments || timeline.brolls || timeline.overlays || timeline.broll_overlays || [];
+    if (!Array.isArray(arr))
+        return [];
+    return arr
+        .filter((s) => s && (s.id || s.segment_id) && String(s.type ?? "") !== "aroll")
+        .map((s) => ({
+        id: String(s.id ?? s.segment_id),
+        beat: s.beat ?? s.label ?? s.caption ?? s.transcript ?? s.phrase ?? undefined,
+        asset_url: s.asset_url ?? s.url ?? undefined,
+        kind: s.type ?? s.kind ?? undefined,
+    }));
+}

package/dist/index.js

@@ -10,6 +10,16 @@ const carousel_video_js_1 = require("./tools/carousel-video.js");
 const video_assembly_js_1 = require("./tools/video-assembly.js");
 const photo_picker_js_1 = require("./tools/photo-picker.js");
 const assembly_adjust_js_1 = require("./tools/assembly-adjust.js");
+const timeline_edit_js_1 = require("./tools/timeline-edit.js");
+const folder_preview_js_1 = require("./tools/folder-preview.js");
+const find_moments_js_1 = require("./tools/find-moments.js");
+const local_mode_js_1 = require("./tools/local-mode.js");
+const color_grade_js_1 = require("./tools/color-grade.js");
+const edit_clip_js_1 = require("./tools/edit-clip.js");
+const relight_clip_js_1 = require("./tools/relight-clip.js");
+const ideas_js_1 = require("./tools/ideas.js");
+const local_index_js_1 = require("./tools/local-index.js");
+const profile_js_1 = require("./tools/profile.js");
 const posts_js_1 = require("./tools/posts.js");
 const captions_js_1 = require("./tools/captions.js");
 const engage_js_1 = require("./tools/engage.js");
@@ -28,6 +38,26 @@ const tools = [
     assembly_adjust_js_1.suggestClipsTool,
     assembly_adjust_js_1.swapClipTool,
     assembly_adjust_js_1.swapCaptionStyleTool,
+    timeline_edit_js_1.trimClipTool,
+    timeline_edit_js_1.removeSpanTool,
+    timeline_edit_js_1.reorderScenesTool,
+    timeline_edit_js_1.renderProjectTool,
+    timeline_edit_js_1.trimSilencesTool,
+    timeline_edit_js_1.getTranscriptTool,
+    timeline_edit_js_1.removeSpansTool,
+    timeline_edit_js_1.keepWindowsTool,
+    folder_preview_js_1.previewFolderTool,
+    find_moments_js_1.findMomentsTool,
+    local_mode_js_1.setLocalModeTool,
+    color_grade_js_1.colorGradeTool,
+    edit_clip_js_1.editRawClipTool,
+    relight_clip_js_1.relightClipTool,
+    ideas_js_1.queueIdeaTool,
+    ideas_js_1.listIdeasTool,
+    profile_js_1.setCreatorProfileTool,
+    profile_js_1.getCreatorProfileTool,
+    local_index_js_1.syncLocalIndexTool,
+    local_index_js_1.searchLocalIndexTool,
     posts_js_1.listPostsTool,
     posts_js_1.cancelPostTool,
     captions_js_1.generateCaptionTool,
@@ -45,32 +75,48 @@ const tools = [
 // Shown to the user as the welcome / getting-started message. The agent fills in
 // <picker link> by calling start_photo_picker (per ONBOARDING below).
 const SAMPLE_COMMANDS = [
-    '1. Make a video:  "Turn my A-roll at C:/clips/talk.mp4 into a 9:16 short, using B-roll from C:/my-broll and my Google Photos."',
-    '2. Publish it:    "Publish that video to TikTok and Instagram with the caption: posting through the chaos."',
+    "Try one of these — I'll open a DRAFT in your ViralSpin editor for you to review side-by-side:",
+    "",
+    'SIMPLE — a quick short:',
+    '   "Turn my talking-head at C:/clips/talk.mp4 into a 9:16 TikTok short — pull B-roll from',
+    '    C:/my-broll and my Google Photos, add captions, and show me the draft."',
+    "",
+    'COMPREHENSIVE — hook + story + scheduled publish (the full loop):',
+    '   "Make a hosted reel. Open on the strongest surprise/reveal clip from C:/footage/hooks with the',
+    '    title \'Claude just killed video editors\', then tell the story of how AI is replacing video editors',
+    '    using the clips in C:/footage/story. Build a story arc that fits the footage, caption it, and show',
+    '    me the draft to review. Once I approve, schedule it to Instagram and TikTok next Tuesday at 8pm."',
 ].join("\n");
 const WELCOME = [
-    "Welcome to ViralSpin. I turn a talking-head A-roll into a polished vertical short —",
-    "B-roll cutaways matched to what you say, captions, a hook headline, and keyword pops —",
-    "then publish it to TikTok, Instagram, or YouTube. B-roll can be local files, a local",
-    "folder (auto-indexed), public URLs, and/or your Google Photos.",
+    "Welcome to ViralSpin. I turn your footage into polished vertical shorts — B-roll matched to",
+    "what's said, captions, a hook headline — then PUBLISH or SCHEDULE them to TikTok, Instagram,",
+    "or YouTube. I open every project as a DRAFT in your web editor so you can watch it come together",
+    "and tweak it side-by-side. B-roll can be local files, a local folder (auto-indexed), URLs, or Google Photos.",
     "",
-    "Two commands to get you started:",
     SAMPLE_COMMANDS,
 ].join("\n");
 // Auto-injected into the agent's context when the server connects. Drives proactive onboarding.
 const INSTRUCTIONS = [
-    "ViralSpin assembles A-roll + B-roll into polished vertical shorts and publishes them to TikTok/Instagram/YouTube.",
+    "ViralSpin assembles footage into polished vertical shorts and PUBLISHES/SCHEDULES them to TikTok/Instagram/YouTube — edit AND ship, all from chat, with a live web editor the user watches side-by-side.",
     "",
-    "ONBOARDING: The FIRST time you help the user with ViralSpin in a session, proactively onboard them:",
-    "(1) give the short intro below, (2) CALL start_photo_picker so they get a live Google Photos B-roll picker link, and",
-    "(3) show these two sample commands verbatim:",
+    "ONBOARDING: The FIRST time you help the user in a session: (1) give the intro below, (2) CALL start_photo_picker for a Google Photos B-roll picker link, and (3) show the TWO ready-to-run use cases verbatim (a SIMPLE one and a COMPREHENSIVE one):",
     SAMPLE_COMMANDS,
     "",
-    "HOW B-ROLL WORKS: create_video_assembly accepts local file paths, a local FOLDER (auto-expanded and indexed),",
-    "public URLs, and Google Photos. For Google Photos: call start_photo_picker → it returns a browser link + sessionId;",
-    "the user picks in their browser (Google forbids listing albums programmatically), then call create_video_assembly",
-    "with google_picker_session set to that sessionId. Pass style_ref (a reference video) to auto-infer captions/hook/pace/aspect.",
-    "After rendering, publish with publish_now or schedule_post.",
+    "DRAFT-FIRST WORKFLOW: For anything beyond a trivial one-off, create a HOSTED project (create_video_assembly destination:\"hosted\") so it opens in the web Swap & Refine editor — the user reviews it side-by-side while you work. You HAVE FREEDOM to pick the clips that best match the user's intent: use suggest_clips to search their analyzed library by MEANING (e.g. a 'surprise/reveal' hook), and build a story arc + hook title that fits the AVAILABLE B-roll. Return the editor link as a DRAFT and invite review. Refine on request with swap_clip / trim_clip / reorder_scenes / remove_span (these stream live into the editor), then render_project. NEVER auto-publish — call publish_now / schedule_post ONLY after the user approves the draft. For 'schedule … next Tuesday 8pm' use schedule_post with that time.",
+    "",
+    "HOW B-ROLL WORKS: create_video_assembly accepts local file paths, a local FOLDER (auto-expanded + indexed), public URLs, and Google Photos. Hosted user_provided B-roll comes from the synced library / Google Photos picker (call start_photo_picker → user picks → pass google_picker_session). Pass style_ref (a reference video) to auto-infer captions/hook/pace/aspect.",
+    "",
+    "COST GATE: before assembling a LARGE local folder, call preview_folder first — it counts the clips so you can warn the user (each is analyzed + charged on create) and CONFIRM before spending credits.",
+    "",
+    "SMART CUTS (you read the transcript, you decide what to cut — no extra vendor): 'edit out the dead air' → trim_silences. 'Remove the bad takes / restarts / repeats' → get_transcript, identify the bad spans yourself, then remove_spans. 'Find the best moments in this long recording / make a highlight reel' → get_transcript, pick the punchy windows, then keep_windows (keeps only those, cuts the rest). This is the cheap moment-search path for talking/narrated long videos — uses the Whisper transcript + your judgment, no Twelve Labs.",
+    "",
+    "LONG / SILENT VIDEO → REEL: for a long or silent local video (e.g. a screen recording), run find_moments(extract:true) — it scores frames with the vision model (free on the user's GPU when local mode is on) and cuts the highlights into small clips LOCALLY. Then build the reel with create_video_assembly using those clips: destination:'hosted' uploads ONLY the snippets (not the long source) + opens the web editor (DEFAULT); destination:'local' keeps everything on-device with no upload (fully private). Same analysis, two destinations — let the user pick privacy vs the web editor.",
+    "",
+    "LOOK / LIGHTING: 'make it cinematic' / 'add a teal-orange (or noir / warm / moody) look' → color_grade — FREE, instant ffmpeg LUT looks, no cost, great on the A-roll or any clip (call with no `look` to list them). 'Relight this / change the lighting / put me in [a scene] / re-scene it' → relight_clip — PAID Fal.ai (best on B-roll + short 3–10s hero shots; can change background + add real directional light). ALWAYS show the cost and get explicit confirmation before relight_clip's paid video step (it's two-call: preview the frame first, then confirm:true). Default to the free color_grade unless the user wants a true relight / new background.",
+    "",
+    "IDEA PIPELINE (brainstorm → execute, persistent): when the user wants content ideas or pastes a saved/liked post URL they want to replicate — (1) analyze it + identify their core topics, (2) write a teleprompter-ready SCRIPT, (3) find what they ALREADY have: search_local_index for their local footage (run sync_local_index on their folders first so it's catalogued) + suggest_clips for cloud library, (4) build a per-shot ASSET PLAN — reuse an existing clip, else AI-generate B-roll (theme), pull a web image (logo/person), add a kinetic-text overlay, or tell them to FILM the missing shot, (5) queue_idea it (hook + script + asset_plan + source_url). It persists cross-browser in /spin/history; the user films the script on the teleprompter at /create and the plan says what B-roll to use vs shoot. Recommend the BEST B-roll option per shot. Use list_ideas to resume / pick the next idea to execute.",
+    "",
+    "WEEKLY IDEA ENGINE: at setup, learn the user's context — call get_creator_profile; if empty, read their connected accounts via list_connections and/or ASK for their niche + handles, then set_creator_profile. To seed a week's ideas: research what's WORKING in their niche — top-performing short-form on TikTok / Instagram / YouTube Shorts (YouTube Shorts has the cleanest 'top by views' signal; for IG/TikTok use WebSearch + the Discover feature), and factor in the user's OWN account insights — then generate 5 ideas and queue_idea each with the SAME `week` tag (e.g. '2026-W27') and a `format` ('video' = film off the teleprompter at /create; 'carousel' = image carousel for a niche news item). They appear as a week-tab set in /spin/history. Offer to make this a WEEKLY ROUTINE (a scheduled run that re-seeds 5 ideas each week) and set weekly_routine via set_creator_profile.",
 ].join("\n");
 const server = new index_js_1.Server({ name: "viralspin", version: "0.1.0" }, { capabilities: { tools: {}, prompts: {} }, instructions: INSTRUCTIONS });
 server.setRequestHandler(types_js_1.ListPromptsRequestSchema, async () => ({

package/dist/sanitize.js

@@ -0,0 +1,22 @@
+"use strict";
+// Strips unpaired UTF-16 surrogates from strings so MCP responses can be
+// safely JSON-serialized and written to the stdio transport. Lone surrogates
+// (e.g. an emoji's surrogate pair cut in half by a fixed-length .slice) cause
+// the transport's UTF-8 encoder to throw "no low surrogate in string".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeSurrogates = sanitizeSurrogates;
+exports.sanitizeObject = sanitizeObject;
+const UNPAIRED_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+function sanitizeSurrogates(str) {
+    return str.replace(UNPAIRED_SURROGATE, "");
+}
+function sanitizeObject(obj) {
+    if (typeof obj === "string")
+        return sanitizeSurrogates(obj);
+    if (Array.isArray(obj))
+        return obj.map(sanitizeObject);
+    if (obj && typeof obj === "object") {
+        return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, sanitizeObject(v)]));
+    }
+    return obj;
+}

package/dist/tools/assembly-adjust.js

@@ -6,13 +6,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.swapCaptionStyleTool = exports.swapClipTool = exports.suggestClipsTool = void 0;
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
-// Adjustment tools operate on the most recent create_video_assembly project (the engine keeps the
-// timeline + analyzed candidate pool + staged clips on disk), so suggesting is instant and swapping
-// just re-renders. Same engine dir as create_video_assembly.
-const ENGINE_DIR = process.env.VIRALSPIN_ASSEMBLY_DIR || "E:/AI test/carissa bot/assembly-engine";
+const hosted_js_1 = require("../hosted.js");
+const engine_js_1 = require("../engine.js");
+// Adjustment tools operate on the most recent create_video_assembly project. By
+// default that's the LOCAL engine project (the engine keeps the timeline +
+// analyzed candidate pool + staged clips on disk), so suggesting is instant and
+// swapping just re-renders locally. When a hosted project is targeted instead —
+// a `job_id` arg, or the VIRALSPIN_HOSTED_JOB_ID env set by a hosted
+// create_video_assembly — the same verbs drive the web Swap & Refine project via
+// the deployed narrative endpoints, so the edit shows up in the browser editor.
+// Shown when a local action is requested but no engine is bundled (the public
+// npm package) and no hosted project is targeted.
+const NO_LOCAL_ENGINE = "This local action needs the ViralSpin engine, which isn't bundled in this install.\n" +
+    "Target a hosted Swap & Refine project instead — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID) — " +
+    "or set VIRALSPIN_ASSEMBLY_DIR to a local engine checkout.";
 function runEngine(args) {
     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 } });
+        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 } });
         let stdout = "";
         child.stdout.on("data", (d) => { stdout += d.toString(); });
         child.stderr.on("data", (d) => process.stderr.write(d));
@@ -22,17 +32,56 @@ function runEngine(args) {
 }
 exports.suggestClipsTool = {
     name: "suggest_clips",
-    description: "Get ranked alternative B-roll for one cutaway in the most recently assembled video (from create_video_assembly). " +
-        "Returns options ranked by how well they fit that moment's transcript, each with a thumbnail image path you can open. " +
-        "Then call swap_clip to apply a choice. Instant — reuses the cached analysis, no re-render.",
+    description: "See a project's cutaways and find better B-roll for one of them. " +
+        "LOCAL project (default): pass `cut` (0-based) to get ranked alternatives for that cutaway, each with a thumbnail. " +
+        "HOSTED Swap & Refine project (pass `job_id`, or set VIRALSPIN_HOSTED_JOB_ID): " +
+        "call with no `query` to list the timeline's cutaways (segment id + the beat each covers + current clip); " +
+        "call with `query` (e.g. \"newborn in hospital\") to search the user's B-roll library — each result includes the " +
+        "library tags it matched on, which is the 'why this clip fits' to show the user. " +
+        "Then call swap_clip to apply a choice.",
     inputSchema: {
         type: "object",
         properties: {
-            cut: { type: "number", description: "Index of the cutaway to replace (0-based; from the cut list create_video_assembly returns)." },
+            cut: { type: "number", description: "LOCAL only: index of the cutaway to replace (0-based; from the cut list create_video_assembly returns)." },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project (narrative job) to inspect. Omit to use VIRALSPIN_HOSTED_JOB_ID, or the local project." },
+            query: { type: "string", description: "HOSTED: theme to search the B-roll library for (the moment's subject). Omit to list the timeline's cutaways instead." },
         },
-        required: ["cut"],
     },
     async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            // Hosted project: either list the timeline's cutaways, or search the
+            // library for alternatives (with the matched tags = the "why").
+            if (args.query) {
+                const r = await (0, hosted_js_1.searchLibrary)(args.query);
+                if (!r.items.length)
+                    return `No library B-roll matched "${args.query}". Try a broader term.`;
+                const lines = r.items.map((it, i) => `${i + 1}. ${it.url}\n   ${it.kind}${it.album ? ` · from "${it.album}"` : ""} — matched on: "${args.query}"`);
+                return [
+                    `B-roll matching "${args.query}" (best fit first):`,
+                    ...lines,
+                    ``,
+                    `Apply one with: swap_clip(job_id: "${jobId}", segment_id: "<from the cutaway list>", asset_url: "<url above>").`,
+                ].join("\n");
+            }
+            const job = await (0, hosted_js_1.getJob)(jobId);
+            const segs = (0, hosted_js_1.listSegments)(job.timeline);
+            if (!segs.length) {
+                return `Project ${jobId} has no listable cutaways yet (status: ${job.status}). Open it: ${(0, hosted_js_1.editorUrl)(jobId)}`;
+            }
+            const lines = segs.map((s, i) => `${i + 1}. segment ${s.id}${s.beat ? ` — "${s.beat}"` : ""}${s.asset_url ? `\n   current: ${s.asset_url}` : ""}`);
+            return [
+                `Cutaways in ${(0, hosted_js_1.editorUrl)(jobId)} :`,
+                ...lines,
+                ``,
+                `Find alternatives for one: suggest_clips(job_id: "${jobId}", query: "<what that moment is about>").`,
+            ].join("\n");
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
+        if (args.cut === undefined) {
+            return "For a local project, pass `cut` (the 0-based cutaway index). For a hosted Swap & Refine project, pass `job_id`.";
+        }
         const out = await runEngine(["--suggest", String(args.cut)]);
         const m = out.match(/SUGGEST:(.+)/);
         if (!m)
@@ -50,17 +99,49 @@ exports.suggestClipsTool = {
 };
 exports.swapClipTool = {
     name: "swap_clip",
-    description: "Replace one cutaway in the most recently assembled video with a chosen B-roll asset (from suggest_clips), then re-render. " +
-        "Returns the path to the updated MP4.",
+    description: "Replace one cutaway with a chosen B-roll asset (from suggest_clips), then re-render. " +
+        "LOCAL project (default): pass `cut` (0-based) + `asset` (filename) → re-renders locally, returns the MP4 path. " +
+        "HOSTED Swap & Refine project (pass `job_id`, or set VIRALSPIN_HOSTED_JOB_ID): pass `segment_id` + `asset_url` → " +
+        "patches the same timeline the browser editor shows and kicks off a cloud re-render; the change appears live in " +
+        "Swap & Refine. Returns immediately — the new preview lands on the project shortly.",
     inputSchema: {
         type: "object",
         properties: {
-            cut: { type: "number", description: "Index of the cutaway to replace (0-based)." },
-            asset: { type: "string", description: "Asset filename from suggest_clips (e.g. \"v03.mp4\" or \"07.jpg\")." },
+            cut: { type: "number", description: "LOCAL: index of the cutaway to replace (0-based)." },
+            asset: { type: "string", description: "LOCAL: asset filename from suggest_clips (e.g. \"v03.mp4\" or \"07.jpg\")." },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            segment_id: { type: "string", description: "HOSTED: the cutaway's segment id (from suggest_clips)." },
+            asset_url: { type: "string", description: "HOSTED: public URL of the replacement B-roll (from suggest_clips)." },
+            asset_kind: { type: "string", enum: ["broll_video", "broll_photo"], description: "HOSTED: optional — kind of the replacement asset." },
+            reason: { type: "string", description: "HOSTED: optional one-line rationale for WHY this clip fits here (e.g. \"the line says 'the day she arrived'\"). Stored as provenance + shown on the timeline." },
+            render: { type: "boolean", description: "HOSTED: re-render now (costs a render/credits). Default false = instant timeline-only edit; iterate freely, then call render_project once to bake & publish." },
         },
-        required: ["cut", "asset"],
     },
     async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            if (!args.segment_id || !args.asset_url) {
+                return "For a hosted project, pass `segment_id` and `asset_url` (both from suggest_clips).";
+            }
+            let kind = args.asset_kind;
+            if (!kind)
+                kind = /\.(mp4|mov|webm|m4v)(\?|$)/i.test(args.asset_url) ? "broll_video" : "broll_photo";
+            await (0, hosted_js_1.swapSegment)(jobId, args.segment_id, args.asset_url, kind, args.reason);
+            if (args.render) {
+                await (0, hosted_js_1.rerender)(jobId);
+                return (`Swapped segment ${args.segment_id} → ${args.asset_url}${args.reason ? ` (${args.reason})` : ""} and started a cloud re-render.\n` +
+                    `Updating live in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+                    `Publish it with publish_now or schedule_post once it finishes.`);
+            }
+            return (`Swapped segment ${args.segment_id} → ${args.asset_url}${args.reason ? ` (${args.reason})` : ""} (instant, no render).\n` +
+                `Keep editing freely — it's all on the timeline. Open: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+                `When the cut is right, call render_project(job_id: "${jobId}") to bake captions/overlays and get the final MP4.`);
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
+        if (args.cut === undefined || !args.asset) {
+            return "For a local project, pass `cut` and `asset`. For a hosted Swap & Refine project, pass `job_id`, `segment_id`, and `asset_url`.";
+        }
         const out = await runEngine(["--swap", String(args.cut), args.asset]);
         const m = out.match(/RESULT:(.+)/);
         if (!m)
@@ -87,10 +168,21 @@ exports.swapCaptionStyleTool = {
                     "minimalist = lowercase thin font fade-in (calm, educational). " +
                     "whiteboard = text revealed left-to-right (explainers, tutorials).",
             },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID or the local project." },
         },
         required: ["caption_style"],
     },
     async execute(args) {
+        // Hosted projects set caption style via the editor's render options; there's
+        // no standalone caption-swap endpoint to drive from here yet. Be explicit
+        // rather than hit a guessed route.
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            return (`Caption style isn't swappable from here for hosted Swap & Refine projects yet — ` +
+                `set it in the editor: ${(0, hosted_js_1.editorUrl)(jobId)} (this is the next slice to wire up).`);
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
         const out = await runEngine(["--caption-style", args.caption_style, "--swap-caption-style"]);
         const m = out.match(/RESULT:(.+)/);
         if (!m)

package/dist/tools/carousel-video.js

@@ -71,6 +71,12 @@ exports.publishCarouselAsVideoTool = {
                 items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
                 description: "Platforms to publish to. Must be connected. For mode='draft', Instagram is not allowed (no IG drafts API).",
             },
+            account_ids: {
+                type: "array",
+                items: { type: "string" },
+                description: "Specific connection IDs (from list_connections) to target. REQUIRED when you have multiple accounts on a platform — " +
+                    "without it the post fans out to EVERY connected account on the platform (e.g. a draft landing on the wrong handle).",
+            },
             caption: { type: "string", description: "Post caption." },
             hashtags: {
                 type: "array",
@@ -158,6 +164,7 @@ exports.publishCarouselAsVideoTool = {
                 media_urls: upload.urls,
                 media_type: "video",
                 platforms: args.platforms,
+                ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
                 caption: args.caption,
                 hashtags: args.hashtags ?? [],
                 publish_now: true,