@viralspin/mcp 0.1.0 → 0.2.2

package/dist/tools/assembly-adjust.js

@@ -0,0 +1,194 @@
+"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"));
+const hosted_js_1 = require("../hosted.js");
+const engine_js_1 = require("../engine.js");
+// Adjustment tools operate on the most recent create_video_assembly project. By
+// default that's the LOCAL engine project (the engine keeps the timeline +
+// analyzed candidate pool + staged clips on disk), so suggesting is instant and
+// swapping just re-renders locally. When a hosted project is targeted instead —
+// a `job_id` arg, or the VIRALSPIN_HOSTED_JOB_ID env set by a hosted
+// create_video_assembly — the same verbs drive the web Swap & Refine project via
+// the deployed narrative endpoints, so the edit shows up in the browser editor.
+// Shown when a local action is requested but no engine is bundled (the public
+// npm package) and no hosted project is targeted.
+const NO_LOCAL_ENGINE = "This local action needs the ViralSpin engine, which isn't bundled in this install.\n" +
+    "Target a hosted Swap & Refine project instead — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID) — " +
+    "or set VIRALSPIN_ASSEMBLY_DIR to a local engine checkout.";
+function runEngine(args) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(engine_js_1.ENGINE_DIR, "assemble.mjs"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+        let stdout = "";
+        child.stdout.on("data", (d) => { stdout += d.toString(); });
+        child.stderr.on("data", (d) => process.stderr.write(d));
+        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: "See a project's cutaways and find better B-roll for one of them. " +
+        "LOCAL project (default): pass `cut` (0-based) to get ranked alternatives for that cutaway, each with a thumbnail. " +
+        "HOSTED Swap & Refine project (pass `job_id`, or set VIRALSPIN_HOSTED_JOB_ID): " +
+        "call with no `query` to list the timeline's cutaways (segment id + the beat each covers + current clip); " +
+        "call with `query` (e.g. \"newborn in hospital\") to search the user's B-roll library — each result includes the " +
+        "library tags it matched on, which is the 'why this clip fits' to show the user. " +
+        "Then call swap_clip to apply a choice.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            cut: { type: "number", description: "LOCAL only: index of the cutaway to replace (0-based; from the cut list create_video_assembly returns)." },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project (narrative job) to inspect. Omit to use VIRALSPIN_HOSTED_JOB_ID, or the local project." },
+            query: { type: "string", description: "HOSTED: theme to search the B-roll library for (the moment's subject). Omit to list the timeline's cutaways instead." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            // Hosted project: either list the timeline's cutaways, or search the
+            // library for alternatives (with the matched tags = the "why").
+            if (args.query) {
+                const r = await (0, hosted_js_1.searchLibrary)(args.query);
+                if (!r.items.length)
+                    return `No library B-roll matched "${args.query}". Try a broader term.`;
+                const lines = r.items.map((it, i) => `${i + 1}. ${it.url}\n   ${it.kind}${it.album ? ` · from "${it.album}"` : ""} — matched on: "${args.query}"`);
+                return [
+                    `B-roll matching "${args.query}" (best fit first):`,
+                    ...lines,
+                    ``,
+                    `Apply one with: swap_clip(job_id: "${jobId}", segment_id: "<from the cutaway list>", asset_url: "<url above>").`,
+                ].join("\n");
+            }
+            const job = await (0, hosted_js_1.getJob)(jobId);
+            const segs = (0, hosted_js_1.listSegments)(job.timeline);
+            if (!segs.length) {
+                return `Project ${jobId} has no listable cutaways yet (status: ${job.status}). Open it: ${(0, hosted_js_1.editorUrl)(jobId)}`;
+            }
+            const lines = segs.map((s, i) => `${i + 1}. segment ${s.id}${s.beat ? ` — "${s.beat}"` : ""}${s.asset_url ? `\n   current: ${s.asset_url}` : ""}`);
+            return [
+                `Cutaways in ${(0, hosted_js_1.editorUrl)(jobId)} :`,
+                ...lines,
+                ``,
+                `Find alternatives for one: suggest_clips(job_id: "${jobId}", query: "<what that moment is about>").`,
+            ].join("\n");
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
+        if (args.cut === undefined) {
+            return "For a local project, pass `cut` (the 0-based cutaway index). For a hosted Swap & Refine project, pass `job_id`.";
+        }
+        const out = await runEngine(["--suggest", String(args.cut)]);
+        const m = out.match(/SUGGEST:(.+)/);
+        if (!m)
+            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 with a chosen B-roll asset (from suggest_clips), then re-render. " +
+        "LOCAL project (default): pass `cut` (0-based) + `asset` (filename) → re-renders locally, returns the MP4 path. " +
+        "HOSTED Swap & Refine project (pass `job_id`, or set VIRALSPIN_HOSTED_JOB_ID): pass `segment_id` + `asset_url` → " +
+        "patches the same timeline the browser editor shows and kicks off a cloud re-render; the change appears live in " +
+        "Swap & Refine. Returns immediately — the new preview lands on the project shortly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            cut: { type: "number", description: "LOCAL: index of the cutaway to replace (0-based)." },
+            asset: { type: "string", description: "LOCAL: asset filename from suggest_clips (e.g. \"v03.mp4\" or \"07.jpg\")." },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            segment_id: { type: "string", description: "HOSTED: the cutaway's segment id (from suggest_clips)." },
+            asset_url: { type: "string", description: "HOSTED: public URL of the replacement B-roll (from suggest_clips)." },
+            asset_kind: { type: "string", enum: ["broll_video", "broll_photo"], description: "HOSTED: optional — kind of the replacement asset." },
+            reason: { type: "string", description: "HOSTED: optional one-line rationale for WHY this clip fits here (e.g. \"the line says 'the day she arrived'\"). Stored as provenance + shown on the timeline." },
+            render: { type: "boolean", description: "HOSTED: re-render now (costs a render/credits). Default false = instant timeline-only edit; iterate freely, then call render_project once to bake & publish." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            if (!args.segment_id || !args.asset_url) {
+                return "For a hosted project, pass `segment_id` and `asset_url` (both from suggest_clips).";
+            }
+            let kind = args.asset_kind;
+            if (!kind)
+                kind = /\.(mp4|mov|webm|m4v)(\?|$)/i.test(args.asset_url) ? "broll_video" : "broll_photo";
+            await (0, hosted_js_1.swapSegment)(jobId, args.segment_id, args.asset_url, kind, args.reason);
+            if (args.render) {
+                await (0, hosted_js_1.rerender)(jobId);
+                return (`Swapped segment ${args.segment_id} → ${args.asset_url}${args.reason ? ` (${args.reason})` : ""} and started a cloud re-render.\n` +
+                    `Updating live in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+                    `Publish it with publish_now or schedule_post once it finishes.`);
+            }
+            return (`Swapped segment ${args.segment_id} → ${args.asset_url}${args.reason ? ` (${args.reason})` : ""} (instant, no render).\n` +
+                `Keep editing freely — it's all on the timeline. Open: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+                `When the cut is right, call render_project(job_id: "${jobId}") to bake captions/overlays and get the final MP4.`);
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
+        if (args.cut === undefined || !args.asset) {
+            return "For a local project, pass `cut` and `asset`. For a hosted Swap & Refine project, pass `job_id`, `segment_id`, and `asset_url`.";
+        }
+        const out = await runEngine(["--swap", String(args.cut), args.asset]);
+        const m = out.match(/RESULT:(.+)/);
+        if (!m)
+            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).",
+            },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID or the local project." },
+        },
+        required: ["caption_style"],
+    },
+    async execute(args) {
+        // Hosted projects set caption style via the editor's render options; there's
+        // no standalone caption-swap endpoint to drive from here yet. Be explicit
+        // rather than hit a guessed route.
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            return (`Caption style isn't swappable from here for hosted Swap & Refine projects yet — ` +
+                `set it in the editor: ${(0, hosted_js_1.editorUrl)(jobId)} (this is the next slice to wire up).`);
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
+        const out = await runEngine(["--caption-style", args.caption_style, "--swap-caption-style"]);
+        const m = out.match(/RESULT:(.+)/);
+        if (!m)
+            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,197 @@
+"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).",
+            },
+            account_ids: {
+                type: "array",
+                items: { type: "string" },
+                description: "Specific connection IDs (from list_connections) to target. REQUIRED when you have multiple accounts on a platform — " +
+                    "without it the post fans out to EVERY connected account on the platform (e.g. a draft landing on the wrong handle).",
+            },
+            caption: { type: "string", description: "Post caption." },
+            hashtags: {
+                type: "array",
+                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,
+                ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
+                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();
+    },
+};

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 */ }
+        }
+    },
+};