@kolbo/mcp 1.0.0 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
 
-Generate images, videos, music, speech, and sound effects — all from natural language in your coding environment.
+Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
 
 ## Quick Setup
 
@@ -34,22 +34,57 @@ Just ask Claude naturally:
 
 - *"Generate an image of a sunset over mountains"*
 - *"Create a 5-second video of waves crashing"*
+- *"Build a 4-scene storyboard for a coffee shop ad"*
+- *"Remove the background from this image"*
 - *"Make a lo-fi hip hop beat"*
-- *"Convert this text to speech: Hello world"*
+- *"Read this out loud with a British female voice"*
+- *"Ask Claude about the latest AI news with web search on"*
+- *"Create a Visual DNA profile called 'Alex' from these images"*
 
-## Available Tools
+## Available Tools (21)
 
+**Generation**
 | Tool | Description |
 |------|-------------|
-| `generate_image` | Generate images from text prompts |
-| `generate_video` | Generate videos from text |
-| `generate_video_from_image` | Animate an image into video |
-| `generate_music` | Generate music from descriptions |
-| `generate_speech` | Convert text to speech |
-| `generate_sound` | Generate sound effects |
-| `list_models` | Browse available AI models |
+| `generate_image` | Text → image |
+| `generate_image_edit` | Existing image(s) + prompt → edited image |
+| `generate_video` | Text → video |
+| `generate_video_from_image` | Still image + motion prompt → video |
+| `generate_creative_director` | One brief → N coordinated scenes (image or video) |
+| `generate_music` | Text (+ optional lyrics) → song |
+| `generate_speech` | Text + voice → spoken audio |
+| `generate_sound` | Text → sound effect |
+
+Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
+
+**Chat**
+| Tool | Description |
+|------|-------------|
+| `chat_send_message` | Multi-turn chat with any Kolbo model; supports web search and deep think |
+| `chat_list_conversations` | List past chat threads |
+| `chat_get_messages` | Fetch messages in a conversation |
+
+**Visual DNA** (reusable character/style/product profiles)
+| Tool | Description |
+|------|-------------|
+| `create_visual_dna` | Create a profile from URLs or local files |
+| `list_visual_dnas` | List your profiles |
+| `get_visual_dna` | Fetch one profile |
+| `delete_visual_dna` | Delete a profile |
+
+**Moodboards**
+| Tool | Description |
+|------|-------------|
+| `list_moodboards` | Browse presets + your moodboards |
+| `get_moodboard` | Fetch one moodboard with all image URLs |
+
+**Discovery & Account**
+| Tool | Description |
+|------|-------------|
+| `list_models` | Current model catalog with costs and capabilities |
+| `list_voices` | TTS voices (presets + cloned) |
 | `check_credits` | Check credit balance |
-| `get_generation_status` | Check a generation's status |
+| `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
 
 ## Environment Variables
 

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
     "kolbo-mcp": "./bin/kolbo-mcp.js"
   },
   "scripts": {
-    "start": "node src/index.js"
+    "start": "node src/index.js",
+    "smoke": "node scripts/smoke.js",
+    "check-parity": "node scripts/check-parity.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js"
   },
   "keywords": [
     "kolbo",
@@ -24,9 +27,9 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/nicenathapong/kolbo-mcp"
+    "url": "https://github.com/Zoharvan12/kolbo-mcp"
   },
-  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-mcp",
+  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
   "author": "Kolbo AI <support@kolbo.ai>",
   "publishConfig": {
     "access": "public"
@@ -37,7 +40,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1"
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "form-data": "^4.0.5"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/client.js

@@ -1,6 +1,23 @@
 /**
  * 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;
@@ -26,10 +43,27 @@ class KolboClient {
     }
 
     const response = await fetch(url, options);
-    const data = await response.json();
+    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) {
-      throw new Error(data.error || data.message || `API error: ${response.status}`);
+      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;
@@ -42,6 +76,55 @@ class KolboClient {
   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;

package/src/index.js

@@ -1,8 +1,69 @@
+/* ============================================================================
+ * @kolbo/mcp — Kolbo AI MCP Server
+ *
+ *   ⛔  STOP.  READ THIS BEFORE TOUCHING ANY TOOL REGISTRATION.  ⛔
+ *
+ * This package is published to npm and installed via `npx -y @kolbo/mcp`.
+ * Thousands of users have it CACHED on their machines, pinned to old versions
+ * by npx's cache. Every tool name, every arg name, every response shape
+ * registered below is a PUBLIC CONTRACT. Breaking it silently strands users
+ * whose LLM will keep calling tool names their cached server no longer
+ * registers — or worse, calls new-style args that the old server can't parse.
+ *
+ * THE THREE COMMANDMENTS
+ *
+ *   1. NEVER RENAME AN EXISTING TOOL.
+ *      Not `generate_image` → `create_image`. Not `list_models` → `get_models`.
+ *      Not "just cleaning up the name." Old cached clients break the instant
+ *      you rename. If you must rename, keep the OLD name as an alias that
+ *      forwards to the new implementation for at least one full major version.
+ *
+ *   2. NEVER REMOVE AN EXISTING TOOL.
+ *      Deprecate it in the description ("[DEPRECATED: use X]") and keep it
+ *      working. Only remove in a major version bump with release notes.
+ *
+ *   3. NEVER CHANGE AN EXISTING TOOL'S ARG NAMES, TYPES, OR REQUIRED STATUS
+ *      IN A BACKWARD-INCOMPATIBLE WAY.
+ *      Adding a new OPTIONAL arg with a sensible default is fine. Everything
+ *      else below is forbidden in a minor release:
+ *        - renaming `prompt` to `text`
+ *        - making a previously-optional arg required
+ *        - changing `aspect_ratio: string` to `aspect_ratio: { w, h }`
+ *        - removing an arg (even one you think nobody uses)
+ *
+ * VERSION BUMPS
+ *
+ *   - minor (1.1.0 → 1.2.0): new tool, new optional arg, description tweak
+ *   - patch (1.1.0 → 1.1.1): internal refactor, bug fix with no user impact
+ *   - major (1.1.0 → 2.0.0): ANY breaking change from commandments 1–3 above,
+ *     AND only after going through the deprecation path in CLAUDE.md.
+ *
+ * WHY THIS MATTERS
+ *
+ *   Users install via `npx -y @kolbo/mcp` — npx CACHES packages. A user who
+ *   installed 3 months ago may still be running v1.0 until their cache
+ *   invalidates. When their Claude Desktop starts the MCP server, it
+ *   registers whatever tools ITS VERSION knows about. Their LLM sees that
+ *   list and calls those names. You cannot force-update them.
+ *
+ *   The matching backend SDK routes in
+ *   `kolbo-api/src/modules/sdk/index.js` are the same kind of public
+ *   contract and follow the same rules — never rename, never remove.
+ *
+ * Full rules, deprecation path, and parity-audit instructions: CLAUDE.md
+ *
+ * If you are a coding agent about to rename/remove a tool or arg: STOP and
+ * ask the human first. This is not optional.
+ * ==========================================================================*/
+
 const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const KolboClient = require('./client');
 const { registerGenerateTools } = require('./tools/generate');
 const { registerModelTools } = require('./tools/models');
+const { registerChatTools } = require('./tools/chat');
+const { registerVisualDnaTools } = require('./tools/visual_dna');
+const { registerMoodboardTools } = require('./tools/moodboards');
 
 async function main() {
   const client = new KolboClient();
@@ -15,6 +76,9 @@ async function main() {
   // Register all tools
   registerGenerateTools(server, client);
   registerModelTools(server, client);
+  registerChatTools(server, client);
+  registerVisualDnaTools(server, client);
+  registerMoodboardTools(server, client);
 
   // Start the server with stdio transport
   const transport = new StdioServerTransport();

package/src/polling.js

@@ -1,31 +1,57 @@
 /**
  * Poll a generation until it reaches a terminal state
  */
+
+class PollingTimeoutError extends Error {
+  constructor(generationId, timeoutMs) {
+    const seconds = Math.round(timeoutMs / 1000);
+    super(
+      `Generation timed out after ${seconds}s of polling. The generation may STILL be running on the server — ` +
+      `call get_generation_status with generation_id="${generationId}" to check its current state. ` +
+      `Videos, deep-think chat, and large batches can take longer than the default polling window.`
+    );
+    this.name = 'PollingTimeoutError';
+    this.generationId = generationId;
+    this.timeoutMs = timeoutMs;
+    this.timedOut = true;
+  }
+}
+
+class GenerationFailedError extends Error {
+  constructor(generationId, reason) {
+    super(`Generation failed: ${reason || 'unknown error'} (generation_id="${generationId}")`);
+    this.name = 'GenerationFailedError';
+    this.generationId = generationId;
+  }
+}
+
 async function pollUntilDone(client, generationId, options = {}) {
   const {
     interval = 5000,
-    timeout = 300000 // 5 minutes default
+    timeout = 300000, // 5 minutes default
+    statusUrl
   } = options;
 
   const startTime = Date.now();
+  const url = statusUrl || `/v1/generate/${generationId}/status`;
 
   while (true) {
     if (Date.now() - startTime > timeout) {
-      throw new Error(`Generation ${generationId} timed out after ${timeout / 1000}s`);
+      throw new PollingTimeoutError(generationId, timeout);
     }
 
-    const result = await client.get(`/v1/generate/${generationId}/status`);
+    const result = await client.get(url);
 
     if (result.state === 'completed') {
       return result;
     }
 
     if (result.state === 'failed') {
-      throw new Error(result.error || 'Generation failed');
+      throw new GenerationFailedError(generationId, result.error);
     }
 
     if (result.state === 'cancelled') {
-      throw new Error('Generation was cancelled');
+      throw new GenerationFailedError(generationId, 'generation was cancelled');
     }
 
     // Wait before next poll
@@ -33,4 +59,4 @@ async function pollUntilDone(client, generationId, options = {}) {
   }
 }
 
-module.exports = { pollUntilDone };
+module.exports = { pollUntilDone, PollingTimeoutError, GenerationFailedError };

package/src/tools/chat.js

@@ -0,0 +1,135 @@
+/* ⛔ 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 { pollUntilDone } = require('../polling');
+
+function registerChatTools(server, client) {
+  // ─── chat_send_message ─────────────────────────────────────
+  server.tool(
+    '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' }
+    },
+    async ({ message, model, session_id, system_prompt, web_search, deep_think, enhance_prompt }) => {
+      const gen = await client.post('/v1/chat', {
+        message,
+        model,
+        session_id,
+        system_prompt,
+        web_search,
+        deep_think,
+        enhance_prompt
+      });
+
+      // Deep think reasoning can run far longer than normal chat. Also grant
+      // extra time when web_search is on (may fetch + analyze multiple pages).
+      const timeout = deep_think ? 600000 : (web_search ? 240000 : 120000);
+
+      const result = await pollUntilDone(client, gen.message_id, {
+        interval: (gen.poll_interval_hint || 2) * 1000,
+        timeout
+      });
+
+      // Chat status shape (from extractResult in kolbo-api sdk/controller.js):
+      // { content, reasoning_content, image_urls?, video_urls?, audio_urls?, model, created_at }
+      const r = result.result || {};
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session_id: gen.session_id,
+            message_id: gen.message_id,
+            model: r.model || gen.model,
+            content: r.content || '',
+            reasoning_content: r.reasoning_content || null,
+            image_urls: r.image_urls || null,
+            video_urls: r.video_urls || null,
+            audio_urls: r.audio_urls || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── chat_list_conversations ───────────────────────────────
+  server.tool(
+    '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' }
+    },
+    async ({ page, limit }) => {
+      const params = new URLSearchParams();
+      if (page) params.set('page', String(page));
+      if (limit) params.set('limit', String(limit));
+
+      const qs = params.toString();
+      const result = await client.get(`/v1/chat/conversations${qs ? '?' + qs : ''}`);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            conversations: result.conversations || [],
+            pagination: result.pagination || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── chat_get_messages ─────────────────────────────────────
+  server.tool(
+    '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' }
+    },
+    async ({ session_id, page, limit }) => {
+      const params = new URLSearchParams();
+      if (page) params.set('page', String(page));
+      if (limit) params.set('limit', String(limit));
+
+      const qs = params.toString();
+      const result = await client.get(
+        `/v1/chat/conversations/${encodeURIComponent(session_id)}/messages${qs ? '?' + qs : ''}`
+      );
+
+      // Trim each message to avoid flooding context.
+      const messages = (result.messages || []).map(m => ({
+        role: m.role,
+        content: m.content,
+        model: m.model?.name || m.model?.identifier || null,
+        status: m.status,
+        created_at: m.createdAt || m.created_at,
+        image_url: m.image_url || null,
+        video_url: m.video_url || null,
+        audio_url: m.audio_url || null
+      }));
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            messages,
+            pagination: result.pagination || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerChatTools };