# video-shot-breakdown-mcp

An MCP server for the part of video work that happens **before** anything is rendered:
reading a finished clip as a list of shots, and turning that list back into something
you can shoot or generate.

Two tools, no dependencies, standard library only.

## Tools

### `breakdown_shots`

Give it a plain-text shot list and it returns the numbers a director actually argues about:

- shot count, total runtime, average / median / shortest / longest shot
- cuts per minute and the pacing bucket (`very fast` → `slow long take`)
- camera-movement mix (static, push, dolly, handheld, crane, aerial …)
- frame totals when you pass `fps`
- a normalised record per shot: description, duration, movement, lens, lighting, start time

Input is loose on purpose — timecodes, inline `3s` durations, or freeform lines all parse:

```
1. 0:00-0:04 Wide establishing shot, slow push in, golden hour
2. 4s handheld close-up on the operator's hands
3. cut to aerial drone shot over the coastline, 6s
```

### `build_remake_plan`

Takes the same shot list and returns the remake:

- one **generator-ready prompt** per shot (camera movement + framing + description + lighting + look)
- a **camera note** for live-action: slider vs. gimbal vs. shoulder mount, and what to keep constant
- **clip segmentation** — shots longer than `max_clip_seconds` (default 10s) are split into
  generation-sized pieces, so a 24s take becomes 10 + 10 + 4 instead of a failed 24s request
- `text-to-video` vs `image-to-video` per shot, decided by `has_reference_still`
- a clip budget line: *"N clips at ≤10s each cover 1:20 of finished runtime"*

## Install

```bash
pip install video-shot-breakdown-mcp
```

Or run straight from the checkout, without installing:

```bash
PYTHONPATH=src python3 -m video_shot_breakdown_mcp
```

## Register with a client

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "video-shot-breakdown": {
      "command": "python3",
      "args": ["-m", "video_shot_breakdown_mcp"],
      "env": { "PYTHONPATH": "/absolute/path/to/video-shot-breakdown-mcp/src" }
    }
  }
}
```

Cursor / VS Code MCP (`.mcp.json` at the project root) uses the same shape:

```json
{
  "mcpServers": {
    "video-shot-breakdown": {
      "command": "video-shot-breakdown-mcp"
    }
  }
}
```

## Example session

> **You:** break down this shot list and build a remake plan for vertical short-form, 5s clips.
>
> **Tool → `build_remake_plan`**
>
> ```json
> {
>   "target_aspect_ratio": "9:16",
>   "step_count": 3,
>   "generation_clip_count": 5,
>   "estimated_duration_seconds": 14.0,
>   "pacing": "medium (narrative)",
>   "steps": [
>     {
>       "shot": 1,
>       "duration": 4.0,
>       "prompt": "camera push, wide framing, wide establishing shot, golden hour lighting, cinematic",
>       "camera_note": "use a slider or gimbal, keep the move the same speed for the whole take; match the wide framing",
>       "generate_with": "text-to-video",
>       "clips": [{ "segment": 1, "seconds": 4.0, "shots": [1] }]
>     }
>   ],
>   "notes": ["generator budget: 5 clips at <= 5s each cover 0:14 of finished runtime"]
> }
> ```

## Why not just ask a model to describe the video?

Description is the easy half. The hard half is reproducibility: what lens, what move,
what light, and how long each piece may be before a generator starts drifting. This server
keeps that as data — JSON you can diff, version, and feed to the next step — instead of prose.

If you want the frame-accurate version against a real video file (camera movement, lighting,
and the likely production method per shot, with a remake plan attached), that is what
[Rea Video](https://reavideo.pro/) does locally on your own footage. This repo is the
lighter, API-shaped sibling you can wire into an agent.

Downstream, the plan maps cleanly onto two generators:

- [Pavo AI](https://pavoai.app/) — text-to-video and image-to-video with consistent cast, good for the short-drama shots the plan produces
- [Wan 3.0](https://wan-3.io/) — cinematic text-to-video / image-to-video, which is where the segmented 5–10s clips go

## Tests

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

## License

MIT