@kolbo/mcp 1.81.11 → 1.82.0

package/package.json

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

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@c3b231a, the single source of truth.
+This tree is mirrored from kolbo-code@9c91cff, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.9.11
+version: 0.9.10
 name: kolbo
 description: |
   Generate, edit, analyze, and direct creative media through Kolbo AI: images,
@@ -57,7 +57,6 @@ Then generate **only** with the confirmed parameters. If the user changes an opt
 - **Batch totalling 100+ credits**: run `check_credits` first.
 - **Quote real cost**: after firing, log `credits_used` (from the tool result) to `.kolbo/production.md` — never `base × count`.
 - **Never state "credits remaining" from arithmetic** (opening balance − generation costs). Coding/chat usage deducts credits too, so the math is always wrong. Report cost only; if the user asks for their balance, call `check_credits` fresh at that moment.
-- **Out of credits → `show_plans`.** A generation refused for credits already returns the upgrade card automatically — do NOT retry it, and do not re-run the tool "to be sure". Call `show_plans` yourself when the user asks about pricing, plans, upgrading, or how to get more credits. Prices are live and promo-adjusted; never quote them from memory. The user completes any purchase themselves on app.kolbo.ai/pricing — you cannot buy for them.
 
 For multi-scene / batch work this pairs with `generate_creative_director` (see below) — still confirm the brief first.
 
@@ -123,7 +122,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 ### Discovery, Library, Visual DNA, Moodboards, Chat, Publishing
 | Tool | Purpose |
 |------|---------|
-| `list_models` / `list_voices` / `check_credits` / `show_plans` / `get_generation_status` / `cancel_generation` / `get_session_usage` | Discovery + status. `list_models` with no args returns the recommended shortlist out of ~428 — pass `type` for a full category with per-model caps. `cancel_generation` stops an in-flight job and refunds what it can: use it when the user changes their mind mid-generation instead of letting it run. `show_plans` renders the balance + upgrade card for pricing/plan/upgrade questions. |
+| `list_models` / `list_voices` / `check_credits` / `get_generation_status` / `cancel_generation` / `get_session_usage` | Discovery + status. `list_models` with no args returns the recommended shortlist out of ~428 — pass `type` for a full category with per-model caps. `cancel_generation` stops an in-flight job and refunds what it can: use it when the user changes their mind mid-generation instead of letting it run. |
 | `upload_media` / `create_upload_ticket` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md`. Getting a LOCAL file in depends on where the server runs: `upload_media` with a path only works on a local (stdio) install; over a remote connector use `create_upload_ticket` and POST the file yourself. |
 | `create_visual_dna` / `update_visual_dna` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — see `workflows/visual-dna.md`. Edit with `update_visual_dna`; never delete+recreate. |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays + sheet presets — see **Preset contract** in Core Workflow. Never omit `preset_id` after claiming a preset was used. |

package/skill/VERSION

@@ -1 +1 @@
-0.9.11
+0.9.10

package/src/apps/index.js

@@ -22,6 +22,7 @@ const { catalogWidgetHtml } = require('./widgets/catalog');
 const { transcriptWidgetHtml } = require('./widgets/transcript');
 const { uploadWidgetHtml } = require('./widgets/upload');
 const { listWidgetHtml } = require('./widgets/list');
+const { plansWidgetHtml } = require('./widgets/plans');
 
 const UI = {
   generation: 'ui://kolbo/generation.html',
@@ -30,6 +31,7 @@ const UI = {
   transcript: 'ui://kolbo/transcript.html',
   upload: 'ui://kolbo/upload.html',
   list: 'ui://kolbo/list.html',
+  plans: 'ui://kolbo/plans.html',
 };
 
 const WIDGET_BUILDERS = {
@@ -39,6 +41,7 @@ const WIDGET_BUILDERS = {
   [UI.transcript]: transcriptWidgetHtml,
   [UI.upload]: uploadWidgetHtml,
   [UI.list]: listWidgetHtml,
+  [UI.plans]: plansWidgetHtml,
 };
 
 // Widgets are pure functions of source — build once per process.
@@ -105,6 +108,7 @@ function registerApps(server) {
     [UI.transcript, 'Kolbo Transcription Widget'],
     [UI.upload, 'Kolbo Upload Widget'],
     [UI.list, 'Kolbo List Widget'],
+    [UI.plans, 'Kolbo Plans Widget'],
   ]) {
     registerAppResource(
       server, name, uri,
@@ -630,6 +634,7 @@ const TOOL_WIDGETS = {
   list_docs: UI.list,
   list_media_folders: UI.list,
   list_visual_dna_folders: UI.list,
+  show_plans: UI.plans,
   list_project_assets: UI.list,
 };
 

package/src/apps/theme.js

@@ -159,6 +159,30 @@ body {
 html.k-peek-fs, html.k-peek-fs body { height: 100%; overflow: hidden; }
 html.k-peek-fs .k-peek { position: fixed; inset: 0; z-index: 50; }
 html.k-peek-fs .k-peek img, html.k-peek-fs .k-peek video { max-height: calc(100vh - 72px); }
+/* ---- Plans / upgrade card ---- */
+.k-plan-toggle { display: inline-flex; gap: 2px; padding: 3px; margin-bottom: 12px;
+  background: var(--surface-2); border: 1px solid var(--border); border-radius: 999px; }
+.k-toggle-btn { border: 0; border-radius: 999px; padding: 5px 14px; cursor: pointer;
+  background: transparent; color: var(--text-muted); font-family: inherit; font-size: 12px; font-weight: 600; }
+.k-toggle-btn.active { background: var(--brand); color: #fff; }
+.k-plan-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(190px, 1fr)); gap: 10px; }
+.k-plan { display: flex; flex-direction: column; gap: 7px; padding: 14px;
+  background: var(--surface); border: 1px solid var(--border); border-radius: 12px; box-shadow: var(--specular); }
+.k-plan.current { border-color: var(--brand); }
+.k-plan-top { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+.k-plan-name { font-size: 15px; font-weight: 700; letter-spacing: -0.01em; }
+.k-plan-badge { padding: 2px 7px; border-radius: 999px; background: var(--brand-soft); color: var(--brand);
+  font-size: 10px; font-weight: 700; }
+.k-plan-badge.current { background: var(--surface-2); color: var(--text-faint); }
+.k-plan-credits { display: flex; align-items: center; gap: 5px; font-size: 12px; color: var(--text-muted); }
+.k-plan-pricing { display: flex; align-items: baseline; gap: 6px; margin-top: 2px; }
+.k-plan-price { font-size: 22px; font-weight: 700; letter-spacing: -0.02em; }
+.k-plan-was { font-size: 13px; color: var(--text-faint); text-decoration: line-through; }
+.k-plan-note { font-size: 11px; color: var(--text-faint); }
+.k-plan .k-btn { margin-top: auto; justify-content: center; }
+.k-pack-head { margin: 14px 0 6px; font-size: 11px; font-weight: 700; letter-spacing: 0.04em;
+  text-transform: uppercase; color: var(--text-faint); }
+.k-pack-row { margin-bottom: 6px; }
 /* Visual DNA chips: the character's face, so you can see WHICH DNA is locked in. */
 .k-dna-face { width: 18px; height: 18px; border-radius: 999px; object-fit: cover; margin-left: -3px; background: var(--border-strong); }
 .k-dna-stack .k-dna-stack-item { display: inline-flex; }

package/src/apps/widgets/plans.js

@@ -0,0 +1,203 @@
+'use strict';
+
+const { widgetPage } = require('../html');
+
+/**
+ * Plans / upgrade widget — shown by `show_plans`, and by any generation the
+ * server refused for credits.
+ *
+ * The buttons deep-link to app.kolbo.ai/pricing rather than a payment session:
+ * promo pricing, tax, currency and saved payment methods live there, and a
+ * checkout link minted on the API-key surface would drift from them the first
+ * time a campaign changes. The prices below ARE the live promo-adjusted
+ * numbers from /v1/account/plans, so the card never quotes a stale figure.
+ *
+ * structuredContent contract:
+ * {
+ *   widget: 'plans',
+ *   reason: 'insufficient_credits' | 'requested',
+ *   balance, required, shortfall,     // when reason === 'insufficient_credits'
+ *   current_plan: { key, name },
+ *   plans:        [{ key, name, interval, credits, price, original_price,
+ *                    discount_percent, promo_text, currency }],
+ *   credit_packs: [ same shape ],
+ *   pricing_url
+ * }
+ */
+
+const BODY = `
+<div class="k-card" id="card">
+  <div class="k-head">
+    <span class="k-logo" id="logo"></span>
+    <span class="k-title" id="tool-title">Plans</span>
+    <span class="k-spacer"></span>
+    <span class="k-chip" id="balance-chip" style="display:none"></span>
+  </div>
+  <div class="k-body">
+    <div class="k-error" id="notice" style="display:none"></div>
+    <div class="k-plan-toggle" id="toggle" style="display:none">
+      <button type="button" class="k-toggle-btn" data-interval="month">Monthly</button>
+      <button type="button" class="k-toggle-btn" data-interval="year">Annual</button>
+    </div>
+    <div id="stage"></div>
+    <div class="k-actions" id="actions"></div>
+  </div>
+  <div class="k-footer">
+    <span>Powered by <a href="#" id="kolbo-link">Kolbo.AI</a></span>
+  </div>
+</div>
+`;
+
+const SCRIPT = `
+var state = null;
+var interval = 'year';   // annual first — it is the better per-credit deal
+
+el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
+el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai'); };
+
+function pricingUrl() {
+  return (state && state.pricing_url) || 'https://app.kolbo.ai/pricing';
+}
+function money(amount, currency) {
+  if (amount == null) return '';
+  var sym = String(currency || 'usd').toLowerCase() === 'usd' ? '$' : '';
+  var n = Math.round(Number(amount) * 100) / 100;
+  return sym + n + (sym ? '' : ' ' + String(currency || '').toUpperCase());
+}
+function perMonthNote(plan) {
+  if (plan.interval !== 'year' || plan.price == null) return '';
+  var monthly = Math.round((Number(plan.price) / 12) * 100) / 100;
+  return money(monthly, plan.currency) + '/mo, billed annually';
+}
+
+function boot(sc) {
+  if (!sc) return;
+  state = sc;
+  el('tool-title').textContent = sc.reason === 'insufficient_credits' ? 'Out of credits' : 'Plans';
+
+  if (sc.balance != null) {
+    var chip = el('balance-chip');
+    chip.style.display = '';
+    chip.innerHTML = ICONS.sparkle + ' ' + esc(String(sc.balance)) + ' credits left';
+  }
+
+  if (sc.reason === 'insufficient_credits') {
+    var need = sc.shortfall != null ? sc.shortfall
+      : (sc.required != null && sc.balance != null ? Math.max(0, sc.required - sc.balance) : null);
+    el('notice').style.display = '';
+    el('notice').innerHTML = ICONS.warn + ' ' +
+      esc(need ? ('That generation needs ' + need + ' more credit' + (need === 1 ? '' : 's') + '.')
+               : 'That generation needs more credits than you have left.');
+  }
+
+  var plans = Array.isArray(sc.plans) ? sc.plans : [];
+  var intervals = {};
+  plans.forEach(function (p) { if (p.interval) intervals[p.interval] = true; });
+  if (intervals.month && intervals.year) {
+    el('toggle').style.display = '';
+    if (!intervals[interval]) interval = intervals.year ? 'year' : 'month';
+  } else {
+    interval = intervals.year ? 'year' : 'month';
+  }
+  wireToggle();
+  render();
+  window.kolbo.notifySize();
+}
+
+function wireToggle() {
+  Array.prototype.forEach.call(document.querySelectorAll('.k-toggle-btn'), function (b) {
+    b.onclick = function () { interval = b.getAttribute('data-interval'); render(); window.kolbo.notifySize(); };
+  });
+}
+
+function render() {
+  Array.prototype.forEach.call(document.querySelectorAll('.k-toggle-btn'), function (b) {
+    b.classList.toggle('active', b.getAttribute('data-interval') === interval);
+  });
+
+  var plans = (state.plans || []).filter(function (p) { return p.interval === interval; });
+  // Cheapest first so the ladder reads left-to-right. A zero-price plan is not
+  // an upgrade path, so it never takes a card slot.
+  plans = plans.filter(function (p) { return Number(p.price) > 0; });
+  plans.sort(function (a, b) { return (a.price || 0) - (b.price || 0); });
+
+  var current = state.current_plan && state.current_plan.key;
+  var html = plans.length
+    ? '<div class="k-plan-grid">' + plans.map(function (p) { return planCard(p, current); }).join('') + '</div>'
+    : '<div class="k-empty">Plan details are on the pricing page</div>';
+
+  var packs = (state.credit_packs || []).filter(function (p) { return Number(p.price) > 0; });
+  if (packs.length) {
+    packs.sort(function (a, b) { return (a.price || 0) - (b.price || 0); });
+    html += '<div class="k-pack-head">One-time credit packs</div>' +
+      packs.slice(0, 4).map(function (p) {
+        return '<div class="k-audio-row k-pack-row"><div class="k-audio-meta">' +
+          '<div class="k-audio-title">' + esc(p.name || '') + '</div>' +
+          (p.credits != null ? '<div class="k-audio-sub">' + esc(String(p.credits)) + ' credits</div>' : '') +
+          '</div><span class="k-chip">' + esc(money(p.price, p.currency)) + '</span></div>';
+      }).join('');
+  }
+
+  el('stage').innerHTML = html;
+  Array.prototype.forEach.call(el('stage').querySelectorAll('[data-buy]'), function (b) {
+    b.onclick = function () { window.kolbo.openLink(pricingUrl()); };
+  });
+  renderActions();
+}
+
+function planCard(p, currentKey) {
+  var isCurrent = currentKey && p.key === currentKey;
+  var badges = '';
+  if (p.discount_percent) badges += '<span class="k-plan-badge">' + esc(String(p.discount_percent)) + '% OFF</span>';
+  if (isCurrent) badges += '<span class="k-plan-badge current">Current</span>';
+
+  var price = '<span class="k-plan-price">' + esc(money(p.price, p.currency)) + '</span>';
+  if (p.original_price && p.original_price > p.price) {
+    price = '<span class="k-plan-was">' + esc(money(p.original_price, p.currency)) + '</span> ' + price;
+  }
+  var note = perMonthNote(p);
+
+  return '<div class="k-plan' + (isCurrent ? ' current' : '') + '">' +
+    '<div class="k-plan-top"><span class="k-plan-name">' + esc(p.name || p.key || '') + '</span>' + badges + '</div>' +
+    (p.credits != null
+      ? '<div class="k-plan-credits">' + ICONS.sparkle + ' ' + esc(String(p.credits)) + ' credits' +
+        (p.interval === 'month' ? '/mo' : p.interval === 'year' ? '/yr' : '') + '</div>'
+      : '') +
+    '<div class="k-plan-pricing">' + price + '</div>' +
+    (note ? '<div class="k-plan-note">' + esc(note) + '</div>' : '') +
+    (p.promo_text ? '<div class="k-plan-note">' + esc(p.promo_text) + '</div>' : '') +
+    (isCurrent
+      ? '<button class="k-btn" disabled>Your plan</button>'
+      : '<button class="k-btn primary" data-buy="' + esc(p.key || '') + '">Get ' + esc(p.name || 'plan') + '</button>') +
+    '</div>';
+}
+
+function renderActions() {
+  el('actions').innerHTML =
+    '<button class="k-btn ghost" id="btn-pricing">See all plans ' + ICONS.open + '</button>';
+  el('btn-pricing').onclick = function () { window.kolbo.openLink(pricingUrl()); };
+}
+
+window.kolbo.onToolResult(function (result) {
+  var sc = result.structuredContent || structured(result);
+  if (sc) boot(sc);
+});
+window.kolbo.onToolInput(function () {
+  if (state) return;
+  el('stage').innerHTML = '<div class="k-gen-grid n2"><div class="k-skel square" style="min-height:120px"></div>'
+    + '<div class="k-skel square" style="min-height:120px"></div></div>';
+  window.kolbo.notifySize();
+});
+window.kolbo.ready(function (ctx) {
+  var info = ctx && ctx.toolInfo;
+  if (state || !info) return;
+  var raw = info.result && (info.result.structuredContent || structured(info.result));
+  if (raw) boot(raw);
+});
+`;
+
+function plansWidgetHtml() {
+  return widgetPage({ title: 'Kolbo Plans', body: BODY, script: SCRIPT });
+}
+
+module.exports = { plansWidgetHtml };

package/src/index.js

@@ -1,233 +1,248 @@
-/* ============================================================================
- * @kolbo/mcp — Kolbo AI MCP Server
- *
- *   ⛔  STOP.  READ THIS BEFORE TOUCHING ANY TOOL REGISTRATION.  ⛔
- *
- * This package is published to npm and installed via `npx -y @kolbo/mcp`.
- * Thousands of users have it CACHED on their machines, pinned to old versions
- * by npx's cache. Every tool name, every arg name, every response shape
- * registered below is a PUBLIC CONTRACT. Breaking it silently strands users
- * whose LLM will keep calling tool names their cached server no longer
- * registers — or worse, calls new-style args that the old server can't parse.
- *
- * THE THREE COMMANDMENTS
- *
- *   1. NEVER RENAME AN EXISTING TOOL.
- *      Not `generate_image` → `create_image`. Not `list_models` → `get_models`.
- *      Not "just cleaning up the name." Old cached clients break the instant
- *      you rename. If you must rename, keep the OLD name as an alias that
- *      forwards to the new implementation for at least one full major version.
- *
- *   2. NEVER REMOVE AN EXISTING TOOL.
- *      Deprecate it in the description ("[DEPRECATED: use X]") and keep it
- *      working. Only remove in a major version bump with release notes.
- *
- *   3. NEVER CHANGE AN EXISTING TOOL'S ARG NAMES, TYPES, OR REQUIRED STATUS
- *      IN A BACKWARD-INCOMPATIBLE WAY.
- *      Adding a new OPTIONAL arg with a sensible default is fine. Everything
- *      else below is forbidden in a minor release:
- *        - renaming `prompt` to `text`
- *        - making a previously-optional arg required
- *        - changing `aspect_ratio: string` to `aspect_ratio: { w, h }`
- *        - removing an arg (even one you think nobody uses)
- *
- * VERSION BUMPS
- *
- *   - minor (1.1.0 → 1.2.0): new tool, new optional arg, description tweak
- *   - patch (1.1.0 → 1.1.1): internal refactor, bug fix with no user impact
- *   - major (1.1.0 → 2.0.0): ANY breaking change from commandments 1–3 above,
- *     AND only after going through the deprecation path in CLAUDE.md.
- *
- * WHY THIS MATTERS
- *
- *   Users install via `npx -y @kolbo/mcp` — npx CACHES packages. A user who
- *   installed 3 months ago may still be running v1.0 until their cache
- *   invalidates. When their Claude Desktop starts the MCP server, it
- *   registers whatever tools ITS VERSION knows about. Their LLM sees that
- *   list and calls those names. You cannot force-update them.
- *
- *   The matching backend SDK routes in
- *   `kolbo-api/src/modules/sdk/index.js` are the same kind of public
- *   contract and follow the same rules — never rename, never remove.
- *
- * Full rules, deprecation path, and parity-audit instructions: CLAUDE.md
- *
- * If you are a coding agent about to rename/remove a tool or arg: STOP and
- * ask the human first. This is not optional.
- * ==========================================================================*/
-
-const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const KolboClient = require('./client');
-const { LOCAL_FILE_ROUTING, attachFileInputHints } = require('./tools/_shared');
-const { registerGenerateTools } = require('./tools/generate');
-const { registerModelTools } = require('./tools/models');
-const { registerChatTools } = require('./tools/chat');
-const { registerVisualDnaTools } = require('./tools/visual_dna');
-const { registerMoodboardTools } = require('./tools/moodboards');
-const { registerColorPaletteTools } = require('./tools/color_palettes');
-const { registerMediaTools } = require('./tools/media');
-const { registerPresetTools } = require('./tools/presets');
-const { registerArtifactTools } = require('./tools/artifacts');
-const { registerProjectTools } = require('./tools/projects');
-const { registerAgentTools } = require('./tools/agents');
-const { registerDocTools } = require('./tools/docs');
-const { registerReviewTools } = require('./tools/review');
-const { registerVoiceTools } = require('./tools/voices');
-const { registerMusicLibraryTools } = require('./tools/music_library');
-const { registerStockLibraryTools } = require('./tools/stock_library');
-const { registerAudioStemTools } = require('./tools/audio_stems');
-const { registerApps, attachToolWidgetMeta } = require('./apps');
-const { attachToolAnnotations } = require('./toolAnnotations');
-
-/**
- * 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.
- * @param {boolean} [opts.apps]    Force-enable MCP Apps widget results. Set by
- *                                 the kolbo-api remote connector (claude.ai),
- *                                 whose stateless transport hides client
- *                                 capabilities. stdio hosts are auto-detected
- *                                 from the initialize handshake instead.
- * @returns {McpServer} a server ready to `.connect(transport)`.
- */
-function createServer(opts = {}) {
-  const client = new KolboClient(opts);
-
-  const server = new McpServer({
-    name: 'kolbo',
-    title: 'Kolbo',
-    version: '1.0.0',
-    websiteUrl: 'https://kolbo.ai',
-    // Connector avatar for hosts that render server icons (claude.ai tool
-    // headers show this instead of a letter monogram).
-    icons: [{ src: 'https://api.kolbo.ai/assets/kolbo-ai.png', mimeType: 'image/png', sizes: ['512x512'] }]
-  }, {
-    // Server-level instructions surfaced to the host model on initialize.
-    // The single most common failure mode is project confusion — spell out
-    // the project contract here so every client gets it without a skill file.
-    instructions: [
-      'LOCAL FILES: never upload a user file with your own cloud credentials, an S3/Spaces script, or a third-party host — Kolbo owns this. ' + LOCAL_FILE_ROUTING,
-      'PROMPT CONVENTIONS (Kolbo-specific — these change the OUTPUT, not just the metadata):',
-      'A. Visual DNA: passing `visual_dna_ids` is not enough — every DNA in play must ALSO be tagged inside the prompt text as `@Name`, using the DNA name (e.g. "@Kobi walks into frame"). Moodboards are referenced the same way with `#Name`. Resolve names via `list_visual_dnas` / `list_moodboards`.',
-      'B. The full Kolbo skill is available to you as MCP RESOURCES under `kolbo://skill/`. Read `kolbo://skill/SKILL.md` first — it is the core rules plus a routing index — then read the matching `kolbo://skill/references/...` file before writing prompts for a specific model or workflow (per-model prompt rules, Visual DNA workflow, Creative Director, marketing, cost validation). Do this instead of guessing; the references exist precisely because the rules differ per model.',
-      'PROJECT CONTRACT (read this before generating anything):',
-      'Everything in Kolbo lives inside a PROJECT — sessions, generations, and media are all project-scoped.',
-      '1. When the user names a project ("in my Acme project", "for the summer campaign"), call `list_projects` ONCE to resolve the name to an id, then pass that SAME id as `project_id` on EVERY subsequent generate_* / chat_send_message / upload_media / create_doc call in THIS conversation. There is no server-side sticky store — omitting `project_id` on any later call silently lands in the default "API Generations" bucket (flagged is_default:true). Once resolved, treat that id as required for the rest of the conversation.',
-      '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). `list_sessions` returns `project_id` on every row — echo that id on follow-up generate/chat/upload calls for work in that session. Do not confuse a generation `session_id` with a project id; they are not interchangeable. Empty leftover sessions after `move_session` can be removed with `delete_session` (soft-delete; `restore_session` undoes it).',
-      '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
-      '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
-      '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',
-      '6. TIMEOUT HANDLING (applies to EVERY generate_* / edit_* / chat_send_message / transcribe_audio tool): each tool blocks and polls internally, then gives up after its own window if the job is not yet terminal. A timeout is NOT a failure — it returns `_timed_out:true` with the `generation_id` (not an error), because the job is almost always STILL RUNNING on the server (or already finished). Call `get_generation_status` with that `generation_id` and `wait=true` to keep checking until state="completed". NEVER conclude the generation failed and re-run the same tool from scratch after a `_timed_out:true` result — that wastes the user\'s credits by paying twice. DIRECTOR / BATCH JOBS follow the same convention through a dedicated tool: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal; on `_timed_out:true` call `get_creative_director_status` (not get_generation_status) with the returned generation_id and keep checking. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
-      '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
-      '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL → pass it directly. A URL from generate_* / list_media / upload_media / media.kolbo.ai / any *.kolbo.ai host is ALREADY hosted — NEVER call upload_media on it (that duplicates the file). External (non-Kolbo) URLs may need one upload_media re-host; Kolbo URLs never do. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
-      '9. MODEL SELECTION — NAMED MODEL WINS, THEN STRENGTHS SUMMARY: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). If the user named a model this turn OR earlier in the conversation (including a compaction "Locked choices" / summary), that name is a FAMILY LOCK: pass it (or its display name) on every follow-up, including when the tool changes (text-to-video → image-to-video). Identifier resolution remaps a t2v id to the family\'s i2v sibling automatically. NEVER substitute a different brand because it is cheaper, faster, or "best balance" (Grok Imagine named → do not fire Seedance). If the named family has no variant for this modality, ASK — do not silently switch. Cheapest-summary routing applies ONLY when no model was named on this task: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost — then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
-      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit`. Auto-pick only Nano Banana 2 (`nano-banana-2` / `nano-banana-2-image-editing`) or GPT Image 2 (`gpt-image-2` / `gpt-image-2/edit`) for photoreal photo edits, object removal, keep-subject/remove-others, or crowd cleanup. Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style, named-only for editing. Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
-      '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.'
-    ].join('\n')
-  });
-  const progress = require('./progress');
-  const tool = server.tool.bind(server);
-  server.tool = (...args) => {
-    const index = args.length - 1;
-    const handler = args[index];
-    if (typeof handler !== 'function') return tool(...args);
-    args[index] = (params, extra) => progress.run(extra, () => handler(params, extra));
-    return tool(...args);
-  };
-
-  // 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. `apps` gates interactive widget results
-  // (MCP Apps) the same way — see src/apps/index.js.
-  const toolOptions = { inlineImages: !!opts.inlineImages, apps: !!opts.apps };
-  registerGenerateTools(server, client, toolOptions);
-  registerModelTools(server, client, toolOptions);
-  registerVoiceTools(server, client, toolOptions);
-  registerChatTools(server, client, toolOptions);
-  registerVisualDnaTools(server, client, toolOptions);
-  registerMoodboardTools(server, client, toolOptions);
-  registerColorPaletteTools(server, client, toolOptions);
-  registerMediaTools(server, client, toolOptions);
-  registerPresetTools(server, client, toolOptions);
-  registerArtifactTools(server, client, toolOptions);
-  registerProjectTools(server, client, toolOptions);
-  registerAgentTools(server, client, toolOptions);
-  registerDocTools(server, client, toolOptions);
-  registerReviewTools(server, client, toolOptions);
-  registerMusicLibraryTools(server, client, toolOptions);
-  registerStockLibraryTools(server, client, toolOptions);
-  registerAudioStemTools(server, client, toolOptions);
-
-  // MCP Apps widget resources (ui://kolbo/*). Registering resources is inert
-  // for text-only hosts — they never fetch them.
-  registerApps(server);
-  // Serve skill/ as standard MCP resources so connector clients — which never
-  // run `npx @kolbo/mcp install` — can still read the operating guidance.
-  registerSkillResources(server);
-  // Every media-input tool advertises the local-file route that works on THIS
-  // transport. Without it, a remote-connector model reads "absolute local path",
-  // sees no filesystem, and tells the user Kolbo cannot accept their file —
-  // the single most-reported failure, despite the upload tools existing.
-  attachFileInputHints(server, toolOptions);
-  // OpenAI public-app review requires every exposed tool to declare the three
-  // safety hints explicitly. The exact contract also fails closed when a tool
-  // is added or removed without a classification.
-  attachToolAnnotations(server);
-  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
-  // claude.ai prepares the widget iframe from tools/list, not from the result.
-  attachToolWidgetMeta(server);
-
-  return server;
-}
-
-async function main() {
-  const server = createServer();
-
-  // Node kills the process on an unhandled rejection / uncaught exception. In a
-  // long-lived stdio server that is not a stack trace the user ever sees — the
-  // host just reports "MCP server disconnected", mid-conversation, with the
-  // generation still running server-side. A tool error is recoverable; a dead
-  // process is not, so log to stderr (stdout is the JSON-RPC channel) and stay
-  // up. Only the stdio entrypoint does this — an embedding host (kolbo-api)
-  // keeps its own process semantics.
-  process.on('unhandledRejection', (err) => {
-    console.error('[kolbo-mcp] unhandled rejection (server staying up):', err);
-  });
-  process.on('uncaughtException', (err) => {
-    console.error('[kolbo-mcp] uncaught exception (server staying up):', err);
-  });
-
-  // Start the server with stdio transport
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
-
-// Widget plumbing for HOST developers embedding Kolbo widgets themselves
-// (e.g. kolbo-api's Kobi Act) — everything else in ./apps stays internal.
-// UI: tool-name-agnostic resource URI map. TOOL_WIDGETS: tool name -> URI, so
-// a host can resolve which widget a given tool call carries without deep-
-// requiring internals. uiMeta/widgetHtml: same helpers registerApps() uses
-// internally, re-exported so a host never has to re-derive them. Additive
-// only — existing consumers (claude.ai, Desktop, npx) are unaffected.
-const { UI, TOOL_WIDGETS, uiMeta, widgetHtml } = require('./apps');
-const { registerSkillResources } = require('./skillResources');
-
-module.exports = { main, createServer, UI, TOOL_WIDGETS, uiMeta, widgetHtml };
-
-// 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);
-  });
-}
+/* ============================================================================
+ * @kolbo/mcp — Kolbo AI MCP Server
+ *
+ *   ⛔  STOP.  READ THIS BEFORE TOUCHING ANY TOOL REGISTRATION.  ⛔
+ *
+ * This package is published to npm and installed via `npx -y @kolbo/mcp`.
+ * Thousands of users have it CACHED on their machines, pinned to old versions
+ * by npx's cache. Every tool name, every arg name, every response shape
+ * registered below is a PUBLIC CONTRACT. Breaking it silently strands users
+ * whose LLM will keep calling tool names their cached server no longer
+ * registers — or worse, calls new-style args that the old server can't parse.
+ *
+ * THE THREE COMMANDMENTS
+ *
+ *   1. NEVER RENAME AN EXISTING TOOL.
+ *      Not `generate_image` → `create_image`. Not `list_models` → `get_models`.
+ *      Not "just cleaning up the name." Old cached clients break the instant
+ *      you rename. If you must rename, keep the OLD name as an alias that
+ *      forwards to the new implementation for at least one full major version.
+ *
+ *   2. NEVER REMOVE AN EXISTING TOOL.
+ *      Deprecate it in the description ("[DEPRECATED: use X]") and keep it
+ *      working. Only remove in a major version bump with release notes.
+ *
+ *   3. NEVER CHANGE AN EXISTING TOOL'S ARG NAMES, TYPES, OR REQUIRED STATUS
+ *      IN A BACKWARD-INCOMPATIBLE WAY.
+ *      Adding a new OPTIONAL arg with a sensible default is fine. Everything
+ *      else below is forbidden in a minor release:
+ *        - renaming `prompt` to `text`
+ *        - making a previously-optional arg required
+ *        - changing `aspect_ratio: string` to `aspect_ratio: { w, h }`
+ *        - removing an arg (even one you think nobody uses)
+ *
+ * VERSION BUMPS
+ *
+ *   - minor (1.1.0 → 1.2.0): new tool, new optional arg, description tweak
+ *   - patch (1.1.0 → 1.1.1): internal refactor, bug fix with no user impact
+ *   - major (1.1.0 → 2.0.0): ANY breaking change from commandments 1–3 above,
+ *     AND only after going through the deprecation path in CLAUDE.md.
+ *
+ * WHY THIS MATTERS
+ *
+ *   Users install via `npx -y @kolbo/mcp` — npx CACHES packages. A user who
+ *   installed 3 months ago may still be running v1.0 until their cache
+ *   invalidates. When their Claude Desktop starts the MCP server, it
+ *   registers whatever tools ITS VERSION knows about. Their LLM sees that
+ *   list and calls those names. You cannot force-update them.
+ *
+ *   The matching backend SDK routes in
+ *   `kolbo-api/src/modules/sdk/index.js` are the same kind of public
+ *   contract and follow the same rules — never rename, never remove.
+ *
+ * Full rules, deprecation path, and parity-audit instructions: CLAUDE.md
+ *
+ * If you are a coding agent about to rename/remove a tool or arg: STOP and
+ * ask the human first. This is not optional.
+ * ==========================================================================*/
+
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const KolboClient = require('./client');
+const { LOCAL_FILE_ROUTING, attachFileInputHints } = require('./tools/_shared');
+const { registerGenerateTools } = require('./tools/generate');
+const { registerModelTools } = require('./tools/models');
+const { registerChatTools } = require('./tools/chat');
+const { registerVisualDnaTools } = require('./tools/visual_dna');
+const { registerMoodboardTools } = require('./tools/moodboards');
+const { registerColorPaletteTools } = require('./tools/color_palettes');
+const { registerMediaTools } = require('./tools/media');
+const { registerPresetTools } = require('./tools/presets');
+const { registerArtifactTools } = require('./tools/artifacts');
+const { registerProjectTools } = require('./tools/projects');
+const { registerAgentTools } = require('./tools/agents');
+const { registerDocTools } = require('./tools/docs');
+const { registerReviewTools } = require('./tools/review');
+const { registerVoiceTools } = require('./tools/voices');
+const { registerMusicLibraryTools } = require('./tools/music_library');
+const { registerStockLibraryTools } = require('./tools/stock_library');
+const { registerAudioStemTools } = require('./tools/audio_stems');
+const { registerApps, attachToolWidgetMeta } = require('./apps');
+const { attachToolAnnotations } = require('./toolAnnotations');
+
+/**
+ * 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.
+ * @param {boolean} [opts.apps]    Force-enable MCP Apps widget results. Set by
+ *                                 the kolbo-api remote connector (claude.ai),
+ *                                 whose stateless transport hides client
+ *                                 capabilities. stdio hosts are auto-detected
+ *                                 from the initialize handshake instead.
+ * @returns {McpServer} a server ready to `.connect(transport)`.
+ */
+function createServer(opts = {}) {
+  const client = new KolboClient(opts);
+
+  const server = new McpServer({
+    name: 'kolbo',
+    title: 'Kolbo',
+    version: '1.0.0',
+    websiteUrl: 'https://kolbo.ai',
+    // Connector avatar for hosts that render server icons (claude.ai tool
+    // headers show this instead of a letter monogram).
+    icons: [{ src: 'https://api.kolbo.ai/assets/kolbo-ai.png', mimeType: 'image/png', sizes: ['512x512'] }]
+  }, {
+    // Server-level instructions surfaced to the host model on initialize.
+    // The single most common failure mode is project confusion — spell out
+    // the project contract here so every client gets it without a skill file.
+    instructions: [
+      'LOCAL FILES: never upload a user file with your own cloud credentials, an S3/Spaces script, or a third-party host — Kolbo owns this. ' + LOCAL_FILE_ROUTING,
+      'PROMPT CONVENTIONS (Kolbo-specific — these change the OUTPUT, not just the metadata):',
+      'A. Visual DNA: passing `visual_dna_ids` is not enough — every DNA in play must ALSO be tagged inside the prompt text as `@Name`, using the DNA name (e.g. "@Kobi walks into frame"). Moodboards are referenced the same way with `#Name`. Resolve names via `list_visual_dnas` / `list_moodboards`.',
+      'B. The full Kolbo skill is available to you as MCP RESOURCES under `kolbo://skill/`. Read `kolbo://skill/SKILL.md` first — it is the core rules plus a routing index — then read the matching `kolbo://skill/references/...` file before writing prompts for a specific model or workflow (per-model prompt rules, Visual DNA workflow, Creative Director, marketing, cost validation). Do this instead of guessing; the references exist precisely because the rules differ per model.',
+      'PROJECT CONTRACT (read this before generating anything):',
+      'Everything in Kolbo lives inside a PROJECT — sessions, generations, and media are all project-scoped.',
+      '1. When the user names a project ("in my Acme project", "for the summer campaign"), call `list_projects` ONCE to resolve the name to an id, then pass that SAME id as `project_id` on EVERY subsequent generate_* / chat_send_message / upload_media / create_doc call in THIS conversation. There is no server-side sticky store — omitting `project_id` on any later call silently lands in the default "API Generations" bucket (flagged is_default:true). Once resolved, treat that id as required for the rest of the conversation.',
+      '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). `list_sessions` returns `project_id` on every row — echo that id on follow-up generate/chat/upload calls for work in that session. Do not confuse a generation `session_id` with a project id; they are not interchangeable. Empty leftover sessions after `move_session` can be removed with `delete_session` (soft-delete; `restore_session` undoes it).',
+      '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
+      '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
+      '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',
+      '6. TIMEOUT HANDLING (applies to EVERY generate_* / edit_* / chat_send_message / transcribe_audio tool): each tool blocks and polls internally, then gives up after its own window if the job is not yet terminal. A timeout is NOT a failure — it returns `_timed_out:true` with the `generation_id` (not an error), because the job is almost always STILL RUNNING on the server (or already finished). Call `get_generation_status` with that `generation_id` and `wait=true` to keep checking until state="completed". NEVER conclude the generation failed and re-run the same tool from scratch after a `_timed_out:true` result — that wastes the user\'s credits by paying twice. DIRECTOR / BATCH JOBS follow the same convention through a dedicated tool: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal; on `_timed_out:true` call `get_creative_director_status` (not get_generation_status) with the returned generation_id and keep checking. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
+      '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
+      '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL → pass it directly. A URL from generate_* / list_media / upload_media / media.kolbo.ai / any *.kolbo.ai host is ALREADY hosted — NEVER call upload_media on it (that duplicates the file). External (non-Kolbo) URLs may need one upload_media re-host; Kolbo URLs never do. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
+      '9. MODEL SELECTION — NAMED MODEL WINS, THEN STRENGTHS SUMMARY: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). If the user named a model this turn OR earlier in the conversation (including a compaction "Locked choices" / summary), that name is a FAMILY LOCK: pass it (or its display name) on every follow-up, including when the tool changes (text-to-video → image-to-video). Identifier resolution remaps a t2v id to the family\'s i2v sibling automatically. NEVER substitute a different brand because it is cheaper, faster, or "best balance" (Grok Imagine named → do not fire Seedance). If the named family has no variant for this modality, ASK — do not silently switch. Cheapest-summary routing applies ONLY when no model was named on this task: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost — then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
+      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit`. Auto-pick only Nano Banana 2 (`nano-banana-2` / `nano-banana-2-image-editing`) or GPT Image 2 (`gpt-image-2` / `gpt-image-2/edit`) for photoreal photo edits, object removal, keep-subject/remove-others, or crowd cleanup. Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style, named-only for editing. Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
+      '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.'
+    ].join('\n')
+  });
+  const progress = require('./progress');
+  const { insufficientCreditsResult } = require('./tools/_shared');
+  const tool = server.tool.bind(server);
+  server.tool = (...args) => {
+    const index = args.length - 1;
+    const handler = args[index];
+    if (typeof handler !== 'function') return tool(...args);
+    args[index] = (params, extra) => progress.run(extra, async () => {
+      try {
+        return await handler(params, extra);
+      } catch (err) {
+        // Running out of credits is the one refusal with an obvious next step,
+        // so it gets a card instead of raw error prose. Wrapped HERE rather
+        // than at each of the ~17 generation submit sites: any tool the server
+        // can refuse for credits (generation, chat, stems) routes through this
+        // single seam, which is also the only way a tool added later inherits
+        // the behavior for free.
+        const card = await insufficientCreditsResult(client, err).catch(() => null);
+        if (card) return card;
+        throw err;
+      }
+    });
+    return tool(...args);
+  };
+
+  // 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. `apps` gates interactive widget results
+  // (MCP Apps) the same way — see src/apps/index.js.
+  const toolOptions = { inlineImages: !!opts.inlineImages, apps: !!opts.apps };
+  registerGenerateTools(server, client, toolOptions);
+  registerModelTools(server, client, toolOptions);
+  registerVoiceTools(server, client, toolOptions);
+  registerChatTools(server, client, toolOptions);
+  registerVisualDnaTools(server, client, toolOptions);
+  registerMoodboardTools(server, client, toolOptions);
+  registerColorPaletteTools(server, client, toolOptions);
+  registerMediaTools(server, client, toolOptions);
+  registerPresetTools(server, client, toolOptions);
+  registerArtifactTools(server, client, toolOptions);
+  registerProjectTools(server, client, toolOptions);
+  registerAgentTools(server, client, toolOptions);
+  registerDocTools(server, client, toolOptions);
+  registerReviewTools(server, client, toolOptions);
+  registerMusicLibraryTools(server, client, toolOptions);
+  registerStockLibraryTools(server, client, toolOptions);
+  registerAudioStemTools(server, client, toolOptions);
+
+  // MCP Apps widget resources (ui://kolbo/*). Registering resources is inert
+  // for text-only hosts — they never fetch them.
+  registerApps(server);
+  // Serve skill/ as standard MCP resources so connector clients — which never
+  // run `npx @kolbo/mcp install` — can still read the operating guidance.
+  registerSkillResources(server);
+  // Every media-input tool advertises the local-file route that works on THIS
+  // transport. Without it, a remote-connector model reads "absolute local path",
+  // sees no filesystem, and tells the user Kolbo cannot accept their file —
+  // the single most-reported failure, despite the upload tools existing.
+  attachFileInputHints(server, toolOptions);
+  // OpenAI public-app review requires every exposed tool to declare the three
+  // safety hints explicitly. The exact contract also fails closed when a tool
+  // is added or removed without a classification.
+  attachToolAnnotations(server);
+  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
+  // claude.ai prepares the widget iframe from tools/list, not from the result.
+  attachToolWidgetMeta(server);
+
+  return server;
+}
+
+async function main() {
+  const server = createServer();
+
+  // Node kills the process on an unhandled rejection / uncaught exception. In a
+  // long-lived stdio server that is not a stack trace the user ever sees — the
+  // host just reports "MCP server disconnected", mid-conversation, with the
+  // generation still running server-side. A tool error is recoverable; a dead
+  // process is not, so log to stderr (stdout is the JSON-RPC channel) and stay
+  // up. Only the stdio entrypoint does this — an embedding host (kolbo-api)
+  // keeps its own process semantics.
+  process.on('unhandledRejection', (err) => {
+    console.error('[kolbo-mcp] unhandled rejection (server staying up):', err);
+  });
+  process.on('uncaughtException', (err) => {
+    console.error('[kolbo-mcp] uncaught exception (server staying up):', err);
+  });
+
+  // Start the server with stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// Widget plumbing for HOST developers embedding Kolbo widgets themselves
+// (e.g. kolbo-api's Kobi Act) — everything else in ./apps stays internal.
+// UI: tool-name-agnostic resource URI map. TOOL_WIDGETS: tool name -> URI, so
+// a host can resolve which widget a given tool call carries without deep-
+// requiring internals. uiMeta/widgetHtml: same helpers registerApps() uses
+// internally, re-exported so a host never has to re-derive them. Additive
+// only — existing consumers (claude.ai, Desktop, npx) are unaffected.
+const { UI, TOOL_WIDGETS, uiMeta, widgetHtml } = require('./apps');
+const { registerSkillResources } = require('./skillResources');
+
+module.exports = { main, createServer, UI, TOOL_WIDGETS, uiMeta, widgetHtml };
+
+// 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/toolAnnotations.js

@@ -10,7 +10,7 @@
 
 const READ_ONLY = [
   'get_creative_director_status', 'get_generation_status', 'list_models',
-  'check_credits', 'get_session_usage', 'list_voices',
+  'check_credits', 'show_plans', 'get_session_usage', 'list_voices',
   'chat_list_conversations', 'chat_get_messages',
   'list_visual_dnas', 'get_visual_dna', 'list_visual_dna_folders',
   'list_moodboards', 'get_moodboard',

package/src/tools/_shared.js

@@ -939,6 +939,61 @@ function compactList(items, { fields, cap = 50, total, extra, note } = {}) {
   return text;
 }
 
+/**
+ * Turn a 403 INSUFFICIENT_CREDITS into the plans/upgrade card.
+ *
+ * Without this the user just sees the raw API sentence and has to go find the
+ * pricing page themselves. The card states the shortfall, shows live
+ * promo-adjusted plans, and links to app.kolbo.ai/pricing.
+ *
+ * Returns null for any other error so callers can rethrow untouched. The plan
+ * fetch is best-effort: if it fails we still return a card carrying the
+ * balance/shortfall and the pricing link, because the ONE thing this path must
+ * never do is swallow the reason the generation did not run.
+ */
+async function insufficientCreditsResult(client, err) {
+  if (!err || err.code !== 'INSUFFICIENT_CREDITS') return null;
+
+  let data = null;
+  try {
+    data = await client.get('/v1/account/plans');
+  } catch {
+    // Offline / rate-limited — fall through to the minimal card.
+  }
+
+  const balance = err.data?.balance ?? data?.credits?.total;
+  const required = err.data?.required;
+  const structured = {
+    widget: 'plans',
+    reason: 'insufficient_credits',
+    balance,
+    required,
+    shortfall: (Number.isFinite(balance) && Number.isFinite(required))
+      ? Math.max(0, required - balance) : undefined,
+    current_plan: data?.current_plan || null,
+    plans: data?.plans || [],
+    credit_packs: data?.credit_packs || [],
+    pricing_url: err.data?.pricing_url || data?.pricing_url || 'https://app.kolbo.ai/pricing',
+  };
+
+  // structuredContent shadows the text on widget hosts, so the refusal reason
+  // has to be inside the object too — an agent that only reads structured
+  // content must still understand that nothing was generated.
+  structured.error = err.message;
+  structured._hint = 'The generation did NOT run and nothing was charged. An upgrade card is shown to the user. Tell them they are out of credits and point at the card; do not retry the generation, and do not attempt to purchase anything for them.';
+
+  const text = JSON.stringify({
+    error: err.message,
+    code: 'INSUFFICIENT_CREDITS',
+    balance,
+    required,
+    pricing_url: structured.pricing_url,
+    _hint: structured._hint,
+  }, null, 2);
+
+  return uiResult(UI.plans, text, structured);
+}
+
 module.exports = {
   MAX_FILE_BYTES,
   MAX_TEXT_CHARS,
@@ -965,5 +1020,6 @@ module.exports = {
   buildProjectUrl,
   uiGenerating,
   uiCompleted,
+  insufficientCreditsResult,
   appsEnabled,
 };

package/src/tools/models.js

@@ -466,6 +466,38 @@ function registerModelTools(server, client, options = {}) {
       }
     }
   );
+
+  // ─── show_plans ──────────────────────────────────
+  // The upgrade card. Also rendered automatically when a generation is refused
+  // for credits — see insufficientCreditsResult() in _shared.js.
+  server.tool(
+    'show_plans',
+    'Show the user their Kolbo credit balance, current plan, and the available upgrade plans / credit packs as an interactive card. Use when the user asks about pricing, plans, upgrading, or how to get more credits. Prices shown are live and promo-adjusted. The card links to app.kolbo.ai/pricing to complete a purchase — never quote prices from memory, and never claim to have made a purchase for them.',
+    {},
+    async () => {
+      const data = await client.get('/v1/account/plans');
+      const structured = {
+        widget: 'plans',
+        reason: 'requested',
+        balance: data?.credits?.total,
+        current_plan: data?.current_plan || null,
+        plans: data?.plans || [],
+        credit_packs: data?.credit_packs || [],
+        pricing_url: data?.pricing_url || 'https://app.kolbo.ai/pricing',
+      };
+      // structuredContent SHADOWS the text on widget hosts, so everything the
+      // agent needs to talk about pricing has to live in the object above.
+      const text = JSON.stringify({
+        credits: structured.balance,
+        current_plan: structured.current_plan,
+        plans: structured.plans,
+        credit_packs: structured.credit_packs,
+        pricing_url: structured.pricing_url,
+        _hint: 'A plans card is rendered for the user. Summarise briefly; do NOT paste the price table. Purchases are completed by the user on the pricing page — you cannot buy on their behalf.',
+      }, null, 2);
+      return uiResult(UI.plans, text, structured);
+    }
+  );
 }
 
 module.exports = { registerModelTools };