@viralspin/mcp 0.1.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,22 +5,33 @@ 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;
 exports.uploadFiles = uploadFiles;
 exports.deleteFiles = deleteFiles;
-const form_data_1 = __importDefault(require("form-data"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const API_URL = (process.env.VIRALSPIN_API_URL || "https://viralspinbackend.onrender.com").replace(/\/$/, "");
+// Python backend — Higgsfield, review-sessions, OAuth, narrative-render
+const PY_API_URL = (process.env.VIRALSPIN_PY_API_URL || "https://viralspin-api.onrender.com").replace(/\/$/, "");
 const API_KEY = process.env.VIRALSPIN_API_KEY || "";
-if (!API_KEY) {
-    process.stderr.write("[viralspin-mcp] Warning: VIRALSPIN_API_KEY not set\n");
+// OAuth token takes precedence over API key (set after "Sign in with ViralSpin" flow)
+const OAUTH_TOKEN = process.env.VIRALSPIN_OAUTH_TOKEN || "";
+if (!API_KEY && !OAUTH_TOKEN) {
+    process.stderr.write("[viralspin-mcp] Warning: Neither VIRALSPIN_API_KEY nor VIRALSPIN_OAUTH_TOKEN is set\n");
 }
 function headers(extra = {}) {
+    // OAuth Bearer token (from "Sign in with ViralSpin" flow) takes priority
+    if (OAUTH_TOKEN) {
+        return { "Authorization": `Bearer ${OAUTH_TOKEN}`, ...extra };
+    }
+    // Legacy API key — retained for backward compatibility with personal installs
     return { "X-API-Key": API_KEY, ...extra };
 }
-async function apiFetch(endpoint, init = {}) {
-    const url = `${API_URL}${endpoint}`;
+async function apiFetch(endpoint, init = {}, base = API_URL) {
+    const url = `${base}${endpoint}`;
     const resp = await fetch(url, {
         ...init,
         headers: { ...(init.headers ?? {}), ...headers() },
@@ -46,6 +57,24 @@ 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);
+}
+function pyPost(endpoint, body) {
+    return apiFetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, PY_API_URL);
+}
 function del(endpoint, body) {
     return apiFetch(endpoint, {
         method: "DELETE",
@@ -55,15 +84,32 @@ function del(endpoint, body) {
 }
 /** Upload one or more local files. Returns { url, storage_path } or { urls, storage_paths } */
 async function uploadFiles(filePaths) {
-    const form = new form_data_1.default();
+    // Use the native Web FormData + Blob (Node 18+). The npm 'form-data' package
+    // streams in a way native fetch can't serialize correctly, which previously
+    // caused Busboy on the backend to fail with "Failed to parse upload".
+    const form = new FormData();
     const fieldName = filePaths.length === 1 ? "file" : "files";
     for (const fp of filePaths) {
-        form.append(fieldName, fs_1.default.createReadStream(fp), path_1.default.basename(fp));
+        const buffer = await fs_1.default.promises.readFile(fp);
+        const ext = path_1.default.extname(fp).toLowerCase();
+        const mime = ext === ".png" ? "image/png" :
+            ext === ".jpg" || ext === ".jpeg" ? "image/jpeg" :
+                ext === ".gif" ? "image/gif" :
+                    ext === ".webp" ? "image/webp" :
+                        ext === ".mp4" ? "video/mp4" :
+                            ext === ".mov" ? "video/quicktime" :
+                                ext === ".webm" ? "video/webm" :
+                                    "application/octet-stream";
+        const blob = new Blob([buffer], { type: mime });
+        form.append(fieldName, blob, path_1.default.basename(fp));
     }
+    const authHeader = OAUTH_TOKEN
+        ? { "Authorization": `Bearer ${OAUTH_TOKEN}` }
+        : { "X-API-Key": API_KEY };
     const resp = await fetch(`${API_URL}/v1/media/upload`, {
         method: "POST",
-        headers: { "X-API-Key": API_KEY, ...form.getHeaders() },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        // Don't set Content-Type manually — fetch will set it with the correct multipart boundary.
+        headers: authHeader,
         body: form,
     });
     if (!resp.ok) {

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

@@ -6,17 +6,145 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const connections_js_1 = require("./tools/connections.js");
 const publish_js_1 = require("./tools/publish.js");
+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");
+const explainer_index_js_1 = require("./tools/explainer-index.js");
+const kinetic_text_js_1 = require("./tools/kinetic-text.js");
+const review_js_1 = require("./tools/review.js");
+const image_ads_js_1 = require("./tools/image-ads.js");
 const tools = [
     connections_js_1.listConnectionsTool,
     publish_js_1.publishNowTool,
     publish_js_1.schedulePostTool,
+    publish_js_1.sendToDraftsTool,
+    carousel_video_js_1.publishCarouselAsVideoTool,
+    video_assembly_js_1.createVideoAssemblyTool,
+    photo_picker_js_1.startPhotoPickerTool,
+    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,
+    engage_js_1.setKeywordLinkTool,
+    engage_js_1.listKeywordLinksTool,
+    engage_js_1.deleteKeywordLinkTool,
+    explainer_index_js_1.indexExplainerSourcesTool,
+    kinetic_text_js_1.createKineticTextTool,
+    review_js_1.createReviewLinkTool,
+    review_js_1.checkReviewStatusTool,
+    image_ads_js_1.prepareProductAssetTool,
+    image_ads_js_1.assembleImageAdTool,
+    image_ads_js_1.publishToMetaTool,
 ];
-const server = new index_js_1.Server({ name: "viralspin", version: "0.1.0" }, { capabilities: { 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 = [
+    "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 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.",
+    "",
+    SAMPLE_COMMANDS,
+].join("\n");
+// Auto-injected into the agent's context when the server connects. Drives proactive onboarding.
+const INSTRUCTIONS = [
+    "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 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,
+    "",
+    "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 () => ({
+    prompts: [
+        {
+            name: "getting_started",
+            description: "Welcome + how to use ViralSpin: intro, a Google Photos B-roll picker link, and two sample commands.",
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.GetPromptRequestSchema, async (req) => {
+    if (req.params.name !== "getting_started") {
+        throw new Error(`Unknown prompt: ${req.params.name}`);
+    }
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: WELCOME +
+                        "\n\nNow call start_photo_picker and include the returned Google Photos picker link in your reply, " +
+                        "so I can pick B-roll. Keep the two sample commands above in your reply.",
+                },
+            },
+        ],
+    };
+});
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
         name: t.name,

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