@kolbo/mcp 1.19.2 → 1.20.1

package/README.md

@@ -4,32 +4,44 @@ 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.
 
-## Install in 2 steps (works in Claude Code, Claude Desktop, Cursor, Codex & Kolbo Code)
+## Set up — paste one prompt, or one config block (keyless, no API key)
+
+### Easiest: paste this prompt to your AI
+
+Copy this and paste it to Claude, ChatGPT, Cursor, or any AI assistant — it installs Kolbo itself (picks local config or remote connector based on what it can do):
+
+```
+Set up the Kolbo AI MCP server so you can generate images, video, music and more.
+
+- If you can edit files (Claude Code, Cursor, Claude Desktop): add this to my MCP config, then tell me to restart the app:
+  {"mcpServers":{"kolbo":{"command":"npx","args":["-y","@kolbo/mcp@latest"]}}}
+  On first use a Kolbo login opens in my browser — I'll click Allow (no API key needed).
+- If you support remote connectors (claude.ai, ChatGPT): add the custom connector URL https://api.kolbo.ai/mcp and walk me through logging in.
+
+Then confirm Kolbo is connected and offer to generate a test image of a sunset.
+```
+
+### Or add the config yourself
 
 <!--
   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_..."}}')
+  1. If you can edit files (Claude Code, Cursor, Claude Desktop): write the JSON block below — it has NO api key — into the user's MCP config, merging into any existing "mcpServers":
+     - Claude Code:    .claude/settings.json (or run: claude mcp add kolbo -- npx -y @kolbo/mcp@latest)
      - 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.
+     Then tell the user to restart. On their first generation a Kolbo login opens in the browser — they click Allow (no API key to create).
+  2. If you're a web chat that can't edit files (claude.ai, ChatGPT): tell the user to add the connector URL https://api.kolbo.ai/mcp under Settings → Connectors instead.
+  The JSON config alone enables every tool. The plugin below is an optional slash-command upgrade.
 -->
 
-**Step 1 — Get your API key:** create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) (it starts with `kolbo_live_`).
-
-**Step 2 — Add one config block.** This single block is identical for every MCP client — paste your key in and you're done:
+This single block is identical for every MCP client and carries **no API key** — on first use it logs you in via the browser:
 
 ```json
 {
   "mcpServers": {
     "kolbo": {
       "command": "npx",
-      "args": ["-y", "@kolbo/mcp@latest"],
-      "env": {
-        "KOLBO_API_KEY": "kolbo_live_..."
-      }
+      "args": ["-y", "@kolbo/mcp@latest"]
     }
   }
 }
@@ -37,13 +49,16 @@ Generate images, videos, music, speech, sound effects, multi-scene campaigns, an
 
 | Client | Where the config goes |
 |--------|----------------------|
-| **Claude Code** | `.claude/settings.json` (or `claude mcp add-json kolbo '…'`) |
+| **Claude Code** | `.claude/settings.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
 | **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 |
+| **Kolbo Code** | configured automatically on `kolbo auth login` |
 
-Restart your app so it loads the Kolbo tools. That's the whole install — every tool below now works.
+Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._
+
+### Browser-only (claude.ai / ChatGPT): the connector
+
+No install at all — add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow. Great for generating from text or URLs; to upload your own local files, use the config install above (it runs on your machine).
 
 ### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
 
@@ -187,9 +202,11 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 
 ## Environment Variables
 
+Both are optional — the local install logs in via the browser on first use.
+
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `KOLBO_API_KEY` | Yes | Your Kolbo API key |
+| `KOLBO_API_KEY` | No | Set a `kolbo_live_` key to skip the browser login (create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer)). |
 | `KOLBO_API_URL` | No | Custom API URL (default: `https://api.kolbo.ai/api`) |
 
 ## Links

package/package.json

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

package/src/auth.js

@@ -0,0 +1,155 @@
+/**
+ * Keyless browser login for the LOCAL (stdio) Kolbo MCP server.
+ *
+ * When the server runs on the user's machine with no KOLBO_API_KEY and no
+ * stored credential, the first tool call triggers this: we open the browser to
+ * Kolbo's OAuth login (the same server that powers the remote connector), the
+ * user clicks Allow, and we capture a token via a loopback redirect — no API
+ * key to create or paste. The token is cached so every later run is silent.
+ *
+ * Standard "native app" OAuth: authorization-code + PKCE with a
+ * http://localhost:<port>/callback redirect (already allow-listed by the Kolbo
+ * OAuth server). This path is NOT used by the remote connector (it always
+ * injects the caller's key, and passes allowBrowserLogin:false).
+ */
+
+const http = require('http');
+const crypto = require('crypto');
+const { exec } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function b64url(buf) {
+  return Buffer.from(buf).toString('base64url');
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'win32' ? `start "" "${url}"`
+    : process.platform === 'darwin' ? `open "${url}"`
+    : `xdg-open "${url}"`;
+  try { exec(cmd, () => {}); } catch (_) { /* best effort */ }
+}
+
+// Where we cache the token — same location + shape that client.js reads back
+// (`<xdg-data>/kolbo/auth.json` → { "kolbo@<host>": { type: 'api', key } }).
+function authStorePath() {
+  const dataDir =
+    process.env.XDG_DATA_HOME ||
+    (process.platform === 'win32'
+      ? (process.env.LOCALAPPDATA || path.join(os.homedir(), '.local', 'share'))
+      : process.platform === 'darwin'
+        ? path.join(os.homedir(), 'Library', 'Application Support')
+        : path.join(os.homedir(), '.local', 'share'));
+  return path.join(dataDir, 'kolbo', 'auth.json');
+}
+
+function storeKey(apiHost, key) {
+  try {
+    const file = authStorePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let store = {};
+    try { store = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) {}
+    store[`kolbo@${apiHost}`] = { type: 'api', key, savedAt: new Date().toISOString() };
+    fs.writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+  } catch (_) { /* non-fatal — the key still works for this process */ }
+}
+
+function donePage(ok) {
+  const title = ok ? 'Connected to Kolbo' : 'Connection cancelled';
+  const sub = ok ? 'You can close this tab and return to your app.' : 'You can close this tab.';
+  const mark = ok ? '✓' : '✕';
+  return `<!doctype html><meta charset="utf-8"><title>${title}</title>` +
+    `<body style="margin:0;font-family:Inter,system-ui,sans-serif;background:#05050f;color:#fff;` +
+    `display:flex;align-items:center;justify-content:center;height:100vh">` +
+    `<div style="text-align:center"><div style="font-size:42px;color:#8B5CF6;margin-bottom:8px">${mark}</div>` +
+    `<h2 style="margin:0 0 6px">${title}</h2><p style="opacity:.55;font-size:14px">${sub}</p></div></body>`;
+}
+
+/**
+ * Run the interactive browser login. Resolves with the kolbo_live_ key.
+ * @param {object} opts
+ * @param {string} opts.apiBase  e.g. https://api.kolbo.ai/api
+ */
+async function browserLogin({ apiBase }) {
+  // The OAuth endpoints live at the host root, not under /api.
+  const oauthBase = apiBase.replace(/\/api\/?$/, '');
+  let apiHost = 'api.kolbo.ai';
+  try { apiHost = new URL(apiBase).host; } catch (_) {}
+
+  const verifier = b64url(crypto.randomBytes(32));
+  const challenge = b64url(crypto.createHash('sha256').update(verifier).digest());
+  const state = b64url(crypto.randomBytes(16));
+
+  // Loopback callback server on a random free port.
+  const server = http.createServer();
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const port = server.address().port;
+  const redirectUri = `http://localhost:${port}/callback`;
+
+  try {
+    // 1. Dynamic client registration (public + PKCE).
+    const regRes = await fetch(`${oauthBase}/oauth/register`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ client_name: 'Kolbo MCP (local)', redirect_uris: [redirectUri] }),
+    });
+    if (!regRes.ok) throw new Error(`client registration failed (${regRes.status})`);
+    const { client_id } = await regRes.json();
+
+    // 2. Wait for the browser redirect to hit our loopback server.
+    const codePromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('login timed out (5 min)')), 5 * 60 * 1000);
+      server.on('request', (req, resp) => {
+        let u;
+        try { u = new URL(req.url, redirectUri); } catch (_) { resp.writeHead(400); resp.end(); return; }
+        if (u.pathname !== '/callback') { resp.writeHead(404); resp.end(); return; }
+        clearTimeout(timer);
+        const code = u.searchParams.get('code');
+        const st = u.searchParams.get('state');
+        const err = u.searchParams.get('error');
+        resp.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        resp.end(donePage(!err && !!code));
+        if (err) return reject(new Error(`login denied: ${err}`));
+        if (!code || st !== state) return reject(new Error('login: invalid callback'));
+        resolve(code);
+      });
+    });
+
+    // 3. Open the consent/login page.
+    const authUrl =
+      `${oauthBase}/oauth/authorize?response_type=code&client_id=${encodeURIComponent(client_id)}` +
+      `&redirect_uri=${encodeURIComponent(redirectUri)}&code_challenge=${challenge}` +
+      `&code_challenge_method=S256&state=${state}&scope=kolbo`;
+    openBrowser(authUrl);
+    process.stderr.write(
+      `\n[kolbo] Connect your Kolbo account in the browser. If it didn't open, visit:\n${authUrl}\n\n`
+    );
+
+    const code = await codePromise;
+
+    // 4. Exchange the code (with the PKCE verifier) for the token.
+    const tokRes = await fetch(`${oauthBase}/oauth/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        grant_type: 'authorization_code',
+        code,
+        code_verifier: verifier,
+        redirect_uri: redirectUri,
+        client_id,
+      }),
+    });
+    if (!tokRes.ok) throw new Error(`token exchange failed (${tokRes.status})`);
+    const tok = await tokRes.json();
+    if (!tok.access_token) throw new Error('login: no access_token returned');
+
+    storeKey(apiHost, tok.access_token);
+    return tok.access_token;
+  } finally {
+    try { server.close(); } catch (_) {}
+  }
+}
+
+module.exports = { browserLogin };

package/src/client.js

@@ -158,17 +158,45 @@ class KolboClient {
     this._explicitKey = opts.apiKey || null;
     this._envKey = process.env.KOLBO_API_KEY || null;
     this._authStoreKey = null; // lazy-loaded
+    // Local stdio servers (raw `npx @kolbo/mcp` in Claude Desktop / Code / Cursor)
+    // may start with no key and log in via the browser on first use. Disabled when:
+    //   - the host opts out (remote HTTP connector passes allowBrowserLogin:false —
+    //     it always injects the caller's key, and opening a browser on a server is
+    //     nonsensical), or
+    //   - we're spawned by Kolbo Code (it sets KOLBO_CALLER_SESSION_ID and runs its
+    //     OWN in-app sign-in off the [KOLBO_AUTH_MISSING] error — don't double up).
+    this._allowBrowserLogin =
+      opts.allowBrowserLogin !== undefined
+        ? opts.allowBrowserLogin
+        : !process.env.KOLBO_CALLER_SESSION_ID;
+    this._loginPromise = null;
     this.apiKey = this._explicitKey || this._envKey || this._readAuthStore();
 
-    if (!this.apiKey) {
-      // No key in env OR auth store. The Kolbo Code parent process should
-      // never spawn us in this state (it injects the key into env after the
-      // user signs in). If this fires, the parent will catch it via the
-      // [KOLBO_AUTH_MISSING] tag and surface the in-app sign-in flow.
+    if (!this.apiKey && !this._allowBrowserLogin) {
       throw new Error(
         'Kolbo API key not found. Sign in to Kolbo to continue. [KOLBO_AUTH_MISSING]'
       );
     }
+    // When allowBrowserLogin is on and there's no key yet, we DON'T throw —
+    // the first request triggers an interactive browser login (see _ensureLogin).
+  }
+
+  /**
+   * Ensure we have a key before a request. If none, run the one-time browser
+   * login (single-flight so concurrent first calls share one login window).
+   */
+  async _ensureLogin() {
+    if (this.apiKey) return;
+    if (!this._allowBrowserLogin) {
+      throw new Error('Kolbo API key not found. Sign in to Kolbo to continue. [KOLBO_AUTH_MISSING]');
+    }
+    if (!this._loginPromise) {
+      const { browserLogin } = require('./auth');
+      this._loginPromise = browserLogin({ apiBase: this.baseUrl })
+        .then((key) => { this.apiKey = key; this._explicitKey = key; return key; })
+        .catch((err) => { this._loginPromise = null; throw err; });
+    }
+    await this._loginPromise;
   }
 
   _readAuthStore() {
@@ -202,6 +230,7 @@ class KolboClient {
   }
 
   async request(method, reqPath, body = null) {
+    if (!this.apiKey) await this._ensureLogin();
     const result = await this._doRequest(method, reqPath, body);
 
     // On 401, try re-reading auth store and retry once
@@ -291,6 +320,7 @@ class KolboClient {
   }
 
   async postMultipart(reqPath, formData) {
+    if (!this.apiKey) await this._ensureLogin();
     const result = await this._doMultipart(reqPath, formData);
     if (result._status === 401 && this._tryRefreshKey()) {
       return this._doMultipart(reqPath, formData);