@kolbo/mcp 1.16.4 → 1.17.1

package/README.md

@@ -4,15 +4,22 @@ Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Deskt
 
 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
+## Install in 2 steps (works in Claude Code, Claude Desktop, Cursor, Codex & Kolbo Code)
 
-### 1. Get an API Key
+<!--
+  AI ASSISTANT SETUP INSTRUCTIONS — if you are an AI agent reading this to set up Kolbo for a user, do exactly this:
+  1. Ask the user for their Kolbo API key (starts with `kolbo_live_`). They get one at https://app.kolbo.ai/developer. Do not continue without it.
+  2. Write the JSON block below into the user's MCP config, merging into any existing "mcpServers":
+     - Claude Code:    .claude/settings.json (or run: claude mcp add-json kolbo '{"command":"npx","args":["-y","@kolbo/mcp@latest"],"env":{"KOLBO_API_KEY":"kolbo_live_..."}}')
+     - Claude Desktop: claude_desktop_config.json
+     - Cursor:         .cursor/mcp.json
+  3. Tell the user to fully restart their app so the Kolbo tools load, then they can just say "generate an image of...".
+  Ignore the optional plugin section below unless the user specifically wants slash-commands — the JSON config alone is enough to use every tool.
+-->
 
-Create a key at [app.kolbo.ai](https://app.kolbo.ai) or via the [API](https://docs.kolbo.ai/developer-api).
+**Step 1 — Get your API key:** create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) (it starts with `kolbo_live_`).
 
-### 2. Add to Claude Code
-
-Add to `.claude/settings.json`:
+**Step 2 — Add one config block.** This single block is identical for every MCP client — paste your key in and you're done:
 
 ```json
 {
@@ -28,22 +35,68 @@ Add to `.claude/settings.json`:
 }
 ```
 
-### 3. Use it
+| Client | Where the config goes |
+|--------|----------------------|
+| **Claude Code** | `.claude/settings.json` (or `claude mcp add-json kolbo '…'`) |
+| **Claude Desktop** | `claude_desktop_config.json` |
+| **Cursor** | `.cursor/mcp.json` |
+| **Codex / other MCP agents** | that agent's MCP config file |
+| **Kolbo Code** | configured automatically on `kolbo auth login` — nothing to do |
+
+Restart your app so it loads the Kolbo tools. That's the whole install — every tool below now works.
+
+### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
+
+The config above is all you need. If you want one-word slash-commands (`/kolbo:marketing-studio`, `/kolbo:product-photoshoot`, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:
+
+```bash
+# Claude Code (also writes the MCP config for you, so you can skip Step 2 above)
+claude plugin marketplace add Zoharvan12/kolbo-skills
+claude plugin install kolbo@kolbo
+
+# Cursor / Codex / any agent (cross-agent installer)
+npx skills add Zoharvan12/kolbo-skills
+```
+
+The skill content is the same canonical routing logic that ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).
 
-Just ask Claude naturally:
+### Use it
 
+Just ask your agent naturally:
+
+**Generation**
 - *"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"*
 - *"Read this out loud with a British female voice"*
+
+**Marketing & UGC**
+- *"Make me a UGC ad for my sneaker brand — 9:16, talking-head style"*
+- *"TV spot for my new beverage, 15 seconds, cinematic"*
+- *"Unboxing video for this product photo"*
+
+**Brand & product imagery**
+- *"Pinterest pin for my candle brand, cottagecore mood"*
+- *"Hero banner for my landing page, wide format"*
+- *"Lifestyle shot of my product in a kitchen"*
+- *"4 ad creative variants for Meta and TikTok"*
+
+**Marketplace listings**
+- *"Generate Amazon main image + 5 secondary images for my product"*
+- *"Full A+ content set for my Shopify listing"*
+
+**Analysis & utility**
 - *"Ask Claude about the latest AI news with web search on"*
 - *"Analyze this video and tell me what prompts are shown on screen"*
 - *"What's in this image?"*
 - *"Create a Visual DNA profile called 'Alex' from these images"*
+- *"Use the same brand as last time"* (loads a persisted brand kit from the workspace)
+
+Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
 
-## Available Tools (51)
+## Available Tools (52)
 
 **Generation**
 | Tool | Description |
@@ -67,6 +120,8 @@ Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard
 
 Every generation tool also accepts an optional `resolution` arg. Images use `"1K"` (~1024px) / `"2K"` (Full HD) / `"3K"` (QHD) / `"4K"` (UHD); videos use vertical-pixel tiers like `"720p"` / `"1080p"` / `"1440p"` / `"2160p"`. Values are model-dependent — call `list_models` and read the chosen model's `supported_resolutions` and `resolutionMultipliers`. Omit to use the model default.
 
+Every generation tool also accepts an optional `project_id` arg that routes the generation into a specific project (owned or shared with edit+). Call `list_projects` to discover IDs. When omitted, generations land in the user's auto-created "API Generations" project.
+
 **Chat & Vision**
 | Tool | Description |
 |------|-------------|
@@ -115,12 +170,18 @@ Every generation tool also accepts an optional `resolution` arg. Images use `"1K
 | `move_folder_contents` | Move every item in a folder to a project |
 | `get_media_stats` | Counts + storage bytes per type (optionally per project) |
 
+**Artifacts**
+| Tool | Description |
+|------|-------------|
+| `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
+
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|
 | `list_models` | Current model catalog with costs and capabilities |
 | `list_voices` | TTS voices (presets + cloned) |
 | `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
+| `list_projects` | List owned + shared projects (id, name, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
 | `check_credits` | Check credit balance |
 | `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
 

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,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.16.4",
+  "version": "1.17.1",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -27,8 +27,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Zoharvan12/kolbo-code",
-    "directory": "packages/kolbo-mcp"
+    "url": "https://github.com/Zoharvan12/kolbo-mcp"
   },
   "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
   "author": "Kolbo AI <support@kolbo.ai>",

package/src/client.js

@@ -139,63 +139,6 @@ 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
 // ---------------------------------------------------------------------------
@@ -246,31 +189,13 @@ class KolboClient {
   }
 
   async request(method, reqPath, body = null) {
-    await acquireSlot();
-    try {
-      const result = await this._doRequestWithRetry(method, reqPath, body);
+    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._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;
+    // 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) {
@@ -307,13 +232,6 @@ 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;
@@ -360,29 +278,11 @@ class KolboClient {
   }
 
   async postMultipart(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;
+    const result = await this._doMultipart(reqPath, formData);
+    if (result._status === 401 && this._tryRefreshKey()) {
+      return this._doMultipart(reqPath, formData);
     }
+    return result;
   }
 
   async _doMultipart(reqPath, formData) {
@@ -419,13 +319,6 @@ 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/index.js

@@ -68,6 +68,7 @@ const { registerMediaTools } = require('./tools/media');
 const { registerPresetTools } = require('./tools/presets');
 const { registerAppBuilderTools } = require('./tools/app_builder');
 const { registerArtifactTools } = require('./tools/artifacts');
+const { registerProjectTools } = require('./tools/projects');
 
 async function main() {
   const client = new KolboClient();
@@ -87,6 +88,7 @@ async function main() {
   registerPresetTools(server, client);
   registerAppBuilderTools(server, client);
   registerArtifactTools(server, client);
+  registerProjectTools(server, client);
 
   // Start the server with stdio transport
   const transport = new StdioServerTransport();

package/src/polling.js

@@ -6,10 +6,9 @@ class PollingTimeoutError extends Error {
   constructor(generationId, timeoutMs) {
     const seconds = Math.round(timeoutMs / 1000);
     super(
-      `Generation timed out after ${seconds}s of polling. The generation is STILL RUNNING on the server — ` +
-      `DO NOT re-issue the original generation tool. A retry would burn credits while the original keeps producing the result you already paid for. ` +
-      `Instead, IMMEDIATELY call get_generation_status with generation_id="${generationId}" (it block-polls server-side, no need to loop). ` +
-      `Videos, deep-think chat, and large batches can legitimately take 5–15+ minutes beyond the default polling window.`
+      `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;

package/src/tools/_shared.js

@@ -230,6 +230,16 @@ function creditFields(polledResult) {
   return out;
 }
 
+// Shared zod schema for the optional `project_id` arg every generation tool
+// accepts. Keep this in one place so the description never drifts across the
+// 17 tools that use it. When omitted, the generation lands in the user's
+// auto-created "API Generations" project. Call `list_projects` first to
+// resolve a name → ObjectId.
+const { z } = require('zod');
+const projectIdField = z.string().optional().describe(
+  'Project ObjectId to drop this generation into. Call `list_projects` to discover IDs (the API has no concept of project names — only ObjectIds). Omit to use the user\'s default "API Generations" project. Requires owner / edit / full permission on the project; view-only is rejected.'
+);
+
 module.exports = {
   MAX_FILE_BYTES,
   VISUAL_DNA_MAX_BYTES,
@@ -240,4 +250,5 @@ module.exports = {
   guessContentType,
   resolveToBuffer,
   creditFields,
+  projectIdField,
 };

package/src/tools/artifacts.js

@@ -9,23 +9,29 @@ function registerArtifactTools(server, client) {
   // ─── publish_html_artifact ─────────────────────────────────────
   server.tool(
     'publish_html_artifact',
-    'Publish an HTML page (or SVG / Mermaid diagram) to kolbo.ai and return a public shareable URL. Use this when the user explicitly asks to share, publish, or deploy a built artifact so they can send the URL to someone. The content is hosted at https://sites.kolbo.ai/<slug>; the page is served with restrictive CSP (no fetch/XHR/form-action) so it cannot exfiltrate data. Identical content uploaded twice returns the same URL (server dedup).',
+    'Publish an HTML page (or SVG / Mermaid diagram) to kolbo.ai and return a public shareable URL. Use this when the user explicitly asks to share, publish, or deploy a built artifact so they can send the URL to someone. The content is hosted at https://sites.kolbo.ai/<slug>; the page is served with restrictive CSP (no fetch/XHR/form-action) so it cannot exfiltrate data. Identical content uploaded twice returns the same URL (server dedup). To update a previously-published page in place (keeping the same URL), pass the `share_token` returned from the prior publish — the old content is preserved in version history.',
     {
       title: z.string().describe('Human-friendly title for the page (also used to generate the SEO slug). Keep under ~60 chars.'),
       content: z.string().describe('The raw artifact body. For type="html" this is a full HTML document (DOCTYPE + html/head/body). For "svg" it is an <svg> document. For "mermaid" it is the Mermaid source text.'),
       type: z.enum(['html', 'svg', 'mermaid']).optional().describe('Artifact type. Default: "html".'),
       allow_js: z.boolean().optional().describe('Allow inline <script> execution on the published page. Default: false. Required for Tailwind JIT, Chart.js, Three.js, React-from-CDN etc.'),
+      share_token: z.string().optional().describe('Optional. Pass the `shareToken` returned from a previous publish to update that artifact in place. The public URL stays the same and the old content is moved into version history. Omit this on the first publish.'),
     },
-    async ({ title, content, type, allow_js }) => {
+    async ({ title, content, type, allow_js, share_token }) => {
       if (!title || !title.trim()) throw new Error('title is required');
       if (typeof content !== 'string' || !content.length) throw new Error('content is required');
 
-      const result = await client.post('/artifact/quick-share', {
+      const body = {
         title: title.trim(),
         content,
         type: type || 'html',
         allowJs: allow_js === true,
-      });
+      };
+      if (typeof share_token === 'string' && share_token.trim()) {
+        body.shareToken = share_token.trim();
+      }
+
+      const result = await client.post('/artifact/quick-share', body);
 
       const artifact = result?.data || {};
       const slug = artifact.shareableSlug || artifact.shareToken;
@@ -49,6 +55,7 @@ function registerArtifactTools(server, client) {
             shareToken: artifact.shareToken,
             shareableSlug: slug,
             duplicate: result?.duplicate === true,
+            updated: result?.updated === true,
             title: artifact.title,
           }),
         }],