<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.

English • Русская документация • Навигатор агента • Манифест

</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.

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

docker build -t video-editor-mcp:latest .

2. Export / Share with a Friend

# 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):

{
  "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)

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, CLAUDE.md и .agents/skills/video-editor/SKILL.md. Среды разработки (Cursor, Antigravity, Claude Code) считывают их автоматически при открытии проекта.

---

📚 Documentation & Scenario Guides

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

---

📄 License

This project is licensed under the MIT License.