davinci-resolve-mcp 2.57.5 → 2.59.0

package/docs/kernels/color-grade-kernel.md

@@ -86,6 +86,57 @@ All actions are exposed through `timeline_item_color`.
   as callable methods but are not forced in the boundary report because they can
   be asynchronous, page dependent, and expensive.
 
+## Advanced (offline) server — the grading / QC catalog
+
+The live actions above drive a *running* Resolve. The companion advanced server
+(`davinci-resolve-advanced`, see `resolve-advanced/README.md`) *computes* grades
+offline from extracted frames and reads/writes `.drx`/`.drp` grades with **no
+Resolve running**. It emits an apply-ready `.drx`; **applying it is this kernel's
+job** (`safe_apply_drx`). Node never drives Resolve.
+
+`drx` grading/QC actions (frame-stats → arithmetic → `.drx`, all local,
+deterministic, guarded — they refuse to fabricate a match rather than emit a
+silent no-op):
+
+| Action | Use when |
+| --- | --- |
+| `match_to_reference` | Match a clip toward an approved still (affine mean/std, skin-line gated, luma-preserving). |
+| `level_clips` | Level within-camera exposure/WB drift to a group hero. |
+| `skin_match` | Cross-camera skin-tone cohesion (skin-gated; throws on log/wrong-space frames). |
+| `shot_match` | B-roll cohesion (gray-world neutralize or hero match). |
+| `white_balance_match` | WB from a known-neutral patch / gray card. |
+| `contrast_normalize` | Match black/white points to a hero (affine gain+offset). |
+| `saturation_match` / `black_balance` | Saturation cohesion / neutralize a shadow cast. |
+| `cdl_io` | Import ASC CDL (`.cc`/`.ccc`/`.cdl`) → `.drx`. |
+| `grade_transfer` | Lossless Body copy — a `.drp` group / `.drx` look → apply-ready `.drx`. |
+| `lut_apply` | Attach a named `.cube` LUT to a node (round-trip asserted). |
+| `author_look` / `carry_look` | Version and carry an approved season/host look. |
+| `scope_read` / `intent_tags` / `gamut_legal` | Read frames: parade/vectorscope/clip%, shot-intent tags, broadcast-legal QC. |
+| `verify_grade` | Intended vs applied `.drx` → landed/drifted/missing/unverifiable. |
+
+Cross-server rules an agent must know:
+
+- **Value space.** `drx` `generate`/`merge` default to `space:'ui'` (Resolve
+  panel units; saturation 0–100, neutral 50). Pass `space:'drx'` only for raw
+  internal floats. Fidelity is ground-truth only for the calibrated set — check
+  the `valueFidelity` marker
+  (`resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md`).
+- **Hue-axis curves.** Naive `[0,1]` point lists auto-canonicalize into the
+  verified bezier cage; a `warnings` array in the result means the curve went
+  through raw and will render **FLAT** — surface it, don't ship silently.
+- **Apply targeting.** `safe_apply_drx` defaults to video track 1 / item 0 —
+  always pass `track_type`/`track_index`/`item_index` explicitly, and grab a
+  still/`.drx` backup first (`safe_apply_drx` does not snapshot).
+- **Relayout ("Cleanup Node Graph," no UI API).** Single clip, live: grab still →
+  `drx(action="relayout")` → `graph.reset_all_grades` → `safe_apply_drx` with
+  explicit indices (a same-structure apply keeps the OLD layout — the reset is
+  required). Whole project, offline: `project_db(action="relayout_node_graphs")`.
+- **Deps.** The grading catalog needs `sharp`; call the advanced `capabilities`
+  tool for live status and install hints.
+
+See the `resolve-color` skill (`.claude/skills/color-grade.md`) for the
+craft ↔ live ↔ offline routing and the frame-first rule.
+
 ## Live Probe
 
 Run the live boundary probe with:

package/docs/kernels/fusion-composition-kernel.md

@@ -104,6 +104,23 @@ in success and in error responses.
   effect parameter. Higher-level wrappers should probe before assuming a
   control exists.
 
+## Advanced (offline) server — declarative `.comp` authoring
+
+The actions above build a Fusion comp on a timeline item in a *running* Resolve.
+The companion advanced server (`davinci-resolve-advanced`, see
+`resolve-advanced/README.md`) authors Fusion compositions **offline, no Resolve
+running**, via the `fusion` tool:
+
+- `generate` / `generate_from_template` — write a `.comp` from a declarative spec
+  or a named template (`list_templates`).
+- `to_api_calls` — compile a spec into the ordered tool-creation / input /
+  connection calls the live server then replays.
+
+Rule of thumb: author and verify the comp offline, then apply it live with
+`fusion_comp` `safe_add_tool` → `safe_set_inputs` → `safe_connect_tools` (the
+`to_api_calls` output maps directly onto those). See the `resolve-fusion` skill
+(`.claude/skills/fusion.md`) and the `/fusion_workflow` prompt.
+
 ## Live Probe
 
 Run the live boundary probe with:

package/docs/kernels/media-pool-ingest-kernel.md

@@ -120,6 +120,26 @@ params={"confirm": true, ...})`.
   the installed DaVinci Resolve 20 Manual, Edit > Chapter 42, "Multicam
   Editing," for the current UI workflow.
 
+## Advanced (offline) server — media front-end / ingest verification
+
+The actions above import and organize media in a *running* Resolve. The companion
+advanced server (`davinci-resolve-advanced`, see `resolve-advanced/README.md`)
+handles the front-end / assistant-editor ingest layer **offline, no Resolve
+running**, via the `media` tool (needs ffmpeg + ffprobe on PATH for the probing
+actions):
+
+- `ingest_verify` — hash seal / verify / dupes-by-hash (chain-of-custody).
+- `media_inventory` — fps / codec / colorspace / TC + card-gap report.
+- `sync` — picture↔sound TC alignment + drift / MOS detection.
+- `relink_manifest`, `rename_plan` (**refuses camera originals**) /
+  `reel_normalize`, `turnover_package`, `project_hygiene`.
+
+Rule of thumb: verify and inventory the card offline *before* importing, then
+import/organize live. `media` also serves the delivery side (see the
+`resolve-delivery` skill). See the `resolve-media-pool` skill
+(`.claude/skills/media-pool.md`) and the `/media_pool_workflow` prompt. Never
+rename or derive camera originals without explicit approval.
+
 ## Live Evidence
 
 Final validation ran on May 9, 2026 with DaVinci Resolve Studio 20.3.2.9 and

package/docs/kernels/render-deliver-kernel.md

@@ -64,6 +64,38 @@ All actions are under `render(action=...)`.
   existing `render_presets` tool, but the live kernel probe does not fabricate
   arbitrary preset files.
 
+## Advanced (offline) server — deliverable QC, media front-end, provenance
+
+The live actions above plan and drive renders in a *running* Resolve. The
+companion advanced server (`davinci-resolve-advanced`, see
+`resolve-advanced/README.md`) QCs the **finished render** and manages media/
+provenance with **no Resolve running**. It is report-only —
+**`gate: review`, never auto-pass-clear.**
+
+- **`deliverable`** — `deliverable_qc` (ffprobe a render vs its spec → pass/fail
+  **per field**), `loudness_qc` (ebur128 LUFS/true-peak/LRA),
+  `reframe_blanking_check`, `conform_completeness` (every intended shot present),
+  `re_delivery_diff`, `render_manifest` (build/reconcile), `expand_deliverable`
+  (texted/textless/stems/slate/leader entities).
+- **`media`** (front-end / AE) — `ingest_verify` (hash seal/verify/dupes),
+  `media_inventory` (fps/codec/colorspace/TC + card gaps), `sync` (picture↔sound
+  TC + drift/MOS), `relink_manifest`, `rename_plan` (**refuses camera
+  originals**) / `reel_normalize`, `turnover_package`, `project_hygiene`.
+- **`provenance`** (audit) — `grade_provenance` ("why is this graded this way"),
+  `gallery_lineage`, `cdl_export` / `cdl_diff` (round-trip asserted),
+  `revision_tracking`, `episode_report`.
+
+Rules an agent must know:
+
+- QC tools **refuse rather than fabricate** — a "refused" result means missing
+  file, wrong spec, or a metric it cannot honestly compute.
+- Deliverable gates never auto-clear; surface the per-field verdict to a human.
+- **Deps.** `deliverable`/`media` QC needs **ffmpeg + ffprobe on PATH** (GPL, not
+  bundled) — call the advanced `capabilities` tool for status + install hints.
+
+See the `resolve-delivery` skill (`.claude/skills/delivery.md`) for the
+craft ↔ live ↔ offline routing.
+
 ## Live Evidence
 
 Final validation ran on May 9, 2026 with DaVinci Resolve Studio 20.3.2.9 and

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -84,6 +84,45 @@ Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
 - Export and import helpers require temp paths by default because they write
   interchange artifacts.
 
+## Advanced (offline) server — the conform QC engine
+
+The live actions above operate on a *running* Resolve. The companion advanced
+server (`davinci-resolve-advanced`, see `resolve-advanced/README.md`) does the
+finishing-grade conform work with **no Resolve running**, against `.drt`/`.drp`
+files and the project DB.
+
+- **`conform`** — offline conform/relink QC with **frame-oracle math, not
+  filename matching** (it catches a clip relinked to the wrong-but-similarly-named
+  source). Also: reverse/retimed subclip DB repair (reversed `source_start` =
+  `masterFrames − 1 − endoffset`, live-validated), sequence lineage store + diff +
+  rollback (hashed snapshots), and per-cut frame QC (oracle-frame vs
+  reference-render, scale-corrected, red/yellow/cyan verdicts).
+- **`color_trace`** — cross-project clip matching → a trace plan for carrying
+  grades across a re-conform (pairs with the color kernel's `drx grade_transfer`).
+- **`offline_ref`** — offline-reference clips have **no scripting API** but live
+  inside `.drp`/`.drt` as `<OfflineClip>` entries; patch them here.
+- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML; **AAF = honest refuse**),
+  `turnover_changelist` (moved/retimed/replaced/new/gone with timing guards),
+  `conform_manifest`, `marker_roundtrip`.
+- **`drt` / `project_db`** — timeline file authoring and DB patching.
+
+Gotchas the live path shares:
+
+- **XML import via the scripting API goes _offline_** (missing-media/generators
+  abort). Use `import_timeline_checked` with media **sanitize** (FCP7/FCPXML) so
+  the API imports with links intact, then exact-path relink. Restart a running MCP
+  server to pick up the sanitize fix.
+- **`.drt` version.** For DaVinci Resolve 19.1.3, set `DbPrjVer` 17 → 16 when
+  authoring a `.drt`.
+- **`project_db` patches** require the project **CLOSED** plus
+  `iConfirmProjectClosed:true`; writes auto-back-up and read-back verify. Resolve
+  caches open projects — **fully quit and relaunch** after patching.
+- **Deps.** `better-sqlite3` gates lineage/reverse/DB; `sharp`/ffmpeg gate frame
+  compare — call the advanced `capabilities` tool.
+
+See the `resolve-conform` skill (`.claude/skills/conform.md`) for the
+craft ↔ live ↔ offline routing.
+
 ## Live Probe
 
 Run the live boundary probe with:

package/docs/kernels/timeline-edit-kernel.md

@@ -180,6 +180,23 @@ Some behavior depends on Resolve's current page or bridge state:
   if Resolve loses current timeline state, the harness records the bridge
   condition separately.
 
+## Advanced (offline) server — editorial interchange + changelist
+
+The kernel above restructures a *running* timeline. The companion advanced server
+(`davinci-resolve-advanced`, see `resolve-advanced/README.md`) authors/diffs
+timelines and reasons over editorial interchange with **no Resolve running**:
+
+- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML; **AAF = honest refuse**),
+  `turnover_changelist` (moved/retimed/replaced/new/gone between two cuts, with
+  timing silent-lie guards), `conform_manifest`, `marker_roundtrip`.
+- **`drt`** — `.drt` timeline file authoring + structural diff.
+
+Use these to answer "what changed between v3 and v4" or to hand a conform an
+accurate change list without opening either timeline. For conforming/relinking
+that change list, see the Timeline Conform / Interchange kernel and the
+`resolve-conform` skill; for the edit ↔ offline routing, see the `resolve-edit`
+skill (`.claude/skills/timeline-edit.md`).
+
 ## Development Guardrails
 
 - Use disposable projects and synthetic media for live validation.

package/docs/process/release-process.md

@@ -35,11 +35,15 @@ Every release bump must update all version surfaces:
   `venv/bin/python scripts/gen_api_limitations.py`. The
   `tests.test_api_limitations_doc` drift guard fails the suite if it is stale.
 - `docs/SKILL.md` when tool discovery, examples, or behavior changed
-- `docs/guides/control-panel.md` when the control panel UI changed, plus
+- `docs/guides/control-panel.md` — check EVERY release, not only when the
+  panel "changed": panel surfaces grow transitively (new tools, new docs pages,
+  new diagnostics cards), so review the guide for accuracy and update it plus
   regenerated screenshots: start the panel against a project with analysis
   data, then run `venv/bin/python scripts/regen_panel_screenshots.py`.
   The `tests.test_panel_docs_drift` guard fails the suite (and the publish
-  workflow) when the guide drifts from the panel's navigation or screenshots.
+  workflow) when the guide drifts from the panel's navigation or screenshots —
+  but the guard checks presence, not prose accuracy; the human pass is the
+  accuracy check.
 - Git tag, e.g. `v2.4.1`
 - GitHub Release notes
 
@@ -54,17 +58,35 @@ Always run static checks before release:
 venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
 venv/bin/python scripts/gen_api_limitations.py --check
-venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift
+node scripts/agent-rules/generate.mjs --check
+venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift
 node bin/davinci-resolve-mcp.mjs --help
 node bin/davinci-resolve-mcp.mjs --version
 npm pack --dry-run
 git diff --check
 ```
 
-The three drift guards (undefined names in `src/`, tool action lists vs
-dispatch, control-panel guide vs panel navigation/screenshots) also run in the
-`Publish npm package` workflow on every `v*` tag, so a stale doc or drifted
-action list fails the publish — fix the drift rather than bypassing the gate.
+The drift guards (undefined names in `src/`, tool action lists vs dispatch,
+control-panel guide vs panel navigation/screenshots, api-limitations vs the
+api_truth ledger, and **tool counts across the docs vs reality** —
+`test_doc_tool_counts`) also run in the `Publish npm package` workflow on every
+`v*` tag, so a stale doc or drifted action list fails the publish — fix the drift
+rather than bypassing the gate.
+
+`test_doc_tool_counts` statically counts the compound (`src/server.py`), granular
+(`src/granular/`), and Node advanced (`resolve-advanced/server/index.mjs`) tools and
+asserts the numbers quoted in README, `resolve-advanced/README.md`, `docs/contributing.md`,
+`docs/SKILL.md`, `docs/reference/api-coverage.md`, and `.github/copilot-instructions.md`
+still match. When you add/remove a tool, update those docs to the counts the test prints.
+
+The cross-platform agent rule files (`.cursor/rules/*`, `.github/instructions/*`,
+`.windsurf/rules/*`, `.cursorrules`, `.windsurfrules`, the `AGENTS.md` domain-routing
+block, and `.github/copilot-instructions.md`) are **generated** by
+`scripts/agent-rules/generate.mjs`, which parses those same counts from their
+canonical docs. After a count or tool-routing change, run
+`node scripts/agent-rules/generate.mjs` and commit the result;
+`test_agent_rules_drift` fails the suite (and publish) if the committed files are
+stale. See `scripts/agent-rules/README.md`.
 
 Run focused unit tests for the changed surface. For recent timeline/marker
 helpers, this usually includes:

package/docs/reference/api-coverage.md

@@ -17,7 +17,7 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 ## API Coverage
 
-Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **33 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **341 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
+Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **34 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **341 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
 
 The 33rd compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.57.5"
+VERSION = "2.59.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -666,14 +666,45 @@ def write_client_config(client, python_path, server_path, api_path, lib_path, dr
     return True, str(config_path)
 
 
+def build_advanced_entry(server_path, python_path=None):
+    """Build the config entry for the optional 'davinci-resolve-advanced' server.
+
+    This is the Node, beyond-the-scripting-API sibling (file/.drp/.drt/.drx
+    authoring + conform + editorial, no live Resolve required). It ships in the
+    same package as a second bin. Opt-in: include it only if you want the
+    file-level tools alongside the live server.
+
+    The Node server shells out to Python for the OFFLINE AAF reader (aaf_probe.py,
+    pyaaf2). We pin AAF_PROBE_PYTHON to the project venv's interpreter — the same
+    venv install.py installs pyaaf2 into — so AAF preview works out of the box
+    instead of depending on whatever `python3` happens to be on PATH.
+    """
+    project_dir = Path(server_path).resolve().parents[1]  # .../src/server.py -> repo root
+    advanced_bin = project_dir / "bin" / "davinci-resolve-advanced-mcp.mjs"
+    entry = {"command": "node", "args": [str(advanced_bin)]}
+    if python_path:
+        entry["env"] = {"AAF_PROBE_PYTHON": str(python_path)}
+    return entry
+
+
 def generate_manual_config(python_path, server_path, api_path, lib_path):
     """Generate config snippets for manual setup."""
     entry = build_server_entry(python_path, server_path, api_path, lib_path)
     zed_entry = build_zed_entry(python_path, server_path, api_path, lib_path)
     opencode_entry = build_opencode_entry(python_path, server_path, api_path, lib_path)
-
-    standard = json.dumps({"mcpServers": {"davinci-resolve": entry}}, indent=2)
-    vscode_fmt = json.dumps({"servers": {"davinci-resolve": entry}}, indent=2)
+    advanced = build_advanced_entry(server_path, python_path)
+
+    # Standard snippet includes BOTH servers: the live Python server and the
+    # optional Node 'advanced' server (file-level, no Resolve). Drop the
+    # advanced entry if you only want live control.
+    standard = json.dumps({"mcpServers": {
+        "davinci-resolve": entry,
+        "davinci-resolve-advanced": advanced,
+    }}, indent=2)
+    vscode_fmt = json.dumps({"servers": {
+        "davinci-resolve": entry,
+        "davinci-resolve-advanced": advanced,
+    }}, indent=2)
     zed_fmt = json.dumps({"context_servers": {"davinci-resolve": zed_entry}}, indent=2)
     opencode_fmt = json.dumps({"mcp": {"davinci-resolve": opencode_entry}}, indent=2)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.57.5",
+  "version": "2.59.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",
@@ -14,11 +14,32 @@
   },
   "type": "module",
   "bin": {
-    "davinci-resolve-mcp": "./bin/davinci-resolve-mcp.mjs"
+    "davinci-resolve-mcp": "./bin/davinci-resolve-mcp.mjs",
+    "davinci-resolve-advanced-mcp": "./bin/davinci-resolve-advanced-mcp.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "adm-zip": "^0.5.16",
+    "fast-xml-parser": "^5.7.3",
+    "fzstd": "^0.1.1",
+    "jszip": "^3.10.1",
+    "uuid": "^9.0.0",
+    "zod": "^3.25.76",
+    "zstd-codec": "^0.1.5"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.0.0",
+    "js-yaml": "^4.1.0",
+    "pg": "^8.11.0",
+    "sharp": "^0.33.0"
   },
   "files": [
     "bin/",
     "src/**/*.py",
+    "resolve-advanced/server/**/*.mjs",
+    "resolve-advanced/vendor/**",
+    "resolve-advanced/package.json",
+    "resolve-advanced/README.md",
     "docs/**/*.md",
     "docs/reference/resolve_scripting_api.txt",
     "examples/**/*.md",

package/resolve-advanced/README.md

@@ -0,0 +1,199 @@
+# davinci-resolve-advanced-mcp
+
+The **beyond-the-API** half of `davinci-resolve-mcp`: a Node MCP server that authors and edits
+DaVinci Resolve **files** (`.drp` / `.drt` / `.drx`) and applies DB/XML-level changes (Fairlight
+routing, offline-reference, conform, color-group grade read) — **with no DaVinci Resolve running.**
+
+It ships as a second `bin` inside the `davinci-resolve-mcp` npm package (one install, two servers):
+
+```
+bin/davinci-resolve-mcp.mjs           → Python, live, sanctioned scripting API (drives Resolve)
+bin/davinci-resolve-advanced-mcp.mjs  → Node, beyond-API file/DB authoring (no Resolve required)   [this]
+```
+
+Runs cloud or local — the file tools never touch Resolve.
+
+## Two ways to use it
+
+- **As an MCP server** (the bin above) — point any MCP client at it.
+- **As a library** — `import` the engine directly. The package exposes a public API surface
+  (`server/lib.mjs`, wired via `package.json` `main`/`exports`), grouped as **codec** (offline
+  `.drp/.drt/.drx`), **grading** (deterministic compute cores), **pipeline** (the DB-as-truth
+  foundation), **tools** (the MCP tool handlers), and **mcp** (the stdio server entry). The MCP
+  server is a thin shell over these same exports.
+
+## Usage
+
+**As a library — a grading core.** You extract display-referred frames per clip (ffmpeg, your
+call); the engine computes the grade offline and writes an apply-ready `.drx`. Applying it in
+Resolve (via the scripting API) is the caller's job.
+
+```js
+import { computeSkinMatch } from 'davinci-resolve-advanced-mcp';
+
+const { grades, report, warnings } = await computeSkinMatch(
+  [
+    { id: 'B_0008', png: '/frames/B_0008.png', group: 'Guest' },
+    { id: 'C_0016', png: '/frames/C_0016.png', group: 'Guest' },
+  ],
+  { outDir: '/out/skin' },
+);
+// grades[].drxPath → apply in Resolve; warnings flag over-corrections; low-skin clips are skipped, not faked.
+```
+
+**The DB-as-truth pipeline** (via the `pipeline` tool handler — same API the MCP server exposes).
+Compile YAML specs into the canonical DB, plan a run, execute a deterministic stage (you supply the
+tool inputs), then read decoded state back and check drift:
+
+```js
+import { pipelineTool } from 'davinci-resolve-advanced-mcp';
+const call = (action, args) => pipelineTool.handler({ action, args });
+
+const dbPath = '/proj/project.db';
+const now = new Date().toISOString(); // the tool takes an explicit timestamp
+
+await call('compile', { dbPath, now, yamlDir: '/proj/specs' }); // YAML → resolved entity tree
+const { runId, stages } = await call('plan', { dbPath, episodeSlug: 'e012', now });
+
+// Deterministic stages run now (you pass the tool args); Resolve-apply stages return an action plan.
+await call('execute_stage', {
+  dbPath, runId, stageIndex: 0, now,
+  toolArgs: { tool: 'gamut_legal', args: { clips: [{ id: 'f', png: '/frames/f.png' }] } },
+});
+
+// Pull decoded actual state up and flag intent↔actual drift.
+await call('readback', {
+  dbPath, entitySlug: 'e012.group.Host', now,
+  facts: { 'look.lut': 'Kodak_5219' }, pushFields: [{ field: 'look.lut' }],
+});
+```
+
+## Tools (18)
+
+`drp` · `drt` · `drx` · `offline_ref` · `conform` · `color_trace` · `fusion` · `audio` ·
+`audio_plan` · `fairlight` · `project_db` · `project_read` · `pipeline` · `capabilities` ·
+`deliverable` · `media` · `editorial` · `provenance`
+
+Each dispatches on an `action`. Highlights:
+
+- **`drx`** — per-clip grade (`.drx`) codec: `parse`, `generate`, `generate_from_request`,
+  `export_cdl`, `merge`, plus the **grading/QC catalog** below.
+- **`drp` / `drt`** — project / timeline file authoring + editing + grade injection + structural diff.
+- **`conform`** — offline conform/relink QC engine (frame-oracle math, not filename matching),
+  reverse-clip DB repair, sequence lineage store + diff, per-cut frame QC.
+- **`color_trace`** — cross-project clip matching → a trace plan for carrying grades across a re-conform.
+- **`project_read` / `project_db`** — read/patch the Resolve project DB (SQLite or Postgres).
+- **`pipeline`** — the DB-as-truth pipeline foundation (see below).
+- **`deliverable`** — deliverable QC / compliance: `deliverable_qc` (ffprobe a render vs its spec →
+  pass/fail per field), `loudness_qc` (ebur128 LUFS/true-peak/LRA), `reframe_blanking_check`,
+  `conform_completeness`, `re_delivery_diff`, `render_manifest` (build/reconcile), `expand_deliverable`
+  (texted/textless/stems/slate/leader entities). Report-only (`gate: review` — never auto-pass-clear).
+- **`media`** — media front-end / AE: `ingest_verify` (hash seal/verify/dupes-by-hash), `media_inventory`
+  (fps/codec/colorspace/TC + card gaps), `sync` (TC picture↔sound + drift/MOS), `relink_manifest`,
+  `rename_plan` (refuses camera originals) / `reel_normalize`, `turnover_package`, `project_hygiene`.
+- **`editorial`** — editorial integrity: `parse_interchange` (EDL/OTIO/XMEML natively, AAF via pyaaf2,
+  **.prproj via gunzip+XML** — pass the file PATH for the binary ones), `list_sequences` (one picker entry
+  point across xml/edl/otio/drt/drp/aaf/prproj), `convert_to_interchange` (author OTIO/EDL/DRT that Resolve
+  imports, from events or a parsed source — **the .prproj→Resolve conform bridge**, no Premiere needed;
+  editorial timing/cuts/transitions/speed carry, per-clip effects/color do not),
+  `turnover_changelist` (moved/retimed/replaced/new/gone + timing silent-lie guards), `conform_manifest`,
+  `marker_roundtrip`.
+- **`provenance`** — provenance / audit: `gallery_lineage`, `grade_provenance` ("why is this graded this
+  way"), `cdl_export` (+ `cdl_diff`, round-trip asserted), `revision_tracking`, `episode_report`.
+
+### Grading / QC catalog (`drx` actions — all local, deterministic, no Resolve)
+
+Frame-stats → arithmetic → `.drx` grade. Frame extraction and grade **apply** are the caller's job;
+these compute the grade offline. Each carries guards that refuse to fabricate a match rather than emit
+a silent no-op.
+
+| Action | What |
+|---|---|
+| `level_clips` | within-camera exposure/WB drift → a group hero (whole-frame mean) |
+| `skin_match` | cross-camera skin-tone cohesion (skin-gated mean; throws on log/wrong-space frames) |
+| `shot_match` | b-roll cohesion — gray-world `neutralize` or `hero` match (per-channel median) |
+| `white_balance_match` | WB from a known-neutral patch (gray card) — accurate, not gray-world guess |
+| `contrast_normalize` | match black/white points to a hero (affine gain+offset) |
+| `match_to_reference` | affine mean-std transfer toward an approved still (skin-line gated, luma-preserve) |
+| `saturation_match` | skin/overall saturation cohesion toward a hero |
+| `black_balance` | neutralize a shadow colour cast (p1 black point, offset-only) |
+| `cdl_io` | import ASC CDL (`.cc`/`.ccc`/`.cdl`) → `.drx` |
+| `grade_transfer` | lossless Body copy — a `.drp` group / `.drx` look → an apply-ready `.drx` |
+| `relayout` | programmatic "Cleanup Node Graph" (the UI command has no API) — rewrite node x/y to Resolve's clean row, grade byte-preserved. Live recipe: grab → `relayout` → reset grade → apply (same-structure applies keep the old layout). Bulk whole-project sweep: `project_db` `relayout_node_graphs` |
+| `author_look` / `carry_look` | version an approved season/host look + plan carrying it across episodes |
+| `lut_apply` | attach a named `.cube` LUT to a node (Body-LUT write path, round-trip asserted) |
+| `scope_read` | frame readouts: parade balance, vectorscope skin-line, black-balance, %clip/%crush + intent signals |
+| `intent_tags` | derive L1 shot-intent tags (low_key, monochromatic, motivated_warm) to exclude from neutralize |
+| `verify_grade` | intended vs applied `.drx` → landed/drifted/missing/unverifiable |
+| `extract_frames` | ffmpeg display-referred frame extraction (hard log-refuse) |
+| `gamut_legal` | broadcast-legal + hard-clip QC (measurement only, no grade emitted) |
+
+### Pipeline foundation (`pipeline` tool — DB-as-truth)
+
+A canonical local **SQLite project DB** is the source of truth; **YAML authoring compiles into it**
+(4-layer inheritance: type → series → episode → deliverable, with validation); a **runner** reads the
+resolved `pipeline:` and executes stages with gates + provenance; **readback** records decoded actual
+state and flags intent↔actual **drift**. Deterministic stages run in Node; Resolve-apply stages emit an
+action plan for the live agent (Node can't drive Resolve). Actions: `compile`, `list_entities`,
+`get_entity`, `ancestry`, `catalog`, `plan`, `execute_stage`, `approve_gate`, `mark_applied`,
+`readback`, `get_run`, `list_runs`, `provenance`, `drift`.
+
+## Layout
+- `vendor/` — vendored, MIT copies of the format libraries (CommonJS):
+  - `drp-format/` — `.drp` project authoring/editing + grade injection + structural diff
+  - `drt-format/` — `.drt` timeline authoring (delegates to drp-format)
+  - `drx-codec/` — per-clip DRX grade parse/generate, CDL export, node-tree/curves/qualifier/window codecs
+  - `drx-parameters/` — calibrated parameter ranges/ids consumed by drx-codec
+  - `conform-qc/` — the offline conform/relink QC engine
+- `server/` — the MCP server, tools, grading cores, and the DB-as-truth pipeline foundation
+- `test/` — offline unit suite (`npm test`); `.prettierrc.json` — formatting config
+- `package.json` — manifest; intentionally CommonJS (no `"type": "module"`) so the vendored libs load
+  under the repo's `type: module` root.
+
+## Requirements & optional features
+
+The **core is pure-JS / MIT with zero required native modules or bundled binaries** — `drp`, `drt`,
+`drx` (incl. the grading catalog needs `sharp`, see below), `offline_ref`, `fusion`, `audio_plan`,
+`conform` (core), `color_trace`, `project_read`, `capabilities` all work out of the box, cloud or local.
+
+A few features need something the **user installs themselves** (call the `capabilities` tool for live
+status + install hints):
+
+| Feature | Needs | Why not bundled / Install |
+|---|---|---|
+| `audio` (split/trim/convert), conform frame ops | **ffmpeg + ffprobe on PATH** | FFmpeg binaries are **GPL** — bundling them would taint this MIT package. `brew install ffmpeg` / `apt install ffmpeg` / `choco install ffmpeg`. |
+| grading/QC catalog, `conform.verify` (frame compare) | `sharp` (optional) | native module; `npm i sharp` |
+| `pipeline` (project DB), `fairlight` live-DB path, conform lineage/reverse | `better-sqlite3` (optional) | native module; `npm i better-sqlite3`. (The `.drp`-zip Fairlight path needs none.) |
+| YAML authoring (`pipeline compile` from a YAML dir) | `js-yaml` (optional) | pure JS; `npm i js-yaml` |
+| `editorial` AAF offline preview (`parse_interchange` format `aaf`, `list_sequences` on `.aaf`) | **Python 3 + `pyaaf2`** | AAF is binary; no trustworthy pure-JS reader. The server shells out to `aaf_probe.py` (pure-Python `aaf2`). `pip install pyaaf2`. Without it, AAF **honest-refuses** with a convert-upstream hint (EDL/OTIO/`.drt` need nothing). Live AAF import is on the Python `davinci-resolve` MCP (Resolve reads AAF natively). |
+
+Missing features fail with a clear, actionable message rather than crashing; the server logs a one-line
+"needs setup" summary to stderr at startup.
+
+## Provenance & license
+Vendored libraries are clean offline format-interop and deterministic compute code: no secrets, no
+external service coupling, no network calls, no LLM dependency. Where a feature can take a second
+opinion from an AI (the conform engine's advisory `VisionValidator`), it does so only through a
+host-injected adapter — the engine ships the interface and a deterministic fake, never a concrete
+LLM client. Licensed **MIT** under this repo's root `LICENSE` (Copyright DaVinci Resolve MCP
+Contributors and Bradford Operations LLC).
+
+> The bundled `vendor/drp-format/templates/media-clip-h264.drp` uses a neutral synthetic source
+> (`/Media/sample.mp4`) — scrubbed of any personal path / third-party clip reference.
+
+DRX write paths were calibrated live against DaVinci Resolve 19 Studio (2026-07): primaries use one
+unified `space: 'ui' | 'drx'` value-space flag (panel units by default), and the structural writes —
+power windows (circle/linear/gradient + polygon/curve vertex shapes), HSL/RGB/luma qualifiers, HDR
+zones, ColorSlice globals, blur/key/motion-effects palettes, sat/lum-axis HSL curves, and hue-axis
+HSL curves (single- **and** multi-band, via a canonical bezier-cage emitter that replicates Resolve's
+own serialization; edge-on-band-slot geometry passes through raw) — are panel-readback-verified.
+OFX/ResolveFX plugin params are read AND write verified (params are self-describing
+on the wire; writes render-confirmed live — see the ResolveFX registry for the full
+plugin universe, measured ranges, and per-plugin enum vocabularies). HDR zone
+DEFINITIONS (custom Max Range/falloff), Motion Effects scales, and the tracker-data
+blob are decoded and (where applicable) write-verified. Still experimental to write:
+Color Warper on Resolve 19 (the pin-list wire format is R21's). Per-control status
+lives in `vendor/drx-parameters/CALIBRATION-STATUS.md` — capabilities are flagged
+honestly, not overclaimed.
+The grading catalog and pipeline foundation are unit-tested offline; their Resolve **apply** is the
+caller's job and is validated live separately.

package/resolve-advanced/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "davinci-resolve-advanced-mcp",
+  "version": "0.0.0-dev",
+  "private": true,
+  "license": "MIT",
+  "description": "Beyond-the-API DaVinci Resolve MCP — offline .drp/.drt/.drx authoring/editing. Sibling Node server to the Python davinci-resolve-mcp. Dev-local package.json; deps promote to the repo root at packaging.",
+  "comment_commonjs": "Intentionally NO \"type\": \"module\" — the vendored libs are CommonJS (require()). The repo root is type:module, so this nested manifest scopes resolve-advanced/**/*.js back to CommonJS.",
+  "comment_exports": "Public library surface so a downstream consumer can import the codec/grading/pipeline API, not just spawn the MCP bin. `.` = the lib barrel; `./mcp` = the stdio server entry. Still private:true — publish name/registry + un-privating are a parked decision.",
+  "main": "./server/lib.mjs",
+  "exports": {
+    ".": "./server/lib.mjs",
+    "./mcp": "./server/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "server/**/*.mjs",
+    "vendor/**",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "adm-zip": "^0.5.16",
+    "fast-xml-parser": "^5.7.3",
+    "fzstd": "^0.1.1",
+    "jszip": "^3.10.1",
+    "uuid": "^9.0.0",
+    "zod": "^3.25.76",
+    "zstd-codec": "^0.1.5"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.10.0",
+    "js-yaml": "^4.3.0",
+    "pg": "^8.22.0",
+    "sharp": "^0.33.0"
+  },
+  "peerDependenciesMeta": {
+    "_comment": "audio (split/trim/convert) + conform frame ops need system ffmpeg/ffprobe on PATH (NOT bundled — FFmpeg binaries are GPL; this package stays MIT). Install ffmpeg yourself: brew install ffmpeg."
+  },
+  "scripts": {
+    "test": "node --test vendor/drp-format/__tests__/ vendor/drt-format/__tests__/ vendor/drx-codec/__tests__/ test/",
+    "test:libs": "node --test vendor/drp-format/__tests__/ vendor/drt-format/__tests__/ vendor/drx-codec/__tests__/",
+    "test:server": "node --test test/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "prettier": "^3.9.4"
+  }
+}