clipbait 1.5.0 → 1.7.0

package/README.md

@@ -1,34 +1,91 @@
 # clipbait
 
-Turn any video into short viral clips — and auto-clip live streams — from your terminal or an AI agent. Wraps the [Clipbait](https://clipbait.ai) API.
+Official CLI + MCP server for [Clipbait](https://clipbait.ai) — the AI video clipping tool for streamers and clippers.
+
+Let Claude (or any MCP-capable agent) turn long videos into viral vertical clips, check your credits, auto-clip live Twitch streams, and download finished clips to disk — on your Clipbait account. Also works as a plain terminal CLI.
+
+## Requires
+
+- **Node.js 18 or higher.**
+- **A paid Clipbait account.** Generate a key at [app.clipbait.ai/me](https://app.clipbait.ai/me) → **Developers / API**. Keys are prefixed `cbk_live_`.
+
+## Install
+
+### Fastest — one command (auto-configures Claude Code + Claude Desktop)
 
-## Fastest start — one command
 ```bash
 npx clipbait@latest
 ```
-It opens Clipbait so you can grab your key, then installs a **`/clipbait`** slash command and connects the Clipbait MCP server to Claude Code. Then just type in Claude:
+
+Opens Clipbait so you can copy your key, then installs a `/clipbait` slash command and wires the MCP server into Claude Code and Claude Desktop for you — no JSON to hand-write. Pass the key inline to skip the prompt: `npx clipbait@latest cbk_live_yourkey`. Restart Claude, then type `/clipbait <video url>`.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http clipbait https://app.clipbait.ai/api/mcp/cbk_live_your_key_here
 ```
-/clipbait https://youtube.com/watch?v=...
+
+### Cursor / Cline / Windsurf / manual
+
+Drop this into the client's MCP config file (runs the local stdio server):
+
+```json
+{
+  "mcpServers": {
+    "clipbait": {
+      "command": "npx",
+      "args": ["-y", "clipbait@latest", "mcp"],
+      "env": { "CLIPBAIT_API_KEY": "cbk_live_your_key_here" }
+    }
+  }
+}
 ```
 
-## Or use it straight from the terminal
+> **ChatGPT / claude.ai** take a remote URL instead of a local process — point them at `https://app.clipbait.ai/api/mcp/<your_api_key>` (nothing runs on your machine, nothing to update).
+
+## Tools
+
+Seven tools are available to any agent:
+
+| Tool | What it does |
+|---|---|
+| `generate_clips` | Start a clipping job (`videoUrl`, optional `aspectRatio` 9:16\|16:9, `maxClips` 1–20). Returns a job id. |
+| `get_job` | Check a job's status and get finished clip URLs (`jobId`). |
+| `list_recent_clips` | List your recent jobs and clip counts. |
+| `get_credits` | Show credits remaining and your plan. No inputs. |
+| `start_live_autoclip` | Auto-clip a **live** Twitch stream continuously (`channelUrl`, optional `cadenceMin`). Pro plan. |
+| `probe_video` | Get a video's duration before clipping (`url`). |
+| `download_clip` | Save a finished clip to your `~/Downloads/` folder and return the path (`jobId`, `clipIndex` 1-based). Max 500 MB. |
+
+## Terminal usage
+
 ```bash
-npx clipbait login <your_api_key>     # get it at clipbait.ai → Me → Developers / API
+npx clipbait login cbk_live_your_key
 npx clipbait generate "https://youtube.com/watch?v=..." --aspect 9:16 --max 9
-npx clipbait status <jobId>           # get finished clip URLs
+npx clipbait status <jobId>       # get finished clip URLs
+npx clipbait jobs                 # list recent jobs
+npx clipbait live "https://twitch.tv/somestreamer"
+npx clipbait mcp                  # run the stdio MCP server (used in configs above)
 ```
 
-## Commands
-| Command | Description |
-|---|---|
-| `clipbait` | One-command Claude Code setup (`/clipbait` + MCP) |
-| `clipbait login <apiKey>` | Save your API key (`~/.clipbait.json`) |
-| `clipbait generate <url> [--aspect 9:16] [--type talking_head] [--max 9]` | Generate clips |
-| `clipbait status <jobId>` | Check a job + get clip URLs |
-| `clipbait jobs` | List recent jobs |
-| `clipbait live <twitchUrl> [--cadence 7]` | Start live auto-clipping (Pro) |
-| `clipbait probe <url>` | Get a video's duration |
+Auth via the `CLIPBAIT_API_KEY` env var or `~/.clipbait.json`.
+
+## Security
+
+- **Never commit your `CLIPBAIT_API_KEY`.** Your agent's config file contains a secret — add it to `.gitignore`, or use a secrets manager (1Password CLI, direnv) instead of inline env vars.
+- If you leak your key, rotate it at [app.clipbait.ai/me](https://app.clipbait.ai/me) immediately — the old key stops working at once.
+- `download_clip` links are presigned and expire in ~1 hour. Save clips promptly.
+
+## Pricing
+
+Requires a **paid Clipbait account**. Clip generation spends credits (1 credit ≈ 1 minute of source video). See [clipbait.ai](https://clipbait.ai).
+
+## Links
+
+- Clipbait: https://clipbait.ai
+- API docs: https://app.clipbait.ai/docs
+- Get an API key: https://app.clipbait.ai/me
 
-Auth via `CLIPBAIT_API_KEY` env var or `~/.clipbait.json`. Requires Node 18+.
+## License
 
-Prefer MCP? Point your agent at `https://app.clipbait.ai/api/mcp/<your_api_key>`.
+MIT

package/index.js

@@ -114,9 +114,35 @@ Do this, conversationally and fast:
 5. Then offer follow-ups and act on them by calling the tools again: regenerate at a different aspect ratio, pull more clips, or probe another video with \`probe_video\`.
 `;
 
+// Claude Desktop config path per-OS.
+function desktopConfigPath() {
+  const home = os.homedir();
+  if (process.platform === "darwin") return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (process.platform === "win32") return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+}
+
+// Configure Claude Desktop (stdio) if it's installed. Desktop can't use the
+// remote http MCP, and the local stdio server is what enables download_clip.
+// Returns false (silently) when Claude Desktop isn't present.
+function writeDesktopConfig(key) {
+  const cfgPath = desktopConfigPath();
+  try {
+    if (!fs.existsSync(path.dirname(cfgPath))) return false; // Desktop not installed
+    let cfg = {};
+    try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch { /* new file */ }
+    cfg.mcpServers = cfg.mcpServers || {};
+    cfg.mcpServers.clipbait = { command: "npx", args: ["-y", "clipbait@latest", "mcp"], env: { CLIPBAIT_API_KEY: key } };
+    const tmp = cfgPath + ".clipbait.tmp";
+    fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+    fs.renameSync(tmp, cfgPath);
+    return true;
+  } catch { return false; }
+}
+
 // Interactive one-command setup. Grabs the key (from arg / saved / by opening
 // the browser and prompting), installs the /clipbait command, and connects the
-// MCP server to Claude Code.
+// MCP server to Claude Code and Claude Desktop.
 async function runSetup(providedKey) {
   let key = providedKey && providedKey.startsWith("cbk_") ? providedKey : loadKey();
 
@@ -163,12 +189,85 @@ async function runSetup(providedKey) {
     }
   }
 
+  // 3) Also configure Claude Desktop if installed (stdio server → download_clip).
+  if (writeDesktopConfig(key)) {
+    console.log("✓ Connected Clipbait to Claude Desktop (quit + reopen it to load)");
+  }
+
   console.log("\n🎬 Done! Restart Claude Code, then type:\n    /clipbait https://youtube.com/watch?v=…\n");
 }
 
+// Download a clip URL to ~/Downloads and return the saved path. Presigned
+// storage URLs need no auth; our own proxy URLs need the key — only send the
+// key to clipbait.ai hosts so we never leak it to third-party storage.
+async function downloadToFile(url, filename) {
+  const dir = path.join(os.homedir(), "Downloads");
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+  const dest = path.join(dir, filename);
+  const headers = /(^|\.)clipbait\.ai/i.test(new URL(url).host) ? { "X-API-Key": loadKey() } : {};
+  const res = await fetch(url, { headers });
+  if (!res.ok) throw new Error(`download failed: HTTP ${res.status}`);
+  const len = Number(res.headers.get("content-length") || 0);
+  if (len > 500 * 1024 * 1024) throw new Error("clip is larger than 500 MB");
+  fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+  return dest;
+}
+
+// Local stdio MCP server. Lets Claude Desktop, Cursor, Cline, Windsurf, etc.
+// drive Clipbait via `npx clipbait mcp`. Tools proxy the REST API; download_clip
+// runs locally so it can save to disk (a remote MCP can't). NEVER write to
+// stdout here — it's the MCP transport; diagnostics go to stderr only.
+async function runMcpServer() {
+  if (!loadKey()) { console.error("No API key. Set CLIPBAIT_API_KEY or run: npx clipbait <cbk_live_...>"); process.exit(1); }
+  const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+  const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+  const { z } = require("zod");
+  const server = new McpServer({ name: "clipbait", version: require("./package.json").version });
+  const ok = (t) => ({ content: [{ type: "text", text: t }] });
+  const fail = (e) => ({ content: [{ type: "text", text: "Error: " + (e.message || String(e)) }], isError: true });
+
+  server.tool("generate_clips", "Generate short vertical viral clips from a long video (YouTube, Twitch VOD, Rumble, Ganjing). Returns a job id; poll get_job.",
+    { videoUrl: z.string(), aspectRatio: z.enum(["9:16", "16:9"]).optional(), maxClips: z.number().int().min(1).max(20).optional() },
+    async (a) => { try { const d = await api("POST", "/clips/generate", { videoUrl: a.videoUrl, aspectRatio: a.aspectRatio || "9:16", maxClips: a.maxClips || 9 }); return ok(`Clip job started: ${d.jobId}${d.duplicate ? " (duplicate of a recent job — no extra credits)" : ""}. Poll get_job("${d.jobId}").`); } catch (e) { return fail(e); } });
+
+  server.tool("get_job", "Check a clip job's status and get finished clip URLs.", { jobId: z.string() },
+    async (a) => { try { const d = await api("GET", "/clips/status/" + a.jobId); const clips = (d.clips || []).map((x, i) => `#${i + 1} ${x.hook || ""} — ${x.url || "(rendering)"}`).join("\n"); return ok(`Status: ${d.status} (${d.progress ?? 0}%)\n${clips || "No clips yet."}`); } catch (e) { return fail(e); } });
+
+  server.tool("list_recent_clips", "List your recent clip jobs and how many clips each produced.", {},
+    async () => { try { const d = await api("GET", "/clips/jobs"); const jobs = (d.jobs || d || []).slice(0, 10).map((j) => `${j._id} · ${j.status} · ${(j.clips || []).length} clips · ${j.videoTitle || j.streamerName || ""}`).join("\n"); return ok(jobs || "No jobs yet."); } catch (e) { return fail(e); } });
+
+  server.tool("get_credits", "Check remaining Clipbait credits and plan before starting a job (1 credit ≈ 1 minute of source video).", {},
+    async () => { try { const d = await api("GET", "/clips/credits"); return ok(`Plan: ${d.plan}. Credits remaining: ${d.credits_remaining}${d.credits_total ? ` of ${d.credits_total}` : ""}.`); } catch (e) { return fail(e); } });
+
+  server.tool("start_live_autoclip", "Start continuous auto-clipping of a LIVE Twitch stream (Pro). Clips are generated automatically as viral moments happen.",
+    { channelUrl: z.string(), cadenceMin: z.number().int().optional() },
+    async (a) => { try { const d = await api("POST", "/live/start", { videoUrl: a.channelUrl, cadenceMin: a.cadenceMin || 7 }); return ok(`Live auto-clipping started (${d.liveSessionId || d.session?._id || "?"}).`); } catch (e) { return fail(e); } });
+
+  server.tool("probe_video", "Get a video's duration before clipping.", { url: z.string() },
+    async (a) => { try { const d = await api("POST", "/clips/probe-url", { url: a.url }); return ok(d.durationSeconds != null ? `Duration: ${d.durationSeconds}s (~${Math.round(d.durationSeconds / 60)} min)` : "Duration unknown for this platform."); } catch (e) { return fail(e); } });
+
+  server.tool("download_clip", "Save a finished clip to the user's ~/Downloads folder and return the file path. Call after get_job shows the job is complete.",
+    { jobId: z.string(), clipIndex: z.number().int().min(1).optional().describe("1-based, default 1") },
+    async (a) => {
+      try {
+        const d = await api("GET", "/clips/status/" + a.jobId);
+        const clips = d.clips || [];
+        if (!clips.length) return fail(new Error("No clips are ready for this job yet."));
+        const idx = (a.clipIndex || 1) - 1;
+        const clip = clips[idx];
+        if (!clip || !clip.url) return fail(new Error(`Clip #${a.clipIndex || 1} isn't available.`));
+        const p = await downloadToFile(clip.url, `clipbait-${a.jobId}-${idx + 1}.mp4`);
+        return ok(`Saved to ${p}`);
+      } catch (e) { return fail(e); }
+    });
+
+  await server.connect(new StdioServerTransport());
+}
+
 const HELP = `clipbait — AI clip generation
 
   npx clipbait@latest                                 set up Claude Code (recommended)
+  clipbait mcp                                         run the stdio MCP server (for Claude Desktop/Cursor/Cline)
   clipbait login <apiKey>                             just save your API key
   clipbait generate <url> [--aspect 9:16] [--type talking_head] [--max 9]
   clipbait status <jobId>                             check a job + get clip URLs
@@ -193,6 +292,7 @@ Auth: CLIPBAIT_API_KEY env var or ~/.clipbait.json (via 'clipbait login').`;
       console.log("✓ Saved API key to " + CFG);
       return;
     }
+    if (cmd === "mcp") { await runMcpServer(); return; } // stdio MCP server for local clients
     if (cmd === "help" || cmd === "--help" || cmd === "-h") { console.log(HELP); return; }
 
     if (!loadKey()) {

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "clipbait",
-  "version": "1.5.0",
-  "description": "Clipbait CLI — turn any video into viral clips, and auto-clip live streams, from your terminal or AI agent.",
+  "version": "1.7.0",
+  "description": "Clipbait CLI + MCP server — turn any video into viral clips, and auto-clip live streams, from your terminal or any AI agent.",
   "bin": { "clipbait": "index.js" },
   "type": "commonjs",
   "engines": { "node": ">=18" },
-  "keywords": ["clipbait", "clips", "video", "ai", "agent", "cli", "twitch", "shorts"],
+  "keywords": ["clipbait", "clips", "video", "ai", "agent", "mcp", "cli", "twitch", "shorts"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
   "license": "MIT"
 }