@ssemble/mcp-server 1.1.4 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssemble/mcp-server",
-  "version": "1.1.4",
+  "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.4",
+  "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.4",
+      "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/tools/create-short.js

@@ -37,6 +37,13 @@ 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(),
 };
@@ -62,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);