@kolbo/mcp 1.13.0 → 1.14.1

package/bin/kolbo-mcp.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 require('../src/index.js');

package/package.json

@@ -1,55 +1,56 @@
-{
-  "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"
-  }
-}
+{
+  "name": "@kolbo/mcp",
+  "version": "1.14.1",
+  "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-code",
+    "directory": "packages/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/client.js

@@ -139,6 +139,63 @@ function readCliAuthKey() {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Burst control
+// ---------------------------------------------------------------------------
+// Caps in-flight requests so multi-step tool calls (file upload + generate +
+// poll status) don't fan out past the kolbo-api global rate limit. The SDK
+// tier on the server is 5000 req/min per API key; 6 in-flight × typical 2s
+// latency keeps us at ~180/min — plenty of headroom.
+const MAX_CONCURRENT = 6;
+let inFlight = 0;
+const waiting = [];
+
+function acquireSlot() {
+  if (inFlight < MAX_CONCURRENT) {
+    inFlight++;
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => waiting.push(resolve));
+}
+
+function releaseSlot() {
+  if (waiting.length > 0) {
+    waiting.shift()();
+  } else {
+    inFlight = Math.max(0, inFlight - 1);
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Parse retry hint from a 429 response. Honors (in order):
+ *   - body.retryAfter (kolbo-api shape)
+ *   - Retry-After header (RFC, seconds)
+ *   - RateLimit-Reset header (seconds until reset)
+ * Falls back to 5s. Caps at 60s so we don't hang the tool call forever.
+ */
+function parseRetryAfter(response, body) {
+  let seconds = null;
+  if (body && typeof body.retryAfter === 'number') seconds = body.retryAfter;
+  if (seconds == null) {
+    const ra = response.headers.get('retry-after');
+    if (ra) {
+      const n = Number(ra);
+      if (Number.isFinite(n)) seconds = n;
+    }
+  }
+  if (seconds == null) {
+    const reset = response.headers.get('ratelimit-reset');
+    if (reset) {
+      const n = Number(reset);
+      if (Number.isFinite(n)) seconds = n;
+    }
+  }
+  if (seconds == null || !Number.isFinite(seconds) || seconds <= 0) seconds = 5;
+  return Math.min(seconds, 60) * 1000;
+}
+
 // ---------------------------------------------------------------------------
 // HTTP client
 // ---------------------------------------------------------------------------
@@ -189,13 +246,31 @@ class KolboClient {
   }
 
   async request(method, reqPath, body = null) {
-    const result = await this._doRequest(method, reqPath, body);
+    await acquireSlot();
+    try {
+      const result = await this._doRequestWithRetry(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);
+      // On 401, try re-reading auth store and retry once
+      if (result._status === 401 && this._tryRefreshKey()) {
+        return this._doRequestWithRetry(method, reqPath, body);
+      }
+      return result;
+    } finally {
+      releaseSlot();
+    }
+  }
+
+  async _doRequestWithRetry(method, reqPath, body = null) {
+    try {
+      return await this._doRequest(method, reqPath, body);
+    } catch (err) {
+      if (err instanceof KolboApiError && err.status === 429) {
+        const delay = err.data?._kolboRetryAfterMs ?? 5000;
+        await sleep(delay);
+        return this._doRequest(method, reqPath, body);
+      }
+      throw err;
     }
-    return result;
   }
 
   async _doRequest(method, reqPath, body = null) {
@@ -232,6 +307,13 @@ class KolboClient {
       });
     }
 
+    if (response.status === 429) {
+      throw new KolboApiError('Rate limited by Kolbo API. Retrying after backoff.', {
+        status: 429,
+        data: { ...(data || {}), _kolboRetryAfterMs: parseRetryAfter(response, data) },
+      });
+    }
+
     if (!response.ok || data.success === false) {
       const message = data.error || data.message || `API error: ${response.status}`;
       const code = data.code || null;
@@ -278,11 +360,29 @@ class KolboClient {
   }
 
   async postMultipart(reqPath, formData) {
-    const result = await this._doMultipart(reqPath, formData);
-    if (result._status === 401 && this._tryRefreshKey()) {
-      return this._doMultipart(reqPath, formData);
+    await acquireSlot();
+    try {
+      const result = await this._doMultipartWithRetry(reqPath, formData);
+      if (result._status === 401 && this._tryRefreshKey()) {
+        return this._doMultipartWithRetry(reqPath, formData);
+      }
+      return result;
+    } finally {
+      releaseSlot();
+    }
+  }
+
+  async _doMultipartWithRetry(reqPath, formData) {
+    try {
+      return await this._doMultipart(reqPath, formData);
+    } catch (err) {
+      if (err instanceof KolboApiError && err.status === 429) {
+        const delay = err.data?._kolboRetryAfterMs ?? 5000;
+        await sleep(delay);
+        return this._doMultipart(reqPath, formData);
+      }
+      throw err;
     }
-    return result;
   }
 
   async _doMultipart(reqPath, formData) {
@@ -319,6 +419,13 @@ class KolboClient {
       });
     }
 
+    if (response.status === 429) {
+      throw new KolboApiError('Rate limited by Kolbo API. Retrying after backoff.', {
+        status: 429,
+        data: { ...(data || {}), _kolboRetryAfterMs: parseRetryAfter(response, data) },
+      });
+    }
+
     if (!response.ok || data.success === false) {
       const message = data.error || data.message || `API error: ${response.status}`;
       const code = data.code || null;

package/src/tools/generate.js

@@ -5,7 +5,7 @@
 
 const { z } = require('zod');
 const FormData = require('form-data');
-const { pollUntilDone } = require('../polling');
+const { pollUntilDone, PollingTimeoutError } = require('../polling');
 const { resolveToBuffer, creditFields } = require('./_shared');
 
 function registerGenerateTools(server, client) {
@@ -383,13 +383,38 @@ function registerGenerateTools(server, client) {
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     '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).',
+    'Resume polling a generation after a timeout. Pass the generation_id from a prior generation tool that timed out. This call BLOCKS server-side, polling internally — you do NOT need to call it again in a loop. Defaults to a 10-minute internal poll which covers most image edits and short videos; pass `wait_seconds` up to 1700 (~28 min) for long video / 3D / batch generations. If it returns with `still_pending: true`, the generation is genuinely slow — STOP calling this tool, tell the user the generation is still running, and resume on the next user turn. Never call this tool more than ONCE per generation_id consecutively.',
     {
-      generation_id: z.string().describe('The generation ID to check')
+      generation_id: z.string().describe('The generation ID to check'),
+      wait_seconds: z.number().int().min(10).max(1700).optional().describe('How long to block-poll internally before giving up (10–1700 seconds, default 600). Use higher values for video / 3D / large batches that can legitimately take 15+ minutes.'),
     },
-    async ({ generation_id }) => {
-      const result = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`);
-
+    async ({ generation_id, wait_seconds }) => {
+      const timeoutMs = (wait_seconds ?? 600) * 1000;
+      let result;
+      try {
+        result = await pollUntilDone(client, generation_id, {
+          interval: 5000,
+          timeout: timeoutMs,
+        });
+      } catch (err) {
+        if (err instanceof PollingTimeoutError) {
+          const current = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`).catch(() => null);
+          const minutes = Math.round(timeoutMs / 60000);
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                generation_id,
+                state: current?.state ?? 'unknown',
+                still_pending: true,
+                waited_seconds: Math.round(timeoutMs / 1000),
+                _note: `Polled for ${minutes} minute(s) — generation is taking longer than usual. STOP calling get_generation_status now. Tell the user the generation is still running and ask them to prompt you to check again later. Do NOT loop.`,
+              }, null, 2),
+            }],
+          };
+        }
+        throw err;
+      }
       return {
         content: [{
           type: 'text',