@kolbo/mcp 1.22.4 → 1.26.0

package/README.md

@@ -120,10 +120,10 @@ Without the optional skill, the config block alone already exposes every tool
 | `generate_image_edit` | Existing image(s) + prompt → edited image |
 | `generate_video` | Text → video |
 | `generate_video_from_image` | Still image + motion prompt → video |
-| `generate_video_from_video` | Input video + prompt → restyled video (video-to-video) |
+| `generate_video_from_video` | Input video → restyled video, or burn in subtitles (video-to-video). `prompt` optional — prompt-less models (VEED Subtitles, Act Two, Wan Animate) use `preset` / `source_language` / `translation_language`, plus `srt_content` / `srt_file_url` / `vocabulary` / `customization` for VEED |
 | `generate_elements` | Reference images/videos + prompt → animated video |
 | `generate_first_last_frame` | First frame + last frame → interpolated video |
-| `generate_lipsync` | Source image/video + audio → lipsynced video |
+| `generate_lipsync` | Source image/video + audio → lipsynced video (Sync-3 adds active-speaker selection, emotion, model mode, temperature) |
 | `generate_creative_director` | One brief → N coordinated scenes (image or video) |
 | `generate_music` | Text (+ optional lyrics) → song |
 | `generate_speech` | Text + voice → spoken audio |
@@ -190,6 +190,17 @@ 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. |
+
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.22.4",
+  "version": "1.26.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` |
@@ -81,7 +82,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
 | `generate_elements` | Reference-driven video. **Primary route for DNA → video.** |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
-| `generate_lipsync` | Lipsync audio to an image or video face. |
+| `generate_lipsync` | Lipsync audio to an image or video face. Sync-3 adds multi-person speaker selection (`active_speaker_detection`), `emotion`, `model_mode`, `temperature`. |
 | `generate_music` | Music generation (Suno + variants). |
 | `generate_speech` | TTS. Use `list_voices` to pick a voice. |
 | `generate_sound` | Sound effects. |
@@ -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

@@ -69,6 +69,8 @@ const { registerPresetTools } = require('./tools/presets');
 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');
 
 /**
  * Build a fully-configured Kolbo MCP server (all tool groups registered)
@@ -95,6 +97,7 @@ function createServer(opts = {}) {
   // keep identical text-URL output.
   registerGenerateTools(server, client, { inlineImages: !!opts.inlineImages });
   registerModelTools(server, client);
+  registerVoiceTools(server, client);
   registerChatTools(server, client);
   registerVisualDnaTools(server, client);
   registerMoodboardTools(server, client);
@@ -103,6 +106,7 @@ function createServer(opts = {}) {
   registerAppBuilderTools(server, client);
   registerArtifactTools(server, client);
   registerProjectTools(server, client);
+  registerMusicLibraryTools(server, client);
 
   return server;
 }

package/src/tools/generate.js

@@ -357,43 +357,6 @@ function registerGenerateTools(server, client, options = {}) {
     }
   );
 
-  // ─── list_voices ─────────────────────────────────────────────
-  server.tool(
-    'list_voices',
-    'List available TTS voices for generate_speech. Returns preset voices and the user\'s own cloned/designed voices. Filter by provider, language, or gender to find the right voice. Use the returned `voice_id` as the `voice` parameter in generate_speech.',
-    {
-      provider: z.string().optional().describe('Filter by provider (e.g., "elevenLabs", "google")'),
-      language: z.string().optional().describe('Filter by language name or code (e.g., "English", "en-US")'),
-      gender: z.string().optional().describe('Filter by gender (e.g., "Female", "Male")')
-    },
-    async ({ provider, language, gender }) => {
-      const params = new URLSearchParams();
-      if (provider) params.set('provider', provider);
-      if (language) params.set('language', language);
-      if (gender) params.set('gender', gender);
-
-      const qs = params.toString();
-      const result = await client.get(`/v1/voices${qs ? '?' + qs : ''}`);
-
-      // Summarize for context window efficiency
-      const voices = (result.voices || []).map(v => ({
-        voice_id: v.voice_id,
-        name: v.name,
-        provider: v.provider,
-        language: v.language,
-        gender: v.gender,
-        custom: v.custom
-      }));
-
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({ voices, count: result.count }, null, 2)
-        }]
-      };
-    }
-  );
-
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
@@ -568,12 +531,27 @@ function registerGenerateTools(server, client, options = {}) {
     {
       source: z.string().describe('URL or absolute local path to the source image or video (the face to animate). For lipsync-video: duration must fall within `min_video_duration`-`max_video_duration` from list_models.'),
       audio: z.string().describe('URL or absolute local path to the audio track (the voice to sync to). Duration must fall within `min_audio_duration`-`max_audio_duration` from list_models; format must be in `supported_audio_formats` (when set).'),
-      text_prompt: z.string().optional().describe('Optional text prompt (for performance-capable models)'),
+      text_prompt: z.string().optional().describe('Optional text prompt (for performance-capable models). For Sync-3 this is the free-text emotion/acting prompt, e.g. "speaking with excitement, calm and serious".'),
       model: z.string().optional().describe('Model identifier. Use list_models type="lipsync-image" or type="lipsync-video" to see options. Omit for Smart Select.'),
       bounding_box_target: z.array(z.number()).optional().describe('Optional bounding box [x, y, w, h] for multi-face inputs (Hedra Character3 style). Leave empty for single-face.'),
+      // Sync-3 (fal-ai/sync-lipsync/v3) only; ignored by other models.
+      sync_mode: z.enum(['cut_off', 'loop', 'bounce', 'silence', 'remap']).optional().describe('Sync-3 / sync-lipsync family: how to reconcile an audio/video length mismatch. Default cut_off.'),
+      model_mode: z.enum(['lips', 'face', 'head', 'lipsync', 'emotion', 'talking_head']).optional().describe('Sync-3 only: which region drives the sync.'),
+      emotion: z.enum(['neutral', 'happy', 'sad', 'angry', 'disgusted', 'surprised']).optional().describe('Sync-3 only: quick emotion shortcut. A free-text text_prompt overrides this and gives finer control.'),
+      temperature: z.number().min(0).max(1).optional().describe('Sync-3 only: expressiveness 0 (subtle) .. 1 (energetic).'),
+      occlusion_detection_enabled: z.boolean().optional().describe('Sync-3 only: handle objects passing in front of the face.'),
+      active_speaker_detection: z.object({
+        auto_detect: z.boolean().optional().describe('Auto-detect and sync the active speaker.'),
+        v3: z.boolean().optional().describe('Use Sync.so v3 detection engine.'),
+        frame_number: z.number().int().min(0).optional().describe('Frame index the coordinates refer to.'),
+        coordinates: z.array(z.number().int()).length(2).optional().describe('[x, y] PIXEL point on the speaker face (source-video resolution).'),
+        bounding_boxes: z.array(z.array(z.number().int())).optional().describe('Per-frame face boxes [x1,y1,x2,y2].'),
+        bounding_boxes_url: z.string().optional().describe('URL to a JSON file with per-frame boxes.'),
+        face_image: z.string().optional().describe('Base64-encoded reference face image.')
+      }).optional().describe('Sync-3 only: choose which speaker gets synced in a multi-person video. Use auto_detect:true for automatic, or coordinates + frame_number to pin a specific face.'),
       project_id: projectIdField
     },
-    async ({ source, audio, text_prompt, model, bounding_box_target, project_id }) => {
+    async ({ source, audio, text_prompt, model, bounding_box_target, sync_mode, model_mode, emotion, temperature, occlusion_detection_enabled, active_speaker_detection, project_id }) => {
       if (!source) throw new Error('source is required (URL or absolute local path to image/video)');
       if (!audio) throw new Error('audio is required (URL or absolute local path to audio file)');
 
@@ -589,6 +567,13 @@ function registerGenerateTools(server, client, options = {}) {
           prompt: text_prompt,
           model,
           bounding_box_target,
+          // Sync-3 advanced options (additive; ignored by other models)
+          sync_mode,
+          model_mode,
+          emotion,
+          temperature,
+          occlusion_detection_enabled,
+          active_speaker_detection,
           project_id
         });
       } else {
@@ -611,6 +596,13 @@ function registerGenerateTools(server, client, options = {}) {
         if (text_prompt) form.append('prompt', text_prompt);
         if (model) form.append('model', model);
         if (bounding_box_target) form.append('bounding_box_target', JSON.stringify(bounding_box_target));
+        // Sync-3 advanced options (additive — ignored by other models)
+        if (sync_mode) form.append('sync_mode', sync_mode);
+        if (model_mode) form.append('model_mode', model_mode);
+        if (emotion) form.append('emotion', emotion);
+        if (temperature !== undefined) form.append('temperature', String(temperature));
+        if (occlusion_detection_enabled !== undefined) form.append('occlusion_detection_enabled', String(occlusion_detection_enabled));
+        if (active_speaker_detection) form.append('active_speaker_detection', JSON.stringify(active_speaker_detection));
         if (project_id) form.append('project_id', project_id);
         startResponse = await client.postMultipart('/v1/generate/lipsync', form);
       }
@@ -638,10 +630,10 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_video_from_video ─────────────────────────────
   server.tool(
     'generate_video_from_video',
-    'Restyle / transform an existing video using a text prompt (video-to-video). Use for style transfer, scene restyling, subject swap, motion transfer, or character replacement. Source video can be a URL or absolute local path. IMPORTANT: different models support different extra inputs — call list_models type="video_to_video" and read max_images / max_videos / max_elements on the chosen model before generating. Pass reference_images for models with max_images > 0 (e.g. Kling O1/O3, Aleph, WAN VACE), reference_videos for models with max_videos > 1 (e.g. WAN 2.6 reference-to-video accepts up to 3), and elements for models with max_elements > 0. For animating a still image use generate_video_from_image instead. For text-only → video use generate_video.',
+    'Restyle / transform an existing video (video-to-video). Use for style transfer, scene restyling, subject swap, motion transfer, character replacement, or burning in styled subtitles (VEED Subtitles). Source video can be a URL or absolute local path. `prompt` is OPTIONAL: most models need it, but prompt-less models (VEED Subtitles, Act Two, Wan Animate, Kling Motion Control) ignore it. For VEED Subtitles, pass a `preset` style and optional `source_language` / `translation_language` instead of a prompt. IMPORTANT: different models support different extra inputs — call list_models type="video_to_video" and read max_images / max_videos / max_elements on the chosen model before generating. Pass reference_images for models with max_images > 0 (e.g. Kling O1/O3, Aleph, WAN VACE), reference_videos for models with max_videos > 1 (e.g. WAN 2.6 reference-to-video accepts up to 3), and elements for models with max_elements > 0. For animating a still image use generate_video_from_image instead. For text-only → video use generate_video.',
     {
       source_video: z.string().describe('URL or absolute local path to the primary source video to restyle. **Source duration must fall within `min_video_duration`-`max_video_duration` from list_models for the chosen model** — videos outside that range are rejected (or silently truncated by some upstream providers). For models that use reference_videos as their primary input (e.g. WAN 2.6 reference-to-video), pass the first reference video here and also include it in reference_videos.'),
-      prompt: z.string().describe('Text description of the desired restyle / transformation'),
+      prompt: z.string().optional().describe('Text description of the desired restyle / transformation. Required by most video-to-video models; omit for prompt-less models (VEED Subtitles, Act Two, Wan Animate, Kling Motion Control).'),
       model: z.string().optional().describe('Model identifier. Use list_models type="video_to_video" to see options and check max_images / max_videos / max_elements / max_video_duration per model. Omit for Smart Select.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio. Must be in `supported_aspect_ratios` from list_models when set. Default: matches source'),
       duration: z.number().optional().describe('Output duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: matches source'),
@@ -651,24 +643,49 @@ function registerGenerateTools(server, client, options = {}) {
       reference_images: z.array(z.string()).optional().describe('Array of reference image URLs for models that support additional image inputs. **Cap: pass at most `max_images` URLs from list_models — if `max_images === 0` the model does not accept image refs.** Examples: character reference images for Kling O1/O3, style reference for Aleph/gen4_aleph, character image for WAN VACE video-edit.'),
       reference_videos: z.array(z.string()).optional().describe('Array of additional reference video URLs for models that support multiple video inputs. **Cap: pass at most `max_videos` URLs from list_models — if `max_videos <= 1` only the source_video is accepted.** Example: WAN 2.6 reference-to-video accepts 1–3 reference videos.'),
       elements: z.array(z.string()).optional().describe('Array of element image URLs. **Cap: pass at most `max_elements` URLs from list_models — if `max_elements === 0` the model does not accept elements.** Elements are style or character reference assets alongside the main video.'),
+      // VEED Subtitles (model: veed/subtitles) — burns styled subtitles into the video
+      preset: z.string().optional().describe('VEED Subtitles only: caption style preset (e.g. "glass", "whisper", "fusion", "simple", "vegas"). Call list_models type="video_to_video" for the veed/subtitles model. Ignored by other models.'),
+      source_language: z.string().optional().describe('VEED Subtitles only: BCP-47 code of the spoken language to improve transcription accuracy (e.g. "en-US", "es-ES", "he-IL"). Omit to auto-detect.'),
+      translation_language: z.string().optional().describe('VEED Subtitles only: BCP-47 code to translate the subtitles into (e.g. "en-US", "fr-FR"). Omit to keep the original spoken language.'),
+      srt_content: z.string().optional().describe('VEED Subtitles only: raw .srt subtitle text to burn in. When set, auto-transcription is skipped.'),
+      srt_file_url: z.string().optional().describe('VEED Subtitles only: URL to a .srt subtitle file. Alternative to srt_content. When set, auto-transcription is skipped.'),
+      vocabulary: z.array(z.object({
+        word: z.string().describe('Correct spelling to enforce'),
+        replaces: z.array(z.string()).describe('Mis-transcriptions to replace with `word`'),
+      })).optional().describe('VEED Subtitles only: brand names / jargon to help transcription (e.g. [{"word":"Kolbo","replaces":["colbo","kolboo"]}]). Ignored when srt_content / srt_file_url is set.'),
+      customization: z.object({
+        position: z.enum(['top', 'center', 'bottom']).optional().describe('Caption vertical position. Ignored by complex animated presets.'),
+        shadow: z.enum(['none', 'min', 'mid', 'max']).optional().describe('Text shadow intensity.'),
+        text_customizations: z.object({
+          baseline: z.object({ font: z.string().optional(), weight: z.number().int().min(100).max(900).optional(), color: z.string().optional() }).optional().describe('All words: Google font name, weight 100-900, hex colour.'),
+          highlighted: z.object({ font: z.string().optional(), weight: z.number().int().min(100).max(900).optional(), color: z.string().optional() }).optional().describe('Highlighted word tier styling.'),
+        }).optional(),
+      }).optional().describe('VEED Subtitles only: style overrides. Any omitted field keeps the preset default. Best supported by Basic presets.'),
       project_id: projectIdField
     },
-    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, reference_images, reference_videos, elements, project_id }) => {
+    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, reference_images, reference_videos, elements, preset, source_language, translation_language, srt_content, srt_file_url, vocabulary, customization, project_id }) => {
       if (!source_video) throw new Error('source_video is required');
-      if (!prompt) throw new Error('prompt is required');
 
       const isUrl = /^https?:\/\//i.test(source_video);
       let startResponse;
       if (isUrl) {
         startResponse = await client.post('/v1/generate/video-from-video', {
           video_url: source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution,
-          reference_images, reference_videos, elements, project_id
+          reference_images, reference_videos, elements, preset, source_language, translation_language,
+          srt_content, srt_file_url, vocabulary, customization, project_id
         });
       } else {
         const resolved = await resolveToBuffer(source_video, 'video');
         const form = new FormData();
         form.append('files', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
-        form.append('prompt', prompt);
+        if (prompt) form.append('prompt', prompt);
+        if (preset) form.append('preset', preset);
+        if (source_language) form.append('source_language', source_language);
+        if (translation_language) form.append('translation_language', translation_language);
+        if (srt_content) form.append('srt_content', srt_content);
+        if (srt_file_url) form.append('srt_file_url', srt_file_url);
+        if (vocabulary) form.append('vocabulary', JSON.stringify(vocabulary));
+        if (customization) form.append('customization', JSON.stringify(customization));
         if (model) form.append('model', model);
         if (aspect_ratio) form.append('aspect_ratio', aspect_ratio);
         if (duration !== undefined) form.append('duration', String(duration));

package/src/tools/models.js

@@ -158,6 +158,31 @@ function registerModelTools(server, client) {
           parts.push(`images_per_request: ${m.images_per_request}`);
         }
 
+        // Quality tiers (image models that support quality selection)
+        if (Array.isArray(m.supported_qualities) && m.supported_qualities.length) {
+          const qMult = m.quality_multipliers || {};
+          const qParts = m.supported_qualities.map(q =>
+            qMult[q] && qMult[q] !== 1 ? `${q}(${qMult[q]}×)` : q
+          );
+          parts.push(`quality: ${qParts.join(' · ')}${m.default_quality ? ` (default ${m.default_quality})` : ''}`);
+        }
+
+        // Fixed-price override (some models charge a flat rate per resolution instead of per-second)
+        if (m.flat_credit_by_resolution && typeof m.flat_credit_by_resolution === 'object' && Object.keys(m.flat_credit_by_resolution).length) {
+          const fp = Object.entries(m.flat_credit_by_resolution).map(([k, v]) => `${k}:${v}cr`).join(' · ');
+          parts.push(`flat_price: ${fp}`);
+        }
+
+        // Estimated generation time (wall-clock at base settings)
+        if (m.estimated_duration_seconds != null) {
+          parts.push(`est_time: ~${m.estimated_duration_seconds}s`);
+        }
+
+        // NSFW flag
+        if (m.nsfw_only) {
+          parts.push('nsfw: required');
+        }
+
         return parts.length ? `\n   ${parts.join(' | ')}` : '';
       };
 

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/voices.js

@@ -0,0 +1,49 @@
+/* ⛔ 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');
+
+function registerVoiceTools(server, client) {
+  // ─── list_voices ──────────────────────────────────────────────
+  server.tool(
+    'list_voices',
+    'List available TTS voices for speech generation. Filter by language, gender, or provider to find the right voice. Returns voice_id, name, provider, language, gender, accent, description, styles, and preview_url for each voice.',
+    {
+      language: z.string().optional().describe('Filter by language name (e.g. "english", "hebrew", "spanish", "french"). Case-insensitive partial match.'),
+      gender: z.enum(['male', 'female']).optional().describe('Filter by gender.'),
+      provider: z.string().optional().describe('Filter by provider (e.g. "elevenlabs", "google"). Omit for all providers.')
+    },
+    async ({ language, gender, provider }) => {
+      const params = new URLSearchParams();
+      if (language) params.set('language', language);
+      if (gender) params.set('gender', gender);
+      if (provider) params.set('provider', provider);
+
+      const path = `/v1/voices${params.toString() ? '?' + params.toString() : ''}`;
+      const result = await client.get(path);
+
+      const voices = result.voices || [];
+      if (voices.length === 0) {
+        return {
+          content: [{ type: 'text', text: 'No voices found matching those filters.' }]
+        };
+      }
+
+      const lines = voices.map(v => {
+        const tags = [v.language, v.gender, v.accent].filter(Boolean).join(' · ');
+        const styles = Array.isArray(v.styles) && v.styles.length ? ` | styles: ${v.styles.join(', ')}` : '';
+        const v3 = v.v3_optimized ? ' [v3]' : '';
+        return `${v.voice_id} — ${v.name} (${v.provider})${v3}\n   ${tags}${styles}${v.description ? `\n   ${v.description}` : ''}`;
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Available voices (${voices.length}):\n\n${lines.join('\n\n')}\n\nUse the "voice_id" value in generate_speech calls.`
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerVoiceTools };