# OpenMontage with MCP (`openmontage-mcp`)

AI-native creative production runtime with Model Context Protocol (MCP), declarative `CreativeSpec`, headless worker engine, and autonomous agent operating skills.

```text
CreativeSpec → Headless Runtime → Provider Adapters → Telemetry & QA → Verified Deliverables
      ↑                                                                         │
      └───────── Autonomous Agents via MCP (stdio JSON-RPC) ────────────────────┘
```

[![Version](https://img.shields.io/badge/version-0.6.0-blue.svg)](pyproject.toml)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPLv3-purple.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-220%20passed%2C%202%20skipped-brightgreen.svg)](tests/)
[![Interface](https://img.shields.io/badge/interface-CLI%20%7C%20MCP%20%7C%20Python-orange.svg)](#interfaces-cli-mcp--python-api)

---

## Declarations & Lineage

> **Attribution Notice:**  
> This project builds upon and evolves the foundational concepts of [OpenMontage](https://github.com/calesthio/OpenMontage) created by [Calesthio AI Labs](https://github.com/calesthio). We acknowledge the foundational architecture pioneered by upstream OpenMontage: the modular tool registry, multi-provider abstraction, style playbooks, and the Backlot visual board.
>
> **`openmontage-mcp`** was engineered to solve a fundamental limitation of the prior platform: upstream OpenMontage was designed as an **interactive, conversational, human-in-the-loop chat experience** requiring manual step-by-step guidance. `openmontage-mcp` packages and extends the substrate into a **reusable, headless, developer-ready creative production platform** operable programmatically through the Model Context Protocol (MCP), a unified CLI, durable background workers, declarative specifications, and autonomous agent skills.

---

## What is Different from Prior OpenMontage? (Table of Changes & Rationale)

The table below details every major architectural addition and difference between upstream OpenMontage and **OpenMontage with MCP**, along with the architectural rationale (*Why*):

| Area / Capability | Upstream OpenMontage (`calesthio/OpenMontage`) | OpenMontage with MCP (`openmontage-mcp`) | Why This Change Was Made (Architectural Rationale) |
|---|---|---|---|
| **Protocol & Agent Interface** | None. Relied on conversational chat prompts and ad-hoc script execution inside a chatbot turn loop. | **Official Model Context Protocol (MCP) Server:** FastMCP 2.x stdio interface exposing 15 typed tools and 2 resources. | External AI assistants (Claude Desktop, Cursor, Antigravity, custom agents) cannot interact reliably with raw Python scripts or multi-turn conversational prompts. MCP provides a standardized, typed, JSON-RPC interface operating across clean OS process boundaries. |
| **Specification Model** | Conversational prompt iteration; stage-by-stage ad-hoc JSON generation across 6 stages. | **Declarative `CreativeSpec` (`schemas/creative_spec.schema.json`):** Complete production intent declared in a single portable JSON/YAML document. | Interactive prompting does not scale to automated workflows or CI/CD pipelines. A declarative specification makes creative intent version-controllable, diffable, repeatable, and compilable without human chat overhead. |
| **Execution Engine** | Human-guided stage-by-stage progression requiring manual reviews and approvals to advance. | **Headless Production Runtime (`HeadlessProductionRun`):** Deterministic, fully automated execution producing a deliverable from a single command. | Production systems, webhook handlers, and background tasks require headless, unattended execution where a valid spec produces a verified deliverable without conversational stalls. |
| **Worker Reliability & Resume** | In-memory execution. Interrupted runs lost state and had to be restarted from stage 0. | **Durable Worker (`ProductionWorker`, `WorkerJob`):** Bounded scene concurrency, disk-persisted state, and idempotent checkpoint resume. | Media generation is expensive and rate-limited. If scene 4 fails or times out, the worker must preserve completed scenes 1-3 and resume cleanly from the exact failure point without re-paying or re-rendering. |
| **Multi-Variant Campaigns** | Single video production at a time; manual re-prompting for different aspect ratios or cutdowns. | **Campaign Orchestration (`CampaignRunner`, `CampaignSpec`):** Multi-aspect (16:9, 9:16, 1:1) and multi-duration matrix with shared asset caching. | Real-world marketing requires coordinated asset bundles for YouTube (16:9), TikTok/Reels (9:16), and Instagram (1:1). Shared asset caching avoids redundant generation and provides unified campaign cost attribution. |
| **Agent Operating Layer** | Unstructured system prompts mixed with Python implementation details. | **7 Runtime Skills & 4 Role-Scoped Agents:** Strict 9-section schema; agents and skills never import Python code directly. | Separates agent reasoning from execution code. Agents operate the engine strictly via MCP tools and CLI commands, preventing hallucinated methods and avoiding AGPL license entanglement. |
| **Offline & Local Guarantees** | Generation frequently failed or stalled if third-party API keys (ElevenLabs, fal, OpenAI) were missing. | **100% Zero-Key Offline Execution:** Produces a verified, full-frame MP4 deliverable in under 6 seconds using bundled FFmpeg and Piper TTS. | Developers, contributors, and CI systems must be able to run, test, and verify the entire platform immediately upon installation without requiring external cloud accounts or credit cards. |
| **Developer CLI** | Internal `Makefile` targets and scattered `scripts/*.py` files. | **Unified CLI (`openmontage-mcp` / `openmontage`):** 9 standard subcommands with UTF-8 safe Windows/POSIX console handling. | Provides a polished, single-binary feel for developers and automation scripts (`validate`, `run`, `resume`, `status`, `render`, `campaign`, `providers`, `inspect`, `mcp`). |
| **Packaging & Public API** | Non-standard packaging; internal scripts imported from deep directories. | **PEP 517/518 Packaging:** `openmontage-mcp` on PyPI with clean public re-exports (18 stable symbols in `openmontage`). | Allows clean installation via `pip install openmontage-mcp` and provides external applications with a documented, stable API boundary. |
| **Licensing Boundary** | Standard AGPL-3.0 without operational guidance on output or client isolation. | **Explicit Operational Boundary Notice:** Clear IPC isolation documentation; media outputs are explicitly confirmed user-owned. | Clarifies for commercial teams and developers that generated video deliverables are free of copyleft restrictions, and external tools communicating over MCP/CLI do not violate AGPL boundaries. |

---

## What is OpenMontage with MCP?

OpenMontage with MCP is a **headless creative-production runtime** that transforms structured creative specifications into validated media production runs, with deterministic tooling, provider adapters, durable execution, CLI access, Model Context Protocol (MCP) integration, Skills, and role-scoped Agents.

```text
OpenMontage with MCP is NOT:
- another prompt-to-video chat playground
- a single AI model API wrapper
- a SaaS dashboard or web UI
- a replacement for professional NLE editing software (Premiere / DaVinci)

OpenMontage with MCP IS:
- a headless media production engine
- a structured, schema-validated workflow runtime
- an agent-operable execution layer via MCP and Skills
- a programmable creative substrate for automated campaigns and video pipelines
```

---

## Architecture & Dependency Direction

OpenMontage with MCP enforces a strict, unidirectional dependency hierarchy:

```mermaid
graph TD
    subgraph Interfaces["1. Agent and Developer Interfaces"]
        A[Autonomous Agents] --> S[Runtime Skills]
        S --> M[MCP Server - stdio]
        D[Developers and CI] --> C[CLI - openmontage-mcp]
        D --> P[Python API - openmontage]
    end

    subgraph Runtime["2. Production Runtime Engine"]
        M --> R[Runtime Engine]
        C --> R
        P --> R
        R --> Comp[CreativeSpec Compiler]
        R --> Worker[Durable ProductionWorker]
        R --> Camp[CampaignRunner]
    end

    subgraph Execution["3. Tooling and Media Providers"]
        Worker --> PR[Provider Registry - 120 Providers]
        PR --> TTS[TTS: ElevenLabs, Piper, Azure, Google, OpenAI]
        PR --> VID[Video: Seedance, Kling, LTX-2, Wan, Sora, Veo]
        PR --> IMG[Image: FLUX, Imagen, Midjourney, Recraft, SD]
        PR --> MUS[Music: Lyria, ACE-Step, MusicGen, Library]
        PR --> COMP[Composition: Remotion and FFmpeg]
    end

    subgraph QA["4. State and Quality Assurance"]
        Worker --> CK[Checkpoints and State Store]
        Worker --> QAEngine[Technical QA: ffprobe, Audio Normalization]
        Worker --> BACK[Backlot State Observer]
    end
```

### Architectural Guardrails:
1. **Agents and Skills never import Python modules:** Agents interact with the runtime strictly through MCP tools and CLI commands.
2. **Deterministic Composition:** Video rendering is reproducible across FFmpeg and Remotion engines.
3. **External Process Isolation:** External IDEs and client applications communicate across standard OS process boundaries (stdio MCP IPC or subprocess CLI calls).

---

## Quickstart (5 Minutes)

### 1. Installation

```bash
# Standard installation (runtime + CLI)
pip install openmontage-mcp

# With MCP server support (recommended for AI agents)
pip install "openmontage-mcp[mcp]"

# For full local GPU video generation
pip install "openmontage-mcp[gpu]"
```

### 2. Verify Installation (Zero API Keys Needed)

```bash
# Check CLI and version
openmontage-mcp --help

# Inspect available media providers on your machine
openmontage-mcp providers
```

### 3. Validate a CreativeSpec

```bash
openmontage-mcp validate examples/minimal_creative_spec.json
```
```text
✓ Valid CreativeSpec
  version:    1.0
  scenes:     1
  duration:   3.0s
  aspect:     16:9
```

### 4. Execute a Production Run

```bash
openmontage-mcp run examples/minimal_creative_spec.json
```
```text
✓ Production run COMPLETED
  project:    run_1a47cdd9cd56
  output:     projects/run_1a47cdd9cd56/renders/run_1a47cdd9cd56_master.mp4
  duration:   5.7s
```

Your rendered 1080p MP4 deliverable is ready under `projects/`.

---

## The CreativeSpec Contract

A `CreativeSpec` is a self-contained, schema-validated JSON or YAML document declaring the entire production intent.

```json
{
  "version": "1.0",
  "title": "Quantum Computing Explained",
  "aspect_ratio": "16:9",
  "target_duration": 15.0,
  "style": {
    "playbook": "clean-professional",
    "tone": "educational",
    "pacing": "steady"
  },
  "audio": {
    "narration": {
      "voice": "alloy",
      "provider": "piper",
      "rate": 1.0
    },
    "music": {
      "mood": "ambient corporate",
      "volume": 0.15
    }
  },
  "scenes": [
    {
      "id": "scene_1",
      "order": 1,
      "duration": 5.0,
      "narration": "Classical computers compute with bits that are either zero or one.",
      "visual": {
        "type": "motion_graphic",
        "prompt": "Binary bits flipping cleanly on a dark slate background, minimalist typography",
        "style_override": "clean-professional"
      }
    },
    {
      "id": "scene_2",
      "order": 2,
      "duration": 10.0,
      "narration": "Quantum computers use qubits, which can exist as both zero and one simultaneously through superposition.",
      "visual": {
        "type": "still_image",
        "prompt": "Futuristic glowing Bloch sphere showing quantum superposition, 3D render, dark background",
        "motion": "slow_zoom_in"
      }
    }
  ]
}
```

Validate against the official schema at `schemas/creative_spec.schema.json`.

---

## Model Context Protocol (MCP) Server

OpenMontage with MCP exposes 15 typed tools and 2 resources to AI assistants over stdio JSON-RPC.

### Claude Desktop / Cursor / Antigravity Configuration

Add to your `claude_desktop_config.json` or agent configuration:

```json
{
  "mcpServers": {
    "openmontage": {
      "command": "openmontage-mcp",
      "args": ["mcp"]
    }
  }
}
```

### MCP Tool Inventory

| Tool Name | Purpose | Key Inputs | Expected Output |
|---|---|---|---|
| `validate_creative_spec` | Pre-flight validation | `spec_path` | Validation status, scene count, estimated duration |
| `compile_creative_spec` | Compile to canonical brief | `spec_path`, `project_id` | Compiled brief, scene breakdown |
| `start_production_run` | Start background worker | `spec_path`, `project_id` | Job ID, initial state, project dir |
| `resume_production_run` | Resume interrupted run | `project_id` | Resumed state, remaining stages |
| `get_production_status` | Poll live progress | `project_id` | Progress %, current scene, completed assets |
| `validate_campaign` | Validate campaign matrix | `campaign_path` | Variant validation, matrix breakdown |
| `run_campaign` | Execute multi-variant matrix | `campaign_path` | Variant job IDs, total cost attribution |
| `get_campaign_status` | Query campaign status | `campaign_id` | Per-variant progress, aggregated cost |
| `init_project` | Initialize workspace | `title`, `pipeline_type` | Project directory, initialized marker |
| `get_project_status` | Query stage rail state | `project_id` | Completed stages, Backlot board summary |
| `inspect_project` | List assets and media | `project_id` | Artifact inventory, media file paths |
| `list_providers` | Inspect capability matrix | `capability` (optional) | Available providers and requirements |
| `get_provider_capabilities` | Query specific provider | `provider_name` | Max resolution, latency, supported formats |
| `list_artifacts` | List canonical artifacts | `project_id` | Available stage artifacts |
| `inspect_artifact` | Inspect stage artifact | `project_id`, `artifact_type` | Parsed canonical artifact JSON |

---

## Command-Line Interface (CLI)

The package installs `openmontage-mcp`, aliased to `openmontage` and `om-mcp`:

| Subcommand | Usage | Description |
|---|---|---|
| `validate` | `openmontage-mcp validate <spec.json> [--json]` | Validates a CreativeSpec or CampaignSpec without side effects |
| `run` | `openmontage-mcp run <spec.json> [--project-id <id>] [--json]` | Executes a full production run headlessly |
| `resume` | `openmontage-mcp resume <project-id> [--json]` | Resumes an interrupted run from its last completed checkpoint |
| `status` | `openmontage-mcp status <project-id> [--json]` | Reports current state, deliverable paths, and errors |
| `render` | `openmontage-mcp render <project-id> [--json]` | Triggers composition render on an existing project workspace |
| `campaign` | `openmontage-mcp campaign <campaign.json> [--json]` | Orchestrates a multi-variant campaign run |
| `providers` | `openmontage-mcp providers [--json]` | Live table of available vs. unconfigured providers |
| `inspect` | `openmontage-mcp inspect <project-id> [--stage <stg>]` | Inspects artifacts, media files, and event logs |
| `mcp` | `openmontage-mcp mcp` | Launches the FastMCP stdio server for AI agents |

---

## Python API

External Python applications import from `openmontage`:

```python
from openmontage import (
    load_creative_spec,
    compile_creative_spec,
    ProductionWorker,
    CampaignRunner,
    ProviderPolicy,
)

# 1. Load and validate
spec = load_creative_spec("examples/minimal_creative_spec.json")

# 2. Configure provider policy
policy = ProviderPolicy(
    video_preference=["seedance", "kling", "offline"],
    tts_preference=["elevenlabs", "piper"],
    max_budget_usd=10.0,
    allow_fallbacks=True,
)

# 3. Execute with durable worker
worker = ProductionWorker(
    creative_spec=spec,
    project_id="my_video_project",
    policy=policy,
)
job = worker.execute()

print(f"State: {job.state}")
print(f"Deliverable: {job.output_video}")
print(f"Cost: ${job.cost_usd:.4f}")
```

---

## Multi-Variant Campaigns

Produce multi-format asset bundles (e.g. YouTube 16:9 + TikTok 9:16 + Instagram 1:1) from one definition:

```json
{
  "campaign_id": "product_launch_2026",
  "base_spec": "specs/base_launch.json",
  "variants": [
    {
      "variant_id": "youtube_horizontal",
      "aspect_ratio": "16:9",
      "target_duration": 30.0
    },
    {
      "variant_id": "reels_vertical",
      "aspect_ratio": "9:16",
      "target_duration": 15.0
    },
    {
      "variant_id": "feed_square",
      "aspect_ratio": "1:1",
      "target_duration": 15.0
    }
  ]
}
```

Execute via CLI:
```bash
openmontage-mcp campaign examples/campaign_product_launch.json
```

---

## Media Providers (120 Total)

OpenMontage with MCP integrates 120 discovered provider adapters across all media modalities:

- **Video Generation:** Seedance 2.0/2.5, Kling Direct/API, LTX-2.3, Wan 2.2, Sora, Google Veo, Hunyuan Cloud, ComfyUI
- **Text-to-Speech:** ElevenLabs, Piper (offline), Azure Speech, Google Cloud TTS, OpenAI Voice, fish.audio, Doubao
- **Image Generation:** FLUX.2/FLUX.1, Google Imagen 3, OpenAI GPT Image, Recraft, SDXL, ComfyUI
- **Music and Sound:** ElevenLabs Music & SFX, Google Lyria 3, ACE-Step 1.5, MusicGen, Royalty-Free Library
- **Composition:** Remotion (React motion graphics, spring physics) and FFmpeg (offline video stitching, Ken Burns)
- **Analysis:** Faster-Whisper, Azure STT, OpenCV frame sampling, scene detection

Configure API keys in `.env`. Inspect active providers anytime with:
```bash
openmontage-mcp providers
```

---

## Offline-First Guarantee

You can develop, test, and render complete video productions with **zero API keys**:
- **Offline Narration:** Bundled Piper neural TTS or ambient audio fallback.
- **Offline Composition:** Local FFmpeg engine (motion graphics, Ken Burns, audio mixing).
- **Offline Speed:** 1080p MP4 deliverable generated in under 6 seconds on standard CPU.

---

## Testing & Quality Assurance

OpenMontage with MCP maintains a comprehensive regression suite:

```text
220 passed, 2 skipped, 0 failed
```

Run test suites:
```bash
# Run contract tests (CLI, MCP, Skills, Agents)
pytest tests/cli tests/mcp tests/skills tests/agents

# Run runtime regression tests
pytest tests/runtime

# Run provider contract tests
pytest tests/providers
```

---

## Licensing & Operational Boundary

OpenMontage with MCP is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0-only)**.

### Operational & Client Boundary Clarifications:
- **Your Media Deliverables Are Yours:** All video files (MP4s), audio tracks, images, and subtitles created by OpenMontage belong entirely to the operator and are **not** subject to AGPL copyleft restrictions.
- **External IPC / Process Boundary:** Applications communicating with OpenMontage strictly over standard input/output (the MCP stdio protocol) or via CLI subprocesses interact across an external process boundary and do not trigger copyleft requirements on external client code.
- **Direct Linking:** Linking or modifying the internal Python source code (`openmontage`, `lib`, `tools`) in a networked service subjects derivative works to AGPL-3.0 source disclosure.