<div align="center">

# 🎬 VE-MCP: Autonomous AI Video Editor

**Model Context Protocol (MCP) Server for automated short-form video montage, Reels, TikTok, SaaS product demos, and localization.**

[![Protocol](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol%20(MCP)-blue.svg)](https://modelcontextprotocol.io/)
[![Python](https://img.shields.io/badge/Python-3.11-3776AB.svg?logo=python&logoColor=white)](https://python.org)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg?logo=docker&logoColor=white)](https://www.docker.com/)
[![FFmpeg](https://img.shields.io/badge/Engine-FFmpeg%20Single--Pass-007808.svg?logo=ffmpeg&logoColor=white)](https://ffmpeg.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

[English](./README.md) • [Русская документация](./docs/README.md) • [Навигатор агента](./docs/INDEX.md) • [Манифест](./docs/INDEX.json)

</div>

---

## ⚡ Overview

**VE-MCP** equips AI agents (Claude Desktop, Cursor, Antigravity, AutoGPT) with professional video editing superpowers. It transforms raw screen recordings, talking-head videos, or raw scripts into published-ready 9:16 vertical videos in **a single high-performance render pass**.

```mermaid
flowchart LR
    A["Raw Footage / Prompt"] --> B["AI Agent + VE-MCP"]
    
    subgraph VE_MCP ["VE-MCP Single-Pass Engine"]
        B --> C["Silence Cutter (auto-editor)"]
        C --> D["Speech-to-Text & Karaoke ASS (faster-whisper)"]
        D --> E["Voicebox / Edge-TTS Voiceover"]
        E --> F["Single-Pass FFmpeg (9:16 + Zooms + EBU R128 Ducking + Subtitles)"]
    end
    
    F --> G["Ready-to-Publish 9:16 MP4 🎉"]
```

---

## 🚀 Key Features

* **✂️ Intelligent Silence Removal (`cut_silence`):** Cuts hesitations, stuttering, and pauses from raw footage using `auto-editor`.
* **🗣️ Voicebox & Edge-TTS Speech Synthesis (`synthesize_speech`):** Native integration with local **Voicebox** (port 17493) with seamless fallback to **Microsoft Edge Neural TTS** (multilingual, zero API keys required).
* **✨ Pause-Aware Karaoke Subtitles (`generate_karaoke_subtitles`):** Word-level highlighted subtitles (`.ass`) rendered with Montserrat and Inter typography. Automatically breaks lines on speech pauses (>0.35s) to eliminate screen sticking.
* **🎨 Professional Color & Light Grading (`adjust_video_color_and_light`):** AI-tunable exposure, contrast, saturation, gamma, sharpness, and color temperature with built-in presets (`vibrant`, `clean_screencast`, `cinematic`, `warm`, `cold`, `high_contrast`).
* **📐 Multi-Format Aspect Ratio Converter (`format_video`):** Single-pass conversion to **9:16** (Reels/Shorts), **16:9** (YouTube Landscape), **1:1** (Square post), **4:5** (Feed) with blurred backgrounds, smart cropping, or letterboxing.
* **📱 9:16 Vertical Formatting (`format_vertical_video`):** High-quality background blur (`blur_background`), center crop, or padded format.
* **👥 Split-Screen SaaS Demo Layout (`format_split_screen_demo`):** Two-tier vertical layout: Speaker on top, application screencast on the bottom with dual-channel audio mixing.
* **🔍 Dynamic Jump-Zooms (`apply_jump_zooms`):** Automated periodic punch-in zooms to boost audience retention.
* **🔊 Broadcast Audio Normalization & Ducking (`add_audio_and_ducking`):** Audio leveled to **EBU R128 (`loudnorm`)** with sidechain compression (background music automatically ducks when speech is active).
* **🎨 Overlays & SFX (`add_visual_overlay_and_sfx`):** Floating badges, logos, and UI callouts with bundled SFX triggers (`pop.wav`, `whoosh.wav`, `click.wav`).
* **🛡️ Automated QA Validator (`validate_video_quality`):** Built-in `ffprobe` verification of 9:16/16:9 resolution, audio stream health, and container integrity.
* **⚡ One-Click Composite Pipelines:** `create_reels_from_raw_video` and `create_promo_from_script` with integrated color grading.

---

## 🛠️ MCP Tools Reference

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `cut_silence` | `input_path, output_path, margin, threshold` | Removes silence and hesitation from raw footage |
| `synthesize_speech` | `text, output_path, voice, speed` | Generates speech via Voicebox or Edge-TTS |
| `generate_karaoke_subtitles` | `media_path, output_ass_path, style, max_pause_sec` | Generates word-by-word highlighted `.ass` subtitles |
| `format_video` | `input_path, output_path, aspect_ratio, mode, color_preset, ...` | Converts to 9:16, 16:9, 1:1, 4:5 + applies color grading |
| `adjust_video_color_and_light` | `input_path, output_path, preset, brightness, contrast, saturation, sharpness, warmth` | AI-tunable exposure, contrast, saturation, sharpness, warmth |
| `format_vertical_video` | `input_path, output_path, mode, color_preset` | Reformats video to 9:16 with blurred background |
| `format_split_screen_demo` | `top_speaker_video, bottom_screencast_video, output_path` | Assembles speaker + screencast split-screen layout |
| `apply_jump_zooms` | `input_path, output_path, zoom_factor, interval_sec` | Adds periodic punch-in zooms for dynamic pacing |
| `add_audio_and_ducking` | `video_path, output_path, voice_path, music_path, music_volume` | Mixes music with speech-driven sidechain ducking |
| `burn_subtitles_to_video` | `video_path, ass_path, output_path` | Hardcodes ASS subtitles using `libass` |
| `add_visual_overlay_and_sfx` | `video_path, overlay_image_path, output_path, start_time, sfx_path` | Adds popups/badges with sound effects |
| `validate_video_quality` | `file_path` | QA tool checking aspect ratio, codecs, and streams |
| `create_reels_from_raw_video` | `input_video, output_video, aspect_ratio, color_preset, background_music, ...` | End-to-end raw footage to Reels pipeline with color grading |
| `create_promo_from_script` | `script_text, background_video, output_video, aspect_ratio, color_preset, ...` | End-to-end script + B-roll to promo pipeline with color grading |


---

## 📦 Quick Start with Docker

### 1. Build the Docker Image
```bash
docker build -t video-editor-mcp:latest .
```

### 2. Export / Share with a Friend
```bash
# Save to tar archive:
docker save video-editor-mcp:latest -o video-editor-mcp.tar

# On friend's machine:
docker load -i video-editor-mcp.tar
```

---

## ⚙️ Connect to AI Assistants

### Claude Desktop / Cursor / Antigravity

Add the following to your MCP configuration file (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "video-editor": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "C:/Projects/my-videos:/data",
        "--add-host=host.docker.internal:host-gateway",
        "video-editor-mcp:latest"
      ]
    }
  }
}
```
*(Replace `C:/Projects/my-videos` with the path to your video workspace on the host).*

### Running Natively with Python (without Docker)
```bash
pip install -r requirements.txt
python server.py
```

---

## 🤖 How AI Agents Automatically Receive Instructions

При подключении сервера ИИ-ассистент получает все регламенты и инструкции **автоматически через 3 встроенных механизма**:

1. **🚀 Нативный MCP Protocol Prompt (`FastMCP instructions`):**
   * В момент подключения клиента сервер `server.py` автоматически передает системный промпт (`SERVER_INSTRUCTIONS`) в `initialize response`. Любой современный клиент (Claude Desktop, Cursor, Antigravity, Cline) сразу понимает дерево решений, пресеты цвета и форматы без ручной настройки.
2. **📖 MCP Resources (`docs://index`, `docs://playbook`):**
   * Сервер предоставляет интерактивные ресурсы с полной базой знаний, которые агент может прочитать через протокол MCP в любой момент.
3. **📂 Репозиторные инструкции (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`):**
   * В корне репозитория созданы файлы [`AGENTS.md`](./AGENTS.md), [`CLAUDE.md`](./CLAUDE.md) и `.agents/skills/video-editor/SKILL.md`. Среды разработки (Cursor, Antigravity, Claude Code) считывают их автоматически при открытии проекта.

---

## 📚 Documentation & Scenario Guides

* **[🧭 Agent Master Index & Decision Tree](./docs/INDEX.md)** — Quick navigation for AI agents.
* **[🤖 Agent Operational Playbook](./docs/AGENT_OPERATIONAL_FLOW.md)** — Step-by-step lifecycle from prompt to QA.
* **[📋 Briefing & Scriptwriting Framework](./docs/00_FRAMEWORK_TZ_AND_PIPELINE.md)** — 5-question user interview & H-V-C formula.
* **[💻 SaaS & Screencast Demos](./docs/01_SAAS_AND_PRODUCT_DEMO.md)** — Product feature demos and changelog promos.
* **[📱 Reels, TikTok & Podcast Highlights](./docs/02_REELS_TIKTOK_SHORTS.md)** — Talking-head editing and viral clip slicing.
* **[🎓 Education & SOP Tutorials](./docs/03_EDUCATION_AND_TUTORIALS.md)** — Converting text guides into videos.
* **[🌍 Localization & Dubbing](./docs/04_LOCALIZATION_AND_DUBBING.md)** — Voicebox translation and archive resizing.
* **[🤝 Sales Outreach & Support](./docs/05_SALES_AND_SUPPORT.md)** — Personalized customer support walkthroughs.
* **[⏰ Cron Automation & CI/CD](./docs/06_AUTOMATION_AND_CRON.md)** — Automated daily news digests and PR previews.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).