@kolbo/mcp 1.12.1 → 1.14.0

package/README.md

@@ -4,7 +4,20 @@ 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
+## Recommended install: the Kolbo Claude Code plugin
+
+The easiest way to use this MCP from Claude Code is the official **Kolbo plugin**, which bundles this server + the routing skill + a first-run API-key prompt — no `settings.json` editing required:
+
+```bash
+claude plugin marketplace add Zoharvan12/kolbo-claude-plugin
+claude plugin install kolbo@kolbo
+```
+
+You'll be prompted for your API key once and it's stored in your OS keychain. The plugin lives in its own tiny repo at [`kolbo-claude-plugin`](https://github.com/Zoharvan12/kolbo-claude-plugin); the routing skill it ships is auto-synced from the canonical source in [`kolbo-code`](https://github.com/Zoharvan12/kolbo-code), so the Claude Code plugin and the Kolbo Code CLI always carry the same skill.
+
+Continue below if you'd rather wire the MCP in by hand (Claude Desktop, Cursor, custom setups).
+
+## Manual setup
 
 ### 1. Get an API Key
 
@@ -115,6 +128,11 @@ 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 |
 |------|-------------|

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@kolbo/mcp",
-  "version": "1.12.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-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.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/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,
           }),
         }],

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.'),