@ssemble/mcp-server 1.0.6 → 1.1.1

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { formatCreateShortResponse, formatError } from '../utils/format.js';
+import { saveRequest } from '../utils/session-store.js';
 
 const SUPPORTED_LANGUAGES = [
   'en', 'es', 'fr', 'de', 'it', 'pt', 'ru', 'ja', 'ko', 'zh',
@@ -55,6 +56,15 @@ export function registerCreateShort(server, client) {
 
       try {
         const result = await client.createShort(params);
+        const requestId = result.data?.requestId;
+        if (requestId) {
+          saveRequest(requestId, {
+            url: params.url || params.fileUrl || '',
+            title: null,
+            status: 'queued',
+            createdAt: new Date().toISOString(),
+          });
+        }
         return { content: [{ type: 'text', text: formatCreateShortResponse(result) }] };
       } catch (error) {
         return { content: [{ type: 'text', text: formatError(error) }], isError: true };

package/src/tools/get-shorts.js

@@ -1,19 +1,70 @@
 import { z } from 'zod';
-import { formatShortsResponse, formatError } from '../utils/format.js';
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
+import { formatShortsResponse, formatRecentRequests, formatError } from '../utils/format.js';
+import { getRecentRequests, hasRequests, updateRequest } from '../utils/session-store.js';
 
 const schema = {
-  requestId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('The request ID from create_short (24-char hex)'),
+  requestId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('The request ID from create_short (24-char hex). Omit to see your recent requests.').optional(),
 };
 
 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. Provide a request ID, or omit it to see your recent requests and pick one.',
+      inputSchema: schema,
+      _meta: {
+        ui: { resourceUri: 'ui://ssemble/shorts-app.html' },
+      },
+    },
     async ({ requestId }) => {
+      if (!requestId) {
+        // No ID given — show recent requests so user can pick
+        if (hasRequests()) {
+          const recent = getRecentRequests(5);
+          return { content: [{ type: 'text', text: formatRecentRequests(recent, 'get_shorts') }] };
+        }
+        try {
+          const result = await client.listRequests({ limit: 5, sortOrder: 'desc' });
+          return { content: [{ type: 'text', text: formatRecentRequests(result.data?.requests || [], 'get_shorts', true) }] };
+        } catch (error) {
+          return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+        }
+      }
+
       try {
         const result = await client.getShorts(requestId);
-        return { content: [{ type: 'text', text: formatShortsResponse(result) }] };
+        // Save the video title back to session store for future lookups
+        if (result.data?.title) {
+          updateRequest(requestId, { title: result.data.title, status: result.data.status });
+        }
+        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/get-status.js

@@ -1,18 +1,35 @@
 import { z } from 'zod';
-import { formatStatusResponse, formatError } from '../utils/format.js';
+import { formatStatusResponse, formatRecentRequests, formatError } from '../utils/format.js';
+import { getRecentRequests, hasRequests, updateRequest } from '../utils/session-store.js';
 
 const schema = {
-  requestId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('The request ID from create_short (24-char hex)'),
+  requestId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('The request ID from create_short (24-char hex). Omit to see your recent requests.').optional(),
 };
 
 export function registerGetStatus(server, client) {
   server.tool(
     'get_status',
-    'Check processing status and progress of a short creation request. Returns status (queued/processing/completed/failed), progress percentage, and current step.',
+    'Check processing status of a short creation request. Provide a request ID, or omit it to see your recent requests and pick one.',
     schema,
     async ({ requestId }) => {
+      if (!requestId) {
+        // No ID given — show recent requests so user can pick
+        if (hasRequests()) {
+          const recent = getRecentRequests(5);
+          return { content: [{ type: 'text', text: formatRecentRequests(recent, 'get_status') }] };
+        }
+        // Nothing in session — fall back to API list
+        try {
+          const result = await client.listRequests({ limit: 5, sortOrder: 'desc' });
+          return { content: [{ type: 'text', text: formatRecentRequests(result.data?.requests || [], 'get_status', true) }] };
+        } catch (error) {
+          return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+        }
+      }
+
       try {
         const result = await client.getStatus(requestId);
+        updateRequest(requestId, { status: result.data?.status });
         return { content: [{ type: 'text', text: formatStatusResponse(result) }] };
       } 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 };
       }