@kolbo/mcp 1.5.5 → 1.6.5

package/README.md

@@ -65,6 +65,8 @@ Just ask Claude naturally:
 
 Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
 
+Every generation tool also accepts an optional `resolution` arg. Images use `"1K"` (~1024px) / `"2K"` (Full HD) / `"3K"` (QHD) / `"4K"` (UHD); videos use vertical-pixel tiers like `"720p"` / `"1080p"` / `"1440p"` / `"2160p"`. Values are model-dependent — call `list_models` and read the chosen model's `supported_resolutions` and `resolutionMultipliers`. Omit to use the model default.
+
 **Chat & Vision**
 | Tool | Description |
 |------|-------------|

package/package.json

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

package/src/index.js

@@ -66,6 +66,7 @@ const { registerVisualDnaTools } = require('./tools/visual_dna');
 const { registerMoodboardTools } = require('./tools/moodboards');
 const { registerMediaTools } = require('./tools/media');
 const { registerPresetTools } = require('./tools/presets');
+const { registerAppBuilderTools } = require('./tools/app_builder');
 
 async function main() {
   const client = new KolboClient();
@@ -83,6 +84,7 @@ async function main() {
   registerMoodboardTools(server, client);
   registerMediaTools(server, client);
   registerPresetTools(server, client);
+  registerAppBuilderTools(server, client);
 
   // Start the server with stdio transport
   const transport = new StdioServerTransport();

package/src/tools/app_builder.js

@@ -0,0 +1,254 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const { z } = require('zod');
+const { PollingTimeoutError } = require('../polling');
+
+// ─── Build-status polling (App Builder uses a different endpoint than /v1/generate) ──
+async function pollBuildStatus(client, sessionId, options = {}) {
+  const {
+    interval = 5000,
+    timeout = 300000 // 5 minutes
+  } = options;
+
+  const startTime = Date.now();
+  const url = `/app-builder/${encodeURIComponent(sessionId)}/build-status`;
+
+  while (true) {
+    if (Date.now() - startTime > timeout) {
+      throw new PollingTimeoutError(sessionId, timeout);
+    }
+
+    const result = await client.get(url);
+
+    if (result.buildStatus === 'deployed') {
+      return result;
+    }
+
+    if (result.buildStatus === 'failed') {
+      throw new Error(
+        `App build failed for session_id="${sessionId}". ` +
+        `Call app_builder_get_build_status to check the current state.`
+      );
+    }
+
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+}
+
+function registerAppBuilderTools(server, client) {
+  // ─── app_builder_list_projects ─────────────────────────────────────────────
+  server.tool(
+    'app_builder_list_projects',
+    'List all Kolbo projects for the authenticated user. Use this to find the project_id required by app_builder_create_session and app_builder_list_sessions. Projects are the top-level containers — each project can hold multiple App Builder sessions.',
+    {},
+    async () => {
+      const res = await client.get('/project/lightweight');
+      const projects = (Array.isArray(res) ? res : (res.data || [])).map(p => ({
+        project_id: p._id,
+        name: p.name,
+        description: p.description || '',
+        created_at: p.createdAt
+      }));
+      return {
+        content: [{ type: 'text', text: JSON.stringify(projects, null, 2) }]
+      };
+    }
+  );
+
+  // ─── app_builder_create_session ────────────────────────────────────────────
+  server.tool(
+    'app_builder_create_session',
+    'Create a new App Builder session inside a Kolbo project. Returns a session_id to pass to app_builder_generate_app. Sessions hold the full app state across multiple generations and edits.',
+    {
+      project_id: z.string().describe('Kolbo project ID to scope this session. Use app_builder_list_projects to find your project_id.'),
+      name: z.string().optional().describe('Optional initial session name. The backend will auto-generate a name on first generation if omitted.')
+    },
+    async ({ project_id, name }) => {
+      const body = name ? { name } : {};
+      const res = await client.post(`/app-builder/session/${encodeURIComponent(project_id)}`, body);
+      const session = res.data || res;
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session_id: session._id,
+            name: session.name,
+            build_status: session.buildStatus,
+            deployment_url: session.deploymentUrl || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── app_builder_generate_app ──────────────────────────────────────────────
+  server.tool(
+    'app_builder_generate_app',
+    'Generate a React app from a text prompt inside an App Builder session. On the FIRST call the backend auto-generates a punchy app name, URL slug, GitHub repo, and (if needed) a Supabase database. The build runs in the background — this tool polls until the app is deployed (up to 5 minutes) then returns the live deployment_url. Always show the user the deployment_url when done.',
+    {
+      session_id: z.string().describe('Session ID from app_builder_create_session.'),
+      prompt: z.string().describe('Natural language description of the app to build (e.g. "a todo app with drag-and-drop and Supabase persistence").')
+    },
+    async ({ session_id, prompt }) => {
+      await client.post(`/app-builder/generation/${encodeURIComponent(session_id)}`, { userPrompt: prompt });
+      const status = await pollBuildStatus(client, session_id);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session_id,
+            build_status: status.buildStatus,
+            deployment_url: status.deploymentUrl || null,
+            app_name: status.appName || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── app_builder_edit_app ──────────────────────────────────────────────────
+  server.tool(
+    'app_builder_edit_app',
+    'Edit an existing generated app with a natural language instruction — "add a dark mode toggle", "change the color scheme to blue", "add a contact form". Like app_builder_generate_app but for modifications. Use app_builder_list_generations to get the current generation_id before calling this.',
+    {
+      session_id: z.string().describe('Session ID of the app to edit.'),
+      generation_id: z.string().describe('The generation to edit. Use app_builder_list_generations to find the latest generation_id.'),
+      edit_prompt: z.string().describe('Natural language instruction describing the change to make.')
+    },
+    async ({ session_id, generation_id, edit_prompt }) => {
+      await client.request(
+        'PUT',
+        `/app-builder/generation/${encodeURIComponent(session_id)}/${encodeURIComponent(generation_id)}`,
+        { editPrompt: edit_prompt }
+      );
+      const status = await pollBuildStatus(client, session_id);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session_id,
+            build_status: status.buildStatus,
+            deployment_url: status.deploymentUrl || null,
+            app_name: status.appName || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── app_builder_get_build_status ──────────────────────────────────────────
+  server.tool(
+    'app_builder_get_build_status',
+    'Check the current build status of an App Builder session. Use this to manually poll after app_builder_generate_app or app_builder_edit_app, or to check on an app at any time. Returns "deployed" when the live URL is ready.',
+    {
+      session_id: z.string().describe('Session ID to check.')
+    },
+    async ({ session_id }) => {
+      const result = await client.get(`/app-builder/${encodeURIComponent(session_id)}/build-status`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            build_status: result.buildStatus,
+            deployment_url: result.deploymentUrl || null,
+            deployed_at: result.deployedAt || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── app_builder_get_session ───────────────────────────────────────────────
+  server.tool(
+    'app_builder_get_session',
+    'Get full details of an App Builder session including metadata, build status, deployment URL, and GitHub/Supabase integration info. Use this when the user wants to clone the app locally — it returns the GitHub repo URL and Supabase connection details needed for local development.',
+    {
+      session_id: z.string().describe('Session ID to retrieve.')
+    },
+    async ({ session_id }) => {
+      const res = await client.get(`/app-builder/session/${encodeURIComponent(session_id)}`);
+      const session = res.data || res;
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session_id: session._id,
+            name: session.name,
+            build_status: session.buildStatus,
+            deployment_url: session.deploymentUrl || null,
+            github_repo_url: session.githubRepoUrl || null,
+            supabase_url: session.supabaseUrl || null,
+            supabase_anon_key: session.supabaseAnonKey || null,
+            created_at: session.createdAt
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── app_builder_list_sessions ─────────────────────────────────────────────
+  server.tool(
+    'app_builder_list_sessions',
+    'List all App Builder sessions in a project. Use this to find existing sessions before creating a new one, or to pick a session_id to continue working on.',
+    {
+      project_id: z.string().describe('Kolbo project ID. Use app_builder_list_projects to find it.')
+    },
+    async ({ project_id }) => {
+      const res = await client.get(`/app-builder/sessions/${encodeURIComponent(project_id)}`);
+      const sessions = (Array.isArray(res) ? res : (res.data || [])).map(s => ({
+        session_id: s._id,
+        name: s.name,
+        build_status: s.buildStatus,
+        deployment_url: s.deploymentUrl || null,
+        created_at: s.createdAt
+      }));
+      return {
+        content: [{ type: 'text', text: JSON.stringify(sessions, null, 2) }]
+      };
+    }
+  );
+
+  // ─── app_builder_list_generations ──────────────────────────────────────────
+  server.tool(
+    'app_builder_list_generations',
+    'List all generations for an App Builder session, newest first. Use this to find the current generation_id before calling app_builder_edit_app.',
+    {
+      session_id: z.string().describe('Session ID to list generations for.')
+    },
+    async ({ session_id }) => {
+      const res = await client.get(`/app-builder/generations/${encodeURIComponent(session_id)}`);
+      const generations = (Array.isArray(res) ? res : (res.data || [])).map(g => ({
+        generation_id: g._id,
+        user_prompt: g.userPrompt || g.editPrompt || '',
+        build_status: g.buildStatus,
+        created_at: g.createdAt
+      }));
+      return {
+        content: [{ type: 'text', text: JSON.stringify(generations, null, 2) }]
+      };
+    }
+  );
+
+  // ─── app_builder_delete_session ────────────────────────────────────────────
+  server.tool(
+    'app_builder_delete_session',
+    'Permanently delete an App Builder session and ALL associated resources: GitHub repo, Supabase database (unless user-connected), deployed files, generation history, messages, and form submissions. THIS IS IRREVERSIBLE — always confirm with the user before calling.',
+    {
+      session_id: z.string().describe('Session ID to permanently delete. This cannot be undone.')
+    },
+    async ({ session_id }) => {
+      await client.delete(`/app-builder/session/${encodeURIComponent(session_id)}`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ success: true }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerAppBuilderTools };

package/src/tools/generate.js

@@ -15,19 +15,21 @@ function registerGenerateTools(server, client) {
     'Generate image(s) from a text prompt using Kolbo AI. Supports Visual DNA profiles (for character/style/product consistency), moodboards (for style direction), reference images (for composition guidance), batch generation (num_images), and web-search grounding. For EDITING an existing image, use generate_image_edit instead. For a coordinated multi-scene set (storyboard, ad campaign), use generate_creative_director. Returns the final image URL(s) when complete.',
     {
       prompt: z.string().describe('Text description of the image to generate'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="image" to see options. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_img" to see options. Omit for Smart Select.'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: true'),
       num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1'),
       reference_images: z.array(z.string()).optional().describe('Array of image URLs used as composition/style references (NOT as source images for editing — use generate_image_edit for that).'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs (from create_visual_dna / list_visual_dnas) to apply for character / style / product / scene consistency. Pass the `id` field of each profile. Use this when the user wants to keep the same character or style across multiple images.'),
       moodboard_id: z.string().optional().describe('Moodboard ID (from list_moodboards / get_moodboard) whose master_prompt and style_guide should be applied to this generation.'),
-      enable_web_search: z.boolean().optional().describe('Enable web-search grounding for the prompt (useful for current events, brand references, real-world accuracy). Default: false')
+      enable_web_search: z.boolean().optional().describe('Enable web-search grounding for the prompt (useful for current events, brand references, real-world accuracy). Default: false'),
+      resolution: z.string().optional().describe('Image resolution tier: "1K" (~1024px), "2K" (Full HD), "3K" (QHD), or "4K" (UHD). Model-dependent — call list_models and read supported_resolutions on the chosen model. Read resolutionMultipliers on the same model to predict credit cost. Omit to use the model default.'),
+      preset_id: z.string().optional().describe('Preset ID from list_presets type="image" to apply a saved style preset to this generation.')
     },
-    async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search }) => {
+    async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id }) => {
       const gen = await client.post('/v1/generate/image', {
         prompt, model, aspect_ratio, enhance_prompt, num_images,
-        reference_images, visual_dna_ids, moodboard_id, enable_web_search
+        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -54,19 +56,20 @@ function registerGenerateTools(server, client) {
     'Edit or transform an existing image using AI. Provide the source image URL(s) in `source_images` and describe the edit in `prompt` (e.g., "remove the background", "change the car color to red", "add sunglasses to the person"). Supports Visual DNA profiles and moodboards for style-consistent edits. For creating a brand new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
     {
       prompt: z.string().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="image_edit" to see options. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="image_editing" to see options. Omit for Smart Select.'),
       source_images: z.array(z.string()).describe('Array of source image URLs to edit. Typically one, but some models accept multiple for compositing.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: true'),
       num_images: z.number().optional().describe('Number of output images. Default: 1'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for consistency with an existing character / style / product.'),
       moodboard_id: z.string().optional().describe('Moodboard ID whose master_prompt and style_guide should be applied.'),
-      enable_web_search: z.boolean().optional().describe('Enable web-search grounding. Default: false')
+      enable_web_search: z.boolean().optional().describe('Enable web-search grounding. Default: false'),
+      resolution: z.string().optional().describe('Image resolution tier: "1K" / "2K" / "3K" / "4K". Model-dependent — call list_models and read supported_resolutions. Default: "1K" for most edit models.')
     },
-    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt, num_images, visual_dna_ids, moodboard_id, enable_web_search }) => {
+    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution }) => {
       const gen = await client.post('/v1/generate/image-edit', {
         prompt, model, source_images, aspect_ratio, enhance_prompt, num_images,
-        visual_dna_ids, moodboard_id, enable_web_search
+        visual_dna_ids, moodboard_id, enable_web_search, resolution
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -102,12 +105,13 @@ function registerGenerateTools(server, client) {
       reference_images: z.array(z.string()).optional().describe('Array of reference image URLs to guide style/composition of every scene.'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply consistently across every scene. 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.'),
-      moodboard_ids: z.array(z.string()).optional().describe('Multiple moodboard IDs when blending styles. Prefer `moodboard_id` for single moodboards.')
+      moodboard_ids: z.array(z.string()).optional().describe('Multiple moodboard IDs when blending styles. Prefer `moodboard_id` for single moodboards.'),
+      resolution: z.string().optional().describe('Resolution tier applied to every scene. Images: "1K" / "2K" / "3K" / "4K". Videos: "720p" / "1080p" / "1440p" / "2160p". Values are model-dependent — call list_models and read supported_resolutions on the target model. Multiplied across every scene.')
     },
-    async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids }) => {
+    async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution }) => {
       const gen = await client.post('/v1/generate/creative-director', {
         prompt, scene_count, model, aspect_ratio, workflow_type, duration,
-        enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids
+        enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -144,16 +148,18 @@ function registerGenerateTools(server, client) {
     'Generate a video from a text prompt using Kolbo AI. For animating an existing still image into motion, use generate_video_from_image instead. For a coordinated multi-scene video campaign, use generate_creative_director with workflow_type="video". Supports Visual DNA profiles (for character consistency) and reference images (for style guidance). Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Text description of the video to generate'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="video" to see options. Check supported_durations and supported_aspect_ratios.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_video" to see options. Check supported_durations and supported_aspect_ratios.'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"'),
       duration: z.number().optional().describe('Duration in seconds. Must be a value the chosen model supports — check supported_durations from list_models. Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
       reference_images: z.array(z.string()).optional().describe('Array of image URLs used as visual references (style / composition / subject).'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to keep a character / style consistent with prior generations.')
+      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to keep a character / style consistent with prior generations.'),
+      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Some models use labels like "512P"/"1024P"/"768P"/"1080P". Model-dependent — call list_models and read supported_resolutions. Read resolutionMultipliers to predict cost.'),
+      preset_id: z.string().optional().describe('Preset ID from list_presets type="video" to apply a saved motion/style preset to this generation.')
     },
-    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, visual_dna_ids }) => {
+    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, visual_dna_ids, resolution, preset_id }) => {
       const gen = await client.post('/v1/generate/video', {
-        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, visual_dna_ids
+        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, visual_dna_ids, resolution, preset_id
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -183,15 +189,16 @@ function registerGenerateTools(server, client) {
     {
       image_url: z.string().describe('URL of the source image to animate'),
       prompt: z.string().describe('Text description of the desired MOTION (e.g., "camera slowly pans right while the character walks forward")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="video_from_image" to see options.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="img_to_video" to see options.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"'),
       duration: z.number().optional().describe('Duration in seconds. Must be a value the chosen model supports. Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the motion prompt. Default: true'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to maintain consistency with prior characters / styles.')
+      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to maintain consistency with prior characters / styles.'),
+      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Some models use labels like "512P"/"1024P"/"768P"/"1080P". Model-dependent — call list_models and read supported_resolutions. Read resolutionMultipliers to predict cost.')
     },
-    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids }) => {
+    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution }) => {
       const gen = await client.post('/v1/generate/video/from-image', {
-        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids
+        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -219,16 +226,17 @@ function registerGenerateTools(server, client) {
     'Generate music from a text description using Kolbo AI. Supports instrumental mode, custom lyrics, style direction, and vocal gender. Default model is Suno. Returns the final audio URL when complete.',
     {
       prompt: z.string().describe('Text description of the music to generate (e.g., "upbeat electronic dance track with synthesizers")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="music" to see options. Omit for Suno (default).'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="music_gen" to see options. Omit for Suno (default).'),
       style: z.string().optional().describe('Music style / genre (e.g., "pop", "rock", "lo-fi", "electronic", "jazz")'),
       instrumental: z.boolean().optional().describe('Generate instrumental only, no vocals. Default: false'),
       lyrics: z.string().optional().describe('Custom lyrics for the song. If omitted, lyrics are generated automatically from the prompt unless instrumental is true.'),
       vocal_gender: z.string().optional().describe('Preferred vocal gender: "male" or "female". Only applies when instrumental is false.'),
-      enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true')
+      enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
+      preset_id: z.string().optional().describe('Preset ID from list_presets type="music" to apply a saved music style preset.')
     },
-    async ({ prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt }) => {
+    async ({ prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt, preset_id }) => {
       const gen = await client.post('/v1/generate/music', {
-        prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt
+        prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt, preset_id
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -257,7 +265,7 @@ function registerGenerateTools(server, client) {
     {
       text: z.string().describe('The text to convert to speech'),
       voice: z.string().optional().describe('Voice ID (from list_voices) or voice display name (e.g., "Rachel", "Adam"). Default: "Rachel"'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="speech" to see options. Default: eleven_v3'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_speech" to see options. Default: eleven_v3'),
       language: z.string().optional().describe('Language code (e.g., "en-US", "he-IL", "es-ES"). Default: "en-US"')
     },
     async ({ text, voice, model, language }) => {
@@ -289,12 +297,13 @@ function registerGenerateTools(server, client) {
     'Generate sound effects (not music, not speech) from a text description using Kolbo AI. Use this for ambient sounds, foley, impacts, atmospheres, UI sounds, etc. For music use generate_music; for voice use generate_speech. Returns the final audio URL when complete.',
     {
       prompt: z.string().describe('Text description of the sound effect (e.g., "thunder clap with rain", "door creaking open", "futuristic UI beep")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="sound" to see options. Default: elevenlabs-sound-effects-v1'),
-      duration: z.number().optional().describe('Duration in seconds. Omit for automatic duration.')
+      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_sound" to see options. Default: elevenlabs-sound-effects-v1'),
+      duration: z.number().optional().describe('Duration in seconds. Omit for automatic duration.'),
+      prompt_influence: z.number().optional().describe('How strongly the prompt guides the generation (0–1). Default: 0.5. Lower values give the model more creative freedom; higher values follow the prompt more literally.')
     },
-    async ({ prompt, model, duration }) => {
+    async ({ prompt, model, duration, prompt_influence }) => {
       const gen = await client.post('/v1/generate/sound', {
-        prompt, model, duration
+        prompt, model, duration, prompt_influence
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -377,20 +386,23 @@ function registerGenerateTools(server, client) {
   // ─── generate_elements ─────────────────────────────────────
   server.tool(
     'generate_elements',
-    'Generate a video from reference elements (images and/or videos) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". Supports Visual DNA for character consistency. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
+    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elementsMaxImages / elementsMaxVideos / elementsMaxAudio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Text description of the desired video / animation'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="video" to see options. Omit for Smart Select.'),
-      reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). URL mode.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="elements" to see options (Seedance 2, Kling O3 Reference, Grok Imagine, Veo 3.1, etc.). Check elementsMaxImages / elementsMaxVideos / elementsMaxAudio on the model. Omit for Smart Select.'),
+      reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). Check elementsMaxImages on the chosen model — pass at most that many URLs.'),
+      reference_videos: z.array(z.string()).optional().describe('Array of reference video URLs for models that accept video inputs (elementsMaxVideos > 0). Check elementsMaxVideos on the chosen model from list_models before passing.'),
+      audio_url: z.string().optional().describe('URL of a reference audio track for models that accept audio inputs (elementsMaxAudio > 0). Check elementsMaxAudio on the chosen model from list_models before passing.'),
       files: z.array(z.string()).optional().describe('Array of URLs or absolute local paths — alternative to reference_images. Use this when you have local files to upload. Each item can be a URL OR a local path.'),
       duration: z.number().optional().describe('Duration in seconds. Default: 5'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"'),
       motion: z.string().optional().describe('Motion style / intensity hint (optional)'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="video" (optional)'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for character/style consistency across outputs.')
+      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for character/style consistency across outputs.'),
+      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.')
     },
-    async ({ prompt, model, reference_images, files, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids }) => {
+    async ({ prompt, model, reference_images, reference_videos, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution }) => {
       if (!prompt) throw new Error('prompt is required');
 
       let startResponse;
@@ -407,6 +419,9 @@ function registerGenerateTools(server, client) {
         if (enhance_prompt !== undefined) form.append('enhance_prompt', String(enhance_prompt));
         if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
         if (reference_images) form.append('reference_images', JSON.stringify(reference_images));
+        if (reference_videos) form.append('reference_videos', JSON.stringify(reference_videos));
+        if (audio_url) form.append('audio_url', audio_url);
+        if (resolution) form.append('resolution', resolution);
         for (const f of resolved) {
           form.append('files', f.buffer, { filename: f.filename, contentType: f.contentType });
         }
@@ -414,7 +429,7 @@ function registerGenerateTools(server, client) {
       } else {
         // URL-only mode: plain JSON.
         startResponse = await client.post('/v1/generate/elements', {
-          prompt, model, reference_images, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids
+          prompt, model, reference_images, reference_videos, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution
         });
       }
 
@@ -447,13 +462,14 @@ function registerGenerateTools(server, client) {
       first_frame: z.string().optional().describe('URL or absolute local path to the first frame (file mode — alternative to first_frame_url)'),
       last_frame: z.string().optional().describe('URL or absolute local path to the last frame (file mode — alternative to last_frame_url)'),
       prompt: z.string().optional().describe('Optional description of the desired motion between the two frames (e.g. "smooth camera dolly in")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="video_from_image" to see options. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="firstlastgenerations" to see options. Omit for Smart Select.'),
       duration: z.number().optional().describe('Duration in seconds. Default: 5'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (auto-detected from first frame if not provided). Default: "16:9"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply.')
+      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply.'),
+      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.')
     },
-    async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids }) => {
+    async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution }) => {
       const urlMode = first_frame_url && last_frame_url;
       const fileMode = first_frame && last_frame;
       if (!urlMode && !fileMode) {
@@ -478,10 +494,11 @@ function registerGenerateTools(server, client) {
         if (aspect_ratio) form.append('aspect_ratio', aspect_ratio);
         if (enhance_prompt !== undefined) form.append('enhance_prompt', String(enhance_prompt));
         if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
+        if (resolution) form.append('resolution', resolution);
         startResponse = await client.postMultipart('/v1/generate/first-last-frame', form);
       } else {
         startResponse = await client.post('/v1/generate/first-last-frame', {
-          first_frame_url, last_frame_url, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids
+          first_frame_url, last_frame_url, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution
         });
       }
 
@@ -512,7 +529,7 @@ function registerGenerateTools(server, client) {
       source: z.string().describe('URL or absolute local path to the source image or video (the face to animate)'),
       audio: z.string().describe('URL or absolute local path to the audio track (the voice to sync to)'),
       text_prompt: z.string().optional().describe('Optional text prompt (for performance-capable models)'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="lipsync" to see options. Omit for Smart Select.'),
+      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.')
     },
     async ({ source, audio, text_prompt, model, bounding_box_target }) => {
@@ -577,17 +594,21 @@ function registerGenerateTools(server, client) {
   // ─── 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 — anything where you want to keep the motion from the input video but change the look. Source video can be a URL or absolute local path. For animating a still image use generate_video_from_image instead. For text-only → video use generate_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 maxImages / maxVideos / maxElements on the chosen model before generating. Pass reference_images for models with maxImages > 0 (e.g. Kling O1/O3, Aleph, WAN VACE), reference_videos for models with maxVideos > 1 (e.g. WAN 2.6 reference-to-video accepts up to 3), and elements for models with maxElements > 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 source video to restyle'),
+      source_video: z.string().describe('URL or absolute local path to the primary source video to restyle. 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'),
-      model: z.string().optional().describe('Model identifier. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="video_to_video" to see options and check maxImages / maxVideos / maxElements per model. Omit for Smart Select.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio. Default: matches source'),
       duration: z.number().optional().describe('Duration in seconds (default: matches source)'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for character/style consistency.')
+      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for character/style consistency.'),
+      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.'),
+      reference_images: z.array(z.string()).optional().describe('Array of reference image URLs for models that support additional image inputs (maxImages > 0). Examples: character reference images for Kling O1/O3, style reference for Aleph/gen4_aleph, character image for WAN VACE video-edit. Check maxImages on the model from list_models before passing.'),
+      reference_videos: z.array(z.string()).optional().describe('Array of additional reference video URLs for models that support multiple video inputs (maxVideos > 1). Example: WAN 2.6 reference-to-video accepts 1–3 reference videos. Check maxVideos on the model from list_models before passing.'),
+      elements: z.array(z.string()).optional().describe('Array of element image URLs for models with maxElements > 0. Elements are used as style or character reference assets alongside the main video. Check maxElements on the model from list_models before passing.')
     },
-    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids }) => {
+    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, reference_images, reference_videos, elements }) => {
       if (!source_video) throw new Error('source_video is required');
       if (!prompt) throw new Error('prompt is required');
 
@@ -595,7 +616,8 @@ function registerGenerateTools(server, client) {
       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
+          video_url: source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution,
+          reference_images, reference_videos, elements
         });
       } else {
         const resolved = await resolveToBuffer(source_video, 'video');
@@ -607,6 +629,10 @@ function registerGenerateTools(server, client) {
         if (duration !== undefined) form.append('duration', String(duration));
         if (enhance_prompt !== undefined) form.append('enhance_prompt', String(enhance_prompt));
         if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
+        if (resolution) form.append('resolution', resolution);
+        if (reference_images) form.append('reference_images', JSON.stringify(reference_images));
+        if (reference_videos) form.append('reference_videos', JSON.stringify(reference_videos));
+        if (elements) form.append('elements', JSON.stringify(elements));
         startResponse = await client.postMultipart('/v1/generate/video-from-video', form);
       }
 
@@ -679,7 +705,7 @@ function registerGenerateTools(server, client) {
       reference_images: z.array(z.string()).optional().describe('Array of public image URLs. 1 image → single mode, 2+ → multi mode.'),
       mode: z.string().optional().describe('Explicitly set mode: "text" | "single" | "multi". Auto-detected from reference_images if omitted.'),
       texture_prompt: z.string().optional().describe('Optional prompt to guide texture generation'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="three_d" to see options.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="three_d" to see all 3D options, or filter by sub-type: "3d_text_to_model", "3d_image_to_model", "3d_multi_image_to_model", "3d_world".'),
       topology: z.string().optional().describe('Topology preset (optional, model-specific)'),
       target_polycount: z.number().optional().describe('Target polygon count (optional, model-specific)'),
       enable_tpose: z.boolean().optional().describe('Force T-pose for character models (optional)'),
@@ -720,6 +746,96 @@ function registerGenerateTools(server, client) {
       };
     }
   );
+  // ─── edit_image ────────────────────────────────────────────
+  server.tool(
+    'edit_image',
+    'Apply a targeted AI edit to an existing image. Use for upscaling resolution, changing aspect ratio (reframe), removing the background, portrait skin enhancement, or a text-guided edit (magic_edit). Faster and cheaper than generate_image_edit for these specific operations because it routes to specialized models. Returns the edited image URL when complete.',
+    {
+      image_url: z.string().describe('URL of the source image to edit'),
+      operation: z.enum(['upscale', 'reframe', 'removebg', 'enhance_skin', 'magic_edit'])
+        .describe('Edit operation to apply: "upscale" (increase resolution 2×–4×), "reframe" (change aspect ratio), "removebg" (remove background), "enhance_skin" (portrait retouching), "magic_edit" (text-guided edit — requires prompt)'),
+      model: z.string().optional().describe('Model identifier override. Omit to use the default model for the operation.'),
+      scale: z.number().optional().describe('Upscale factor: 2, 3, or 4. Only used when operation="upscale". Default: 2.'),
+      aspect_ratio: z.string().optional().describe('Target aspect ratio (e.g., "16:9", "9:16", "1:1"). Required for operation="reframe".'),
+      skin_strength: z.enum(['subtle', 'realistic', 'pimple', 'freckle']).optional()
+        .describe('Skin enhancement style. Only used when operation="enhance_skin". Default: "realistic".'),
+      prompt: z.string().optional().describe('Text instruction for the edit. Required for operation="magic_edit" (e.g., "add sunglasses", "change the sky to sunset").')
+    },
+    async ({ image_url, operation, model, scale, aspect_ratio, skin_strength, prompt }) => {
+      if (operation === 'magic_edit' && !prompt) throw new Error('prompt is required for magic_edit operation');
+      if (operation === 'reframe' && !aspect_ratio) throw new Error('aspect_ratio is required for reframe operation');
+
+      const gen = await client.post('/v1/edit/image', {
+        image_url, operation, model, scale, aspect_ratio, skin_strength, prompt
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 5) * 1000,
+        timeout: 180000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result?.urls || [],
+            edit_type: result.result?.edit_type || null,
+            model: result.result?.model || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── edit_video ────────────────────────────────────────────
+  server.tool(
+    'edit_video',
+    'Apply a targeted AI edit to an existing video. Operations: upscale (4K resolution boost), reframe (change aspect ratio), generate_audio (add AI-generated sound/music from a prompt), remove_watermark, face_swap (replace faces using a reference image URL), extend (lengthen at start or end), magic_edit (restyle/transform with a prompt), lipsync (sync an audio track to a face in the video). Returns the edited video URL when complete.',
+    {
+      video_url: z.string().describe('URL of the source video to edit'),
+      operation: z.enum(['upscale', 'reframe', 'generate_audio', 'remove_watermark', 'face_swap', 'extend', 'magic_edit', 'lipsync'])
+        .describe('Edit operation: "upscale", "reframe" (requires aspect_ratio), "generate_audio" (requires prompt), "remove_watermark", "face_swap" (requires image_url), "extend" (requires duration), "magic_edit" (requires prompt), "lipsync" (requires audio_url)'),
+      model: z.string().optional().describe('Model identifier override. Omit to use the default model for the operation.'),
+      aspect_ratio: z.string().optional().describe('Target aspect ratio (e.g., "16:9", "9:16"). Required for operation="reframe".'),
+      scale: z.number().optional().describe('Upscale factor. Only used when operation="upscale".'),
+      prompt: z.string().optional().describe('Text prompt. Required for operation="magic_edit" and "generate_audio". Optional hint for "extend".'),
+      image_url: z.string().optional().describe('URL of the reference face image. Required for operation="face_swap".'),
+      audio_url: z.string().optional().describe('URL of the audio track to sync. Required for operation="lipsync".'),
+      duration: z.number().optional().describe('Seconds of video to generate. Required for operation="extend". Typical range: 1–20.'),
+      mode: z.string().optional().describe('Where to extend: "start" or "end". Only used when operation="extend". Default: "end".')
+    },
+    async ({ video_url, operation, model, aspect_ratio, scale, prompt, image_url, audio_url, duration, mode }) => {
+      if (operation === 'magic_edit' && !prompt) throw new Error('prompt is required for magic_edit');
+      if (operation === 'generate_audio' && !prompt) throw new Error('prompt is required for generate_audio');
+      if (operation === 'reframe' && !aspect_ratio) throw new Error('aspect_ratio is required for reframe');
+      if (operation === 'face_swap' && !image_url) throw new Error('image_url (reference face) is required for face_swap');
+      if (operation === 'lipsync' && !audio_url) throw new Error('audio_url is required for lipsync');
+      if (operation === 'extend' && !duration) throw new Error('duration is required for extend');
+
+      const gen = await client.post('/v1/edit/video', {
+        video_url, operation, model, aspect_ratio, scale, prompt,
+        image_url, audio_url, duration, mode
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 8) * 1000,
+        timeout: 600000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result?.urls || [],
+            download_url: result.result?.download_url || null,
+            edit_type: result.result?.edit_type || null,
+            duration: result.result?.duration || null,
+            model: result.result?.model || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
 }
 
 module.exports = { registerGenerateTools };

package/src/tools/models.js

@@ -11,7 +11,7 @@ function registerModelTools(server, client) {
     'list_models',
     'List available AI models on Kolbo. Filter by type to find models for a specific generation type.',
     {
-      type: z.string().optional().describe('Filter by type: "image", "image_edit", "video", "video_from_image", "video_from_video", "music", "speech", "sound", "chat", "lipsync", "three_d", "elements", "first_last_frame", "transcription". Omit for all models.')
+      type: z.string().optional().describe('Filter by DB type name: "text_to_img", "image_editing", "text_to_video", "img_to_video", "draw_to_video", "video_to_video", "elements", "firstlastgenerations", "lipsync-image", "lipsync-video", "music_gen", "text_to_speech", "text_to_sound", "stt", "text". Legacy aliases also accepted: "image", "image_edit", "video", "video_from_image", "video_from_video", "music", "speech", "sound", "chat", "lipsync" (both lipsync types), "three_d" (all 3D types), "first_last_frame", "transcription". Omit for all models.')
     },
     async ({ type }) => {
       const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';