@ssemble/mcp-server 1.1.3 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssemble/mcp-server",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "mcpName": "com.ssemble/mcp-server",
   "description": "MCP server for Ssemble AI Clipping — create viral short-form videos from any AI assistant. Webhook callbacks for n8n, Zapier, and Make automation.",
   "type": "module",

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.ssemble/mcp-server",
   "title": "Ssemble AI Clipping",
   "description": "Create AI-powered short-form video clips from YouTube videos. Supports webhook callbacks.",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "websiteUrl": "https://www.ssemble.com/mcp",
   "repository": {
     "url": "https://github.com/ssembleinc/ssemble-mcp-server",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@ssemble/mcp-server",
-      "version": "1.1.3",
+      "version": "1.1.5",
       "transport": {
         "type": "stdio"
       },

package/src/api/client.js

@@ -3,7 +3,36 @@
  * Wraps all 9 Ssemble AI Clipping API endpoints with native fetch.
  */
 
+import { createRequire } from 'module';
+
 const DEFAULT_BASE_URL = 'https://aiclipping.ssemble.com/api/v1';
+const PKG_VERSION = createRequire(import.meta.url)('../../package.json').version;
+
+// Per-attempt timeout. Backend create/validate calls can take a while (YouTube
+// metadata lookup), so give them more headroom than plain reads.
+const DEFAULT_TIMEOUT_MS = 30_000;
+const CREATE_TIMEOUT_MS = 90_000;
+const MAX_RETRIES = 2;
+
+// Only statuses where the request provably did NOT run application logic are
+// retried for POST (429 = rejected by limiter, 502/503 = never reached the app).
+// A 504 or a dropped socket may have already created a request and charged a
+// credit, so POST is never retried on those. GET/DELETE are idempotent.
+const RETRY_STATUSES_ANY = new Set([429, 502, 503]);
+const RETRY_STATUSES_IDEMPOTENT = new Set([429, 500, 502, 503, 504]);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function retryDelayMs(response, attempt) {
+  const ra = response?.headers?.get('retry-after');
+  if (ra) {
+    const secs = Number(ra);
+    if (Number.isFinite(secs)) return Math.min(secs, 30) * 1000;
+    const at = Date.parse(ra);
+    if (!Number.isNaN(at)) return Math.max(0, Math.min(at - Date.now(), 30_000));
+  }
+  return 1000 * 2 ** attempt; // 1s, 2s
+}
 
 export class SsembleApiError extends Error {
   constructor(status, error, rateLimits) {
@@ -60,7 +89,7 @@ export class SsembleClient {
     const headers = {
       'X-API-Key': this.apiKey,
       'Content-Type': 'application/json',
-      'User-Agent': 'ssemble-mcp-server/1.0.5',
+      'User-Agent': `ssemble-mcp-server/${PKG_VERSION}`,
     };
 
     const options = { method, headers };
@@ -68,7 +97,36 @@ export class SsembleClient {
       options.body = JSON.stringify(body);
     }
 
-    const response = await fetch(url, options);
+    const idempotent = method === 'GET' || method === 'DELETE';
+    const retryStatuses = idempotent ? RETRY_STATUSES_IDEMPOTENT : RETRY_STATUSES_ANY;
+    const timeoutMs = path === '/shorts/create' ? CREATE_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
+
+    let response;
+    for (let attempt = 0; ; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        response = await fetch(url, { ...options, signal: controller.signal });
+      } catch (err) {
+        clearTimeout(timer);
+        const timedOut = err?.name === 'AbortError';
+        // Network failures / timeouts: safe to retry only when nothing could
+        // have been created server-side (idempotent calls).
+        if (idempotent && attempt < MAX_RETRIES) { await sleep(retryDelayMs(null, attempt)); continue; }
+        throw new SsembleApiError(timedOut ? 504 : 503, {
+          code: timedOut ? 'timeout' : 'network_error',
+          message: timedOut
+            ? `Ssemble API did not respond within ${timeoutMs / 1000}s (${method} ${path}). ${idempotent ? 'Please retry.' : 'If this was create_short, check list_requests before retrying so you are not charged twice.'}`
+            : `Could not reach the Ssemble API (${err?.message || 'network error'}).`,
+        });
+      }
+      clearTimeout(timer);
+      if (retryStatuses.has(response.status) && attempt < MAX_RETRIES) {
+        await sleep(retryDelayMs(response, attempt));
+        continue;
+      }
+      break;
+    }
 
     const rateLimits = {
       hourlyLimit: response.headers.get('x-ratelimit-limit-hour'),
@@ -82,7 +140,18 @@ export class SsembleClient {
       return { data: { message: 'Request successfully deleted' }, rateLimits };
     }
 
-    const data = await response.json();
+    // Gateways (Cloudflare / the load balancer) answer 5xx with HTML, not JSON.
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new SsembleApiError(response.status, {
+        code: response.ok ? 'invalid_response' : 'upstream_error',
+        message: response.ok
+          ? 'Ssemble API returned a non-JSON response'
+          : `Ssemble API is temporarily unavailable (HTTP ${response.status}). Please retry in a moment.`,
+      }, rateLimits);
+    }
 
     if (!response.ok) {
       throw new SsembleApiError(response.status, data.error, rateLimits);

package/src/resources/static-data.js

@@ -7,6 +7,13 @@ const SUPPORTED_LANGUAGES = {
   pt: 'Portuguese', ru: 'Russian', ja: 'Japanese', ko: 'Korean', zh: 'Chinese',
   ar: 'Arabic', hi: 'Hindi', tr: 'Turkish', pl: 'Polish', nl: 'Dutch',
   sv: 'Swedish', no: 'Norwegian', da: 'Danish', fi: 'Finnish', cs: 'Czech',
+  vi: 'Vietnamese', id: 'Indonesian', fa: 'Persian (Farsi)', uk: 'Ukrainian',
+  af: 'Afrikaans', ca: 'Catalan', et: 'Estonian', fo: 'Faroese', gl: 'Galician',
+  is: 'Icelandic', ms: 'Malay', sq: 'Albanian', sw: 'Swahili', tl: 'Filipino (Tagalog)',
+  ro: 'Romanian', sk: 'Slovak', hr: 'Croatian', sl: 'Slovenian', hu: 'Hungarian',
+  lv: 'Latvian', lt: 'Lithuanian', bs: 'Bosnian', az: 'Azerbaijani',
+  bg: 'Bulgarian', mk: 'Macedonian', sr: 'Serbian', mt: 'Maltese', el: 'Greek',
+  ne: 'Nepali', mr: 'Marathi', ka: 'Georgian', hy: 'Armenian', ur: 'Urdu', he: 'Hebrew',
 };
 
 const PREFERRED_LENGTHS = {
@@ -21,7 +28,7 @@ const PREFERRED_LENGTHS = {
 const LAYOUTS = {
   auto: 'Automatic — AI detects best framing based on speaker position',
   fill: 'Fill — crop to fill 9:16 vertical frame',
-  fit: 'Fit — fit entire frame with bars if needed',
+  fit: 'Fit — fit entire frame; the area around the video is a blurred copy of the video (default) or the template color when blurBackground=false',
   square: 'Square — 1:1 aspect ratio',
 };
 
@@ -52,6 +59,7 @@ export function registerResources(server) {
         text += `| \`${value}\` | ${desc} |\n`;
       }
       text += '\nDefault: `under60sec`';
+      text += '\n\nTo limit how many shorts a request creates, pass `maxShorts` (1-12) to `create_short`. Omit it to get up to 12.';
       return { contents: [{ uri: 'ssemble://preferred-lengths', mimeType: 'text/markdown', text }] };
     }
   );

package/src/tools/create-short.js

@@ -2,9 +2,15 @@ import { z } from 'zod';
 import { formatCreateShortResponse, formatError } from '../utils/format.js';
 import { saveRequest } from '../utils/session-store.js';
 
+// Mirrors the backend list (plugin-shortsmaker-node-backend/constants/apiConstants.js
+// SUPPORTED_LANGUAGES) and the ssemble://supported-languages resource. Keep all three in sync.
 const SUPPORTED_LANGUAGES = [
   'en', 'es', 'fr', 'de', 'it', 'pt', 'ru', 'ja', 'ko', 'zh',
   'ar', 'hi', 'tr', 'pl', 'nl', 'sv', 'no', 'da', 'fi', 'cs',
+  'vi', 'id', 'fa', 'uk',
+  'af', 'ca', 'et', 'fo', 'gl', 'is', 'ms', 'sq', 'sw', 'tl',
+  'ro', 'sk', 'hr', 'sl', 'hu', 'lv', 'lt', 'bs', 'az',
+  'bg', 'mk', 'sr', 'mt', 'el', 'ne', 'mr', 'ka', 'hy', 'ur', 'he',
 ];
 
 const schema = {
@@ -14,6 +20,8 @@ const schema = {
   end: z.number().min(1).describe('End time in seconds (> start, max 1200s window)'),
   preferredLength: z.enum(['under30sec', 'under60sec', 'under90sec', 'under3min', 'under5min', 'under10min'])
     .default('under60sec').describe('Target clip duration').optional(),
+  maxShorts: z.number().int().min(1).max(12)
+    .describe('Maximum number of shorts to create (1-12). Keeps the highest-scoring clips and never pads, so short videos may return fewer. Omit to get up to 12.').optional(),
   language: z.enum(SUPPORTED_LANGUAGES).default('en').describe('Spoken language (ISO 639-1)').optional(),
   captionLanguage: z.enum(SUPPORTED_LANGUAGES).describe('Caption language if different from spoken').optional(),
   templateId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('Caption template ID from list_templates (24-char hex)').optional(),
@@ -29,6 +37,14 @@ 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(),
+  captionsEnabled: z.boolean().default(true).describe('Burn captions into the clips (default true). Set false for sources that already have captions.').optional(),
+  outroEnabled: z.boolean().default(false).describe('Append an end-screen outro card (bell animation + "Please subscribe" text) after each clip. Default false.').optional(),
+  outroText: z.string().max(80).describe('Custom outro text (max 80 chars). Omit for the localized default ("Please subscribe"). Requires outroEnabled=true.').optional(),
+  outroImageUrl: z.string().url().describe('Public image URL for a custom outro card instead of the stock bell card. Requires outroEnabled=true.').optional(),
+  outroSeconds: z.number().int().min(1).max(3).default(2).describe('Outro duration in seconds (1-3, default 2). Requires outroEnabled=true.').optional(),
+  outroSting: z.boolean().default(true).describe('Play the short bell sound on the outro (default true). Requires outroEnabled=true.').optional(),
+  outroHandle: z.string().max(40).describe('Channel handle shown on the outro card, e.g. "@mychannel" (max 40 chars). Requires outroEnabled=true.').optional(),
+  blurBackground: z.boolean().describe('Background behind the clip when the source does not fill the 9:16 canvas (mainly layout=fit): true = blurred copy of the video, false = solid template color. Omit to use the account\'s saved editor preference (default: blurred).').optional(),
   webhookUrl: z.string().url().describe('Optional webhook URL for completion/failure notifications. Receives a POST with results when processing finishes.').optional(),
 };
 
@@ -53,6 +69,10 @@ export function registerCreateShort(server, client) {
       if (params.ctaEnabled && !params.ctaText) {
         return { content: [{ type: 'text', text: formatError({ message: 'ctaText is required when ctaEnabled is true', code: 'invalid_request' }) }], isError: true };
       }
+      const outroExtras = ['outroText', 'outroImageUrl', 'outroHandle'].filter((k) => params[k] !== undefined && params[k] !== '');
+      if (outroExtras.length && params.outroEnabled !== true) {
+        return { content: [{ type: 'text', text: formatError({ message: `${outroExtras.join(', ')} require outroEnabled: true`, code: 'invalid_request' }) }], isError: true };
+      }
 
       try {
         const result = await client.createShort(params);