@kolbo/mcp 1.95.0 → 1.96.1

package/README.md

@@ -356,3 +356,7 @@ Both are optional — the local install logs in via the browser on first use.
 | `update_video_editor_session` | Atomic rename, settings, tracks, clips, trims, speed, captions and effects |
 
 `create_video_editor_session` also accepts optional advanced `session_data` instead of clips/audio/texts. Read the schema and saved revision before editing. Changes affect saved state; reload an already-open editor before manual editing. Existing create/export names and arguments remain supported.
+
+### URL downloads
+
+`download_media_from_url` starts a server download for a public media page URL. Use `get_download_status` with the returned `job_id` (not `get_generation_status`) and wait for `completed` before using `resultUrl`. `cancel_download` cancels an active job. This produces a cloud file and saves it to the account library when library sync succeeds; it does not write to the caller's computer. Video returns a verified MP4, audio returns MP3; maximum 500 MB. Existing `upload_media` still handles local/direct-file uploads. SDK routes reuse the authenticated utility pipeline at `POST /v1/downloads`, `GET /v1/downloads/:jobId`, and `DELETE /v1/downloads/:jobId`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.95.0",
+  "version": "1.96.1",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@d6af561, the single source of truth.
+This tree is mirrored from kolbo-code@8d24f6e, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -142,6 +142,7 @@ Font tools (when exposed by the installed MCP): `list_fonts`, `get_font`, `uploa
 | Tool | Purpose |
 |------|---------|
 | `list_models` / `list_voices` / `check_credits` / `show_plans` / `get_generation_status` / `cancel_generation` / `get_session_usage` | Discovery + status. `list_models` with no args returns the recommended shortlist out of ~428 — pass `type` for a full category with per-model caps. `cancel_generation` stops an in-flight job and refunds what it can: use it when the user changes their mind mid-generation instead of letting it run. `show_plans` renders the balance + upgrade card for pricing/plan/upgrade questions. |
+| `download_media_from_url` / `get_download_status` / `cancel_download` | Download a public social/video page URL to Kolbo storage. Async job; use download status, not generation status. See `workflows/media-library.md`. |
 | `upload_media` / `create_upload_ticket` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md`. Getting a LOCAL file in depends on where the server runs: `upload_media` with a path only works on a local (stdio) install; over a remote connector use `create_upload_ticket` and POST the file yourself. |
 | `create_visual_dna` / `update_visual_dna` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — see `workflows/visual-dna.md`. Edit with `update_visual_dna`; never delete+recreate. |
 | `list_moodboards` / `get_moodboard` / `list_presets` / `list_cinematic_presets` | Style overlays + presets. `list_presets` spans FOUR distinct catalogs (`image`, `image_edit`, `video`, `music`; `text_to_video` is an alias for `video`, `shorts` is empty) — the `video` one holds 200+ Seedance shot recipes. `list_cinematic_presets` is a separate tool feeding the `cinematic` arg, never `preset_id`. Full doctrine + intent→catalog map: `references/workflows/presets.md`. Never omit `preset_id` after claiming a preset was used. |

package/skill/references/workflows/media-library.md

@@ -124,3 +124,12 @@ The `*_music_library` tools (`search_music_library` / `browse_music_library` / `
 - `import_music_track_to_library` charges the same way AND also copies the clean track into the media library.
 - `analyze_script_for_music` turns a script into search terms for `search_music_library`.
 - Use this family when the user needs music cleared for commercial use. When free stock will do, use `search_stock_media` with `mediaType: "music"` instead.
+
+
+## Download a public video or audio page
+
+For a YouTube, Instagram, TikTok, Facebook, X or other supported public media page, call `download_media_from_url`. Use `output_type: "video"` (default) for MP4 or `"audio"` for MP3; choose an optional resolution through `quality`. This is a download, not AI generation. Maximum output size is 500 MB.
+
+Keep the returned `job_id`. Check `get_download_status` at reasonable intervals (at least two seconds); never use `get_generation_status` for these jobs or start another download while the first is pending. Only `completed` means the returned `resultUrl` is ready. Use `cancel_download` if the user cancels. Do not repeatedly retry unavailable/private media.
+
+The result is hosted by Kolbo, not saved to the user's local folder automatically. If a local file was requested and your host supports filesystem downloads, save the completed result URL there. Never claim local delivery from a cloud URL alone. For an existing local file or direct file upload, keep using `upload_media` instead.

package/src/toolAnnotations.js

@@ -9,6 +9,7 @@
  */
 
 const READ_ONLY = [
+  'get_download_status',
   'get_video_editor_schema', 'list_video_editor_sessions', 'get_video_editor_session',
   'list_fonts', 'get_font', 'get_font_upload_status',
   'get_creative_director_status', 'get_generation_status', 'list_models',
@@ -70,6 +71,7 @@ const PRIVATE_WRITE = [
 ];
 
 const DESTRUCTIVE_WRITE = [
+  'cancel_download',
   'extend_music', 'cover_music',
   'update_video_editor_session',
   'delete_font',
@@ -102,6 +104,7 @@ const DESTRUCTIVE_WRITE = [
 ];
 
 const OPEN_WORLD_WRITE = [
+  'download_media_from_url',
   'import_music_audio',
   'publish_html_artifact', 'create_review_share_link', 'blender_capture_viewport',
   // Adobe edits add bins, clips, sequences or caption tracks; none delete or overwrite.

package/src/tools/media.js

@@ -64,6 +64,23 @@ function uploadTicketPayload(ticket) {
 }
 
 function registerMediaTools(server, client, options = {}) {
+
+  server.tool('download_media_from_url',
+    'Download a public YouTube, Instagram, TikTok, Facebook, X or other supported media page through Kolbo servers. Use this for social page URLs; upload_media is for existing files or direct file URLs. Returns an asynchronous download job, NOT a finished file. Call get_download_status with job_id until terminal; do not use get_generation_status or resubmit while pending. Completed video output is one MP4 with its expected audio, audio output is MP3, maximum 500 MB. Returns a cloud URL, not a local filesystem path. Private/login-restricted or unavailable media may fail.',
+    { url: z.string().url(), quality: z.enum(['best','2160','1440','1080','720','480','360']).optional(), output_type: z.enum(['video','audio']).optional() },
+    async ({ url, quality = 'best', output_type = 'video' }) => {
+      const result = await client.post('/v1/downloads', { url, quality, outputType: output_type });
+      return { content: [{ type: 'text', text: JSON.stringify({ ...result, job_id: result.jobId, next_tool: 'get_download_status' }) }] };
+    });
+  server.tool('get_download_status',
+    'Read a URL-download job owned by this account. Use the job_id returned by download_media_from_url. pending/processing means wait before checking again; completed includes resultUrl/url; failed/cancelled is terminal. Do not report a file ready until completed. This is separate from AI generation status.',
+    { job_id: z.string().min(1).max(100) },
+    async ({ job_id }) => ({ content: [{ type: 'text', text: JSON.stringify(await client.get(`/v1/downloads/${encodeURIComponent(job_id)}`)) }] }));
+  server.tool('cancel_download',
+    "Cancel this account's pending or processing URL-download job. Does not delete a previously completed file.",
+    { job_id: z.string().min(1).max(100) },
+    async ({ job_id }) => ({ content: [{ type: 'text', text: JSON.stringify(await client.delete(`/v1/downloads/${encodeURIComponent(job_id)}`)) }] }));
+
   // `opts.apps` is set only by kolbo-api's per-request server (see createServer
   // in ../index.js), which makes it a TRANSPORT signal — deliberately not
   // `appsEnabled()`, which also returns true for stdio hosts that advertise UI.