@kolbo/mcp 1.28.0 → 1.30.0

package/README.md

@@ -4,6 +4,8 @@ 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.
 
+**✨ Interactive widgets (v1.30+):** in claude.ai and Claude Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video player, and one-click **Animate · Edit · Recreate · Download** actions. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Cursor) keep the classic text responses.
+
 ## Set up — paste one prompt, or one config block (keyless, no API key)
 
 ### Easiest: paste this prompt to your AI
@@ -111,7 +113,7 @@ Just ask your agent naturally:
 
 Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
 
-## Available Tools (52)
+## Available Tools (86)
 
 **Generation**
 | Tool | Description |
@@ -211,6 +213,17 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `analyze_script_for_stock` | AI: turn a script into b-roll search terms (`queries[]`, `mediaType`, `keywords`). |
 | `import_stock_asset` | Copy a stock asset into the media library (CDN copy, stable URL). Free. |
 
+**Shorts Creator** (long video → viral vertical shorts, two-phase)
+| Tool | Description |
+|------|-------------|
+| `shorts_analyze` | Phase 1: analyze a long video (Kolbo media-library URL, ≤30 min) → AI-picked best moments with titles, hooks, scores, accent beats. Flat 15 credits. Polls until moments are ready (~1-3 min). |
+| `shorts_list_presets` | List restyle presets (identifier, name, preview video, default mode/subtitle style). |
+| `shorts_get_transcript` | Word-level Scribe transcript of the source video (`words`, `language`, `sourceDuration`) — the base for the Review & Edit workflow (build `delete_ranges` cuts + edited `srt_content`). |
+| `shorts_estimate` | Price a selection before rendering — free. Per-short credits + chunk counts. `delete_ranges` cuts shorten the effective duration (cheaper). |
+| `shorts_render` | Phase 2: render up to 5 shorts (15-90s each) from picked moments — `accents` mode (restyle strongest beats, cheaper) or `full` (restyle everything), optional burned-in subtitles. Per short: optional `delete_ranges` (cut dead air, absolute source seconds, ≥8s must remain) and `srt_content` (user-edited SRT, cut-timeline times, ≤200KB). Polls until done (~5-20 min), returns final URLs. Failed shorts auto-refund. |
+| `shorts_status` | One-shot job state read (moments / shorts / phase) — resume after a timeout. |
+| `shorts_cancel` | Cancel a job and refund unused credits. |
+
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -41,6 +41,7 @@
     "README.md"
   ],
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "form-data": "^4.0.5",
     "zod": "^3.25.0"

package/skill/GENERATED.md

@@ -1,7 +1,7 @@
 # AUTO-GENERATED — do not edit
 
 This skill/ tree is mirrored from kolbo-code (the single source of truth)
-by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@2d43295.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@9cf6c35.
 
 It is the skill that 'npx @kolbo/mcp install' deploys into the user's agent.
 To change it, edit packages/opencode/skills/kolbo/ in kolbo-code and push;

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.4.0
+version: 0.5.0
 name: kolbo
 description: |
   Generate, edit, or analyze creative media via the Kolbo AI MCP server:
@@ -39,6 +39,25 @@ Once per conversation, before any other Kolbo tool call:
 
 If the user is on a whitelabel build (`sapir`, etc.), they must use their branded command — not `kolbo`. See `references/workflows/troubleshooting.md`.
 
+## 🎬 Confirm the Creative Brief BEFORE Generating (CRITICAL — read first)
+
+Never fire a paid generation the moment the user says "make X". First **present the brief back as a confirmation the user can change** — this is the single most important interaction. It gives the user control over what gets created and what it costs, instead of silently spending credits on defaults.
+
+**Before ANY paid image / video / music / speech / 3D generation**, unless the user has *explicitly* dictated every key parameter in this message, ask ONE labeled question (the UI renders it as an options card) confirming:
+
+- **Model** — your recommended pick as the default option, plus 1–2 alternatives (with their credit cost).
+- **Aspect ratio** — e.g. `1:1 / 9:16 / 16:9` (offer the sensible default first).
+- **Count** — how many (1 / 4 / …).
+- **Resolution / quality / duration** — where the model supports it.
+- **Creative direction** — style / mood / scene, when the user was vague ("4 cats" → offer style options: photoreal / illustrated / cinematic / surprise-me).
+- **Credit cost** — state the total (`✦ N credits`) right in the question so cost is never a surprise.
+
+Then generate **only** with the confirmed parameters. If the user changes an option, use the change. This mirrors the approval-card flow: propose → let them adjust → confirm → generate.
+
+**Only skip the brief confirmation when** the user's message already pins model + aspect + count + creative direction (e.g. "generate 4 photoreal tabby cats, 1:1, z-image/turbo") — then just state the cost one-liner and fire. A low credit cost is **not** a reason to skip: cheap ≠ no-confirmation. What matters is whether the user actually chose the parameters.
+
+For multi-scene / batch work this pairs with `generate_creative_director` (see below) — still confirm the brief first.
+
 ## Routing Index — Read These Files on Demand
 
 | If the user wants to… | Read first |
@@ -49,7 +68,6 @@ If the user is on a whitelabel build (`sapir`, etc.), they must use their brande
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
 | Build a **multi-scene set** (Creative Director, storyboard, campaign batch, 4+ angles) | `references/models/creative-director.md` |
 | Generate **music** (Suno, song, lyrics, jingle, score) | `references/models/music.md` |
-| Find an **existing / stock / library / royalty-free track** to score a video, ad, or voiceover | `references/workflows/music-library.md` |
 | Build an **HTML presentation / slide deck** | `references/models/html-presentation.md` |
 | Build a **landing page / marketing site** | `references/models/landing-page.md` |
 | Build a **dashboard / data viz / interactive widget / mini-game / UI mockup** | `references/models/visual-code.md` |
@@ -82,7 +100,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
 | `generate_elements` | Reference-driven video. **Primary route for DNA → video.** |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
-| `generate_lipsync` | Lipsync audio to an image or video face. Sync-3 adds multi-person speaker selection (`active_speaker_detection`), `emotion`, `model_mode`, `temperature`. |
+| `generate_lipsync` | Lipsync audio to an image or video face. |
 | `generate_music` | Music generation (Suno + variants). |
 | `generate_speech` | TTS. Use `list_voices` to pick a voice. |
 | `generate_sound` | Sound effects. |
@@ -96,7 +114,6 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` | Visual DNA — see `workflows/visual-dna.md` |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
-| `search_music_library` / `analyze_script_for_music` / `browse_music_library` / `get_music_library_facets` / `get_music_track_audio` / `get_music_track_related` / `get_music_track_lyrics` | **Stock / production music library** — find a licensed ready-made track (NOT `generate_music`, which composes a new song). See `workflows/music-library.md` |
 | `app_builder_*` (9 tools) | Full React app generation — see `workflows/app-builder.md` |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 
@@ -145,8 +162,8 @@ Model types for `list_models`: `text_to_img`, `image_editing`, `text_to_video`,
 
 Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick rules:
 
-- **Skip cost confirmation** when the user already specified model + count + duration, OR when a single generation costs < 5 credits.
-- **Required cost confirmation** otherwise: one-line summary, suggest cheaper alternative if available, wait for confirm.
+- **Skip the brief/cost confirmation ONLY** when the user's message already pins model + count + aspect + creative direction (see "Confirm the Creative Brief" above). Low cost alone is **not** a reason to skip — cheap generations still get the one labeled confirmation unless the user chose the parameters.
+- **Otherwise confirm** via the labeled-question card: the parameters + the credit cost, suggest a cheaper alternative if one fits, wait for the user's pick. Never fire on defaults the user didn't choose.
 - **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`.
 

package/skill/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

package/skill/references/models/seedance.md

@@ -13,18 +13,18 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 - **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too.
 - **Order inside each shot**: Subject → Action → Camera → Style → Constraints → (Audio/SFX if relevant).
-- **Prompt length**: aim for ~120–280 words TOTAL across all shots combined (not per shot). Shorter than ~120 words = random output. Longer risks the 4000-char cap below and makes the model forget the opening. For 6-shot prompts, keep each shot 1–2 tight sentences.
+- **Prompt length**: aim for ~120–280 words TOTAL across all shots combined (not per shot). Shorter than ~120 words = random output. Longer risks the 8000-char cap below and makes the model forget the opening. For 6-shot prompts, keep each shot 1–2 tight sentences.
 - **Character lock**: if a character recurs, open with `same character throughout all shots` to stop identity drift.
 - **Max 3 shots per single-shot prompt; max 6 shots in a multi-shot montage.** More causes drift.
 - **Always describe at least one camera movement per shot.**
 - **Tell Seedance what the camera is NOT doing** (e.g. `no cuts, no zoom, natural head movement`) — this is what locks POV.
 - **Final prompt is always English**, wrapped in a copy-ready code block. Detect intent in any language and reply in the user's language, but the prompt itself is English.
-- **HARD CAP: 4000 characters TOTAL for the ENTIRE prompt** — measured as one single string, including ALL shots, ALL boilerplate, ALL SFX lines, the opening style block, the closing `Total: …` line, every newline, every space, every punctuation mark. This is non-negotiable.
-  - Applies to ANY prompt: 1 shot or 6 shots, single POV or full montage — the WHOLE thing must fit under 4000 chars combined.
-  - It is NOT 4000 chars per shot. It is 4000 chars per prompt.
-  - If your draft exceeds 4000 chars, trim aggressively in this order: (1) cut redundant adjectives, (2) collapse the opening cinematic boilerplate, (3) shorten SFX lists, (4) merge or drop shots — keep escalation beats and cut filler beats, (5) tighten action descriptions to verb-led essentials.
+- **HARD CAP: 8000 characters TOTAL for the ENTIRE prompt** — measured as one single string, including ALL shots, ALL boilerplate, ALL SFX lines, the opening style block, the closing `Total: …` line, every newline, every space, every punctuation mark. This is non-negotiable.
+  - Applies to ANY prompt: 1 shot or 6 shots, single POV or full montage — the WHOLE thing must fit under 8000 chars combined.
+  - It is NOT 8000 chars per shot. It is 8000 chars per prompt.
+  - If your draft exceeds 8000 chars, trim aggressively in this order: (1) cut redundant adjectives, (2) collapse the opening cinematic boilerplate, (3) shorten SFX lists, (4) merge or drop shots — keep escalation beats and cut filler beats, (5) tighten action descriptions to verb-led essentials.
   - **Never** split into multiple prompts, multiple code blocks, or "part 1 / part 2" to evade the cap.
-  - Before outputting, internally count the characters of the final prompt as a single string. If > 4000, rewrite tighter and re-count. Repeat until ≤ 4000. Only then show the user.
+  - Before outputting, internally count the characters of the final prompt as a single string. If > 8000, rewrite tighter and re-count. Repeat until ≤ 8000. Only then show the user.
 
 ## The 5 Formats
 
@@ -83,7 +83,7 @@ When the user uploads a 3×3 grid image and asks for Seedance prompts, switch to
 - Final prompt(s) ALWAYS in a fenced code block ready to paste into the Seedance `prompt` field (or pass as `prompt` on `generate_video` / `generate_elements`).
 - After the code block, give a 1-line "why this works" note (camera/escalation/physics choice).
 - If user asked in any language other than English, write your explanation in their language but keep the prompt itself English.
-- **Never exceed 4000 characters TOTAL** for the entire prompt as one string — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 4000 per shot — 4000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
+- **Never exceed 8000 characters TOTAL** for the entire prompt as one string — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 8000 per shot — 8000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
 
 ## Seedance + Visual DNA / References
 

package/skill/references/workflows/marketing-studio.md

@@ -119,6 +119,68 @@ For ads that feature a specific product:
 
 If the user gives a **product URL** instead of a photo, see `workflows/research-first.md` — scrape, extract images, re-host via `upload_media`, persist as a brand kit at `.kolbo/brand-kits/<slug>.md`.
 
+<!-- SKILL-ONLY: no server parity — UGC output routes through the creative-director / veo / seedance enhancers, so any server-side rule lives in those parity files, not here. -->
+
+## Multi-Slot Board Method (structured shot specs + character consistency)
+
+For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. This is a prompt-only convention — no special MCP mode; it uses `generate_image` (board) + `generate_elements` / `generate_video_from_image` (per-slot animate) that already exist.
+
+### 1. Structured input slots
+
+Define each shot as one row. Fill every column before generating — blanks are where identity/quality drift creeps in.
+
+| Slot | Arc role | POV / framing | Presenter action | Product visibility | Aspect | Audio |
+|---|---|---|---|:-:|:-:|:-:|
+| 1 | hook | selfie arm, chest-up, eye contact | states the problem / grabs attention | held up to camera | 9:16 | monologue seg 1 |
+| 2 | demo | slightly wider, hands in frame | uses / demonstrates the product | in active use | 9:16 | monologue seg 2 |
+| 3 | payoff | back to selfie framing | reaction + soft CTA | resting in hand / on surface | 9:16 | monologue seg 3 |
+
+Scale to 2–6 slots. Keep `hook → demo → payoff` as the minimum arc; add `tension` / `proof` slots between demo and payoff for longer reviews.
+
+### 2. Rendering rules (hard invariants — apply to EVERY slot)
+
+- One aspect ratio across all slots (UGC = `9:16`). Never mix.
+- **No on-image text**, captions, subtitles, watermarks, or lower-thirds (users add captions in post).
+- **Identity lock**: same presenter, same wardrobe, same lighting environment across all slots — open the prompt with `same character throughout all shots`.
+- Hands and product must read cleanly — no deformed hands, no floating / clipping product, product logo legible when held.
+- Phone-shot aesthetic (handheld sway, window/screen key) unless the mode is polished (`tv_spot`, `product_showcase`).
+
+### 3. Board-first consistency (the grid technique)
+
+Before animating, generate ONE composite board image that locks the presenter's identity, then animate each panel:
+
+1. `generate_image` a labeled N-panel grid (2×2 or 1×N) of the presenter across the slot poses — front hook pose, hands-on-product demo pose, reaction pose — locked to `visual_dna_ids` (the presenter's Visual DNA). Aspect `16:9` for the board sheet.
+2. Treat that board image's CDN URL as the **`board_media_id`** — the single source of truth for identity.
+3. Animate each slot with `generate_video_from_image` / `generate_elements`, passing the board panel (and product) as `reference_images` and tagging `@image1`, so every clip inherits the same face/wardrobe.
+
+This mirrors how the best UGC pipelines keep a character consistent: lock once as a board, then move each shot — not N independent generations that drift.
+
+### 4. Structured parameters (what to carry per generation)
+
+Track these so each slot's call is reproducible and the arc stays coherent:
+
+| Param | Meaning | Maps to |
+|---|---|---|
+| `arc_role` | hook / tension / demo / proof / payoff | prompt framing + shot order |
+| `board_media_id` | the locked board image URL | `reference_images` (`@image1`) |
+| `character_media_id` / `visual_dna_id` | presenter identity | `visual_dna_ids` (`@<dna-name>`) |
+| `product_media_id` | product photo URL | `reference_images` (`@image2`) |
+| `input_tier` | `draft` (fast preview) vs `hero` (final) | model + resolution choice |
+| `monologue_segment` | the spoken line for this slot | prompt audio/dialogue line |
+| `aspect_ratio` / `duration` / `sound_enabled` | per UGC Family Defaults above | MCP call args |
+
+### 5. Worked example (brief → slots → board → clips)
+
+Brief: *"15s UGC review of a skincare serum, tech-savvy woman creator."*
+
+1. Ensure/create presenter Visual DNA (tech-savvy woman) → `visual_dna_id`.
+2. Board: `generate_image` a 3-panel `16:9` sheet — (a) chest-up hook holding the serum, (b) hands applying it, (c) thumbs-up reaction — `same character throughout all shots`, locked to the DNA. → `board_media_id`.
+3. Slots (each `9:16`, ~5s, sound OFF, animate from the matching board panel + product `@image2`):
+   - Slot 1 (hook): "Before this serum my routine was five products…" holding it to camera.
+   - Slot 2 (demo): hands applying, product in active use.
+   - Slot 3 (payoff): reaction + "…now it's just one step." soft CTA.
+4. Deliver as a structured message (setup + monologue + media), humanized refs (names/thumbnails, not raw IDs).
+
 ## UX Rules
 
 1. **Always pick a mode explicitly.** Don't auto-pick from one ambiguous word. If the user said "make me an ad" with no other signal, offer labeled options: `[UGC / TV Spot / Product Showcase / Surprise me]`.

package/src/apps/bridge.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * Minimal MCP Apps iframe bridge (io.modelcontextprotocol/ui, protocol 2026-01-26).
+ *
+ * Injected as an inline <script> into every ui://kolbo/* widget. Hand-rolled instead
+ * of shipping the 337KB @modelcontextprotocol/ext-apps browser bundle — implements the
+ * same JSON-RPC-over-postMessage handshake the official App class performs:
+ *
+ *   widget → host  request      ui/initialize { appInfo, appCapabilities, protocolVersion }
+ *   widget → host  notification ui/notifications/initialized
+ *   host  → widget notification ui/notifications/tool-result | tool-input | host-context-changed
+ *   widget → host  request      tools/call | ui/message | ui/open-link
+ *   widget → host  notification ui/notifications/size-changed
+ *
+ * Host-bound calls made before the handshake completes are queued (avoids the
+ * hidden-iframe race documented in claude-ai-mcp#61/#149).
+ *
+ * Exposed global: window.kolbo
+ *   .ready(fn)                 — fn(hostContext) after handshake
+ *   .onToolResult(fn)          — fn(result) for ui/notifications/tool-result
+ *   .onThemeChange(fn)         — fn(hostContext) on host-context-changed
+ *   .callTool(name, args)      — Promise<CallToolResult>
+ *   .sendMessage(text)         — append a user chat message (returns Promise)
+ *   .openLink(url)             — open external URL
+ *   .notifySize()              — report content size to host
+ */
+
+const BRIDGE_JS = `
+(function () {
+  var nextId = 1;
+  var pending = {};      // id -> {resolve, reject}
+  var initialized = false;
+  var queue = [];        // deferred host-bound sends until initialized
+  var hostContext = null;
+  var readyFns = [], toolResultFns = [], themeFns = [];
+
+  function post(msg) { window.parent.postMessage(msg, '*'); }
+
+  function request(method, params) {
+    return new Promise(function (resolve, reject) {
+      var id = nextId++;
+      pending[id] = { resolve: resolve, reject: reject };
+      var msg = { jsonrpc: '2.0', id: id, method: method, params: params || {} };
+      if (initialized || method === 'ui/initialize') post(msg);
+      else queue.push(msg);
+    });
+  }
+
+  function notify(method, params) {
+    var msg = { jsonrpc: '2.0', method: method, params: params || {} };
+    if (initialized || method === 'ui/notifications/initialized') post(msg);
+    else queue.push(msg);
+  }
+
+  window.addEventListener('message', function (ev) {
+    var m = ev.data;
+    if (!m || m.jsonrpc !== '2.0') return;
+    if (m.id != null && (m.result !== undefined || m.error !== undefined)) {
+      var p = pending[m.id];
+      if (!p) return;
+      delete pending[m.id];
+      if (m.error) p.reject(new Error(m.error.message || 'host error'));
+      else p.resolve(m.result);
+      return;
+    }
+    if (m.method === 'ui/notifications/tool-result') {
+      toolResultFns.forEach(function (f) { try { f(m.params || {}); } catch (e) {} });
+    } else if (m.method === 'ui/notifications/host-context-changed') {
+      hostContext = (m.params && m.params.hostContext) || m.params || hostContext;
+      themeFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
+    } else if (m.method === 'ui/resource-teardown' && m.id != null) {
+      post({ jsonrpc: '2.0', id: m.id, result: {} });
+    } else if (m.id != null) {
+      // Unknown host request — respond empty so the host isn't left hanging.
+      post({ jsonrpc: '2.0', id: m.id, result: {} });
+    }
+  });
+
+  request('ui/initialize', {
+    protocolVersion: '2026-01-26',
+    appInfo: { name: 'kolbo-widget', version: '1.0.0' },
+    appCapabilities: {}
+  }).then(function (res) {
+    hostContext = (res && res.hostContext) || null;
+    notify('ui/notifications/initialized');
+    initialized = true;
+    queue.forEach(post);
+    queue = [];
+    readyFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
+  }).catch(function () { /* host without apps support — widget stays static */ });
+
+  function notifySize() {
+    var el = document.documentElement;
+    notify('ui/notifications/size-changed', {
+      width: el.scrollWidth, height: el.scrollHeight
+    });
+  }
+
+  var sizeTimer = null;
+  new MutationObserver(function () {
+    clearTimeout(sizeTimer);
+    sizeTimer = setTimeout(notifySize, 120);
+  }).observe(document.documentElement, { childList: true, subtree: true, attributes: true });
+
+  window.kolbo = {
+    ready: function (f) { if (initialized) f(hostContext); else readyFns.push(f); },
+    onToolResult: function (f) { toolResultFns.push(f); },
+    onThemeChange: function (f) { themeFns.push(f); },
+    callTool: function (name, args) { return request('tools/call', { name: name, arguments: args || {} }); },
+    sendMessage: function (text) {
+      return request('ui/message', { role: 'user', content: [{ type: 'text', text: text }] });
+    },
+    openLink: function (url) { return request('ui/open-link', { url: url }); },
+    updateModelContext: function (text) {
+      return request('ui/update-model-context', { content: [{ type: 'text', text: text }] });
+    },
+    notifySize: notifySize,
+    hostContext: function () { return hostContext; }
+  };
+})();
+`;
+
+module.exports = { BRIDGE_JS };

package/src/apps/html.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const { BRIDGE_JS } = require('./bridge');
+const { KOLBO_CSS, KOLBO_LOGO_SVG } = require('./theme');
+
+/**
+ * Assemble a self-contained widget page. No build step — each widget module
+ * provides a body skeleton + its script; we wrap with theme, bridge, and the
+ * shared runtime helpers (theme sync, escaping, chips, formatting).
+ */
+function widgetPage({ title, body, script }) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+<style>${KOLBO_CSS}</style>
+</head>
+<body>
+${body}
+<script>${BRIDGE_JS}</script>
+<script>
+// ---- shared widget runtime ----
+var KOLBO_LOGO = ${JSON.stringify(KOLBO_LOGO_SVG)};
+function esc(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
+    return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+  });
+}
+function el(id) { return document.getElementById(id); }
+function fmtCredits(n) { return (n == null) ? '' : (Math.round(n * 100) / 100) + ' cr'; }
+function fmtDur(s) { if (s == null) return ''; s = Math.round(s); return s >= 60 ? Math.floor(s/60) + 'm ' + (s%60) + 's' : s + 's'; }
+function applyTheme(ctx) {
+  try {
+    var theme = ctx && (ctx.theme || (ctx.styles && ctx.styles.theme));
+    if (theme === 'light') document.documentElement.setAttribute('data-theme', 'light');
+    else if (theme === 'dark') document.documentElement.removeAttribute('data-theme');
+  } catch (e) {}
+}
+window.kolbo.ready(function (ctx) { applyTheme(ctx); window.kolbo.notifySize(); });
+window.kolbo.onThemeChange(applyTheme);
+
+// Model chip: real icon when the API provided one, brand monogram fallback.
+function modelChipHTML(name, iconUrl) {
+  if (!name) return '';
+  var inner = iconUrl
+    ? '<img src="' + esc(iconUrl) + '" onerror="this.outerHTML=monogram(\\'' + esc(name).replace(/'/g, '') + '\\')" alt="">'
+    : monogram(name);
+  return '<span class="k-chip brand">' + inner + esc(name) + '</span>';
+}
+function monogram(name) {
+  return '<span class="k-mono-icon">' + esc(String(name).trim().charAt(0).toUpperCase()) + '</span>';
+}
+// Pull structuredContent out of a tools/call result (host bridge shape).
+function structured(res) {
+  if (!res) return null;
+  if (res.structuredContent) return res.structuredContent;
+  try {
+    var t = (res.content || []).filter(function (c) { return c.type === 'text'; })[0];
+    return t ? JSON.parse(t.text) : null;
+  } catch (e) { return null; }
+}
+</script>
+<script>${script}</script>
+</body>
+</html>`;
+}
+
+module.exports = { widgetPage };

package/src/apps/index.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * MCP Apps integration (io.modelcontextprotocol/ui) — Kolbo interactive widgets.
+ *
+ * Registers the ui://kolbo/* HTML resources and provides the helpers tool files
+ * use to attach widgets to results. Everything here is ADDITIVE: text-only hosts
+ * (Claude Code, Cursor, old clients) ignore `_meta` + `structuredContent` and see
+ * exactly the same text responses as before.
+ */
+
+const {
+  registerAppResource,
+  getUiCapability,
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} = require('@modelcontextprotocol/ext-apps/server');
+
+const { generationWidgetHtml } = require('./widgets/generation');
+const { mediaGridWidgetHtml } = require('./widgets/mediaGrid');
+const { catalogWidgetHtml } = require('./widgets/catalog');
+const { transcriptWidgetHtml } = require('./widgets/transcript');
+
+const UI = {
+  generation: 'ui://kolbo/generation.html',
+  mediaGrid: 'ui://kolbo/media-grid.html',
+  catalog: 'ui://kolbo/catalog.html',
+  transcript: 'ui://kolbo/transcript.html',
+};
+
+const WIDGET_BUILDERS = {
+  [UI.generation]: generationWidgetHtml,
+  [UI.mediaGrid]: mediaGridWidgetHtml,
+  [UI.catalog]: catalogWidgetHtml,
+  [UI.transcript]: transcriptWidgetHtml,
+};
+
+// Widgets are pure functions of source — build once per process.
+const htmlCache = new Map();
+function widgetHtml(uri) {
+  if (!htmlCache.has(uri)) htmlCache.set(uri, WIDGET_BUILDERS[uri]());
+  return htmlCache.get(uri);
+}
+
+/** Register all Kolbo widget resources on an McpServer. */
+function registerApps(server) {
+  for (const [uri, name] of [
+    [UI.generation, 'Kolbo Generation Widget'],
+    [UI.mediaGrid, 'Kolbo Library Widget'],
+    [UI.catalog, 'Kolbo Model Catalog Widget'],
+    [UI.transcript, 'Kolbo Transcription Widget'],
+  ]) {
+    registerAppResource(server, name, uri, { mimeType: RESOURCE_MIME_TYPE }, async () => ({
+      contents: [{ uri, mimeType: RESOURCE_MIME_TYPE, text: widgetHtml(uri) }],
+    }));
+  }
+}
+
+/** `_meta` for a tool RESULT (and optionally for tool registration). */
+function uiMeta(uri) {
+  return { [RESOURCE_URI_META_KEY]: uri, ui: { resourceUri: uri } };
+}
+
+/**
+ * Should this server instance produce widget results?
+ * - `opts.apps === true` — set by the kolbo-api remote connector (claude.ai),
+ *   where the stateless transport makes client capabilities unavailable per-call.
+ * - stdio hosts (Claude Desktop) — detected from the initialize handshake.
+ * - `KOLBO_MCP_APPS=1|0` env — manual override for local testing.
+ */
+function appsEnabled(server, opts = {}) {
+  if (process.env.KOLBO_MCP_APPS === '0') return false;
+  if (opts.apps === true || process.env.KOLBO_MCP_APPS === '1') return true;
+  try {
+    const caps = server?.server?.getClientCapabilities?.();
+    return getUiCapability(caps) !== undefined;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Build a widget-carrying tool result. `text` stays the LLM-facing source of
+ * truth; `structured` goes to the widget only.
+ */
+function uiResult(uri, text, structured) {
+  return {
+    content: [{ type: 'text', text }],
+    structuredContent: structured,
+    _meta: uiMeta(uri),
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Model icon lookup (name/identifier → absolute avatar URL)           */
+/* ------------------------------------------------------------------ */
+
+const ICON_TTL_MS = 10 * 60 * 1000;
+const iconCache = new Map(); // apiBase → { at, byKey: Map<lowername, url> }
+
+async function modelIconMap(client) {
+  const cacheKey = client.apiBase || 'default';
+  const hit = iconCache.get(cacheKey);
+  if (hit && Date.now() - hit.at < ICON_TTL_MS) return hit.byKey;
+  const byKey = new Map();
+  try {
+    const res = await client.request('GET', '/v1/models');
+    const models = res?.models || res?.data?.models || [];
+    for (const m of models) {
+      if (!m || !m.avatar) continue;
+      // The API usually resolves avatars to absolute URLs; bare filenames (older
+      // deployments / internal calls) resolve against the app's public icon dir.
+      const url = /^https?:\/\//i.test(m.avatar)
+        ? m.avatar
+        : `https://app.kolbo.ai/models_icons/${encodeURIComponent(m.avatar)}`;
+      if (m.name) byKey.set(String(m.name).toLowerCase(), url);
+      if (m.identifier) byKey.set(String(m.identifier).toLowerCase(), url);
+    }
+  } catch (_) {
+    /* fail open — widgets fall back to monogram chips */
+  }
+  iconCache.set(cacheKey, { at: Date.now(), byKey });
+  return byKey;
+}
+
+/** Resolve one model's icon URL; null → widget renders a monogram. */
+async function modelIcon(client, modelName) {
+  if (!modelName) return null;
+  const map = await modelIconMap(client);
+  return map.get(String(modelName).toLowerCase()) || null;
+}
+
+module.exports = {
+  UI,
+  registerApps,
+  uiMeta,
+  uiResult,
+  appsEnabled,
+  modelIcon,
+  modelIconMap,
+  widgetHtml, // exported for smoke tests
+};