@viralspin/mcp 0.2.0 → 0.3.1

package/dist/local-render/tokens.js

@@ -0,0 +1,201 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenManager = exports.RefreshRefused = void 0;
+exports.jwtExpiry = jwtExpiry;
+exports.saveTokens = saveTokens;
+exports.defaultTokenFile = defaultTokenFile;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function jwtExpiry(token) {
+    try {
+        const part = token.split(".")[1];
+        if (!part)
+            return null;
+        const json = JSON.parse(Buffer.from(part.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+        return typeof json.exp === "number" ? json.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the token file owner-only (dir 0700, file 0600), atomically. chmod even if the file existed with looser bits. */
+function saveTokens(file, data) {
+    const dir = path_1.default.dirname(file);
+    fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+    }
+    catch { /* not ours to chmod (a shared home on Windows) */ }
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs_1.default.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+    try {
+        fs_1.default.chmodSync(tmp, 0o600);
+    }
+    catch { /* Windows */ }
+    fs_1.default.renameSync(tmp, file);
+}
+function defaultTokenFile() {
+    return path_1.default.join(os_1.default.homedir(), ".viralspin", "oauth.json");
+}
+/** The server said the refresh token is no good (expired, revoked): a new sign-in is the only way forward. */
+class RefreshRefused extends Error {
+}
+exports.RefreshRefused = RefreshRefused;
+class TokenManager {
+    constructor(opts) {
+        this.opts = opts;
+        this.mem = null;
+        this.refreshCount = 0;
+        this.signing = null;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.file = opts.file ?? defaultTokenFile();
+        this.env = opts.env ?? process.env;
+        this.now = opts.now ?? Date.now;
+        this.skew = opts.skewSec ?? 120;
+    }
+    readFile() {
+        try {
+            const j = JSON.parse(fs_1.default.readFileSync(this.file, "utf8"));
+            return j && typeof j.access_token === "string" ? j : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    fromEnv() {
+        const a = this.env.VIRALSPIN_OAUTH_TOKEN;
+        if (!a && !this.env.VIRALSPIN_OAUTH_REFRESH_TOKEN)
+            return null;
+        return {
+            access_token: a || "",
+            refresh_token: this.env.VIRALSPIN_OAUTH_REFRESH_TOKEN || undefined,
+            client_id: this.env.VIRALSPIN_OAUTH_CLIENT_ID || undefined,
+        };
+    }
+    expiry(p) {
+        if (!p.access_token)
+            return 0;
+        return jwtExpiry(p.access_token) ?? Number.POSITIVE_INFINITY; // not a JWT with exp: trust until the server says 401
+    }
+    /** The candidate with the latest expiry (re-read from the file every call). */
+    best() {
+        const all = [this.mem, this.readFile(), this.fromEnv()].filter(Boolean);
+        if (!all.length)
+            return null;
+        return all.sort((a, b) => this.expiry(b) - this.expiry(a))[0];
+    }
+    refreshToken() {
+        for (const p of [this.mem, this.readFile(), this.fromEnv()]) {
+            if (p?.refresh_token)
+                return { rt: p.refresh_token, client_id: p.client_id };
+        }
+        return null;
+    }
+    /** Run the browser sign-in, one at a time, and forget anything stale held in memory. */
+    async signInNow() {
+        if (!this.opts.signIn)
+            return false;
+        this.signing ?? (this.signing = this.opts.signIn().finally(() => { this.signing = null; }));
+        await this.signing;
+        this.mem = null;
+        return true;
+    }
+    async getAccessToken() {
+        let cur = this.best();
+        if (!cur && (await this.signInNow()))
+            cur = this.best();
+        if (!cur) {
+            throw new Error("Not signed in to ViralSpin on this computer. Run `npx -y @viralspin/mcp login` once (it opens your browser), " +
+                "or set VIRALSPIN_OAUTH_TOKEN (+ VIRALSPIN_OAUTH_REFRESH_TOKEN) in the MCP server's env.");
+        }
+        const nowSec = this.now() / 1000;
+        if (cur.access_token && this.expiry(cur) - nowSec > this.skew)
+            return cur.access_token;
+        if (this.refreshToken()) {
+            try {
+                return await this.refresh();
+            }
+            catch (e) {
+                // the 30-day refresh token ran out (or was revoked): sign in again in the browser, if we can
+                if (!(e instanceof RefreshRefused) || !(await this.signInNow()))
+                    throw e;
+                const fresh = this.best();
+                if (fresh?.access_token)
+                    return fresh.access_token;
+                throw e;
+            }
+        }
+        if (cur.access_token)
+            return cur.access_token; // nothing to refresh with: let the server judge it
+        throw new Error("The ViralSpin sign-in has expired and there is no refresh token. Sign in again.");
+    }
+    async refresh() {
+        const r = this.refreshToken();
+        if (!r)
+            throw new Error("The ViralSpin sign-in expired and there is no refresh token (VIRALSPIN_OAUTH_REFRESH_TOKEN). Sign in again.");
+        const form = new URLSearchParams({ grant_type: "refresh_token", refresh_token: r.rt });
+        if (r.client_id)
+            form.set("client_id", r.client_id);
+        const resp = await this.fetchImpl(`${this.opts.apiBase}/v1/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: form.toString(),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            const msg = `Could not renew the ViralSpin sign-in (${resp.status}). The refresh token lasts 30 days; sign in again. ${text.slice(0, 160)}`;
+            throw resp.status === 400 || resp.status === 401 ? new RefreshRefused(msg) : new Error(msg);
+        }
+        const j = (await resp.json());
+        if (!j.access_token)
+            throw new Error("The token endpoint answered without an access_token.");
+        this.mem = { access_token: j.access_token, refresh_token: j.refresh_token || r.rt, client_id: r.client_id };
+        this.refreshCount++;
+        try {
+            saveTokens(this.file, { ...this.mem });
+        }
+        catch {
+            /* the file is a convenience; memory is enough for this process */
+        }
+        return j.access_token;
+    }
+    /** Authenticated JSON request; one retry after a refresh when the server says 401. */
+    async request(method, url, body) {
+        const go = async (token) => this.fetchImpl(url, {
+            method,
+            headers: { Authorization: `Bearer ${token}`, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        let resp = await go(await this.getAccessToken());
+        if (resp.status === 401 && (this.refreshToken() || this.opts.signIn)) {
+            let fresh;
+            try {
+                fresh = this.refreshToken() ? await this.refresh() : (await this.signInNow(), await this.getAccessToken());
+            }
+            catch (e) {
+                if (!(e instanceof RefreshRefused) || !(await this.signInNow()))
+                    throw e;
+                fresh = await this.getAccessToken();
+            }
+            resp = await go(fresh);
+        }
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            let detail = text;
+            try {
+                const d = JSON.parse(text).detail;
+                detail = typeof d === "string" ? d : JSON.stringify(d ?? text);
+            }
+            catch {
+                /* keep text */
+            }
+            throw new Error(`API error ${resp.status} on ${method} ${url.replace(this.opts.apiBase, "")}: ${detail.slice(0, 400)}`);
+        }
+        return (await resp.json());
+    }
+}
+exports.TokenManager = TokenManager;

package/dist/sanitize.js

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

package/dist/tools/assembly-adjust.js

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

package/dist/tools/carousel-video.js

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

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