@viralspin/mcp 0.1.0 → 0.2.0

package/src/tools/kinetic-text.ts

@@ -0,0 +1,130 @@
+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

@@ -0,0 +1,31 @@
+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 +1,58 @@
-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.`;
-  },
-};
+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.`;
+  },
+};