@kolbo/mcp 1.25.0 → 1.28.0

package/README.md

@@ -190,6 +190,27 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 |------|-------------|
 | `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
 
+**Music Library** (stock / production music)
+| Tool | Description |
+|------|-------------|
+| `search_music_library` | Search the licensed stock-music catalog by keyword + genre/mood/BPM/duration filters. Find a ready-made track (distinct from `generate_music`, which composes a new song). |
+| `analyze_script_for_music` | AI: turn a video/voiceover script into a music search (`query`, `mood`, `genre`, `keywords`). |
+| `browse_music_library` | Browse the catalog without a query (paginated). |
+| `get_music_library_facets` | List available genres, moods, instruments + BPM/duration ranges. |
+| `get_music_track_audio` | Get a track's downloadable 128/320/WAV URLs by id. |
+| `get_music_track_related` | Get stems + alternate versions of a track. |
+| `get_music_track_lyrics` | Get lyrics text, theme, and explicit flag for a track. |
+
+**Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
+| Tool | Description |
+|------|-------------|
+| `search_stock_media` | Search photos/videos/illustrations/vectors/3D/music across providers. `source="all"` returns one interleaved feed. Find ready-made assets / b-roll (distinct from `generate_image`/`generate_video`). |
+| `get_stock_sources` | List enabled sources + which media types/filters each supports. |
+| `get_stock_categories` | List dynamic category/topic chips (pass `providerParam` as the `category` filter). |
+| `get_stock_asset` | Get one asset with all download variants, author, license, and attribution. |
+| `analyze_script_for_stock` | AI: turn a script into b-roll search terms (`queries[]`, `mediaType`, `keywords`). |
+| `import_stock_asset` | Copy a stock asset into the media library (CDN copy, stable URL). Free. |
+
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|

package/package.json

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

package/skill/SKILL.md

@@ -49,6 +49,7 @@ If the user is on a whitelabel build (`sapir`, etc.), they must use their brande
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
 | Build a **multi-scene set** (Creative Director, storyboard, campaign batch, 4+ angles) | `references/models/creative-director.md` |
 | Generate **music** (Suno, song, lyrics, jingle, score) | `references/models/music.md` |
+| Find an **existing / stock / library / royalty-free track** to score a video, ad, or voiceover | `references/workflows/music-library.md` |
 | Build an **HTML presentation / slide deck** | `references/models/html-presentation.md` |
 | Build a **landing page / marketing site** | `references/models/landing-page.md` |
 | Build a **dashboard / data viz / interactive widget / mini-game / UI mockup** | `references/models/visual-code.md` |
@@ -95,6 +96,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` | Visual DNA — see `workflows/visual-dna.md` |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
+| `search_music_library` / `analyze_script_for_music` / `browse_music_library` / `get_music_library_facets` / `get_music_track_audio` / `get_music_track_related` / `get_music_track_lyrics` | **Stock / production music library** — find a licensed ready-made track (NOT `generate_music`, which composes a new song). See `workflows/music-library.md` |
 | `app_builder_*` (9 tools) | Full React app generation — see `workflows/app-builder.md` |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 

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

@@ -0,0 +1,32 @@
+# Music Library (stock / production music)
+
+The music library is Kolbo's catalog of **licensed, ready-made background tracks**. Use it to score a video, ad, or voiceover with an existing track.
+
+> **Library vs generation.** `search_music_library` finds an existing track. `generate_music` composes a brand-new song with Suno. If the user wants "a track for my ad", reach for the library first — it's free (no credits) and instant. Use `generate_music` only when they want something original/custom.
+
+## Tools
+
+| Tool | Use |
+|------|-----|
+| `search_music_library` | Keyword search + filters (genre, mood, bpm, duration, has_stems, has_lyrics) + sort. Returns tracks with id, title, artist, duration, BPM, key, genres, moods, preview URL. |
+| `analyze_script_for_music` | Turn a script/scene description into `{ query, mood, genre, keywords }`. |
+| `browse_music_library` | Paginated browse with no query. |
+| `get_music_library_facets` | Valid genres, moods, instruments + BPM/duration ranges. |
+| `get_music_track_audio` | A track's downloadable 128 / 320 / WAV URLs. |
+| `get_music_track_related` | Stems + alternate versions of a master track. |
+| `get_music_track_lyrics` | Lyrics text, theme, explicit flag. |
+
+All tools are **free** (no credits) and read-only.
+
+## Typical flow
+
+1. **From a script** → call `analyze_script_for_music` to derive `query` / `mood` / `genre`.
+2. **Search** → `search_music_library` with that query (+ optional filters). Show the user the top matches by title + vibe; include the `preview` URL so they can listen.
+3. **Pick** → once the user chooses, call `get_music_track_audio` with the track `id` to get the final downloadable URLs (offer WAV for editing, 320 for delivery).
+4. Optionally `get_music_track_related` for an instrumental/stems cut, or `get_music_track_lyrics` if it's a vocal track.
+
+## Tips
+
+- Don't dump every field — surface title, artist, duration, BPM, mood, and the preview link.
+- If a filtered search returns nothing, call `get_music_library_facets` to use exact valid genre/mood values, then retry.
+- `sort` options: `duration-asc`, `duration-desc`, `bpm-asc`, `bpm-desc`, `title`. Omit for relevance order.

package/src/index.js

@@ -70,6 +70,8 @@ const { registerAppBuilderTools } = require('./tools/app_builder');
 const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
 const { registerVoiceTools } = require('./tools/voices');
+const { registerMusicLibraryTools } = require('./tools/music_library');
+const { registerStockLibraryTools } = require('./tools/stock_library');
 
 /**
  * Build a fully-configured Kolbo MCP server (all tool groups registered)
@@ -105,6 +107,8 @@ function createServer(opts = {}) {
   registerAppBuilderTools(server, client);
   registerArtifactTools(server, client);
   registerProjectTools(server, client);
+  registerMusicLibraryTools(server, client);
+  registerStockLibraryTools(server, client);
 
   return server;
 }

package/src/tools/music_library.js

@@ -0,0 +1,179 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg. Full rules: ../index.js top-of-file. */
+
+const { z } = require('zod');
+
+// Format a normalized track into a compact human-readable line.
+function trackLine(t) {
+  const meta = [
+    t.durationSeconds != null ? `${Math.round(t.durationSeconds)}s` : null,
+    t.bpm != null ? `${t.bpm} BPM` : null,
+    t.musicalKey || null,
+    Array.isArray(t.genres) && t.genres.length ? t.genres.join('/') : t.genre,
+    Array.isArray(t.moodTags) && t.moodTags.length ? t.moodTags.slice(0, 3).join(', ') : null,
+  ].filter(Boolean).join(' · ');
+  const flags = [t.hasStems ? 'stems' : null, t.hasLyrics ? 'lyrics' : null].filter(Boolean).join(', ');
+  return `${t.id} — ${t.title}${t.artist ? ` by ${t.artist}` : ''}\n   ${meta}${flags ? `  [${flags}]` : ''}${t.audioUrl ? `\n   preview: ${t.audioUrl}` : ''}`;
+}
+
+function registerMusicLibraryTools(server, client) {
+  // ─── search_music_library ─────────────────────────────────────
+  server.tool(
+    'search_music_library',
+    'Search the Kolbo stock / production music library (licensed background tracks) by keyword with optional filters. Use this to FIND an existing ready-made track to score a video, ad, or voiceover — distinct from generate_music, which composes a brand-new song with Suno. Returns matching tracks with id, title, artist, duration, BPM, key, genres, moods, and preview/download URLs (128/320/wav). To turn a script into a good query first, call analyze_script_for_music.',
+    {
+      query: z.string().max(200).optional().describe('Keyword search, e.g. "uplifting corporate", "tense cinematic", "lofi hip hop". If omitted, falls back to the mood/genre filter as the search term.'),
+      mood: z.string().optional().describe('Mood filter, e.g. "Emotional", "Energetic", "Tense". Use get_music_library_facets to see valid values.'),
+      genre: z.string().optional().describe('Genre filter, e.g. "Soundtrack", "Corporate", "Hip Hop". Use get_music_library_facets to see valid values.'),
+      bpmMin: z.number().optional().describe('Minimum beats-per-minute.'),
+      bpmMax: z.number().optional().describe('Maximum beats-per-minute.'),
+      durationMin: z.number().optional().describe('Minimum track duration in seconds.'),
+      durationMax: z.number().optional().describe('Maximum track duration in seconds.'),
+      hasStems: z.boolean().optional().describe('Only return tracks that have separated stems.'),
+      hasLyrics: z.boolean().optional().describe('Only return tracks that have lyrics.'),
+      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional().describe('Optional sort order. Omit for relevance order.'),
+      limit: z.number().int().min(1).max(40).optional().describe('Results per page (max 40, default 20).'),
+      offset: z.number().int().min(0).optional().describe('Pagination offset for loading more results.')
+    },
+    async (args) => {
+      const result = await client.post('/v1/music-library/search', args);
+      const tracks = result.tracks || [];
+      if (tracks.length === 0) {
+        return { content: [{ type: 'text', text: 'No tracks found matching those filters. Try a broader query or call get_music_library_facets for valid genres/moods.' }] };
+      }
+      const head = `Found ${tracks.length} track${tracks.length === 1 ? '' : 's'}${result.total ? ` (of ${result.total} sorted)` : ''}:`;
+      return { content: [{ type: 'text', text: `${head}\n\n${tracks.map(trackLine).join('\n\n')}\n\nUse the track id with get_music_track_audio to get the downloadable 128/320/wav URLs.` }] };
+    }
+  );
+
+  // ─── analyze_script_for_music ─────────────────────────────────
+  server.tool(
+    'analyze_script_for_music',
+    'AI helper that turns a video or voiceover script into a music search. Returns { query, mood, genre, keywords } you can pass straight into search_music_library to find a fitting background track. Use this first when the user gives you a script/scene description rather than explicit music keywords.',
+    {
+      script: z.string().min(1).describe('The video or voiceover script / scene description to analyze (up to ~8000 chars).')
+    },
+    async ({ script }) => {
+      const result = await client.post('/v1/music-library/analyze-script', { script });
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            query: result.query,
+            mood: result.mood,
+            genre: result.genre,
+            keywords: result.keywords,
+            _followup_hint: 'Pass query + mood + genre into search_music_library.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── browse_music_library ─────────────────────────────────────
+  server.tool(
+    'browse_music_library',
+    'Browse the music library catalog without a search query (stable paginated listing). Use when the user just wants to see what is available. For a targeted search use search_music_library instead.',
+    {
+      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional().describe('Optional sort order.'),
+      limit: z.number().int().min(1).max(50).optional().describe('Results per page (max 50, default 50).'),
+      offset: z.number().int().min(0).optional().describe('Pagination offset for loading more results.')
+    },
+    async ({ sort, limit, offset }) => {
+      const params = new URLSearchParams();
+      if (sort) params.set('sort', sort);
+      if (limit != null) params.set('limit', String(limit));
+      if (offset != null) params.set('offset', String(offset));
+      const path = `/v1/music-library/catalog${params.toString() ? '?' + params.toString() : ''}`;
+      const result = await client.get(path);
+      const tracks = result.tracks || [];
+      if (tracks.length === 0) {
+        return { content: [{ type: 'text', text: 'No tracks returned.' }] };
+      }
+      return { content: [{ type: 'text', text: `Catalog (${tracks.length} track${tracks.length === 1 ? '' : 's'}):\n\n${tracks.map(trackLine).join('\n\n')}` }] };
+    }
+  );
+
+  // ─── get_music_library_facets ─────────────────────────────────
+  server.tool(
+    'get_music_library_facets',
+    'List the distinct genres, moods, and instruments available in the music library, plus the BPM and duration ranges. Use these values to build precise search_music_library filters.',
+    {},
+    async () => {
+      const result = await client.get('/v1/music-library/facets');
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            genres: result.genres || [],
+            moods: result.moods || [],
+            instruments: result.instruments || [],
+            bpmRange: result.bpmRange || null,
+            durationRange: result.durationRange || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_music_track_audio ────────────────────────────────────
+  server.tool(
+    'get_music_track_audio',
+    'Get the downloadable audio URLs (128 kbps / 320 kbps / WAV) for a single music-library track by id. Call this after the user picks a track from search_music_library or browse_music_library.',
+    {
+      track_id: z.string().describe('The track id returned by search_music_library / browse_music_library.')
+    },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/audio`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ id: result.id, urls: result.urls }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_music_track_related ──────────────────────────────────
+  server.tool(
+    'get_music_track_related',
+    'Get the stems and alternate versions of a music-library master track by id (e.g. instrumental, 30s cut, looped).',
+    {
+      track_id: z.string().describe('The master track id.')
+    },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/related`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ stems: result.stems || [], versions: result.versions || [] }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_music_track_lyrics ───────────────────────────────────
+  server.tool(
+    'get_music_track_lyrics',
+    'Get the lyrics text, lyrical theme, and explicit flag for a single music-library track by id.',
+    {
+      track_id: z.string().describe('The track id.')
+    },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/lyrics`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            hasLyrics: result.hasLyrics,
+            lyrics: result.lyrics,
+            lyricalTheme: result.lyricalTheme,
+            explicit: result.explicit
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerMusicLibraryTools };

package/src/tools/stock_library.js

@@ -0,0 +1,143 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg. Full rules: ../index.js top-of-file. */
+
+const { z } = require('zod');
+
+// Compact one-line render of a normalized stock asset.
+function assetLine(a) {
+  const dims = a.width && a.height ? `${a.width}x${a.height}` : null;
+  const dur = a.durationSeconds != null ? `${Math.round(a.durationSeconds)}s` : null;
+  const meta = [a.mediaType, dims, dur].filter(Boolean).join(' · ');
+  const by = a.author?.name ? ` by ${a.author.name}` : '';
+  const variants = Array.isArray(a.downloadVariants) ? a.downloadVariants.map((v) => v.label).join('/') : '';
+  return `[${a.source}:${a.sourceId}] ${a.title || '(untitled)'}${by}\n   ${meta}${variants ? `  variants: ${variants}` : ''}${a.thumbnailUrl ? `\n   thumb: ${a.thumbnailUrl}` : ''}`;
+}
+
+// Returns the raw querystring (no leading '?'). Callers inline it as
+// `${q ? '?' + q : ''}` so the parity checker recognizes it as a querystring.
+function buildQuery(obj) {
+  const p = new URLSearchParams();
+  for (const [k, v] of Object.entries(obj)) if (v != null && v !== '') p.set(k, String(v));
+  return p.toString();
+}
+
+function registerStockLibraryTools(server, client) {
+  // ─── search_stock_media ───────────────────────────────────────
+  server.tool(
+    'search_stock_media',
+    'Search the Kolbo unified stock media library and return matching assets. 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.'),
+      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 the Artlist groups (transitions/ambience/foley/genre/realistic).'),
+      subcategory: z.string().optional().describe('Kolbo SFX sub-filter within a group (providerParam from get_stock_categories, e.g. "risers", "footsteps", "scary-textures").'),
+      packId: z.string().optional().describe('Filter to one Kolbo themed pack id (from get_stock_collections, kind="pack").'),
+      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).'),
+      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).')
+    },
+    async (args) => {
+      const q = buildQuery(args);
+      const result = await client.get(`/v1/stock/search${q ? '?' + q : ''}`);
+      const assets = result.assets || [];
+      if (!assets.length) return { content: [{ type: 'text', text: 'No assets found. Try a broader query, a different source/mediaType, or call get_stock_sources.' }] };
+      const head = `Found ${assets.length} asset${assets.length === 1 ? '' : 's'}${result.total ? ` (≈${result.total} total)` : ''}${result.hasMore ? ' — more available (increment page)' : ''}:`;
+      return { content: [{ type: 'text', text: `${head}\n\n${assets.map(assetLine).join('\n\n')}\n\nUse [source:sourceId] with get_stock_asset for full variants, or import_stock_asset to copy it into the media library.` }] };
+    }
+  );
+
+  // ─── get_stock_sources ────────────────────────────────────────
+  server.tool(
+    'get_stock_sources',
+    'List the enabled stock providers and which media types + filters each supports. Call this to know whether a source supports image/video/illustration/vector/3d/music before searching.',
+    {},
+    async () => {
+      const result = await client.get('/v1/stock/sources');
+      return { content: [{ type: 'text', text: JSON.stringify({ mediaTypes: result.mediaTypes, sources: result.sources }, null, 2) }] };
+    }
+  );
+
+  // ─── get_stock_categories ─────────────────────────────────────
+  server.tool(
+    '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 Artlist groups (top-level, group=null) AND their 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.'),
+      mediaType: z.string().optional().describe('Restrict to one media type (e.g. "image", "video", "3d", "sfx").')
+    },
+    async (args) => {
+      const q = buildQuery(args);
+      const result = await client.get(`/v1/stock/categories${q ? '?' + q : ''}`);
+      return { content: [{ type: 'text', text: JSON.stringify({ count: result.count, categories: result.categories }, null, 2) }] };
+    }
+  );
+
+  // ─── get_stock_collections ────────────────────────────────────
+  server.tool(
+    'get_stock_collections',
+    'List Kolbo\'s own SFX collections — the category collections AND the curated themed packs (kind="pack": e.g. Trailer Hits, Horror & Tension, Gaming FX, Foley Essentials). Use the returned `id` as `packId` or `collectionId` in search_stock_media to browse one pack/collection. Each has a cover image.',
+    {
+      mediaType: z.string().optional().describe('Media type (default "sfx").'),
+      kind: z.enum(['category', 'pack']).optional().describe('Filter to category collections or themed packs only.')
+    },
+    async (args) => {
+      const q = buildQuery(args);
+      const result = await client.get(`/v1/stock/collections${q ? '?' + q : ''}`);
+      return { content: [{ type: 'text', text: JSON.stringify({ count: result.count, collections: result.collections }, null, 2) }] };
+    }
+  );
+
+  // ─── get_stock_asset ──────────────────────────────────────────
+  server.tool(
+    '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.'),
+      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.')
+    },
+    async ({ source, id, mediaType }) => {
+      const q = buildQuery({ mediaType });
+      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) }] };
+    }
+  );
+
+  // ─── analyze_script_for_stock ─────────────────────────────────
+  server.tool(
+    'analyze_script_for_stock',
+    'AI helper that turns a video/voiceover script into stock b-roll search terms. Returns { queries[], mediaType, keywords } you can feed into search_stock_media to auto-source matching footage/photos. Use this first when the user gives you a script rather than explicit search keywords.',
+    {
+      script: z.string().min(1).describe('The video/voiceover script or scene description to analyze (up to ~8000 chars).')
+    },
+    async ({ script }) => {
+      const result = await client.post('/v1/stock/analyze-script', { script });
+      return { content: [{ type: 'text', text: JSON.stringify({ queries: result.queries, mediaType: result.mediaType, keywords: result.keywords, _followup_hint: 'Run each query through search_stock_media (source="all", mediaType=result.mediaType).' }, null, 2) }] };
+    }
+  );
+
+  // ─── import_stock_asset ───────────────────────────────────────
+  server.tool(
+    '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. Returns the created media library item. Works for Kolbo SFX (source='kolbo-ai', mediaType='sfx') and external visual/audio sources. Licensed Music (source='music') is not importable here (use the music-library tools).",
+    {
+      source: z.enum(['kolbo-ai', 'pexels', 'pixabay', '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.'),
+      project_id: z.string().optional().describe('Optional project id to associate the imported item with.')
+    },
+    async (args) => {
+      const result = await client.post('/v1/stock/import', args);
+      const it = result.libraryItem || {};
+      return { content: [{ type: 'text', text: `${result.alreadyImported ? 'Already in library' : 'Imported'}: ${it.url || '(no url)'}\n${JSON.stringify({ id: it._id, mediaType: it.mediaType, filename: it.filename, url: it.url }, null, 2)}` }] };
+    }
+  );
+}
+
+module.exports = { registerStockLibraryTools };