# Premiere Pro MCP for Antigravity

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Adobe Premiere Pro](https://img.shields.io/badge/Adobe%20Premiere%20Pro-CC%202019--2025%2B-purple.svg)](https://www.adobe.com/products/premiere.html)
[![Node.js Version](https://img.shields.io/badge/Node.js-v18%2B-green.svg)](https://nodejs.org/)
[![Model Context Protocol](https://img.shields.io/badge/Protocol-MCP-blue.svg)](https://modelcontextprotocol.io/)

A production-ready **Model Context Protocol (MCP)** integration and **Adobe CEP 9+ Bridge** that connects **Google Antigravity** (and compatible MCP clients) directly to **Adobe Premiere Pro (CC 2019 through CC 2025+)** on Windows 10/11.

It empowers AI assistants to inspect active video projects, import and organize media, assemble and edit timeline clips, split and trim tracks with sub-frame precision, animate motion/opacity keyframes, and trigger exports directly from natural language.

---

## 📖 Table of Contents
- [What is it & Why Use It?](#-what-is-it--why-use-it)
- [How It Works (Architecture)](#-how-it-works-architecture)
- [Sub-Frame Precision & Tick System](#-sub-frame-precision--tick-system)
- [Safety & Project Backup Protections](#-safety--project-backup-protections)
- [Supported Tools (41 Operations)](#-supported-tools-41-operations)
- [Prerequisites](#-prerequisites)
- [Step-by-Step Setup Guide](#-step-by-step-setup-guide)
  - [Step 1: Clone the Repository](#step-1-clone-the-repository)
  - [Step 2: Install Node Dependencies](#step-2-install-node-dependencies)
  - [Step 3: Enable CEP Developer Mode (PlayerDebugMode)](#step-3-enable-cep-developer-mode-playerdebugmode)
  - [Step 4: Install the CEP Extension](#step-4-install-the-cep-extension)
  - [Step 5: Launch the Extension in Premiere Pro](#step-5-launch-the-extension-in-premiere-pro)
  - [Step 6: Configure Google Antigravity](#step-6-configure-google-antigravity)
- [Verification & Diagnostics](#-verification--diagnostics)
- [Prompt Examples for Antigravity](#-prompt-examples-for-antigravity)
- [Project Structure](#-project-structure)
- [Troubleshooting & FAQ](#-troubleshooting--faq)
- [License](#-license)

---

## 💡 What is it & Why Use It?

Video editing involves thousands of repetitive actions: organizing bins, placing b-roll on the timeline, cutting silences or bad takes, adjusting motion scale and position, and queuing renders.

**Premiere Pro MCP for Antigravity** enables autonomous and pair-editing workflows:
- Antigravity reads timeline markers, sequence frame rates, track layouts, and clip in/out points.
- You can ask Antigravity to organize media bins, assemble rough cuts, sync b-roll over an audio narration track, or razor cut clips at specific timecodes.
- Built-in automatic backup guarantees that your `.prproj` file is backed up before any destructive editing command is executed.

---

## 🏗️ How It Works (Architecture)

Adobe Premiere Pro executes ExtendScript within an ES3 engine that cannot directly import modern Node.js or MCP stdio packages. This project uses a secure, decoupled local bridge architecture:

```text
┌───────────────────────────────────────┐
│     Google Antigravity / MCP Client   │
└───────────────────┬───────────────────┘
                    │  (stdio JSON-RPC 2.0)
                    ▼
┌───────────────────────────────────────┐
│       Node.js MCP Server Process      │
│         (mcp-server/index.js)         │
│  - Input validation & tick conversion │
│  - Automatic .prproj backup creation  │
│  - Loopback token authentication      │
└───────────────────┬───────────────────┘
                    │  (Loopback HTTP: 127.0.0.1:17890, Token Auth)
                    ▼
┌───────────────────────────────────────┐
│       Premiere CEP 9+ Panel           │
│     (com.antigravity.premiere.mcp)    │
│  - Long-polling / dispatch queue      │
└───────────────────┬───────────────────┘
                    │  (window.__adobe_cep__.evalScript)
                    ▼
┌───────────────────────────────────────┐
│   ExtendScript Host + QEAdapter       │
│          (host/premiere.jsx)          │
└───────────────────┬───────────────────┘
                    │  (app.project / Sequence / TrackItem DOM APIs)
                    ▼
┌───────────────────────────────────────┐
│       Adobe Premiere Pro Timeline     │
│   Video & Audio Tracks, FX & Exporter │
└───────────────────────────────────────┘
```

1. **Node.js MCP Server**: Started by Antigravity via stdio. Listens on loopback HTTP port `127.0.0.1:17890`.
2. **Local Token Security**: A 256-bit secure token is created dynamically in `.bridge-state.json`. Every request is authenticated using constant-time comparison.
3. **CEP 9 Extension**: Loaded inside Premiere Pro. It continuously connects to the bridge and executes verified ExtendScript calls inside the project DOM.
4. **QEAdapter**: Isolated QE (Quality Engineering) API wrapper that provides razor splitting and sequence preset creation that are not otherwise exposed in the standard Premiere DOM.

---

## ⏱️ Sub-Frame Precision & Tick System

Premiere Pro calculates time internally in **ticks** (where $1\text{ second} = 254{,}016{,}000{,}000\text{ ticks}$).
- The MCP server includes built-in conversions between seconds, SMPTE timecodes (`HH:MM:SS:FF`), and exact integer ticks.
- This prevents floating-point rounding errors and ensures frame-accurate cuts, trims, and keyframes at any frame rate (23.976, 24, 25, 29.97, 30, 59.94, 60 fps).

---

## 🛡️ Safety & Project Backup Protections

Editing projects can be large and critical. The MCP server integrates built-in safety mechanisms:
- **Automatic Backups**: Commands like `save_project`, `remove_clip`, and destructive timeline edits automatically generate a timestamped `.prproj` backup in a dedicated `_backups` folder before applying modifications.
- **Loopback Enforcement**: Only allows connections from `127.0.0.1`. Network access from other machines or public interfaces is strictly rejected.
- **Whitelist Enforcement**: Only the 41 documented, validated actions can be triggered. No arbitrary command line or eval injection is permitted.

---

## ⚡ Supported Tools (41 Operations)

| Category | Available Tools |
|---|---|
| **System & Health** | `premiere_ping`, `premiere_health_check` |
| **Project & Sequences** | `get_project_info`, `save_project`, `get_active_sequence`, `get_sequence_settings`, `list_sequences`, `create_sequence_from_supported_preset` |
| **Media & Project Items** | `list_project_items`, `import_media`, `search_project_media`, `get_selected_project_items` |
| **Timeline Inspection** | `get_selected_timeline_clips`, `get_track_information`, `get_clip_information` |
| **Timeline Editing** | `place_media_on_timeline`, `move_clip`, `trim_clip`, `split_clip_at_time`, `remove_clip`, `set_clip_enabled` |
| **Effects & Motion** | `list_clip_components`, `list_component_properties`, `read_clip_properties`, `set_supported_clip_property`, `set_motion_position`, `set_motion_scale`, `set_motion_rotation`, `set_opacity`, `set_supported_blend_mode` |
| **Keyframes** | `list_supported_keyframe_properties`, `get_property_keyframes`, `add_property_keyframe`, `update_property_keyframe`, `remove_property_keyframe`, `set_keyframe_interpolation_when_supported` |
| **Export & Encoder** | `get_export_capabilities`, `validate_export_settings`, `export_active_sequence`, `get_export_status`, `cancel_export_when_supported` |

---

## 📋 Prerequisites

- **Operating System**: Windows 10 or 11 (64-bit)
- **Adobe Premiere Pro**: CC 2019 (v13.x), CC 2020, CC 2021, CC 2022, CC 2023, CC 2024, or CC 2025+
- **Node.js**: Node.js 18.x or later installed
- **MCP Client**: Google Antigravity, Claude Desktop, or Cursor

---

## 🚀 Step-by-Step Setup Guide

### Step 1: Clone the Repository
Open PowerShell or Command Prompt:
```powershell
git clone https://github.com/okaybhargav/Premiere-Pro-MCP-for-Antigravity.git "C:\MCP\Premiere pro MCP"
cd "C:\MCP\Premiere pro MCP"
```

### Step 2: Install Node Dependencies
```powershell
npm install
```

### Step 3: Enable CEP Developer Mode (PlayerDebugMode)
In PowerShell, enable `PlayerDebugMode` so Premiere Pro allows local developer CEP extensions:
```powershell
# Enables debug mode for CSXS 9 through 16 (covers CC 2019 through 2025+)
9..16 | ForEach-Object { reg add "HKCU\Software\Adobe\CSXS.$_" /v PlayerDebugMode /t REG_SZ /d 1 /f }
```

### Step 4: Install the CEP Extension
Run the included PowerShell installer:
```powershell
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
```
This deploys the extension to:
`%APPDATA%\Adobe\CEP\extensions\com.antigravity.premiere.mcp`

### Step 5: Launch the Extension in Premiere Pro
1. Open **Adobe Premiere Pro**.
2. Open or create a project.
3. In the top menu, go to: **Window** > **Extensions** > **Premiere MCP Bridge**.
4. The extension window will open and display connection status. Once the MCP server runs, it turns **Green (Connected)**.

### Step 6: Configure Google Antigravity
Open your Antigravity MCP configuration file:
- File path: `C:\Users\<YourUsername>\.gemini\config\mcp_config.json`

Add the `premiere-pro` server entry under `mcpServers`:

```json
{
  "mcpServers": {
    "premiere-pro": {
      "command": "node",
      "args": [
        "C:\\MCP\\Premiere pro MCP\\mcp-server\\index.js"
      ]
    }
  }
}
```
*(Make sure to adjust the path if your repository is placed in a different folder).*

Restart Antigravity or refresh MCP tools.

---

## 🔍 Verification & Diagnostics

Run the automated diagnostic and test scripts to verify the bridge:

```powershell
# 1. Environment & registry diagnostic check
powershell -ExecutionPolicy Bypass -File scripts\diagnose.ps1

# 2. Automated unit and mock tests
npm test
```

---

## 💬 Prompt Examples for Antigravity

- *"Inspect the active sequence and list all clips on Video Track 1 and Audio Track 1."*
- *"Import media files from 'C:\Media\Footage' into a new bin called 'RawFootage'."*
- *"Place 'clip_01.mp4' on Video Track 1 at time 00:00:05:00 and trim it to 10 seconds duration."*
- *"Razor split the clip on Video Track 1 at timecode 00:00:12:15."*
- *"Select the first clip on Video Track 1 and scale it down to 80% while moving it to the top-right corner."*
- *"Animate opacity from 0% to 100% between seconds 0 and 1.5 to create a fade-in."*
- *"Export the current sequence using preset 'YouTube 1080p Full HD' to 'C:\Exports\FinalEdit.mp4'."*

---

## 📁 Project Structure

```text
Premiere-Pro-MCP-for-Antigravity/
├── cep-extension/
│   ├── CSXS/manifest.xml         # CEP 9.0+ manifest (CSXS version definitions)
│   ├── host/premiere.jsx         # ExtendScript host + JSON polyfill + QEAdapter
│   ├── index.html                # Panel UI (status, command queue, debug logs)
│   ├── panel.js                  # CEP bridge polling client
│   └── styles.css                # Premiere Pro dark theme styling
├── mcp-server/
│   ├── index.js                  # MCP stdio server entry point
│   ├── bridge.js                 # Local 127.0.0.1:17890 HTTP bridge with token auth
│   ├── tools.js                  # 41 MCP tool definitions, schemas, and handlers
│   └── validation.js             # Strict input validation and tick/timecode math
├── scripts/
│   ├── install.ps1               # Deploys CEP extension to %APPDATA%
│   ├── diagnose.ps1              # Full environment, registry, and bridge diagnostic
│   └── uninstall.ps1             # Clean uninstallation script
├── tests/
│   ├── bridge.test.js            # Loopback HTTP server and token auth tests
│   └── validation.test.js        # Parameter validation and tick math tests
├── package.json                  # Node dependencies and test scripts
├── .gitignore                    # Excludes node_modules and bridge runtime state
├── LICENSE                       # MIT Open-Source License
└── README.md                     # Documentation
```

---

## ❓ Troubleshooting & FAQ

### 1. Panel is blank or shows "Extension could not be loaded"
- **Fix**: Confirm you ran the `PlayerDebugMode` command for your CSXS version in Step 3. Restart Premiere Pro.

### 2. Panel status says "Connecting..." but doesn't turn green
- **Fix**: The panel connects when the Node MCP server is running. Ensure Antigravity is active and has registered `premiere-pro` in `mcp_config.json`. You can also manually test the bridge by running `node mcp-server\index.js` in a command prompt.

### 3. Razor splitting fails
- **Fix**: Razor cutting utilizes Premiere's internal `QEAdapter`. Ensure Premiere Pro has an active sequence open and that the track containing the clip is not locked or targeted incorrectly.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE) - free for personal and commercial open-source use.