katto-mcp 0.5.4 → 0.5.6

package/QUICKSTART.md

@@ -0,0 +1,35 @@
+# Katto — 60-second quickstart
+
+Turn a long video into captioned 9:16 short clips from your assistant, your terminal, or
+your code. **One quota** (Creator: 25 videos/mo, ≤90 min each · Free: 2/mo), shared across
+all three. Create a key at https://katto.tech/dashboard/api-keys (keys can be read-only).
+
+## MCP — in Claude, Cursor, ChatGPT
+Hosted, zero-install, OAuth 2.1:
+```json
+{ "mcpServers": { "katto": { "url": "https://mcp.katto.tech/mcp" } } }
+```
+Then just ask: *"Clip the best 6 moments from <url> and caption them."*
+Prefer local? `npx -y katto-mcp` with `KATTO_API_KEY=sk_live_...`.
+
+## CLI — in your terminal or a cron
+```bash
+npm i -g katto-cli
+katto login                        # or set KATTO_API_KEY=sk_live_...
+katto clip <url> --clips 6 --wait --json | jq '.clips[].url'
+```
+
+## REST API — in your product
+```bash
+curl -X POST https://katto.tech/api/v1/jobs \
+  -H "Authorization: Bearer sk_live_..." \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://youtube.com/watch?v=..."}'
+# → { "job_id": "..." }
+# then poll GET /v1/jobs/{id}, or pass a "webhook_url" for a signed completion callback.
+```
+
+What comes back: finished clips (MP4 + SRT captions + a title and a 0–100 score), 9:16,
+word-timed captions, reframed. Re-render the layout/caption style or dub into 8 languages
+for free (no quota). Full reference: https://katto.tech/docs/api

package/README.md

@@ -85,6 +85,7 @@ Account and reference:
 - **`katto_get_webhook_secret()`** your webhook signing secret and how to verify signed callbacks (returns a secret — treat it like a credential).
 - **`katto_list_sources()`** the video platforms Katto can clip from, with an example url each.
 - **`katto_list_clip_lengths()`** the valid target clip-length buckets.
+- **`katto_list_caption_styles()`** the caption-style presets you can pass as `caption_style` when creating a job or re-rendering a clip.
 
 Jobs draw from your Katto plan's monthly video quota (25 on Creator, 2 on Free), videos up to 90 minutes. The underlying REST API also supports `Idempotency-Key` safe retries, read-only scoped keys, and signed HMAC webhooks. See the [docs](https://katto.tech/docs/api).
 

package/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: katto-clip
+description: Turn a long video (a YouTube / Twitch / Vimeo / Rumble / Zoom / Dailymotion link, or an upload) into scored, captioned, 9:16 short clips using Katto's cloud pipeline. Use when the user wants to clip, repurpose, or make shorts from long-form video, or to dub / re-render an existing clip.
+---
+
+# Katto clipping skill
+
+Katto runs the whole pipeline in its cloud — download → transcript → moment scoring →
+cut → captions → reframe → optional dub → publish. You trigger it; nothing renders on
+the local machine.
+
+## Connect
+- **Hosted MCP (recommended, zero-install):** point the client at `https://mcp.katto.tech/mcp`
+  (OAuth 2.1 + Dynamic Client Registration; no key on disk).
+- **Local:** `npx -y katto-mcp` with `KATTO_API_KEY=sk_live_...` (Cursor, CI, cron).
+- Tools are prefixed `katto_`. `tools/list` works without a key; every tool **call** needs a key.
+
+## Core flow
+1. `katto_create_clip_job({ url, config? })` → returns a `job_id`. Spends **1 video** from the
+   monthly quota. Pass an idempotency key so a retry never double-spends.
+2. Poll `katto_get_job({ id })` until `status` is `"completed"`.
+3. `katto_get_clips({ id })` → finished clips (MP4 url + SRT + title + score 0–100).
+
+## Editing — never counts against quota
+- `katto_rerender_clip({ id, clip_index, layout_mode?, caption_style? })`, then `katto_get_rerender(...)`.
+- `katto_dub_clip({ id, clip_index, languages })` → dub into any of **8 languages**: en, es, fr, it, pt, hi, ja, zh.
+
+## Reference / account
+- `katto_get_usage`, `katto_get_account` — remaining quota, plan, this key's scopes.
+- `katto_list_sources` (accepted platforms), `katto_list_clip_lengths` (valid length buckets).
+- `katto_get_transcript` (timestamped), `katto_get_brand_kit`, `katto_get_webhook_secret` (treat as a credential).
+
+## Rules of the road
+- **One quota**, shared with the app / API / CLI: Creator = 25 videos/month, ≤90 min each; Free = 2/month.
+  Re-renders and dubs are free.
+- Captions: **99 languages** (word-timed in 41, sentence-level in the rest). Dubbing: **8**. Publish: **7 platforms**.
+- **Don't invent timings.** The only measured figure is ~5 minutes for 8 clips on a 20-minute video;
+  longer sources take longer. Say that, not a number you'd like.
+
+## Example
+User: *"Clip the best 6 moments from this podcast, then dub clip 2 in Spanish."*
+→ `katto_create_clip_job(url, { clips: 6 })` → poll `katto_get_job` → `katto_get_clips`
+→ `katto_dub_clip(id, 2, ["es"])` → `katto_get_rerender`.
+
+Full reference: https://katto.tech/docs/api · OpenAPI: https://katto.tech/openapi.json

package/index.mjs

@@ -153,7 +153,14 @@ const TOOLS = [
     name: "katto_list_clip_lengths",
     description:
       "List the valid values for the optional config.clipLength on katto_create_clip_job (target clip " +
-      "duration buckets).",
+      "duration buckets). Note: clipLength is fixed at job creation and cannot be changed by re-render.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "katto_list_caption_styles",
+    description:
+      "List the valid caption_style preset names for katto_rerender_clip (e.g. 'hormozi' for bold " +
+      "word-by-word highlight). Call this before re-rendering so you pass a real preset, not a guess.",
     inputSchema: { type: "object", properties: {} },
   },
   {
@@ -170,7 +177,12 @@ const TOOLS = [
           type: "string",
           enum: ["face_tracking", "wide", "split_screen", "stacked", "passthrough", "grid_3", "grid_4"],
         },
-        caption_style: { type: "string", description: "A caption style preset name." },
+        caption_style: {
+          type: "string",
+          // Keep in sync with CAPTION_STYLES below (katto_list_caption_styles).
+          enum: ["default", "hormozi", "yellowPop", "redAlert", "skyline", "bubblegum", "aqua", "violet", "headline", "centerPop", "topLime", "impactMax", "bebasGold", "robotoBold", "montserratClean", "poppinsSoft", "robotoDoc", "broadcast", "wideClean", "mono", "bebasWhite", "rainbow", "multicolor"],
+          description: "A caption style preset name. See katto_list_caption_styles for the labels.",
+        },
       },
       required: ["id", "clip_index"],
     },
@@ -240,6 +252,7 @@ const ANNOTATIONS = {
   katto_get_account: { title: "Get account", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   katto_list_sources: { title: "List supported sources", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   katto_list_clip_lengths: { title: "List clip-length options", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  katto_list_caption_styles: { title: "List caption styles", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   katto_rerender_clip: { title: "Re-render a clip", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
   katto_dub_clip: { title: "Dub a clip", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
   katto_get_rerender: { title: "Poll a re-render", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -251,16 +264,17 @@ const ANNOTATIONS = {
 // on tools/list — identical across all sources, enriching the terser inline text.
 const DESCRIPTIONS = {
   katto_create_clip_job: "Submit a long video (YouTube, Twitch, Vimeo, Rumble, Zoom, Dailymotion) for clipping. Consumes 1 video from your monthly quota — check katto_get_usage first. Clips are produced asynchronously; returns a job id, then poll katto_get_job until status is 'completed'. Fails if the URL is unsupported or the video is over 90 minutes.",
-  katto_get_job: "Read-only. Get the status, progress and clips of a job by id. When status is 'completed', 'clips' holds the finished 9:16 MP4 urls and caption (SRT) urls; while processing, clips is empty. Returns 404 for an unknown id.",
+  katto_get_job: "Read-only. Get the status, progress and clips of a job by id. Clips come ranked by virality score (0-100, highest first; ties broken by clip_index). Each clip is { url, captions_url, title, score, clip_index, hd }: when status is 'completed' every url is a finished, downloadable clip; hd is true once the 1080p high-quality render is ready. hd=false does NOT mean broken — the url already works, the 1080p is just still rendering in the background (and stays the standard render on the free plan). The job-level hd_ready flag turns true once every clip is hd, i.e. the URLs are final and won't be swapped again (status='completed' fires earlier). Returns 404 for an unknown id.",
   katto_list_jobs: "Read-only. List your recent jobs, newest first. Paginate with 'cursor' (pass the previous next_cursor); optional 'status' filter. Returns { jobs: [{id, status, source, created_at, completed_at}], next_cursor }.",
-  katto_get_clips: "Read-only convenience: just the finished clips of a job (9:16 MP4 urls + caption SRT urls + title + virality score). Returns an empty list while the job is still processing.",
+  katto_get_clips: "Read-only convenience: the clips of a job as { url, captions_url, title, score, clip_index, hd }, ranked by score (highest first). hd=true means the 1080p render is ready; hd=false means the url is the standard render (HD still finishing, or the free plan). Empty until the first clip is ready.",
   katto_get_usage: "Read-only. Your current plan and monthly video quota: { plan, videos_used, videos_limit, videos_remaining }. Call before katto_create_clip_job to confirm remaining quota.",
   katto_get_transcript: "Read-only. The transcript of a completed job as timestamped segments [{ start, end, text }]. Returns 404 while the job is still processing.",
   katto_cancel_job: "Cancel a still-running job (queued/processing) and refund the video back to your monthly quota. Safe to retry (idempotent). Returns an error if the job already finished, failed, or was cancelled.",
   katto_get_account: "Read-only. The account behind this key: plan, this key's scopes (read/write), and monthly quota { videos_used, videos_limit, videos_remaining }.",
   katto_list_sources: "Read-only. The video platforms Katto can clip from, each with an example URL. Use it to confirm a URL is supported before calling katto_create_clip_job.",
-  katto_list_clip_lengths: "Read-only. The valid values for the optional config.clipLength on katto_create_clip_job (target clip-duration buckets).",
-  katto_rerender_clip: "Re-render one already-finished clip with a new reframe layout and/or caption style. Free — does NOT use video quota. Each call starts a new render (not idempotent); the original clip is kept. Returns a rerender_id; poll katto_get_rerender for the new clip url.",
+  katto_list_clip_lengths: "Read-only. The valid values for the optional config.clipLength on katto_create_clip_job (target clip-duration buckets). Note: clipLength is fixed at creation and cannot be changed by re-render.",
+  katto_list_caption_styles: "Read-only. The valid caption_style preset names for katto_rerender_clip (id + label), e.g. 'hormozi' for bold word-by-word highlight. Call this before re-rendering so you pass a real preset instead of guessing.",
+  katto_rerender_clip: "Re-render one already-finished clip with a new reframe layout and/or caption style (get valid caption_style values from katto_list_caption_styles). Free — does NOT use video quota. Each call starts a new render (not idempotent); the original clip is kept. Returns a rerender_id; poll katto_get_rerender for the new clip url.",
   katto_dub_clip: "Re-render one finished clip dubbed into one or more of 8 languages (en, es, fr, it, pt, hi, ja, zh). Free — does NOT use video quota. Each call starts a new render (not idempotent). Returns a rerender_id; poll katto_get_rerender for the result.",
   katto_get_rerender: "Read-only. Poll a re-render started by katto_rerender_clip or katto_dub_clip. Returns { status, clip_url, captions_url } — clip_url is null until status is 'completed'.",
   katto_get_brand_kit: "Read-only. Your saved brand kits (colors, caption font and position, default layout, watermark url).",
@@ -289,8 +303,35 @@ const CLIP_LENGTHS = [
   { value: '60_90', label: '60 to 90 seconds' },
   { value: '90_180', label: '90 to 180 seconds' },
 ];
+// Valid values for caption_style on katto_rerender_clip. Mirrors the editor's
+// named presets. Keep in sync with mcp-worker/src/index.js CAPTION_STYLES.
+const CAPTION_STYLES = [
+  { value: 'default', label: 'Default' },
+  { value: 'hormozi', label: 'Hormozi (bold word-by-word highlight)' },
+  { value: 'yellowPop', label: 'Yellow Pop' },
+  { value: 'redAlert', label: 'Red Alert' },
+  { value: 'skyline', label: 'Skyline' },
+  { value: 'bubblegum', label: 'Bubblegum' },
+  { value: 'aqua', label: 'Aqua' },
+  { value: 'violet', label: 'Violet' },
+  { value: 'headline', label: 'Headline' },
+  { value: 'centerPop', label: 'Center Pop' },
+  { value: 'topLime', label: 'Top Lime' },
+  { value: 'impactMax', label: 'Impact Max' },
+  { value: 'bebasGold', label: 'Bebas Gold' },
+  { value: 'robotoBold', label: 'Roboto Bold' },
+  { value: 'montserratClean', label: 'Montserrat' },
+  { value: 'poppinsSoft', label: 'Poppins' },
+  { value: 'robotoDoc', label: 'Roboto Doc' },
+  { value: 'broadcast', label: 'Broadcast' },
+  { value: 'wideClean', label: 'Wide Clean' },
+  { value: 'mono', label: 'Mono' },
+  { value: 'bebasWhite', label: 'Bebas' },
+  { value: 'rainbow', label: 'Rainbow (per-word colour cycle)' },
+  { value: 'multicolor', label: 'Multicolor' },
+];
 
-const server = new Server({ name: "katto", version: "0.5.4" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "katto", version: "0.5.5" }, { capabilities: { tools: {} } });
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS_LISTED }));
 
@@ -327,6 +368,8 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       data = { sources: SOURCES, note: "You can also clip a local file via the REST API (POST /v1/uploads)." };
     } else if (name === "katto_list_clip_lengths") {
       data = { clip_lengths: CLIP_LENGTHS };
+    } else if (name === "katto_list_caption_styles") {
+      data = { caption_styles: CAPTION_STYLES };
     } else if (name === "katto_rerender_clip") {
       const b = {};
       if (args.layout_mode) b.layout_mode = args.layout_mode;

package/package.json

@@ -1,43 +1,45 @@
-{
-  "name": "katto-mcp",
-  "version": "0.5.4",
-  "mcpName": "io.github.miracleweasel/katto-mcp",
-  "description": "AI video clipping MCP server: turn long videos, podcasts and Twitch VODs into scored, captioned 9:16 shorts from Claude, Cursor, ChatGPT and any MCP client.",
-  "type": "module",
-  "bin": {
-    "katto-mcp": "index.mjs"
-  },
-  "files": [
-    "index.mjs",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "katto",
-    "video",
-    "clips",
-    "shorts",
-    "ai",
-    "ai-video-clipper",
-    "video-to-shorts",
-    "youtube-to-shorts",
-    "podcast-clips",
-    "ai-captions",
-    "ai-video-editor",
-    "repurpose-video",
-    "video-dubbing"
-  ],
-  "homepage": "https://katto.tech/docs/api",
-  "repository": { "type": "git", "url": "git+https://github.com/miracleweasel/katto-mcp.git" },
-  "bugs": { "url": "https://katto.tech/contact" },
-  "author": "Katto (https://katto.tech)",
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
-  }
-}
+{
+  "name": "katto-mcp",
+  "version": "0.5.6",
+  "mcpName": "io.github.miracleweasel/katto-mcp",
+  "description": "AI video clipping MCP server: turn long videos, podcasts and Twitch VODs into scored, captioned 9:16 shorts from Claude, Cursor, ChatGPT and any MCP client.",
+  "type": "module",
+  "bin": {
+    "katto-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "LICENSE",
+    "SKILL.md",
+    "QUICKSTART.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "katto",
+    "video",
+    "clips",
+    "shorts",
+    "ai",
+    "ai-video-clipper",
+    "video-to-shorts",
+    "youtube-to-shorts",
+    "podcast-clips",
+    "ai-captions",
+    "ai-video-editor",
+    "repurpose-video",
+    "video-dubbing"
+  ],
+  "homepage": "https://katto.tech/docs/api",
+  "repository": { "type": "git", "url": "git+https://github.com/miracleweasel/katto-mcp.git" },
+  "bugs": { "url": "https://katto.tech/contact" },
+  "author": "Katto (https://katto.tech)",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}