katto-mcp 0.5.3 → 0.5.5

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

@@ -1,5 +1,10 @@
 # katto-mcp
 
+[![npm version](https://img.shields.io/npm/v/katto-mcp.svg)](https://www.npmjs.com/package/katto-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/katto-mcp.svg)](https://www.npmjs.com/package/katto-mcp)
+[![license](https://img.shields.io/npm/l/katto-mcp.svg)](./LICENSE)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.miracleweasel%2Fkatto--mcp-blue)](https://registry.modelcontextprotocol.io)
+
 **The AI video clipping MCP server.** Turn long videos into scored, captioned, vertical 9:16 short clips from any MCP client (Claude, Cursor, Claude Code, ChatGPT, VS Code, and other conformant clients). Drop in a YouTube link, a podcast, or a Twitch VOD and get publish-ready shorts back through natural conversation.
 
 Powered by [Katto](https://katto.tech), an AI video clipper that turns long-form video (podcasts, interviews, streams, webinars) into short-form clips for TikTok, Reels and YouTube Shorts. Katto is a flat-priced, no-credits alternative to tools like OpusClip: one 25-video quota covers videos up to 90 minutes each, with the API and MCP included on every paid plan (not gated behind an enterprise tier).
@@ -10,7 +15,7 @@ Ask your agent something like *"clip the best moments from this podcast and refr
 
 - find the strongest 30 to 90 second moments in a long video and score each clip 0 to 100 on Hook, Flow, Value and Trend,
 - reframe to vertical 9:16 with face tracking, split-screen for two speakers, and stacked layouts for gaming,
-- burn word-by-word animated captions (99 languages) and optionally dub into 8 languages,
+- burn animated captions (auto-captioned in 99 languages via Whisper large-v3; word-by-word timing in 41 of them, sentence-level in the rest) and optionally dub into 8 languages,
 - and hand back publish-ready MP4 files plus SRT caption urls.
 
 Typical uses: repurpose a YouTube video into shorts, turn a podcast episode into clips, cut highlights from a Twitch VOD, or convert a long interview into vertical social posts.
@@ -43,7 +48,22 @@ For Cursor, CI and scripts. Create an API key at **[katto.tech/dashboard/api-key
 
 The hosted endpoint above also accepts `Authorization: Bearer sk_live_...` directly for key-based clients.
 
-## Tools (15)
+## Install per client
+
+**Claude Code** (hosted, OAuth):
+```bash
+claude mcp add --transport http katto https://mcp.katto.tech/mcp
+```
+
+**Claude Desktop** — Settings → Connectors → *Add custom connector* → `https://mcp.katto.tech/mcp`, then sign in. (Or add the `npx` block above to `claude_desktop_config.json`.)
+
+**Cursor** — Settings → MCP → *Add* → paste the `npx` JSON block above (uses `KATTO_API_KEY`).
+
+**VS Code** (MCP extension) — add the same `npx` block to your MCP settings, or point it at the hosted URL if your client supports remote OAuth servers.
+
+**ChatGPT** (Developer mode / connectors) — add a custom connector with URL `https://mcp.katto.tech/mcp`.
+
+## Tools
 
 Clipping:
 - **`katto_create_clip_job(url, config?)`** clip a long video (YouTube, Twitch, Vimeo, Rumble, Zoom, Dailymotion). Returns a job id.
@@ -62,7 +82,7 @@ Account and reference:
 - **`katto_get_usage()`** your plan and remaining monthly video quota.
 - **`katto_get_account()`** the connected account, this key's scopes, and quota.
 - **`katto_get_brand_kit()`** your saved brand kits (colors, caption font, layout, watermark).
-- **`katto_get_webhook_secret()`** your webhook signing secret and how to verify signed callbacks.
+- **`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.
 
@@ -77,6 +97,12 @@ Jobs draw from your Katto plan's monthly video quota (25 on Creator, 2 on Free),
 
 Full docs: **[katto.tech/docs/api](https://katto.tech/docs/api)**
 
+## Security & data
+
+- **Hosted auth is OAuth 2.1** — the API key is never written to your disk, and you can revoke a connected client anytime from your Katto account settings.
+- **Local auth uses a scoped `sk_live_` key** you create yourself; keys can be read-only, and the npx server only sends it to `KATTO_API_URL` (default `katto.tech`) over HTTPS.
+- `katto_get_webhook_secret` returns a signing secret — handle it like any credential; it is only needed to verify inbound webhook signatures.
+
 ## Also listed on
 
 - npm: [katto-mcp](https://www.npmjs.com/package/katto-mcp)
@@ -96,4 +122,6 @@ Example prompts:
 2. "Check the status of my last clipping job and give me the download links for the finished clips."
 3. "Take clip 2 from that job, dub it into Spanish and re-render it with the Bold caption style."
 
-MIT
+## License
+
+MIT — see [LICENSE](./LICENSE).

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

@@ -15,12 +15,19 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 const API_URL = (process.env.KATTO_API_URL || "https://katto.tech").replace(/\/$/, "");
 const API_KEY = process.env.KATTO_API_KEY;
 
+// NOTE: we intentionally do NOT exit when the key is missing. The server must be
+// able to start and answer tools/list WITHOUT a key so that MCP directory/aggregator
+// sandboxes (Glama, mcp.so, ...) can enumerate the tools — otherwise they show
+// "0 tools". Nothing runs unauthenticated: the key is enforced at call time in api()
+// below, so tools/list is public but every tool CALL still requires a valid key.
 if (!API_KEY) {
-  console.error("[katto-mcp] KATTO_API_KEY is required. Create one at https://katto.tech/dashboard/api-keys");
-  process.exit(1);
+  console.error("[katto-mcp] No KATTO_API_KEY set — tools/list works, but calling any tool requires a key. Create one at https://katto.tech/dashboard/api-keys");
 }
 
 async function api(path, init = {}) {
+  if (!API_KEY) {
+    throw new Error("KATTO_API_KEY is required to call Katto tools. Create one at https://katto.tech/dashboard/api-keys and set it in your MCP client config.");
+  }
   const res = await fetch(`${API_URL}${path}`, {
     ...init,
     headers: {
@@ -146,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: {} },
   },
   {
@@ -233,6 +247,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 },
@@ -244,16 +259,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. Each clip is { url, captions_url, title, score, final }: score is the 0-100 virality score (sort by it to rank), and final is true once the HQ 1080p render is ready — during processing you may see interim clips with final=false whose url is a preview that will be replaced. 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, final }. Sort by score for the top N. `final` is false while a clip's HQ render is still finishing. 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).",
@@ -282,8 +298,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.3" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "katto", version: "0.5.5" }, { capabilities: { tools: {} } });
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS_LISTED }));
 
@@ -320,6 +363,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.3",
-  "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.5",
+  "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"
+  }
+}