@kolbo/mcp 1.28.1 → 1.30.0

package/src/index.js

@@ -72,6 +72,8 @@ const { registerProjectTools } = require('./tools/projects');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
+const { registerShortsCreatorTools } = require('./tools/shorts_creator');
+const { registerApps } = require('./apps');
 
 /**
  * Build a fully-configured Kolbo MCP server (all tool groups registered)
@@ -83,6 +85,11 @@ const { registerStockLibraryTools } = require('./tools/stock_library');
  * @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 = {}) {
@@ -95,20 +102,27 @@ function createServer(opts = {}) {
 
   // Register all tools. `inlineImages` (off by default) is opt-in: only the
   // remote HTTP host enables it, so stdio clients (Kolbo Code / Desktop / Cursor)
-  // keep identical text-URL output.
-  registerGenerateTools(server, client, { inlineImages: !!opts.inlineImages });
-  registerModelTools(server, client);
-  registerVoiceTools(server, client);
-  registerChatTools(server, client);
-  registerVisualDnaTools(server, client);
-  registerMoodboardTools(server, client);
-  registerMediaTools(server, client);
-  registerPresetTools(server, client);
-  registerAppBuilderTools(server, client);
-  registerArtifactTools(server, client);
-  registerProjectTools(server, client);
-  registerMusicLibraryTools(server, client);
-  registerStockLibraryTools(server, client);
+  // 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);
+  registerMediaTools(server, client, toolOptions);
+  registerPresetTools(server, client, toolOptions);
+  registerAppBuilderTools(server, client, toolOptions);
+  registerArtifactTools(server, client, toolOptions);
+  registerProjectTools(server, client, toolOptions);
+  registerMusicLibraryTools(server, client, toolOptions);
+  registerStockLibraryTools(server, client, toolOptions);
+  registerShortsCreatorTools(server, client, toolOptions);
+
+  // MCP Apps widget resources (ui://kolbo/*). Registering resources is inert
+  // for text-only hosts — they never fetch them.
+  registerApps(server);
 
   return server;
 }

package/src/tools/_shared.js

@@ -291,6 +291,78 @@ async function inlineImageBlocks(urls, opts = {}) {
   return blocks.filter(Boolean);
 }
 
+// ─── MCP Apps generation widget helpers ──────────────────────────────────────
+// When the host renders MCP Apps (claude.ai via the remote connector, Claude
+// Desktop over stdio), generation tools return IMMEDIATELY after submit and the
+// ui://kolbo/generation.html widget takes over: live progress, inline result,
+// action buttons. Text-only hosts never enter this path — their blocking
+// behavior and response bytes are UNCHANGED.
+const { UI, uiResult, appsEnabled, modelIcon } = require('../apps');
+
+/**
+ * Build the "submitted — widget is live" tool result for a UI host.
+ * @param {object} p
+ *   tool           MCP tool name (e.g. 'generate_image')
+ *   kind           'image' | 'video' | 'audio' | '3d' | 'scenes'
+ *   gen            the submit response ({ generation_id, poll_interval_hint })
+ *   client         KolboClient (for model icon lookup)
+ *   model, prompt, count, settings, reference_image, estimated_seconds
+ *   poll_tool      widget-side status tool (default 'get_generation_status')
+ *   status_args    args for poll_tool (default { generation_id })
+ */
+async function uiGenerating(p) {
+  const icon = await modelIcon(p.client, p.model).catch(() => null);
+  const structured = {
+    phase: 'generating',
+    widget: 'generation',
+    kind: p.kind,
+    tool: p.tool,
+    generation_id: p.gen.generation_id,
+    poll_tool: p.poll_tool || 'get_generation_status',
+    status_args: p.status_args,
+    model: p.model || 'Smart Select',
+    model_icon: icon,
+    prompt: p.prompt,
+    count: p.count || 1,
+    settings: p.settings || {},
+    reference_image: p.reference_image,
+    estimated_seconds: p.estimated_seconds,
+  };
+  const text = JSON.stringify({
+    status: 'submitted',
+    generation_id: p.gen.generation_id,
+    _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update — do NOT poll in a loop. If you later need the output URLs (e.g. for a follow-up edit), call get_generation_status once with this generation_id.',
+  }, null, 2);
+  return uiResult(UI.generation, text, structured);
+}
+
+/**
+ * Wrap an already-completed generation result with the widget (used by tools
+ * that stay blocking even on UI hosts, e.g. creative director).
+ */
+async function uiCompleted(p, textPayload) {
+  const icon = await modelIcon(p.client, p.model).catch(() => null);
+  const structured = {
+    phase: 'completed',
+    widget: 'generation',
+    kind: p.kind,
+    tool: p.tool,
+    model: p.model || 'Smart Select',
+    model_icon: icon,
+    prompt: p.prompt,
+    count: p.count || 1,
+    settings: p.settings || {},
+    reference_image: p.reference_image,
+    urls: p.urls,
+    thumbnail_url: p.thumbnail_url,
+    title: p.title,
+    duration: p.duration,
+    scenes: p.scenes,
+    credits_used: p.credits_used,
+  };
+  return uiResult(UI.generation, textPayload, structured);
+}
+
 module.exports = {
   MAX_FILE_BYTES,
   VISUAL_DNA_MAX_BYTES,
@@ -303,4 +375,7 @@ module.exports = {
   creditFields,
   projectIdField,
   inlineImageBlocks,
+  uiGenerating,
+  uiCompleted,
+  appsEnabled,
 };

package/src/tools/generate.js

@@ -6,13 +6,18 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks } = require('./_shared');
+const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
+const { UI, uiResult } = require('../apps');
 
 function registerGenerateTools(server, client, options = {}) {
   // Only enabled by hosts that explicitly opt in (the remote HTTP connector).
   // stdio hosts (Kolbo Code, Claude Desktop, Cursor) leave this false, so their
   // tool output is unchanged: a text block with the image URL.
   const inlineImages = !!options.inlineImages;
+  // MCP Apps hosts (claude.ai remote connector, Claude Desktop) get an instant
+  // "submitted" response + a live ui://kolbo/generation.html widget that polls
+  // get_generation_status itself. Text-only hosts never take this branch.
+  const ui = () => appsEnabled(server, options);
   // ─── generate_image ────────────────────────────────────────
   server.tool(
     'generate_image',
@@ -37,6 +42,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_image', kind: 'image', gen, client, model, prompt,
+        count: num_images, settings: { resolution, aspect_ratio },
+        reference_image: reference_images?.[0], estimated_seconds: 25
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 3) * 1000,
         timeout: 120000
@@ -81,6 +92,12 @@ function registerGenerateTools(server, client, options = {}) {
         visual_dna_ids, moodboard_id, enable_web_search, resolution, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_image_edit', kind: 'image', gen, client, model, prompt,
+        count: num_images, settings: { resolution, aspect_ratio },
+        reference_image: source_images?.[0], estimated_seconds: 40
+      });
+
       // Multi-source compositing or DNA-anchored edits routinely exceed 120s
       // server-side. Extend the polling window in those cases to avoid forcing
       // every call into the timeout-and-recover path via get_generation_status.
@@ -146,18 +163,24 @@ function registerGenerateTools(server, client, options = {}) {
           video_urls: s.video_urls
         }));
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            scenes,
-            total_scenes: result.scenes?.length || 0,
-            completed_scenes: scenes.length,
-            _followup_hint: 'Each scene is a separate asset. If the user asks to edit one scene, find that scene by scene_number/title and pass its image_urls[0] (or video_urls[0]) to generate_image_edit / edit_image / edit_video / generate_video_from_video. Do NOT re-run generate_creative_director unless the user explicitly wants a brand-new set.'
-          }, null, 2)
-        }]
-      };
+      const cdText = JSON.stringify({
+        ...creditFields(result),
+        scenes,
+        total_scenes: result.scenes?.length || 0,
+        completed_scenes: scenes.length,
+        _followup_hint: 'Each scene is a separate asset. If the user asks to edit one scene, find that scene by scene_number/title and pass its image_urls[0] (or video_urls[0]) to generate_image_edit / edit_image / edit_video / generate_video_from_video. Do NOT re-run generate_creative_director unless the user explicitly wants a brand-new set.'
+      }, null, 2);
+
+      // Creative Director polls a dedicated status route the widget can't reach
+      // through get_generation_status, so it stays blocking on UI hosts too and
+      // renders the completed scene gallery.
+      if (ui()) return uiCompleted({
+        tool: 'generate_creative_director', kind: 'scenes', client, model, prompt,
+        settings: { duration, resolution, mode: workflow_type }, scenes,
+        credits_used: creditFields(result).credits_used
+      }, cdText);
+
+      return { content: [{ type: 'text', text: cdText }] };
     }
   );
 
@@ -185,6 +208,12 @@ function registerGenerateTools(server, client, options = {}) {
         prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_video', kind: 'video', gen, client, model, prompt,
+        settings: { duration, resolution, aspect_ratio },
+        reference_image: reference_images?.[0], estimated_seconds: 120
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 300000
@@ -227,6 +256,12 @@ function registerGenerateTools(server, client, options = {}) {
         image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_video_from_image', kind: 'video', gen, client, model, prompt,
+        settings: { duration, resolution, aspect_ratio },
+        reference_image: image_url, estimated_seconds: 120
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 300000
@@ -268,6 +303,12 @@ function registerGenerateTools(server, client, options = {}) {
         prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt, preset_id, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_music', kind: 'audio', gen, client, model: model || 'Suno', prompt,
+        settings: { mode: instrumental ? 'instrumental' : (style || undefined) },
+        estimated_seconds: 90
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 300000
@@ -304,6 +345,11 @@ function registerGenerateTools(server, client, options = {}) {
         text, voice, model, language, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_speech', kind: 'audio', gen, client, model, prompt: text,
+        settings: { voice: voice || 'Rachel' }, estimated_seconds: 20
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 120000
@@ -339,6 +385,11 @@ function registerGenerateTools(server, client, options = {}) {
         prompt, model, duration, prompt_influence, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_sound', kind: 'audio', gen, client, model, prompt,
+        settings: { duration }, estimated_seconds: 20
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 120000
@@ -432,6 +483,12 @@ function registerGenerateTools(server, client, options = {}) {
         });
       }
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_elements', kind: 'video', gen: startResponse, client, model, prompt,
+        settings: { duration, resolution, aspect_ratio },
+        reference_image: reference_images?.[0], estimated_seconds: 180
+      });
+
       const result = await pollUntilDone(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
@@ -504,6 +561,12 @@ function registerGenerateTools(server, client, options = {}) {
         });
       }
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_first_last_frame', kind: 'video', gen: startResponse, client, model, prompt,
+        settings: { duration, resolution, aspect_ratio },
+        reference_image: first_frame_url || undefined, estimated_seconds: 120
+      });
+
       const result = await pollUntilDone(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 300000
@@ -607,6 +670,13 @@ function registerGenerateTools(server, client, options = {}) {
         startResponse = await client.postMultipart('/v1/generate/lipsync', form);
       }
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_lipsync', kind: 'video', gen: startResponse, client, model,
+        prompt: text_prompt, settings: { mode: 'lipsync' },
+        reference_image: sourceIsUrl && !/\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? source : undefined,
+        estimated_seconds: 180
+      });
+
       const result = await pollUntilDone(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
@@ -699,6 +769,13 @@ function registerGenerateTools(server, client, options = {}) {
         startResponse = await client.postMultipart('/v1/generate/video-from-video', form);
       }
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_video_from_video', kind: 'video', gen: startResponse, client, model,
+        prompt: prompt || (preset ? `Subtitles preset: ${preset}` : undefined),
+        settings: { duration, resolution, aspect_ratio, mode: preset ? 'subtitles' : 'restyle' },
+        reference_image: reference_images?.[0], estimated_seconds: 240
+      });
+
       const result = await pollUntilDone(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
@@ -742,6 +819,19 @@ function registerGenerateTools(server, client, options = {}) {
         startResponse = await client.postMultipart('/v1/transcribe', form);
       }
 
+      if (ui()) {
+        return uiResult(UI.transcript, JSON.stringify({
+          status: 'submitted',
+          generation_id: startResponse.generation_id,
+          _widget_note: 'A live Kolbo transcription widget is rendering above — it shows progress, the transcript text, and SRT/TXT download buttons. Tell the user it is transcribing. If you need the transcript text for a follow-up step, call get_generation_status with this generation_id once done.',
+        }, null, 2), {
+          widget: 'transcript', phase: 'generating',
+          generation_id: startResponse.generation_id,
+          poll_tool: 'get_generation_status',
+          audio_url: isUrl ? source : undefined,
+        });
+      }
+
       const result = await pollUntilDone(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 5) * 1000,
         timeout: 1800000 // 30 minutes — long podcasts are a thing
@@ -797,6 +887,12 @@ function registerGenerateTools(server, client, options = {}) {
         project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'generate_3d', kind: '3d', gen: startResponse, client, model, prompt,
+        settings: { mode: mode || (reference_images?.length > 1 ? 'multi' : reference_images?.length === 1 ? 'single' : 'text') },
+        reference_image: reference_images?.[0], estimated_seconds: 300
+      });
+
       const result = await pollUntilDone(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 900000 // 15 minutes — 3D generation is slow
@@ -840,6 +936,13 @@ function registerGenerateTools(server, client, options = {}) {
         image_url, operation, model, scale, aspect_ratio, skin_strength, prompt, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'edit_image', kind: 'image', gen, client, model,
+        prompt: prompt || operation,
+        settings: { mode: operation, aspect_ratio },
+        reference_image: image_url, estimated_seconds: 40
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 180000
@@ -890,6 +993,13 @@ function registerGenerateTools(server, client, options = {}) {
         image_url, audio_url, duration, mode, project_id
       });
 
+      if (ui()) return uiGenerating({
+        tool: 'edit_video', kind: 'video', gen, client, model,
+        prompt: prompt || operation,
+        settings: { mode: operation, duration, aspect_ratio },
+        reference_image: image_url, estimated_seconds: 180
+      });
+
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 600000

package/src/tools/media.js

@@ -6,8 +6,10 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { resolveToBuffer } = require('./_shared');
+const { UI, uiResult, appsEnabled } = require('../apps');
 
-function registerMediaTools(server, client) {
+function registerMediaTools(server, client, options = {}) {
+  const ui = () => appsEnabled(server, options);
   // ─── upload_media ──────────────────────────────────────────
   server.tool(
     'upload_media',
@@ -72,13 +74,32 @@ function registerMediaTools(server, client) {
       const qs = params.toString();
       const result = await client.get(`/v1/media${qs ? '?' + qs : ''}`);
 
+      const media = result.media || [];
+      const pagination = result.pagination || null;
+      const text = JSON.stringify({ media, pagination }, null, 2);
+
+      if (ui()) {
+        const items = media.slice(0, 24).map((m) => ({
+          id: m.id,
+          title: m.filename,
+          subtitle: m.media_type + (m.size ? ' · ' + Math.round(m.size / 1024) + 'KB' : ''),
+          thumbnail: m.media_type === 'image' ? m.url : (m.thumbnail_url || null),
+          media_type: m.media_type,
+          url: m.url,
+          use_hint: 'Use this media library asset in my next step:\nURL: {URL}\n(id: {ID})'
+        }));
+        return uiResult(UI.mediaGrid, text, {
+          widget: 'media-grid',
+          title: 'Media Library',
+          items,
+          total: pagination && pagination.total != null ? pagination.total : media.length
+        });
+      }
+
       return {
         content: [{
           type: 'text',
-          text: JSON.stringify({
-            media: result.media || [],
-            pagination: result.pagination || null
-          }, null, 2)
+          text
         }]
       };
     }

package/src/tools/models.js

@@ -4,8 +4,72 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
+const { UI, uiResult, appsEnabled } = require('../apps');
 
-function registerModelTools(server, client) {
+// type name → human group label for the catalog widget
+const TYPE_GROUPS = {
+  text_to_img: 'Image Generation',
+  text_to_video: 'Video Generation',
+  img_to_video: 'Video Generation',
+  music_gen: 'Music',
+  text_to_speech: 'Voice',
+  image_editing: 'Image Editing',
+  video_to_video: 'Video to Video',
+  elements: 'Elements',
+};
+
+function groupNameFor(m) {
+  const t = (Array.isArray(m.types) && m.types[0]) || m.type || '';
+  if (TYPE_GROUPS[t]) return TYPE_GROUPS[t];
+  if (t === 'three_d' || String(t).startsWith('3d_')) return '3D';
+  return 'Other';
+}
+
+function modelChips(m) {
+  const chips = [];
+  if (Array.isArray(m.supported_resolutions) && m.supported_resolutions.length) {
+    const highest = [...m.supported_resolutions]
+      .sort((a, b) => (parseInt(a, 10) || 0) - (parseInt(b, 10) || 0))
+      .pop();
+    if (highest) chips.push(String(highest));
+  }
+  if (Array.isArray(m.supported_durations) && m.supported_durations.length) {
+    const ds = [...m.supported_durations].sort((a, b) => a - b);
+    chips.push(ds.length > 1 ? `${ds[0]}-${ds[ds.length - 1]}s` : `${ds[0]}s`);
+  }
+  if (m.supports_visual_dna) chips.push('DNA');
+  if (m.new_model || m.newModel) chips.push('NEW');
+  return chips.slice(0, 3);
+}
+
+// structuredContent for ui://kolbo/catalog.html — see src/apps/widgets/catalog.js
+function buildCatalogStructured(models, type) {
+  const groups = [];
+  const byName = new Map();
+  for (const m of models) {
+    const name = groupNameFor(m);
+    let g = byName.get(name);
+    if (!g) { g = { name, models: [] }; byName.set(name, g); groups.push(g); }
+    if (g.models.length >= 12) continue; // cap per group (≤60 total across groups)
+    g.models.push({
+      name: m.name,
+      icon: m.avatar
+        ? (/^https?:\/\//i.test(m.avatar) ? m.avatar : `https://app.kolbo.ai/models_icons/${m.avatar}`)
+        : null,
+      description: String(m.smartSelect_StrengthsSummary || m.summary || m.description || '').slice(0, 90),
+      chips: modelChips(m),
+      use_hint: `Generate with the "${m.name}" model — ask me what I want to create first.`,
+    });
+  }
+  return {
+    widget: 'catalog',
+    title: 'Kolbo AI Models' + (type ? ' — ' + type : ''),
+    groups,
+  };
+}
+
+function registerModelTools(server, client, options = {}) {
+  const ui = () => appsEnabled(server, options);
   // ─── list_models ───────────────────────────────────────────
   server.tool(
     'list_models',
@@ -23,12 +87,9 @@ function registerModelTools(server, client) {
       // a request lives here (durations, reference caps, audio/video min/max,
       // resolution multipliers, supports_* flags, prompt-length limits, etc.).
       if (format === 'json') {
-        return {
-          content: [{
-            type: 'text',
-            text: JSON.stringify({ count: result.count, models: result.models }, null, 2)
-          }]
-        };
+        const text = JSON.stringify({ count: result.count, models: result.models }, null, 2);
+        if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type));
+        return { content: [{ type: 'text', text }] };
       }
 
       // Split into auto-selectable (has summary) and named-only (no summary)
@@ -197,12 +258,9 @@ function registerModelTools(server, client) {
         sections.push(`Named-only models (${withoutSummary.length}) — only use if the user explicitly requests by name:\n${withoutSummary.map(formatModel).join('\n')}`);
       }
 
-      return {
-        content: [{
-          type: 'text',
-          text: `Available models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools. For programmatic cap validation, re-call with format: "json".`
-        }]
-      };
+      const text = `Available models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools. For programmatic cap validation, re-call with format: "json".`;
+      if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type));
+      return { content: [{ type: 'text', text }] };
     }
   );
 

package/src/tools/moodboards.js

@@ -4,8 +4,10 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
+const { UI, uiResult, appsEnabled } = require('../apps');
 
-function registerMoodboardTools(server, client) {
+function registerMoodboardTools(server, client, options = {}) {
+  const ui = () => appsEnabled(server, options);
   // ─── list_moodboards ───────────────────────────────────────
   server.tool(
     'list_moodboards',
@@ -18,15 +20,29 @@ function registerMoodboardTools(server, client) {
       if (scope && scope !== 'all') params.set('scope', scope);
       const qs = params.toString();
       const result = await client.get(`/v1/moodboards${qs ? '?' + qs : ''}`);
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            moodboards: result.moodboards || [],
-            count: result.count || 0
-          }, null, 2)
-        }]
-      };
+      const moodboards = result.moodboards || [];
+      const text = JSON.stringify({
+        moodboards,
+        count: result.count || 0
+      }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.mediaGrid, text, {
+          widget: 'media-grid',
+          title: 'Moodboards',
+          items: moodboards.slice(0, 24).map(mb => ({
+            id: mb.id,
+            title: mb.name,
+            thumbnail: mb.thumbnail || (Array.isArray(mb.image_urls) ? mb.image_urls[0] : undefined),
+            media_type: 'image',
+            use_hint: 'Apply moodboard "{TITLE}" (moodboard_id: {ID}) to my next generation.'
+          })),
+          total: result.count || moodboards.length,
+          has_more: moodboards.length > 24
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );