@ssemble/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ssemble
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# Ssemble MCP Server
+
+MCP server for [Ssemble AI Clipping](https://aiclipping.ssemble.com) — create viral short-form videos from any AI assistant.
+
+Works with **Claude Desktop**, **Claude Code**, **Cursor**, **VS Code**, **Windsurf**, and any MCP-compatible client.
+
+## What it does
+
+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
+- **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
+
+## Prerequisites
+
+- [Ssemble account](https://app.ssemble.com) with an active subscription
+- API key (get it from Settings → API Keys in the Ssemble dashboard)
+- Node.js >= 18
+
+## Quick Start
+
+### Claude Desktop
+
+Edit your config file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ssemble": {
+      "command": "npx",
+      "args": ["@ssemble/mcp-server"],
+      "env": {
+        "SSEMBLE_API_KEY": "sk_ssemble_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### Claude Code
+
+```bash
+claude mcp add ssemble -- npx @ssemble/mcp-server
+```
+
+Then set the environment variable:
+
+```bash
+export SSEMBLE_API_KEY="sk_ssemble_your_key_here"
+```
+
+### Cursor / VS Code / Windsurf
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "ssemble": {
+      "command": "npx",
+      "args": ["@ssemble/mcp-server"],
+      "env": {
+        "SSEMBLE_API_KEY": "sk_ssemble_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_short` | Create AI-generated short clips from a video. Returns request ID instantly. |
+| `get_status` | Check processing progress (0-100%) and current step |
+| `get_shorts` | Retrieve completed clips with video URLs, titles, viral scores |
+| `list_requests` | List all your requests with pagination and status filtering |
+| `delete_request` | Permanently delete a request and its videos |
+| `list_templates` | Browse caption style templates |
+| `list_music` | Browse background music tracks |
+| `list_game_videos` | Browse gameplay overlay videos |
+| `list_meme_hooks` | Browse meme hook attention-grabber clips |
+
+## How Processing Works
+
+Video processing takes 5-30 minutes. The workflow is:
+
+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
+
+## Usage Examples
+
+**Create shorts from a YouTube video:**
+> "Create shorts from https://youtube.com/watch?v=abc123, use the first 10 minutes with chill background music"
+
+**Browse available assets:**
+> "Show me all caption templates" / "What background music is available?"
+
+**Check progress:**
+> "What's the status of my video request?"
+
+**Get results:**
+> "Show me the clips for request 507f1f77bcf86cd799439011, sorted by viral score"
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SSEMBLE_API_KEY` | Yes | Your Ssemble API key (starts with `sk_ssemble_`) |
+| `SSEMBLE_API_BASE_URL` | No | Override API base URL (default: `https://aiclipping.ssemble.com/api/v1`) |
+
+## Development
+
+```bash
+git clone https://gitlab.com/vlogr/ssemble-mcp-server.git
+cd ssemble-mcp-server
+npm install
+SSEMBLE_API_KEY=sk_ssemble_your_key npm start
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ssemble/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Ssemble AI Clipping — create viral short-form videos from any AI assistant",
+  "type": "module",
+  "bin": {
+    "ssemble-mcp": "./src/transports/stdio.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "src/",
+    "server.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/transports/stdio.js",
+    "start:http": "node src/transports/http.js",
+    "test": "node --test tests/**/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ssemble",
+    "ai-clipping",
+    "video",
+    "shorts",
+    "youtube",
+    "tiktok",
+    "instagram-reels"
+  ],
+  "author": "Ssemble <support@ssemble.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/vlogr/ssemble-mcp-server.git"
+  },
+  "homepage": "https://aiclipping.ssemble.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "express": "^4.21.0",
+    "zod": "^3.23.0"
+  }
+}

package/server.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.gitlab.vlogr/ssemble-mcp-server",
+  "title": "Ssemble AI Clipping",
+  "description": "Create AI-powered short-form video clips from YouTube videos or uploaded files. Browse caption templates, background music, gameplay overlays, and meme hooks.",
+  "version": "1.0.0",
+  "websiteUrl": "https://aiclipping.ssemble.com",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/vlogr/ssemble-mcp-server.git"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@ssemble/mcp-server",
+      "version": "1.0.0",
+      "transport": "stdio",
+      "environmentVariables": [
+        {
+          "name": "SSEMBLE_API_KEY",
+          "description": "Your Ssemble API key (starts with sk_ssemble_). Get it at https://app.ssemble.com → Settings → API Keys",
+          "required": true
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "transportType": "streamable-http",
+      "url": "https://mcp.ssemble.com/mcp"
+    }
+  ]
+}

package/src/api/client.js

@@ -0,0 +1,122 @@
+/**
+ * Ssemble API Client
+ * Wraps all 9 Ssemble AI Clipping API endpoints with native fetch.
+ */
+
+const DEFAULT_BASE_URL = 'https://aiclipping.ssemble.com/api/v1';
+
+export class SsembleApiError extends Error {
+  constructor(status, error, rateLimits) {
+    super(error?.message || `API error (${status})`);
+    this.name = 'SsembleApiError';
+    this.status = status;
+    this.code = error?.code || 'unknown_error';
+    this.details = error?.details || null;
+    this.rateLimits = rateLimits;
+  }
+}
+
+export class SsembleClient {
+  constructor(apiKey, baseUrl) {
+    if (!apiKey) {
+      throw new Error('SSEMBLE_API_KEY is required');
+    }
+    if (!apiKey.startsWith('sk_ssemble_')) {
+      throw new Error('Invalid API key format. Must start with sk_ssemble_');
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl || DEFAULT_BASE_URL;
+  }
+
+  async _request(method, path, { body, query } = {}) {
+    let url = `${this.baseUrl}${path}`;
+
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null) {
+          params.set(key, String(value));
+        }
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+
+    const headers = {
+      'X-API-Key': this.apiKey,
+      'Content-Type': 'application/json',
+    };
+
+    const options = { method, headers };
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    const rateLimits = {
+      hourlyLimit: response.headers.get('x-ratelimit-limit-hour'),
+      hourlyRemaining: response.headers.get('x-ratelimit-remaining-hour'),
+      dailyLimit: response.headers.get('x-ratelimit-limit-day'),
+      dailyRemaining: response.headers.get('x-ratelimit-remaining-day'),
+      reset: response.headers.get('x-ratelimit-reset'),
+    };
+
+    if (method === 'DELETE' && response.status === 204) {
+      return { data: { message: 'Request successfully deleted' }, rateLimits };
+    }
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new SsembleApiError(response.status, data.error, rateLimits);
+    }
+
+    return { ...data, rateLimits };
+  }
+
+  // Endpoint 1: GET /templates
+  async listTemplates() {
+    return this._request('GET', '/templates');
+  }
+
+  // Endpoint 2: POST /shorts/create
+  async createShort(params) {
+    return this._request('POST', '/shorts/create', { body: params });
+  }
+
+  // Endpoint 3: GET /shorts/:id/status
+  async getStatus(requestId) {
+    return this._request('GET', `/shorts/${requestId}/status`);
+  }
+
+  // Endpoint 4: GET /shorts/:id
+  async getShorts(requestId) {
+    return this._request('GET', `/shorts/${requestId}`);
+  }
+
+  // Endpoint 5: GET /shorts
+  async listRequests(query) {
+    return this._request('GET', '/shorts', { query });
+  }
+
+  // Endpoint 6: DELETE /shorts/:id
+  async deleteRequest(requestId) {
+    return this._request('DELETE', `/shorts/${requestId}`);
+  }
+
+  // Endpoint 7: GET /music
+  async listMusic(query) {
+    return this._request('GET', '/music', { query });
+  }
+
+  // Endpoint 8: GET /game-videos
+  async listGameVideos(query) {
+    return this._request('GET', '/game-videos', { query });
+  }
+
+  // Endpoint 9: GET /meme-hooks
+  async listMemeHooks(query) {
+    return this._request('GET', '/meme-hooks', { query });
+  }
+}

package/src/index.js

@@ -0,0 +1,50 @@
+/**
+ * Ssemble MCP Server — factory function.
+ * Creates and configures the McpServer with all tools, resources, and prompts.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SsembleClient } from './api/client.js';
+
+// Tools
+import { registerCreateShort } from './tools/create-short.js';
+import { registerGetStatus } from './tools/get-status.js';
+import { registerGetShorts } from './tools/get-shorts.js';
+import { registerListRequests } from './tools/list-requests.js';
+import { registerDeleteRequest } from './tools/delete-request.js';
+import { registerListTemplates } from './tools/list-templates.js';
+import { registerListMusic } from './tools/list-music.js';
+import { registerListGameVideos } from './tools/list-game-videos.js';
+import { registerListMemeHooks } from './tools/list-meme-hooks.js';
+
+// Resources & Prompts
+import { registerResources } from './resources/static-data.js';
+import { registerPrompts } from './prompts/workflows.js';
+
+export function createSsembleMcpServer(apiKey, baseUrl) {
+  const server = new McpServer({
+    name: 'ssemble-ai-clipping',
+    version: '1.0.0',
+  });
+
+  const client = new SsembleClient(apiKey, baseUrl);
+
+  // Register all 9 tools
+  registerCreateShort(server, client);
+  registerGetStatus(server, client);
+  registerGetShorts(server, client);
+  registerListRequests(server, client);
+  registerDeleteRequest(server, client);
+  registerListTemplates(server, client);
+  registerListMusic(server, client);
+  registerListGameVideos(server, client);
+  registerListMemeHooks(server, client);
+
+  // Register resources
+  registerResources(server);
+
+  // Register prompts
+  registerPrompts(server);
+
+  return server;
+}

package/src/prompts/workflows.js

@@ -0,0 +1,63 @@
+/**
+ * MCP Prompts — pre-built workflow templates.
+ */
+
+export function registerPrompts(server) {
+  server.prompt(
+    'create-viral-short',
+    'Guided workflow for creating an optimized viral short from a YouTube video',
+    [
+      { name: 'url', description: 'YouTube video URL', required: true },
+      { name: 'style', description: 'Style preference: engaging, educational, funny, dramatic', required: false },
+    ],
+    ({ url, style }) => {
+      const styleHint = style ? `\nThe user prefers a **${style}** style.` : '';
+      return {
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `I want to create viral short-form clips from this YouTube video: ${url}${styleHint}
+
+Please help me by:
+1. First, use \`list_templates\` to show me available caption styles
+2. Use \`list_music\` to suggest background music options
+3. Ask me which template and music I prefer
+4. Then use \`create_short\` with my choices (use start: 0, end: 600 for the first 10 minutes, or ask me for a specific time range)
+5. After submitting, remind me to check back with \`get_status\` in a few minutes`,
+            },
+          },
+        ],
+      };
+    }
+  );
+
+  server.prompt(
+    'batch-process-videos',
+    'Template for processing multiple YouTube videos into shorts',
+    [
+      { name: 'urls', description: 'Comma-separated YouTube URLs', required: true },
+    ],
+    ({ urls }) => {
+      const urlList = urls.split(',').map((u) => u.trim()).filter(Boolean);
+      return {
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `I want to create shorts from these ${urlList.length} videos:
+${urlList.map((u, i) => `${i + 1}. ${u}`).join('\n')}
+
+Please:
+1. Submit each video using \`create_short\` with default settings (start: 0, end: 600, preferredLength: under60sec)
+2. Track all request IDs
+3. After all are submitted, list the request IDs so I can check on them later with \`get_status\``,
+            },
+          },
+        ],
+      };
+    }
+  );
+}

package/src/resources/static-data.js

@@ -0,0 +1,73 @@
+/**
+ * MCP Resources — static reference data for AI context.
+ */
+
+const SUPPORTED_LANGUAGES = {
+  en: 'English', es: 'Spanish', fr: 'French', de: 'German', it: 'Italian',
+  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',
+};
+
+const PREFERRED_LENGTHS = {
+  under30sec: 'Under 30 seconds — quick hook clips',
+  under60sec: 'Under 60 seconds (default) — standard TikTok/Reels length',
+  under90sec: 'Under 90 seconds — extended shorts',
+  under3min: 'Under 3 minutes — YouTube Shorts max',
+  under5min: 'Under 5 minutes — longer highlight clips',
+  under10min: 'Under 10 minutes — full segment extraction',
+};
+
+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',
+  square: 'Square — 1:1 aspect ratio',
+};
+
+export function registerResources(server) {
+  server.resource(
+    'supported-languages',
+    'ssemble://supported-languages',
+    'List of supported language codes and names for video transcription and captions',
+    async () => {
+      let text = '## Supported Languages\n\n';
+      text += '| Code | Language |\n|------|----------|\n';
+      for (const [code, name] of Object.entries(SUPPORTED_LANGUAGES)) {
+        text += `| ${code} | ${name} |\n`;
+      }
+      text += '\nUse the 2-letter code in the `language` or `captionLanguage` parameter.';
+      return { contents: [{ uri: 'ssemble://supported-languages', mimeType: 'text/markdown', text }] };
+    }
+  );
+
+  server.resource(
+    'preferred-lengths',
+    'ssemble://preferred-lengths',
+    'Available clip duration options for the preferredLength parameter',
+    async () => {
+      let text = '## Preferred Length Options\n\n';
+      text += '| Value | Description |\n|-------|-------------|\n';
+      for (const [value, desc] of Object.entries(PREFERRED_LENGTHS)) {
+        text += `| \`${value}\` | ${desc} |\n`;
+      }
+      text += '\nDefault: `under60sec`';
+      return { contents: [{ uri: 'ssemble://preferred-lengths', mimeType: 'text/markdown', text }] };
+    }
+  );
+
+  server.resource(
+    'layouts',
+    'ssemble://layouts',
+    'Available video layout/framing options',
+    async () => {
+      let text = '## Layout Options\n\n';
+      text += '| Value | Description |\n|-------|-------------|\n';
+      for (const [value, desc] of Object.entries(LAYOUTS)) {
+        text += `| \`${value}\` | ${desc} |\n`;
+      }
+      text += '\nDefault: `auto`';
+      return { contents: [{ uri: 'ssemble://layouts', mimeType: 'text/markdown', text }] };
+    }
+  );
+}

package/src/tools/create-short.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { formatCreateShortResponse, formatError } from '../utils/format.js';
+
+const SUPPORTED_LANGUAGES = [
+  'en', 'es', 'fr', 'de', 'it', 'pt', 'ru', 'ja', 'ko', 'zh',
+  'ar', 'hi', 'tr', 'pl', 'nl', 'sv', 'no', 'da', 'fi', 'cs',
+];
+
+const schema = {
+  url: z.string().describe('YouTube video URL').optional(),
+  fileUrl: z.string().url().describe('Public video file URL (alternative to url)').optional(),
+  start: z.number().min(0).describe('Start time in seconds (>= 0)'),
+  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(),
+  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(),
+  noClipping: z.boolean().default(false).describe('Skip AI clipping, process entire range as one clip').optional(),
+  hookTitle: z.boolean().default(false).describe('Add animated hook title at start').optional(),
+  memeHook: z.boolean().default(false).describe('Prepend a meme hook clip (2-5s attention grabber)').optional(),
+  memeHookName: z.string().describe('Exact meme hook name from list_meme_hooks (case-sensitive)').optional(),
+  gameVideo: z.boolean().default(false).describe('Add split-screen gameplay overlay').optional(),
+  gameVideoName: z.string().describe('Exact game video name from list_game_videos (case-sensitive)').optional(),
+  ctaEnabled: z.boolean().default(false).describe('Show call-to-action text overlay').optional(),
+  ctaText: z.string().max(200).describe('CTA text (max 200 chars, required when ctaEnabled=true)').optional(),
+  music: z.boolean().default(false).describe('Add background music').optional(),
+  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(),
+};
+
+export function registerCreateShort(server, client) {
+  server.tool(
+    'create_short',
+    'Create AI-generated short-form video clips from a YouTube video or uploaded file. Returns a request ID instantly. Processing takes 5-30 minutes. Costs 1 credit.',
+    schema,
+    async (params) => {
+      if (!params.url && !params.fileUrl) {
+        return { content: [{ type: 'text', text: formatError({ message: 'Either url or fileUrl is required', code: 'invalid_request' }) }], isError: true };
+      }
+      if (params.url && params.fileUrl) {
+        return { content: [{ type: 'text', text: formatError({ message: 'Provide either url or fileUrl, not both', code: 'invalid_request' }) }], isError: true };
+      }
+      if (params.start >= params.end) {
+        return { content: [{ type: 'text', text: formatError({ message: 'Start time must be less than end time', code: 'invalid_request' }) }], isError: true };
+      }
+      if ((params.end - params.start) > 1200) {
+        return { content: [{ type: 'text', text: formatError({ message: 'Time window exceeds maximum of 1200 seconds (20 minutes)', code: 'invalid_request' }) }], isError: true };
+      }
+      if (params.ctaEnabled && !params.ctaText) {
+        return { content: [{ type: 'text', text: formatError({ message: 'ctaText is required when ctaEnabled is true', code: 'invalid_request' }) }], isError: true };
+      }
+
+      try {
+        const result = await client.createShort(params);
+        return { content: [{ type: 'text', text: formatCreateShortResponse(result) }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/delete-request.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { formatDeleteResponse, formatError } from '../utils/format.js';
+
+const schema = {
+  requestId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('The request ID to delete (24-char hex). This action is irreversible and credits are NOT refunded.'),
+};
+
+export function registerDeleteRequest(server, client) {
+  server.tool(
+    'delete_request',
+    'Permanently delete a short creation request and all generated videos. Credits are NOT refunded. This action is irreversible.',
+    schema,
+    async ({ requestId }) => {
+      try {
+        const result = await client.deleteRequest(requestId);
+        return { content: [{ type: 'text', text: formatDeleteResponse(result) }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/get-shorts.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { formatShortsResponse, formatError } from '../utils/format.js';
+
+const schema = {
+  requestId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('The request ID from create_short (24-char hex)'),
+};
+
+export function registerGetShorts(server, client) {
+  server.tool(
+    '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,
+    async ({ requestId }) => {
+      try {
+        const result = await client.getShorts(requestId);
+        return { content: [{ type: 'text', text: formatShortsResponse(result) }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/get-status.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { formatStatusResponse, formatError } from '../utils/format.js';
+
+const schema = {
+  requestId: z.string().regex(/^[0-9a-fA-F]{24}$/).describe('The request ID from create_short (24-char hex)'),
+};
+
+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.',
+    schema,
+    async ({ requestId }) => {
+      try {
+        const result = await client.getStatus(requestId);
+        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

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { formatPaginatedAssets, formatError } from '../utils/format.js';
+
+const schema = {
+  page: z.number().min(1).default(1).describe('Page number').optional(),
+  limit: z.number().min(1).max(100).default(20).describe('Items per page (1-100)').optional(),
+};
+
+export function registerListGameVideos(server, client) {
+  server.tool(
+    'list_game_videos',
+    'List available gameplay videos for split-screen overlays (content top, game bottom). Use the exact gameVideoName when creating shorts.',
+    schema,
+    async (params) => {
+      try {
+        const result = await client.listGameVideos(params);
+        return { content: [{ type: 'text', text: formatPaginatedAssets(result, 'gameVideos', 'Gameplay Overlays') }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

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

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { formatPaginatedAssets, formatError } from '../utils/format.js';
+
+const schema = {
+  page: z.number().min(1).default(1).describe('Page number').optional(),
+  limit: z.number().min(1).max(100).default(20).describe('Items per page (1-100)').optional(),
+};
+
+export function registerListMemeHooks(server, client) {
+  server.tool(
+    'list_meme_hooks',
+    'List available meme hook clips (2-5 second attention grabbers prepended to shorts). Use the exact memeHookName when creating shorts.',
+    schema,
+    async (params) => {
+      try {
+        const result = await client.listMemeHooks(params);
+        return { content: [{ type: 'text', text: formatPaginatedAssets(result, 'memeHooks', 'Meme Hooks') }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/list-music.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { formatPaginatedAssets, formatError } from '../utils/format.js';
+
+const schema = {
+  page: z.number().min(1).default(1).describe('Page number').optional(),
+  limit: z.number().min(1).max(100).default(20).describe('Items per page (1-100)').optional(),
+};
+
+export function registerListMusic(server, client) {
+  server.tool(
+    'list_music',
+    'List available background music tracks with names and durations. Use the exact musicName when creating shorts.',
+    schema,
+    async (params) => {
+      try {
+        const result = await client.listMusic(params);
+        return { content: [{ type: 'text', text: formatPaginatedAssets(result, 'music', 'Background Music') }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/list-requests.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { formatListRequestsResponse, formatError } from '../utils/format.js';
+
+const schema = {
+  page: z.number().min(1).default(1).describe('Page number').optional(),
+  limit: z.number().min(1).max(100).default(20).describe('Items per page (1-100)').optional(),
+  status: z.enum(['queued', 'processing', 'completed', 'failed', 'cancelled']).describe('Filter by status').optional(),
+  sortBy: z.enum(['createdAt', 'updatedAt']).default('createdAt').describe('Sort field').optional(),
+  sortOrder: z.enum(['asc', 'desc']).default('desc').describe('Sort direction').optional(),
+};
+
+export function registerListRequests(server, client) {
+  server.tool(
+    'list_requests',
+    'List all short creation requests with optional status filtering, pagination, and sorting.',
+    schema,
+    async (params) => {
+      try {
+        const result = await client.listRequests(params);
+        return { content: [{ type: 'text', text: formatListRequestsResponse(result) }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/list-templates.js

@@ -0,0 +1,17 @@
+import { formatTemplatesResponse, formatError } from '../utils/format.js';
+
+export function registerListTemplates(server, client) {
+  server.tool(
+    'list_templates',
+    'List all available caption style templates with IDs and names. Use the templateId when creating shorts.',
+    {},
+    async () => {
+      try {
+        const result = await client.listTemplates();
+        return { content: [{ type: 'text', text: formatTemplatesResponse(result) }] };
+      } catch (error) {
+        return { content: [{ type: 'text', text: formatError(error) }], isError: true };
+      }
+    }
+  );
+}

package/src/transports/http.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * Streamable HTTP transport — entry point for remote deployment.
+ * Runs an Express server that handles MCP protocol via HTTP.
+ * Supports per-request API keys for multi-tenant usage.
+ */
+
+import express from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createSsembleMcpServer } from '../index.js';
+
+const app = express();
+app.use(express.json());
+
+const SERVER_CARD = {
+  serverInfo: {
+    name: 'ssemble-ai-clipping',
+    version: '1.0.0',
+  },
+  capabilities: {
+    tools: true,
+    resources: true,
+    prompts: true,
+  },
+  authentication: {
+    required: true,
+    schemes: ['api_key'],
+    instructions: 'Pass your Ssemble API key via the X-Ssemble-API-Key header or set SSEMBLE_API_KEY env var on the server.',
+  },
+};
+
+// Health check
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok', server: 'ssemble-mcp', version: '1.0.0' });
+});
+
+// Smithery auto-discovery
+app.get('/.well-known/mcp/server-card.json', (_req, res) => {
+  res.json(SERVER_CARD);
+});
+
+// MCP endpoint — stateless mode (each request is independent)
+app.all('/mcp', async (req, res) => {
+  const apiKey = req.headers['x-ssemble-api-key'] || process.env.SSEMBLE_API_KEY;
+
+  if (!apiKey) {
+    return res.status(401).json({
+      error: {
+        code: 'missing_api_key',
+        message: 'Ssemble API key required. Pass via X-Ssemble-API-Key header or set SSEMBLE_API_KEY env var.',
+      },
+    });
+  }
+
+  try {
+    const baseUrl = process.env.SSEMBLE_API_BASE_URL;
+    const server = createSsembleMcpServer(apiKey, baseUrl);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined, // stateless
+    });
+
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  } catch (error) {
+    if (!res.headersSent) {
+      res.status(500).json({
+        error: {
+          code: 'internal_error',
+          message: 'MCP server error',
+        },
+      });
+    }
+  }
+});
+
+const port = parseInt(process.env.MCP_PORT || '3100', 10);
+app.listen(port, () => {
+  console.log(`Ssemble MCP Server (HTTP) listening on port ${port}`);
+  console.log(`  MCP endpoint: http://localhost:${port}/mcp`);
+  console.log(`  Health check: http://localhost:${port}/health`);
+  console.log(`  Server card:  http://localhost:${port}/.well-known/mcp/server-card.json`);
+});

package/src/transports/stdio.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Stdio transport — entry point for local usage via npx or Claude Desktop/Code config.
+ * Reads SSEMBLE_API_KEY from environment variable.
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+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');
+  process.exit(1);
+}
+
+const baseUrl = process.env.SSEMBLE_API_BASE_URL;
+const server = createSsembleMcpServer(apiKey, baseUrl);
+const transport = new StdioServerTransport();
+
+await server.connect(transport);

package/src/utils/format.js

@@ -0,0 +1,191 @@
+/**
+ * Response formatting utilities for AI readability.
+ * Converts API responses into markdown that AI assistants can present clearly.
+ */
+
+export function formatRateLimits(rateLimits) {
+  if (!rateLimits || !rateLimits.hourlyRemaining) return '';
+  return `\n\n---\nRate limits: ${rateLimits.hourlyRemaining}/${rateLimits.hourlyLimit} hourly, ${rateLimits.dailyRemaining}/${rateLimits.dailyLimit} daily`;
+}
+
+export function formatCreateShortResponse(result) {
+  const d = result.data;
+  let text = `## Short Creation Submitted\n\n`;
+  text += `- **Request ID**: \`${d.requestId}\`\n`;
+  text += `- **Status**: ${d.status}\n`;
+  text += `- **Credits Used**: ${d.creditsUsed}\n`;
+  text += `- **Estimated Completion**: ${d.estimatedCompletionTime}\n`;
+  text += `\nProcessing takes 5-30 minutes. Use \`get_status\` with request ID \`${d.requestId}\` to check progress.`;
+
+  if (d.timeAdjustment) {
+    text += `\n\n**Note**: ${d.timeAdjustment.message}\n`;
+    text += `- Original: ${d.timeAdjustment.original.start}s - ${d.timeAdjustment.original.end}s\n`;
+    text += `- Adjusted: ${d.timeAdjustment.adjusted.start}s - ${d.timeAdjustment.adjusted.end}s\n`;
+    text += `- Video duration: ${d.timeAdjustment.videoDuration}s\n`;
+  }
+
+  text += formatRateLimits(result.rateLimits);
+  return text;
+}
+
+export function formatStatusResponse(result) {
+  const d = result.data;
+  const progressBar = makeProgressBar(d.progress || 0);
+
+  let text = `## Request Status: \`${d._id}\`\n\n`;
+  text += `- **Status**: ${d.status}\n`;
+  text += `- **Step**: ${d.step}\n`;
+  text += `- **Progress**: ${progressBar} ${d.progress || 0}%\n`;
+  if (d.stepMessage) {
+    text += `- **Message**: ${d.stepMessage}\n`;
+  }
+  if (d.failureReason) {
+    text += `- **Failure Reason**: ${d.failureReason}\n`;
+  }
+
+  if (d.status === 'completed') {
+    text += `\nUse \`get_shorts\` with request ID \`${d._id}\` to retrieve the generated clips.`;
+  }
+
+  text += formatRateLimits(result.rateLimits);
+  return text;
+}
+
+export function formatShortsResponse(result) {
+  const d = result.data;
+
+  if (d.status !== 'completed' && d.status !== 'TASK_COMPLETE') {
+    return `Request \`${d._id}\` is not yet completed (status: ${d.status}). Use \`get_status\` to check progress.`;
+  }
+
+  let text = `## Generated Shorts for "${d.title || 'Untitled'}"\n\n`;
+  text += `- **Source**: ${d.url || 'uploaded file'}\n`;
+  text += `- **Time Range**: ${d.start}s - ${d.end}s\n`;
+  text += `- **Language**: ${d.language}\n`;
+  text += `- **Template**: ${d.template}\n\n`;
+
+  const shorts = d.shorts || [];
+  if (shorts.length === 0) {
+    text += `No shorts were generated.\n`;
+    return text;
+  }
+
+  // Sort by viral_score descending
+  const sorted = [...shorts].sort((a, b) => (b.viral_score || 0) - (a.viral_score || 0));
+
+  text += `| # | Title | Duration | Viral Score | Video URL |\n`;
+  text += `|---|-------|----------|-------------|----------|\n`;
+
+  sorted.forEach((short, i) => {
+    const title = (short.title || 'Untitled').substring(0, 40);
+    const duration = short.duration ? `${short.duration}s` : 'N/A';
+    const score = short.viral_score != null ? short.viral_score : 'N/A';
+    const url = short.video_url || (short.error ? 'Error' : 'Processing...');
+    text += `| ${i + 1} | ${title} | ${duration} | ${score} | ${url} |\n`;
+  });
+
+  text += `\n**${sorted.length} clips generated**, sorted by viral score.`;
+  text += formatRateLimits(result.rateLimits);
+  return text;
+}
+
+export function formatListRequestsResponse(result) {
+  const d = result.data;
+  const requests = d.requests || [];
+  const p = d.pagination;
+
+  if (requests.length === 0) {
+    return `No requests found.${formatRateLimits(result.rateLimits)}`;
+  }
+
+  let text = `## Your Requests (Page ${p.page}/${p.totalPages}, ${p.totalCount} total)\n\n`;
+  text += `| # | Request ID | Status | Progress | Created | Duration |\n`;
+  text += `|---|-----------|--------|----------|---------|----------|\n`;
+
+  requests.forEach((req, i) => {
+    const created = req.createdAt ? new Date(req.createdAt).toLocaleDateString() : 'N/A';
+    const duration = req.duration ? `${req.duration}s` : 'N/A';
+    text += `| ${(p.page - 1) * p.limit + i + 1} | \`${req.requestId}\` | ${req.status} | ${req.progress || 0}% | ${created} | ${duration} |\n`;
+  });
+
+  if (p.totalPages > 1) {
+    text += `\nPage ${p.page} of ${p.totalPages}. Use \`page\` parameter to browse more.`;
+  }
+
+  text += formatRateLimits(result.rateLimits);
+  return text;
+}
+
+export function formatTemplatesResponse(result) {
+  const d = result.data;
+  const templates = d.templates || [];
+
+  let text = `## Caption Templates (${templates.length} available)\n\n`;
+  text += `| Template ID | Name | Default |\n`;
+  text += `|-------------|------|--------|\n`;
+
+  templates.forEach((t) => {
+    const isDefault = t.templateId === d.defaultTemplateId ? 'Yes' : '';
+    text += `| \`${t.templateId}\` | ${t.displayName || t.name} | ${isDefault} |\n`;
+  });
+
+  text += `\nDefault template: **${d.defaultTemplateName}** (\`${d.defaultTemplateId}\`)`;
+  text += `\nUse \`templateId\` when calling \`create_short\`.`;
+  text += formatRateLimits(result.rateLimits);
+  return text;
+}
+
+export function formatPaginatedAssets(result, assetKey, assetLabel) {
+  const d = result.data;
+  const items = d[assetKey] || [];
+  const p = d.pagination;
+
+  if (items.length === 0) {
+    return `No ${assetLabel} found.${formatRateLimits(result.rateLimits)}`;
+  }
+
+  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`;
+
+  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`;
+  });
+
+  if (p.totalPages > 1) {
+    text += `\nPage ${p.page} of ${p.totalPages}. Use \`page\` parameter to browse more.`;
+  }
+
+  text += `\nUse the exact \`name\` value when calling \`create_short\`.`;
+  text += formatRateLimits(result.rateLimits);
+  return text;
+}
+
+export function formatDeleteResponse(result) {
+  let text = `Request successfully deleted. Credits are NOT refunded.`;
+  text += formatRateLimits(result.rateLimits);
+  return text;
+}
+
+export function formatError(error) {
+  if (error instanceof Error && error.code) {
+    let text = `**Error**: ${error.message}`;
+    if (error.code) text += ` (${error.code})`;
+    if (error.details) {
+      text += `\n\n**Details**: ${JSON.stringify(error.details, null, 2)}`;
+    }
+    if (error.rateLimits?.hourlyRemaining) {
+      text += formatRateLimits(error.rateLimits);
+    }
+    return text;
+  }
+  return `**Error**: ${error.message || String(error)}`;
+}
+
+function makeProgressBar(percent) {
+  const filled = Math.round(percent / 10);
+  const empty = 10 - filled;
+  return '[' + '='.repeat(filled) + ' '.repeat(empty) + ']';
+}