@kolbo/mcp 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -40,8 +40,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "form-data": "^4.0.5"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "form-data": "^4.0.5",
+    "zod": "^3.25.0"
   },
   "overrides": {
     "hono": "^4.12.12",

package/src/client.js

@@ -1,130 +1,312 @@
-/**
- * Kolbo API HTTP client wrapper
- */
-
-/**
- * Structured error thrown when the Kolbo API returns a non-OK response.
- * Preserves the SDK's error code, HTTP status, and full response data so
- * MCP tools (and the LLM consuming them) can distinguish NOT_FOUND from
- * INSUFFICIENT_CREDITS from VALIDATION_ERROR etc.
- */
-class KolboApiError extends Error {
-  constructor(message, { code, status, data } = {}) {
-    super(message);
-    this.name = 'KolboApiError';
-    this.code = code || null;
-    this.status = status || null;
-    this.data = data || null;
-  }
-}
-
-class KolboClient {
-  constructor() {
-    this.apiKey = process.env.KOLBO_API_KEY;
-    this.baseUrl = (process.env.KOLBO_API_URL || 'https://api.kolbo.ai/api').replace(/\/$/, '');
-
-    if (!this.apiKey) {
-      throw new Error('KOLBO_API_KEY environment variable is required');
-    }
-  }
-
-  async request(method, path, body = null) {
-    const url = `${this.baseUrl}${path}`;
-    const options = {
-      method,
-      headers: {
-        'X-API-Key': this.apiKey,
-        'Content-Type': 'application/json'
-      }
-    };
-
-    if (body) {
-      options.body = JSON.stringify(body);
-    }
-
-    const response = await fetch(url, options);
-    let data;
-    try {
-      data = await response.json();
-    } catch (_) {
-      // Non-JSON body (gateway error, HTML etc.)
-      throw new KolboApiError(`API error: ${response.status} ${response.statusText}`, {
-        status: response.status,
-        data: null
-      });
-    }
-
-    if (!response.ok || data.success === false) {
-      const message = data.error || data.message || `API error: ${response.status}`;
-      const code = data.code || null;
-      // Surface the code in the message so the LLM sees it even if it ignores the .code property
-      const fullMessage = code ? `${message} [${code}]` : message;
-      throw new KolboApiError(fullMessage, {
-        code,
-        status: response.status,
-        data
-      });
-    }
-
-    return data;
-  }
-
-  async post(path, body) {
-    return this.request('POST', path, body);
-  }
-
-  async get(path) {
-    return this.request('GET', path);
-  }
-
-  async delete(path) {
-    return this.request('DELETE', path);
-  }
-
-  async postMultipart(path, formData) {
-    const url = `${this.baseUrl}${path}`;
-    const headers = {
-      'X-API-Key': this.apiKey,
-      ...formData.getHeaders()
-    };
-
-    // form-data exposes getLengthSync for known-size parts; set Content-Length when available.
-    try {
-      const len = formData.getLengthSync();
-      if (len) headers['Content-Length'] = String(len);
-    } catch (_) { /* streaming length unavailable — let fetch handle it */ }
-
-    const response = await fetch(url, {
-      method: 'POST',
-      headers,
-      body: formData,
-      duplex: 'half'
-    });
-
-    let data;
-    try {
-      data = await response.json();
-    } catch (_) {
-      throw new KolboApiError(`API error: ${response.status} ${response.statusText}`, {
-        status: response.status,
-        data: null
-      });
-    }
-
-    if (!response.ok || data.success === false) {
-      const message = data.error || data.message || `API error: ${response.status}`;
-      const code = data.code || null;
-      const fullMessage = code ? `${message} [${code}]` : message;
-      throw new KolboApiError(fullMessage, {
-        code,
-        status: response.status,
-        data
-      });
-    }
-
-    return data;
-  }
-}
-
-module.exports = KolboClient;
-module.exports.KolboApiError = KolboApiError;
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Kolbo API HTTP client wrapper
+ *
+ * Auth resolution (first match wins):
+ *   1. KOLBO_API_KEY env var          — explicit key, always honored
+ *   2. CLI auth store (auth.json)     — auto-shared with `kolbo auth login`
+ *
+ * API base resolution (mirrors CLI partner.ts):
+ *   1. KOLBO_API_URL env var          — explicit override
+ *   2. KOLBO_API_BASE env var         — same as CLI
+ *   3. partner.json on disk           — whitelabel config
+ *   4. https://api.kolbo.ai/api       — default
+ */
+
+class KolboApiError extends Error {
+  constructor(message, { code, status, data } = {}) {
+    super(message);
+    this.name = 'KolboApiError';
+    this.code = code || null;
+    this.status = status || null;
+    this.data = data || null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Partner / whitelabel resolution (mirrors CLI's brand/partner.ts)
+// ---------------------------------------------------------------------------
+
+function readJsonSync(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Resolve the API base URL, checking the same sources as the CLI:
+ *   1. KOLBO_API_URL / KOLBO_API_BASE env vars
+ *   2. partner.json files (KOLBO_PARTNER_PROFILE, XDG_CONFIG_HOME, ~/.config)
+ *   3. Default: https://api.kolbo.ai/api
+ */
+function resolveApiBase() {
+  // Env vars take priority
+  const fromEnv = process.env.KOLBO_API_URL || process.env.KOLBO_API_BASE;
+  if (fromEnv) return fromEnv.replace(/\/$/, '');
+
+  // Partner profile files (same order as CLI)
+  const candidates = [];
+  if (process.env.KOLBO_PARTNER_PROFILE) {
+    candidates.push(process.env.KOLBO_PARTNER_PROFILE);
+  }
+  const xdgConfig = process.env.XDG_CONFIG_HOME || (
+    process.platform === 'win32'
+      ? path.join(os.homedir(), '.config')
+      : path.join(os.homedir(), '.config')
+  );
+  candidates.push(path.join(xdgConfig, 'kolbo', 'partner.json'));
+
+  for (const file of candidates) {
+    const data = readJsonSync(file);
+    if (data && data.apiBase) return data.apiBase.replace(/\/$/, '');
+  }
+
+  return 'https://api.kolbo.ai/api';
+}
+
+// ---------------------------------------------------------------------------
+// CLI auth store reader
+// ---------------------------------------------------------------------------
+
+/**
+ * XDG data dir — same logic as the `xdg-basedir` npm package the CLI uses.
+ * On Windows with Git Bash / MSYS2 this resolves to ~/.local/share (matching
+ * what the CLI actually writes to).
+ */
+function xdgDataDir() {
+  if (process.env.XDG_DATA_HOME) return process.env.XDG_DATA_HOME;
+  if (process.platform === 'win32') {
+    // xdg-basedir on Windows: LOCALAPPDATA → ~/.local/share fallback
+    return process.env.LOCALAPPDATA || path.join(os.homedir(), '.local', 'share');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support');
+  }
+  return path.join(os.homedir(), '.local', 'share');
+}
+
+/**
+ * Read the Kolbo CLI's auth store. The CLI writes credentials to
+ * <xdg-data>/kolbo/auth.json after device-code login.
+ *
+ * On Windows (Git Bash / MSYS2) xdg-basedir resolves to ~/.local/share,
+ * so we check multiple candidates to be safe.
+ */
+function readCliAuthKey() {
+  const dataDir = xdgDataDir();
+  const candidates = [
+    path.join(dataDir, 'kolbo', 'auth.json'),
+  ];
+  // Windows fallback: also check ~/.local/share if LOCALAPPDATA was primary
+  if (process.platform === 'win32' && dataDir !== path.join(os.homedir(), '.local', 'share')) {
+    candidates.push(path.join(os.homedir(), '.local', 'share', 'kolbo', 'auth.json'));
+  }
+
+  // Determine the API host for namespaced auth lookup
+  const apiBase = process.env.KOLBO_API_URL || process.env.KOLBO_API_BASE || '';
+  let apiHost = null;
+  try { apiHost = new URL(apiBase).host; } catch (_) {}
+  if (!apiHost) {
+    // Check partner.json for the API host
+    const partnerCandidates = [];
+    if (process.env.KOLBO_PARTNER_PROFILE) partnerCandidates.push(process.env.KOLBO_PARTNER_PROFILE);
+    const xdgCfg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    partnerCandidates.push(path.join(xdgCfg, 'kolbo', 'partner.json'));
+    for (const f of partnerCandidates) {
+      const p = readJsonSync(f);
+      if (p && p.apiBase) { try { apiHost = new URL(p.apiBase).host; } catch (_) {} break; }
+    }
+  }
+  if (!apiHost) apiHost = 'api.kolbo.ai';
+
+  for (const file of candidates) {
+    try {
+      const auth = JSON.parse(fs.readFileSync(file, 'utf8'));
+      // Try namespaced key first (e.g. "kolbo@api.kolbo.ai"), then bare "kolbo"
+      const entry = auth[`kolbo@${apiHost}`] || auth.kolbo;
+      if (!entry) continue;
+      if (entry.type === 'oauth' && entry.refresh) return entry.refresh;
+      if (entry.type === 'api' && entry.key) return entry.key;
+    } catch (_) {
+      // File doesn't exist or isn't valid JSON — try next
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP client
+// ---------------------------------------------------------------------------
+
+class KolboClient {
+  constructor() {
+    this.baseUrl = resolveApiBase();
+    this._envKey = process.env.KOLBO_API_KEY || null;
+    this._authStoreKey = null; // lazy-loaded
+    this.apiKey = this._envKey || this._readAuthStore();
+
+    if (!this.apiKey) {
+      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.'
+      );
+    }
+  }
+
+  _readAuthStore() {
+    this._authStoreKey = readCliAuthKey();
+    return this._authStoreKey;
+  }
+
+  /**
+   * On 401, re-read the CLI auth store in case the user re-authenticated
+   * since the MCP server started. Returns true if a new key was found.
+   */
+  _tryRefreshKey() {
+    if (this._envKey) {
+      // Env var is set but invalid — can't override it, but try auth store
+      const fresh = readCliAuthKey();
+      if (fresh && fresh !== this._envKey) {
+        this.apiKey = fresh;
+        return true;
+      }
+      return false;
+    }
+    const fresh = readCliAuthKey();
+    if (fresh && fresh !== this.apiKey) {
+      this.apiKey = fresh;
+      return true;
+    }
+    return false;
+  }
+
+  async request(method, reqPath, body = null) {
+    const result = await this._doRequest(method, reqPath, body);
+
+    // On 401, try re-reading auth store and retry once
+    if (result._status === 401 && this._tryRefreshKey()) {
+      return this._doRequest(method, reqPath, body);
+    }
+    return result;
+  }
+
+  async _doRequest(method, reqPath, body = null) {
+    const url = `${this.baseUrl}${reqPath}`;
+    const options = {
+      method,
+      headers: {
+        'X-API-Key': this.apiKey,
+        'Content-Type': 'application/json'
+      }
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+    let data;
+    try {
+      data = await response.json();
+    } catch (_) {
+      throw new KolboApiError(`API error: ${response.status} ${response.statusText}`, {
+        status: response.status,
+        data: null
+      });
+    }
+
+    if (!response.ok || data.success === false) {
+      const message = data.error || data.message || `API error: ${response.status}`;
+      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
+        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';
+      }
+      throw new KolboApiError(fullMessage, {
+        code,
+        status: response.status,
+        data
+      });
+    }
+
+    return data;
+  }
+
+  async post(reqPath, body) {
+    return this.request('POST', reqPath, body);
+  }
+
+  async get(reqPath) {
+    return this.request('GET', reqPath);
+  }
+
+  async delete(reqPath) {
+    return this.request('DELETE', reqPath);
+  }
+
+  async postMultipart(reqPath, formData) {
+    const result = await this._doMultipart(reqPath, formData);
+    if (result._status === 401 && this._tryRefreshKey()) {
+      return this._doMultipart(reqPath, formData);
+    }
+    return result;
+  }
+
+  async _doMultipart(reqPath, formData) {
+    const url = `${this.baseUrl}${reqPath}`;
+    const headers = {
+      'X-API-Key': this.apiKey,
+      ...formData.getHeaders()
+    };
+
+    try {
+      const len = formData.getLengthSync();
+      if (len) headers['Content-Length'] = String(len);
+    } catch (_) { /* streaming length unavailable */ }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: formData,
+      duplex: 'half'
+    });
+
+    let data;
+    try {
+      data = await response.json();
+    } catch (_) {
+      throw new KolboApiError(`API error: ${response.status} ${response.statusText}`, {
+        status: response.status,
+        data: null
+      });
+    }
+
+    if (!response.ok || data.success === false) {
+      const message = data.error || data.message || `API error: ${response.status}`;
+      const code = data.code || null;
+      let fullMessage = code ? `${message} [${code}]` : message;
+      if (response.status === 401) {
+        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';
+      }
+      throw new KolboApiError(fullMessage, {
+        code,
+        status: response.status,
+        data
+      });
+    }
+
+    return data;
+  }
+}
+
+module.exports = KolboClient;
+module.exports.KolboApiError = KolboApiError;

package/src/tools/chat.js

@@ -3,6 +3,7 @@
  * `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 { pollUntilDone } = require('../polling');
 
 function registerChatTools(server, client) {
@@ -11,13 +12,13 @@ function registerChatTools(server, client) {
     'chat_send_message',
     'Send a chat message to Kolbo AI. Starts a new conversation (omit session_id) or continues an existing one. Returns the assistant response when complete. Supports web search and deep think modes.',
     {
-      message: { type: 'string', description: 'The user message to send' },
-      model: { type: 'string', description: 'Model identifier (e.g. "gpt-4o", "claude-sonnet-4-5"). Omit for Smart Select (auto).' },
-      session_id: { type: 'string', description: 'Existing chat session ID to continue. Omit to start a new conversation.' },
-      system_prompt: { type: 'string', description: 'System prompt for the conversation. Only applied when creating a new session.' },
-      web_search: { type: 'boolean', description: 'Enable web search for this message. Default: false' },
-      deep_think: { type: 'boolean', description: 'Enable deep think (extended reasoning). Default: false' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' }
+      message: z.string().describe('The user message to send'),
+      model: z.string().optional().describe('Model identifier (e.g. "gpt-4o", "claude-sonnet-4-5"). Omit for Smart Select (auto).'),
+      session_id: z.string().optional().describe('Existing chat session ID to continue. Omit to start a new conversation.'),
+      system_prompt: z.string().optional().describe('System prompt for the conversation. Only applied when creating a new session.'),
+      web_search: z.boolean().optional().describe('Enable web search for this message. Default: false'),
+      deep_think: z.boolean().optional().describe('Enable deep think (extended reasoning). Default: false'),
+      enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true')
     },
     async ({ message, model, session_id, system_prompt, web_search, deep_think, enhance_prompt }) => {
       const gen = await client.post('/v1/chat', {
@@ -65,8 +66,8 @@ function registerChatTools(server, client) {
     'chat_list_conversations',
     'List your SDK chat conversations, most-recent first. Returns session_id, name, and activity timestamps.',
     {
-      page: { type: 'number', description: 'Page number, 1-indexed. Default: 1' },
-      limit: { type: 'number', description: 'Results per page, max 50. Default: 20' }
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
+      limit: z.number().optional().describe('Results per page, max 50. Default: 20')
     },
     async ({ page, limit }) => {
       const params = new URLSearchParams();
@@ -93,9 +94,9 @@ function registerChatTools(server, client) {
     'chat_get_messages',
     'Fetch messages in a chat conversation. Returns role, content, model, and any media URLs attached to each message.',
     {
-      session_id: { type: 'string', description: 'The chat session ID' },
-      page: { type: 'number', description: 'Page number, 1-indexed. Default: 1' },
-      limit: { type: 'number', description: 'Messages per page, max 100. Default: 50' }
+      session_id: z.string().describe('The chat session ID'),
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
+      limit: z.number().optional().describe('Messages per page, max 100. Default: 50')
     },
     async ({ session_id, page, limit }) => {
       const params = new URLSearchParams();

package/src/tools/generate.js

@@ -3,6 +3,7 @@
  * `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 FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
 const { resolveToBuffer } = require('./_shared');
@@ -13,15 +14,15 @@ function registerGenerateTools(server, client) {
     'generate_image',
     '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: { type: 'string', description: 'Text description of the image to generate' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="image" to see options. Omit for Smart Select.' },
-      aspect_ratio: { type: 'string', description: 'Aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt for better results. Default: true' },
-      num_images: { type: 'number', description: 'Number of images to generate in one call. Default: 1' },
-      reference_images: { type: 'array', description: 'Array of image URLs used as composition/style references (NOT as source images for editing — use generate_image_edit for that).' },
-      visual_dna_ids: { type: 'array', description: '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: { type: 'string', description: 'Moodboard ID (from list_moodboards / get_moodboard) whose master_prompt and style_guide should be applied to this generation.' },
-      enable_web_search: { type: 'boolean', description: 'Enable web-search grounding for the prompt (useful for current events, brand references, real-world accuracy). Default: false' }
+      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.'),
+      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')
     },
     async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search }) => {
       const gen = await client.post('/v1/generate/image', {
@@ -52,15 +53,15 @@ function registerGenerateTools(server, client) {
     'generate_image_edit',
     '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: { type: 'string', description: 'Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="image_edit" to see options. Omit for Smart Select.' },
-      source_images: { type: 'array', description: 'Array of source image URLs to edit. Typically one, but some models accept multiple for compositing.' },
-      aspect_ratio: { type: 'string', description: 'Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt for better results. Default: true' },
-      num_images: { type: 'number', description: 'Number of output images. Default: 1' },
-      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to apply for consistency with an existing character / style / product.' },
-      moodboard_id: { type: 'string', description: 'Moodboard ID whose master_prompt and style_guide should be applied.' },
-      enable_web_search: { type: 'boolean', description: 'Enable web-search grounding. Default: false' }
+      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.'),
+      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')
     },
     async ({ prompt, model, source_images, aspect_ratio, enhance_prompt, num_images, visual_dna_ids, moodboard_id, enable_web_search }) => {
       const gen = await client.post('/v1/generate/image-edit', {
@@ -91,17 +92,17 @@ function registerGenerateTools(server, client) {
     'generate_creative_director',
     'Generate a multi-scene coordinated set from ONE creative brief. Use this INSTEAD of calling generate_image/generate_video multiple times when the user wants a storyboard, multi-scene ad, product showcase, or any set of related outputs that should share visual language. Produces 1–8 scenes in a single request with consistent style. Supports image mode and video mode (`workflow_type`). Visual DNA and moodboard references keep character/style consistent across every scene.',
     {
-      prompt: { type: 'string', description: 'Creative brief or concept describing the full set of scenes to generate' },
-      scene_count: { type: 'number', description: 'Number of scenes to generate, 1–8. Default: 4' },
-      model: { type: 'string', description: 'Model identifier applied to every scene. Omit for Smart Select.' },
-      aspect_ratio: { type: 'string', description: 'Aspect ratio applied to every scene (e.g., "1:1", "16:9", "9:16"). Default: "1:1"' },
-      workflow_type: { type: 'string', description: '"image" (default) or "video"' },
-      duration: { type: 'number', description: 'Duration in seconds per scene (video mode only). E.g., 5 or 10.' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance prompts per scene. Default: true' },
-      reference_images: { type: 'array', description: 'Array of reference image URLs to guide style/composition of every scene.' },
-      visual_dna_ids: { type: 'array', description: '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: { type: 'string', description: 'A single moodboard ID whose master_prompt and style_guide should shape every scene.' },
-      moodboard_ids: { type: 'array', description: 'Multiple moodboard IDs when blending styles. Prefer `moodboard_id` for single moodboards.' }
+      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 to generate, 1–8. Default: 4'),
+      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"'),
+      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.'),
+      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.'),
+      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.')
     },
     async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids }) => {
       const gen = await client.post('/v1/generate/creative-director', {
@@ -142,13 +143,13 @@ function registerGenerateTools(server, client) {
     'generate_video',
     '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: { type: 'string', description: 'Text description of the video to generate' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="video" to see options. Check supported_durations and supported_aspect_ratios.' },
-      aspect_ratio: { type: 'string', description: 'Aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"' },
-      duration: { type: 'number', description: 'Duration in seconds. Must be a value the chosen model supports — check supported_durations from list_models. Default: 5' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' },
-      reference_images: { type: 'array', description: 'Array of image URLs used as visual references (style / composition / subject).' },
-      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to keep a character / style consistent with prior generations.' }
+      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.'),
+      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.')
     },
     async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, visual_dna_ids }) => {
       const gen = await client.post('/v1/generate/video', {
@@ -180,13 +181,13 @@ function registerGenerateTools(server, client) {
     'generate_video_from_image',
     'Animate an existing still image into a video using Kolbo AI. The image comes from `image_url`; `prompt` describes the motion (not the subject — the subject is already in the image). For generating a video from scratch, use generate_video. Returns the final video URL when complete.',
     {
-      image_url: { type: 'string', description: 'URL of the source image to animate' },
-      prompt: { type: 'string', description: 'Text description of the desired MOTION (e.g., "camera slowly pans right while the character walks forward")' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="video_from_image" to see options.' },
-      aspect_ratio: { type: 'string', description: 'Output aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"' },
-      duration: { type: 'number', description: 'Duration in seconds. Must be a value the chosen model supports. Default: 5' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the motion prompt. Default: true' },
-      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to maintain consistency with prior characters / styles.' }
+      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.'),
+      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.')
     },
     async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids }) => {
       const gen = await client.post('/v1/generate/video/from-image', {
@@ -217,13 +218,13 @@ function registerGenerateTools(server, client) {
     'generate_music',
     '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: { type: 'string', description: 'Text description of the music to generate (e.g., "upbeat electronic dance track with synthesizers")' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="music" to see options. Omit for Suno (default).' },
-      style: { type: 'string', description: 'Music style / genre (e.g., "pop", "rock", "lo-fi", "electronic", "jazz")' },
-      instrumental: { type: 'boolean', description: 'Generate instrumental only, no vocals. Default: false' },
-      lyrics: { type: 'string', description: 'Custom lyrics for the song. If omitted, lyrics are generated automatically from the prompt unless instrumental is true.' },
-      vocal_gender: { type: 'string', description: 'Preferred vocal gender: "male" or "female". Only applies when instrumental is false.' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' }
+      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).'),
+      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')
     },
     async ({ prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt }) => {
       const gen = await client.post('/v1/generate/music', {
@@ -254,10 +255,10 @@ function registerGenerateTools(server, client) {
     'generate_speech',
     'Convert text to speech using Kolbo AI. Default provider is ElevenLabs. To pick a specific voice by language/gender, call list_voices first and pass the returned voice_id (or a voice display name — both work). Returns the final audio URL when complete.',
     {
-      text: { type: 'string', description: 'The text to convert to speech' },
-      voice: { type: 'string', description: 'Voice ID (from list_voices) or voice display name (e.g., "Rachel", "Adam"). Default: "Rachel"' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="speech" to see options. Default: eleven_v3' },
-      language: { type: 'string', description: 'Language code (e.g., "en-US", "he-IL", "es-ES"). Default: "en-US"' }
+      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'),
+      language: z.string().optional().describe('Language code (e.g., "en-US", "he-IL", "es-ES"). Default: "en-US"')
     },
     async ({ text, voice, model, language }) => {
       const gen = await client.post('/v1/generate/speech', {
@@ -287,9 +288,9 @@ function registerGenerateTools(server, client) {
     'generate_sound',
     '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: { type: 'string', description: 'Text description of the sound effect (e.g., "thunder clap with rain", "door creaking open", "futuristic UI beep")' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="sound" to see options. Default: elevenlabs-sound-effects-v1' },
-      duration: { type: 'number', description: 'Duration in seconds. Omit for automatic duration.' }
+      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.')
     },
     async ({ prompt, model, duration }) => {
       const gen = await client.post('/v1/generate/sound', {
@@ -318,9 +319,9 @@ function registerGenerateTools(server, client) {
     'list_voices',
     'List available TTS voices for generate_speech. Returns preset voices and the user\'s own cloned/designed voices. Filter by provider, language, or gender to find the right voice. Use the returned `voice_id` as the `voice` parameter in generate_speech.',
     {
-      provider: { type: 'string', description: 'Filter by provider (e.g., "elevenLabs", "google")' },
-      language: { type: 'string', description: 'Filter by language name or code (e.g., "English", "en-US")' },
-      gender: { type: 'string', description: 'Filter by gender (e.g., "Female", "Male")' }
+      provider: z.string().optional().describe('Filter by provider (e.g., "elevenLabs", "google")'),
+      language: z.string().optional().describe('Filter by language name or code (e.g., "English", "en-US")'),
+      gender: z.string().optional().describe('Filter by gender (e.g., "Female", "Male")')
     },
     async ({ provider, language, gender }) => {
       const params = new URLSearchParams();
@@ -355,7 +356,7 @@ function registerGenerateTools(server, client) {
     'get_generation_status',
     'Check the status of a generation. Use this as a FALLBACK when a generation tool returned a timeout error — the generation is probably still running on the server. Pass the generation_id from the timeout error (or from any prior generation response).',
     {
-      generation_id: { type: 'string', description: 'The generation ID to check' }
+      generation_id: z.string().describe('The generation ID to check')
     },
     async ({ generation_id }) => {
       const result = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`);
@@ -378,16 +379,16 @@ function registerGenerateTools(server, client) {
     '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.',
     {
-      prompt: { type: 'string', description: 'Text description of the desired video / animation' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="video" to see options. Omit for Smart Select.' },
-      reference_images: { type: 'array', description: 'Array of public image URLs used as reference elements (product shots, character references, etc.). URL mode.' },
-      files: { type: 'array', description: '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: { type: 'number', description: 'Duration in seconds. Default: 5' },
-      aspect_ratio: { type: 'string', description: 'Aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"' },
-      motion: { type: 'string', description: 'Motion style / intensity hint (optional)' },
-      preset_id: { type: 'string', description: 'Preset ID from list_presets type="video" (optional)' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' },
-      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to apply for character/style consistency across outputs.' }
+      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.'),
+      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.')
     },
     async ({ prompt, model, reference_images, files, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids }) => {
       if (!prompt) throw new Error('prompt is required');
@@ -441,16 +442,16 @@ function registerGenerateTools(server, client) {
     'generate_first_last_frame',
     'Generate a video that morphs / interpolates from a FIRST frame to a LAST frame. Provide the two frames as URLs (first_frame_url + last_frame_url) OR as local file paths (first_frame + last_frame). Optional prompt describes the desired motion/transition. Do NOT mix URL and file inputs. Returns the final video URL when complete.',
     {
-      first_frame_url: { type: 'string', description: 'Public URL of the first frame image (URL mode)' },
-      last_frame_url: { type: 'string', description: 'Public URL of the last frame image (URL mode)' },
-      first_frame: { type: 'string', description: 'URL or absolute local path to the first frame (file mode — alternative to first_frame_url)' },
-      last_frame: { type: 'string', description: 'URL or absolute local path to the last frame (file mode — alternative to last_frame_url)' },
-      prompt: { type: 'string', description: 'Optional description of the desired motion between the two frames (e.g. "smooth camera dolly in")' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="video_from_image" to see options. Omit for Smart Select.' },
-      duration: { type: 'number', description: 'Duration in seconds. Default: 5' },
-      aspect_ratio: { type: 'string', description: 'Aspect ratio (auto-detected from first frame if not provided). Default: "16:9"' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' },
-      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to apply.' }
+      first_frame_url: z.string().optional().describe('Public URL of the first frame image (URL mode)'),
+      last_frame_url: z.string().optional().describe('Public URL of the last frame image (URL mode)'),
+      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.'),
+      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.')
     },
     async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids }) => {
       const urlMode = first_frame_url && last_frame_url;
@@ -508,11 +509,11 @@ function registerGenerateTools(server, client) {
     '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.',
     {
-      source: { type: 'string', description: 'URL or absolute local path to the source image or video (the face to animate)' },
-      audio: { type: 'string', description: 'URL or absolute local path to the audio track (the voice to sync to)' },
-      text_prompt: { type: 'string', description: 'Optional text prompt (for performance-capable models)' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="lipsync" to see options. Omit for Smart Select.' },
-      bounding_box_target: { type: 'array', description: 'Optional bounding box [x, y, w, h] for multi-face inputs (Hedra Character3 style). Leave empty for single-face.' }
+      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.'),
+      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 }) => {
       if (!source) throw new Error('source is required (URL or absolute local path to image/video)');
@@ -578,13 +579,13 @@ 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 — 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.',
     {
-      source_video: { type: 'string', description: 'URL or absolute local path to the source video to restyle' },
-      prompt: { type: 'string', description: 'Text description of the desired restyle / transformation' },
-      model: { type: 'string', description: 'Model identifier. Omit for Smart Select.' },
-      aspect_ratio: { type: 'string', description: 'Output aspect ratio. Default: matches source' },
-      duration: { type: 'number', description: 'Duration in seconds (default: matches source)' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' },
-      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to apply for character/style consistency.' }
+      source_video: z.string().describe('URL or absolute local path to the source video to restyle'),
+      prompt: z.string().describe('Text description of the desired restyle / transformation'),
+      model: z.string().optional().describe('Model identifier. 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.')
     },
     async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids }) => {
       if (!source_video) throw new Error('source_video is required');
@@ -633,7 +634,7 @@ function registerGenerateTools(server, client) {
     'transcribe_audio',
     'Transcribe audio or video into text + SRT subtitles. Source can be a URL or an absolute local file path. Returns the full text, SRT content, duration, and download URLs for .srt/.txt files. Works on both audio-only files (mp3, wav, m4a) and videos with audio tracks (mp4, mov, webm).',
     {
-      source: { type: 'string', description: 'URL or absolute local path to the audio / video file to transcribe' }
+      source: z.string().describe('URL or absolute local path to the audio / video file to transcribe')
     },
     async ({ source }) => {
       if (!source) throw new Error('source is required (URL or absolute local path)');
@@ -660,6 +661,7 @@ function registerGenerateTools(server, client) {
           text: JSON.stringify({
             text: result.result?.text || '',
             srt_url: result.result?.srt_url || null,
+            word_by_word_srt_url: result.result?.word_by_word_srt_url || null,
             txt_url: result.result?.txt_url || null,
             duration: result.result?.duration || null
           }, null, 2)
@@ -673,15 +675,15 @@ function registerGenerateTools(server, client) {
     'generate_3d',
     'Generate a 3D model from a text prompt, a single reference image, or multiple reference images (for multi-view reconstruction). Returns model URLs in multiple formats (GLB, FBX, OBJ, USDZ). Modes: "text" (prompt-only), "single" (one image), "multi" (multiple images for better quality). The mode is auto-detected from the inputs if not specified.',
     {
-      prompt: { type: 'string', description: 'Text description of the 3D object to generate (used in text mode and also as a hint in image modes)' },
-      reference_images: { type: 'array', description: 'Array of public image URLs. 1 image → single mode, 2+ → multi mode.' },
-      mode: { type: 'string', description: 'Explicitly set mode: "text" | "single" | "multi". Auto-detected from reference_images if omitted.' },
-      texture_prompt: { type: 'string', description: 'Optional prompt to guide texture generation' },
-      model: { type: 'string', description: 'Model identifier. Use list_models type="three_d" to see options.' },
-      topology: { type: 'string', description: 'Topology preset (optional, model-specific)' },
-      target_polycount: { type: 'number', description: 'Target polygon count (optional, model-specific)' },
-      enable_tpose: { type: 'boolean', description: 'Force T-pose for character models (optional)' },
-      enable_pbr: { type: 'boolean', description: 'Enable PBR textures (optional)' }
+      prompt: z.string().optional().describe('Text description of the 3D object to generate (used in text mode and also as a hint in image modes)'),
+      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.'),
+      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)'),
+      enable_pbr: z.boolean().optional().describe('Enable PBR textures (optional)')
     },
     async ({ prompt, reference_images, mode, texture_prompt, model, topology, target_polycount, enable_tpose, enable_pbr }) => {
       if (!prompt && !(reference_images && reference_images.length > 0)) {

package/src/tools/media.js

@@ -3,6 +3,7 @@
  * `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 FormData = require('form-data');
 const { resolveToBuffer } = require('./_shared');
 
@@ -12,8 +13,8 @@ function registerMediaTools(server, client) {
     'upload_media',
     'Upload a local file (or remote URL) to the user\'s Kolbo media library and get back a stable Kolbo CDN URL. Use this when the user wants to reference a local file in multiple subsequent generation calls — upload once, then pass the returned URL to generate_image / generate_video / visual_dna / etc. Auto-detects media type (image / video / audio) from the file extension. For a single-use reference where you already have a public URL, you can skip this and pass the URL directly to the generation tool.',
     {
-      source: { type: 'string', description: 'URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability.' },
-      description: { type: 'string', description: 'Optional description / caption for the uploaded media' }
+      source: z.string().describe('URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability.'),
+      description: z.string().optional().describe('Optional description / caption for the uploaded media')
     },
     async ({ source, description }) => {
       if (!source) throw new Error('source is required (URL or absolute local path)');
@@ -46,10 +47,10 @@ function registerMediaTools(server, client) {
     '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.',
     {
-      type: { type: 'string', description: 'Filter by type: "image" | "video" | "audio". Omit for all types.' },
-      page: { type: 'number', description: 'Page number (1-indexed). Default: 1' },
-      page_size: { type: 'number', description: 'Items per page. Default: 20, max 100' },
-      search: { type: 'string', description: 'Optional full-text search term matched against media names and descriptions' }
+      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')
     },
     async ({ type, page, page_size, search }) => {
       const params = new URLSearchParams();

package/src/tools/models.js

@@ -1,53 +1,52 @@
-/* ⛔ 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. */
-
-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.',
-    {
-      type: {
-        type: 'string',
-        description: 'Filter by type: "image", "video", "video_from_image", "music", "speech", "sound". Omit for all models.'
-      }
-    },
-    async ({ type }) => {
-      const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
-      const result = await client.get(path);
-
-      // Format for readability
-      const summary = result.models.map(m =>
-        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}`
-      ).join('\n');
-
-      return {
-        content: [{
-          type: 'text',
-          text: `Available models (${result.count}):\n\n${summary}\n\nUse the "identifier" value as the "model" parameter in generate tools.`
-        }]
-      };
-    }
-  );
-
-  // ─── check_credits ─────────────────────────────────────────
-  server.tool(
-    'check_credits',
-    'Check your remaining Kolbo credit balance.',
-    {},
-    async () => {
-      const result = await client.get('/v1/account/credits');
-
-      return {
-        content: [{
-          type: 'text',
-          text: `Credit Balance:\n- Total: ${result.credits.total}\n- Plan credits: ${result.credits.plan_credits}\n- Credit pack: ${result.credits.credit_pack}\n- Redemption: ${result.credits.redemption}`
-        }]
-      };
-    }
-  );
-}
-
-module.exports = { registerModelTools };
+/* ⛔ 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 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.',
+    {
+      type: z.string().optional().describe('Filter by type: "image", "video", "video_from_image", "music", "speech", "sound". Omit for all models.')
+    },
+    async ({ type }) => {
+      const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
+      const result = await client.get(path);
+
+      // Format for readability
+      const summary = result.models.map(m =>
+        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}`
+      ).join('\n');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Available models (${result.count}):\n\n${summary}\n\nUse the "identifier" value as the "model" parameter in generate tools.`
+        }]
+      };
+    }
+  );
+
+  // ─── check_credits ─────────────────────────────────────────
+  server.tool(
+    'check_credits',
+    'Check your remaining Kolbo credit balance.',
+    {},
+    async () => {
+      const result = await client.get('/v1/account/credits');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Credit Balance:\n- Total: ${result.credits.total}\n- Plan credits: ${result.credits.plan_credits}\n- Credit pack: ${result.credits.credit_pack}\n- Redemption: ${result.credits.redemption}`
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerModelTools };

package/src/tools/moodboards.js

@@ -3,6 +3,8 @@
  * `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 registerMoodboardTools(server, client) {
   // ─── list_moodboards ───────────────────────────────────────
   server.tool(
@@ -28,7 +30,7 @@ function registerMoodboardTools(server, client) {
     'get_moodboard',
     'Fetch a single moodboard by ID. Returns the full moodboard including master_prompt, style_guide, and all image URLs.',
     {
-      moodboard_id: { type: 'string', description: 'The moodboard ID' }
+      moodboard_id: z.string().describe('The moodboard ID')
     },
     async ({ moodboard_id }) => {
       const result = await client.get(`/v1/moodboards/${encodeURIComponent(moodboard_id)}`);

package/src/tools/presets.js

@@ -3,13 +3,15 @@
  * `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 registerPresetTools(server, client) {
   // ─── list_presets ──────────────────────────────────────────
   server.tool(
     'list_presets',
     'List generation presets across image, video, music, and text-to-video catalogs. Presets bundle a specific prompt template + style direction that can be passed to a generation tool via its `preset_id` arg for a one-shot creative direction. Filter by `type` to narrow to a specific catalog. Returns id, name, description, thumbnail, category, and (for music) audio preview URL.',
     {
-      type: { type: 'string', description: 'Filter by catalog: "image" | "video" | "music" | "text_to_video". Omit for all.' }
+      type: z.string().optional().describe('Filter by catalog: "image" | "video" | "music" | "text_to_video". Omit for all.')
     },
     async ({ type }) => {
       const params = new URLSearchParams();

package/src/tools/visual_dna.js

@@ -3,6 +3,7 @@
  * `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 FormData = require('form-data');
 const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES } = require('./_shared');
 
@@ -19,12 +20,12 @@ function registerVisualDnaTools(server, client) {
     'create_visual_dna',
     'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each.',
     {
-      name: { type: 'string', description: 'Name of the Visual DNA profile' },
-      dna_type: { type: 'string', description: 'Type: "character", "style", "product", "scene". Default: "character"' },
-      prompt_helper: { type: 'string', description: 'Optional description/notes to guide DNA extraction' },
-      images: { type: 'array', description: 'Array of image sources (URLs or absolute local paths). Max 4.' },
-      video: { type: 'string', description: 'Optional video source (URL or absolute local path)' },
-      audio: { type: 'string', description: 'Optional audio source (URL or absolute local path)' }
+      name: z.string().describe('Name of the Visual DNA profile'),
+      dna_type: z.string().optional().describe('Type: "character", "style", "product", "scene". Default: "character"'),
+      prompt_helper: z.string().optional().describe('Optional description/notes to guide DNA extraction'),
+      images: z.array(z.string()).optional().describe('Array of image sources (URLs or absolute local paths). Max 4.'),
+      video: z.string().optional().describe('Optional video source (URL or absolute local path)'),
+      audio: z.string().optional().describe('Optional audio source (URL or absolute local path)')
     },
     async ({ name, dna_type, prompt_helper, images, video, audio }) => {
       if (!name || !name.trim()) {
@@ -96,7 +97,7 @@ function registerVisualDnaTools(server, client) {
     'get_visual_dna',
     'Fetch a single Visual DNA profile by ID. Returns the full profile including system_prompt and all reference images.',
     {
-      visual_dna_id: { type: 'string', description: 'The Visual DNA profile ID' }
+      visual_dna_id: z.string().describe('The Visual DNA profile ID')
     },
     async ({ visual_dna_id }) => {
       const result = await client.get(`/v1/visual-dna/${encodeURIComponent(visual_dna_id)}`);
@@ -114,7 +115,7 @@ function registerVisualDnaTools(server, client) {
     'delete_visual_dna',
     'Delete a Visual DNA profile by ID. Only the owner can delete.',
     {
-      visual_dna_id: { type: 'string', description: 'The Visual DNA profile ID to delete' }
+      visual_dna_id: z.string().describe('The Visual DNA profile ID to delete')
     },
     async ({ visual_dna_id }) => {
       const result = await client.delete(`/v1/visual-dna/${encodeURIComponent(visual_dna_id)}`);