@viralspin/mcp 0.2.0 → 0.2.2

package/src/tools/kinetic-text.ts

@@ -1,130 +0,0 @@
-import { spawn } from "child_process";
-import path from "path";
-
-const ENGINE_DIR =
-  process.env.VIRALSPIN_ASSEMBLY_DIR || path.resolve(__dirname, "../../engine");
-
-const EFFECTS = ["typing", "billboard_flip", "isometric"] as const;
-const STYLES  = ["terminal", "cinematic", "minimal"] as const;
-const FORMATS = ["9x16", "16x9", "1x1"] as const;
-
-interface KineticTextArgs {
-  text: string;
-  effect?: typeof EFFECTS[number];
-  style?: typeof STYLES[number];
-  format?: typeof FORMATS[number];
-  font_size?: number;
-  camera?: {
-    rotateX?: number;
-    rotateY?: number;
-    rotateZ?: number;
-    translateZ?: number;
-  };
-  duration_sec?: number;
-  out?: string;
-}
-
-function runKinetic(args: string[]): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(
-      process.platform === "win32" ? "node.exe" : "node",
-      [path.join(ENGINE_DIR, "kinetic.mjs"), ...args],
-      { cwd: 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) => {
-      const m = stdout.match(/RESULT:(.+)/);
-      if (code === 0 && m) resolve(m[1].trim());
-      else reject(new Error(`Kinetic render failed (exit ${code}). ${stdout.slice(-300)}`));
-    });
-  });
-}
-
-export const createKineticTextTool = {
-  name: "create_kinetic_text",
-  description:
-    "Render a standalone cinematic typing-animation video — great for explainer intros that visually demo " +
-    "what a user types into the prompt. Text is typed out character-by-character with a blinking cursor " +
-    "while a 3D camera slowly pans, giving a cinematic 'Star Wars pull-back' feel. " +
-    "Three effects: 'typing' (character-by-character with 3D camera), " +
-    "'billboard_flip' (words fly from Z-depth and snap into place), " +
-    "'isometric' (letters extrude upward on a tilted plane). " +
-    "Three styles: 'terminal' (green-on-dark, monospace, scanlines), " +
-    "'cinematic' (white-on-black, serif, vignette), " +
-    "'minimal' (transparent background, for overlay use). " +
-    "Returns the path to a finished MP4 — feed it to publish_now or as A-roll in create_video_assembly.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      text: {
-        type: "string",
-        description: "The text to animate — e.g. the prompt the user would type.",
-      },
-      effect: {
-        type: "string",
-        enum: EFFECTS,
-        description: "Animation style. Default: typing.",
-      },
-      style: {
-        type: "string",
-        enum: STYLES,
-        description: "Visual theme. terminal = green monospace; cinematic = white serif; minimal = transparent BG. Default: terminal.",
-      },
-      format: {
-        type: "string",
-        enum: FORMATS,
-        description: "Output aspect ratio. Default: 9x16 (vertical).",
-      },
-      font_size: {
-        type: "number",
-        description: "Font size in px. Auto-sized by format if omitted (72px for 9x16, 96px for 16x9).",
-      },
-      camera: {
-        type: "object",
-        description: "Override the 3D camera end position. Each field defaults to the effect's cinematic preset.",
-        properties: {
-          rotateX:   { type: "number", description: "X-axis tilt in degrees (positive = tilt top toward viewer)." },
-          rotateY:   { type: "number", description: "Y-axis turn in degrees." },
-          rotateZ:   { type: "number", description: "Z-axis roll in degrees." },
-          translateZ: { type: "number", description: "Z-depth offset in px (negative = pull back/zoom out)." },
-        },
-      },
-      duration_sec: {
-        type: "number",
-        description: "Override clip length in seconds. Default: auto (≈ text.length × 0.1s + 1.5s hold).",
-      },
-      out: {
-        type: "string",
-        description: "Output MP4 path. Defaults to engine/out/kinetic_<timestamp>.mp4.",
-      },
-    },
-    required: ["text"],
-  },
-
-  async execute(args: KineticTextArgs): Promise<string> {
-    const cli: string[] = ["--text", args.text];
-    if (args.effect)     cli.push("--effect",      args.effect);
-    if (args.style)      cli.push("--style",        args.style);
-    if (args.format)     cli.push("--format",       args.format);
-    if (args.font_size)  cli.push("--font-size",    String(args.font_size));
-    if (args.duration_sec) cli.push("--duration-sec", String(args.duration_sec));
-    if (args.out)        cli.push("--out",          args.out);
-    if (args.camera) {
-      const c = args.camera;
-      if (c.rotateX   != null) cli.push("--camera-rx", String(c.rotateX));
-      if (c.rotateY   != null) cli.push("--camera-ry", String(c.rotateY));
-      if (c.rotateZ   != null) cli.push("--camera-rz", String(c.rotateZ));
-      if (c.translateZ != null) cli.push("--camera-tz", String(c.translateZ));
-    }
-
-    const outPath = await runKinetic(cli);
-    return (
-      `Kinetic text render complete.\n` +
-      `Output: ${outPath}\n` +
-      `Use this as a hook intro by passing it as A-roll to create_video_assembly, or publish directly with publish_now.`
-    );
-  },
-};

package/src/tools/photo-picker.ts

@@ -1,31 +0,0 @@
-import { post } from "../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.
- */
-export const 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(): Promise<string> {
-    const r = await post<{ sessionId: string; pickerUri: string }>("/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/src/tools/posts.ts

@@ -1,58 +0,0 @@
-import { get, del } from "../client.js";
-
-interface ScheduledPost {
-  id: string;
-  platforms: string[];
-  caption: string;
-  status: string;
-  scheduled_time: string;
-  published_at: string | null;
-  failed_reason: string | null;
-  media_type: string;
-}
-
-export const listPostsTool = {
-  name: "list_posts",
-  description: "List your scheduled, published, or failed posts.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      status: {
-        type: "string",
-        enum: ["pending", "published", "cancelled", "failed"],
-        description: "Filter by status. Omit to list all posts.",
-      },
-    },
-    required: [],
-  },
-
-  async execute(args: { status?: string }) {
-    const qs = args.status ? `?status=${args.status}` : "";
-    const posts = await get<ScheduledPost[]>(`/v1/publish/posts${qs}`);
-    if (!posts.length) return "No posts found.";
-    return posts
-      .map((p) => {
-        const time = p.published_at ?? p.scheduled_time;
-        const label = p.published_at ? "published" : "scheduled";
-        return `[${p.id.slice(0, 8)}] ${p.status.toUpperCase()} — ${p.platforms.join("+")} ${p.media_type} | ${label}: ${time}\n  "${p.caption?.slice(0, 60)}${(p.caption?.length ?? 0) > 60 ? "…" : ""}"${p.failed_reason ? `\n  Error: ${p.failed_reason}` : ""}`;
-      })
-      .join("\n\n");
-  },
-};
-
-export const cancelPostTool = {
-  name: "cancel_post",
-  description: "Cancel a pending scheduled post by ID.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      post_id: { type: "string", description: "The post ID to cancel." },
-    },
-    required: ["post_id"],
-  },
-
-  async execute(args: { post_id: string }) {
-    await del(`/v1/publish/posts/${args.post_id}`);
-    return `Post ${args.post_id} cancelled.`;
-  },
-};

package/src/tools/publish.ts

@@ -1,236 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { post, uploadFiles, deleteFiles } from "../client.js";
-
-const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
-const VIDEO_EXTS = new Set([".mp4", ".mov", ".webm", ".avi"]);
-
-function detectMediaType(filePaths: string[]): "video" | "carousel" {
-  if (filePaths.length > 1) return "carousel";
-  const ext = path.extname(filePaths[0]).toLowerCase();
-  return IMAGE_EXTS.has(ext) ? "carousel" : "video";
-}
-
-/** Expand a folder path into individual file paths (images/videos only, sorted) */
-function expandPaths(inputs: string[]): string[] {
-  const result: string[] = [];
-  for (const p of inputs) {
-    const stat = fs.statSync(p, { throwIfNoEntry: false });
-    if (!stat) throw new Error(`Path not found: ${p}`);
-    if (stat.isDirectory()) {
-      const files = fs.readdirSync(p)
-        .filter((f) => {
-          const ext = path.extname(f).toLowerCase();
-          return IMAGE_EXTS.has(ext) || VIDEO_EXTS.has(ext);
-        })
-        .sort()
-        .map((f) => path.join(p, f));
-      result.push(...files);
-    } else {
-      result.push(p);
-    }
-  }
-  return result;
-}
-
-interface PublishResult {
-  post: { id: string; status: string; platform_post_ids: Record<string, string>; failed_reason?: string };
-}
-
-const publishSchema = {
-  type: "object",
-  properties: {
-    paths: {
-      type: "array",
-      items: { type: "string" },
-      description: "Local file path(s) or a folder path. Single video → video post. Multiple images or image folder → carousel.",
-    },
-    platforms: {
-      type: "array",
-      items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
-      description: "Platforms to publish to. Must be connected.",
-    },
-    caption: { type: "string", description: "Post caption." },
-    hashtags: {
-      type: "array",
-      items: { type: "string" },
-      description: "Hashtags without # prefix.",
-    },
-  },
-  required: ["paths", "platforms", "caption"],
-};
-
-export const 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.",
-  inputSchema: publishSchema,
-
-  async execute(args: { paths: string[]; platforms: string[]; caption: string; hashtags?: string[] }) {
-    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(`Instagram supports max 10 images per carousel. Found ${filePaths.length} files.`);
-    }
-
-    // Upload files
-    const { urls, storage_paths } = await uploadFiles(filePaths);
-
-    let result: PublishResult;
-    try {
-      result = await post<PublishResult>("/v1/publish/schedule", {
-        media_urls: urls,
-        media_type: mediaType,
-        platforms: args.platforms,
-        caption: args.caption,
-        hashtags: args.hashtags ?? [],
-        publish_now: true,
-      });
-    } finally {
-      // Always clean up uploaded files
-      await deleteFiles(storage_paths).catch(() => {});
-    }
-
-    const { status, platform_post_ids, failed_reason } = result.post;
-    const published = Object.keys(platform_post_ids);
-    let summary = `Status: ${status}\n`;
-    if (published.length) summary += `Published to: ${published.join(", ")}\n`;
-    if (failed_reason) summary += `Errors: ${failed_reason}`;
-    return summary.trim();
-  },
-};
-
-export const 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: { paths: string[]; platforms: string[]; caption: string; hashtags?: string[] }) {
-    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 uploadFiles(filePaths);
-
-    let result: PublishResult;
-    try {
-      result = await post<PublishResult>("/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 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();
-  },
-};
-
-export const 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.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      ...publishSchema.properties,
-      scheduled_time: {
-        type: "string",
-        description: "ISO 8601 datetime string for when to publish (e.g. '2026-05-10T09:00:00'). Uses your local timezone if no timezone offset provided.",
-      },
-      timezone: {
-        type: "string",
-        description: "IANA timezone name (e.g. 'America/New_York'). Defaults to UTC.",
-      },
-    },
-    required: ["paths", "platforms", "caption", "scheduled_time"],
-  },
-
-  async execute(args: {
-    paths: string[];
-    platforms: string[];
-    caption: string;
-    hashtags?: string[];
-    scheduled_time: string;
-    timezone?: string;
-  }) {
-    const filePaths = expandPaths(args.paths);
-    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
-
-    const mediaType = detectMediaType(filePaths);
-
-    // Upload files (storage URLs remain valid for 1 hour; cron will publish before then if scheduled soon,
-    // otherwise the cron route will fail — advise scheduling within the hour for now)
-    const { urls, storage_paths } = await uploadFiles(filePaths);
-
-    const result = await post<PublishResult>("/v1/publish/schedule", {
-      media_urls: urls,
-      media_type: mediaType,
-      platforms: args.platforms,
-      caption: args.caption,
-      hashtags: args.hashtags ?? [],
-      scheduled_time: args.scheduled_time,
-      timezone: args.timezone,
-      publish_now: false,
-    });
-
-    // 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 { post: p } = result;
-    return `Scheduled post ${p.id}\nPlatforms: ${args.platforms.join(", ")}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
-  },
-};

package/src/tools/review.ts

@@ -1,126 +0,0 @@
-import crypto from "crypto";
-import { get, post } from "../client.js";
-
-const APP_BASE = process.env.VIRALSPIN_APP_URL || "https://app.viralspin.ai";
-
-function makeToken(): string {
-  return crypto.randomBytes(9).toString("base64url").slice(0, 12);
-}
-
-interface CreateReviewArgs {
-  output_path: string;
-  metadata?: {
-    caption?: string;
-    hook_text?: string;
-    style?: string;
-    format?: "9x16" | "1x1" | "16x9";
-    platform_targets?: string[];
-  };
-  pin?: string;
-  expires_hours?: number;
-}
-
-interface ReviewStatusResponse {
-  status: "pending" | "approved" | "rejected";
-  feedback: string | null;
-  approved_at: string | null;
-}
-
-export const 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" as const,
-    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: CreateReviewArgs): Promise<string> {
-    const token = makeToken();
-    const expiresHours = args.expires_hours ?? 168;
-
-    await 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");
-  },
-};
-
-export const 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" as const,
-    required: ["token"],
-    properties: {
-      token: {
-        type: "string",
-        description: "The 12-character review token from the review URL.",
-      },
-    },
-  },
-  async execute({ token }: { token: string }): Promise<string> {
-    const data = await get<ReviewStatusResponse>(`/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");
-  },
-};