@viralspin/mcp 0.1.0 → 0.2.0

package/src/tools/engage.ts

@@ -0,0 +1,105 @@
+import { get, post, del } from "../client.js";
+
+interface KeywordLink {
+  id: string;
+  keyword: string;
+  link: string;
+  platform: string | null;
+  media_id: string | null;
+  match_type: "exact" | "contains";
+  is_active: boolean;
+  reply_to_comment: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+function describe(k: KeywordLink): string {
+  const scope = k.media_id ? `post ${k.media_id}` : "all posts";
+  const platform = k.platform ?? "any platform";
+  const reply = k.reply_to_comment ? ", + comment reply" : ", DM only";
+  const status = k.is_active ? "" : " (paused)";
+  return `"${k.keyword}" → ${k.link}  [${platform}, ${scope}, ${k.match_type}${reply}]${status}`;
+}
+
+export const setKeywordLinkTool = {
+  name: "set_keyword_link",
+  description:
+    "Map a keyword to a resource/destination link for DM automation. When a follower comments/DMs the keyword, " +
+    "the link is sent back (delivery activates once Instagram messaging access is approved). " +
+    "Re-running with the same keyword + scope updates the link instead of creating a duplicate. " +
+    "Omit media_id for a global rule (fires on any post); set media_id for a single post.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      keyword: { type: "string", description: "The trigger word, e.g. 'guide' or 'link'. Case-insensitive." },
+      link: { type: "string", description: "The destination URL to send (e.g. a resource-hub article)." },
+      platform: {
+        type: "string",
+        enum: ["instagram", "tiktok", "youtube"],
+        description: "Platform this rule applies to. Omit for any connected platform. Only Instagram delivers today.",
+      },
+      media_id: {
+        type: "string",
+        description: "Optional. A specific post/media id to scope the rule to. Omit for a global rule across all posts.",
+      },
+      match_type: {
+        type: "string",
+        enum: ["exact", "contains"],
+        description: "'contains' (default) fires if the comment includes the keyword; 'exact' requires a full match.",
+      },
+      reply_to_comment: {
+        type: "boolean",
+        description: "Also post a public reply to the comment (e.g. 'Check your DMs', wording varies). Defaults to true.",
+      },
+    },
+    required: ["keyword", "link"],
+  },
+
+  async execute(args: { keyword: string; link: string; platform?: string; media_id?: string; match_type?: string; reply_to_comment?: boolean }) {
+    const created = await post<KeywordLink>("/v1/engage/keyword-links", {
+      keyword: args.keyword,
+      link: args.link,
+      platform: args.platform ?? null,
+      media_id: args.media_id ?? null,
+      match_type: args.match_type ?? "contains",
+      reply_to_comment: args.reply_to_comment ?? true,
+    });
+    return `Saved: ${describe(created)}`;
+  },
+};
+
+export const listKeywordLinksTool = {
+  name: "list_keyword_links",
+  description: "List your keyword→link DM-automation rules.",
+  inputSchema: { type: "object", properties: {}, required: [] },
+
+  async execute(_args: Record<string, unknown>) {
+    const rules = await get<KeywordLink[]>("/v1/engage/keyword-links");
+    if (!rules.length) {
+      return "No keyword→link rules yet. Use set_keyword_link to add one (e.g. map 'guide' to your resource link).";
+    }
+    return rules.map((r) => `• ${describe(r)}`).join("\n");
+  },
+};
+
+export const deleteKeywordLinkTool = {
+  name: "delete_keyword_link",
+  description: "Delete a keyword→link rule by its keyword. If multiple rules share the keyword, all of them are removed.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      keyword: { type: "string", description: "The keyword whose rule(s) should be deleted." },
+    },
+    required: ["keyword"],
+  },
+
+  async execute(args: { keyword: string }) {
+    const rules = await get<KeywordLink[]>("/v1/engage/keyword-links");
+    const matches = rules.filter((r) => r.keyword.toLowerCase() === args.keyword.trim().toLowerCase());
+    if (!matches.length) return `No rule found for keyword "${args.keyword}".`;
+    for (const m of matches) {
+      await del(`/v1/engage/keyword-links/${m.id}`);
+    }
+    return `Deleted ${matches.length} rule(s) for "${args.keyword}".`;
+  },
+};

package/src/tools/explainer-index.ts

@@ -0,0 +1,298 @@
+import fs from "node:fs";
+import https from "node:https";
+import path from "node:path";
+import os from "node:os";
+
+const TL_BASE = "https://api.twelvelabs.io/v1.3";
+const VIRALSPIN_HOME = path.join(os.homedir(), ".viralspin");
+const CACHE_FILE = path.join(VIRALSPIN_HOME, "explainer_cache.json");
+
+// ── Cache helpers ──────────────────────────────────────────────────────────
+
+interface CacheEntry {
+  video_id: string;
+  index_id: string;
+}
+
+interface Cache {
+  indexes: Record<string, string>; // folderPath → index_id
+  videos: Record<string, CacheEntry>; // "filePath|size" → { video_id, index_id }
+}
+
+function readCache(): Cache {
+  try {
+    if (fs.existsSync(CACHE_FILE)) return JSON.parse(fs.readFileSync(CACHE_FILE, "utf8"));
+  } catch { /* ignore */ }
+  return { indexes: {}, videos: {} };
+}
+
+function writeCache(c: Cache) {
+  fs.mkdirSync(VIRALSPIN_HOME, { recursive: true });
+  fs.writeFileSync(CACHE_FILE, JSON.stringify(c, null, 2));
+}
+
+function cacheKey(filePath: string): string {
+  try {
+    const stat = fs.statSync(filePath);
+    return `${filePath}|${stat.size}`;
+  } catch {
+    return filePath;
+  }
+}
+
+// ── Twelve Labs REST helpers ───────────────────────────────────────────────
+
+function tlFetch(method: string, urlPath: string, body?: unknown, apiKey?: string): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const key = apiKey || process.env.TWELVE_LABS_API_KEY || "";
+    const bodyBuf = body ? Buffer.from(JSON.stringify(body)) : undefined;
+    const req = https.request(`${TL_BASE}${urlPath}`, {
+      method,
+      headers: {
+        "x-api-key": key,
+        "Content-Type": "application/json",
+        ...(bodyBuf ? { "Content-Length": bodyBuf.length } : {}),
+      },
+    }, (res) => {
+      const chunks: Buffer[] = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => {
+        const text = Buffer.concat(chunks).toString();
+        try { resolve(JSON.parse(text)); }
+        catch { reject(new Error(`TL parse error: ${text.slice(0, 200)}`)); }
+      });
+    });
+    req.on("error", reject);
+    if (bodyBuf) req.write(bodyBuf);
+    req.end();
+  });
+}
+
+async function tlUploadFile(filePath: string, indexId: string, apiKey: string): Promise<string> {
+  // Multipart upload using form-data
+  const { default: FormData } = await import("form-data" as any);
+  const form = new FormData();
+  form.append("index_id", indexId);
+  form.append("language", "en");
+  form.append("video_file", fs.createReadStream(filePath), { filename: path.basename(filePath) });
+
+  return new Promise((resolve, reject) => {
+    const headers = { ...form.getHeaders(), "x-api-key": apiKey };
+    const req = https.request(`${TL_BASE}/tasks`, { method: "POST", headers }, (res) => {
+      const chunks: Buffer[] = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => {
+        try {
+          const d = JSON.parse(Buffer.concat(chunks).toString());
+          resolve(d._id || d.id);
+        } catch (e) {
+          reject(new Error(`TL upload parse error: ${Buffer.concat(chunks).toString().slice(0, 200)}`));
+        }
+      });
+    });
+    req.on("error", reject);
+    form.pipe(req);
+  });
+}
+
+async function waitForTask(taskId: string, apiKey: string): Promise<string> {
+  const deadline = Date.now() + 30 * 60 * 1000; // 30-min max
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 8000));
+    const d = await tlFetch("GET", `/tasks/${taskId}`, undefined, apiKey);
+    if (d.status === "ready") return d.video_id;
+    if (d.status === "failed") throw new Error(`Twelve Labs indexing failed for task ${taskId}: ${d.error || ""}`);
+  }
+  throw new Error(`Twelve Labs indexing timed out for task ${taskId}`);
+}
+
+async function getOrCreateIndex(folderPath: string, indexName: string, apiKey: string): Promise<string> {
+  const cache = readCache();
+  if (cache.indexes[folderPath]) return cache.indexes[folderPath];
+
+  // Create a new index
+  const d = await tlFetch("POST", "/indexes", {
+    name: indexName,
+    engines: [{ name: "marengo2.6", options: ["visual", "conversation", "text_in_video"] }],
+  }, apiKey);
+  const indexId: string = d._id || d.id;
+  cache.indexes[folderPath] = indexId;
+  writeCache(cache);
+  return indexId;
+}
+
+// ── Folder walking ─────────────────────────────────────────────────────────
+
+const VIDEO_EXTS = new Set([".mp4", ".mkv", ".mov", ".avi", ".wmv", ".webm"]);
+
+function walkFolder(folder: string): string[] {
+  const results: string[] = [];
+  try {
+    for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+      const full = path.join(folder, entry.name);
+      if (entry.isDirectory()) results.push(...walkFolder(full));
+      else if (VIDEO_EXTS.has(path.extname(entry.name).toLowerCase())) results.push(full);
+    }
+  } catch { /* ignore permission errors */ }
+  return results;
+}
+
+// ── Tool definition ────────────────────────────────────────────────────────
+
+interface IndexArgs {
+  sources_folder: string;
+  index_name?: string;
+}
+
+export const indexExplainerSourcesTool = {
+  name: "index_explainer_sources",
+  description:
+    "Index a local folder of screen recordings and OBS videos with Twelve Labs so they can be searched semantically " +
+    "inside create_video_assembly. Call this once per folder — indexing is cached, so re-running skips already-indexed files. " +
+    "Returns an index_id to pass as explainer_index_id in create_video_assembly. " +
+    "Requires TWELVE_LABS_API_KEY in the MCP environment.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sources_folder: {
+        type: "string",
+        description: "Local folder containing your screen recordings / OBS videos (e.g. C:/obs-recordings).",
+      },
+      index_name: {
+        type: "string",
+        description: "Optional name for the Twelve Labs index (defaults to the folder's base name).",
+      },
+    },
+    required: ["sources_folder"],
+  },
+
+  async execute(args: IndexArgs): Promise<string> {
+    const apiKey = process.env.TWELVE_LABS_API_KEY;
+    if (!apiKey) {
+      return "Error: TWELVE_LABS_API_KEY is not set in the MCP environment. Add it to your ~/.claude.json MCP config under env.TWELVE_LABS_API_KEY.";
+    }
+
+    const folder = args.sources_folder;
+    if (!fs.existsSync(folder)) {
+      return `Error: folder not found: ${folder}`;
+    }
+
+    const indexName = args.index_name || path.basename(folder) || "viralspin-explainer";
+    process.stderr.write(`[explainer-index] Getting/creating Twelve Labs index for ${folder}…\n`);
+    const indexId = await getOrCreateIndex(folder, indexName, apiKey);
+    process.stderr.write(`[explainer-index] index_id=${indexId}\n`);
+
+    const videos = walkFolder(folder);
+    if (videos.length === 0) {
+      return `No video files found in ${folder}. Supported formats: ${[...VIDEO_EXTS].join(", ")}`;
+    }
+
+    const cache = readCache();
+    let indexed = 0;
+    let skipped = 0;
+    const errors: string[] = [];
+
+    for (const vpath of videos) {
+      const key = cacheKey(vpath);
+      if (cache.videos[key]) {
+        skipped++;
+        process.stderr.write(`[explainer-index] skip (cached): ${path.basename(vpath)}\n`);
+        continue;
+      }
+      process.stderr.write(`[explainer-index] uploading: ${path.basename(vpath)}…\n`);
+      try {
+        const taskId = await tlUploadFile(vpath, indexId, apiKey);
+        process.stderr.write(`[explainer-index] waiting for task ${taskId}…\n`);
+        const videoId = await waitForTask(taskId, apiKey);
+        cache.videos[key] = { video_id: videoId, index_id: indexId };
+        writeCache(cache);
+        indexed++;
+        process.stderr.write(`[explainer-index] indexed: ${path.basename(vpath)} → video_id=${videoId}\n`);
+      } catch (e: any) {
+        errors.push(`${path.basename(vpath)}: ${e?.message || e}`);
+        process.stderr.write(`[explainer-index] ERROR: ${e?.message || e}\n`);
+      }
+    }
+
+    const parts = [
+      `Index ready: ${indexId}`,
+      `  Newly indexed: ${indexed} video${indexed !== 1 ? "s" : ""}`,
+      `  Already cached: ${skipped}`,
+      `  Total in folder: ${videos.length}`,
+      "",
+      `Pass this to create_video_assembly as:  explainer_index_id: "${indexId}"`,
+    ];
+    if (errors.length) {
+      parts.push("", `Errors (${errors.length}):`, ...errors.map((e) => `  • ${e}`));
+    }
+    return parts.join("\n");
+  },
+};
+
+// ── Clip retrieval (used by assemble.mjs via env forwarding) ───────────────
+// Exported so assemble.mjs can also call this logic if needed in future.
+
+export async function searchAndExtract(
+  searchQuery: string,
+  indexId: string,
+  outDir: string,
+  clipIndex: number,
+): Promise<{ clip_path: string; confidence: number; start_sec: number } | null> {
+  const apiKey = process.env.TWELVE_LABS_API_KEY;
+  if (!apiKey) return null;
+
+  try {
+    const result = await tlFetch("POST", "/search", {
+      query_text: searchQuery,
+      index_id: indexId,
+      search_options: ["visual", "conversation", "text_in_video"],
+      page_limit: 1,
+    }, apiKey);
+
+    const hit = result?.data?.[0];
+    if (!hit) return null;
+
+    const videoId: string = hit.video_id;
+    const startSec: number = hit.start || 0;
+    const endSec: number = hit.end || startSec + 15;
+    const confidence: number = hit.score || 0;
+
+    // Look up local path from cache
+    const cache = readCache();
+    let localPath: string | null = null;
+    for (const entry of Object.values(cache.videos)) {
+      if (entry.video_id === videoId && entry.index_id === indexId) {
+        // Find the key (which is "filePath|size")
+        for (const [key, val] of Object.entries(cache.videos)) {
+          if (val.video_id === videoId) {
+            localPath = key.split("|")[0];
+            break;
+          }
+        }
+        break;
+      }
+    }
+
+    if (!localPath || !fs.existsSync(localPath)) return null;
+
+    const outPath = path.join(outDir, `explainer_clip_${clipIndex}.mp4`);
+    const duration = Math.min(endSec - startSec, 30);
+    const { spawn } = await import("child_process");
+
+    await new Promise<void>((resolve, reject) => {
+      const ff = spawn("ffmpeg", [
+        "-y", "-ss", String(startSec), "-t", String(duration),
+        "-i", localPath!,
+        "-c:v", "libx264", "-crf", "26", "-c:a", "aac", "-movflags", "+faststart",
+        outPath,
+      ]);
+      ff.on("close", (code) => code === 0 ? resolve() : reject(new Error(`ffmpeg exit ${code}`)));
+      ff.on("error", reject);
+    });
+
+    return { clip_path: outPath, confidence, start_sec: startSec };
+  } catch (e: any) {
+    process.stderr.write(`[explainer-index] searchAndExtract error: ${e?.message || e}\n`);
+    return null;
+  }
+}

package/src/tools/image-ads.ts

@@ -0,0 +1,192 @@
+import { get, post, pyPost, pyGet, uploadFiles } from "../client.js";
+
+const APP_BASE = process.env.VIRALSPIN_APP_URL || "https://app.viralspin.ai";
+
+interface PrepareAssetArgs {
+  image_url: string;
+}
+
+interface AssembleImageAdArgs {
+  product_image_path: string;
+  prompt: string;
+  pin?: string;
+}
+
+interface PublishToMetaArgs {
+  media_url: string;
+  platforms: ("instagram" | "facebook")[];
+  caption: string;
+}
+
+export const prepareProductAssetTool = {
+  name: "prepare_product_asset",
+  description:
+    "Download and verify a product image from a local path or public URL, upload it to ViralSpin " +
+    "cloud storage, and return a stable cloud URL ready for Higgsfield image ad generation.",
+  inputSchema: {
+    type: "object" as const,
+    required: ["image_url"],
+    properties: {
+      image_url: {
+        type: "string",
+        description:
+          "Local file path (e.g. C:/photos/product.jpg) or public URL of the product image.",
+      },
+    },
+  },
+  async execute({ image_url }: PrepareAssetArgs): Promise<string> {
+    if (image_url.startsWith("http://") || image_url.startsWith("https://")) {
+      return `✅ Asset ready (already a URL):\n\n  ${image_url}\n\nPass this to assemble_image_ad.`;
+    }
+    const { urls } = await uploadFiles([image_url]);
+    return [
+      `✅ Product asset uploaded:`,
+      ``,
+      `  ${urls[0]}`,
+      ``,
+      `Pass this URL to assemble_image_ad.`,
+    ].join("\n");
+  },
+};
+
+export const assembleImageAdTool = {
+  name: "assemble_image_ad",
+  description:
+    "Generate image ad variants from a product photo using Higgsfield AI. " +
+    "Uploads the product image, generates styled variants with your prompt, then creates a " +
+    "client review link showing all variants in a carousel. " +
+    "Requires Higgsfield credentials saved in ViralSpin Settings.",
+  inputSchema: {
+    type: "object" as const,
+    required: ["product_image_path", "prompt"],
+    properties: {
+      product_image_path: {
+        type: "string",
+        description: "Local file path (e.g. C:/photos/product.jpg) or public URL of the product image.",
+      },
+      prompt: {
+        type: "string",
+        description:
+          "Higgsfield styling prompt describing the desired ad aesthetic. " +
+          "Example: 'luxury product shot on white marble, soft studio lighting, premium brand aesthetic'",
+      },
+      pin: {
+        type: "string",
+        description: "Optional 4-digit PIN to protect the client review link.",
+      },
+    },
+  },
+  async execute({ product_image_path, prompt, pin }: AssembleImageAdArgs): Promise<string> {
+    // Upload local files; pass through URLs unchanged
+    let imageUrl = product_image_path;
+    if (!product_image_path.startsWith("http://") && !product_image_path.startsWith("https://")) {
+      const { urls } = await uploadFiles([product_image_path]);
+      imageUrl = urls[0];
+    }
+
+    // Start async generation job — Higgsfield lives on Python backend
+    const { job_id } = await pyPost<{ job_id: string }>("/v1/higgsfield/generate", {
+      product_image_url: imageUrl,
+      prompt,
+    });
+
+    // Poll until done (~3 min timeout)
+    let variants: string[] = [];
+    for (let attempt = 0; attempt < 40; attempt++) {
+      await new Promise((r) => setTimeout(r, 5000));
+      const status = await pyGet<{
+        status: string;
+        variant_urls?: string[];
+        error?: string;
+      }>(`/v1/higgsfield/status/${job_id}`);
+
+      if (status.status === "complete") {
+        variants = status.variant_urls ?? [];
+        break;
+      }
+      if (status.status === "failed") {
+        throw new Error(`Higgsfield generation failed: ${status.error ?? "unknown error"}`);
+      }
+    }
+
+    if (!variants.length) {
+      throw new Error("Generation timed out after ~3 minutes — try again or check Higgsfield credentials");
+    }
+
+    // Create a review session with image variants displayed as a carousel
+    const { token } = await post<{ token: string; review_url: string }>("/v1/review-sessions", {
+      output_path: variants[0],
+      metadata: {
+        media_type: "image",
+        variants,
+        caption: prompt,
+        platform_targets: ["instagram", "facebook"],
+      },
+      pin: pin ?? null,
+      expires_hours: 168,
+    });
+
+    const reviewUrl = `${APP_BASE}/review/${token}`;
+    return [
+      `✅ ${variants.length} image ad variant${variants.length > 1 ? "s" : ""} generated!`,
+      ``,
+      `Review link: ${reviewUrl}`,
+      ``,
+      `Send this to your client — they'll see all ${variants.length} variants as a carousel`,
+      `and can Approve or Request Changes.`,
+      pin ? `PIN: ${pin}` : ``,
+      ``,
+      `To publish an approved variant:`,
+      `  publish_to_meta with media_url="${variants[0]}" and your caption.`,
+    ]
+      .filter((l) => l !== undefined)
+      .join("\n");
+  },
+};
+
+export const publishToMetaTool = {
+  name: "publish_to_meta",
+  description:
+    "Publish an image (or video) to Instagram and/or Facebook. " +
+    "Use after a client approves an image ad variant from assemble_image_ad.",
+  inputSchema: {
+    type: "object" as const,
+    required: ["media_url", "platforms", "caption"],
+    properties: {
+      media_url: {
+        type: "string",
+        description: "Public URL of the approved image or video to publish.",
+      },
+      platforms: {
+        type: "array",
+        items: { type: "string", enum: ["instagram", "facebook"] },
+        description: "Target platforms: 'instagram', 'facebook', or both.",
+      },
+      caption: {
+        type: "string",
+        description: "Post caption (include hashtags here if desired).",
+      },
+    },
+  },
+  async execute({ media_url, platforms, caption }: PublishToMetaArgs): Promise<string> {
+    const result = await post<{
+      status?: string;
+      results?: Record<string, { success: boolean; error?: string }>;
+    }>("/v1/publish/schedule", {
+      video_url: media_url,
+      platforms,
+      caption,
+      publish_now: true,
+    });
+
+    const lines: string[] = ["📸 Published to Meta:"];
+    const results = result.results ?? {};
+    for (const [platform, res] of Object.entries(results)) {
+      lines.push(`  ${res.success ? "✅" : "❌"} ${platform}${res.error ? `: ${res.error}` : ""}`);
+    }
+    if (!Object.keys(results).length) {
+      lines.push("  (no platform results returned — check your connected accounts in Settings)");
+    }
+    return lines.join("\n");
+  },
+};