# 🧠 Brainrot MCP Server

[![Docker Compose](https://img.shields.io/badge/docker--compose-up-blue?logo=docker&style=flat-square)](https://docs.docker.com/compose/)
[![FastMCP](https://img.shields.io/badge/FastMCP-Python-green?style=flat-square)](https://github.com/jlowin/fastmcp)
[![Piper TTS](https://img.shields.io/badge/TTS-Piper--ONNX-orange?style=flat-square)](https://github.com/OHF-Voice/piper1-gpl)
[![MoviePy](https://img.shields.io/badge/Video--Engine-MoviePy-red?style=flat-square)](https://zulko.github.io/moviepy/)

An advanced **Model Context Protocol (MCP)** server that enables AI assistants (like Gemini/Antigravity) to automatically generate vertical "brainrot" style videos. It takes a text script, generates high-quality localized Text-to-Speech voiceovers with synchronized word-wrapped subtitles, overlays custom SVG graphics at precise timestamps, ducks background audio, and renders a complete MP4 ready for publishing.

---

## 🗺️ System Architecture

```mermaid
graph TD
    Client[AI Client / Gemini / Antigravity] -->|1. Call create_brainrot_video| MCP[Brainrot MCP Server]
    MCP -->|2. Generate Audio & Subtitles| TTS[Local Piper TTS Service]
    TTS -->|3. Audio WAV & SRT timings| MCP
    MCP -->|4. Convert SVGs to PNG| IM[ImageMagick / librsvg]
    MCP -->|5. Slice, Overlay, Duck & Render| MP[MoviePy Engine]
    MP -->|6. Save Video| Out[(Output Directory)]
```

---

## ⚡ Quick Start (Automated Setup)

The easiest way to get everything up and running is using the automated setup script, which automatically registers the MCP server in your Gemini config and starts the Docker services.

### 1. Download Background Videos
Before running the setup, you must download at least one background video (e.g., Minecraft parkour, Subway Surfers gameplay, or satisfying sand-cutting videos in vertical aspect ratio) and place it in the `videos` directory.
- **Directory**: `[project_root]/videos/`
- **Supported Formats**: `.mp4`, `.webm`, `.mov`, `.mkv`, `.avi`

### 2. Run the Setup Script
Run the script appropriate for your operating system:

#### Windows (PowerShell / CMD)
```cmd
.\scripts\setup.bat
```

#### Linux / macOS
```bash
chmod +x scripts/setup.sh
./scripts/setup.sh
```

> [!NOTE]  
> The script will look for your Gemini configuration directory at `~/.gemini/config/` and add the `brainrot` MCP server pointing to `http://localhost:8543/mcp`. It will then run `docker compose up --build -d` to start the backend services.
> 
> You will need to **restart Antigravity / Gemini** for the settings to take effect.

---

## 🛠️ Manual Setup (Step-by-Step)

If you prefer to configure the server manually or do not want to use the setup script, follow these steps:

### 1. Prepare Background Footage
Download vertical background videos and place them into the `videos/` folder inside the project root:
```
brainrot-mcp/
├── videos/
│   ├── minecraft_parkour.mp4
│   └── subway_surfers.mp4
```

### 2. Run with Docker Compose
From the project root directory, build and launch the multi-container setup in detached mode:
```bash
docker compose up --build -d
```
This launches two services:
* **`tts-service`** on port `8000`: Runs the Piper TTS FastAPI server.
* **`mcp-server`** on port `8543`: Runs the FastMCP server exposed over `streamable-http` at `/mcp`.

### 3. Register the MCP Server
Add the server entry to your client configuration file. 

* **Config Path**: `~/.gemini/config/mcp_config.json` (or `config.json`)
* **JSON Block**:
```json
{
  "mcpServers": {
    "brainrot": {
      "serverUrl": "http://localhost:8543/mcp"
    }
  }
}
```

---

## ⚙️ How It Works Under the Hood

### 🎙️ Local Text-To-Speech Service (`/tts`)
* **Core Engine**: Powered by **Piper TTS** using the high-quality `en_US-ryan-medium.onnx` voice. It executes on the **GPU (via CUDA)** if a compatible Nvidia card is available, gracefully falling back to CPU execution.
* **Text Sanitization**: Includes a robust regular-expression pre-processor that translates spoken stumbling blocks into natural speech:
  * IP addresses: `127.0.0.1` ➡️ *"one two seven dot zero dot zero dot one"*
  * Domain names: `google.com` ➡️ *"google dot com"*
  * Acronyms/Protocols: `HTTP`, `mcp`, `URL`, `localhost` ➡️ *"H T T P"*, *"M C P"*, *"U R L"*, *"local host"*

### 🎬 Video Composition Engine (`/mcp_server`)
* **Dynamic Slicing**: Loads a random background video from your `videos/` folder and crops/loops it to perfectly match the duration of the generated speech audio.
* **Vertical Layout Optimization**: Resizes output footage to **540p width** (540x960 vertical format, qHD) to guarantee lightning-fast render speeds while maintaining sharp resolution on mobile screens.
* **Subtitle Synced Overlays**: Parses SRT subtitles returned from the Piper engine. Wraps text block widths to prevent clipping and uses yellow text with thick black borders (`TextClip`) for maximum readability.
* **SVG Graphics Renderer**: Converts arbitrary inline SVGs supplied by the AI model into transparent PNGs using `rsvg-convert` or ImageMagick, then composites them on screen at specific script checkpoints.
* **Audio Ducking**: Automatically scales the background audio of the original video down to **8% volume**, layering the clear TTS voiceover on top.

---

## 🔌 MCP Tool Reference

The server exposes a single, powerful tool to the AI model:

### `create_brainrot_video`
Generates a vertical brainrot video with text-to-speech voiceover and synchronized subtitles.

#### Arguments
* **`script`** *(string, required)*: The voiceover script. Supports inline tags:
  * `[show_image <key>] ... [end_show_image]`: Displays the image associated with `<key>` during the reading of this text segment.
  * `[wait <float>s]`: Pauses the voiceover generation for the specified duration (e.g. `[wait 1.5s]`).
* **`title`** *(string, optional)*: The title of the video. It will appear centered as an intro card for `0.5s` and then slide to the top-left corner as a constant watermark.
* **`images_json`** *(string, optional)*: A JSON string mapping the image keys used in the script tags to raw SVG source strings.

#### Example Payload
```json
{
  "title": "LOCALHOST DEMO",
  "script": "[show_image server_icon] Starting up the local host server at 127.0.0.1. [end_show_image] We are online! [wait 1.5s] Check it out.",
  "images_json": "{\"server_icon\": \"<svg width='100' height='100'><circle cx='50' cy='50' r='40' fill='green'/></svg>\"}"
}
```

---

## 🧪 Testing the Setup

You can run the included Python test client to verify that your Docker services are running and the MCP tool executes correctly.

### 1. Set Up Environment
Ensure you have the required dependencies installed (ideally in your virtual environment):
```bash
pip install fastmcp
# Or using uv:
uv pip install fastmcp
```

### 2. Run Test Client
Make sure the docker containers are running (`docker compose ps`), then run:
```bash
python test_client.py
```
This script will:
1. Connect to the MCP server at `http://localhost:8543/mcp`.
2. Retrieve and print available tools.
3. Call `create_brainrot_video` with a sample script containing wait states, inline SVG images, and a title.
4. Save the compiled video to the `./output/` folder.