@ssemble/mcp-server 1.0.5 → 1.1.0

package/src/apps/templates-app.html

@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Ssemble Templates</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif);
+      background: var(--color-background-primary, #1a1a2e);
+      color: var(--color-text-primary, #e0e0e0);
+      padding: 16px;
+    }
+    h2 { font-size: 18px; margin-bottom: 16px; color: var(--color-text-primary, #fff); }
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+      gap: 12px;
+    }
+    .card {
+      background: var(--color-background-secondary, #16213e);
+      border-radius: var(--border-radius-md, 8px);
+      overflow: hidden;
+      cursor: pointer;
+      border: 2px solid transparent;
+      transition: border-color 0.2s, transform 0.15s;
+    }
+    .card:hover { border-color: var(--color-border-primary, #4a6cf7); transform: translateY(-2px); }
+    .card.selected { border-color: var(--color-border-primary, #4a6cf7); box-shadow: 0 0 12px rgba(74,108,247,0.3); }
+    .card.default { border-color: #f7c94a; }
+    .card img {
+      width: 100%;
+      aspect-ratio: 9/16;
+      object-fit: cover;
+      display: block;
+      background: var(--color-background-tertiary, #0f3460);
+    }
+    .card .placeholder {
+      width: 100%;
+      aspect-ratio: 9/16;
+      background: var(--color-background-tertiary, #0f3460);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: var(--color-text-secondary, #555);
+      font-size: 12px;
+    }
+    .card-label {
+      padding: 8px;
+      font-size: 13px;
+      text-align: center;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    .badge {
+      display: inline-block;
+      font-size: 10px;
+      background: #f7c94a;
+      color: #1a1a2e;
+      padding: 2px 6px;
+      border-radius: 4px;
+      margin-left: 4px;
+      font-weight: 600;
+    }
+    .loading { text-align: center; padding: 40px; color: var(--color-text-secondary, #888); }
+    .selected-info {
+      margin-top: 16px;
+      padding: 12px;
+      background: var(--color-background-secondary, #16213e);
+      border-radius: var(--border-radius-md, 8px);
+      font-size: 13px;
+    }
+    .selected-info code {
+      background: var(--color-background-tertiary, #0f3460);
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-family: var(--font-mono, monospace);
+    }
+  </style>
+</head>
+<body>
+  <div id="app"><div class="loading">Loading templates...</div></div>
+  <script type="module" src="./templates-app.js"></script>
+</body>
+</html>

package/src/apps/templates-app.js

@@ -0,0 +1,74 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+
+const appEl = document.getElementById('app');
+const app = new App({ name: 'Ssemble Templates', version: '1.0.0' });
+
+let selectedTemplateId = null;
+let cachedData = null;
+
+function render(data) {
+  if (!data || !data.templates) {
+    appEl.innerHTML = '<div class="loading">No template data received.</div>';
+    return;
+  }
+
+  cachedData = data;
+  const { templates, defaultTemplateId } = data;
+
+  let html = `<h2>Caption Templates (${templates.length})</h2>`;
+  html += '<div class="grid">';
+
+  templates.forEach((t) => {
+    const isDefault = t.templateId === defaultTemplateId;
+    const isSelected = t.templateId === selectedTemplateId;
+    const classes = ['card'];
+    if (isDefault && !isSelected) classes.push('default');
+    if (isSelected) classes.push('selected');
+
+    const imgSrc = t.preview || t.gif || '';
+    const imgTag = imgSrc
+      ? `<img src="${imgSrc}" alt="${t.displayName}" loading="lazy" />`
+      : `<div class="placeholder">No preview</div>`;
+
+    html += `<div class="${classes.join(' ')}" data-id="${t.templateId}" data-name="${t.name}">
+      ${imgTag}
+      <div class="card-label">
+        ${t.displayName}${isDefault ? '<span class="badge">default</span>' : ''}
+      </div>
+    </div>`;
+  });
+
+  html += '</div>';
+
+  if (selectedTemplateId) {
+    const sel = templates.find((t) => t.templateId === selectedTemplateId);
+    if (sel) {
+      html += `<div class="selected-info">
+        Selected: <strong>${sel.displayName}</strong> — templateId: <code>${sel.templateId}</code>
+      </div>`;
+    }
+  }
+
+  appEl.innerHTML = html;
+
+  appEl.querySelectorAll('.card').forEach((card) => {
+    card.addEventListener('click', () => {
+      selectedTemplateId = card.dataset.id;
+      render(cachedData);
+      app.updateModelContext({
+        text: `User selected template: ${card.dataset.name} (templateId: ${card.dataset.id}). Use this templateId when creating shorts.`,
+      });
+    });
+  });
+}
+
+app.ontoolresult = (result) => {
+  const data = result.structuredContent || null;
+  if (data) {
+    render(data);
+  } else {
+    appEl.innerHTML = '<div class="loading">No structured data available.</div>';
+  }
+};
+
+app.connect();

package/src/index.js

@@ -19,6 +19,7 @@ import { registerListMemeHooks } from './tools/list-meme-hooks.js';
 
 // Resources & Prompts
 import { registerResources } from './resources/static-data.js';
+import { registerAppResources } from './resources/app-resources.js';
 import { registerPrompts } from './prompts/workflows.js';
 
 export function createSsembleMcpServer(apiKey, baseUrl) {
@@ -44,6 +45,7 @@ export function createSsembleMcpServer(apiKey, baseUrl) {
 
   // Register resources
   registerResources(server);
+  registerAppResources(server);
 
   // Register prompts
   registerPrompts(server);

package/src/resources/app-resources.js

@@ -0,0 +1,149 @@
+/**
+ * Registers MCP App UI resources for interactive HTML views.
+ */
+
+import { registerAppResource } from '@modelcontextprotocol/ext-apps/server';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DIST_DIR = join(__dirname, '..', 'apps', 'dist');
+
+function loadHtml(filename) {
+  return readFileSync(join(DIST_DIR, filename), 'utf-8');
+}
+
+const CDN_DOMAINS = ['https://cf.ssemble.com', 'https://*.ssemble.com'];
+
+export function registerAppResources(server) {
+  registerAppResource(
+    server,
+    'Templates Browser',
+    'ui://ssemble/templates-app.html',
+    {
+      description: 'Interactive grid of caption style templates with GIF previews',
+      _meta: {
+        ui: {
+          csp: {
+            resourceDomains: CDN_DOMAINS,
+            connectDomains: CDN_DOMAINS,
+          },
+        },
+      },
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'ui://ssemble/templates-app.html',
+          mimeType: 'text/html;profile=mcp-app',
+          text: loadHtml('templates-app.html'),
+        },
+      ],
+    })
+  );
+
+  registerAppResource(
+    server,
+    'Music Player',
+    'ui://ssemble/music-app.html',
+    {
+      description: 'Interactive music player with audio preview and track selection',
+      _meta: {
+        ui: {
+          csp: {
+            resourceDomains: CDN_DOMAINS,
+            connectDomains: CDN_DOMAINS,
+          },
+        },
+      },
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'ui://ssemble/music-app.html',
+          mimeType: 'text/html;profile=mcp-app',
+          text: loadHtml('music-app.html'),
+        },
+      ],
+    })
+  );
+
+  registerAppResource(
+    server,
+    'Game Videos Gallery',
+    'ui://ssemble/game-videos-app.html',
+    {
+      description: 'Interactive gallery of gameplay overlay videos with preview images',
+      _meta: {
+        ui: {
+          csp: {
+            resourceDomains: CDN_DOMAINS,
+            connectDomains: CDN_DOMAINS,
+          },
+        },
+      },
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'ui://ssemble/game-videos-app.html',
+          mimeType: 'text/html;profile=mcp-app',
+          text: loadHtml('game-videos-app.html'),
+        },
+      ],
+    })
+  );
+
+  registerAppResource(
+    server,
+    'Meme Hooks Gallery',
+    'ui://ssemble/meme-hooks-app.html',
+    {
+      description: 'Interactive gallery of meme hook clips with preview images',
+      _meta: {
+        ui: {
+          csp: {
+            resourceDomains: CDN_DOMAINS,
+            connectDomains: CDN_DOMAINS,
+          },
+        },
+      },
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'ui://ssemble/meme-hooks-app.html',
+          mimeType: 'text/html;profile=mcp-app',
+          text: loadHtml('meme-hooks-app.html'),
+        },
+      ],
+    })
+  );
+
+  registerAppResource(
+    server,
+    'Shorts Viewer',
+    'ui://ssemble/shorts-app.html',
+    {
+      description: 'Interactive viewer for generated short clips with video player and viral scores',
+      _meta: {
+        ui: {
+          csp: {
+            resourceDomains: CDN_DOMAINS,
+            connectDomains: CDN_DOMAINS,
+          },
+        },
+      },
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'ui://ssemble/shorts-app.html',
+          mimeType: 'text/html;profile=mcp-app',
+          text: loadHtml('shorts-app.html'),
+        },
+      ],
+    })
+  );
+}

package/src/tools/create-short.js

@@ -28,6 +28,7 @@ const schema = {
   musicName: z.string().describe('Exact track name from list_music (case-sensitive)').optional(),
   musicVolume: z.number().min(0).max(100).default(10).describe('Music volume 0-100').optional(),
   layout: z.enum(['auto', 'fill', 'fit', 'square']).default('auto').describe('Video framing layout').optional(),
+  webhookUrl: z.string().url().describe('Optional webhook URL for completion/failure notifications. Receives a POST with results when processing finishes.').optional(),
 };
 
 export function registerCreateShort(server, client) {

package/src/tools/get-shorts.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
 import { formatShortsResponse, formatError } from '../utils/format.js';
 
 const schema = {
@@ -6,14 +7,45 @@ const schema = {
 };
 
 export function registerGetShorts(server, client) {
-  server.tool(
+  registerAppTool(
+    server,
     'get_shorts',
-    'Retrieve all generated short clips for a completed request. Returns video URLs, AI-generated titles, descriptions, viral scores, and durations sorted by viral score.',
-    schema,
+    {
+      title: 'Get Shorts',
+      description:
+        'Retrieve all generated short clips for a completed request. Returns video URLs, AI-generated titles, descriptions, viral scores, and durations sorted by viral score.',
+      inputSchema: schema,
+      _meta: {
+        ui: { resourceUri: 'ui://ssemble/shorts-app.html' },
+      },
+    },
     async ({ requestId }) => {
       try {
         const result = await client.getShorts(requestId);
-        return { content: [{ type: 'text', text: formatShortsResponse(result) }] };
+        const textFallback = formatShortsResponse(result);
+        const d = result.data;
+
+        const structuredContent = {
+          title: d.title || '',
+          url: d.url || '',
+          start: d.start,
+          end: d.end,
+          language: d.language || '',
+          template: d.template || '',
+          shorts: (d.shorts || []).map((s) => ({
+            title: s.title || '',
+            description: s.description || '',
+            duration: s.duration || 0,
+            viral_score: s.viral_score != null ? s.viral_score : 0,
+            video_url: s.video_url || '',
+            error: !!s.error,
+          })),
+        };
+
+        return {
+          content: [{ type: 'text', text: textFallback }],
+          structuredContent,
+        };
       } catch (error) {
         return { content: [{ type: 'text', text: formatError(error) }], isError: true };
       }

package/src/tools/list-game-videos.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
 import { formatPaginatedAssets, formatError } from '../utils/format.js';
 
 const schema = {
@@ -7,14 +8,43 @@ const schema = {
 };
 
 export function registerListGameVideos(server, client) {
-  server.tool(
+  registerAppTool(
+    server,
     'list_game_videos',
-    'List available gameplay videos for split-screen overlays (content top, game bottom). Use the exact gameVideoName when creating shorts.',
-    schema,
+    {
+      title: 'List Game Videos',
+      description:
+        'List available gameplay videos for split-screen overlays (content top, game bottom). Use the exact gameVideoName when creating shorts.',
+      inputSchema: schema,
+      _meta: {
+        ui: { resourceUri: 'ui://ssemble/game-videos-app.html' },
+      },
+    },
     async (params) => {
       try {
         const result = await client.listGameVideos(params);
-        return { content: [{ type: 'text', text: formatPaginatedAssets(result, 'gameVideos', 'Gameplay Overlays') }] };
+        const textFallback = formatPaginatedAssets(result, 'gameVideos', 'Gameplay Overlays');
+
+        const items = result.data?.gameVideos || [];
+        const pagination = result.data?.pagination || {};
+        const structuredContent = {
+          gameVideos: items.map((g) => ({
+            name: g.name,
+            preview: g.preview || '',
+            video: g.video || '',
+            video_duration: g.video_duration || 0,
+          })),
+          pagination: {
+            page: pagination.page || 1,
+            totalPages: pagination.totalPages || 1,
+            totalCount: pagination.totalCount || items.length,
+          },
+        };
+
+        return {
+          content: [{ type: 'text', text: textFallback }],
+          structuredContent,
+        };
       } catch (error) {
         return { content: [{ type: 'text', text: formatError(error) }], isError: true };
       }

package/src/tools/list-meme-hooks.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
 import { formatPaginatedAssets, formatError } from '../utils/format.js';
 
 const schema = {
@@ -7,14 +8,43 @@ const schema = {
 };
 
 export function registerListMemeHooks(server, client) {
-  server.tool(
+  registerAppTool(
+    server,
     'list_meme_hooks',
-    'List available meme hook clips (2-5 second attention grabbers prepended to shorts). Use the exact memeHookName when creating shorts.',
-    schema,
+    {
+      title: 'List Meme Hooks',
+      description:
+        'List available meme hook clips (2-5 second attention grabbers prepended to shorts). Use the exact memeHookName when creating shorts.',
+      inputSchema: schema,
+      _meta: {
+        ui: { resourceUri: 'ui://ssemble/meme-hooks-app.html' },
+      },
+    },
     async (params) => {
       try {
         const result = await client.listMemeHooks(params);
-        return { content: [{ type: 'text', text: formatPaginatedAssets(result, 'memeHooks', 'Meme Hooks') }] };
+        const textFallback = formatPaginatedAssets(result, 'memeHooks', 'Meme Hooks');
+
+        const items = result.data?.memeHooks || [];
+        const pagination = result.data?.pagination || {};
+        const structuredContent = {
+          memeHooks: items.map((h) => ({
+            name: h.name,
+            preview: h.preview || '',
+            video: h.video || '',
+            video_duration: h.video_duration || 0,
+          })),
+          pagination: {
+            page: pagination.page || 1,
+            totalPages: pagination.totalPages || 1,
+            totalCount: pagination.totalCount || items.length,
+          },
+        };
+
+        return {
+          content: [{ type: 'text', text: textFallback }],
+          structuredContent,
+        };
       } catch (error) {
         return { content: [{ type: 'text', text: formatError(error) }], isError: true };
       }

package/src/tools/list-music.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
 import { formatPaginatedAssets, formatError } from '../utils/format.js';
 
 const schema = {
@@ -7,14 +8,43 @@ const schema = {
 };
 
 export function registerListMusic(server, client) {
-  server.tool(
+  registerAppTool(
+    server,
     'list_music',
-    'List available background music tracks with names and durations. Use the exact musicName when creating shorts.',
-    schema,
+    {
+      title: 'List Music',
+      description:
+        'List available background music tracks with names and durations. Use the exact musicName when creating shorts.',
+      inputSchema: schema,
+      _meta: {
+        ui: { resourceUri: 'ui://ssemble/music-app.html' },
+      },
+    },
     async (params) => {
       try {
         const result = await client.listMusic(params);
-        return { content: [{ type: 'text', text: formatPaginatedAssets(result, 'music', 'Background Music') }] };
+        const textFallback = formatPaginatedAssets(result, 'music', 'Background Music');
+
+        // Structured content for the MCP App
+        const items = result.data?.music || [];
+        const pagination = result.data?.pagination || {};
+        const structuredContent = {
+          music: items.map((t) => ({
+            name: t.name,
+            duration: t.duration,
+            url: t.url || '',
+          })),
+          pagination: {
+            page: pagination.page || 1,
+            totalPages: pagination.totalPages || 1,
+            totalCount: pagination.totalCount || items.length,
+          },
+        };
+
+        return {
+          content: [{ type: 'text', text: textFallback }],
+          structuredContent,
+        };
       } catch (error) {
         return { content: [{ type: 'text', text: formatError(error) }], isError: true };
       }

package/src/tools/list-templates.js

@@ -1,14 +1,73 @@
-import { formatTemplatesResponse, formatError } from '../utils/format.js';
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { formatError, formatRateLimits } from '../utils/format.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const THUMB_DIR = join(__dirname, '..', 'assets', 'thumbnails');
+
+function loadThumbnail(templateName) {
+  try {
+    const data = readFileSync(join(THUMB_DIR, `${templateName}.jpg`));
+    return { data: data.toString('base64'), mimeType: 'image/jpeg' };
+  } catch {
+    return null;
+  }
+}
 
 export function registerListTemplates(server, client) {
-  server.tool(
+  registerAppTool(
+    server,
     'list_templates',
-    'List all available caption style templates with IDs and names. Use the templateId when creating shorts.',
-    {},
+    {
+      title: 'List Templates',
+      description:
+        'List all available caption style templates with preview thumbnails, names, and IDs. Use the templateId when creating shorts.',
+      _meta: {
+        ui: { resourceUri: 'ui://ssemble/templates-app.html' },
+      },
+    },
     async () => {
       try {
         const result = await client.listTemplates();
-        return { content: [{ type: 'text', text: formatTemplatesResponse(result) }] };
+        const d = result.data;
+        const templates = d.templates || [];
+
+        // Text + image content for non-app clients (Claude Code, Cursor, etc.)
+        const content = [];
+        content.push({
+          type: 'text',
+          text: `## Caption Templates (${templates.length} available)\n`,
+        });
+
+        templates.forEach((t) => {
+          const isDefault = t.templateId === d.defaultTemplateId;
+          const thumb = loadThumbnail(t.name);
+          if (thumb) {
+            content.push({ type: 'image', data: thumb.data, mimeType: thumb.mimeType });
+          }
+          const label = `**${t.displayName || t.name}**${isDefault ? ' _(default)_' : ''}`;
+          content.push({ type: 'text', text: label });
+        });
+
+        let footer = `\nUse the \`templateId\` field when calling \`create_short\` to pick a style.`;
+        footer += formatRateLimits(result.rateLimits);
+        content.push({ type: 'text', text: footer });
+
+        // Structured content for the MCP App
+        const structuredContent = {
+          templates: templates.map((t) => ({
+            templateId: t.templateId,
+            name: t.name,
+            displayName: t.displayName || t.name,
+            gif: t.gif || '',
+            preview: t.preview || '',
+          })),
+          defaultTemplateId: d.defaultTemplateId,
+        };
+
+        return { content, structuredContent };
       } catch (error) {
         return { content: [{ type: 'text', text: formatError(error) }], isError: true };
       }

package/src/utils/format.js

@@ -144,14 +144,18 @@ export function formatPaginatedAssets(result, assetKey, assetLabel) {
     return `No ${assetLabel} found.${formatRateLimits(result.rateLimits)}`;
   }
 
+  const hasUrl = items.some((item) => item.url);
+  const hasDuration = items[0]?.duration != null;
+
   let text = `## ${assetLabel} (Page ${p.page}/${p.totalPages}, ${p.totalCount} total)\n\n`;
-  text += `| # | Name |${items[0]?.duration != null ? ' Duration |' : ''}\n`;
-  text += `|---|------|${items[0]?.duration != null ? '----------|' : ''}\n`;
+  text += `| # | Name |${hasDuration ? ' Duration |' : ''}${hasUrl ? ' Listen |' : ''}\n`;
+  text += `|---|------|${hasDuration ? '----------|' : ''}${hasUrl ? '--------|' : ''}\n`;
 
   items.forEach((item, i) => {
     const num = (p.page - 1) * p.limit + i + 1;
-    const durationCol = item.duration != null ? ` ${item.duration}s |` : '';
-    text += `| ${num} | ${item.name} |${durationCol}\n`;
+    const durationCol = hasDuration ? ` ${Math.round(item.duration)}s |` : '';
+    const listenCol = hasUrl ? ` ${item.url ? `[▶ Play](${item.url})` : ''} |` : '';
+    text += `| ${num} | ${item.name} |${durationCol}${listenCol}\n`;
   });
 
   if (p.totalPages > 1) {