studio-mcp

The block-method film pipeline as agent-callable MCP tools.

An MCP server that lets an LLM agent drive a full brief → shots → render → QC → cut workflow by calling tools — instead of clicking through generation UIs by hand. Plan-then-generate, never reverse: every shot is planned (type, move, duration) before any pixel is made, and every still is QC'd against a locked look so the piece stays on-model.

Above: one shot from the brief "MARÉA — wordless coastal slow-burn" — planned, rendered on Higgsfield Soul Cinema at 21:9, and passed by the style-drift QC (intent 80 / look 84 / character 90). The agent re-rolls anything that fails.

Why

Single-tool MCP servers (one model, one call) are common. This is the layer above: it orchestrates across your generation stack with a block-method planner and a style-drift QC gate — the part nobody ships.

Related MCP server: atsurae

Three ways to drive it

• As an MCP server — connect to Claude Desktop / Claude Code and the LLM calls the 14 tools directly (stdio, or --transport streamable-http for web clients).

• The web console — a cinematic "grading bay" UI over the server: browse instruments, invoke them from schema-driven forms, stream long renders, and brief the Director (an LLM that drives the instruments for you). Live demo: https://console-pied-eight.vercel.app · console/.

• The orchestration graph — Planner → Generation ⇄ QC → Assembly as an agent graph with retries, human gates, and replayable per-run traces (studio_mcp/orchestration/).

Plus Langfuse tracing + an offline benchmark suite for evaluating the pipeline (eval/). CI runs tests on 3.10–3.12 and builds the package on every push.

Tools (14)

Plan & lock

Render & QC (via Higgsfield CLI)

Assemble & utility

Ground (via creative-rag)

Integration — the studio trio

studio-mcp is one of three interlocking pieces; see INTEGRATION.md.

• ai-content-pipeline skill — the method (block plan → lock → stills → animate → cut). It maps each stage to the studio-mcp tool that executes it and calls craft_lookup to ground prompts.

• studio-mcp (this repo) — the tools that execute the method.

• creative-rag — the cited craft KB behind craft_lookup.

Smoke-test the full chain (skill method → craft_lookup → creative-rag):

python scripts/smoke_chain.py        # needs creative-rag on :8000

Provider-agnostic

The LLM layer talks to any OpenAI-compatible endpoint — Anthropic, OpenRouter, OpenAI, or a local server — chosen entirely through env config. No provider is hard-coded.

cp .env.example .env   # set STUDIO_LLM_BASE_URL / _MODEL / _API_KEY

Install

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Run

studio-mcp        # stdio MCP server

Register with an MCP client (e.g. Claude Code / Claude Desktop):

{
  "mcpServers": {
    "studio": {
      "command": "/path/to/studio-mcp/.venv/bin/studio-mcp",
      "env": { "STUDIO_LLM_API_KEY": "sk-..." }
    }
  }
}

Example flow

plan_shots("MARÉA — wordless coastal slow-burn, 90s", project="marea")
lock_campaign("marea", aspect="21:9", day_stock="Kodak 500T, soft handheld",
              hex_palette=["#1b2a3a","#c8a15a"], elements=["the woman in grey"],
              audio="diegetic SFX only, no music")
# render a still (v1.1) → then:
qc_still("marea", image="assets/shot1.png", shot_id=1)   # pass/fail + fix
assemble("marea")                                         # cut manifest

State lives under STUDIO_ROOT (default ~/studio-projects/<project>/) as plain JSON — human-inspectable, and a clean contract a future console can read.

License

MIT