@viralspin/mcp 0.1.0 → 0.2.2

package/dist/tools/profile.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCreatorProfileTool = exports.setCreatorProfileTool = void 0;
+/**
+ * set_creator_profile / get_creator_profile — the user's niche + social handles +
+ * topics, so the weekly idea routine knows their context. Capture it at setup
+ * (ask the user, or read their connected accounts via list_connections), and the
+ * weekly routine reads it to research what's working in their niche.
+ */
+const client_js_1 = require("../client.js");
+exports.setCreatorProfileTool = {
+    name: "set_creator_profile",
+    description: "Save the user's creator profile — their NICHE, social HANDLES (instagram/tiktok/youtube), and core TOPICS — " +
+        "so the weekly idea routine can research WHAT'S CURRENTLY GOING VIRAL in their niche (trending formats, hooks, " +
+        "and 5-7s caption reels — queue_idea format 'reel_7s') and model that week's ideas on proven winners. Capture " +
+        "this at setup: ask the user, or infer handles from list_connections. Call get_creator_profile first.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            niche: { type: "string", description: "The user's niche / what their content is about (e.g. 'AI tech for founders')." },
+            handles: {
+                type: "object",
+                description: "Their social handles: { instagram, tiktok, youtube }.",
+                properties: { instagram: { type: "string" }, tiktok: { type: "string" }, youtube: { type: "string" } },
+            },
+            topics: { type: "array", items: { type: "string" }, description: "Core content pillars / recurring topics." },
+            weekly_routine: { type: "boolean", description: "Whether the weekly 5-ideas routine is on for them." },
+        },
+    },
+    async execute(args) {
+        await (0, client_js_1.post)("/v1/spin/profile", args);
+        return `Saved the creator profile${args.niche ? ` (niche: ${args.niche})` : ""}. The weekly idea routine will research this niche + their accounts.`;
+    },
+};
+exports.getCreatorProfileTool = {
+    name: "get_creator_profile",
+    description: "Read the user's saved creator profile (niche, handles, topics, whether the weekly routine is on). Use at the " +
+        "start of a brainstorming or weekly-idea session so you target their actual niche/accounts. If it's empty, ask " +
+        "the user for their niche + handles (or read list_connections) and set_creator_profile.",
+    inputSchema: { type: "object", properties: {} },
+    async execute() {
+        const r = await (0, client_js_1.get)("/v1/spin/profile");
+        if (!r.profile || (!r.profile.niche && !r.profile.handles)) {
+            return "No creator profile set yet. Ask the user for their niche + social handles (or read list_connections), then set_creator_profile.";
+        }
+        const p = r.profile;
+        const handles = p.handles ? Object.entries(p.handles).filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join(", ") : "";
+        return [
+            `Creator profile:`,
+            `- niche: ${p.niche || "(not set)"}`,
+            handles ? `- handles: ${handles}` : `- handles: (none)`,
+            p.topics?.length ? `- topics: ${p.topics.join(", ")}` : "",
+            `- weekly routine: ${p.weekly_routine ? "on" : "off"}`,
+        ].filter(Boolean).join("\n");
+    },
+};

package/dist/tools/publish.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.schedulePostTool = exports.publishNowTool = void 0;
+exports.schedulePostTool = exports.sendToDraftsTool = exports.publishNowTool = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const client_js_1 = require("../client.js");
@@ -48,8 +48,15 @@ const publishSchema = {
         },
         platforms: {
             type: "array",
-            items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
-            description: "Platforms to publish to. Must be connected.",
+            items: { type: "string", enum: ["tiktok", "instagram", "youtube", "linkedin"] },
+            description: "Platforms to publish to (uses the first connected account per platform). Omit when using account_ids. LinkedIn posts the caption as the article body + the images as a native multi-image carousel; LinkedIn has no draft mode.",
+        },
+        account_ids: {
+            type: "array",
+            items: { type: "string" },
+            description: "Specific connection IDs to publish to. Use list_connections to get IDs. " +
+                "Required when you have multiple accounts on the same platform and want to target a specific one. " +
+                "Takes precedence over 'platforms' when both are provided.",
         },
         caption: { type: "string", description: "Post caption." },
         hashtags: {
@@ -58,13 +65,18 @@ const publishSchema = {
             description: "Hashtags without # prefix.",
         },
     },
-    required: ["paths", "platforms", "caption"],
+    required: ["paths", "caption"],
 };
 exports.publishNowTool = {
     name: "publish_now",
-    description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. Pass a folder path to publish all images in it as a carousel.",
+    description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. " +
+        "Pass a folder path to publish all images in it as a carousel. " +
+        "Use account_ids (from list_connections) to target a specific account when you have multiple accounts on the same platform.",
     inputSchema: publishSchema,
     async execute(args) {
+        if (!args.platforms?.length && !args.account_ids?.length) {
+            throw new Error("Provide 'platforms' (e.g. [\"instagram\"]) or 'account_ids' from list_connections.");
+        }
         const filePaths = expandPaths(args.paths);
         if (!filePaths.length)
             throw new Error("No media files found in the provided paths.");
@@ -79,7 +91,8 @@ exports.publishNowTool = {
             result = await (0, client_js_1.post)("/v1/publish/schedule", {
                 media_urls: urls,
                 media_type: mediaType,
-                platforms: args.platforms,
+                platforms: args.platforms ?? [],
+                ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
                 caption: args.caption,
                 hashtags: args.hashtags ?? [],
                 publish_now: true,
@@ -99,6 +112,81 @@ exports.publishNowTool = {
         return summary.trim();
     },
 };
+exports.sendToDraftsTool = {
+    name: "send_to_drafts",
+    description: "Upload local file(s) and send to the platform's drafts (TikTok inbox / YouTube as private) so the user can finish in the mobile app — useful when they want to add licensed music or polish before publishing. " +
+        "Instagram does NOT support drafts via API (IG drafts are local to the mobile app only) — if instagram is in the platforms list, that platform will return an error explaining the limitation. " +
+        "Pass a folder path to send all images as a carousel draft.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Local file path(s) or a folder path. Single video → video draft. Multiple images or image folder → carousel draft.",
+            },
+            platforms: {
+                type: "array",
+                items: { type: "string", enum: ["tiktok", "youtube"] },
+                description: "Platforms to send drafts to. Must be connected. Instagram is not supported (API limitation).",
+            },
+            caption: {
+                type: "string",
+                description: "Caption text. On TikTok video drafts, the caption is NOT used (user enters it in-app); on TikTok photo drafts and YouTube drafts it is preserved.",
+            },
+            hashtags: {
+                type: "array",
+                items: { type: "string" },
+                description: "Hashtags without # prefix.",
+            },
+        },
+        required: ["paths", "platforms", "caption"],
+    },
+    async execute(args) {
+        if (!args.platforms?.length && !args.account_ids?.length) {
+            throw new Error("Provide 'platforms' (e.g. [\"tiktok\"]) or 'account_ids' from list_connections.");
+        }
+        const filePaths = expandPaths(args.paths);
+        if (!filePaths.length)
+            throw new Error("No media files found in the provided paths.");
+        const mediaType = detectMediaType(filePaths);
+        if (mediaType === "carousel" && filePaths.length > 10) {
+            throw new Error(`Carousel max is 10 images. Found ${filePaths.length} files.`);
+        }
+        // Surface the IG-not-supported gotcha before consuming credits / uploading.
+        if (args.platforms?.includes("instagram")) {
+            throw new Error("Instagram does not support drafts via API. IG drafts are local to the mobile app only — " +
+                "there is no API endpoint to send to drafts. Remove 'instagram' from platforms, or use schedule_post / publish_now instead.");
+        }
+        const { urls, storage_paths } = await (0, client_js_1.uploadFiles)(filePaths);
+        let result;
+        try {
+            result = await (0, client_js_1.post)("/v1/publish/schedule", {
+                media_urls: urls,
+                media_type: mediaType,
+                platforms: args.platforms ?? [],
+                ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
+                caption: args.caption,
+                hashtags: args.hashtags ?? [],
+                publish_now: true,
+                mode: "draft",
+            });
+        }
+        finally {
+            await (0, client_js_1.deleteFiles)(storage_paths).catch(() => { });
+        }
+        const { status, platform_post_ids, failed_reason } = result.post;
+        const sentTo = Object.keys(platform_post_ids);
+        let summary = `Status: ${status}\n`;
+        if (sentTo.length) {
+            summary += `Sent to drafts on: ${sentTo.join(", ")}\n`;
+            summary += `Open the platform's mobile app to finish — add music, adjust caption, then publish.`;
+        }
+        if (failed_reason)
+            summary += `\nErrors: ${failed_reason}`;
+        return summary.trim();
+    },
+};
 exports.schedulePostTool = {
     name: "schedule_post",
     description: "Upload local file(s) and schedule a post for a future time. Pass a folder path to schedule all images as a carousel.",
@@ -115,9 +203,12 @@ exports.schedulePostTool = {
                 description: "IANA timezone name (e.g. 'America/New_York'). Defaults to UTC.",
             },
         },
-        required: ["paths", "platforms", "caption", "scheduled_time"],
+        required: ["paths", "caption", "scheduled_time"],
     },
     async execute(args) {
+        if (!args.platforms?.length && !args.account_ids?.length) {
+            throw new Error("Provide 'platforms' (e.g. [\"instagram\"]) or 'account_ids' from list_connections.");
+        }
         const filePaths = expandPaths(args.paths);
         if (!filePaths.length)
             throw new Error("No media files found in the provided paths.");
@@ -128,7 +219,8 @@ exports.schedulePostTool = {
         const result = await (0, client_js_1.post)("/v1/publish/schedule", {
             media_urls: urls,
             media_type: mediaType,
-            platforms: args.platforms,
+            platforms: args.platforms ?? [],
+            ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
             caption: args.caption,
             hashtags: args.hashtags ?? [],
             scheduled_time: args.scheduled_time,
@@ -138,7 +230,10 @@ exports.schedulePostTool = {
         // Note: storage_paths are NOT deleted here — the cron job needs the URLs to stay valid.
         // They expire after 1 hour. For posts scheduled further out, re-upload closer to publish time.
         void storage_paths;
+        const targets = args.account_ids?.length
+            ? `account IDs: ${args.account_ids.join(", ")}`
+            : (args.platforms ?? []).join(", ");
         const { post: p } = result;
-        return `Scheduled post ${p.id}\nPlatforms: ${args.platforms.join(", ")}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
+        return `Scheduled post ${p.id}\nTargets: ${targets}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
     },
 };

package/dist/tools/relight-clip.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relightClipTool = void 0;
+/**
+ * relight_clip — relight / re-scene a SHORT clip (3–10s) via Fal.ai (bundled
+ * relight.py: nano-banana-2 relights one frame, Kling O3 Pro transfers it onto
+ * the clip with audio preserved). PAID, so it's two-phase with a cost gate:
+ *   phase 1 (no confirm): prep + relight ONE frame (~$0.10) → preview + the video
+ *     cost estimate + the folder.
+ *   phase 2 (confirm + folder): run the paid Kling video step.
+ * Needs FAL_KEY in the environment. Best on B-roll / short hero shots — a full
+ * talking-head monologue can drift on the mouth.
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+function pythonBin() { return process.platform === "win32" ? "python" : "python3"; }
+function runRelight(args) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(pythonBin(), [path_1.default.join(engine_js_1.ENGINE_DIR, "relight.py"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => { out += d.toString(); });
+        child.stderr.on("data", (d) => { err += d.toString(); process.stderr.write(d); });
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve(out.trim()) : reject(new Error(err.slice(-300) || out.slice(-300) || `relight exited ${code}`))));
+    });
+}
+function lastJson(s) {
+    const m = s.match(/\{[\s\S]*\}\s*$/);
+    return JSON.parse(m ? m[0] : s);
+}
+exports.relightClipTool = {
+    name: "relight_clip",
+    description: "Relight or re-scene a SHORT clip (3–10s — best on B-roll / short hero shots) via Fal.ai: change the lighting " +
+        "or drop the subject into a new environment, audio preserved. PAID (~$0.10 for the reference frame + ~$0.168/sec " +
+        "for the video). COST-GATED two-step: call WITHOUT confirm → it preps + relights ONE frame and returns a preview " +
+        "+ the video cost + a `folder`; review it, show the user the cost, then call again WITH confirm:true and that " +
+        "`folder` to run the paid video step. Write a geometry-locked, LIGHTING-focused scene_prompt (same framing/pose; " +
+        "change only lighting + background). Needs FAL_KEY in the environment. For a free non-AI color look, use color_grade.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            video_path: { type: "string", description: "Local path to a 3–10s clip." },
+            scene_prompt: { type: "string", description: "Relight/re-scene prompt — keep the EXACT framing/pose; change only lighting + background (e.g. 'hard key from high front-left, deep shadow on the other side, warm rim; soft golden-hour rooftop bokeh behind him')." },
+            reference_image: { type: "string", description: "Optional reference image of the scene/lighting to match." },
+            confirm: { type: "boolean", description: "true = run the PAID video step (only after the user approved the preview + cost)." },
+            folder: { type: "string", description: "The `folder` returned by the first (no-confirm) call — required with confirm:true." },
+            model: { type: "string", enum: ["o3", "o1"], description: "o3 (default, best lip-sync) or o1 (cheaper/faster draft)." },
+        },
+        required: ["video_path", "scene_prompt"],
+    },
+    async execute(args) {
+        if (!process.env.FAL_KEY) {
+            return "relight_clip needs FAL_KEY in the environment. Set it (Windows: setx FAL_KEY \"<key>\") and restart, then try again.";
+        }
+        // Phase 2 — the PAID video transfer.
+        if (args.confirm) {
+            if (!args.folder)
+                return "To run the paid video step, pass the `folder` returned by the first call.";
+            try {
+                const res = lastJson(await runRelight(["video", "--folder", args.folder, ...(args.model ? ["--model", args.model] : [])]));
+                return `Relit clip rendered (audio preserved): ${res.video_path}\nSwap it into your project, or publish it.`;
+            }
+            catch (e) {
+                return `Relight video step failed: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        // Phase 1 — prep + relight ONE frame (cheap), then quote the video cost.
+        let prep;
+        try {
+            prep = lastJson(await runRelight(["prep", "--video", args.video_path, "--title", "relight"]));
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return /3.?10|second|duration/i.test(msg) ? `That clip is outside the 3–10s limit — trim to a ≤10s segment first. (${msg})` : `Couldn't prep the clip: ${msg}`;
+        }
+        try {
+            await runRelight(["image", "--frame", prep.frame_path, "--folder", prep.folder, "--aspect-ratio", String(prep.aspect_ratio), "--prompt", args.scene_prompt, ...(args.reference_image ? ["--reference", args.reference_image] : [])]);
+        }
+        catch (e) {
+            return `Couldn't relight the reference frame: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        const sec = Number(prep.duration) || 0;
+        const perSec = args.model === "o1" ? 0.168 : 0.168;
+        const cost = (0.1 + sec * perSec).toFixed(2);
+        return [
+            `Relit a reference frame ✓ — preview in: ${prep.folder}`,
+            ``,
+            `The PAID video step transfers that look onto the whole ${sec}s clip (audio kept) ≈ $${cost}.`,
+            `Show this cost to the user. To run it, call:`,
+            `  relight_clip(video_path: "${args.video_path}", scene_prompt: "…", confirm: true, folder: "${prep.folder}")`,
+        ].join("\n");
+    },
+};

package/dist/tools/review.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkReviewStatusTool = exports.createReviewLinkTool = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const client_js_1 = require("../client.js");
+const APP_BASE = process.env.VIRALSPIN_APP_URL || "https://app.viralspin.ai";
+function makeToken() {
+    return crypto_1.default.randomBytes(9).toString("base64url").slice(0, 12);
+}
+exports.createReviewLinkTool = {
+    name: "create_review_link",
+    description: "After assembling a video, generate a private shareable review link for a client. " +
+        "The client opens the link in their browser — no account required — sees the video in a " +
+        "premium 'Private Review Room', and clicks Approve or Request Changes. " +
+        "Returns the review URL to paste into an email or DM.",
+    inputSchema: {
+        type: "object",
+        required: ["output_path"],
+        properties: {
+            output_path: {
+                type: "string",
+                description: "The local file path or public URL of the rendered MP4 — e.g. the path returned by create_video_assembly.",
+            },
+            metadata: {
+                type: "object",
+                description: "Optional context shown in the review room: caption, hook_text, style, format, platform_targets.",
+                properties: {
+                    caption: { type: "string" },
+                    hook_text: { type: "string" },
+                    style: { type: "string" },
+                    format: { type: "string", enum: ["9x16", "1x1", "16x9"] },
+                    platform_targets: { type: "array", items: { type: "string" } },
+                },
+            },
+            pin: {
+                type: "string",
+                description: "Optional 4-digit PIN the client must enter before viewing the review.",
+            },
+            expires_hours: {
+                type: "number",
+                description: "How many hours until the link expires (default: 168 = 7 days).",
+            },
+        },
+    },
+    async execute(args) {
+        const token = makeToken();
+        const expiresHours = args.expires_hours ?? 168;
+        await (0, client_js_1.post)("/v1/review-sessions", {
+            token,
+            output_path: args.output_path,
+            metadata: args.metadata ?? {},
+            pin: args.pin ?? null,
+            expires_hours: expiresHours,
+        });
+        const reviewUrl = `${APP_BASE}/review/${token}`;
+        return [
+            `✅ Review link created:`,
+            ``,
+            `  ${reviewUrl}`,
+            ``,
+            `Send this link to your client. They'll see the video in a private premiere room`,
+            `and can Approve or Request Changes — no account required.`,
+            args.pin ? `PIN required: ${args.pin}` : ``,
+            `Link expires in ${expiresHours >= 24 ? `${Math.round(expiresHours / 24)} days` : `${expiresHours}h`}.`,
+            ``,
+            `To check if they've approved: check_review_status with token "${token}"`,
+        ]
+            .filter((l) => l !== undefined)
+            .join("\n");
+    },
+};
+exports.checkReviewStatusTool = {
+    name: "check_review_status",
+    description: "Check whether a client has approved or requested changes on a review link. " +
+        "Pass the token from the URL (e.g. 'abc123xyz456' from /review/abc123xyz456).",
+    inputSchema: {
+        type: "object",
+        required: ["token"],
+        properties: {
+            token: {
+                type: "string",
+                description: "The 12-character review token from the review URL.",
+            },
+        },
+    },
+    async execute({ token }) {
+        const data = await (0, client_js_1.get)(`/v1/review-sessions/${token}/status`);
+        const statusLine = data.status === "approved"
+            ? `✅ Approved${data.approved_at ? ` on ${new Date(data.approved_at).toLocaleString()}` : ""}`
+            : data.status === "rejected"
+                ? `📝 Changes requested`
+                : `⏳ Pending — client hasn't reviewed yet`;
+        const lines = [statusLine];
+        if (data.feedback)
+            lines.push(``, `Client feedback: "${data.feedback}"`);
+        if (data.status === "approved")
+            lines.push(``, `Ready to publish with publish_now or schedule_post.`);
+        return lines.join("\n");
+    },
+};