clipai-mcp 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# ClipAI MCP server
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the ClipAI clipping
+pipeline as agent-callable tools, so Claude (or any MCP client) can run the whole
+loop from a message: **import a YouTube video, list the AI-detected clips, render
+one, and schedule it to a connected account.**
+
+This is ClipAI's answer to agent-triggered clipping: the same generate -> distribute
+loop the app does, now drivable by an agent.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `import_youtube` | Import a YouTube URL and start AI clip detection (returns video_id, job_id). |
+| `list_videos` | List the org's videos with status and clip counts. |
+| `list_clips` | List clips (optionally for one video): id, title, status, score, start/end. |
+| `get_clip` | Fetch one clip (poll its status after rendering). |
+| `render_clip` | Render a clip to a 9:16 short with burned captions (returns jobId). |
+| `list_social_accounts` | List connected social accounts to schedule to. |
+| `schedule_clip` | Schedule a rendered clip (or `publish_now`) to an account. |
+
+A typical agent flow: `import_youtube` -> poll `list_clips(video_id)` until clips
+appear -> `render_clip` -> poll `get_clip` until `status: "READY"` ->
+`list_social_accounts` -> `schedule_clip`.
+
+## Auth
+
+The server authenticates with a per-org **API key** (a revocable key you generate in
+ClipAI under **Settings -> API keys**), sent as `Authorization: Bearer <key>`. Set:
+
+- `CLIPAI_API_KEY` - the key (starts with `clip_`)
+- `CLIPAI_BASE_URL` - optional, defaults to `https://clipai.online`
+
+The key carries the org owner's authority and can be revoked at any time from
+Settings. The same key works for any programmatic API call, not just this server.
+
+## Build
+
+```bash
+cd apps/mcp
+pnpm install     # from repo root (workspace) or here
+pnpm build       # tsc -> dist/
+```
+
+## Configure in Claude Desktop / Claude Code
+
+Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "clipai": {
+      "command": "node",
+      "args": ["/absolute/path/to/clipping-app/apps/mcp/dist/index.js"],
+      "env": {
+        "CLIPAI_API_KEY": "clip_xxxxxxxxxxxxxxxxxxxx",
+        "CLIPAI_BASE_URL": "https://clipai.online"
+      }
+    }
+  }
+}
+```
+
+Then ask: *"Clip this YouTube video to 9:16 with a hook, then schedule the best one
+to my TikTok."* The agent will call the tools above in sequence.

package/dist/client.js

@@ -0,0 +1,55 @@
+export class ClipAIClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    url(path) {
+        return new URL(path, this.cfg.baseUrl).toString();
+    }
+    async request(method, path, jsonBody) {
+        const res = await fetch(this.url(path), {
+            method,
+            headers: {
+                authorization: `Bearer ${this.cfg.apiKey}`,
+                ...(jsonBody !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            body: jsonBody !== undefined ? JSON.stringify(jsonBody) : undefined,
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok) {
+            const msg = data && typeof data === "object" && "error" in data
+                ? String(data.error)
+                : `HTTP ${res.status}`;
+            throw new Error(`${method} ${path} failed: ${msg}`);
+        }
+        return data;
+    }
+    importYouTube(url, clipOptions) {
+        return this.request("POST", "/api/import", { url, ...(clipOptions ? { clip_options: clipOptions } : {}) });
+    }
+    listVideos() {
+        return this.request("GET", "/api/videos");
+    }
+    listClips(videoId) {
+        return this.request("GET", `/api/clips${videoId ? `?videoId=${encodeURIComponent(videoId)}` : ""}`);
+    }
+    getClip(clipId) {
+        return this.request("GET", `/api/clips/${encodeURIComponent(clipId)}`);
+    }
+    renderClip(clipId, opts) {
+        return this.request("POST", `/api/clips/${encodeURIComponent(clipId)}/render`, opts);
+    }
+    listSocialAccounts() {
+        return this.request("GET", "/api/social/accounts");
+    }
+    scheduleClip(payload) {
+        return this.request("POST", "/api/schedules", payload);
+    }
+}

package/dist/index.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * ClipAI MCP server. Exposes the ClipAI clipping pipeline as agent-callable tools
+ * so Claude (or any MCP client) can run the whole loop from a message:
+ * import a YouTube video -> list the AI-detected clips -> render one -> schedule it.
+ *
+ * Auth is the org owner's email/password (env), used via the existing session API.
+ * Configure in an MCP client (e.g. Claude Desktop) - see README.md.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { ClipAIClient } from "./client.js";
+const baseUrl = process.env.CLIPAI_BASE_URL ?? "https://clipai.online";
+const apiKey = process.env.CLIPAI_API_KEY ?? "";
+const client = new ClipAIClient({ baseUrl, apiKey });
+const tools = [
+    {
+        name: "import_youtube",
+        description: "Import a YouTube video into ClipAI and start AI clip detection. Returns a video_id and job_id. " +
+            "Detection runs asynchronously; poll list_clips(video_id) until clips appear (usually under a few minutes).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "A YouTube URL (youtube.com/watch, youtu.be, or /shorts/)." },
+                goal: {
+                    type: "string",
+                    enum: ["viral", "highlights", "insights"],
+                    description: "Optional steering for what kind of clips to favor.",
+                },
+                max_clips: { type: "number", description: "Optional cap on how many clips to detect." },
+            },
+            required: ["url"],
+        },
+    },
+    {
+        name: "list_videos",
+        description: "List the org's videos (most recent first) with status and clip counts.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "list_clips",
+        description: "List clips, optionally filtered to one video_id. Each clip has id, title, status, score (0-1 virality), " +
+            "startTime, endTime. A clip must reach status READY (via render_clip) before it can be scheduled.",
+        inputSchema: { type: "object", properties: { video_id: { type: "string" } } },
+    },
+    {
+        name: "get_clip",
+        description: "Get one clip by id (use to poll status after render_clip).",
+        inputSchema: { type: "object", properties: { clip_id: { type: "string" } }, required: ["clip_id"] },
+    },
+    {
+        name: "render_clip",
+        description: "Render a clip into a vertical short: captions burned in, auto-reframed to 9:16. Returns a jobId; " +
+            "poll get_clip until status is READY. Rendering is required before scheduling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                clip_id: { type: "string" },
+                platform: {
+                    type: "string",
+                    enum: ["tiktok", "instagram", "youtube", "linkedin", "x", "threads", "bluesky"],
+                    description: "Target platform (defaults to tiktok).",
+                },
+                caption_language: { type: "string", description: "Optional: translate captions to this language." },
+                dub_language: { type: "string", description: "Optional: dub the audio into this language (ElevenLabs)." },
+                hook_text: { type: "string", description: "Optional headline burned over the first few seconds." },
+                reframe_focus: { type: "string", enum: ["center", "left", "right"] },
+                remove_silence: { type: "boolean" },
+                layout: { type: "string", enum: ["fill", "split"] },
+            },
+            required: ["clip_id"],
+        },
+    },
+    {
+        name: "list_social_accounts",
+        description: "List connected social accounts (id, platform, accountName) available to schedule to.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "schedule_clip",
+        description: "Schedule a rendered (READY) clip to a connected social account. Pass publish_now=true to post immediately, " +
+            "or scheduled_at (ISO 8601) for a future time.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                clip_id: { type: "string" },
+                social_account_id: { type: "string" },
+                caption: { type: "string" },
+                hashtags: { type: "array", items: { type: "string" } },
+                scheduled_at: { type: "string", description: "ISO 8601 datetime; ignored when publish_now is true." },
+                publish_now: { type: "boolean" },
+            },
+            required: ["clip_id", "social_account_id", "caption"],
+        },
+    },
+];
+const server = new Server({ name: "clipai", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = (req.params.arguments ?? {});
+    try {
+        let result;
+        switch (name) {
+            case "import_youtube": {
+                const clipOptions = {};
+                if (args.goal)
+                    clipOptions.goal = args.goal;
+                if (typeof args.max_clips === "number")
+                    clipOptions.max_clips = args.max_clips;
+                result = await client.importYouTube(String(args.url), Object.keys(clipOptions).length ? clipOptions : undefined);
+                break;
+            }
+            case "list_videos":
+                result = await client.listVideos();
+                break;
+            case "list_clips":
+                result = await client.listClips(args.video_id ? String(args.video_id) : undefined);
+                break;
+            case "get_clip":
+                result = await client.getClip(String(args.clip_id));
+                break;
+            case "render_clip": {
+                const opts = {};
+                if (args.platform)
+                    opts.platform = args.platform;
+                if (args.caption_language)
+                    opts.captionLanguage = args.caption_language;
+                if (args.dub_language)
+                    opts.dubLanguage = args.dub_language;
+                if (args.hook_text)
+                    opts.hookText = args.hook_text;
+                if (args.reframe_focus)
+                    opts.reframeFocus = args.reframe_focus;
+                if (typeof args.remove_silence === "boolean")
+                    opts.removeSilence = args.remove_silence;
+                if (args.layout)
+                    opts.layout = args.layout;
+                result = await client.renderClip(String(args.clip_id), opts);
+                break;
+            }
+            case "list_social_accounts":
+                result = await client.listSocialAccounts();
+                break;
+            case "schedule_clip": {
+                const payload = {
+                    clipId: String(args.clip_id),
+                    socialAccountId: String(args.social_account_id),
+                    caption: String(args.caption),
+                    hashtags: Array.isArray(args.hashtags) ? args.hashtags : [],
+                    // The schedule API requires a datetime even for publish_now (it overrides
+                    // it to "now"), so always send a valid ISO string.
+                    scheduledAt: args.scheduled_at ? String(args.scheduled_at) : new Date().toISOString(),
+                    ...(args.publish_now ? { publishNow: true } : {}),
+                };
+                result = await client.scheduleClip(payload);
+                break;
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+    }
+});
+async function main() {
+    if (!apiKey) {
+        console.error("ClipAI MCP: set CLIPAI_API_KEY (generate one in ClipAI Settings -> API keys).");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`ClipAI MCP server running against ${baseUrl}`);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "clipai-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server exposing the ClipAI clipping pipeline as agent-callable tools (import, clip, render, schedule).",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "clipai",
+    "video",
+    "clips",
+    "ai",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/isi1314/clipping-app.git",
+    "directory": "apps/mcp"
+  },
+  "bin": {
+    "clipai-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}