@kolbo/mcp 1.110.1 → 1.110.3

package/package.json

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

package/src/apps/index.js

@@ -362,7 +362,7 @@ async function modelInfoMap(client) {
 // model the user actually knows. draft_enhance finalizes a Seedance 2.5 Draft;
 // its engine id is internal, so the card showed "Smart Select" / a raw id.
 const DISPLAY_ALIASES = {
-  'flux-3-draft-enhance': { base: 'seedance-2-5', name: 'Seedance 2.5 Draft Enhance' },
+  'flux-3-draft-enhance': { base: 'seedance-2-5', name: 'Seedance 2.5 Draft Enhance' },
   'video-draft-enhance': { base: 'seedance-2-5', name: 'Seedance 2.5 Draft Enhance' },
 };
 // Operations whose engine is picked server-side when no model is passed.
@@ -573,11 +573,17 @@ async function modelIcon(client, modelName) {
 // `key.replace(/\s+/g, '-')`) is why "flux-2-flash" never found "flux-2/flash".
 const normId = (s) => String(s || '').toLowerCase().replace(/[\s._/-]+/g, '');
 
-// The API maps these to Smart Select itself. They are never typos, so they must
-// never be "corrected" or reported as unknown.
+// "Let Kolbo pick" spellings. They are never typos, so they must never be
+// "corrected" or reported as unknown. The API only accepts the exact spellings
+// in API_AUTO_ALIASES; it answers any other explicit model with 400
+// MODEL_NOT_FOUND, so the rest ("Smart Select", "default", "none") are sent
+// as 'auto'.
 const AUTO_ALIASES = new Set([
   'auto', 'autoselect', 'smartselect', 'kolbosmartselectrouter', 'default', 'none',
 ]);
+const API_AUTO_ALIASES = new Set([
+  'smart-select', 'smart_select', 'smartselect', 'auto', 'auto-select', 'kolbo_smart_select_router',
+]);
 
 /**
  * Narrow several models that answer to the same string down to one identifier.
@@ -649,7 +655,8 @@ async function canonicalModelId(client, input, type) {
   if (!input || typeof input !== 'string') return input;
   const key = input.toLowerCase().trim();
   const want = normId(key);
-  if (!want || AUTO_ALIASES.has(want)) return input;
+  if (!want) return input;
+  if (AUTO_ALIASES.has(want)) return API_AUTO_ALIASES.has(key) ? input : 'auto';
   // Exact native-workflow ids pass through: the near-miss check below would reject an
   // unpublished or cached-out 'kolbo-*' id as unknown.
   if (NATIVE_WORKFLOW_MODEL_IDS.has(key)) return input;

package/src/apps/widgets/generation.js

@@ -393,6 +393,14 @@ function referenceHTML(sc) {
         + peek + ' onerror="this.style.display=\\'none\\'">';
     }
   }
+  // Local files the caller passed by path: the iframe cannot load them and they
+  // are only uploaded during the run, so name them instead of showing nothing.
+  // The finished card carries the uploaded thumbnails and drops these.
+  if (sc.phase !== 'completed' && Array.isArray(sc.local_references)) {
+    sc.local_references.slice(0, 6).forEach(function (name) {
+      h += '<span class="k-chip" title="' + esc(name) + '">' + ICONS.image + ' ' + esc(String(name).slice(0, 24)) + '</span>';
+    });
+  }
   return h;
 }
 // Which characters/looks are locked into this generation — by face and name,
@@ -1304,7 +1312,8 @@ function openPromptRow(placeholder, onSend) {
 // like the result path, so a .mp4 handed to the files arg renders as video.
 var PRE_IMAGE_KEYS = ['source_images', 'reference_images', 'image_url', 'mask_image_url',
   'additional_images', 'first_frame', 'last_frame', 'seed_reference_image_url',
-  'elements', 'files', 'keyframes', 'source'];
+  'elements', 'files', 'keyframes', 'source', 'first_frame_url', 'last_frame_url',
+  'texture_image_url', 'background_reference_image'];
 var PRE_VIDEO_KEYS = ['source_video', 'video_url', 'mask_video_url', 'reference_videos'];
 var PRE_AUDIO_KEYS = ['audio', 'audio_url', 'reference_audio_urls', 'seed_reference_audio_urls'];
 
@@ -1319,11 +1328,16 @@ var PRE_AUDIO_KEYS = ['audio', 'audio_url', 'reference_audio_urls', 'seed_refere
 // this) — rendering the raw identifier the caller passed would put an id on the
 // card, which is never allowed.
 function preRefSc(toolName, a) {
-  var img = [], vid = [], aud = [];
+  var img = [], vid = [], aud = [], local = [];
   var take = function (v, bucket) {
     if (typeof v === 'string') {
-      // http(s) only — an absolute local path is not loadable from the iframe.
-      if (/^https?:/i.test(v) && bucket.indexOf(v) < 0) bucket.push(v);
+      // http(s) only — an absolute local path is not loadable from the iframe,
+      // so it is shown by file name instead (see referenceHTML).
+      if (/^https?:/i.test(v)) { if (bucket.indexOf(v) < 0) bucket.push(v); }
+      else if (/^(?:[a-z]:[\\\\/]|\\/|~[\\\\/]|file:)/i.test(v)) {
+        var name = v.split(/[\\\\/]/).pop() || v;
+        if (local.indexOf(name) < 0) local.push(name);
+      }
       return;
     }
     if (Array.isArray(v)) {
@@ -1343,6 +1357,7 @@ function preRefSc(toolName, a) {
     reference_images: img,
     reference_videos: vid,
     reference_audio: aud,
+    local_references: local,
     settings: {
       duration: a.duration,
       resolution: a.draft === true ? '480p-draft' : a.draft === false ? String(a.resolution || '').replace(/-draft$/i, '') : a.resolution,

package/src/tools/agents.js

@@ -35,14 +35,23 @@ function registerSkillCrud(server, client, { noun, idArg, suffix, plural }) {
   server.tool(
     `list_${plural}`,
     `List the user's custom ${plural} (personal + any platform/org preset ${plural} visible to them). A ${noun} is a reusable, named persona for the chat tool — its \`description\` is the system instruction the model adopts. Use this to resolve a ${noun} NAME the user mentioned into its id, or to show what ${plural} exist. Returns id, name, description, emoji, is_global. Personal ${plural} (is_global:false) are editable/deletable; platform presets are not.${legacyNote}`,
-    { search: z.string().optional().describe('Optional case-insensitive name filter.') },
-    async ({ search }) => {
-      const qs = search ? `?search=${encodeURIComponent(search)}` : '';
-      const result = await client.get(`/v1/skills${qs}`);
+    {
+      search: z.string().optional().describe('Optional case-insensitive name filter.'),
+      page: z.number().int().min(1).optional().describe('Page number, 1-indexed. Default: 1. The response `pagination.has_more` says whether another page exists.'),
+      limit: z.number().int().min(1).max(100).optional().describe('Results per page, max 100. Default: 50.')
+    },
+    async ({ search, page, limit }) => {
+      const params = new URLSearchParams();
+      if (search) params.set('search', search);
+      if (page) params.set('page', String(page));
+      if (limit) params.set('limit', String(limit));
+      const qs = params.toString();
+      const result = await client.get(`/v1/skills${qs ? '?' + qs : ''}`);
       const agents = result.agents || [];
       const text = JSON.stringify({
         agents,
-        count: result.count || agents.length
+        count: result.count || agents.length,
+        ...(result.pagination ? { pagination: result.pagination } : {})
       }, null, 2);
 
       return listResult(text, {
@@ -55,7 +64,9 @@ function registerSkillCrud(server, client, { noun, idArg, suffix, plural }) {
           badge: a.is_global ? 'preset' : null,
           use_hint: `Use my "{TITLE}" ${noun} (${idArg}: {ID}) for this conversation.`
         })),
-        total: agents.length
+        total: agents.length,
+        page_tool: `list_${plural}`,
+        next_args: result.pagination?.has_more ? { search, page: (page || 1) + 1, limit } : undefined
       });
     }
   );
@@ -66,7 +77,7 @@ function registerSkillCrud(server, client, { noun, idArg, suffix, plural }) {
     `Create a reusable custom ${noun} (a named persona for the chat tool). The \`description\` IS the ${noun}'s system instruction — write it as the persona + behavior you want ("You are a senior creative director. Turn any brief into a structured shot list…"). Use when the user wants a persistent, reusable assistant ("make me a creative-director ${noun}", "set up a support-triage bot"). For a ONE-OFF persona on a single conversation, pass \`system_prompt\` to chat_send_message instead — no need to create a ${noun}. Plan limits apply (server rejects when the ${noun} cap is reached).${legacyNote}`,
     {
       name: z.string().optional().describe(`${noun[0].toUpperCase() + noun.slice(1)} name. If omitted, a name is generated from the description.`),
-      description: z.string().describe(`The ${noun} persona + instructions (max 2000 chars). This becomes the system prompt the model adopts in every conversation that uses the ${noun}.`),
+      description: z.string().describe(`The ${noun} persona + instructions (no API length cap; keep it under 8000 characters if it should stay editable in the Kolbo app). This becomes the system prompt the model adopts in every conversation that uses the ${noun}.`),
       emoji: z.string().optional().describe('Optional emoji avatar (auto-picked if omitted).'),
       thumbnail: z.string().optional().describe('Optional thumbnail image URL.')
     },
@@ -87,7 +98,7 @@ function registerSkillCrud(server, client, { noun, idArg, suffix, plural }) {
     {
       [idArg]: z.string().describe(idDesc),
       name: z.string().optional().describe('New name.'),
-      description: z.string().optional().describe('New persona/instructions (replaces the old description; max 2000 chars).'),
+      description: z.string().optional().describe('New persona/instructions (replaces the old description; no API length cap, keep it under 8000 characters if it should stay editable in the Kolbo app).'),
       emoji: z.string().optional().describe('New emoji avatar.'),
       thumbnail: z.string().optional().describe('New thumbnail image URL.')
     },

package/src/tools/audio_stems.js

@@ -3,12 +3,9 @@
  *
  * Audio stem separation — Kolbo's own pipeline, not a passthrough to one vendor.
  *
- * Demucs supplies the masks (its stems sum back to the original at −30 to −37 dB, so nothing
- * is resynthesised) and a speech classifier supplies the semantic gate Demucs lacks: a
- * "vocals" mask is NOT the same thing as dialogue, because engines, impacts and centred
- * ambience land there at full volume. When no words are actually spoken, that mask is folded
- * back into Effects rather than handed over mislabeled as Dialogue. That gate is why these
- * tools exist as their own surface instead of a `separate` operation on edit_video.
+ * The backend runs prompted source separation in sequence (speech, then music, then
+ * ambience), each pass working on the previous residual, so the layers stay disjoint.
+ * mode="dialogue" stops after the speech pass (Dialogue + M&E only).
  *
  * These three routes answer INLINE — there is no job id and nothing to poll. Each call holds
  * its connection for the whole run, so they carry an explicit long request timeout rather
@@ -57,13 +54,13 @@ function registerAudioStemTools(server, client) {
   // ─── separate_audio_stems ─────────────────────────────────────
   server.tool(
     'separate_audio_stems',
-    'Split a soundtrack into separate audio layers: Dialogue, Music, Effects, and a '
+    'Split a soundtrack into separate audio layers: Dialogue, Music, Ambience, Effects, and a '
     + '"without dialogue" (M&E) track — Kolbo\'s own separation pipeline, built for dubbing, '
     + 'localisation, podcast cleanup and re-scoring. Use this whenever someone wants to '
     + 'remove/isolate speech, strip narration, mute the music, get a clean instrumental bed, '
-    + 'or hand an editor stems. A speech classifier decides whether the vocal mask is really '
-    + 'dialogue, so an engine roar or centred ambience is not mislabelled as speech — that is '
-    + 'what makes this better than a plain vocal remover. Costs 5 credits. Runs inline and '
+    + 'or hand an editor stems. Speech, music and ambience are pulled out one after another, '
+    + 'each from what the previous pass left, so the layers do not overlap. Pass '
+    + 'mode="dialogue" when only the voice/background split is needed. Costs 5 credits. Runs inline and '
     + 'returns the finished layer URLs (usually 20–90 seconds); there is nothing to poll. '
     + 'Sources up to 15 minutes long — trim longer files first. NOTE: there is no cache on the '
     + 'URL form, so calling it twice on the same file separates twice and bills twice.',
@@ -73,9 +70,12 @@ function registerAudioStemTools(server, client) {
       generation_id: z.string().optional()
         .describe('ID of a Kolbo video generation to separate instead of a URL. Layers are also saved onto that generation, so a repeat call is free.'),
       project_id: projectIdField,
+      mode: z.enum(['full', 'dialogue']).optional()
+        .describe('"full" (default): Dialogue, Music, Ambience, Effects and M&E. "dialogue": one speech pass returning only Dialogue and the without-dialogue (M&E) track.'),
     },
-    async ({ audio_url, generation_id, project_id }) => {
+    async ({ audio_url, generation_id, project_id, mode }) => {
       const body = buildBody({ audio_url, generation_id, project_id }, 'separate_audio_stems');
+      if (mode) body.mode = mode;
       const result = await client.post('/v1/audio/separate', body, { timeoutMs: STEMS_TIMEOUT_MS });
       return textResult({
         ...summarize(result),
@@ -86,11 +86,12 @@ function registerAudioStemTools(server, client) {
         layer_guide: {
           dialogue: 'Speech only.',
           music: 'Score / song bed. Absent when the clip has no music.',
+          ambience: 'Room tone / atmosphere. Present in mode="full".',
           sfx: 'Effects and Foley.',
           me: 'Everything except dialogue (M&E) — the track to dub over.',
           original: 'The untouched mix, for reference.',
         },
-        next_steps: 'If voices are still faintly audible in the "me" layer, run clean_dialogue_leftovers on its URL. To pull room tone out of the Effects bed, run separate_ambience on it.',
+        next_steps: 'If voices are still faintly audible in the "me" layer, run clean_dialogue_leftovers on its URL. Ambience comes back as its own layer in mode="full"; for a dialogue-mode split, run separate_ambience on the "me" layer with source_type="me".',
       });
     },
   );
@@ -101,8 +102,8 @@ function registerAudioStemTools(server, client) {
     'Strip voices that are still faintly audible in a "without dialogue" (M&E) track produced '
     + 'by separate_audio_stems. Use it only when the user actually hears speech bleeding '
     + 'through — it is not part of the normal flow, and it trades fidelity to do its job '
-    + '(the generative model that removes the leak reconstructs the bed less cleanly than the '
-    + 'masking model that made it). Typical on dense crowd scenes; unnecessary on clean '
+    + '(each cleanup pass re-separates the bed, so the M&E comes back less faithful than the '
+    + 'original split; it runs up to 3 passes until the voices are gone). Typical on dense crowd scenes; unnecessary on clean '
     + 'dialogue. Costs 17 credits, charged even when the track turns out to be already clean '
     + '(the analysis pass still runs) — the response says which happened. Runs inline.',
     {
@@ -128,8 +129,9 @@ function registerAudioStemTools(server, client) {
   server.tool(
     'separate_ambience',
     'Pull room tone / atmosphere out of an Effects or Music bed, leaving the hard effects '
-    + 'behind — a fourth lane on top of separate_audio_stems, for when someone wants the '
-    + 'ambience of a location on its own, or wants it gone. Run separate_audio_stems first '
+    + 'behind. separate_audio_stems in its default "full" mode already returns an Ambience '
+    + 'layer, so this is only needed for a dialogue-mode split, an older split, or a bed that '
+    + 'still carries room tone. Run separate_audio_stems first '
     + 'and pass the resulting "sfx" (or "music") layer URL. Costs 17 credits, charged even '
     + 'when the bed turns out to have no separable ambience — the response reports '
     + 'skipped: true in that case. Runs inline.',

package/src/tools/chat.js

@@ -26,11 +26,11 @@ function registerChatTools(server, client) {
       project_id: projectIdField
     },
     async ({ message, model, session_id, system_prompt, web_search, deep_think, thinking_level, routing_mode, enhance_prompt = false, media_urls, project_id }) => {
-      // Every generate_* tool resolves its model this way; chat was the one
-      // `model` arg that went straight to the API, which has no fuzzy matching.
-      // So the display names list_models hands back ("Claude Fable 5") came
-      // back as a bare `Model not found: Claude Fable 5 [MODEL_NOT_FOUND]` —
-      // discovery had no path to use.
+      // Every generate_* tool resolves its model this way. The API answers an
+      // explicit model it cannot match with 400 MODEL_NOT_FOUND (plus "did you
+      // mean" suggestions) instead of silently falling back to Smart Select, so
+      // resolve display names list_models hands back ("Claude Fable 5") to their
+      // catalog identifier here, scoped to the text catalog, before sending.
       model = await canonicalModelId(client, model, 'text'); // lenient id resolution ("Grok 4.5" → its identifier)
 
       const gen = await client.post('/v1/chat', {

package/src/tools/docs.js

@@ -7,7 +7,7 @@ const { z } = require('zod');
 const { projectIdField } = require('./_shared');
 const { listResult } = require('../apps');
 
-const CONTENT_GUIDE = 'HTML body content. Use clean semantic HTML the in-app editor understands: <h1>-<h3>, <p>, <ul>/<ol>/<li>, <table>, <blockquote>, <strong>/<em>, <a>. No <script>/<style>/<iframe> (stripped server-side). Write the FULL document yourself — this is where you author the doc.';
+const CONTENT_GUIDE = 'HTML body content. Use clean semantic HTML the in-app editor understands: <h1>-<h3>, <p>, <ul>/<ol>/<li>, <table>, <blockquote>, <strong>/<em>, <a>, <img>, <video>/<audio> (http(s) src, e.g. Kolbo CDN URLs from list_media), and <iframe> embeds from YouTube, Vimeo, Spotify, SoundCloud, CodePen, CodeSandbox, Google Maps, Figma or Loom (https only; other iframe hosts are stripped). No <script>/<style> (stripped server-side). Write the FULL document yourself — this is where you author the doc.';
 
 function registerDocTools(server, client) {
   // ─── create_doc ────────────────────────────────────────────
@@ -90,12 +90,14 @@ function registerDocTools(server, client) {
     {
       doc_id: z.string().describe('The doc ObjectId to update.'),
       title: z.string().optional().describe('New title. Omit to keep the current one.'),
-      content: z.string().optional().describe('Full replacement ' + CONTENT_GUIDE)
+      content: z.string().optional().describe('Full replacement ' + CONTENT_GUIDE),
+      destructive_intent: z.enum(['replace-document', 'clear-document']).optional().describe('Only when the update intentionally removes most of the document. The server rejects with 409 DESTRUCTIVE_DOCUMENT_REPLACEMENT when new content drops most of the text or every table/image/video, and with 409 DOCUMENT_CLEAR_REQUIRES_INTENT when it empties a populated doc. "replace-document" = the user asked for a rewrite/replacement; "clear-document" = the user asked to empty the doc (send empty content). Never pass it to get past a 409 the user did not ask for — re-read with get_doc and merge instead.')
     },
-    async ({ doc_id, title, content }) => {
+    async ({ doc_id, title, content, destructive_intent }) => {
       const body = {};
       if (title !== undefined) body.title = title;
       if (content !== undefined) body.content = content;
+      if (destructive_intent !== undefined) body.destructive_intent = { kind: destructive_intent };
       const result = await client.put(`/v1/docs/${encodeURIComponent(doc_id)}`, body);
       return { content: [{ type: 'text', text: JSON.stringify(result.doc, null, 2) }] };
     }

package/src/tools/generate.js

@@ -486,7 +486,7 @@ function registerGenerateTools(server, client, options = {}) {
       aspect_ratio: z.string().optional().describe(aspectRatioDescribe('1:1')),
       workflow_type: z.string().optional().describe('"image" (default) or "video"'),
       duration: z.number().optional().describe('Duration in seconds per scene (video mode only). Must be a value in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. E.g., 5 or 10.'),
-      enhance_prompt: z.boolean().optional().describe('Enhance prompts per scene. Default: false — only pass true if the user explicitly asks to enhance/improve the prompts.'),
+      enhance_prompt: z.boolean().optional().describe('Ignored by the server: Creative Director always writes and enhances each scene prompt itself, so true and false behave the same. Kept for backward compatibility.'),
       reference_images: z.array(z.string()).optional().describe('Array of reference images (URLs or absolute local paths) to guide style/composition of every scene. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model.**'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply consistently across every scene. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model.** This is the ideal way to keep a character or product looking the same in all scenes of a campaign.'),
       moodboard_id: z.string().optional().describe('A single moodboard ID whose master_prompt and style_guide should shape every scene.'),

package/src/tools/projects.js

@@ -70,7 +70,7 @@ function registerProjectTools(server, client) {
   // ─── move_session ──────────────────────────────────────────
   server.tool(
     'move_session',
-    'Move ONE session — and ALL of its generations and media library items — to another project. Works for any session type: generation sessions (the `session_id` returned by generate_* tools), chat conversations, transcription sessions, etc. Use this when work landed in the wrong project (e.g. the default "API Generations" bucket) and the user wants it in a named project — moving is always better than regenerating. For SEVERAL sessions use `bulk_move_sessions` instead: one call, up to 100 sessions, and it reports per-session failures. Caller needs edit/full/owner permission on BOTH the source and target projects (a shared-project member can move a teammate\'s session). Resolve the target project id with `list_projects` first.',
+    'Move ONE session — and ALL of its generations and media library items — to another project. Works for image, image_edit, video, video_from_image, elements, first_last_frame, lipsync, video_from_video, global_video_edit, music, speech, sound and chat sessions (the `session_id` returned by generate_* tools, or a chat conversation). Creative Director, transcription, global_image_edit and shorts sessions cannot be moved through the API and return SESSION_TYPE_NOT_MOVABLE. Use this when work landed in the wrong project (e.g. the default "API Generations" bucket) and the user wants it in a named project — moving is always better than regenerating. For SEVERAL sessions use `bulk_move_sessions` instead: one call, up to 100 sessions, and it reports per-session failures. Caller needs edit/full/owner permission on BOTH the source and target projects (a shared-project member can move a teammate\'s session). Resolve the target project id with `list_projects` first.',
     {
       session_id: z.string().describe('The session ObjectId to move (from a generation submit response, chat_list_conversations, or an "Open in Kolbo" link).'),
       project_id: z.string().describe('Target project ObjectId. Call `list_projects` to resolve a project name to its id.'),

package/src/tools/stock_library.js

@@ -49,7 +49,7 @@ function registerStockLibraryTools(server, client, options = {}) {
     'Covers external providers (Pexels photos/videos, Pixabay, Sketchfab 3D, licensed Music) AND Kolbo\'s OWN AI-generated library: thousands of SOUND EFFECTS (mediaType="sfx") and MUSIC tracks (source="kolbo-ai"). Use this to FIND ready-made photos, videos, 3D models, music, or sound effects as b-roll/references/project assets — distinct from generate_* tools which create new content.\n\nFor SOUND EFFECTS or MUSIC, Kolbo supports SEMANTIC "VIBE" SEARCH: pass a natural-language description of the feeling/use ("tense ominous build-up for a horror reveal", "uplifting hopeful corporate background", "retro arcade coin pickup") with source="kolbo-ai" and mediaType="sfx" (or "music") — it matches by meaning, not just keywords. For external visual providers, use concrete keywords.\n\nsource="all" interleaves providers for the requested media type; or pick a single source. Returns assets with source, sourceId, mediaType, dimensions, author, attribution, thumbnail, and downloadable variants. To turn a script into queries first, call analyze_script_for_stock.',
     {
       query: z.string().max(200).optional().describe('For visual providers: concrete keywords ("city skyline sunset"). For Kolbo SFX/music (source="kolbo-ai"): a natural-language VIBE works great ("eerie suspenseful drone", "emotional sad piano"). Omit to browse.'),
-      source: z.enum(['all', 'kolbo-ai', 'pexels', 'pixabay', 'sketchfab', 'music', 'freesound']).optional().describe('Provider. "all" (default) interleaves. "kolbo-ai" = Kolbo\'s own AI SFX + music (best for vibe search). "freesound" = external CC sound effects.'),
+      source: z.enum(['all', 'kolbo-ai', 'pexels', 'unsplash', 'pixabay', 'coverr', 'sketchfab', 'music', 'freesound']).optional().describe('Provider. "all" (default) interleaves. "kolbo-ai" = Kolbo\'s own AI SFX + music (best for vibe search). "unsplash" = photos. "coverr" = stock video + music. "freesound" = external CC sound effects. "music" is not available over the API (returns not found) — use "kolbo-ai" or "coverr" for music.'),
       mediaType: z.enum(['image', 'illustration', 'vector', 'video', '3d', 'music', 'sfx']).optional().describe('Asset type (default "image"). "sfx" = sound effects, "music" = music tracks. Not every source supports every type — call get_stock_sources.'),
       category: z.string().optional().describe('Category/group chip value (providerParam) from get_stock_categories. For Kolbo SFX these are 77 Soundly-style top-level groups (e.g. Ambience, Animals, Vehicles, Weapons, Water, Designed, Magic, UI) — call get_stock_categories to list them all.'),
       subcategory: z.string().optional().describe('Kolbo SFX sub-filter within a group (providerParam from get_stock_categories, e.g. Weapons>sword, Water>splash, Footsteps>concrete, Designed>riser). 623 sub-filters across the 77 groups.'),
@@ -57,10 +57,11 @@ function registerStockLibraryTools(server, client, options = {}) {
       collectionId: z.string().optional().describe('Filter to one Kolbo collection id (from get_stock_collections).'),
       orientation: z.enum(['horizontal', 'vertical', 'landscape', 'portrait', 'square']).optional().describe('Orientation filter (provider-dependent).'),
       color: z.string().optional().describe('Color filter (Pixabay named color, or Pexels named/hex color).'),
-      order: z.enum(['popular', 'latest']).optional().describe('Sort order (Pixabay).'),
+      order: z.enum(['popular', 'latest', 'trending', 'newest', 'title', 'duration_asc', 'duration_desc', 'bpm_asc', 'bpm_desc']).optional().describe('Sort order, provider-dependent. "popular"/"latest": Pixabay, Freesound, Coverr. "trending": Coverr. Music (mediaType="music"): "popular", "newest", "title", "duration_asc", "duration_desc", "bpm_asc", "bpm_desc". A provider ignores values it does not support.'),
       cursor: z.string().optional().describe('Opaque pagination cursor for Sketchfab single-source browse (from a previous response).'),
       page: z.number().int().min(1).optional().describe('1-based page number (default 1).'),
-      perPage: z.number().int().min(1).max(80).optional().describe('Results per page (default 24, max 80).')
+      perPage: z.number().int().min(1).max(80).optional().describe('Results per page (default 24, max 80).'),
+      projectId: z.string().optional().describe('Optional project id. Prices Kolbo music/SFX for that project (e.g. org-project access), so meta.priceCredits matches what importing into that project would cost.')
     },
     async (args) => {
       const q = buildQuery(args);
@@ -136,7 +137,7 @@ function registerStockLibraryTools(server, client, options = {}) {
     'get_stock_categories',
     'List the dynamic category chips for stock sources. For external providers: Pixabay/Sketchfab categories + curated Pexels topics. For Kolbo SFX (source="kolbo-ai", mediaType="sfx"): the 77 Soundly-style top-level groups (group=null) AND their 623 sub-filters (each has a `group` pointing to its parent). Pass a row\'s `providerParam` as `category` (groups) or `subcategory` (sub-filters) to search_stock_media.',
     {
-      source: z.enum(['kolbo-ai', 'pexels', 'pixabay', 'sketchfab']).optional().describe('Restrict to one source. Use "kolbo-ai" to list the SFX groups + sub-filters.'),
+      source: z.enum(['kolbo-ai', 'pexels', 'unsplash', 'pixabay', 'coverr', 'sketchfab', 'freesound']).optional().describe('Restrict to one source. Use "kolbo-ai" to list the SFX groups + sub-filters.'),
       mediaType: z.string().optional().describe('Restrict to one media type (e.g. "image", "video", "3d", "sfx").')
     },
     async (args) => {
@@ -204,12 +205,13 @@ function registerStockLibraryTools(server, client, options = {}) {
     'get_stock_asset',
     'Get a single normalized stock asset with all downloadable variants, author, license, and attribution, by source + id. Call after search_stock_media to resolve the exact download URLs (incl. WAV master + MP3 for Kolbo SFX/music).',
     {
-      source: z.enum(['kolbo-ai', 'pexels', 'pixabay', 'sketchfab', 'music', 'freesound']).describe('The asset source.'),
+      source: z.enum(['kolbo-ai', 'pexels', 'unsplash', 'pixabay', 'coverr', 'sketchfab', 'music', 'freesound']).describe('The asset source. "music" is not available over the API.'),
       id: z.string().describe('The provider asset id (sourceId).'),
-      mediaType: z.string().optional().describe('Media type hint (e.g. "video") — needed for sources that share ids across types.')
+      mediaType: z.string().optional().describe('Media type hint (e.g. "video") — needed for sources that share ids across types.'),
+      projectId: z.string().optional().describe('Optional project id used to price Kolbo music/SFX for that project (same as search_stock_media).')
     },
-    async ({ source, id, mediaType }) => {
-      const q = buildQuery({ mediaType });
+    async ({ source, id, mediaType, projectId }) => {
+      const q = buildQuery({ mediaType, projectId });
       const result = await client.get(`/v1/stock/asset/${encodeURIComponent(source)}/${encodeURIComponent(id)}${q ? '?' + q : ''}`);
       return { content: [{ type: 'text', text: JSON.stringify(result.asset, null, 2) }] };
     }
@@ -233,7 +235,7 @@ function registerStockLibraryTools(server, client, options = {}) {
     'import_stock_asset',
     "Copy a stock asset into the account's Kolbo media library (downloaded to Kolbo's CDN with a stable URL) so it can be used in projects/generations. FREE for images, video and 3D. Kolbo's own MUSIC and SFX are free for subscribers, org members and anyone who already bought the track; for everyone else they COST CREDITS (search results carry the exact price in meta.priceCredits; 0/absent means free for this caller). When a price is shown, tell the user the cost and get agreement BEFORE calling this. Returns the created media library item. Works for Kolbo SFX (source='kolbo-ai', mediaType='sfx') and supported external visual/audio sources. For SYNCI music use import_music_track_to_library; that paid action acquires a clean licensed file.",
     {
-      source: z.enum(['kolbo-ai', 'pexels', 'pixabay', 'sketchfab', 'freesound']).describe('The asset source.'),
+      source: z.enum(['kolbo-ai', 'pexels', 'unsplash', 'pixabay', 'coverr', 'sketchfab', 'freesound']).describe('The asset source.'),
       id: z.string().describe('The provider asset id (sourceId).'),
       mediaType: z.string().optional().describe('Media type hint (e.g. "video", "image", "vector", "3d").'),
       variant: z.string().optional().describe('Which download variant label to import (from get_stock_asset). Defaults to the best/largest available.'),