@kolbo/mcp 1.17.2 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.17.2",
+  "version": "1.19.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/src/client.js

@@ -144,11 +144,21 @@ function readCliAuthKey() {
 // ---------------------------------------------------------------------------
 
 class KolboClient {
-  constructor() {
-    this.baseUrl = resolveApiBase();
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.apiKey]  Explicit key. Takes precedence over env +
+   *   auth store. Used by a remote HTTP host that injects the caller's key per
+   *   request (one KolboClient per request) instead of reading a process-wide
+   *   env var. When set, the auth-store 401 refresh path is disabled — the host
+   *   owns the key lifecycle.
+   * @param {string} [opts.apiBase] Explicit API base URL override.
+   */
+  constructor(opts = {}) {
+    this.baseUrl = opts.apiBase ? String(opts.apiBase).replace(/\/$/, '') : resolveApiBase();
+    this._explicitKey = opts.apiKey || null;
     this._envKey = process.env.KOLBO_API_KEY || null;
     this._authStoreKey = null; // lazy-loaded
-    this.apiKey = this._envKey || this._readAuthStore();
+    this.apiKey = this._explicitKey || this._envKey || this._readAuthStore();
 
     if (!this.apiKey) {
       // No key in env OR auth store. The Kolbo Code parent process should
@@ -171,6 +181,9 @@ class KolboClient {
    * since the MCP server started. Returns true if a new key was found.
    */
   _tryRefreshKey() {
+    // Host-injected per-request key is authoritative — never override it from
+    // the local CLI auth store (which may not even exist in a server context).
+    if (this._explicitKey) return false;
     if (this._envKey) {
       // Env var is set but invalid — can't override it, but try auth store
       const fresh = readCliAuthKey();

package/src/index.js

@@ -70,16 +70,30 @@ const { registerAppBuilderTools } = require('./tools/app_builder');
 const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
 
-async function main() {
-  const client = new KolboClient();
+/**
+ * Build a fully-configured Kolbo MCP server (all tool groups registered)
+ * WITHOUT connecting a transport. This is the reusable core shared by:
+ *   - the stdio entrypoint below (npx / Kolbo Code), and
+ *   - a remote HTTP host (kolbo-api) that creates one server per request with
+ *     the caller's key injected via `opts.apiKey`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.apiKey]   Per-instance Kolbo API key (overrides env).
+ * @param {string} [opts.apiBase]  API base URL override.
+ * @returns {McpServer} a server ready to `.connect(transport)`.
+ */
+function createServer(opts = {}) {
+  const client = new KolboClient(opts);
 
   const server = new McpServer({
     name: 'kolbo',
     version: '1.0.0'
   });
 
-  // Register all tools
-  registerGenerateTools(server, client);
+  // Register all tools. `inlineImages` (off by default) is opt-in: only the
+  // remote HTTP host enables it, so stdio clients (Kolbo Code / Desktop / Cursor)
+  // keep identical text-URL output.
+  registerGenerateTools(server, client, { inlineImages: !!opts.inlineImages });
   registerModelTools(server, client);
   registerChatTools(server, client);
   registerVisualDnaTools(server, client);
@@ -90,12 +104,18 @@ async function main() {
   registerArtifactTools(server, client);
   registerProjectTools(server, client);
 
+  return server;
+}
+
+async function main() {
+  const server = createServer();
+
   // Start the server with stdio transport
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 
-module.exports = { main };
+module.exports = { main, createServer };
 
 // 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

package/src/tools/_shared.js

@@ -240,6 +240,42 @@ 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.'
 );
 
+// ─── Optional inline-image content blocks ────────────────────────────────────
+// When a host opts in (the remote HTTP connector sets inlineImages:true), turn
+// generated IMAGE urls into MCP `image` content blocks so clients render them
+// inline instead of a "Show Image" link. Strictly gated + bounded:
+//   - only runs when opts.enabled is true (stdio/Kolbo Code never enables it,
+//     so their behavior is byte-identical: text URL only);
+//   - caps the number of images and the bytes per image;
+//   - ONLY embeds responses whose content-type is image/* — a video/audio URL
+//     can never be base64-embedded even if mistakenly passed in;
+//   - any fetch/decoding failure silently falls back to URL-only.
+const INLINE_IMG_MAX_COUNT = 4;
+const INLINE_IMG_MAX_BYTES = 8 * 1024 * 1024; // 8 MB per image
+
+async function inlineImageBlocks(urls, opts = {}) {
+  if (!opts || !opts.enabled) return [];
+  if (!Array.isArray(urls) || urls.length === 0) return [];
+  const out = [];
+  for (const url of urls.slice(0, INLINE_IMG_MAX_COUNT)) {
+    try {
+      if (typeof url !== 'string' || !isHttpUrl(url)) continue;
+      const res = await safeFetch(url);
+      if (!res.ok) continue;
+      const contentType = (res.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
+      if (!contentType.startsWith('image/')) continue; // never embed non-images
+      const declaredLen = Number(res.headers.get('content-length') || 0);
+      if (declaredLen && declaredLen > INLINE_IMG_MAX_BYTES) continue;
+      const ab = await res.arrayBuffer();
+      if (ab.byteLength > INLINE_IMG_MAX_BYTES) continue;
+      out.push({ type: 'image', data: Buffer.from(ab).toString('base64'), mimeType: contentType });
+    } catch (_) {
+      // fall back to URL-only for this image
+    }
+  }
+  return out;
+}
+
 module.exports = {
   MAX_FILE_BYTES,
   VISUAL_DNA_MAX_BYTES,
@@ -251,4 +287,5 @@ module.exports = {
   resolveToBuffer,
   creditFields,
   projectIdField,
+  inlineImageBlocks,
 };

package/src/tools/generate.js

@@ -6,9 +6,13 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer, creditFields, projectIdField } = require('./_shared');
+const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks } = require('./_shared');
 
-function registerGenerateTools(server, client) {
+function registerGenerateTools(server, client, options = {}) {
+  // Only enabled by hosts that explicitly opt in (the remote HTTP connector).
+  // stdio hosts (Kolbo Code, Claude Desktop, Cursor) leave this false, so their
+  // tool output is unchanged: a text block with the image URL.
+  const inlineImages = !!options.inlineImages;
   // ─── generate_image ────────────────────────────────────────
   server.tool(
     'generate_image',
@@ -38,6 +42,7 @@ function registerGenerateTools(server, client) {
         timeout: 120000
       });
 
+      const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
       return {
         content: [{
           type: 'text',
@@ -48,7 +53,7 @@ function registerGenerateTools(server, client) {
             prompt_used: result.result.prompt_used,
             _followup_hint: 'If the user asks to edit/change/modify this image next, pass urls[0] to generate_image_edit (free-form edits) or edit_image (upscale/reframe/removebg/enhance_skin/magic_edit). Do NOT call generate_image again.'
           }, null, 2)
-        }]
+        }, ...images]
       };
     }
   );
@@ -85,6 +90,7 @@ function registerGenerateTools(server, client) {
         timeout: heavy ? 240000 : 120000
       });
 
+      const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
       return {
         content: [{
           type: 'text',
@@ -95,7 +101,7 @@ function registerGenerateTools(server, client) {
             prompt_used: result.result.prompt_used,
             _followup_hint: 'If the user asks for another edit on this output, pass urls[0] back into generate_image_edit as source_images. For targeted ops (upscale/reframe/removebg/enhance_skin) use edit_image instead. Do NOT call generate_image from scratch.'
           }, null, 2)
-        }]
+        }, ...images]
       };
     }
   );