@kolbo/mcp 1.12.0 → 1.13.0

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@kolbo/mcp",
-  "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": {
-    "kolbo-mcp": "./bin/kolbo-mcp.js"
-  },
-  "scripts": {
-    "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",
-    "mcp",
-    "ai",
-    "image-generation",
-    "video-generation",
-    "music-generation",
-    "text-to-speech",
-    "claude-code",
-    "claude-desktop",
-    "model-context-protocol"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Zoharvan12/kolbo-mcp"
-  },
-  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
-  "author": "Kolbo AI <support@kolbo.ai>",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "src/",
-    "bin/",
-    "README.md"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "form-data": "^4.0.5",
-    "zod": "^3.25.0"
-  },
-  "overrides": {
-    "hono": "^4.12.12",
-    "@hono/node-server": "^1.19.13",
-    "path-to-regexp": "^8.4.2"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@kolbo/mcp",
+  "version": "1.13.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",
+    "smoke": "node scripts/smoke.js",
+    "check-parity": "node scripts/check-parity.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js"
+  },
+  "keywords": [
+    "kolbo",
+    "mcp",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "music-generation",
+    "text-to-speech",
+    "claude-code",
+    "claude-desktop",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zoharvan12/kolbo-mcp"
+  },
+  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
+  "author": "Kolbo AI <support@kolbo.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "form-data": "^4.0.5",
+    "zod": "^3.25.0"
+  },
+  "overrides": {
+    "hono": "^4.12.12",
+    "@hono/node-server": "^1.19.13",
+    "path-to-regexp": "^8.4.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -93,7 +93,15 @@ async function main() {
   await server.connect(transport);
 }
 
-main().catch(err => {
-  console.error('Failed to start Kolbo MCP server:', err);
-  process.exit(1);
-});
+module.exports = { main };
+
+// Auto-run when invoked directly (e.g. `node src/index.js` or via the published
+// bin/kolbo-mcp.js wrapper). Consumers that `require()` this module to embed it
+// inside another process (the Kolbo Code CLI's `kolbo mcp serve` subcommand)
+// should call `main()` themselves.
+if (require.main === module || require.main?.filename?.endsWith('kolbo-mcp.js')) {
+  main().catch(err => {
+    console.error('Failed to start Kolbo MCP server:', err);
+    process.exit(1);
+  });
+}

package/src/polling.js

@@ -25,6 +25,25 @@ class GenerationFailedError extends Error {
   }
 }
 
+// HTTP status codes / fetch failure modes we treat as transient when
+// polling. The job is almost always still running on the server (or about
+// to come back up) — bailing out makes the agent give up on a generation
+// that completes 2 seconds later.
+const TRANSIENT_STATUS_CODES = new Set([0, 408, 425, 429, 500, 502, 503, 504, 522, 524]);
+
+function isTransientPollError(err) {
+  if (!err) return false;
+  // fetch() rejects with a TypeError on network failure (ECONNREFUSED,
+  // ECONNRESET, DNS failure, kolbo-api restart, etc.) — no `status` on
+  // the error object.
+  if (err.name === 'TypeError') return true;
+  if (err.code === 'ECONNRESET' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT' || err.code === 'EPIPE') return true;
+  // KolboApiError tags status on the options object.
+  const status = err.status ?? err.options?.status;
+  if (typeof status === 'number' && TRANSIENT_STATUS_CODES.has(status)) return true;
+  return false;
+}
+
 async function pollUntilDone(client, generationId, options = {}) {
   const {
     interval = 5000,
@@ -34,13 +53,36 @@ async function pollUntilDone(client, generationId, options = {}) {
 
   const startTime = Date.now();
   const url = statusUrl || `/v1/generate/${encodeURIComponent(generationId)}/status`;
+  let transientFailures = 0;
 
   while (true) {
     if (Date.now() - startTime > timeout) {
       throw new PollingTimeoutError(generationId, timeout);
     }
 
-    const result = await client.get(url);
+    let result;
+    try {
+      result = await client.get(url);
+      transientFailures = 0; // reset on successful poll
+    } catch (err) {
+      // kolbo-api restart, transient network blip, rate-limit, 5xx —
+      // the job is still alive on the server (or coming back). Don't
+      // abandon the polling loop just because one status check failed:
+      // wait a bit longer and try again. After ~30 consecutive failures
+      // (~2.5 minutes at the 5s base interval) we still surface the
+      // last error so a truly dead backend doesn't loop forever.
+      if (isTransientPollError(err)) {
+        transientFailures++;
+        if (transientFailures > 30) {
+          throw err;
+        }
+        const backoff = Math.min(interval * Math.pow(1.5, Math.min(transientFailures - 1, 5)), 30000);
+        await new Promise((resolve) => setTimeout(resolve, backoff));
+        continue;
+      }
+      // Non-transient (auth, 4xx other than 408/425/429) — bubble up.
+      throw err;
+    }
 
     if (result.state === 'completed') {
       return result;

package/src/tools/visual_dna.js

@@ -20,7 +20,7 @@ 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: z.string().describe('Name of the Visual DNA profile'),
+      name: z.string().describe('Name of the Visual DNA profile. **Pick a short, lowercase, no-space single token** (e.g. `maya`, `tokyo_neon`, `brand_red`, `esther_model`) — never names with spaces (`Sarah Johnson` ❌). The user/LLM types this as `@<name>` inside generation prompts, and the @ parser stops at the first space, so `@Sarah Johnson` matches only `Sarah` and the binding silently drops. Multi-word concepts should use underscores or be a single token. Names are case-insensitive on lookup, but **reserved** values rejected on creation: `Image1`, `Image2`, …, `Video1`, …, `Audio1`, … (any-language characters allowed; max 100 chars).'),
       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.'),