architecture

The package

Four buckets, one Python package.

CutMaster is maximum-control by design. The full DaVinci Resolve Scripting API exposed as MCP tools, plus deterministic workflow compounds, plus AI-enhanced features, plus an optional React workflow panel — all from one Python package, with a stable plugin contract for closed-source extensions.

This page describes the architecture so you can decide whether to build on it or fork it.

Three deliverables, one repo

Deliverable

What

Consumer

cutmaster-ai

MCP stdio server

Claude Code / Desktop / Cursor / any MCP client

cutmaster-ai-panel

HTTP / SSE server on 127.0.0.1:8765

The React workflow panel

Resolve Workflow Integration plugin

Thin wrapper that opens the panel inside Resolve

DaVinci Resolve Studio 18.5+

The MCP server and the panel backend share the same Python package — adding a feature once makes it available on both surfaces.

The layer model

DIAGRAM

Claude Code stdio MCP

React Panel HTTP+SSE

Resolve Plugin wraps panel

▼

src/cutmaster_ai/

Kernel config.py · resolve.py · errors.py · constants.py

tools/ atomic Resolve ops · no logic

workflows/ deterministic compounds · no LLM

intelligence/ stateless LLM tools

cutmaster/ (AI product) 6 subpackages, stateful · CutMaster panel pipeline

http/ FastAPI panel backend

▼

DaVinci Resolve Scripting API

┌──────────────────────────────────────────────────────────────┐
│  CONSUMERS                                                    │
│  Claude Code   ·   React Panel   ·   Resolve Plugin          │
│  (stdio MCP)       (HTTP+SSE)        (wraps panel)           │
└────────────────┬─────────────────────────────────────────────┘
                 ▼
┌──────────────────────────────────────────────────────────────┐
│  src/cutmaster_ai/                                            │
│                                                                │
│  Kernel:    config.py · resolve.py · errors.py · constants.py │
│                                                                │
│  ┌────────┐  ┌──────────┐  ┌──────────────┐                  │
│  │ tools/ │  │ workflows│  │ intelligence/│                  │
│  │ atomic │  │ /compound│  │  stateless   │                  │
│  │ Resolve│  │ no LLM   │  │  LLM tools   │                  │
│  │ ops    │  │          │  │              │                  │
│  └────────┘  └──────────┘  └──────┬───────┘                  │
│                                   │                            │
│  ┌─────────────────────────────┐  │                            │
│  │  cutmaster/  (AI product)   │◄─┘                            │
│  │  6 subpackages, stateful    │                                │
│  └────────────┬────────────────┘                                │
│               ▼                                                  │
│  ┌─────────────────────────────────┐                            │
│  │  http/  (FastAPI panel backend) │                            │
│  └─────────────────────────────────┘                            │
└────────────────┬─────────────────────────────────────────────┘
                 ▼
        DaVinci Resolve Scripting API

The four-bucket responsibility model

Every feature fits exactly one bucket. This is the rule we use to decide where new code goes — and why CutMaster looks structurally different from "yet another MCP server."

Bucket

Rule

Example

Atomic Resolve op

One function = one Resolve SDK call = one MCP tool. No logic. tools/

cutmaster_add_node
cutmaster_set_cdl

Deterministic compound

Chains atomic ops. No LLM. workflows/

cutmaster_quick_assembly
cutmaster_setup_log_grade

Stateless LLM tool

One MCP call → one LLM roundtrip → one answer. intelligence/

cutmaster_analyze_frame
cutmaster_color_assist

Stateful AI product

Owns state, multi-stage pipeline, optionally its own transport. cutmaster/

The whole CutMaster panel flow

This is what keeps the codebase navigable as it grows: each bucket has a clear test matrix (atomic = mock the SDK, compound = mock atomics, intelligence = mock the LLM, product = end-to-end fixtures), each has a clear scaling profile, and each can have its own plugin surface.

The plugin contract

CutMaster is not just an MCP server — it's a plugin host. Two pyproject.toml entry-point groups let third-party packages register capabilities into a running CutMaster without touching OSS code:

[project.entry-points."cutmaster_ai.tools"]
my_plugin = "my_plugin:register_tools"

[project.entry-points."cutmaster_ai.panel_routes"]
my_plugin = "my_plugin:register_routes"

Third-party closed-source plugins register via these same entry points — there's no special path for first-party code. If you ship a plugin, you use the same surface OSS does.

The full contract — registration signatures, route conventions, stable Python imports, migrations — is in SURFACE.md ↗. It's versioned: breaking changes require a major bump and a CHANGELOG entry, machine-verified per PR.

Why this matters

If you're considering building your own MCP server for Resolve:

The atomic layer alone took us months. The Scripting API has hundreds of methods, lots of phantom calls (functions that exist but raise on invocation), and platform-specific quirks. Wrapping it once is a real cost.
The compound layer is where bugs hide. "Quick assembly" looks like one thing; it's actually six SDK calls in the right order with the right error handling. Doing this for every compound across ingest / conform / grading / delivery is the "real" workload.
The plugin contract was harder than it looks. Versioning a public surface, snapshot-testing it, and keeping it stable across renames is what makes building on top of CutMaster safe.

If you're going to wrap the Resolve Scripting API anyway, fork CutMaster instead and contribute back. If you have a niche, ship it as a plugin.

Deeper reading

docs/ARCHITECTURE.md ↗ — full architecture write-up, package layout, four-bucket rules with edge cases.
SURFACE.md ↗ — the stable plugin / embedding contract.
docs/CONTRIBUTING.md ↗ — how to land code in the right bucket.