@kolbo/mcp 1.6.8 → 1.12.0

package/README.md

@@ -43,7 +43,7 @@ Just ask Claude naturally:
 - *"What's in this image?"*
 - *"Create a Visual DNA profile called 'Alex' from these images"*
 
-## Available Tools (30)
+## Available Tools (51)
 
 **Generation**
 | Tool | Description |
@@ -92,7 +92,28 @@ Every generation tool also accepts an optional `resolution` arg. Images use `"1K
 | Tool | Description |
 |------|-------------|
 | `upload_media` | Upload a local file (or remote URL) → stable Kolbo CDN URL for reuse |
-| `list_media` | Browse your uploaded media with type filter and pagination |
+| `list_media` | Browse media library — filter by `project_id`, `folder_id`, `type`, `category` (ai / uploaded / edited / favorites / training-lab), `source_type`, `sort`, `search`, pagination |
+| `list_media_folders` | List the user's media folders (owned + shared) — discover `folder_id` values to pass to `list_media` |
+| `create_media_folder` | Create a new folder (name, optional description / color / icon) |
+| `update_media_folder` | Rename / recolor / re-icon a folder (owner only) |
+| `delete_media_folder` | Soft-delete a folder (owner only; items remain in library) |
+| `add_media_to_folder` | Add up to 500 media items to a folder (idempotent) |
+| `remove_media_from_folder` | Remove media items from a folder |
+| `share_media_folder` | Share a folder by user email (owner only) |
+| `unshare_media_folder` | Revoke a user's access to a folder (owner only) |
+| `favorite_media` | Mark a media item as favorited (idempotent) — pass `media_id` from `list_media` |
+| `unfavorite_media` | Remove a media item from favorites (idempotent) — pass `media_id` from `list_media` |
+| `get_media` | Fetch one media item's full details by id |
+| `delete_media` | Soft-delete a media item (30-day trash) |
+| `restore_media` | Restore a trashed item |
+| `permanently_delete_media` | Hard-delete (NOT reversible — confirm with user first) |
+| `move_media` | Re-assign a media item to a different project |
+| `bulk_delete_media` | Soft-delete up to 1000 items in one call |
+| `bulk_restore_media` | Restore up to 1000 trashed items |
+| `bulk_permanently_delete_media` | Hard-delete up to 1000 (NOT reversible) |
+| `bulk_move_media` | Move up to 1000 items to a project (atomic — all-or-nothing) |
+| `move_folder_contents` | Move every item in a folder to a project |
+| `get_media_stats` | Counts + storage bytes per type (optionally per project) |
 
 **Discovery & Account**
 | Tool | Description |

package/package.json

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

package/src/client.js

@@ -151,10 +151,12 @@ class KolboClient {
     this.apiKey = this._envKey || this._readAuthStore();
 
     if (!this.apiKey) {
+      // No key in env OR auth store. The Kolbo Code parent process should
+      // never spawn us in this state (it injects the key into env after the
+      // user signs in). If this fires, the parent will catch it via the
+      // [KOLBO_AUTH_MISSING] tag and surface the in-app sign-in flow.
       throw new Error(
-        'Kolbo API key not found.\n' +
-        'Fix: Run "kolbo auth login" in the terminal, then restart this editor.\n' +
-        'Or: Get an API key at https://app.kolbo.ai/developer and set KOLBO_API_KEY env var.'
+        'Kolbo API key not found. Sign in to Kolbo to continue. [KOLBO_AUTH_MISSING]'
       );
     }
   }
@@ -198,12 +200,21 @@ class KolboClient {
 
   async _doRequest(method, reqPath, body = null) {
     const url = `${this.baseUrl}${reqPath}`;
+    const headers = {
+      'X-API-Key': this.apiKey,
+      'Content-Type': 'application/json'
+    };
+    // Stable per-app-launch identifier from the parent process (Kolbo Code
+    // sets this in the MCP env when spawning us). kolbo-api tags every
+    // CreditUsage record with it so the desktop UI and the get_session_usage
+    // tool can aggregate spend without enumerating individual generations.
+    const callerSessionId = process.env.KOLBO_CALLER_SESSION_ID;
+    if (callerSessionId) {
+      headers['X-Kolbo-Caller-Session-Id'] = callerSessionId;
+    }
     const options = {
       method,
-      headers: {
-        'X-API-Key': this.apiKey,
-        'Content-Type': 'application/json'
-      }
+      headers,
     };
 
     if (body) {
@@ -226,9 +237,15 @@ class KolboClient {
       const code = data.code || null;
       let fullMessage = code ? `${message} [${code}]` : message;
       if (response.status === 401) {
-        // Tag the response so the retry logic in request() can see it
+        // Tag the response so the retry logic in request() can see it AND so
+        // the Kolbo Code parent process can intercept this error before the
+        // agent sees it — trigger the in-app reconnect flow, refresh the key,
+        // and transparently retry the tool call. Never instruct the user to
+        // open a terminal: most users run Kolbo Code as a desktop / web app
+        // and have no terminal context.
         data._status = 401;
-        fullMessage += '\n\nAPI key is invalid or expired. Fix: run "kolbo auth login" in the terminal, then restart this editor. Or get a new key at https://app.kolbo.ai/developer';
+        data._kolbo_auth_expired = true;
+        fullMessage = `${fullMessage} [KOLBO_AUTH_EXPIRED]`;
       }
       throw new KolboApiError(fullMessage, {
         code,
@@ -252,8 +269,12 @@ class KolboClient {
     return this.request('PUT', reqPath, body);
   }
 
-  async delete(reqPath) {
-    return this.request('DELETE', reqPath);
+  async patch(reqPath, body = null) {
+    return this.request('PATCH', reqPath, body);
+  }
+
+  async delete(reqPath, body = null) {
+    return this.request('DELETE', reqPath, body);
   }
 
   async postMultipart(reqPath, formData) {
@@ -270,6 +291,11 @@ class KolboClient {
       'X-API-Key': this.apiKey,
       ...formData.getHeaders()
     };
+    // Same caller-session header as JSON requests — see _doRequest.
+    const callerSessionId = process.env.KOLBO_CALLER_SESSION_ID;
+    if (callerSessionId) {
+      headers['X-Kolbo-Caller-Session-Id'] = callerSessionId;
+    }
 
     // Serialize form-data to a Buffer before passing to fetch(). Node's
     // built-in fetch (undici) can't consume legacy Node.js streams from
@@ -298,8 +324,12 @@ class KolboClient {
       const code = data.code || null;
       let fullMessage = code ? `${message} [${code}]` : message;
       if (response.status === 401) {
+        // Multipart uploads: same auth-expired contract as _doRequest. The
+        // Kolbo Code parent process intercepts [KOLBO_AUTH_EXPIRED] and runs
+        // the in-app reconnect flow — no terminal command needed.
         data._status = 401;
-        fullMessage += '\n\nAPI key is invalid or expired. Fix: run "kolbo auth login" in the terminal, then restart this editor. Or get a new key at https://app.kolbo.ai/developer';
+        data._kolbo_auth_expired = true;
+        fullMessage = `${fullMessage} [KOLBO_AUTH_EXPIRED]`;
       }
       throw new KolboApiError(fullMessage, {
         code,

package/src/index.js

@@ -67,6 +67,7 @@ const { registerMoodboardTools } = require('./tools/moodboards');
 const { registerMediaTools } = require('./tools/media');
 const { registerPresetTools } = require('./tools/presets');
 const { registerAppBuilderTools } = require('./tools/app_builder');
+const { registerArtifactTools } = require('./tools/artifacts');
 
 async function main() {
   const client = new KolboClient();
@@ -85,6 +86,7 @@ async function main() {
   registerMediaTools(server, client);
   registerPresetTools(server, client);
   registerAppBuilderTools(server, client);
+  registerArtifactTools(server, client);
 
   // Start the server with stdio transport
   const transport = new StdioServerTransport();

package/src/tools/_shared.js

@@ -200,6 +200,36 @@ async function resolveToBuffer(source, kind, opts = {}) {
   };
 }
 
+/**
+ * Extract real, multiplier-adjusted credit cost from a polled getStatus
+ * response. kolbo-api returns `credits_used` (final number deducted) and
+ * `credits_breakdown` (per-CreditUsage detail) when the generation is
+ * complete. Returns `{}` when the API didn't include them so spreading
+ * the result into a tool's response object is a no-op (forward-compatible
+ * with old kolbo-api versions).
+ *
+ * Usage in every generation tool:
+ *   return {
+ *     content: [{ type: 'text', text: JSON.stringify({
+ *       urls: result.result.urls,
+ *       model: result.result.model,
+ *       ...creditFields(result),   // adds credits_used + credits_breakdown
+ *       _followup_hint: '...',
+ *     }, null, 2) }]
+ *   };
+ */
+function creditFields(polledResult) {
+  if (!polledResult) return {};
+  const out = {};
+  if (typeof polledResult.credits_used === 'number') {
+    out.credits_used = polledResult.credits_used;
+  }
+  if (Array.isArray(polledResult.credits_breakdown) && polledResult.credits_breakdown.length) {
+    out.credits_breakdown = polledResult.credits_breakdown;
+  }
+  return out;
+}
+
 module.exports = {
   MAX_FILE_BYTES,
   VISUAL_DNA_MAX_BYTES,
@@ -208,5 +238,6 @@ module.exports = {
   safeFetch,
   guessFilename,
   guessContentType,
-  resolveToBuffer
+  resolveToBuffer,
+  creditFields,
 };

package/src/tools/artifacts.js

@@ -0,0 +1,60 @@
+/* ⛔ 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');
+
+function registerArtifactTools(server, client) {
+  // ─── publish_html_artifact ─────────────────────────────────────
+  server.tool(
+    'publish_html_artifact',
+    'Publish an HTML page (or SVG / Mermaid diagram) to kolbo.ai and return a public shareable URL. Use this when the user explicitly asks to share, publish, or deploy a built artifact so they can send the URL to someone. The content is hosted at https://sites.kolbo.ai/<slug>; the page is served with restrictive CSP (no fetch/XHR/form-action) so it cannot exfiltrate data. Identical content uploaded twice returns the same URL (server dedup).',
+    {
+      title: z.string().describe('Human-friendly title for the page (also used to generate the SEO slug). Keep under ~60 chars.'),
+      content: z.string().describe('The raw artifact body. For type="html" this is a full HTML document (DOCTYPE + html/head/body). For "svg" it is an <svg> document. For "mermaid" it is the Mermaid source text.'),
+      type: z.enum(['html', 'svg', 'mermaid']).optional().describe('Artifact type. Default: "html".'),
+      allow_js: z.boolean().optional().describe('Allow inline <script> execution on the published page. Default: false. Required for Tailwind JIT, Chart.js, Three.js, React-from-CDN etc.'),
+    },
+    async ({ title, content, type, allow_js }) => {
+      if (!title || !title.trim()) throw new Error('title is required');
+      if (typeof content !== 'string' || !content.length) throw new Error('content is required');
+
+      const result = await client.post('/artifact/quick-share', {
+        title: title.trim(),
+        content,
+        type: type || 'html',
+        allowJs: allow_js === true,
+      });
+
+      const artifact = result?.data || {};
+      const slug = artifact.shareableSlug || artifact.shareToken;
+      // Compose env-correct URL. sites.kolbo.ai only resolves in prod; for
+      // dev/staging we serve straight from the kolbo-api host.
+      const apiBase = client.baseUrl || 'https://api.kolbo.ai/api';
+      const isProd = /(^|\/\/)api\.kolbo\.ai/i.test(apiBase);
+      let url;
+      if (isProd) {
+        url = artifact.siteUrl || (slug ? `https://sites.kolbo.ai/${slug}` : null);
+      }
+      if (!url && artifact.shareToken) {
+        url = `${apiBase}/shared-artifact-raw/${artifact.shareToken}`;
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            url,
+            shareToken: artifact.shareToken,
+            shareableSlug: slug,
+            duplicate: result?.duplicate === true,
+            title: artifact.title,
+          }),
+        }],
+      };
+    },
+  );
+}
+
+module.exports = { registerArtifactTools };

package/src/tools/chat.js

@@ -5,6 +5,7 @@
 
 const { z } = require('zod');
 const { pollUntilDone } = require('../polling');
+const { creditFields } = require('./_shared');
 
 function registerChatTools(server, client) {
   // ─── chat_send_message ─────────────────────────────────────
@@ -49,6 +50,7 @@ function registerChatTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             session_id: gen.session_id,
             message_id: gen.message_id,
             model: r.model || gen.model,

package/src/tools/generate.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer } = require('./_shared');
+const { resolveToBuffer, creditFields } = require('./_shared');
 
 function registerGenerateTools(server, client) {
   // ─── generate_image ────────────────────────────────────────
@@ -16,11 +16,11 @@ function registerGenerateTools(server, client) {
     {
       prompt: z.string().describe('Text description of the image to generate'),
       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"'),
+      aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "1:1", "16:9", "9:16"). Must be a value present in the model\'s `supported_aspect_ratios` from list_models — pass an unsupported value and the API rejects. 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('STYLE/COMPOSITION inspiration only — does NOT embed reference pixels. Array of image URLs used to guide the look-and-feel of a brand-new generation. The model interprets the references and regenerates approximations conditioned on them. It will NOT copy pixels from these images into the output. To embed a specific logo, icon, watermark, or asset pixel-accurately, use generate_image_edit with the asset in source_images. To EDIT an existing image, also use generate_image_edit.'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Visual DNA profile IDs (from create_visual_dna / list_visual_dnas) for character / style / product / scene consistency. How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (this is by design — the description carries the identity signal, independent of enhance_prompt). Practical implication: do NOT also write physical descriptors of the same subject in your own prompt — they will compete with the DNA description text. For pixel-accurate face anchoring of a specific person, prefer passing the DNA\'s reference image directly via source_images on generate_image_edit and OMIT visual_dna_ids. visual_dna_ids is best for style / scene / product DNAs and for soft consistency across a set.'),
+      num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1. Note: some models (Midjourney etc.) have a fixed `images_per_request` and ignore this — check list_models.'),
+      reference_images: z.array(z.string()).optional().describe('STYLE/COMPOSITION inspiration only — does NOT embed reference pixels. Array of image URLs used to guide the look-and-feel of a brand-new generation. The model interprets the references and regenerates approximations conditioned on them. It will NOT copy pixels from these images into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** To embed a specific logo, icon, watermark, or asset pixel-accurately, use generate_image_edit with the asset in source_images. To EDIT an existing image, also use generate_image_edit.'),
+      visual_dna_ids: z.array(z.string()).optional().describe('Visual DNA profile IDs (from create_visual_dna / list_visual_dnas) for character / style / product / scene consistency. **Cap: pass at most `max_visual_dna` IDs from list_models — if the field is null/0 or `supports_visual_dna: false`, the model rejects DNA entirely (silently ignored in some paths).** How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (by design — independent of enhance_prompt). Practical implication: do NOT also write physical descriptors of the same subject in your own prompt — they will compete with the DNA description text. For pixel-accurate face anchoring of a specific person, prefer passing the DNA\'s reference image directly via source_images on generate_image_edit and OMIT visual_dna_ids. visual_dna_ids is best for style / scene / product DNAs and for soft consistency across a set.'),
       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'),
       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 resolution_multipliers on the same model to predict credit cost. Omit to use the model default.'),
@@ -41,6 +41,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             prompt_used: result.result.prompt_used,
@@ -58,11 +59,11 @@ function registerGenerateTools(server, client) {
     {
       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_editing" to see options. Omit for Smart Select.'),
-      source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image"). Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
-      aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"'),
+      source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image") or use @image1/@image2 tags. Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
+      aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. 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('Visual DNA profile IDs for character / style / product consistency. How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (by design — independent of enhance_prompt). For pixel-accurate face anchoring of a specific person on this tool, the PREFERRED pattern is to pass the face photo directly via source_images and OMIT visual_dna_ids — that way the face pixels anchor the output and no description text competes. Do NOT pass visual_dna_ids if source_images already contains the same person\'s face (face averaging). visual_dna_ids is best here for style / product DNAs.'),
+      visual_dna_ids: z.array(z.string()).optional().describe('Visual DNA profile IDs for character / style / product consistency. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model.** How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (by design — independent of enhance_prompt). For pixel-accurate face anchoring of a specific person on this tool, the PREFERRED pattern is to pass the face photo directly via source_images and OMIT visual_dna_ids — that way the face pixels anchor the output and no description text competes. Do NOT pass visual_dna_ids if source_images already contains the same person\'s face (face averaging). visual_dna_ids is best here for style / product DNAs.'),
       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'),
       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.')
@@ -86,6 +87,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             prompt_used: result.result.prompt_used,
@@ -104,12 +106,12 @@ function registerGenerateTools(server, client) {
       prompt: z.string().describe('Creative brief or concept describing the full set of scenes to generate'),
       scene_count: z.number().optional().describe('Number of scenes/images to generate, 1–8. Default: 4. Use this — NOT num_images — to control how many outputs are created.'),
       model: z.string().optional().describe('Model identifier applied to every scene. Omit for Smart Select.'),
-      aspect_ratio: z.string().optional().describe('Aspect ratio applied to every scene (e.g., "1:1", "16:9", "9:16"). Default: "1:1"'),
+      aspect_ratio: z.string().optional().describe('Aspect ratio applied to every scene (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       workflow_type: z.string().optional().describe('"image" (default) or "video"'),
-      duration: z.number().optional().describe('Duration in seconds per scene (video mode only). E.g., 5 or 10.'),
+      duration: z.number().optional().describe('Duration in seconds per scene (video mode only). Must be a value in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. E.g., 5 or 10.'),
       enhance_prompt: z.boolean().optional().describe('Enhance prompts per scene. Default: true'),
-      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.'),
+      reference_images: z.array(z.string()).optional().describe('Array of reference image URLs to guide style/composition of every scene. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model.**'),
+      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply consistently across every scene. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model.** This is the ideal way to keep a character or product looking the same in all scenes of a campaign.'),
       moodboard_id: z.string().optional().describe('A single moodboard ID whose master_prompt and style_guide should shape every scene.'),
       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.')
@@ -139,6 +141,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             scenes,
             total_scenes: result.scenes?.length || 0,
             completed_scenes: scenes.length,
@@ -160,10 +163,10 @@ function registerGenerateTools(server, client) {
     {
       prompt: z.string().describe('Text description of the video to generate'),
       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'),
+      aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "16:9"'),
+      duration: z.number().optional().describe('Duration in seconds. Must be a value in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration` (whichever the model exposes). 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).'),
+      reference_images: z.array(z.string()).optional().describe('Array of image URLs used as visual references (style / composition / subject). **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
       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 resolution_multipliers 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.')
     },
@@ -181,6 +184,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
@@ -201,10 +205,10 @@ 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="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'),
+      aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "16:9"'),
+      duration: z.number().optional().describe('Duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. 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. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false` the model ignores DNA entirely.**'),
       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 resolution_multipliers to predict cost.')
     },
     async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution }) => {
@@ -221,6 +225,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
@@ -260,6 +265,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             title: result.result.title,
             duration: result.result.duration,
@@ -294,6 +300,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             voice: result.result.voice,
             duration: result.result.duration
@@ -327,6 +334,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             duration: result.result.duration
           }, null, 2)
@@ -402,16 +410,16 @@ function registerGenerateTools(server, client) {
     {
       prompt: z.string().describe('Text description of the desired video / animation'),
       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 elements_max_images / elements_max_videos / elements_max_audio 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 elements_max_images 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 (elements_max_videos > 0). Check elements_max_videos 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 (elements_max_audio > 0). Check elements_max_audio 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"'),
+      reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). **Cap: pass at most `elements_max_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
+      reference_videos: z.array(z.string()).optional().describe('Array of reference video URLs for models that accept video inputs. **Cap: pass at most `elements_max_videos` URLs from list_models — if the cap is 0 the model rejects videos.**'),
+      audio_url: z.string().optional().describe('URL of a reference audio track. **Audio constraints: `elements_max_audio` from list_models gates whether audio is accepted at all; audio duration must fall within `min_audio_duration`-`max_audio_duration`; format must be in `supported_audio_formats` (if specified).**'),
+      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. **Total count across files + reference_images still capped by `elements_max_images`.**'),
+      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: 5'),
+      aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in `supported_aspect_ratios` from list_models. 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. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model.**'),
       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, reference_videos, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution }) => {
@@ -454,6 +462,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -475,10 +484,10 @@ function registerGenerateTools(server, client) {
       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="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"'),
+      duration: z.number().optional().describe('Duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: 5'),
+      aspect_ratio: z.string().optional().describe('Aspect ratio (auto-detected from first frame if not provided). Must be in `supported_aspect_ratios` from list_models when set. 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. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false`, DNA is silently ignored.**'),
       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, resolution }) => {
@@ -523,6 +532,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -536,10 +546,10 @@ function registerGenerateTools(server, client) {
   // ─── generate_lipsync ──────────────────────────────────────
   server.tool(
     'generate_lipsync',
-    'Lipsync an audio track to a source image or video. Both `source` (image or video) and `audio` can be provided as URLs or as absolute local file paths. Pass a text_prompt only if the model supports it (some lipsync models do character performance from a prompt). Returns a lipsynced video URL.',
+    'Lipsync an audio track to a source image or video. Both `source` (image or video) and `audio` can be provided as URLs or as absolute local file paths. Pass a text_prompt only if the model supports it (some lipsync models do character performance from a prompt). **Validate before submitting: for `lipsync-video` sources, the input video duration must fall within `min_video_duration`-`max_video_duration` from list_models; audio duration must fall within `min_audio_duration`-`max_audio_duration` (and if `audio_max_follows_video_duration: true`, audio is also capped at the video duration); audio format must be in `supported_audio_formats` when specified.** Returns a lipsynced video URL.',
     {
-      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)'),
+      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)'),
       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.')
@@ -593,6 +603,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -608,17 +619,17 @@ function registerGenerateTools(server, client) {
     '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.',
     {
-      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.'),
+      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'),
-      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 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)'),
+      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'),
       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. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false`, DNA is silently ignored.**'),
       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 (max_images > 0). Examples: character reference images for Kling O1/O3, style reference for Aleph/gen4_aleph, character image for WAN VACE video-edit. Check max_images 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 (max_videos > 1). Example: WAN 2.6 reference-to-video accepts 1–3 reference videos. Check max_videos on the model from list_models before passing.'),
-      elements: z.array(z.string()).optional().describe('Array of element image URLs for models with max_elements > 0. Elements are used as style or character reference assets alongside the main video. Check max_elements on the model from list_models before passing.')
+      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.')
     },
     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');
@@ -657,6 +668,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -697,6 +709,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             text: result.result?.text || '',
             srt_url: result.result?.srt_url || null,
             word_by_word_srt_url: result.result?.word_by_word_srt_url || null,
@@ -749,6 +762,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             mode: result.result?.mode || null,
@@ -790,6 +804,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             edit_type: result.result?.edit_type || null,
             model: result.result?.model || null
@@ -838,6 +853,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             download_url: result.result?.download_url || null,
             edit_type: result.result?.edit_type || null,

package/src/tools/media.js

@@ -45,19 +45,29 @@ function registerMediaTools(server, client) {
   // ─── list_media ────────────────────────────────────────────
   server.tool(
     'list_media',
-    'List the user\'s uploaded media from their Kolbo media library. Supports filtering by type (image / video / audio) and pagination. Returns items with stable URLs, names, sizes, and upload timestamps. Use this to discover what the user has previously uploaded before deciding whether to create new content.',
+    'Browse the user\'s Kolbo media library — both uploaded files AND AI-generated outputs they have saved. Powerful filtering: scope to a single project (`project_id`), a user folder (`folder_id`), a "section" / category (`category`: ai / uploaded / edited / favorites / training-lab), a media type (`type`: image / video / audio), or generation provenance (`source_type`). Combine filters freely. Use this to discover what the user already has before generating something new, to retrieve a specific past creation, or to list everything in a project for downstream batch work.',
     {
-      type: z.string().optional().describe('Filter by type: "image" | "video" | "audio". Omit for all types.'),
-      page: z.number().optional().describe('Page number (1-indexed). Default: 1'),
-      page_size: z.number().optional().describe('Items per page. Default: 20, max 100'),
-      search: z.string().optional().describe('Optional full-text search term matched against media names and descriptions')
+      project_id: z.string().optional().describe('Restrict to a single project (Mongo ObjectId). Use `app_builder_list_projects` to discover IDs. Omit to list across all the user\'s media.'),
+      folder_id: z.string().optional().describe('Restrict to a user folder (Mongo ObjectId). Discover folder IDs via `list_media_folders`. Takes precedence over project_id when both are set.'),
+      type: z.enum(['image', 'video', 'audio', 'all']).optional().describe('Filter by media type. Default: all types.'),
+      category: z.enum(['ai', 'uploaded', 'edited', 'favorites', 'training-lab', 'all']).optional().describe('Filter by "section" (matches the Kolbo desktop app sidebar): `ai` = AI-generated, `uploaded` = files the user uploaded, `edited` = AI-edited variants, `favorites` = items the user starred, `training-lab` = training-lab assets. Default: all sections.'),
+      source_type: z.enum(['uploaded', 'generated', 'chat-generated']).optional().describe('Lower-level provenance filter. Use `category` for the common case; use `source_type` for fine-grained distinction (e.g. only chat-generated images).'),
+      sort: z.enum(['created_desc', 'created_asc', 'name_asc', 'name_desc']).optional().describe('Sort order. Default: created_desc (newest first).'),
+      page: z.number().optional().describe('1-indexed page number. Default: 1'),
+      page_size: z.number().optional().describe('Items per page. Default: 50, max 200.'),
+      search: z.string().optional().describe('Free-text match against filename + original prompt.')
     },
-    async ({ type, page, page_size, search }) => {
+    async ({ project_id, folder_id, type, category, source_type, sort, page, page_size, search }) => {
       const params = new URLSearchParams();
-      if (type) params.set('type', type);
-      if (page) params.set('page', String(page));
-      if (page_size) params.set('pageSize', String(page_size));
-      if (search) params.set('searchTerm', search);
+      if (project_id) params.set('project_id', project_id);
+      if (folder_id)  params.set('folder_id', folder_id);
+      if (type)       params.set('type', type);
+      if (category)   params.set('category', category);
+      if (source_type) params.set('source_type', source_type);
+      if (sort)       params.set('sort', sort);
+      if (page)       params.set('page', String(page));
+      if (page_size)  params.set('page_size', String(page_size));
+      if (search)     params.set('search', search);
 
       const qs = params.toString();
       const result = await client.get(`/v1/media${qs ? '?' + qs : ''}`);
@@ -73,6 +83,334 @@ function registerMediaTools(server, client) {
       };
     }
   );
+
+  // ─── favorite_media ────────────────────────────────────────
+  server.tool(
+    'favorite_media',
+    'Mark a media item as a favorite for the user. Idempotent — calling on an already-favorited item is a no-op. Requires the media `id` from `list_media`. After favoriting, the item shows up in `list_media` with `category=favorites` and in the desktop app sidebar\'s Favorites section. Use this when the user explicitly says "favorite this", "save this to favorites", "star this", or similar.',
+    {
+      media_id: z.string().describe('The MediaLibraryItem id (returned as `id` from `list_media`).')
+    },
+    async ({ media_id }) => {
+      const result = await client.post(`/v1/media/${encodeURIComponent(media_id)}/favorite`, {});
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── unfavorite_media ──────────────────────────────────────
+  server.tool(
+    'unfavorite_media',
+    'Remove a media item from the user\'s favorites. Idempotent — calling on an item that isn\'t favorited is a no-op. Requires the media `id` from `list_media`. Use this when the user says "unfavorite", "remove from favorites", "unstar", or similar.',
+    {
+      media_id: z.string().describe('The MediaLibraryItem id (returned as `id` from `list_media`).')
+    },
+    async ({ media_id }) => {
+      const result = await client.delete(`/v1/media/${encodeURIComponent(media_id)}/favorite`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_media_folders ────────────────────────────────────
+  server.tool(
+    'list_media_folders',
+    'List the user\'s media folders (their own + folders shared with them). Folders are user-scoped and can span multiple projects — they\'re a way for the user to group media across the library independent of project structure. Use this to discover folder IDs to pass into `list_media` via `folder_id`, or to show the user what folders exist before suggesting where to look.',
+    {},
+    async () => {
+      const result = await client.get('/v1/media/folders');
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            folders: result.folders || [],
+            count: result.count || 0
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── create_media_folder ───────────────────────────────────
+  server.tool(
+    'create_media_folder',
+    'Create a new media folder for the user. Folders are user-scoped (span all projects) and useful for grouping related assets. Returns the new folder id — pass it as `folder_id` to `list_media`, `add_media_to_folder`, etc.',
+    {
+      name: z.string().describe('Folder name (1–100 characters).'),
+      description: z.string().optional().describe('Optional description (up to 500 characters).'),
+      color: z.string().optional().describe('Optional hex color like "#3B82F6" for UI tinting. Default: Kolbo blue.'),
+      icon: z.string().optional().describe('Optional Lucide icon name (e.g. "folder", "star", "image"). Default: "folder".')
+    },
+    async ({ name, description, color, icon }) => {
+      const result = await client.post('/v1/media/folders', { name, description, color, icon });
+      return { content: [{ type: 'text', text: JSON.stringify(result.folder || result, null, 2) }] };
+    }
+  );
+
+  // ─── update_media_folder ───────────────────────────────────
+  server.tool(
+    'update_media_folder',
+    'Rename a folder or update its color / icon / description. Owner only. Any subset of fields may be provided — fields omitted are left unchanged.',
+    {
+      folder_id: z.string().describe('Folder id from `list_media_folders` or `create_media_folder`.'),
+      name: z.string().optional().describe('New folder name (1–100 characters).'),
+      description: z.string().optional().describe('New description (up to 500 characters). Pass "" to clear.'),
+      color: z.string().optional().describe('New hex color like "#3B82F6".'),
+      icon: z.string().optional().describe('New Lucide icon name.')
+    },
+    async ({ folder_id, name, description, color, icon }) => {
+      const body = {};
+      if (name !== undefined) body.name = name;
+      if (description !== undefined) body.description = description;
+      if (color !== undefined) body.color = color;
+      if (icon !== undefined) body.icon = icon;
+      const result = await client.put(`/v1/media/folders/${encodeURIComponent(folder_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.folder || result, null, 2) }] };
+    }
+  );
+
+  // ─── delete_media_folder ───────────────────────────────────
+  server.tool(
+    'delete_media_folder',
+    'Delete a folder (soft delete — items inside are detached but NOT deleted from the user\'s media library). Owner only. ALWAYS ask the user to confirm before calling this — folder deletion is not surfaced in any "undo" flow.',
+    {
+      folder_id: z.string().describe('Folder id to delete.')
+    },
+    async ({ folder_id }) => {
+      const result = await client.delete(`/v1/media/folders/${encodeURIComponent(folder_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── add_media_to_folder ───────────────────────────────────
+  server.tool(
+    'add_media_to_folder',
+    'Add one or more media items to a folder. Caller must own the folder or be a shared member. Idempotent — items already in the folder are skipped silently. Up to 500 items per call.',
+    {
+      folder_id: z.string().describe('Target folder id.'),
+      media_ids: z.array(z.string()).describe('Array of MediaLibraryItem ids (from `list_media`). Up to 500.')
+    },
+    async ({ folder_id, media_ids }) => {
+      const result = await client.post(
+        `/v1/media/folders/${encodeURIComponent(folder_id)}/items`,
+        { media_ids }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── remove_media_from_folder ──────────────────────────────
+  server.tool(
+    'remove_media_from_folder',
+    'Remove one or more media items from a folder. Caller must own the folder or be a shared member. Items themselves remain in the library. Up to 500 items per call.',
+    {
+      folder_id: z.string().describe('Folder id.'),
+      media_ids: z.array(z.string()).describe('Array of MediaLibraryItem ids to remove from the folder.')
+    },
+    async ({ folder_id, media_ids }) => {
+      const result = await client.delete(
+        `/v1/media/folders/${encodeURIComponent(folder_id)}/items`,
+        { media_ids }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── share_media_folder ────────────────────────────────────
+  server.tool(
+    'share_media_folder',
+    'Share a folder with one or more users by email. Owner only. Users must already have a Kolbo account; emails not found are returned in `not_found`. Shared members can list folder contents, add and remove items, but cannot delete the folder or reshare it.',
+    {
+      folder_id: z.string().describe('Folder id to share.'),
+      user_emails: z.array(z.string()).describe('Array of email addresses to grant access to. Up to 50 per call.')
+    },
+    async ({ folder_id, user_emails }) => {
+      const result = await client.post(
+        `/v1/media/folders/${encodeURIComponent(folder_id)}/share`,
+        { user_emails }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── get_media ─────────────────────────────────────────────
+  server.tool(
+    'get_media',
+    'Fetch one media item\'s full details by id. Returns the same shape as items in `list_media` plus extra metadata. Use this when the user references a specific item ("tell me about this generation", "what prompt did I use for [item]").',
+    {
+      media_id: z.string().describe('MediaLibraryItem id (from `list_media`). Generation ids are also accepted as a fallback.')
+    },
+    async ({ media_id }) => {
+      const result = await client.get(`/v1/media/${encodeURIComponent(media_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result.media || result, null, 2) }] };
+    }
+  );
+
+  // ─── delete_media ──────────────────────────────────────────
+  server.tool(
+    'delete_media',
+    'Soft-delete a media item — moves it to the user\'s trash where it can be restored for 30 days. Owner only. Idempotent. Use this for "delete this image / video / song" — NOT for `permanently_delete_media`, which is irreversible.',
+    {
+      media_id: z.string().describe('MediaLibraryItem id to soft-delete.')
+    },
+    async ({ media_id }) => {
+      const result = await client.delete(`/v1/media/${encodeURIComponent(media_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── restore_media ─────────────────────────────────────────
+  server.tool(
+    'restore_media',
+    'Restore a soft-deleted (trashed) media item back to the user\'s active library. Owner only. Use after `delete_media` if the user changes their mind, or when the user explicitly asks "restore [item] from trash".',
+    {
+      media_id: z.string().describe('MediaLibraryItem id to restore from trash.')
+    },
+    async ({ media_id }) => {
+      const result = await client.post(`/v1/media/${encodeURIComponent(media_id)}/restore`, {});
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── permanently_delete_media ──────────────────────────────
+  server.tool(
+    'permanently_delete_media',
+    'PERMANENTLY delete a media item — removes it from MongoDB, deletes the file from S3, removes from all folders, and deletes the source generation record. NOT REVERSIBLE — there is no recovery flow. Owner only. ALWAYS ask the user to explicitly confirm before calling this; use `delete_media` for normal "delete" intent.',
+    {
+      media_id: z.string().describe('MediaLibraryItem id to permanently delete. Cannot be undone.')
+    },
+    async ({ media_id }) => {
+      const result = await client.delete(`/v1/media/${encodeURIComponent(media_id)}/permanent`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── move_media ────────────────────────────────────────────
+  server.tool(
+    'move_media',
+    'Move a media item to a different project. Caller must own the item AND have access to the target project. Items in shared projects from other members cannot be moved by you. Use this when the user says "move this to project X" or wants to reorganize.',
+    {
+      media_id: z.string().describe('MediaLibraryItem id to move.'),
+      project_id: z.string().describe('Target project id (use `app_builder_list_projects` to discover ids).')
+    },
+    async ({ media_id, project_id }) => {
+      const result = await client.patch(
+        `/v1/media/${encodeURIComponent(media_id)}/project`,
+        { project_id }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── bulk_delete_media ─────────────────────────────────────
+  server.tool(
+    'bulk_delete_media',
+    'Soft-delete up to 1000 media items in one call. Items go to trash (30-day recovery). Owner only — items not owned by the user are silently skipped (count returned in response). Use this for "clean up all my old [type]" or "delete the failed generations from yesterday".',
+    {
+      media_ids: z.array(z.string()).describe('Array of MediaLibraryItem ids. Up to 1000 per call.')
+    },
+    async ({ media_ids }) => {
+      const result = await client.post('/v1/media/bulk/delete', { media_ids });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── bulk_restore_media ────────────────────────────────────
+  server.tool(
+    'bulk_restore_media',
+    'Restore up to 1000 trashed media items at once. Owner only. Returns the count restored and how many ids weren\'t in trash (already active or not owned).',
+    {
+      media_ids: z.array(z.string()).describe('Array of trashed MediaLibraryItem ids to restore. Up to 1000.')
+    },
+    async ({ media_ids }) => {
+      const result = await client.post('/v1/media/bulk/restore', { media_ids });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── bulk_permanently_delete_media ─────────────────────────
+  server.tool(
+    'bulk_permanently_delete_media',
+    'PERMANENTLY delete up to 1000 media items. NOT REVERSIBLE — removes from MongoDB, S3, folders, and source generation records. Owner only. ALWAYS confirm with the user before calling; this is the bulk equivalent of `permanently_delete_media`.',
+    {
+      media_ids: z.array(z.string()).describe('Array of MediaLibraryItem ids to permanently delete. Up to 1000. Cannot be undone.')
+    },
+    async ({ media_ids }) => {
+      const result = await client.post('/v1/media/bulk/permanent', { media_ids });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── bulk_move_media ───────────────────────────────────────
+  server.tool(
+    'bulk_move_media',
+    'Move up to 1000 media items to a different project in a single call. Caller must own ALL items AND have access to the target project — if any item isn\'t owned by the caller, the entire operation is rejected (atomic).',
+    {
+      media_ids: z.array(z.string()).describe('Array of MediaLibraryItem ids to move. Up to 1000.'),
+      project_id: z.string().describe('Target project id.')
+    },
+    async ({ media_ids, project_id }) => {
+      const result = await client.post('/v1/media/bulk/move', { media_ids, project_id });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── move_folder_contents ──────────────────────────────────
+  server.tool(
+    'move_folder_contents',
+    'Move every media item inside a folder to a different project. Caller must own ALL items in the folder AND have access to the target project. Shared folder members cannot use this — only the item owner can move items between projects.',
+    {
+      folder_id: z.string().describe('Folder id whose contents will be moved.'),
+      project_id: z.string().describe('Target project id.')
+    },
+    async ({ folder_id, project_id }) => {
+      const result = await client.post(
+        `/v1/media/folders/${encodeURIComponent(folder_id)}/move-contents`,
+        { project_id }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── get_media_stats ───────────────────────────────────────
+  server.tool(
+    'get_media_stats',
+    'Get counts and total storage size of the user\'s media (or a specific project\'s media). Returns `{ total, images, videos, audio, total_size_bytes }`. Use this for "how many videos do I have", "what\'s my storage usage", or before bulk operations to estimate scope.',
+    {
+      project_id: z.string().optional().describe('Optional project id to scope stats to one project. Omit for the user\'s personal library across all projects.')
+    },
+    async ({ project_id }) => {
+      const params = new URLSearchParams();
+      if (project_id) params.set('project_id', project_id);
+      const qs = params.toString();
+      const result = await client.get(qs ? `/v1/media/stats?${qs}` : '/v1/media/stats');
+      return { content: [{ type: 'text', text: JSON.stringify(result.stats || result, null, 2) }] };
+    }
+  );
+
+  // ─── unshare_media_folder ──────────────────────────────────
+  server.tool(
+    'unshare_media_folder',
+    'Revoke a single user\'s access to a folder. Owner only. The user keeps any media they uploaded — only the folder access is removed.',
+    {
+      folder_id: z.string().describe('Folder id.'),
+      user_id: z.string().describe('User id to revoke (from the folder\'s `shared_with` array).')
+    },
+    async ({ folder_id, user_id }) => {
+      const result = await client.delete(
+        `/v1/media/folders/${encodeURIComponent(folder_id)}/share/${encodeURIComponent(user_id)}`
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
 }
 
 module.exports = { registerMediaTools };

package/src/tools/models.js

@@ -9,14 +9,28 @@ function registerModelTools(server, client) {
   // ─── list_models ───────────────────────────────────────────
   server.tool(
     'list_models',
-    'List available AI models on Kolbo. Filter by type to find models for a specific generation type.',
+    'List available AI models on Kolbo. Filter by `type` to narrow to a generation type, and pass `format: "json"` to get the raw model documents (every constraint field, useful for programmatic comparison / cap validation before submitting a generation). Default `format: "text"` returns the human-readable summary.',
     {
-      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.')
+      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.'),
+      format: z.enum(['text', 'json']).optional().describe('Output format. "text" (default) returns a human-readable summary with the most-used caps. "json" returns the raw model documents from the API — use this when you need to programmatically verify caps (max_reference_images, max_visual_dna, max_video_duration, supported_aspect_ratios, etc.) before passing an array/value that might exceed a model-specific limit. The JSON form is the source of truth; the text form is a convenience preview.')
     },
-    async ({ type }) => {
+    async ({ type, format }) => {
       const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
       const result = await client.get(path);
 
+      // JSON mode — return the raw API documents unchanged. This is the
+      // authoritative shape; every constraint the agent might need to validate
+      // a request lives here (durations, reference caps, audio/video min/max,
+      // resolution multipliers, supports_* flags, prompt-length limits, etc.).
+      if (format === 'json') {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({ count: result.count, models: result.models }, null, 2)
+          }]
+        };
+      }
+
       // Split into auto-selectable (has summary) and named-only (no summary)
       const withSummary = result.models.filter(m => m.summary && m.summary.trim() !== '');
       const withoutSummary = result.models.filter(m => !m.summary || m.summary.trim() === '');
@@ -25,8 +39,26 @@ function registerModelTools(server, client) {
       // it has to guess `supported_resolutions`/`supported_durations` and
       // either invents values (then the API silently substitutes) or asks
       // the user to clarify what's only knowable from this list.
+      //
+      // Rendering rule: emit a line for EVERY known constraint that is
+      // applicable for this model's type — even when the value is 0 / null.
+      // Hiding "0 cap" lines used to mean the agent couldn't distinguish
+      // "this model rejects DNA" (cap = 0) from "I don't know" (field
+      // missing). Now an explicit `max_dna: 0 (DNA not supported)` says the
+      // model says no, and absence means the API doesn't expose the field.
       const formatSpecs = m => {
         const parts = [];
+        const types = Array.isArray(m.types) ? m.types : [];
+        const isVideoType = types.some(t =>
+          ['text_to_video', 'img_to_video', 'video_to_video', 'elements',
+           'firstlastgenerations', 'lipsync-image', 'lipsync-video', 'draw_to_video'].includes(t)
+        );
+        const isElements = types.includes('elements');
+        const isV2V = types.includes('video_to_video');
+        const isLipsyncVideo = types.includes('lipsync-video');
+        const isLipsyncImage = types.includes('lipsync-image');
+        const isImageEdit = types.includes('image_editing');
+        const isImage = types.includes('text_to_img') || isImageEdit;
 
         if (Array.isArray(m.supported_resolutions) && m.supported_resolutions.length) {
           const mult = m.resolution_multipliers || {};
@@ -38,33 +70,70 @@ function registerModelTools(server, client) {
           );
         }
 
+        // Output durations (video gen output, not source video)
         if (Array.isArray(m.supported_durations) && m.supported_durations.length) {
           const ds = m.supported_durations;
-          // Compact ranges like 4-15 if it's a contiguous run.
           const sorted = [...ds].sort((a, b) => a - b);
           const isRange = sorted.length > 2 && sorted.every((v, i) => i === 0 || v - sorted[i - 1] === 1);
           parts.push(`durations: ${isRange ? `${sorted[0]}-${sorted[sorted.length - 1]}s` : sorted.join('/') + 's'}`);
+        } else if (isVideoType && (m.min_output_duration != null || m.max_output_duration != null)) {
+          parts.push(`duration_range: ${m.min_output_duration ?? '?'}-${m.max_output_duration ?? '?'}s${m.default_duration != null ? ` (default ${m.default_duration}s)` : ''}`);
         }
 
-        if (Array.isArray(m.supported_aspect_ratios) && m.supported_aspect_ratios.length) {
-          parts.push(`aspect: ${m.supported_aspect_ratios.join(', ')}`);
+        // Aspect ratios — prefer per-type override if set
+        const ratios = m.supported_aspect_ratios_by_type
+          ? Object.entries(m.supported_aspect_ratios_by_type).map(([t, arr]) => `${t}: ${arr.join('/')}`)
+          : null;
+        if (ratios) {
+          parts.push(`aspect (per-type): ${ratios.join(' | ')}`);
+        } else if (Array.isArray(m.supported_aspect_ratios) && m.supported_aspect_ratios.length) {
+          parts.push(`aspect: ${m.supported_aspect_ratios.join(', ')}${m.default_aspect_ratio ? ` (default ${m.default_aspect_ratio})` : ''}`);
+        }
+
+        // Reference-input caps — show the slot relevant for this model family.
+        // The same conceptual "max reference images" lives under THREE field
+        // names depending on the model type. Be explicit about which is which
+        // so the agent reads the right one.
+        if (isImage || isImageEdit) {
+          parts.push(`max_reference_images: ${m.max_reference_images ?? 0}${(m.max_reference_images ?? 0) === 0 ? ' (no refs)' : ''}`);
+        }
+        if (isElements) {
+          parts.push(`elements caps: imgs=${m.elements_max_images ?? 0} · vids=${m.elements_max_videos ?? 0} · audio=${m.elements_max_audio ?? 0}`);
+        }
+        if (isV2V) {
+          parts.push(`v2v ref caps: imgs=${m.max_images ?? 0} · vids=${m.max_videos ?? 0} · elements=${m.max_elements ?? 0} · audio=${m.max_audio ?? 0}`);
         }
 
-        // Elements-type caps (only show when at least one is non-zero)
-        const eImg = m.elements_max_images, eVid = m.elements_max_videos, eAud = m.elements_max_audio;
-        if ((eImg ?? 0) > 0 || (eVid ?? 0) > 0 || (eAud ?? 0) > 0) {
-          parts.push(`elements: ${eImg ?? 0} imgs / ${eVid ?? 0} vids / ${eAud ?? 0} audio`);
+        // Visual DNA cap — always show for image / elements / video, even if 0.
+        // Use the authoritative supports_visual_dna flag when available; fall
+        // back to inferring from cap > 0 for older API responses.
+        const dnaSupported = typeof m.supports_visual_dna === 'boolean'
+          ? m.supports_visual_dna
+          : (m.max_visual_dna ?? 0) > 0;
+        if (isImage || isVideoType) {
+          const cap = m.max_visual_dna;
+          if (dnaSupported && cap != null && cap > 0) parts.push(`max_visual_dna: ${cap}`);
+          else if (dnaSupported && cap == null) parts.push('visual_dna: supported (no cap published — confirm before passing >3)');
+          else parts.push('visual_dna: not supported');
         }
 
-        // Video-to-video / multi-input caps
-        const mImg = m.max_images, mVid = m.max_videos, mElm = m.max_elements;
-        if ((mImg ?? 0) > 0 || (mVid ?? 0) > 0 || (mElm ?? 0) > 0) {
-          parts.push(`refs: ${mImg ?? 0} imgs / ${mVid ?? 0} vids / ${mElm ?? 0} elms`);
+        // Source-video duration constraints — only matter for tools that take
+        // an INPUT video (lipsync-video, video_to_video).
+        if (isLipsyncVideo || isV2V) {
+          if (m.min_video_duration != null || m.max_video_duration != null) {
+            parts.push(`source_video: ${m.min_video_duration ?? '?'}-${m.max_video_duration ?? '?'}s`);
+          }
         }
 
-        if ((m.max_visual_dna ?? 0) > 0) parts.push(`max_dna: ${m.max_visual_dna}`);
+        // Audio input — lipsync, elements, music-driven flows.
+        if (m.max_audio_duration != null || m.min_audio_duration != null) {
+          parts.push(`audio_input: ${m.min_audio_duration ?? '?'}-${m.max_audio_duration ?? '?'}s${m.audio_max_follows_video_duration ? ' (max follows video)' : ''}`);
+        }
+        if (Array.isArray(m.supported_audio_formats) && m.supported_audio_formats.length) {
+          parts.push(`audio_formats: ${m.supported_audio_formats.join('/')}`);
+        }
 
-        // Sound (only show when sound costs more or is generated natively)
+        // Native sound generation (video models that emit synced audio)
         if (m.sound_generation_type === 'native') {
           const mult = m.sound_credit_multiplier && m.sound_credit_multiplier !== 1
             ? ` (${m.sound_credit_multiplier}×)`
@@ -72,7 +141,22 @@ function registerModelTools(server, client) {
           parts.push(`sound: native${mult}${m.sound_enabled_by_default ? ' on-by-default' : ''}`);
         }
 
-        if (m.max_audio_duration != null) parts.push(`audio_max: ${m.max_audio_duration}s`);
+        // Prompt constraints
+        if (m.requires_prompt === false) parts.push('prompt: optional');
+        if (m.min_prompt_length != null || m.max_prompt_length != null) {
+          parts.push(`prompt_length: ${m.min_prompt_length ?? 0}-${m.max_prompt_length ?? '∞'} chars`);
+        }
+
+        // Upload cap (when present)
+        if (m.max_file_size != null) {
+          const mb = Math.round(m.max_file_size / (1024 * 1024));
+          parts.push(`max_file_size: ${mb}MB`);
+        }
+
+        // Images-per-request (Midjourney-style fixed-N output)
+        if (m.images_per_request != null && m.images_per_request !== 1) {
+          parts.push(`images_per_request: ${m.images_per_request}`);
+        }
 
         return parts.length ? `\n   ${parts.join(' | ')}` : '';
       };
@@ -91,7 +175,7 @@ function registerModelTools(server, client) {
       return {
         content: [{
           type: 'text',
-          text: `Available models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools.`
+          text: `Available models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools. For programmatic cap validation, re-call with format: "json".`
         }]
       };
     }
@@ -113,6 +197,38 @@ function registerModelTools(server, client) {
       };
     }
   );
+
+  // ─── get_session_usage ─────────────────────────────────────
+  // Real, multiplier-adjusted credit spend tagged with the caller's
+  // X-Kolbo-Caller-Session-Id (set automatically by the parent process —
+  // no need to pass it). Use this to give the user an honest "you've spent
+  // X credits in this app session" instead of estimating from base credits.
+  server.tool(
+    'get_session_usage',
+    'Fetch real, multiplier-adjusted credit spend for the current Kolbo Code app session. Use when the user asks "how much did I spend?" or before/after a large bulk job so you can quote actual cost (not an estimate from base credits). Returns total + per-tool breakdown + per-model breakdown + a recent list. The caller-session-id is forwarded automatically by the MCP HTTP client.',
+    {},
+    async () => {
+      try {
+        const r = await client.get('/credit-usage/by-caller-session');
+        // The endpoint returns { message, data: { total, count, by_tool, by_model, recent[] } }
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(r.data || r, null, 2)
+          }]
+        };
+      } catch (err) {
+        // 400 from the endpoint means no caller-session-id was forwarded —
+        // surface a clear hint instead of a generic API error.
+        const hint = err?.status === 400
+          ? 'No caller-session-id was forwarded. Ensure the parent process (Kolbo Code / desktop sidecar) sets KOLBO_CALLER_SESSION_ID in this MCP\'s env, or call again after at least one media generation has fired.'
+          : err?.message || 'Failed to fetch session usage';
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ error: hint }, null, 2) }]
+        };
+      }
+    }
+  );
 }
 
 module.exports = { registerModelTools };