@viralspin/mcp 0.1.0 → 0.3.1

package/dist/tools/color-grade.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colorGradeTool = void 0;
+/**
+ * color_grade — free, instant cinematic LUT looks (ffmpeg, no AI, no cost). The
+ * cheap counterpart to relight_clip: it regrades color/contrast but can't change
+ * the background or add 3D relighting. Great for the A-roll or any clip.
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+const LOOKS = ["teal-orange", "noir", "warm-golden", "cool-cinematic", "vintage", "vibrant", "moody-blue"];
+function runGrade(args) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(engine_js_1.ENGINE_DIR, "grade.mjs"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+        let out = "";
+        child.stdout.on("data", (d) => { out += d.toString(); });
+        child.stderr.on("data", (d) => process.stderr.write(d));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const m = out.match(/RESULT:([\s\S]+)/);
+            if (code === 0 && m)
+                resolve(m[1].trim());
+            else
+                reject(new Error(out.slice(-300) || `grade exited ${code}`));
+        });
+    });
+}
+exports.colorGradeTool = {
+    name: "color_grade",
+    description: "Apply a FREE, instant cinematic color grade / LUT look to a LOCAL video (no AI, no cost) — teal-orange, " +
+        "noir, warm-golden, cool-cinematic, vintage, vibrant, or moody-blue. Great for the A-roll or any clip; it's " +
+        "a toggle-able look (keep the original or the graded file). For true relighting / background change, that's " +
+        "the paid relight_clip instead. Omit `look` to list the available looks.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            video_path: { type: "string", description: "Local path to the video to grade." },
+            look: { type: "string", enum: LOOKS, description: "The look to apply. Omit to list all looks." },
+        },
+        required: ["video_path"],
+    },
+    async execute(args) {
+        if (!(0, engine_js_1.engineAvailable)("grade.mjs")) {
+            return "color_grade needs the local engine (ffmpeg). It's unavailable in this install.";
+        }
+        if (!args.look) {
+            const r = JSON.parse(await runGrade(["--list"]));
+            const lines = r.looks.map((l) => `  • ${l.key} — ${l.label}`);
+            return ["Free cinematic looks (no cost):", ...lines, "", `Apply one: color_grade(video_path: "${args.video_path}", look: "teal-orange").`].join("\n");
+        }
+        let r;
+        try {
+            r = JSON.parse(await runGrade([args.video_path, args.look]));
+        }
+        catch (e) {
+            return `Couldn't grade the video: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        return `Applied the "${r.look}" grade → ${r.out}\nFree + instant (ffmpeg). Swap it in, or try another look.`;
+    },
+};

package/dist/tools/connections.js

@@ -4,15 +4,34 @@ exports.listConnectionsTool = void 0;
 const client_js_1 = require("../client.js");
 exports.listConnectionsTool = {
     name: "list_connections",
-    description: "List your connected social media accounts (TikTok, Instagram, YouTube).",
+    description: "List your connected social media accounts (TikTok, Instagram, YouTube). " +
+        "Returns each account's connection ID — pass the ID to publish_now / schedule_post / send_to_drafts " +
+        "via the account_ids param when you have multiple accounts on the same platform.",
     inputSchema: { type: "object", properties: {}, required: [] },
     async execute(_args) {
+        var _a;
         const connections = await (0, client_js_1.get)("/v1/publish/connections");
         if (!connections.length) {
             return "No platforms connected yet. Visit https://www.viralspin.ai/spin/settings to connect your accounts.";
         }
-        return connections
-            .map((c) => `${c.platform}: ${c.display_name} (${c.username}) — ${c.follower_count.toLocaleString()} followers`)
-            .join("\n");
+        // Group by platform
+        const byPlatform = {};
+        for (const c of connections) {
+            (byPlatform[_a = c.platform] ?? (byPlatform[_a] = [])).push(c);
+        }
+        const lines = [];
+        for (const [platform, accounts] of Object.entries(byPlatform)) {
+            lines.push(`${platform.toUpperCase()}:`);
+            for (const c of accounts) {
+                const label = c.account_label ? ` [${c.account_label}]` : "";
+                const handle = c.username ? ` (@${c.username.replace(/^@/, "")})` : "";
+                const followers = c.follower_count > 0 ? ` — ${c.follower_count.toLocaleString()} followers` : "";
+                lines.push(`  • ${c.display_name}${handle}${label}${followers}`);
+                lines.push(`    id: ${c.id}`);
+            }
+        }
+        lines.push("");
+        lines.push("Tip: when publishing to a specific account, pass its id in the account_ids param.");
+        return lines.join("\n");
     },
 };

package/dist/tools/edit-clip.js

@@ -0,0 +1,136 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editRawClipTool = void 0;
+/**
+ * edit_raw_clip — "edit this" for a RAW local talking-head clip. Transcribes it, cuts the dead
+ * space + filler words, burns captions, and drops RICH on-beat motion-graphics (an LLM plans
+ * varied stat / logo tile / step / quote cards from the transcript) → a finished 9:16 short.
+ *
+ * Runs on the user's machine via the bundled intake engine (mcp/engine/intake.py). Only the
+ * transcript (not the footage) is sent to the cloud graphics planner, so the video stays local.
+ * Falls back to on-device deterministic graphics if the planner isn't reachable.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+const client_js_1 = require("../client.js");
+/** Spawn the local Python intake engine, trying the usual interpreter names. */
+function runPy(args) {
+    const bins = process.platform === "win32" ? ["python", "py", "python3"] : ["python3", "python"];
+    return new Promise((resolve, reject) => {
+        const tryBin = (i) => {
+            if (i >= bins.length) {
+                reject(new Error("Python 3 not found on PATH — install it to use edit_raw_clip."));
+                return;
+            }
+            const child = (0, child_process_1.spawn)(bins[i], [path_1.default.join(engine_js_1.ENGINE_DIR, "intake.py"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+            let out = "", err = "";
+            child.stdout.on("data", (d) => { out += d.toString(); });
+            child.stderr.on("data", (d) => { err += d.toString(); });
+            child.on("error", (e) => { if (e.code === "ENOENT")
+                tryBin(i + 1);
+            else
+                reject(e); });
+            child.on("close", (code) => {
+                if (code === 0)
+                    resolve(out);
+                else
+                    reject(new Error((err || out).slice(-500) || `intake exited ${code}`));
+            });
+        };
+        tryBin(0);
+    });
+}
+exports.editRawClipTool = {
+    name: "edit_raw_clip",
+    description: "EDIT a raw local talking-head video into a finished 9:16 short — the natural tool for \"edit this: " +
+        "<path>\", \"dress this clip\", or \"clean up my talking-head recording\". It transcribes the clip, cuts " +
+        "the dead space and filler words (um/uh/…), burns captions, and drops RICH on-beat motion-graphics — " +
+        "varied stat cards, brand/logo tiles, step/pipeline cards, and quote cards, chosen and filled by an LLM " +
+        "from what's actually said (like a polished explainer, not just captions). Runs on the user's machine; " +
+        "the footage stays local (only the transcript is used to plan graphics). Give it the video_path; returns " +
+        "the finished file path (and a preview URL). For a pure color/LUT look instead, that's color_grade.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            video_path: { type: "string", description: "Local path to the raw talking-head video to edit (e.g. G:/clips/talk.mov)." },
+            captions: { type: "boolean", description: "Burn captions onto the reel (default true)." },
+            graphics: { type: "boolean", description: "Add on-beat motion-graphics (default true)." },
+            sensitivity: { type: "number", description: "Dead-space cut threshold in seconds (default 0.5; lower = tighter, more cuts)." },
+            out_path: { type: "string", description: "Where to write the finished reel (default: next to the input as <name>_edited.mp4)." },
+        },
+        required: ["video_path"],
+    },
+    async execute(args) {
+        if (!(0, engine_js_1.engineAvailable)("intake.py")) {
+            return "edit_raw_clip needs the local editing engine (Python + ffmpeg). It's unavailable in this install.";
+        }
+        const vp = (args.video_path || "").trim().replace(/^["']|["']$/g, "");
+        if (!vp || !fs_1.default.existsSync(vp)) {
+            return `Couldn't find that video: ${vp || "(no path given)"}. Pass a local path, e.g. edit_raw_clip(video_path: "G:/clips/talk.mov").`;
+        }
+        const tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "vs-edit-"));
+        const wordsPath = path_1.default.join(tmp, "words.json");
+        const outPath = args.out_path || vp.replace(/\.[^./\\]+$/, "") + "_edited.mp4";
+        const wantGraphics = args.graphics !== false;
+        try {
+            // 1) transcribe → word timestamps (reused by the cut + captions + planner, so no double work)
+            await runPy(["transcribe", "--clip", vp, "--out", wordsPath]);
+            const words = JSON.parse(fs_1.default.readFileSync(wordsPath, "utf8"));
+            // 2) plan RICH graphics from the transcript (LLM, best-effort). Only the transcript leaves the
+            //    machine. If it fails, the engine falls back to on-device deterministic graphics.
+            const planArgs = [];
+            let plannerNote = "on-device graphics";
+            if (wantGraphics && words.length) {
+                try {
+                    const dur = words[words.length - 1]?.end || 0;
+                    const { graphics } = await (0, client_js_1.pyPost)("/v1/spin/plan-graphics", { words, duration: dur });
+                    if (Array.isArray(graphics) && graphics.length) {
+                        const pp = path_1.default.join(tmp, "plan.json");
+                        fs_1.default.writeFileSync(pp, JSON.stringify(graphics));
+                        planArgs.push("--graphics", pp);
+                        plannerNote = `${graphics.length} LLM-planned graphics`;
+                    }
+                }
+                catch { /* planner unreachable → on-device fallback */ }
+            }
+            // 3) dress: cut dead space + filler → captions → graphics (reusing the transcript)
+            const dressArgs = ["dress", "--clip", vp, "--out", outPath, "--words", wordsPath, "--max-gap", String(args.sensitivity ?? 0.5), ...planArgs];
+            if (args.captions === false)
+                dressArgs.push("--no-captions");
+            if (!wantGraphics)
+                dressArgs.push("--no-graphics");
+            const dressOut = await runPy(dressArgs);
+            const rm = dressOut.match(/REPORT:(\{.*\})/);
+            const report = rm ? JSON.parse(rm[1]) : {};
+            // 4) best-effort upload for a shareable preview URL (local file is the real deliverable)
+            let url = "";
+            try {
+                url = (await (0, client_js_1.uploadFiles)([outPath])).urls[0] || "";
+            }
+            catch { /* local-only is fine */ }
+            const bits = [
+                `Edited **${path_1.default.basename(vp)}** → \`${outPath}\``,
+                `• ${report.original_sec ?? "?"}s → ${report.cut_sec ?? "?"}s (${report.pct_removed ?? 0}% tighter), ${report.n_cuts ?? 0} cuts`,
+                `• ${report.n_graphics ?? 0} on-beat graphics (${plannerNote})${args.captions === false ? "" : " + captions"}`,
+            ];
+            if (url)
+                bits.push(`• Preview: ${url}`);
+            return bits.join("\n");
+        }
+        catch (e) {
+            return `Couldn't edit the clip: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        finally {
+            try {
+                fs_1.default.rmSync(tmp, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+        }
+    },
+};

package/dist/tools/engage.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteKeywordLinkTool = exports.listKeywordLinksTool = exports.setKeywordLinkTool = void 0;
+const client_js_1 = require("../client.js");
+function describe(k) {
+    const scope = k.media_id ? `post ${k.media_id}` : "all posts";
+    const platform = k.platform ?? "any platform";
+    const reply = k.reply_to_comment
+        ? (k.comment_reply_text ? `, replies "${k.comment_reply_text}"` : ", + comment reply")
+        : ", DM only";
+    const status = k.is_active ? "" : " (paused)";
+    return `"${k.keyword}" → ${k.link}  [${platform}, ${scope}, ${k.match_type}${reply}]${status}`;
+}
+exports.setKeywordLinkTool = {
+    name: "set_keyword_link",
+    description: "Map a keyword to a resource/destination link for DM automation. When a follower comments/DMs the keyword, " +
+        "the link is sent back (delivery activates once Instagram messaging access is approved). " +
+        "Re-running with the same keyword + scope updates the link instead of creating a duplicate. " +
+        "Omit media_id for a global rule (fires on any post); set media_id for a single post.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            keyword: { type: "string", description: "The trigger word, e.g. 'guide' or 'link'. Case-insensitive." },
+            link: { type: "string", description: "The destination URL to send (e.g. a resource-hub article)." },
+            platform: {
+                type: "string",
+                enum: ["instagram", "tiktok", "youtube"],
+                description: "Platform this rule applies to. Omit for any connected platform. Only Instagram delivers today.",
+            },
+            media_id: {
+                type: "string",
+                description: "Optional. A specific post/media id to scope the rule to. Omit for a global rule across all posts.",
+            },
+            match_type: {
+                type: "string",
+                enum: ["exact", "contains", "word"],
+                description: "'word' (default, recommended) fires when the keyword appears as a whole word — 'the app.' matches, " +
+                    "'appreciate' does not. 'contains' fires on any substring, which misfires on short keywords. " +
+                    "'exact' requires the comment to be nothing but the keyword.",
+            },
+            reply_to_comment: {
+                type: "boolean",
+                description: "Also post a public reply to the comment (e.g. 'Check your DMs', wording varies). Defaults to true.",
+            },
+            comment_reply_text: {
+                type: "string",
+                description: "Custom wording for that public reply. Omit to rotate through the built-in phrases.",
+            },
+        },
+        required: ["keyword", "link"],
+    },
+    async execute(args) {
+        const created = await (0, client_js_1.post)("/v1/engage/keyword-links", {
+            keyword: args.keyword,
+            link: args.link,
+            platform: args.platform ?? null,
+            media_id: args.media_id ?? null,
+            match_type: args.match_type ?? "word",
+            reply_to_comment: args.reply_to_comment ?? true,
+            comment_reply_text: args.comment_reply_text ?? null,
+        });
+        return `Saved: ${describe(created)}`;
+    },
+};
+exports.listKeywordLinksTool = {
+    name: "list_keyword_links",
+    description: "List your keyword→link DM-automation rules.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+    async execute(_args) {
+        const rules = await (0, client_js_1.get)("/v1/engage/keyword-links");
+        if (!rules.length) {
+            return "No keyword→link rules yet. Use set_keyword_link to add one (e.g. map 'guide' to your resource link).";
+        }
+        return rules.map((r) => `• ${describe(r)}`).join("\n");
+    },
+};
+exports.deleteKeywordLinkTool = {
+    name: "delete_keyword_link",
+    description: "Delete a keyword→link rule by its keyword. If multiple rules share the keyword, all of them are removed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            keyword: { type: "string", description: "The keyword whose rule(s) should be deleted." },
+        },
+        required: ["keyword"],
+    },
+    async execute(args) {
+        const rules = await (0, client_js_1.get)("/v1/engage/keyword-links");
+        const matches = rules.filter((r) => r.keyword.toLowerCase() === args.keyword.trim().toLowerCase());
+        if (!matches.length)
+            return `No rule found for keyword "${args.keyword}".`;
+        for (const m of matches) {
+            await (0, client_js_1.del)(`/v1/engage/keyword-links/${m.id}`);
+        }
+        return `Deleted ${matches.length} rule(s) for "${args.keyword}".`;
+    },
+};

package/dist/tools/explainer-index.js

@@ -0,0 +1,307 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexExplainerSourcesTool = void 0;
+exports.searchAndExtract = searchAndExtract;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_https_1 = __importDefault(require("node:https"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const TL_BASE = "https://api.twelvelabs.io/v1.3";
+const VIRALSPIN_HOME = node_path_1.default.join(node_os_1.default.homedir(), ".viralspin");
+const CACHE_FILE = node_path_1.default.join(VIRALSPIN_HOME, "explainer_cache.json");
+function readCache() {
+    try {
+        if (node_fs_1.default.existsSync(CACHE_FILE))
+            return JSON.parse(node_fs_1.default.readFileSync(CACHE_FILE, "utf8"));
+    }
+    catch { /* ignore */ }
+    return { indexes: {}, videos: {} };
+}
+function writeCache(c) {
+    node_fs_1.default.mkdirSync(VIRALSPIN_HOME, { recursive: true });
+    node_fs_1.default.writeFileSync(CACHE_FILE, JSON.stringify(c, null, 2));
+}
+function cacheKey(filePath) {
+    try {
+        const stat = node_fs_1.default.statSync(filePath);
+        return `${filePath}|${stat.size}`;
+    }
+    catch {
+        return filePath;
+    }
+}
+// ── Twelve Labs REST helpers ───────────────────────────────────────────────
+function tlFetch(method, urlPath, body, apiKey) {
+    return new Promise((resolve, reject) => {
+        const key = apiKey || process.env.TWELVE_LABS_API_KEY || "";
+        const bodyBuf = body ? Buffer.from(JSON.stringify(body)) : undefined;
+        const req = node_https_1.default.request(`${TL_BASE}${urlPath}`, {
+            method,
+            headers: {
+                "x-api-key": key,
+                "Content-Type": "application/json",
+                ...(bodyBuf ? { "Content-Length": bodyBuf.length } : {}),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                const text = Buffer.concat(chunks).toString();
+                try {
+                    resolve(JSON.parse(text));
+                }
+                catch {
+                    reject(new Error(`TL parse error: ${text.slice(0, 200)}`));
+                }
+            });
+        });
+        req.on("error", reject);
+        if (bodyBuf)
+            req.write(bodyBuf);
+        req.end();
+    });
+}
+async function tlUploadFile(filePath, indexId, apiKey) {
+    // Multipart upload using form-data
+    const { default: FormData } = await Promise.resolve(`${"form-data"}`).then(s => __importStar(require(s)));
+    const form = new FormData();
+    form.append("index_id", indexId);
+    form.append("language", "en");
+    form.append("video_file", node_fs_1.default.createReadStream(filePath), { filename: node_path_1.default.basename(filePath) });
+    return new Promise((resolve, reject) => {
+        const headers = { ...form.getHeaders(), "x-api-key": apiKey };
+        const req = node_https_1.default.request(`${TL_BASE}/tasks`, { method: "POST", headers }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                try {
+                    const d = JSON.parse(Buffer.concat(chunks).toString());
+                    resolve(d._id || d.id);
+                }
+                catch (e) {
+                    reject(new Error(`TL upload parse error: ${Buffer.concat(chunks).toString().slice(0, 200)}`));
+                }
+            });
+        });
+        req.on("error", reject);
+        form.pipe(req);
+    });
+}
+async function waitForTask(taskId, apiKey) {
+    const deadline = Date.now() + 30 * 60 * 1000; // 30-min max
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 8000));
+        const d = await tlFetch("GET", `/tasks/${taskId}`, undefined, apiKey);
+        if (d.status === "ready")
+            return d.video_id;
+        if (d.status === "failed")
+            throw new Error(`Twelve Labs indexing failed for task ${taskId}: ${d.error || ""}`);
+    }
+    throw new Error(`Twelve Labs indexing timed out for task ${taskId}`);
+}
+async function getOrCreateIndex(folderPath, indexName, apiKey) {
+    const cache = readCache();
+    if (cache.indexes[folderPath])
+        return cache.indexes[folderPath];
+    // Create a new index
+    const d = await tlFetch("POST", "/indexes", {
+        name: indexName,
+        engines: [{ name: "marengo2.6", options: ["visual", "conversation", "text_in_video"] }],
+    }, apiKey);
+    const indexId = d._id || d.id;
+    cache.indexes[folderPath] = indexId;
+    writeCache(cache);
+    return indexId;
+}
+// ── Folder walking ─────────────────────────────────────────────────────────
+const VIDEO_EXTS = new Set([".mp4", ".mkv", ".mov", ".avi", ".wmv", ".webm"]);
+function walkFolder(folder) {
+    const results = [];
+    try {
+        for (const entry of node_fs_1.default.readdirSync(folder, { withFileTypes: true })) {
+            const full = node_path_1.default.join(folder, entry.name);
+            if (entry.isDirectory())
+                results.push(...walkFolder(full));
+            else if (VIDEO_EXTS.has(node_path_1.default.extname(entry.name).toLowerCase()))
+                results.push(full);
+        }
+    }
+    catch { /* ignore permission errors */ }
+    return results;
+}
+exports.indexExplainerSourcesTool = {
+    name: "index_explainer_sources",
+    description: "Index a local folder of screen recordings and OBS videos with Twelve Labs so they can be searched semantically " +
+        "inside create_video_assembly. Call this once per folder — indexing is cached, so re-running skips already-indexed files. " +
+        "Returns an index_id to pass as explainer_index_id in create_video_assembly. " +
+        "Requires TWELVE_LABS_API_KEY in the MCP environment.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sources_folder: {
+                type: "string",
+                description: "Local folder containing your screen recordings / OBS videos (e.g. C:/obs-recordings).",
+            },
+            index_name: {
+                type: "string",
+                description: "Optional name for the Twelve Labs index (defaults to the folder's base name).",
+            },
+        },
+        required: ["sources_folder"],
+    },
+    async execute(args) {
+        // Credit gate: Twelve Labs indexing makes paid API calls that are not yet
+        // metered to a user's credit balance, so it is OFF by default for public
+        // MCP deployments. Internal/power users can enable it explicitly.
+        if (process.env.EXPLAINER_INDEX_ENABLED !== "true") {
+            return "Twelve Labs explainer indexing is disabled. This feature calls a paid API that is not yet billed to credits, so it is off by default. To enable it for internal use, set EXPLAINER_INDEX_ENABLED=true in the MCP environment.";
+        }
+        const apiKey = process.env.TWELVE_LABS_API_KEY;
+        if (!apiKey) {
+            return "Error: TWELVE_LABS_API_KEY is not set in the MCP environment. Add it to your ~/.claude.json MCP config under env.TWELVE_LABS_API_KEY.";
+        }
+        const folder = args.sources_folder;
+        if (!node_fs_1.default.existsSync(folder)) {
+            return `Error: folder not found: ${folder}`;
+        }
+        const indexName = args.index_name || node_path_1.default.basename(folder) || "viralspin-explainer";
+        process.stderr.write(`[explainer-index] Getting/creating Twelve Labs index for ${folder}…\n`);
+        const indexId = await getOrCreateIndex(folder, indexName, apiKey);
+        process.stderr.write(`[explainer-index] index_id=${indexId}\n`);
+        const videos = walkFolder(folder);
+        if (videos.length === 0) {
+            return `No video files found in ${folder}. Supported formats: ${[...VIDEO_EXTS].join(", ")}`;
+        }
+        const cache = readCache();
+        let indexed = 0;
+        let skipped = 0;
+        const errors = [];
+        for (const vpath of videos) {
+            const key = cacheKey(vpath);
+            if (cache.videos[key]) {
+                skipped++;
+                process.stderr.write(`[explainer-index] skip (cached): ${node_path_1.default.basename(vpath)}\n`);
+                continue;
+            }
+            process.stderr.write(`[explainer-index] uploading: ${node_path_1.default.basename(vpath)}…\n`);
+            try {
+                const taskId = await tlUploadFile(vpath, indexId, apiKey);
+                process.stderr.write(`[explainer-index] waiting for task ${taskId}…\n`);
+                const videoId = await waitForTask(taskId, apiKey);
+                cache.videos[key] = { video_id: videoId, index_id: indexId };
+                writeCache(cache);
+                indexed++;
+                process.stderr.write(`[explainer-index] indexed: ${node_path_1.default.basename(vpath)} → video_id=${videoId}\n`);
+            }
+            catch (e) {
+                errors.push(`${node_path_1.default.basename(vpath)}: ${e?.message || e}`);
+                process.stderr.write(`[explainer-index] ERROR: ${e?.message || e}\n`);
+            }
+        }
+        const parts = [
+            `Index ready: ${indexId}`,
+            `  Newly indexed: ${indexed} video${indexed !== 1 ? "s" : ""}`,
+            `  Already cached: ${skipped}`,
+            `  Total in folder: ${videos.length}`,
+            "",
+            `Pass this to create_video_assembly as:  explainer_index_id: "${indexId}"`,
+        ];
+        if (errors.length) {
+            parts.push("", `Errors (${errors.length}):`, ...errors.map((e) => `  • ${e}`));
+        }
+        return parts.join("\n");
+    },
+};
+// ── Clip retrieval (used by assemble.mjs via env forwarding) ───────────────
+// Exported so assemble.mjs can also call this logic if needed in future.
+async function searchAndExtract(searchQuery, indexId, outDir, clipIndex) {
+    const apiKey = process.env.TWELVE_LABS_API_KEY;
+    if (!apiKey)
+        return null;
+    try {
+        const result = await tlFetch("POST", "/search", {
+            query_text: searchQuery,
+            index_id: indexId,
+            search_options: ["visual", "conversation", "text_in_video"],
+            page_limit: 1,
+        }, apiKey);
+        const hit = result?.data?.[0];
+        if (!hit)
+            return null;
+        const videoId = hit.video_id;
+        const startSec = hit.start || 0;
+        const endSec = hit.end || startSec + 15;
+        const confidence = hit.score || 0;
+        // Look up local path from cache
+        const cache = readCache();
+        let localPath = null;
+        for (const entry of Object.values(cache.videos)) {
+            if (entry.video_id === videoId && entry.index_id === indexId) {
+                // Find the key (which is "filePath|size")
+                for (const [key, val] of Object.entries(cache.videos)) {
+                    if (val.video_id === videoId) {
+                        localPath = key.split("|")[0];
+                        break;
+                    }
+                }
+                break;
+            }
+        }
+        if (!localPath || !node_fs_1.default.existsSync(localPath))
+            return null;
+        const outPath = node_path_1.default.join(outDir, `explainer_clip_${clipIndex}.mp4`);
+        const duration = Math.min(endSec - startSec, 30);
+        const { spawn } = await Promise.resolve().then(() => __importStar(require("child_process")));
+        await new Promise((resolve, reject) => {
+            const ff = spawn("ffmpeg", [
+                "-y", "-ss", String(startSec), "-t", String(duration),
+                "-i", localPath,
+                "-c:v", "libx264", "-crf", "26", "-c:a", "aac", "-movflags", "+faststart",
+                outPath,
+            ]);
+            ff.on("close", (code) => code === 0 ? resolve() : reject(new Error(`ffmpeg exit ${code}`)));
+            ff.on("error", reject);
+        });
+        return { clip_path: outPath, confidence, start_sec: startSec };
+    }
+    catch (e) {
+        process.stderr.write(`[explainer-index] searchAndExtract error: ${e?.message || e}\n`);
+        return null;
+    }
+}