# studio-state — MCP server for AI film & video production state

**Keep AI-generated characters, locations, and shots consistent across an entire
project — by giving Claude (or any MCP client) a single source of truth for where
your production stands.**

`studio-state` is a small, stateless [Model Context Protocol](https://modelcontextprotocol.io)
server for people producing **AI-generated film, video, episodic shows, and animation**
with tools like **Higgsfield, Runway, Kling, Seedance, nano-banana, Veo, and ElevenLabs**.
It reads your project's plain files on every call and answers three questions an AI
filmmaking assistant constantly needs to re-establish:

- **`orient`** — *"Where am I right now?"* Project, phase, active episode, budget/spend
  posture, open blockers, next actions, and the scene index — one call instead of a
  50-line copy-paste at the start of every session.
- **`get_shot_status`** — *"What's the state of this scene?"* Per-shot status
  (planned / pending / fired / locked / needs-rework / dropped) reconciled from your
  shot plan, your canonical lock state, and the server's own working notes.
- **`update_shot`** — *"Mark this shot fired/locked and attach the generation job + still."*

It's the free companion tool to **[The Studio Method](#the-studio-method-paid-companion)** —
a complete system for getting **consistent characters and zero-retry continuity** out of
generative video models.

---

## Why this exists

AI generation tools drift. Across a long shoot they hallucinate characters, swap faces,
reinvent backgrounds, and contradict your references — and the human becomes the only
thing holding continuity together. Most of that pain is *state* pain: the assistant
helping you forgets where the production stands the moment a session resets.

`studio-state` fixes the state half structurally. Truth lives in your files, not in a
chat history or a server-side database. Every tool call re-reads the files, so it is
**crash-proof and always current**, and it **never mutates your canonical files** — the
only thing it writes is its own per-scene `shot_status.json` sidecar.

## What makes it safe

- **Read-dominant.** 2 of 3 tools are pure reads. The one writer only ever touches a
  shim-owned sidecar file — your shot plans, render manifests, and state file are never
  modified.
- **Stateless.** No server-side store, no daemon state. Kill it mid-call and nothing
  corrupts (atomic sidecar writes).
- **Path-sandboxed.** Scene/episode arguments are validated — no path traversal out of
  your project tree.
- **Hardened.** Reviewed adversarially across multiple frontier models before release;
  malformed files return structured errors instead of crashing the assistant.

## Quick start

```bash
# 1. Python 3.9+ and the MCP SDK
python3 -m pip install "mcp[cli]"          # add --break-system-packages if needed

# 2. Try it against the bundled demo project (no setup)
python3 tests/test_acceptance.py           # expect: 4/4 checks passed

# 3. Point it at your own project (a folder containing _pipeline/STATE.json + episodes/)
export STUDIO_ROOT="/path/to/your_show"
python3 server.py
```

Then register it in Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "studio-state": {
      "command": "python3",
      "args": ["/abs/path/studio-state-public/server.py"],
      "env": { "STUDIO_ROOT": "/abs/path/your_show" }
    }
  }
}
```

Full walkthrough: [`INSTALL.md`](./INSTALL.md).

## Does my project work with this?

`studio-state` expects a lightweight, file-based project layout:

```
your_show/
  _pipeline/STATE.json                         # project phase, episode, budget, scenes
  episodes/episode_001/scenes/<SCENE>/
    phase_04_IRs.json                          # the shot plan (shot anchors + types)
    phase_05_render_manifest.json              # canonical lock/render state (optional)
```

A complete synthetic example ships in [`examples/demo_project/`](./examples/demo_project) —
copy its shape to adapt your own pipeline, or adopt the full convention via the paid pack
below.

## The Studio Method (paid companion)

This tool tracks state. The hard part — **getting the same character to render
consistently, shot after shot, with near-zero retries** — is a *method*. **The Studio
Method Starter Pack** is the full system: the character/location/camera "bible" templates,
the pre-fire ritual, the prompt-assembly formula, and the anti-default doctrine that make
generative models hold continuity.

→ **Get the Starter Pack:** https://dkf2studios.gumroad.com/l/flplx
*(Use code `EARLY` for the launch discount.)*

## Tools reference

| Tool | Type | Reads | Writes |
|---|---|---|---|
| `orient` | read | `_pipeline/STATE.json` | — |
| `get_shot_status` | read | scene IRs + render manifest + sidecar | — |
| `update_shot` | write | scene IRs (to validate) | `shot_status.json` sidecar only |

## Keywords

AI filmmaking · AI video production · generative video pipeline · character consistency ·
continuity · shot tracking · render manifest · production state · Model Context Protocol ·
MCP server · Claude Desktop · Higgsfield · Runway · Kling · Seedance · nano-banana ·
ElevenLabs · AI short film · AI episodic show · previs · session orientation

## License

MIT © 2026 DKF2 Studios. Contact: dkf2studios@gmail.com