Control DaVinci Resolve with AI

DaVinci Resolve MCP Server

English | 简体中文

A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.

A local browser control panel ships with the server for inspecting Resolve state, running source-safe analysis, drilling into analyzed clips and shots, and editing analysis output inline. See the Control Panel Guide for the full tour.

Quick Start

npx davinci-resolve-mcp setup

Before connecting, open DaVinci Resolve Studio and set Preferences > General > External scripting using to Local. (On the free edition that preference does not help - see Free edition below.) The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, Codex CLI, and JetBrains IDEs.

For source installs:

git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
cd davinci-resolve-mcp
python install.py

For platform paths, client-specific config, and manual setup, see Installation and Configuration.

The installer and server check the latest GitHub release for MCP updates. Checks are best-effort and throttled; the server never blocks MCP startup for a prompt. The installer can prompt, snooze, ignore a release, disable checks, or apply an opt-in safe auto-update for clean git checkouts.

Free edition (in-app bridge)

Blackmagic gates external scripting to Studio: on the free edition scriptapp("Resolve") refuses a foreign process, whatever the preference says. Through Resolve 21.0.x the Workspace ▸ Scripts menu was not gated - a script launched from it is handed the live resolve object (measured on free 21.0.3.7) - so the server can reach the free edition through a small script that runs inside Resolve and re-exports it over an authenticated loopback listener. Resolve 21.1 moved Python scripting to Studio. On free 21.1 the Scripts menu no longer lists .py files at all (reported on Fedora 44 in #203; a Lua script in the same folder lists normally). Whether the Console still runs Python there is unconfirmed, so treat the bridge as a 21.0.x path until that is measured.

python scripts/install_resolve_bridge.py
# restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge

The installer and MCP client use ~/.config/davinci-resolve-mcp/bridge.json by default. To keep the authenticated bridge config elsewhere, set DAVINCI_RESOLVE_BRIDGE_CONFIG while running the installer and in the MCP client environment; both sides will use that path.

Once that listener is running it is used automatically whenever external scripting is unavailable - no environment variable required. Setting DAVINCI_RESOLVE_BRIDGE=1 forces the bridge instead: it becomes the only transport tried, so a bridge that stops answering reports its own fault rather than quietly falling back to another transport. Use it when the bridge is the path you intend to depend on.

On macOS, Resolve looks for Python 3 in exactly two places: the PYTHON3HOME environment variable, then /usr/local/bin/python3. Homebrew, pyenv, uv and conda land in neither, so the script silently never appears in the menu. A python.org install works because its installer creates /usr/local/bin/python3 - but you do not need one: point Resolve at the interpreter you already have, no sudo required.

launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"

Use launchctl setenv, not export - Resolve is launched from the Dock and never sees your shell's environment. Restart Resolve afterwards. A Lua canary is installed alongside so you can tell "Python not detected" apart from a wrong folder.

Two things that bite (#182). The prefix must contain both lib/libpython3.X.dylib and bin/python3 under that exact unversioned name - Homebrew's framework builds often ship only bin/python3.13, which is half a Python as far as Resolve is concerned, and the installer's preflight now says so instead of reporting a usable prefix. And launchctl setenv does not survive a reboot; if scripts stop listing weeks later with no error, that is why. For something persistent, put an interpreter where Resolve already looks (this one needs sudo, and check that /usr/local/bin does not precede your normal Python on PATH):

sudo ln -s "$(command -v python3)" /usr/local/bin/python3

Validated on free 21.0.3.7 and Studio 19.1.3.7, both macOS. The Windows paths added in v2.70.1 (issue #106) shipped unverified; reports on free 21.0.1.11 (issue #109) and free 21.0.3.7 (issue #112) have since shown the bridge installing, listing and serving from both %PROGRAMDATA% and %APPDATA% on Windows 11, so those paths are now confirmed rather than assumed. Linux is confirmed as well: a report on free 20.3.2.9 (issue #129, Fedora 43) shows the bridge installing to ~/.local/share/DaVinciResolve/Fusion/Scripts/Utility, listing against the system Python - Linux has none of this discovery problem - and serving end-to-end. No platform now rests on an assumption: macOS was validated directly, Windows and Linux on user reports.

Note that the bridge holds its port for as long as it serves. Before v2.70.3 a Windows bridge could outlive Resolve and block the next session's listener; if you are on an older build and a bridge stops answering, check for a stale fuscript.exe still holding the port.

This is the documented in-app path, not a licence circumvention, but Blackmagic could close it - treat it as a supported-until-it-is-not tier. Loopback only, HMAC-signed requests, one-use nonces.

Local Control Panel

Launch the single-user local control panel from the repository root:

venv/bin/python -m src.control_panel

The command starts a loopback-only server and opens the control panel in your browser at a URL that carries a per-launch access token (http://127.0.0.1:8765/#token=…) - use that exact URL; the panel refuses requests without it. To have an AI coding agent do this, ask: "Open the Resolve MCP control panel for this repo." Agents should use venv/bin/python -m src.control_panel unless your Python environment is already active. Persisted analysis jobs refresh the local search index automatically after successful slices; the manual Build Index action is for rebuilding from existing reports.

Server Modes

The compound server is recommended unless you specifically need the granular one-tool-per-method surface.

Advanced server - beyond the scripting API (optional, Node)

The same package ships a second, optional MCP server: davinci-resolve-advanced-mcp (bin bin/davinci-resolve-advanced-mcp.mjs). Where the Python server drives a live Resolve over the sanctioned scripting API, the advanced server does what the API can't - it reads and edits Resolve files (.drp / .drt / .drx) and applies DB/XML-level changes with no Resolve running, so it runs cloud or local. 18 tools: drp, drt, drx (per-clip grade codec plus a deterministic, offline grading/QC catalog - within-camera + cross-camera skin (v2 skin-line metric) + b-roll + neutral-patch WB matching, match-to-reference, saturation/black-balance, contrast-normalize, ASC CDL import, lossless grade-transfer + season-look authoring, named-LUT attach, scope reads + intent tags, verify-grade, display-referred frame extraction, broadcast-legal QC), offline_ref, conform (frame-oracle conform/relink QC + lineage), color_trace (carry grades across a re-conform), fusion, audio_plan, fairlight (bus routing), audio, project_read, project_db, pipeline (a DB-as-truth pipeline: compile YAML project specs into a canonical SQLite DB, then run stages with gates, provenance, and intent↔actual drift detection), capabilities, deliverable (deliverable QC / compliance), media (media front-end / AE ingest), editorial (editorial integrity / changelist), provenance (provenance / audit / episode report). It can also be consumed as a library (importable engine API), not just spawned as a server.

DRX grade writes are live-calibrated against Resolve Studio: grade params take Resolve's on-screen panel units by default (space: 'ui' | 'drx'), and the structural writes (power windows, qualifiers, HDR zones, HSL curves, ColorSlice, blur/key/motion-effects) are panel-readback-verified - per-control status in resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md. It also closes a UI-only gap: programmatic "Cleanup Node Graph" (drx relayout for one clip, project_db relayout_node_graphs for a whole project) - node layout tidied, grade content byte-preserved.

Add it alongside the live server (both ship in one npm install):

{
  "mcpServers": {
    "davinci-resolve": { "command": "<python>", "args": ["<path>/src/server.py"] },
    "davinci-resolve-advanced": { "command": "node", "args": ["<path>/bin/davinci-resolve-advanced-mcp.mjs"] }
  }
}

install.py prints both entries. The core is pure-JS/MIT with no required native modules; a few features need user-installed tools (ffmpeg for audio, sharp/better-sqlite3 for some paths) - call the capabilities tool for live status and install hints.

Unlike the Python server, this one has Node dependencies. npx davinci-resolve-mcp setup installs them into the managed install (npm install --omit=dev --omit=optional under resolve-advanced/) and only then registers the bin. If that install could not run - offline, or npm unavailable - setup registers an npx command for the advanced server instead, so the entry it writes always boots. To repair an existing install without re-running setup: npx davinci-resolve-mcp sync.

Bradford Post Assistant - managed application (closed beta)

The maintainers also build Bradford Post Assistant, a desktop application on top of this open foundation. Where the MCP servers give an agent hands, Post Assistant is the working copilot around them - an on-device AI assistant for post-production where client material never leaves the workstation:

• A post-production copilot - a desktop app that sits alongside DaVinci Resolve and watches the session live (timeline, grades, and frames - not just API calls), with an embedded AI assistant and agent runtime, local media analysis (transcription, frame analysis, editorial intelligence), and in-app conform QC.
• Memory - persistent, encrypted on-device assistant memory plus cross-episode learning mined from your pipeline's decoded facts (season-look drift, per-camera correction priors, hero-frame libraries, conform path-map reuse), with accumulation managed for you and a reviewed-insight workflow.
• Self-contained by design - Post Assistant wires everything itself: this MCP for Resolve control, the Bradford API for its extended services, and your choice of LLM provider. Nothing to configure by hand, no separate clients to manage, and the app keeps itself (and its bundled MCP) current with signed auto-updates.
• An extended professional toolset - grade surgery on live projects, 22+ adaptive grade families, a curated looks library, delivery-spec validation, editorial pacing/cleanup analysis, natural-language color direction, and Fusion composition authoring - delivered through the managed Bradford API.
• Production workflows - the raw tools composed into finished, real-world flows (turnover → conform → QC → delivery, season-look carry, episode reporting) with the guardrails and approvals a client-facing shop expects.

It is currently in closed beta - you can request access at bradfordoperations.com/software/post-assistant. The open-source servers are complete and fully functional on their own.

What You Can Do

"List all projects and open the one called 'My Film'"
"Create a timeline called 'Assembly Cut' from all clips in the current bin"
"Build a multicam prep timeline from selected camera angles and preserve source media"
"Detect 2-pops or slate claps and suggest record offsets for sync prep"
"Publish analysis summaries, keywords, people, and slate hints into Resolve clip metadata"
"Probe this timeline for gaps, overlaps, missing media, and source frame ranges"
"Safely import this image sequence, organize it into bins, and normalize clip metadata"
"Build a ProRes 422 HQ render plan, validate the settings, and queue the job"
"Copy review markers from the timeline to the selected clip and export a review report"
"Snapshot this clip's grade, validate a CDL update, and export a temp LUT"
"Create a Fusion TextPlus overlay on the selected clip and verify graph connections"
"Report audio channel mappings, voice isolation availability, and subtitle support"
"Install this MCP-marked DCTL or script, classify refresh/restart needs, then remove it"

Core Capabilities

Operation envelope

Every compound tool return carries an _operation block beside its payload, so an agent reads one shape instead of a different key per tool: status (success / partial / blocked / failed), verification (with contradiction kept distinct - Resolve reported success and the readback disagreed), changes (the semantic delta), warnings, and an execution_id.

Two absences are meaningful and deliberate. verification.status: "unverified" means no evidence was reported, not "checked and clean". A missing changes means the action did not report a delta, not that nothing changed - an empty {} there would be a confident, wrong answer about an edit that simply never declared one.

The envelope is namespaced rather than merged into the top level because status, operation, warnings, result and changes are all already domain keys here; flattening would rewrite a background job's status: "done" and a confirm gate's status: "confirmation_required". setup(action="set_defaults", params={"result_envelope": "pure" | "legacy"}) changes the shape, per call via params={"envelope": ...}, per process via RESOLVE_MCP_RESULT_ENVELOPE.

Agent execution traces ("Why did the editor do this?")

Multi-step AI operations correlate across tool calls into unified execution traces. Each trace aggregates tool durations (duration_ms), call counts, cumulative semantic deltas (items_deleted, items_added), and readback verifications. Agents and editors can inspect workflows via resolve_control: get_execution_trace(execution_id?), list_recent_executions(), or open a scoped execution with begin_execution(request="...") / end_execution(). export_execution_report(execution_id?, format="markdown"|"json") writes a reviewable audit artifact with the same summary, defaulting to logs/execution-reports/<execution_id>.md. path writes it anywhere you want it instead - alongside a conform in a dated TransferFiles folder, say - and creates the directories to get there, so check the path before you send it. An existing file is never replaced without overwrite: true. inspect_operation(tool?, target_action?, target_params?) evaluates pre-flight risk level (low, medium, high, critical), destructive potential, and blast radius (item, track, timeline, project, system) before taking action, while list_lifecycle_hooks() inspects active execution interceptors.

It is a heuristic over action names, not a simulation - it never touches the project and does not validate your parameters, so recognised: false means the levels are defaults rather than a finding, and snapshot_available: null means rollback availability was not determined rather than absent. Every shipped hook observes; none replaces a tool's result, so dry_run always reaches the real handler and nothing synthesises a preview for an action that has none.

A report for a run where nothing was verified says "not established - no checks recorded", not "passed". Absence of evidence is a question still open, and an audit document is the last place to let a reader read it as an all-clear.

Traces live in a 100-entry in-memory ring and are appended to logs/execution-traces.jsonl beside server.log - RESOLVE_MCP_TRACE_FILE moves it, and RESOLVE_MCP_LOG_FILE moves server.log itself (a path, or empty for no file; the offline test suite points it at a temporary file so it never writes into the operator's log). list_recent_executions reports that path and whether it is writable, so "the log is empty" and "nothing is being written" are distinguishable without reading the source. What is recorded is tool name, action, timing, status, semantic deltas and verification - no parameters and no file paths. The one free-text field is the request you pass to begin_execution, so treat it the way you would a commit message on a client project.

Verified-Trap Guard

src/utils/api_truth.py records behaviours of the Resolve API that were measured against a live build rather than read off a signature - calls that return True having done nothing, settings keys silently rejected, methods that are not there at all. That ledger used to be pull-only: it answered resolve_control(action="api_truth") and was otherwise a file nobody greps in the middle of a job.

It now reaches the caller at the callsite. An action mapped to a symbol with a recorded fact carries a compact known_limitation on its result - symbol, reality, recommendation, and nothing else, because response weight is a real cost on a long grading session and the full entry is one lookup away.

A fact is only attached when the mapping names that exact symbol. Nothing is inferred from a similar name: an unrelated explanation stapled to a failure reads as a diagnosis, and a wrong diagnosis is worse than none.

One behaviour refuses rather than warns. TimelineItem.CopyGrades replaces the target's grade wholesale - measured by baking each state to a 33-point LUT and comparing bytes - returns True while doing it, and creates no version to go back to. Applied to clips carrying hand-work, that is unrecoverable loss reported as success. So actions that call it refuse until the caller passes acknowledge_trap: true:

{
  "success": false,
  "error": "'timeline_item_color.copy_grades' is refused: its verified behaviour destroys existing work that cannot be recovered afterwards.",
  "known_limitation": [{"symbol": "TimelineItem.CopyGrades", "reality": "...", "recommended": "..."}],
  "retry_with": {"acknowledge_trap": true}
}

The intent is not to forbid the operation - it is to make the caller say out loud that they know what it does. Dry runs are exempt: a preview destroys nothing.

Set RESOLVE_MCP_DISABLE_TRAP_GUARD=1 to turn both the refusal and the advisory push off. This is a behaviour change for callers that previously received a bare {"success": true} from a destructive copy.

Facts that power a refusal must stay re-measurable, so a live probe re-derives each one and records drifted when Resolve stops agreeing; a test fails if a destroys_prior_work entry has no probe.

Optional Extras

The core install is deliberately small: Python, ffmpeg, and the Resolve scripting API. Some features need more, and each one refuses honestly with its own install line rather than degrading into a guess - a fabricated tempo or an invented level produces confident, wrong output, which is worse than no feature.

Run python scripts/doctor.py to see which of these you have.

media_analysis action capabilities reports the analysis stack in detail and tells you what each missing piece would enable.

Nothing here is bundled. Model weights carry their own licences separate from the code that loads them; check them before commercial use.

What This Does Not Do

Knowing where a tool stops is worth as much as knowing what it does, and it is cheaper to read it here than to discover it mid-project.

Anything analyzed but unverifiable is reported as unverified, never folded into "fine". An empty result means "nothing found", never "nothing to find".

Source Media Safety

This project treats camera originals and source media as immutable. Analysis tools read source files and write reports only to sidecar, scratch, or project analysis directories; confirmed metadata publishing writes only to Resolve's project database. The server must not modify, transcode, proxy, or create derivatives of source media unless the user explicitly asks for that. See Media Analysis Guide for the detailed source-safe workflow.

Security Posture

The default server is a local stdio process launched by your MCP client; it does not expose a network listener or built-in multi-user auth surface. The two opt-in local HTTP surfaces - the control panel and the networked MCP transport - bind loopback only and require a per-launch bearer token on every request, with Host/Origin checks against DNS rebinding and CSRF. Tool metadata includes MCP client-safety hints for read-only, destructive, idempotent, and external-resource operations. Destructive writes on both servers honour destructive.safe_mode and the security audit log; only the compound server archives a timeline before mutating it - granular writes are refused or recorded, never recovered. See Security Policy for operational boundaries, confirmation guidance, and vulnerability reporting.

Key Stats

For method-by-method status, see API Coverage and Test Results. For current workflow support, see Kernel Action Coverage.

analyze_media executes directly by default, persists inspectable reports/artifacts under the analysis root, requests host-chat visual analysis via the host_chat_paths protocol (analyze returns absolute frame paths + a JSON schema; the host chat reads each frame as an image and calls media_analysis(action="commit_vision", ...) to finalize), runs transcription through the configured local backend, and writes analysis summaries plus source-time Media Pool clip markers back to the Resolve project. Pass include_visuals=false, include_transcription=false, publish_metadata=false, timed_markers=no, or dry_run=true only when you want to opt out of those default behaviors. Skipping commit_vision leaves the run in pending_host_vision_analysis - surfaced as a failure mode, not silently downgraded.

Documentation

Extension authoring references live in docs/authoring. Resolve developer-package notes live in docs/notes and docs/integrations. Prompt recipes live in examples.

Requirements

• DaVinci Resolve 18.5+ on macOS, Windows, or Linux. Studio supports external scripting directly. The free edition does not - Blackmagic gates external scripting to Studio - but it is still reachable through the in-app bridge, which runs inside Resolve from the ungated Workspace ▸ Scripts menu.
• Python 3.10+ (3.10-3.12 is the lowest-risk range). Python 3.13/3.14 also work on recent Resolve builds (verified on Studio 20.3.2); older builds may fail to connect on 3.13+, in which case use 3.10-3.12.
• Resolve external scripting set to Local (Studio). On the free edition this preference has no effect - use the in-app bridge instead.

Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+. They are live-tested on Studio 21.0.2.4 - see the Resolve 21 delta. Note that AnalyzeForIntellisearch, AnalyzeForSlate and GenerateSpeech each require a separately-downloaded AI Extras pack, and Resolve reports a missing pack inconsistently (some return False, others an error string), so these actions report success: false with the Resolve-supplied reason rather than guessing.

Reporting Bugs and Requesting Features

Tell your assistant "send this as a bug" or "send this as a feature request". It drafts a GitHub issue from the conversation, including the failing call and its error, and attaches the server version, Resolve build, connection mode and OS. Local paths, your username and anything that looks like a secret are redacted. Nothing is filed for you: you get a prefilled link, review the draft, and submit it on GitHub yourself. You can also open an issue directly.

Development

python src/server.py          # Compound server
python src/server.py --full   # Granular server
venv/bin/python tests/test_import.py
venv/bin/python scripts/audit_api_parity.py

Release and validation rules are in docs/process/release-process.md. AI agents working in this repository should start with AGENTS.md; Claude Code users can also read CLAUDE.md, which points to the same canonical instructions.

Author

Samuel Gursky (samgursky@gmail.com)

• GitHub: github.com/samuelgursky

scripts/install_resolve_bridge.py

"""Install the bridge (or just the host-model probe) into Resolve's Scripts folder.

    python scripts/install_resolve_bridge.py --probe-only    # settle the host model first
    python scripts/install_resolve_bridge.py                 # probe + bridge launcher

Deploys to every applicable macOS/Windows/Linux location, including the sandboxed
App Store container used by the free edition — which is why the free edition can
be installed alongside a direct-download Studio without either disturbing the other.

Nothing is started here. Resolve must be restarted after installing so it
re-scans the Scripts folders, and the script is then run from
**Workspace ▸ Scripts**.
"""

from __future__ import annotations

import argparse
import base64
import json
import os
import secrets
import shutil
import sys
from pathlib import Path

REPO = Path(__file__).resolve().parent.parent
DEFAULT_CONFIG_PATH = Path.home() / ".config/davinci-resolve-mcp/bridge.json"
ENV_CONFIG_PATH = "DAVINCI_RESOLVE_BRIDGE_CONFIG"
DEFAULT_PORT = 49632


def config_path() -> Path:
    """Bridge config written by this installer and read by the MCP client."""
    override = os.environ.get(ENV_CONFIG_PATH)
    return Path(override).expanduser() if override else DEFAULT_CONFIG_PATH


_SCRIPTS_SUFFIX = "Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility"

#: A sandboxed (App Store) build sees its container as HOME, so Resolve's
#: documented per-user path virtualizes to `<container>/Data/` + the SAME suffix.
#: The vendor segment is kept.
#:
#: Two traps, both hit on a real install:
#:
#: 1. `<container>/Data/Library/Application Support/Fusion/Scripts/Utility`
#:    exists and is pre-scaffolded with Color/Comp/Deliver/Edit/Tool/Utility, but
#:    it is **Fusion's standalone tree**, not Resolve's. Keying on "which
#:    directory already exists" picks it over the one the README documents.
#: 2. Resolve does not create its own `Fusion/Scripts` tree until a script is
#:    installed, so requiring the target to pre-exist skips the free edition
#:    entirely — the one build the bridge exists for.
#:
#: So: a container that exists means the edition is installed, and the tree is
#: *created*. Blackmagic's README is the authority on the suffix, not the
#: filesystem.
#:
#: **Correction, measured on free 21.0.3.7:** an earlier version of trap 1 said
#: Resolve "does not scan" the Fusion standalone tree. It does — a marker left in
#: `<container>/Data/Library/Application Support/Fusion/Scripts/Utility` appeared
#: under Workspace ▸ Scripts, as did one in
#: `<container>/Data/Documents/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility`.
#: So Lite scans more locations than the README documents.
#:
#: **Second correction (issue #104), same version, opposite result:** on another
#: free 21.0.3.7 App Store install the documented tree listed *nothing* — not
#: even the Lua canary, which rules out the Python-detection explanation and
#: points at the folder — while the Fusion standalone tree listed all four files
#: with no restart. Two machines, same build, contradictory results.
#:
#: We cannot tell them apart from outside Resolve, so we stop trying to pick a
#: winner and install to BOTH container trees. The documented path stays first
#: (it is the one Blackmagic commits to), the standalone tree is the fallback
#: that demonstrably works where the documented one silently does not. The cost
#: is one extra App Management prompt; the cost of guessing wrong is a bridge
#: that never appears and gives the user nothing to diagnose.
_SANDBOX_MARKER = "com.blackmagic-design."

#: Scanned by Lite in addition to `_SCRIPTS_SUFFIX`, inside the container only.
#: NOT used outside a sandbox: on a normal install this is genuinely Fusion's
#: own tree and has nothing to do with Resolve.
_SANDBOX_FALLBACK_SUFFIX = "Library/Application Support/Fusion/Scripts/Utility"
#: Containers that are not Resolve (RAW Player, Speed Test, the IO XPC helper).
_NON_RESOLVE_CONTAINERS = ("BlackmagicRaw", "IOXPC")

#: Windows Scripts/Utility trees, per Blackmagic's own README
#: (docs/reference/resolve_scripting_api.txt, "Specific user"/"All users").
#: Two traps, both live in those two lines:
#:
#: 1. The per-user tree carries a `Support` segment that the all-users tree does
#:    NOT. They are not one layout under two roots, and deriving one from the
#:    other lands in a folder Resolve never scans.
#: 2. The README writes the per-user root as `%APPDATA%\Roaming\...`, which is
#:    wrong — `%APPDATA%` already IS `...\AppData\Roaming`, so following it
#:    literally yields `AppData\Roaming\Roaming\...`. The paths below drop the
#:    doubled segment; both were confirmed present and writable on the Windows 11
#:    machine in issue #106.
_WINDOWS_USER_SCRIPTS_SUFFIX = (
    "Blackmagic Design/DaVinci Resolve/Support/Fusion/Scripts/Utility"
)
_WINDOWS_ALL_USERS_SCRIPTS_SUFFIX = "Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility"


#: The product folder both Windows trees hang off. Its existence is the "Resolve
#: is installed" signal — see `_windows_script_candidates`.
_WINDOWS_PRODUCT_ROOT = "Blackmagic Design/DaVinci Resolve"


def _windows_script_candidates() -> list[Path]:
    """Scripts/Utility trees Resolve scans on Windows (issue #106).

    Gated on the *product* folder, not the Scripts/Utility tree, for the same
    reason the sandbox branch is: Resolve does not create its `Fusion/Scripts`
    tree until a script is installed, so requiring the target to pre-exist skips
    a fresh free-edition install — the one build the bridge exists for. The
    product folder is created on first launch, so it answers "is Resolve
    installed" without demanding a folder only we will ever create.

    Per-user first: it is the one a non-elevated account can actually write,
    while `%PROGRAMDATA%` typically needs an elevated prompt. Ordering it first
    means the target that will succeed is also the one reported first.
    """
    candidates: list[Path] = []
    for env_var, suffix in (
        ("APPDATA", _WINDOWS_USER_SCRIPTS_SUFFIX),
        ("PROGRAMDATA", _WINDOWS_ALL_USERS_SCRIPTS_SUFFIX),
    ):
        root = os.environ.get(env_var)
        if not root:
            continue
        target = Path(root) / suffix
        if target.is_dir() or (Path(root) / _WINDOWS_PRODUCT_ROOT).is_dir():
            candidates.append(target)
    return candidates


def _is_resolve_container(path: Path) -> bool:
    if not path.name.startswith(_SANDBOX_MARKER):
        return False
    return not any(marker in path.name for marker in _NON_RESOLVE_CONTAINERS)


def script_targets() -> list[Path]:
    """Every Scripts/Utility folder Resolve will scan on this machine.

    Sandboxed containers are included because the App Store build cannot see the
    normal per-user path — that isolation is exactly what lets the free edition
    coexist with a direct-download Studio install. Each container contributes
    TWO targets (see the module comment on issue #104): the documented tree
    first, then the Fusion standalone tree that Lite also scans.

    Windows has no sandbox and no `~/Library`, so it gets its own candidate list
    (issue #106) — without one this returned empty on every Windows machine and
    the installer exited with "Is Resolve installed?" on a working install.
    Those candidates arrive pre-vetted, like the sandboxed ones: they are gated
    on Resolve's product folder rather than on the Scripts tree, which Resolve
    does not create until a script is installed.
    """
    home = Path.home()
    # Pre-vetted targets, whose tree gets created rather than being required.
    vetted: list[Path] = []
    candidates: list[Path] = []
    if sys.platform == "win32":
        vetted.extend(_windows_script_candidates())
    else:
        candidates = [
            home / _SCRIPTS_SUFFIX,
            Path("/") / _SCRIPTS_SUFFIX,
            home / ".local/share/DaVinciResolve/Fusion/Scripts/Utility",
        ]
        containers = home / "Library/Containers"
        if containers.is_dir():
            for entry in sorted(containers.iterdir()):
                if _is_resolve_container(entry) and (entry / "Data").is_dir():
                    # The container's existence is the signal; the tree gets created.
                    vetted.append(entry / "Data" / _SCRIPTS_SUFFIX)
                    vetted.append(entry / "Data" / _SANDBOX_FALLBACK_SUFFIX)

    usable: list[Path] = []
    for path in candidates:
        # Non-sandboxed: the install created the tree, so require it.
        if path.is_dir() or (path.parent.is_dir() and os.access(path.parent, os.W_OK)):
            usable.append(path)
    usable.extend(vetted)
    return list(dict.fromkeys(usable))


#: Where a Resolve app bundle actually lives. The App Store build installs flat
#: into /Applications; the direct download uses its own folder. RESOLVE_APP
#: overrides both, matching scripts/doctor.py.
_APP_BUNDLE_CANDIDATES = (
    "/Applications/DaVinci Resolve/DaVinci Resolve.app",
    "/Applications/DaVinci Resolve.app",
    "/Applications/DaVinci Resolve Studio.app",
)


def installed_app_bundles() -> list[str]:
    """Resolve app bundles present on this machine."""
    override = os.environ.get("RESOLVE_APP")
    candidates = (override,) + _APP_BUNDLE_CANDIDATES if override else _APP_BUNDLE_CANDIDATES
    return [path for path in candidates if path and Path(path).is_dir()]


def stale_container_warning(targets: list[Path]) -> str | None:
    """Are we about to install into a container left by an *uninstalled* Resolve?

    A container outlives the app that created it — uninstalling Resolve leaves
    the whole `~/Library/Containers/com.blackmagic-design.*` tree behind. Since
    a container's existence is what makes us target it, the installer would
    otherwise report a clean success on a machine with no Resolve at all, and
    the user would go hunting through the Scripts menu of an app they do not
    have (issue #104). Warn rather than refuse: we cannot enumerate every place
    an app bundle might legitimately live, and being wrong in the refusing
    direction blocks a working install.
    """
    if not any("Containers" in str(target) for target in targets):
        return None
    if installed_app_bundles():
        return None
    return (
        "Installed into a sandbox container, but no DaVinci Resolve app bundle "
        "was found on this machine. A container OUTLIVES the app that created "
        "it, so this is what an uninstalled Resolve looks like — the files were "
        "written, but nothing will ever read them. Checked: "
        + ", ".join(_APP_BUNDLE_CANDIDATES)
        + ". If Resolve is installed somewhere else, re-run with RESOLVE_APP "
        "set to its .app bundle to silence this. If it is not installed, "
        "install it first, then re-run."
    )


#: Resolve enumerates `.py` scripts in Workspace > Scripts only when it can find
#: and load a Python 3, and the failure is completely silent: the script sits in
#: the right folder with the right permissions and simply never appears. Lua is
#: embedded, so `.lua` always lists — which is why a Lua canary is installed
#: alongside the probe.
#:
#: **What it actually looks for (issue #143, corrected 2026-08-10).** This check
#: used to require a *framework* build and send everyone else to python.org. That
#: was the right remedy for the wrong reason, and it turned a one-line fix into a
#: system-wide `sudo` install that managed machines often forbid. In
#: `fusionscript.so` — read on Studio 19.1.3.7, a January 2025 binary, matching
#: what the reporter read on 21.0.4.5 — every `Python.framework` reference is
#: Python **2.7**:
#:
#:     /Library/Frameworks/Python.framework/Versions/2.7/
#:     /System/Library/Frameworks/Python.framework/Versions/2.7/
#:
#: There is no `Python.framework/Versions/3` string at all. Python 3 is found by
#: a different mechanism entirely, whose pieces sit adjacent in the binary:
#:
#:     PYTHON3HOME
#:     /usr/local/bin/python3
#:     python3 -c 'import sys; sys.stdout.write("%s.%s|%s" % (sys.version_info.major, sys.version_info.minor, sys.prefix))'
#:     /libpython
#:
#: i.e. resolve `PYTHON3HOME`, else `/usr/local/bin/python3`; probe it for its
#: version and `sys.prefix`; `dlopen` `<prefix>/lib/libpython3.X.dylib`. The
#: ordering is inferred from adjacency rather than decompiled control flow, but
#: the two entry points are not in doubt.
#:
#: That explains every observation the old rule was built on. python.org works
#: because its installer creates `/usr/local/bin/python3` — verified here, where
#: it is a symlink into `Python.framework/Versions/3.11`. Homebrew on Apple
#: silicon installs to `/opt/homebrew/bin`, pyenv to `~/.pyenv/shims`, and uv to
#: `~/.local/share/uv/...`; none of them land `/usr/local/bin/python3`, so none
#: are found. Framework-ness was never the variable — it was correlated with it.
#:
#: So a non-framework interpreter works once Resolve can see it, and `uv`/`pixi`/
#: conda-forge users are not stuck: they can point `PYTHON3HOME` at their prefix
#: without touching a system directory. It must be set with `launchctl setenv`,
#: not `export` — Resolve is GUI-launched and inherits launchd's environment, not
#: any shell's.
_FRAMEWORK_PYTHON_ROOTS = (
    Path("/Library/Frameworks/Python.framework/Versions"),
    Path("/System/Library/Frameworks/Python.framework/Versions"),
)

#: The interpreter path baked into fusionscript.so as the fallback when
#: PYTHON3HOME is unset. This is the one python.org's installer creates.
_FALLBACK_PYTHON3 = Path("/usr/local/bin/python3")

#: Filename of the Lua enumeration canary. Named once: the installer writes it
#: and the post-install guidance counts it, and those two disagreeing is how a
#: user ends up told to expect entries that are not there.
_CANARY_NAME = "resolve_bridge_canary.lua"

_LUA_CANARY = """-- Installed by davinci-resolve-mcp as an enumeration canary.
-- If THIS appears under Workspace > Scripts but resolve_bridge_probe does not,
-- Resolve is listing Lua and silently skipping Python. On Resolve 21.1+ FREE
-- that is expected: Python scripting moved to Studio (issue #203), and nothing
-- below will change it. On Studio, or 21.0.x and earlier, it cannot find a Python 3.
-- It looks at PYTHON3HOME, then /usr/local/bin/python3 -- and nowhere else, which
-- is why Homebrew, pyenv, uv and conda interpreters go unseen. Either point it at
-- the one you have (no sudo, but does NOT survive a reboot):
--   launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
-- (launchctl, not export -- Resolve never sees your shell; and the prefix needs
-- BOTH lib/libpython3.X.dylib and bin/python3 under that unversioned name --
-- Homebrew framework builds often ship only python3.X), or put one where Resolve
-- already looks, which persists:
--   sudo ln -s "$(command -v python3)" /usr/local/bin/python3
-- A python.org build creates that symlink for you. Res...