@ssemble/mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -9,6 +9,7 @@ Works with **Claude Desktop**, **Claude Code**, **Cursor**, **VS Code**, **Winds
 This MCP server lets AI assistants create short-form video clips from YouTube videos using Ssemble's AI clipping engine. The AI can:
 
 - **Create shorts** from YouTube URLs or uploaded files
+- **Webhook callbacks** — get notified when processing completes (works with n8n, Zapier, Make)
 - **Browse assets** — caption templates, background music, gameplay overlays, meme hooks
 - **Track processing** — check progress and retrieve completed clips
 - **Manage requests** — list history, get results, delete old requests
@@ -91,12 +92,39 @@ Add to your MCP settings:
 
 ## How Processing Works
 
-Video processing takes 5-30 minutes. The workflow is:
+Video processing takes 5-30 minutes. Two workflows available:
 
+### Option A: Polling (manual check)
 1. `create_short` — submits the job and returns instantly with a request ID
 2. `get_status` — check progress anytime (queued → processing → completed)
 3. `get_shorts` — retrieve the generated clips when done
 
+### Option B: Webhook (automated)
+1. `create_short` with `webhookUrl` — submits the job with a callback URL
+2. When processing completes or fails, the API sends an HTTP POST to your URL with the results
+3. No polling needed — ideal for n8n, Zapier, Make, and custom backend integrations
+
+Webhook payload example:
+```json
+{
+  "event": "shorts.completed",
+  "requestId": "507f1f77bcf86cd799439011",
+  "status": "completed",
+  "timestamp": "2026-03-30T12:00:00.000Z",
+  "data": {
+    "shorts": [
+      {
+        "id": "...",
+        "title": "AI-Generated Title",
+        "video_url": "https://...",
+        "duration": 45,
+        "viral_score": 8.5
+      }
+    ]
+  }
+}
+```
+
 ## Usage Examples
 
 **Create shorts from a YouTube video:**

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ssemble/mcp-server",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "mcpName": "com.ssemble/mcp-server",
-  "description": "MCP server for Ssemble AI Clipping — create viral short-form videos from any AI assistant",
+  "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",
   "bin": {
     "ssemble-mcp": "./src/transports/stdio.js"

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.ssemble/mcp-server",
   "title": "Ssemble AI Clipping",
-  "description": "Create AI-powered short-form video clips from YouTube videos using any AI assistant.",
-  "version": "1.0.4",
+  "description": "Create AI-powered short-form video clips from YouTube videos using any AI assistant. Webhook callbacks for n8n, Zapier, and Make automation.",
+  "version": "1.0.6",
   "websiteUrl": "https://www.ssemble.com",
   "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.0.4",
+      "version": "1.0.6",
       "transport": {
         "type": "stdio"
       },

package/src/api/client.js

@@ -34,13 +34,13 @@ export class SsembleClient {
     if (!this.apiKey) {
       throw new SsembleApiError(401, {
         code: 'missing_api_key',
-        message: 'Ssemble API key required. Pass via X-Ssemble-API-Key header when using the remote endpoint, or set SSEMBLE_API_KEY env var for local usage. Get your key at https://app.ssemble.com → Settings → API Keys.',
+        message: 'Ssemble API key required. Pass via X-Ssemble-API-Key header when using the remote endpoint, or set SSEMBLE_API_KEY env var for local usage. Get your key at https://app.ssemble.com/api-keys',
       });
     }
     if (!this.apiKey.startsWith('sk_ssemble_')) {
       throw new SsembleApiError(401, {
         code: 'invalid_api_key',
-        message: 'Invalid API key format. Must start with sk_ssemble_',
+        message: 'Invalid API key format. Must start with sk_ssemble_. Get your key at https://app.ssemble.com/api-keys',
       });
     }
 
@@ -60,7 +60,7 @@ export class SsembleClient {
     const headers = {
       'X-API-Key': this.apiKey,
       'Content-Type': 'application/json',
-      'User-Agent': 'ssemble-mcp-server/1.0.4',
+      'User-Agent': 'ssemble-mcp-server/1.0.5',
     };
 
     const options = { method, headers };

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/transports/stdio.js

@@ -11,7 +11,7 @@ import { createSsembleMcpServer } from '../index.js';
 const apiKey = process.env.SSEMBLE_API_KEY;
 if (!apiKey) {
   console.error('Error: SSEMBLE_API_KEY environment variable is required.');
-  console.error('Get your API key at https://app.ssemble.com → Settings → API Keys');
+  console.error('Get your API key at https://app.ssemble.com/api-keys');
   process.exit(1);
 }
 

package/src/utils/format.js

@@ -171,11 +171,24 @@ export function formatDeleteResponse(result) {
 
 export function formatError(error) {
   if (error instanceof Error && error.code) {
-    let text = `**Error**: ${error.message}`;
-    if (error.code) text += ` (${error.code})`;
+    let text = `**Error**: ${error.message} (${error.code})`;
     if (error.details) {
       text += `\n\n**Details**: ${JSON.stringify(error.details, null, 2)}`;
     }
+
+    // Add helpful guidance based on error code
+    const helpLinks = {
+      missing_api_key: '\n\n**Get your API key**: https://app.ssemble.com/api-keys\n**Setup guide**: https://www.npmjs.com/package/@ssemble/mcp-server',
+      invalid_api_key: '\n\n**Get a valid API key**: https://app.ssemble.com/api-keys\nAPI keys start with `sk_ssemble_` and are 43 characters long.',
+      subscription_required: '\n\n**Subscribe to a plan**: https://app.ssemble.com/pricing\nAn active subscription is required to use the API.',
+      insufficient_credits: '\n\n**Get credits**: https://app.ssemble.com/pricing\nEach short creation costs 1 credit.',
+      user_not_found: '\n\n**Create an account**: https://app.ssemble.com\nThen generate an API key at https://app.ssemble.com/api-keys',
+    };
+
+    if (helpLinks[error.code]) {
+      text += helpLinks[error.code];
+    }
+
     if (error.rateLimits?.hourlyRemaining) {
       text += formatRateLimits(error.rateLimits);
     }