# Creatomate Video Engine MCP Server

This is a Model Context Protocol (MCP) server that interfaces with the [Creatomate API](https://creatomate.com). It turns LLMs (like Claude, ChatGPT) into autonomous **Senior Motion Designers** capable of generating industry-standard social media videos, ads, and shorts programmatically.

## 🚀 The Crux

This server goes beyond simple video rendering. It is architected to produce **viral-style content** (Reels/Shorts/TikTok) by enforcing:

1.  **Kinetic Typography:** Word-by-word "karaoke" animations.
2.  **Auto-Captions:** Automatic synchronization between AI Voiceovers (TTS) and Text.
3.  **Social Safe Zones:** Smart defaults for 9:16 aspect ratios and readable text overlays.
4.  **Hallucination Prevention:** Exposes valid animation dictionaries to the LLM via Resources.

---

## 🏗 Server Structure

The server is built on the `@modelcontextprotocol/sdk` and exposes the following three primitives:

### 1. Resources (Data Context)

**`creatomate://catalog/animations`**

- **Purpose:** Provides the LLM with a strict JSON catalog of valid animation types (`text-slide`, `scale`, `wipe`) and easing functions (`elastic-out`, `bounce-out`).
- **Why:** Prevents the LLM from inventing animations that don't exist in the Creatomate engine.

### 2. Prompts (Agent Personas)

**`design-social-ad`**

- **Arguments:** `topic`, `platform` (Instagram, TikTok, YouTube).
- **Behavior:** Sets the LLM's system instruction to "Senior Motion Designer."
- **Logic:** Enforces a checklist before tool use:
  - Must use 9:16 aspect ratio.
  - Must use short scenes (2-4s).
  - Must link Audio tracks to Text layers for auto-captions.

### 3. Tools (Action Capabilities)

**`render_video`**

- **Capabilities:** The core engine that constructs the render script.
- **Advanced Features:**
  - **TTS Integration:** Converts `audio` elements with text sources into speech (via Google/ElevenLabs).
  - **Auto-Captions:** Uses the `transcript_source` property to link a Text element to an Audio element.
  - **Styling:** Supports "Sticker" styles (background boxes with padding/radius) for high readability.

---

## 💻 Installation & Setup

### Prerequisites

- Node.js (v18+)
- A [Creatomate API Key](https://creatomate.com)

### 1. Environment

Create a `.env` file in the root directory:

```env
CREATOMATE_API_KEY=your_api_key_here
```

### 2. Install Dependencies

```bash
npm install
```

### 3. Build

```bash
npm run build
```

---

## 🔌 Transports & Usage

This server supports both **Stdio** (for local desktop apps like Claude Desktop) and **SSE** (Server-Sent Events for remote web integration).

### Option A: Stdio (Local / Claude Desktop)

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "creatomate": {
      "command": "node",
      "args": ["dist/index-stdio.js"],
      "env": {
        "CREATOMATE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Option B: SSE (Web / Remote)

If running as a standalone HTTP server (e.g., for a web-based chat interface):

```bash
# Assumes your code exports an SSE handler or runs a server on a port
node dist/index-sse.js --transport sse --port 3000
```

_Note: Ensure your code implements the `SSEServerTransport` logic if you intend to run this mode._

---

## 🧠 LLM Workflow Example

Here is how the LLM interacts with the server internally:

1.  **User:** "Make a hype video for my new energy drink."
2.  **LLM (Prompt `design-social-ad`):** "I need to make a 9:16 video. I will use the 'text-slide' animation."
3.  **LLM (Tool `render_video`):** Generates this payload:

```json
{
  "width": 1080,
  "height": 1920,
  "elements": [
    {
      "type": "video",
      "track": 1,
      "source": "https://stock-footage..."
    },
    {
      "type": "audio",
      "track": 2,
      "name": "voiceover_main",
      "source": "Wake up. Focus. Dominate.",
      "provider": "google"
    },
    {
      "type": "text",
      "track": 3,
      "transcript_source": "voiceover_main",
      "fillColor": "#FFFF00",
      "enter": { "type": "text-slide", "scope": "split-clip", "split": "word" }
    }
  ]
}
```

4.  **Server:** Renders the video via Creatomate and returns the MP4 URL.

---

## 🛠 Troubleshooting

- **Error: `API Key Missing`**: Ensure `.env` is loaded. If using Stdio via Claude Desktop, the env var must be in the `claude_desktop_config.json`, not just the local `.env`.
- **Video Render Failed**: Check the `render_video` tool output. If the stock asset URL is broken, Creatomate will fail.
- **Captions not syncing**: Ensure the `name` property of the Audio element exactly matches the `transcript_source` of the Text element.