@viralspin/mcp 0.1.0 → 0.2.0

package/BUNDLE_LOCAL_SPEC.md

@@ -0,0 +1,133 @@
+# Bundle-Local Spec — `@viralspin/mcp` local video-assembly
+
+Status: proposed. Owner: Allen. Last updated: 2026-05-24.
+
+## 1. Goal
+
+Let any ViralSpin user produce a polished vertical short from **their own local files**
+(local A-roll + local B-roll folders) and/or Google Photos, with **zero key management**
+and a **one-time ~10-minute install** — driven entirely by natural language.
+
+Target UX (the literal command from day one of this work):
+
+> "Create a video with A-roll `E:\...\test.mp4`, B-roll from `E:\PickedByCarissa` and my Google Photos."
+
+The agent recognizes the local paths, realizes the cloud connector can't read local disk,
+offers a one-time local install (~10 min, with consent), then runs the assembly. Gemini /
+AI cost runs on **ViralSpin's** key server-side and is metered as **credits**. The user
+never sees or pastes an API key.
+
+## 2. Current state (2026-05-24)
+
+- **Engine** (`E:\AI test\carissa bot\assembly-engine\`) — Node orchestrator (`assemble.mjs`)
+  + Python Gemini scripts (`transcribe.py`, `analyze.py`, `edit.py`, `albums.py`, `style.py`)
+  + parameterized Remotion composition (`src/Assembly.tsx` / `Root.tsx`). Produces the
+  cindyzhu-style edit (captions + hook + keyword pops + fast focal-anchored cuts).
+  **Not in the repo**; referenced by `VIRALSPIN_ASSEMBLY_DIR` (defaults to the carissa path).
+- **MCP** (`mcp/`, this package) — stdio server. `create_video_assembly` + `start_photo_picker`
+  shell out to the engine. **Merged to main (PR #93)** but the engine is still external.
+- **Backend** — `/v1/assembly/picker` (POST create picker session, GET poll → re-host picks to
+  public `narrative` bucket URLs) is **live**. Hosted `viralspin_create_video_assembly`
+  (URL-only, older pipeline) is unchanged.
+- **Two credentials today** (both need to disappear from the user's view):
+  1. `VITE_GEMINI_API_KEY` — engine calls Gemini directly from a local `.env`. **Blocker for
+     distribution** (would be baked into shipped code).
+  2. `vs_…` token — per-user ViralSpin auth, currently hand-pasted into the MCP config env.
+
+## 3. Target architecture
+
+```
+natural-language command
+        │
+        ▼
+  Agent (Claude Code / Desktop, local shell)
+        │  detects local E:\ paths → cloud can't read disk
+        │  one-time consent → installs local helper (.mcpb / npx)  ── §4F
+        ▼
+  Local @viralspin/mcp (stdio, self-contained: Node + ffmpeg-static + Remotion/Chromium) ── §4B
+        │  transcribe / analyze / edit / style  ── all Node ── §4A
+        │  AI calls → ViralSpin backend proxy (no Gemini key locally) ── §4C
+        │  auth via login-provisioned token (no pasted vs_) ── §4D
+        │  persistent analysis cache (path+size+mtime) ── §4E
+        ▼
+  Remotion render (local CPU) → out.mp4 → publish_now / schedule_post
+```
+
+## 4. Workstreams
+
+### A. Port Python → Node (remove the Python dependency)
+Reimplement `transcribe.py`, `analyze.py`, `edit.py`, `albums.py`, `style.py` in TypeScript.
+- Keep the exact contracts (focal `{subject,focal_x,focal_y,secondary,desc,keywords}`;
+  editorial output `{hook,pops,cuts}`; album weights; style `{format,captions,hook,pops,pace,coverage}`).
+- Preserve the hard-won Gemini settings: `thinkingConfig.thinkingBudget=0` +
+  `responseMimeType:application/json` (gemini-2.5-flash is a thinking model — without this it
+  burns the token budget on hidden thinking and returns empty text).
+- Keep "transcribe FIRST → drives album ranking + B-roll selection + captions" ordering.
+
+### B. Bundle the runtime into the package
+- `ffmpeg-static` (transcode A-roll, stage B-roll, extract audio, mid-frame for video analysis).
+- Remotion + its headless Chromium (the ~hundreds-of-MB download → the bulk of the 10 min).
+- Vendor the composition (`Assembly.tsx`/`Root.tsx`) inside the package.
+- Result: `@viralspin/mcp` runs with only Node present; no external engine dir,
+  no system ffmpeg, no Python.
+
+### C. Proxy AI through the backend (credits, no user Gemini key)  ← enables distribution
+- New backend endpoints (X-API-Key / token authed) that wrap the Gemini calls the engine makes:
+  transcription, per-asset vision analysis, editorial pass, style inference.
+- Server holds the Gemini key. Each call **debits credits** against the user's account.
+- Local engine calls these instead of Gemini directly → no key ships to clients.
+- Decide credit pricing per render (≈ #assets analyzed + 1 transcript + 1 editorial + optional style).
+
+### D. Token provisioning via login (no pasted `vs_`)
+- A connect/login flow writes the user's token into the MCP config automatically
+  (or the helper fetches it post-login). User funds credits; never handles a key.
+- Token identifies whose credits to charge and whose Google account the picker uses.
+
+### E. Persistent analysis cache
+- Key each analyzed asset by `path + size + mtime` (and a content hash for URLs).
+- A 1000-item folder is indexed **once**; re-runs / edits skip re-analysis (huge cost + time win).
+- Cache lives under the package's data dir; survives across renders.
+
+### F. Packaging, distribution, auto-install
+- Primary: **`.mcpb` Claude Desktop extension** — double-click install, bundles Node.
+- Secondary: `npx @viralspin/mcp` / install script for Claude Code (`claude mcp add`).
+- **Client-side auto-install trigger**: the agent (not the cloud connector — it has no disk
+  access) detects local paths in the request and offers the one-time setup **with explicit
+  consent**. Never install silently.
+- Note the **reconnect seam**: adding a stdio server still requires the client to spawn it;
+  today that means "restart once" after first install. (`/mcp` reconnect re-attaches to the
+  existing child — it does NOT pick up a freshly installed/rebuilt server.)
+
+### G. Adjustment tools (post-MVP)
+On a persisted "project" (editData + cached candidate pool + transcript), conversational edits:
+`suggest_clips(cut)` → ranked alternatives w/ thumbnails, `swap_clip(cut,choice)` → re-render
+(~1 min local), plus remove / add / reframe / set_hook / edit_caption / set_pace.
+
+### H. Optional server-side render (zero-install fallback)
+For users who can't/won't install: render on ViralSpin infra (your compute → more credits).
+Trade-off: no local-file capability (must upload), but truly zero-setup.
+
+## 5. End-to-end UX (target)
+
+1. User signs in to ViralSpin, funds credits (one time). Token provisioned silently.
+2. Adds the ViralSpin connector — enough on its own for URL / Google-Photos → server-side render.
+3. Types a command referencing local files. Agent: *"This needs a one-time ~10-min local setup
+   to use your local files — install it?"* → installs the `.mcpb` → restart once.
+4. Thereafter, local-file commands "just work": transcribe → AI picks B-roll by context
+   (local folders + Google Photos pooled) → render locally → publish. AI cost = credits; no keys shown.
+
+## 6. Open questions / caveats
+
+- **Render on user hardware** — slow on weak machines. §4H is the escape hatch.
+- **Baseline prereqs** — OS + disk space even with a bundle; confirm Node bundling in `.mcpb`.
+- **Reconnect seam** — see §4F; need "restart once" UX until clients hot-load MCP servers.
+- **Credit metering granularity** — per-asset analysis vs per-render flat fee.
+- **Cache invalidation** — mtime is good enough locally; URLs need a content hash.
+
+## 7. Suggested sequencing
+
+1. **C + D** (Gemini→backend proxy + token-via-login) — unblocks distribution; do first.
+2. **A** (Python→Node) — removes the Python prereq.
+3. **B + E** (bundle runtime + analysis cache) — the actual "10-min install, then fast" payoff.
+4. **F** (.mcpb + client-side auto-install with consent).
+5. **G** (adjustment tools), **H** (server-side render) — after the local MVP ships.

package/dist/client.js

@@ -5,22 +5,32 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.get = get;
 exports.post = post;
+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 +56,17 @@ function post(endpoint, body) {
         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 +76,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/index.js

@@ -6,17 +6,99 @@ 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 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,
     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 = [
+    '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."',
+].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.",
+    "",
+    "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.",
+    "",
+    "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:",
+    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.",
+].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/tools/assembly-adjust.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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";
+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 } });
+        let stdout = "";
+        child.stdout.on("data", (d) => { stdout += d.toString(); });
+        child.stderr.on("data", (d) => process.stderr.write(d));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve(stdout) : reject(new Error(`engine exited ${code}. ${stdout.slice(-300)}`))));
+    });
+}
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            cut: { type: "number", description: "Index of the cutaway to replace (0-based; from the cut list create_video_assembly returns)." },
+        },
+        required: ["cut"],
+    },
+    async execute(args) {
+        const out = await runEngine(["--suggest", String(args.cut)]);
+        const m = out.match(/SUGGEST:(.+)/);
+        if (!m)
+            throw new Error("no suggestions returned");
+        const d = JSON.parse(m[1]);
+        const lines = (d.options || []).map((o, i) => `${i + 1}. ${o.asset} (${o.kind}) — ${o.desc || "no description"}\n   thumbnail: ${o.thumb}`);
+        return [
+            `Cut #${d.cut} (currently: ${d.current})${d.beat ? ` · line: "${d.beat}"` : ""}`,
+            `Ranked alternatives:`,
+            ...lines,
+            ``,
+            `Apply one with: swap_clip(cut: ${d.cut}, asset: "<asset>").`,
+        ].join("\n");
+    },
+};
+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.",
+    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\")." },
+        },
+        required: ["cut", "asset"],
+    },
+    async execute(args) {
+        const out = await runEngine(["--swap", String(args.cut), args.asset]);
+        const m = out.match(/RESULT:(.+)/);
+        if (!m)
+            throw new Error(`swap failed. ${out.slice(-300)}`);
+        return `Swapped cut #${args.cut} → ${args.asset} and re-rendered.\nOutput: ${m[1].trim()}`;
+    },
+};
+exports.swapCaptionStyleTool = {
+    name: "swap_caption_style",
+    description: "Change the caption style of the most recently assembled video and re-render. " +
+        "Uses the cached edit data — much faster than a full re-assembly (no re-transcription, no B-roll re-analysis). " +
+        "Styles: default (bold white spring pop), hormozi (word-by-word yellow highlight), glow_neon (neon cyan pulse), " +
+        "minimalist (lowercase clean fade), whiteboard (left-to-right reveal).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            caption_style: {
+                type: "string",
+                enum: ["default", "hormozi", "glow_neon", "minimalist", "whiteboard"],
+                description: "Caption style to apply. " +
+                    "default = bold white pop-in (universal). " +
+                    "hormozi = word-by-word yellow highlight on black pill (high-energy talking-head). " +
+                    "glow_neon = neon cyan pulsing text (dark aesthetic, music, gaming). " +
+                    "minimalist = lowercase thin font fade-in (calm, educational). " +
+                    "whiteboard = text revealed left-to-right (explainers, tutorials).",
+            },
+        },
+        required: ["caption_style"],
+    },
+    async execute(args) {
+        const out = await runEngine(["--caption-style", args.caption_style, "--swap-caption-style"]);
+        const m = out.match(/RESULT:(.+)/);
+        if (!m)
+            throw new Error(`caption style swap failed. ${out.slice(-300)}`);
+        return (`Caption style changed to "${args.caption_style}" and re-rendered.\n` +
+            `Output: ${m[1].trim()}\n` +
+            `Publish with publish_now or schedule_post.`);
+    },
+};

package/dist/tools/carousel-video.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishCarouselAsVideoTool = void 0;
+/**
+ * publish_carousel_as_video — convert image slides into a slideshow MP4 and publish.
+ *
+ * Solves two real platform constraints:
+ *   1. TikTok rejects PHOTO carousels in MEDIA_UPLOAD (draft) mode — but accepts
+ *      VIDEO drafts via the inbox endpoint. Converting first lets users send a
+ *      slideshow to TikTok drafts and add trending music in-app before publishing.
+ *   2. Neither TikTok nor Instagram allows attaching a custom audio file to a
+ *      PHOTO carousel via API. Baking the audio into a video sidesteps that.
+ *
+ * Requires ffmpeg on PATH locally.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+const client_js_1 = require("../client.js");
+const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
+function expandImagePaths(inputs) {
+    const result = [];
+    for (const p of inputs) {
+        const stat = fs_1.default.statSync(p, { throwIfNoEntry: false });
+        if (!stat)
+            throw new Error(`Path not found: ${p}`);
+        if (stat.isDirectory()) {
+            const files = fs_1.default.readdirSync(p)
+                .filter((f) => IMAGE_EXTS.has(path_1.default.extname(f).toLowerCase()))
+                .sort()
+                .map((f) => path_1.default.join(p, f));
+            result.push(...files);
+        }
+        else if (IMAGE_EXTS.has(path_1.default.extname(p).toLowerCase())) {
+            result.push(p);
+        }
+    }
+    return result;
+}
+function ensureFfmpeg() {
+    const r = (0, child_process_1.spawnSync)("ffmpeg", ["-version"], { encoding: "utf8" });
+    if (r.error || r.status !== 0) {
+        throw new Error("ffmpeg is required for slideshow generation but was not found on PATH.\n" +
+            "Install instructions:\n" +
+            "  Windows : winget install Gyan.FFmpeg   (or download from https://ffmpeg.org/download.html)\n" +
+            "  macOS   : brew install ffmpeg\n" +
+            "  Linux   : sudo apt install ffmpeg\n" +
+            "After installing, restart Claude Code so the new PATH is picked up.");
+    }
+}
+exports.publishCarouselAsVideoTool = {
+    name: "publish_carousel_as_video",
+    description: "Convert a folder of images into a 1080×1920 slideshow MP4 and publish it. " +
+        "Use this when (a) you want the carousel as a TikTok DRAFT (TikTok's API rejects PHOTO carousels for drafts but accepts VIDEO drafts so the user can add trending music in-app), " +
+        "or (b) you want to attach a specific MP3 to the carousel (TikTok/IG don't allow audio attachment to photo posts via API, but a video with baked-in audio works). " +
+        "Requires ffmpeg installed locally. Returns a single video post, not a carousel post.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Folder containing slide images, or a list of image file paths. Files are sorted alphabetically — name them 01_, 02_, etc. for ordering.",
+            },
+            platforms: {
+                type: "array",
+                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).",
+            },
+            caption: { type: "string", description: "Post caption." },
+            hashtags: {
+                type: "array",
+                items: { type: "string" },
+                description: "Hashtags without # prefix.",
+            },
+            audio_path: {
+                type: "string",
+                description: "Optional. Local path to an MP3/WAV/M4A/AAC file to use as soundtrack. If omitted, the video has no audio (creator can add trending music in-app if mode='draft').",
+            },
+            duration_per_slide: {
+                type: "number",
+                description: "Optional. Seconds each slide is displayed. Defaults to 3.",
+            },
+            mode: {
+                type: "string",
+                enum: ["publish", "draft"],
+                description: "Optional. 'publish' (default) publishes immediately. 'draft' sends to TikTok inbox / YouTube as private — user finishes in mobile app.",
+            },
+        },
+        required: ["paths", "platforms", "caption"],
+    },
+    async execute(args) {
+        ensureFfmpeg();
+        const imagePaths = expandImagePaths(args.paths);
+        if (!imagePaths.length)
+            throw new Error("No image files found in the provided paths.");
+        const mode = args.mode ?? "publish";
+        const duration = Math.max(0.5, args.duration_per_slide ?? 3);
+        if (mode === "draft" && args.platforms.includes("instagram")) {
+            throw new Error("Instagram does not support drafts via API. Remove 'instagram' from platforms or use mode='publish'.");
+        }
+        if (args.audio_path && !fs_1.default.existsSync(args.audio_path)) {
+            throw new Error(`Audio file not found: ${args.audio_path}`);
+        }
+        // Build slideshow MP4 via ffmpeg concat demuxer.
+        const tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "viralspin-slideshow-"));
+        const concatFile = path_1.default.join(tmpDir, "concat.txt");
+        const outputPath = path_1.default.join(tmpDir, "slideshow.mp4");
+        // concat demuxer format: file '<path>'  +  duration N  per entry;
+        // last image must be re-listed without a duration so ffmpeg holds the final frame.
+        const escape = (p) => p.replace(/\\/g, "/").replace(/'/g, "'\\''");
+        const concatLines = [];
+        for (const img of imagePaths) {
+            concatLines.push(`file '${escape(img)}'`);
+            concatLines.push(`duration ${duration}`);
+        }
+        concatLines.push(`file '${escape(imagePaths[imagePaths.length - 1])}'`);
+        fs_1.default.writeFileSync(concatFile, concatLines.join("\n"));
+        const ffmpegArgs = [
+            "-y",
+            "-f", "concat",
+            "-safe", "0",
+            "-i", concatFile,
+        ];
+        if (args.audio_path) {
+            ffmpegArgs.push("-i", args.audio_path);
+        }
+        // Scale slides to fit 1080×1920 (TikTok/Reels native), pad edges black to preserve aspect.
+        ffmpegArgs.push("-vf", "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:black,format=yuv420p,fps=30", "-c:v", "libx264", "-preset", "fast", "-crf", "23", "-pix_fmt", "yuv420p");
+        if (args.audio_path) {
+            ffmpegArgs.push("-c:a", "aac", "-b:a", "192k", "-shortest");
+        }
+        else {
+            ffmpegArgs.push("-an");
+        }
+        ffmpegArgs.push(outputPath);
+        const ffmpeg = (0, child_process_1.spawnSync)("ffmpeg", ffmpegArgs, { encoding: "utf8" });
+        if (ffmpeg.status !== 0) {
+            try {
+                fs_1.default.unlinkSync(concatFile);
+                fs_1.default.rmdirSync(tmpDir);
+            }
+            catch { /* ignore */ }
+            const stderr = (ffmpeg.stderr || "").split("\n").slice(-10).join("\n");
+            throw new Error(`ffmpeg failed (exit ${ffmpeg.status}):\n${stderr}`);
+        }
+        // Upload + publish.
+        let result;
+        let storagePaths = [];
+        try {
+            const upload = await (0, client_js_1.uploadFiles)([outputPath]);
+            storagePaths = upload.storage_paths;
+            result = await (0, client_js_1.post)("/v1/publish/schedule", {
+                media_urls: upload.urls,
+                media_type: "video",
+                platforms: args.platforms,
+                caption: args.caption,
+                hashtags: args.hashtags ?? [],
+                publish_now: true,
+                mode,
+            });
+        }
+        finally {
+            try {
+                fs_1.default.unlinkSync(concatFile);
+                fs_1.default.unlinkSync(outputPath);
+                fs_1.default.rmdirSync(tmpDir);
+            }
+            catch { /* ignore */ }
+            if (storagePaths.length)
+                await (0, client_js_1.deleteFiles)(storagePaths).catch(() => { });
+        }
+        const { status, platform_post_ids, failed_reason } = result.post;
+        const targets = Object.keys(platform_post_ids);
+        const totalSeconds = (imagePaths.length * duration).toFixed(1);
+        let summary = `Slideshow video built: ${imagePaths.length} images × ${duration}s = ${totalSeconds}s, 1080×1920, ${args.audio_path ? "with audio" : "silent"}.\nStatus: ${status}\n`;
+        if (targets.length) {
+            summary += mode === "draft"
+                ? `Sent to drafts on: ${targets.join(", ")}\nOpen the platform's mobile app to finish — add trending audio (if silent), adjust caption, then publish.`
+                : `Published to: ${targets.join(", ")}`;
+        }
+        if (failed_reason)
+            summary += `\nErrors: ${failed_reason}`;
+        return summary.trim();
+    },
+};