katto-mcp 0.5.8 → 0.5.10

package/README.md

@@ -7,7 +7,7 @@
 
 **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).
+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: the Creator plan's 25-video monthly quota covers videos up to 90 minutes each. API and MCP access is included on **every plan, including the free one** (2 videos/month), not gated behind a paid or enterprise tier.
 
 ## What it does
 
@@ -65,6 +65,8 @@ claude mcp add --transport http katto https://mcp.katto.tech/mcp
 
 ## Tools
 
+**16 tools**, in three groups: six for clipping, three for editing, seven for account and reference.
+
 Clipping:
 - **`katto_create_clip_job(url, config?)`** clip a long video (YouTube, Twitch, Vimeo, Rumble, Zoom, Dailymotion). Returns a job id.
 - **`katto_get_job(id)`** poll until `status` is `completed`; `clips` holds the finished MP4 + caption (SRT) urls.
@@ -87,7 +89,7 @@ Account and reference:
 - **`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).
+Jobs draw from your Katto plan's monthly video quota (25 on Creator, 10 on Solo, 2 on Free), with source videos up to 90, 60 and 30 minutes respectively. 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).
 
 ## Env
 
@@ -108,7 +110,7 @@ Full docs: **[katto.tech/docs/api](https://katto.tech/docs/api)**
 
 - npm: [katto-mcp](https://www.npmjs.com/package/katto-mcp)
 - GitHub: [miracleweasel/katto-mcp](https://github.com/miracleweasel/katto-mcp)
-- [mcp.so](https://mcp.so/servers/katto) · [Smithery](https://smithery.ai/server/@dev-4lue/katto-mcp) · [Glama](https://glama.ai/mcp/servers/@miracleweasel/katto-mcp)
+- [mcp.so](https://mcp.so/servers/katto) · [Smithery](https://smithery.ai/servers/dev-4lue/katto-mcp) · [Glama](https://glama.ai/mcp/servers/@miracleweasel/katto-mcp)
 - Official MCP Registry: `io.github.miracleweasel/katto-mcp`
 
 ## Public Discovery

package/SKILL.md

@@ -1,13 +1,14 @@
 ---
 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.
+description: Turn a long video (a YouTube / Twitch / Vimeo / Rumble / Zoom / Dailymotion link) 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.
+cut → captions → reframe → optional dub. You trigger it; nothing renders on the local
+machine. Publishing to social platforms is done in the Katto app: no tool here publishes.
+Local files go through the REST upload API (`POST /v1/uploads`), not through these tools.
 
 ## Connect
 - **Hosted MCP (recommended, zero-install):** point the client at `https://mcp.katto.tech/mcp`
@@ -17,8 +18,9 @@ the local machine.
 
 ## 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"`.
+   monthly quota. Pass `idempotency_key` (e.g. a UUID) when you might retry, so a retry never
+   double-spends; pass `webhook_url` to be notified instead of polling.
+2. Poll `katto_get_job({ id })` every 30–60 s until `status` is `"completed"`.
 3. `katto_get_clips({ id })` → finished clips (MP4 url + SRT + title + score 0–100).
 
 ## Editing — never counts against quota
@@ -31,15 +33,17 @@ the local machine.
 - `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 are free; dubbing is a Creator feature.
-- Captions: **99 languages** (word-timed in 41, sentence-level in the rest). Dubbing: **19**. Publish: **7 platforms**.
+- **One quota**, shared with the app and the API: Free = 2 videos/month (≤30 min each),
+  Solo = 10 (≤60 min), Creator = 25 (≤90 min). Re-renders are free; dubbing is Creator only.
+- If a call fails on quota, tell the user and give them the upgrade link included in the error.
+- Captions: **99 languages** (word-timed in 41, sentence-level in the rest). Dubbing: **19**.
 - **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`
+User: *"Clip this podcast, then dub clip 2 in Spanish."*
+→ `katto_create_clip_job({ url, idempotency_key })` → poll `katto_get_job` → `katto_get_clips`
+(Katto decides how many clips the video holds: there is no clip-count parameter.)
 → `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

@@ -57,14 +57,16 @@ const TOOLS = [
       type: "object",
       properties: {
         url: { type: "string", description: "Public video URL to clip." },
+        webhook_url: { type: "string", description: "Optional https URL that receives a signed POST when the job finishes, so you do not have to poll. Verify the signature with the secret from katto_get_webhook_secret. Private and local addresses are refused." },
+        idempotency_key: { type: "string", description: "Optional unique string (max 255 chars). Retrying with the same key returns the original job instead of creating a second one and spending another video. Use one per intended job, e.g. a UUID." },
         config: {
           type: "object",
           description: "Optional pre-clip settings.",
           properties: {
             genre: { type: "string", description: "e.g. podcast, gaming, sports, interview" },
-            clipLength: { type: "string", enum: ["lt30", "30_60", "60_90", "90_180"] },
-            customPrompt: { type: "string" },
-            topics: { type: "string" },
+            clipLength: { type: "string", enum: ["lt30", "30_60", "60_90", "90_180"], description: "Target length band for the clips, in seconds. Guides candidate selection by setting a minimum and maximum duration; it is a preference, not a hard cut. Omit to let the model decide." },
+            customPrompt: { type: "string", description: "Free-text hint about what matters in this video. Its keywords nudge selection toward matching moments. It does not filter: a clip that matches nothing can still be selected if it scores well." },
+            topics: { type: "string", description: "Comma-separated topics to favour. Merged with customPrompt into a single keyword hint, so both bias the ranking rather than restrict it." },
           },
         },
       },
@@ -175,6 +177,7 @@ const TOOLS = [
         clip_index: { type: "number", description: "0-based index of the clip to re-render." },
         layout_mode: {
           type: "string",
+          description: "Force a reframing layout instead of letting detection choose one. Omit for automatic, which is what produces the best result on most clips.",
           enum: ["face_tracking", "wide", "split_screen", "stacked", "passthrough", "grid_3", "grid_4"],
         },
         caption_style: {
@@ -199,6 +202,7 @@ const TOOLS = [
         clip_index: { type: "number", description: "0-based clip index." },
         languages: {
           type: "array",
+          description: "Target languages for the dub, as ISO 639-1 codes. Nineteen are available; the clip keeps its original audio for any language not listed here.",
           items: { type: "string", enum: ["en", "es", "fr", "it", "pt", "hi", "ja", "zh", "de", "ko", "nl", "pl", "ru", "tr", "id", "vi", "th", "uk", "ar"] },
         },
       },
@@ -263,7 +267,7 @@ const ANNOTATIONS = {
 // Agent-facing descriptions (when to call, returns, errors, quota cost). Served
 // 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_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 every 30-60 s until status is 'completed', or pass webhook_url to be notified. Pass idempotency_key when you might retry, so a retry never spends a second video. 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. 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: 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.",
@@ -331,7 +335,11 @@ const CAPTION_STYLES = [
   { value: 'multicolor', label: 'Multicolor' },
 ];
 
-const server = new Server({ name: "katto", version: "0.5.8" }, { capabilities: { tools: {} } });
+// Lues par le client au demarrage, avant tout appel : le deroule type, la
+// cadence de sondage et quoi faire d'un quota epuise. Meme texte dans les 3 sources.
+const SERVER_INSTRUCTIONS = "Katto turns a long video into short vertical clips. Typical flow: katto_get_usage (each new job spends 1 video from the monthly quota) -> katto_create_clip_job with the public URL -> poll katto_get_job every 30-60 seconds until status is 'completed' (a 20-minute video took about 5 minutes for 8 clips; longer sources take longer) -> katto_get_clips, and show each clip's title and score rather than only ids. Do not download, open or transcribe the video yourself: Katto fetches it. If a call fails with a quota error, tell the user and give them the upgrade link included in the message. Re-renders and dubbing are separate jobs: start one, then poll katto_get_rerender; do not start the same re-render twice in a loop.";
+
+const server = new Server({ name: "katto", version: "0.5.10" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS_LISTED }));
 
@@ -342,7 +350,8 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     if (name === "katto_create_clip_job") {
       data = await api("/api/v1/jobs", {
         method: "POST",
-        body: JSON.stringify({ url: args.url, config: args.config }),
+        body: JSON.stringify({ url: args.url, config: args.config, ...(args.webhook_url ? { webhook_url: args.webhook_url } : {}) }),
+      ...(args.idempotency_key ? { headers: { "Idempotency-Key": String(args.idempotency_key) } } : {}),
       });
     } else if (name === "katto_get_job") {
       data = await api(`/api/v1/jobs/${encodeURIComponent(args.id)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "katto-mcp",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "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",
@@ -38,8 +38,13 @@
     "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" },
+  "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": {