@kolbo/mcp 1.52.1 → 1.53.0

package/package.json

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

package/src/apps/index.js

@@ -21,6 +21,7 @@ const { mediaGridWidgetHtml } = require('./widgets/mediaGrid');
 const { catalogWidgetHtml } = require('./widgets/catalog');
 const { transcriptWidgetHtml } = require('./widgets/transcript');
 const { uploadWidgetHtml } = require('./widgets/upload');
+const { listWidgetHtml } = require('./widgets/list');
 
 const UI = {
   generation: 'ui://kolbo/generation.html',
@@ -28,6 +29,7 @@ const UI = {
   catalog: 'ui://kolbo/catalog.html',
   transcript: 'ui://kolbo/transcript.html',
   upload: 'ui://kolbo/upload.html',
+  list: 'ui://kolbo/list.html',
 };
 
 const WIDGET_BUILDERS = {
@@ -36,6 +38,7 @@ const WIDGET_BUILDERS = {
   [UI.catalog]: catalogWidgetHtml,
   [UI.transcript]: transcriptWidgetHtml,
   [UI.upload]: uploadWidgetHtml,
+  [UI.list]: listWidgetHtml,
 };
 
 // Widgets are pure functions of source — build once per process.
@@ -93,6 +96,7 @@ function registerApps(server) {
     [UI.catalog, 'Kolbo Model Catalog Widget'],
     [UI.transcript, 'Kolbo Transcription Widget'],
     [UI.upload, 'Kolbo Upload Widget'],
+    [UI.list, 'Kolbo List Widget'],
   ]) {
     registerAppResource(
       server, name, uri,
@@ -292,8 +296,21 @@ const TOOL_WIDGETS = {
   list_visual_dnas: UI.mediaGrid,
   list_moodboards: UI.mediaGrid,
   shorts_analyze: UI.mediaGrid,
+  // NOTE: list_color_palettes' handler has always called uiResult(UI.mediaGrid, ...)
+  // (see color_palettes.js) but was missing here — hosts that prepare the widget
+  // iframe from the tool DECLARATION (claude.ai reads tools/list, not the result)
+  // never saw it as widget-carrying. Result-level _meta alone isn't enough.
+  list_color_palettes: UI.mediaGrid,
   // upload widget
   media_upload_widget: UI.upload,
+  // generic list widget — flat record lists with no natural thumbnail
+  list_projects: UI.list,
+  list_sessions: UI.list,
+  list_project_context: UI.list,
+  list_agents: UI.list,
+  list_docs: UI.list,
+  list_media_folders: UI.list,
+  list_visual_dna_folders: UI.list,
 };
 
 function attachToolWidgetMeta(server) {

package/src/apps/theme.js

@@ -242,8 +242,9 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 .k-cell { position: relative; border-radius: 10px; overflow: hidden; border: 1px solid var(--border);
   background: var(--surface); cursor: pointer; transition: transform 250ms var(--spring); }
 .k-cell:hover { transform: translateY(-2px) scale(1.01); }
-.k-cell .k-cell-media { aspect-ratio: 1; background: #000; }
+.k-cell .k-cell-media { position: relative; aspect-ratio: 1; background: #000; }
 .k-cell .k-cell-media img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.k-cell-play { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); }
 .k-cell .k-cell-label { padding: 6px 8px; font-size: 11px; color: var(--text-muted);
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .k-cell .k-cell-sub { padding: 0 8px 7px; font-size: 10px; color: var(--text-faint);
@@ -274,7 +275,7 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 @media (max-width: 520px) {
   .k-generated-audio { grid-template-columns: 36px minmax(0, 1fr); }
   .k-generated-audio .k-audio-art { width: 36px; height: 36px; }
-  .k-generated-audio .k-audio-download { grid-column: 2; justify-self: start; }
+  .k-generated-audio .k-btn { grid-column: 2; justify-self: start; }
   .k-generated-audio .k-audio-player { grid-column: 1 / -1; }
 }
 .k-play {

package/src/apps/widgets/list.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const { widgetPage } = require('../html');
+
+/**
+ * Generic list widget — for tools that return a flat list of named records
+ * with no natural thumbnail (projects, sessions, agents, docs, folders,
+ * knowledge-base sources). Reuses the exact row shell mediaGrid's audio rows
+ * and catalog's model rows already use (`.k-audio-row` / `.k-audio-meta` /
+ * `.k-chip` / `.k-btn` — no new CSS needed).
+ *
+ * structuredContent contract:
+ * {
+ *   widget: 'list',
+ *   title: 'Your Projects',
+ *   items: [{
+ *     id, title, subtitle,        // main two lines
+ *     badge,                      // small pill, e.g. role/status ("owner", "default", "shared")
+ *     meta,                       // small trailing text, e.g. a date or count
+ *     open_url,                   // optional — renders an "Open" button (openLink)
+ *     use_hint                    // optional — row becomes clickable, sends this on click
+ *   }],
+ *   total
+ * }
+ */
+
+const BODY = `
+<div class="k-card">
+  <div class="k-head">
+    <span class="k-logo" id="logo"></span>
+    <span class="k-title" id="title"></span>
+    <span class="k-spacer"></span>
+    <span class="k-chip" id="count-chip" style="display:none"></span>
+  </div>
+  <div class="k-body"><div id="stage" class="k-empty">Loading…</div></div>
+  <div class="k-footer"><span>Powered by <a href="#" id="kolbo-link">Kolbo.AI</a></span></div>
+</div>
+`;
+
+const SCRIPT = `
+el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
+el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai'); };
+var state = null;
+
+function boot(sc) {
+  if (!sc || !sc.items) return;
+  state = sc;
+  el('title').textContent = sc.title || 'List';
+  var total = sc.total != null ? sc.total : sc.items.length;
+  el('count-chip').style.display = '';
+  el('count-chip').textContent = total + (total === 1 ? ' item' : ' items');
+  if (!sc.items.length) { el('stage').innerHTML = '<div class="k-empty">Nothing here yet</div>'; return; }
+  el('stage').innerHTML = sc.items.slice(0, 40).map(itemHTML).join('');
+  el('stage').classList.remove('k-empty');
+  wire();
+  window.kolbo.notifySize();
+}
+
+function itemHTML(item, i) {
+  var clickable = !!item.use_hint;
+  return '<div class="k-audio-row" data-i="' + i + '"' + (clickable ? ' style="cursor:pointer"' : '') + '>' +
+    monogram(item.title || '?') +
+    '<div class="k-audio-meta"><div class="k-audio-title">' + esc(item.title || '') + '</div>' +
+    (item.subtitle ? '<div class="k-audio-sub">' + esc(item.subtitle) + '</div>' : '') + '</div>' +
+    (item.badge ? '<span class="k-chip" style="flex:none">' + esc(item.badge) + '</span>' : '') +
+    (item.meta ? '<span style="flex:none;font-size:10.5px;color:var(--text-faint)">' + esc(item.meta) + '</span>' : '') +
+    (item.open_url ? '<button class="k-btn" data-open="' + i + '">Open</button>' : '') +
+    '</div>';
+}
+
+function wire() {
+  Array.prototype.forEach.call(document.querySelectorAll('[data-open]'), function (b) {
+    b.onclick = function (e) {
+      e.stopPropagation();
+      window.kolbo.openLink(state.items[+b.getAttribute('data-open')].open_url);
+    };
+  });
+  Array.prototype.forEach.call(document.querySelectorAll('.k-audio-row'), function (row) {
+    var item = state.items[+row.getAttribute('data-i')];
+    if (!item || !item.use_hint) return;
+    row.onclick = function () {
+      var msg = item.use_hint.replace('{TITLE}', item.title || '').replace('{ID}', item.id || '');
+      window.kolbo.sendMessage(msg);
+    };
+  });
+}
+
+window.kolbo.onToolResult(function (result) {
+  var sc = result.structuredContent || structured(result);
+  if (sc && sc.items) return boot(sc);
+  var card = document.querySelector('.k-card');
+  if (card) card.style.display = 'none';
+  window.kolbo.notifySize();
+});
+`;
+
+function listWidgetHtml() {
+  return widgetPage({ title: 'Kolbo List', body: BODY, script: SCRIPT });
+}
+
+module.exports = { listWidgetHtml };

package/src/apps/widgets/mediaGrid.js

@@ -38,7 +38,6 @@ const SCRIPT = `
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
 el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai'); };
 var state = null;
-var playing = null;
 
 function boot(sc) {
   if (!sc || !sc.items) return;
@@ -63,12 +62,15 @@ function boot(sc) {
 
 function cellHTML(item, i) {
   var idx = state.items.indexOf(item);
+  var isVideo = item.media_type === 'video' && item.url;
   var media = item.thumbnail
     ? '<img src="' + esc(item.thumbnail) + '" loading="lazy" alt="">'
     : '<div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text-faint);font-size:22px">' +
       kindIcon(item.media_type) + '</div>';
   return '<div class="k-cell" data-i="' + idx + '">' +
-    '<div class="k-cell-media">' + media + '</div>' +
+    '<div class="k-cell-media">' + media +
+    (isVideo ? '<button class="k-play k-cell-play" data-video-play="' + esc(item.url) + '">' + ICONS.play + '</button>' : '') +
+    '</div>' +
     '<div class="k-cell-label">' + esc(item.title || '') + '</div>' +
     (item.subtitle ? '<div class="k-cell-sub">' + esc(item.subtitle) + '</div>' : '') +
     '</div>';
@@ -76,13 +78,14 @@ function cellHTML(item, i) {
 
 function audioRowHTML(item) {
   var idx = state.items.indexOf(item);
-  return '<div class="k-audio-row" data-i="' + idx + '">' +
+  var src = item.preview_audio || item.url;
+  return '<div class="k-audio-row k-generated-audio" data-i="' + idx + '">' +
     (item.thumbnail ? '<img class="k-audio-art" src="' + esc(item.thumbnail) + '">' : '<div class="k-audio-art"></div>') +
     '<div class="k-audio-meta"><div class="k-audio-title">' + esc(item.title || '') + '</div>' +
     '<div class="k-audio-sub">' + esc(item.subtitle || '') + '</div></div>' +
-    (item.preview_audio || item.url
-      ? '<button class="k-play" data-play="' + esc(item.preview_audio || item.url) + '">' + ICONS.play + '</button>' : '') +
-    '<button class="k-btn" data-use="' + idx + '">Use</button></div>';
+    '<button class="k-btn" data-use="' + idx + '">Use</button>' +
+    (src ? '<audio class="k-audio-player" src="' + esc(src) + '" controls preload="none" aria-label="Play ' + esc(item.title || '') + '"></audio>' : '') +
+    '</div>';
 }
 
 function wire() {
@@ -92,17 +95,25 @@ function wire() {
   Array.prototype.forEach.call(document.querySelectorAll('[data-use]'), function (b) {
     b.onclick = function (e) { e.stopPropagation(); useItem(+b.getAttribute('data-use')); };
   });
-  Array.prototype.forEach.call(document.querySelectorAll('[data-play]'), function (b) {
+  // Native <audio controls> already gives play/pause + a seek bar + duration;
+  // just stop clicks on it from bubbling up to the row's "Use" handler, and
+  // pause any other preview when a new one starts.
+  var players = document.querySelectorAll('.k-audio-player');
+  Array.prototype.forEach.call(players, function (player) {
+    player.onclick = function (e) { e.stopPropagation(); };
+    player.addEventListener('play', function () {
+      Array.prototype.forEach.call(players, function (other) { if (other !== player) other.pause(); });
+    });
+  });
+  // Video cells stay a static thumbnail until the play overlay is clicked,
+  // then swap in a native <video controls> for an in-place scrubber.
+  Array.prototype.forEach.call(document.querySelectorAll('[data-video-play]'), function (b) {
     b.onclick = function (e) {
       e.stopPropagation();
-      var url = b.getAttribute('data-play');
-      if (playing && playing.src === url && !playing.paused) { playing.pause(); b.innerHTML = ICONS.play; return; }
-      if (playing) playing.pause();
-      Array.prototype.forEach.call(document.querySelectorAll('[data-play]'), function (x) { x.innerHTML = ICONS.play; });
-      playing = new Audio(url);
-      playing.play();
-      b.innerHTML = ICONS.pause;
-      playing.onended = function () { b.innerHTML = ICONS.play; };
+      var url = b.getAttribute('data-video-play');
+      var holder = b.parentNode;
+      holder.innerHTML = '<video src="' + esc(url) + '" controls autoplay playsinline style="width:100%;height:100%;object-fit:cover"></video>';
+      holder.querySelector('video').onclick = function (ev) { ev.stopPropagation(); };
     };
   });
 }

package/src/tools/agents.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 registerAgentTools(server, client) {
+function registerAgentTools(server, client, options = {}) {
+  const ui = () => appsEnabled(server, options);
   // ─── list_agents ───────────────────────────────────────────
   server.tool(
     'list_agents',
@@ -14,10 +16,28 @@ function registerAgentTools(server, client) {
     async ({ search }) => {
       const qs = search ? `?search=${encodeURIComponent(search)}` : '';
       const result = await client.get(`/v1/agents${qs}`);
-      return { content: [{ type: 'text', text: JSON.stringify({
-        agents: result.agents || [],
-        count: result.count || (result.agents || []).length
-      }, null, 2) }] };
+      const agents = result.agents || [];
+      const text = JSON.stringify({
+        agents,
+        count: result.count || agents.length
+      }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: 'Your Agents',
+          items: agents.map(a => ({
+            id: a.id,
+            title: (a.emoji ? a.emoji + ' ' : '') + a.name,
+            subtitle: a.description,
+            badge: a.is_global ? 'preset' : null,
+            use_hint: 'Use my "{TITLE}" agent (agent_id: {ID}) for this conversation.'
+          })),
+          total: agents.length
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );
 

package/src/tools/docs.js

@@ -5,10 +5,12 @@
 
 const { z } = require('zod');
 const { projectIdField } = require('./_shared');
+const { UI, uiResult, appsEnabled } = require('../apps');
 
 const CONTENT_GUIDE = 'HTML body content. Use clean semantic HTML the in-app editor understands: <h1>-<h3>, <p>, <ul>/<ol>/<li>, <table>, <blockquote>, <strong>/<em>, <a>. No <script>/<style>/<iframe> (stripped server-side). Write the FULL document yourself — this is where you author the doc.';
 
-function registerDocTools(server, client) {
+function registerDocTools(server, client, options = {}) {
+  const ui = () => appsEnabled(server, options);
   // ─── create_doc ────────────────────────────────────────────
   server.tool(
     'create_doc',
@@ -50,7 +52,24 @@ function registerDocTools(server, client) {
       if (limit) params.set('limit', String(limit));
       const qs = params.toString();
       const result = await client.get(`/v1/docs${qs ? '?' + qs : ''}`);
-      return { content: [{ type: 'text', text: JSON.stringify({ docs: result.docs || [], pagination: result.pagination || null }, null, 2) }] };
+      const docs = result.docs || [];
+      const text = JSON.stringify({ docs, pagination: result.pagination || null }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: 'Your AI Docs',
+          items: docs.map(d => ({
+            id: d.id,
+            title: d.title,
+            subtitle: (d.updated_at ? String(d.updated_at).slice(0, 10) : '') + (d.is_shared ? ' · shared' : ''),
+            open_url: d.share_url || null
+          })),
+          total: docs.length
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );
 

package/src/tools/media.js

@@ -227,15 +227,25 @@ function registerMediaTools(server, client, options = {}) {
     {},
     async () => {
       const result = await client.get('/v1/media/folders');
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            folders: result.folders || [],
-            count: result.count || 0
-          }, null, 2)
-        }]
-      };
+      const folders = result.folders || [];
+      const text = JSON.stringify({ folders, count: result.count || 0 }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: 'Media Folders',
+          items: folders.map(f => ({
+            id: f.id,
+            title: f.name,
+            subtitle: f.description,
+            meta: (f.item_count || 0) + (f.item_count === 1 ? ' item' : ' items'),
+            use_hint: 'List media in my "{TITLE}" folder (folder_id: {ID}).'
+          })),
+          total: folders.length
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );
 

package/src/tools/projects.js

@@ -5,8 +5,10 @@
 
 const { z } = require('zod');
 const { buildProjectUrl } = require('./_shared');
+const { UI, uiResult, appsEnabled } = require('../apps');
 
-function registerProjectTools(server, client) {
+function registerProjectTools(server, client, options = {}) {
+  const ui = () => appsEnabled(server, options);
   // ─── list_projects ─────────────────────────────────────────
   server.tool(
     'list_projects',
@@ -21,16 +23,28 @@ function registerProjectTools(server, client) {
         is_default: !!p.is_default,
         open_url: buildProjectUrl(p.id, { is_default: !!p.is_default })
       }));
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            projects,
-            count: projects.length,
-            _hint: 'Pass the chosen `id` as `project_id` on any generate_* tool to drop the generation into that project. Omit project_id to use the project flagged is_default:true. `open_url` opens that project\'s media in the web app (share it with the user).'
-          }, null, 2)
-        }]
-      };
+      const text = JSON.stringify({
+        projects,
+        count: projects.length,
+        _hint: 'Pass the chosen `id` as `project_id` on any generate_* tool to drop the generation into that project. Omit project_id to use the project flagged is_default:true. `open_url` opens that project\'s media in the web app (share it with the user).'
+      }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: 'Your Projects',
+          items: projects.map(p => ({
+            id: p.id,
+            title: p.name,
+            subtitle: p.role + (p.is_default ? ' · default' : ''),
+            open_url: p.open_url,
+            use_hint: 'Use my "{TITLE}" project (project_id: {ID}) for what I do next.'
+          })),
+          total: projects.length
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );
 
@@ -131,7 +145,23 @@ function registerProjectTools(server, client) {
       if (limit) params.set('limit', String(limit));
       const qs = params.toString();
       const result = await client.get(`/v1/sessions${qs ? '?' + qs : ''}`);
-      return { content: [{ type: 'text', text: JSON.stringify({ sessions: result.sessions || [], pagination: result.pagination || null }, null, 2) }] };
+      const sessions = result.sessions || [];
+      const text = JSON.stringify({ sessions, pagination: result.pagination || null }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: 'Sessions' + (type ? ' — ' + type : ''),
+          items: sessions.map(s => ({
+            id: s.session_id,
+            title: s.name || s.type,
+            subtitle: s.type + (s.updated_at ? ' · ' + String(s.updated_at).slice(0, 10) : '')
+          })),
+          total: sessions.length
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );
 
@@ -162,7 +192,24 @@ function registerProjectTools(server, client) {
     { project_id: z.string().describe('Project ObjectId.') },
     async ({ project_id }) => {
       const result = await client.get(`/v1/projects/${encodeURIComponent(project_id)}/context`);
-      return { content: [{ type: 'text', text: JSON.stringify({ sources: result.sources || [], count: result.count || 0 }, null, 2) }] };
+      const sources = result.sources || [];
+      const text = JSON.stringify({ sources, count: result.count || 0 }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: 'Project Knowledge Base',
+          items: sources.map(s => ({
+            id: s.file_key,
+            title: s.title || s.type,
+            subtitle: s.type + ' · ' + s.status,
+            open_url: s.url || null
+          })),
+          total: sources.length
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );
 

package/src/tools/visual_dna.js

@@ -210,7 +210,24 @@ function registerVisualDnaTools(server, client, options = {}) {
     {},
     async () => {
       const result = await client.get('/v1/visual-dna/folders');
-      return { content: [{ type: 'text', text: JSON.stringify({ folders: result.folders || [], count: result.count || 0 }, null, 2) }] };
+      const folders = result.folders || [];
+      const text = JSON.stringify({ folders, count: result.count || 0 }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: 'Visual DNA Folders',
+          items: folders.map(f => ({
+            id: f.id,
+            title: f.name,
+            meta: f.item_count != null ? (f.item_count + (f.item_count === 1 ? ' DNA' : ' DNAs')) : null,
+            use_hint: 'List Visual DNAs in my "{TITLE}" folder (folder_id: {ID}).'
+          })),
+          total: folders.length
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
     }
   );