@viralspin/mcp 0.1.0 → 0.2.0

package/dist/tools/photo-picker.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startPhotoPickerTool = void 0;
+const client_js_1 = require("../client.js");
+/**
+ * Opens a Google Photos Picker session for choosing B-roll. Google does NOT allow
+ * apps to list or search a user's albums programmatically (Library API readonly was
+ * removed 2025-03-31), so the user searches/selects inside Google's own picker UI.
+ * This tool just hands back the picker link + sessionId; create_video_assembly then
+ * ingests the picks via google_picker_session.
+ */
+exports.startPhotoPickerTool = {
+    name: "start_photo_picker",
+    description: "Open a Google Photos picker to choose B-roll for create_video_assembly. Returns a link to open in your browser. " +
+        "Google does not allow listing or searching your albums programmatically — so use the picker's OWN search box to find an " +
+        "album or topic that matches your video (by person, place, event, or theme), select the photos/clips, and finish. " +
+        "Then call create_video_assembly with google_picker_session set to the returned sessionId. " +
+        "Requires a Google account connected at app.viralspin.ai/settings.",
+    inputSchema: { type: "object", properties: {} },
+    async execute() {
+        const r = await (0, client_js_1.post)("/v1/assembly/picker", {});
+        return [
+            "📸 Open this link to pick your Google Photos B-roll:",
+            r.pickerUri,
+            "",
+            "Tip: use the picker's search box to find an album/topic that matches your video — by person, place, event, or theme — then select the clips/photos and finish.",
+            "",
+            `When done, run create_video_assembly with:  google_picker_session: "${r.sessionId}"  (plus your A-roll).`,
+        ].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");
@@ -99,6 +99,77 @@ 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) {
+        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,
+                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.",

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");
+    },
+};

package/dist/tools/video-assembly.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVideoAssemblyTool = void 0;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const client_js_1 = require("../client.js");
+// The assembly engine ships inside this package (mcp/engine). Override with env if needed.
+// __dirname at runtime = mcp/dist/tools → ../../engine = mcp/engine.
+const ENGINE_DIR = process.env.VIRALSPIN_ASSEMBLY_DIR || path_1.default.resolve(__dirname, "../../engine");
+const BROLL_STYLE_KEYS = ["sketchbook", "cinematic_minimal", "dark_studio", "vibrant_illustrated"];
+const CAPTION_STYLE_KEYS = ["auto", "default", "hormozi", "glow_neon", "minimalist", "whiteboard"];
+/** Run the engine orchestrator, streaming its logs to stderr, and capture RESULT:<path>. */
+function runEngine(args, extraEnv = {}) {
+    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, ...extraEnv } });
+        let stdout = "";
+        child.stdout.on("data", (d) => { stdout += d.toString(); });
+        child.stderr.on("data", (d) => process.stderr.write(d)); // progress → MCP server log
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const m = stdout.match(/RESULT:(.+)/);
+            if (code === 0 && m)
+                resolve(m[1].trim());
+            else
+                reject(new Error(`Assembly engine exited ${code}. ${stdout.slice(-400)}`));
+        });
+    });
+}
+exports.createVideoAssemblyTool = {
+    name: "create_video_assembly",
+    description: "Turn an A-roll talking-head/performance clip into a polished vertical (9:16) short by editing in B-roll cutaways. " +
+        "Runs a LOCAL pipeline: transcribes the A-roll, finds each B-roll's focal point (face/subject-aware so nothing is cropped off), " +
+        "matches B-roll to what's being said, and renders with Ken Burns motion + the speaker's voice as the soundtrack (B-roll clip audio is mixed in as a low faded bed). " +
+        "Accepts LOCAL file paths OR public URLs for both A-roll and B-roll, and a B-roll FOLDER is expanded automatically. " +
+        "Pass style_ref (a reference video) to AUTO-INFER the editing style from it — captions, hook headline, keyword pops, pace, and aspect ratio — so you don't have to describe them. " +
+        "Returns the path to the finished MP4, which you can then publish with publish_now / schedule_post.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            aroll: {
+                type: "string",
+                description: "A-roll source: a local file path (e.g. C:/clips/talk.mp4) OR a public video URL.",
+            },
+            broll: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional B-roll sources: local file paths, a local FOLDER (expanded to its images/videos), and/or public URLs. " +
+                    "Mix freely. Omit for an A-roll-only edit (just motion, no cutaways).",
+            },
+            prompt: {
+                type: "string",
+                description: "Optional creative direction for the edit (mood, what to emphasise, pacing).",
+            },
+            output_format: {
+                type: "string",
+                enum: ["9x16", "1x1", "16x9"],
+                description: "Aspect ratio. Default 9x16 (vertical for Reels/TikTok/Shorts).",
+            },
+            out: {
+                type: "string",
+                description: "Optional output MP4 path. Defaults to the engine's out/ folder.",
+            },
+            google_picker_session: {
+                type: "string",
+                description: "Optional sessionId from start_photo_picker. If set, the photos/clips you picked in Google Photos are ingested as B-roll (in addition to any `broll`).",
+            },
+            style_ref: {
+                type: "string",
+                description: "Optional reference video (local path or URL). The tool watches it and infers the edit style — captions on/off + style, hook headline, keyword pops, cut pace, and aspect ratio — and applies it automatically. Overrides output_format when set.",
+            },
+            broll_mode: {
+                type: "string",
+                enum: ["user_provided", "ai_generated"],
+                description: "B-roll source mode. 'user_provided' (default) = use local files or Google Photos. 'ai_generated' = AI reads the transcript and generates stylized cinematic B-roll images — no local footage needed. Requires the 'style' param.",
+            },
+            style: {
+                type: "string",
+                enum: BROLL_STYLE_KEYS,
+                description: "Style anchor for AI-generated B-roll (required when broll_mode='ai_generated'). " +
+                    "sketchbook = hand-drawn ink on graph paper; " +
+                    "cinematic_minimal = flat-lay dark surface, warm tungsten lamp; " +
+                    "dark_studio = matte black workspace, designer aesthetic; " +
+                    "vibrant_illustrated = bold pop-art flat illustration.",
+            },
+            explainer_index_id: {
+                type: "string",
+                description: "Optional Twelve Labs index ID returned by index_explainer_sources. " +
+                    "When set, long-form videos (>2 min) in the broll folder are searched semantically " +
+                    "instead of being clipped from their start. Requires TWELVE_LABS_API_KEY in the MCP env.",
+            },
+            caption_style: {
+                type: "string",
+                enum: CAPTION_STYLE_KEYS,
+                description: "Caption style. Default 'auto' = AI picks the best style from the transcript. " +
+                    "default = bold white spring pop-in. " +
+                    "hormozi = word-by-word yellow highlight (high-energy talking-head). " +
+                    "glow_neon = neon cyan pulsing text (dark aesthetic, music, gaming). " +
+                    "minimalist = lowercase thin font fade-in (calm, educational). " +
+                    "whiteboard = left-to-right text reveal (explainers, tutorials). " +
+                    "After rendering, change it instantly with swap_caption_style.",
+            },
+        },
+        required: ["aroll"],
+    },
+    async execute(args) {
+        // AI-generated B-roll mode: delegate to the cloud narrative pipeline.
+        if (args.broll_mode === "ai_generated") {
+            if (!args.style) {
+                return "Error: 'style' is required when broll_mode='ai_generated'. Choose one of: sketchbook, cinematic_minimal, dark_studio, vibrant_illustrated.";
+            }
+            const job = await (0, client_js_1.post)("/v1/narrative/jobs", {
+                aroll_paths: [args.aroll],
+                prompt: args.prompt,
+                output_format: args.output_format ?? "9x16",
+                broll_mode: "ai_generated",
+                style_anchor: args.style,
+            });
+            const deadline = Date.now() + 15 * 60 * 1000;
+            let result = { status: "queued" };
+            while (Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, 6000));
+                result = await (0, client_js_1.get)(`/v1/narrative/jobs/${job.job_id}`);
+                if (result.status === "complete" || result.status === "failed")
+                    break;
+            }
+            if (result.status === "failed")
+                return `Assembly failed: ${result.error_message ?? "unknown error"}`;
+            if (result.status !== "complete")
+                return `Assembly timed out. Job ID: ${job.job_id} — check the dashboard.`;
+            return (`AI B-roll assembly complete (style: ${args.style}).\n` +
+                `Preview: ${result.preview_url ?? "—"}\n` +
+                `Download: ${result.download_url ?? "—"}\n` +
+                `Publish it with publish_now or schedule_post.`);
+        }
+        const broll = [...(args.broll ?? [])];
+        // Pull in Google Photos picks (re-hosted to public URLs by the backend), if any.
+        if (args.google_picker_session) {
+            const r = await (0, client_js_1.get)(`/v1/assembly/picker?sessionId=${encodeURIComponent(args.google_picker_session)}`);
+            if (r.status !== "ready") {
+                return "Your Google Photos picks aren't ready yet — finish selecting in the picker tab, then run create_video_assembly again with the same google_picker_session.";
+            }
+            for (const it of r.items ?? [])
+                broll.push(it.url);
+        }
+        const cli = ["--aroll", args.aroll];
+        if (broll.length)
+            cli.push("--broll", ...broll);
+        if (args.prompt)
+            cli.push("--prompt", args.prompt);
+        if (args.style_ref)
+            cli.push("--style-ref", args.style_ref);
+        if (args.output_format)
+            cli.push("--format", args.output_format);
+        if (args.out)
+            cli.push("--out", args.out);
+        if (args.caption_style && args.caption_style !== "auto")
+            cli.push("--caption-style", args.caption_style);
+        // Pull the admin-managed "secret sauce" prompts (LLM Prompt Store →
+        // LOCAL VIDEO ASSEMBLY section) and hand them to the engine. Best-effort:
+        // on any failure the engine falls back to its built-in prompts.
+        const extraEnv = {};
+        try {
+            const r = await (0, client_js_1.get)("/v1/assembly/prompts");
+            if (r.prompts && Object.keys(r.prompts).length) {
+                extraEnv.VIRALSPIN_ASSEMBLY_PROMPTS = JSON.stringify(r.prompts);
+            }
+        }
+        catch { /* engine uses built-in prompts */ }
+        if (args.explainer_index_id) {
+            extraEnv.EXPLAINER_INDEX_ID = args.explainer_index_id;
+        }
+        if (process.env.TWELVE_LABS_API_KEY) {
+            extraEnv.TWELVE_LABS_API_KEY = process.env.TWELVE_LABS_API_KEY;
+        }
+        const outPath = await runEngine(cli, extraEnv);
+        return (`Video assembly complete.\n` +
+            `Output: ${outPath}\n` +
+            `Publish it with publish_now (paths: ["${outPath}"]) or schedule_post.`);
+    },
+};