davinci-resolve-mcp 2.63.0 → 2.63.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.63.1
+
+Documentation-only. Records the `Graph.SetLUT` master-LUT-dir behavior (from the
+v2.62.3 fix) in the canonical reference surfaces. No code or tool-surface change.
+
+### Documentation
+
+- **`api_truth` + api-limitations report** — added a `Graph.SetLUT` entry
+  (`submit: bug`, #90): `SetLUT` resolves LUT paths only against the master
+  (system) LUT dir and configured custom paths, never the per-user dir the
+  `dctl` tool installs to; an absolute user-dir path fails too, and
+  `RefreshLUTList()` does not help, while a master-subfolder path resolves.
+  Verified live on Studio 19.1.3.7 (same behavior reported on 21.0.2 in #90).
+  Regenerated `docs/reference/api-limitations.md`.
+- **`docs/notes/lut-notes.md`** — corrected a misleading claim that any valid
+  absolute path resolves (an absolute path into the user LUT dir does not),
+  added a "master LUT dir only" section, and documented the per-user install
+  location.
+- **`docs/notes/dctl-notes.md`** — noted the same caveat on the `set_lut`
+  action, including that `set_lut` now auto-relocates into the master dir.
+
 ## What's New in v2.63.0
 
 Waveform silence ripple for the edit engine (PR #91, by @EliteSystemsAI),

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.63.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.63.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/notes/dctl-notes.md

@@ -19,7 +19,12 @@ Relevant existing actions:
   Resolve's LUT folders.
 - `graph(action="set_lut", params={"node_index": 1, "lut_path": "..."})`
   wraps `Graph.SetLUT(nodeIndex, lutPath)`. DCTLs that Resolve exposes through
-  LUT selection follow the same discovery constraints as LUTs.
+  LUT selection follow the same discovery constraints as LUTs. **Caveat:**
+  `install` writes to the per-user LUT dir, but `SetLUT` resolves only against
+  the *master* LUT dir (not even an absolute user-dir path works, and
+  `refresh_luts` does not help). `set_lut` now auto-relocates the file into an
+  `MCP/` subfolder of the master dir and retries — see `docs/notes/lut-notes.md`
+  ("master LUT dir only") and the `Graph.SetLUT` entry in `api_truth.py`.
 - `graph(action="get_lut", params={"node_index": 1})` wraps `Graph.GetLUT()`.
 - `graph(action="get_tools_in_node", ...)` may report ResolveFX tools present
   in a Color page node, but the scripting API does not expose a general

package/docs/notes/lut-notes.md

@@ -21,8 +21,32 @@ The scripting API already exposes the important LUT operations:
   can include LUTs in a `.drp` export.
 
 `SetLUT()` uses 1-based node indexes and succeeds only for LUT paths Resolve has
-already discovered. The `lut_path` may be absolute or relative to Resolve's
-master/custom LUT paths.
+already discovered.
+
+### `SetLUT` resolves against the master LUT dir only
+
+Resolve resolves the `lut_path` given to `SetLUT()` **only against the master
+(system) LUT directory and its configured custom LUT paths — not the per-user
+LUT directory** that the `dctl` tool and Project-level LUT installs write to.
+This trips up the obvious workflow (install a LUT/DCTL, then apply it):
+
+- A bare basename that lives only in the user LUT dir returns `False`.
+- An **absolute path into the user LUT dir also returns `False`** — absolute
+  paths are not a workaround.
+- `project_settings(action="refresh_luts")` (`RefreshLUTList()`) does **not**
+  change this; the file is discovered but still not resolvable by `SetLUT`.
+- A **subfolder-relative** path under the master root (e.g. `MCP/Foo.cube`)
+  *does* resolve.
+
+Verified live on Studio 19.1.3.7; the same behavior was reported on 21.0.2
+(PR #90), so it is not version-specific. See the `Graph.SetLUT` entry in
+`src/utils/api_truth.py`.
+
+`graph.set_lut` (and the granular `graph_set_lut`) handle this automatically:
+on a `False` return they stage the LUT into an `MCP/` subfolder of the master
+LUT dir, refresh, and retry, returning `resolved_lut` on success. If you call
+`Graph.SetLUT` directly, relocate the file into the master dir yourself first
+(`src.utils.lut_paths.ensure_lut_in_master`).
 
 ## Cube LUT Format
 
@@ -100,16 +124,25 @@ Blackmagic's examples live in the installed LUT folder:
 Example built-in LUT categories include `VFX IO`, `Blackmagic Design`, and
 `ACES`.
 
+The `dctl` tool and Project-level LUT installs instead write to the **per-user**
+LUT dir (macOS `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/LUT`,
+Windows `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\LUT`). Files there
+are discovered by the LUT browser but are **not** resolvable by `SetLUT` until
+relocated into the master dir above — see "master LUT dir only".
+
 ## Practical Failure Checks
 
 If `graph.set_lut` fails or `graph.get_lut` returns empty:
 
 - Confirm the current page/context has a valid Color graph and the node index is
   1-based.
-- Confirm the LUT file is in a Resolve LUT folder or is referenced by a valid
-  absolute path.
+- Confirm the LUT is in the **master** LUT folder (or a configured custom LUT
+  path) — not just the per-user LUT dir. A file only in the user dir fails even
+  by absolute path (see "master LUT dir only" above). `graph.set_lut` relocates
+  it for you; a direct `Graph.SetLUT` call does not.
 - Call `project_settings(action="refresh_luts")` after adding or changing LUT
-  files.
+  files (note: refresh alone does not make a user-dir LUT resolvable by
+  `SetLUT`).
 - Check the `.cube` header and row count. 3D LUTs must contain exactly
   `N * N * N` rows.
 - Confirm the file extension is `.cube` and the content is plain text.

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 19 missing capabilities, 11 bugs / unreliable behaviors.
+**Totals:** 19 missing capabilities, 12 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -265,3 +265,12 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** After writing 'Reel Name', read it back with GetClipProperty('Reel Name') and refuse to report success on mismatch; surface the project-setting gate to the caller (server._verify_clip_property_writeback).
 - **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
 - **Tags:** unreliable-return, silent-failure, metadata, reel-name
+
+### Graph.SetLUT (master-LUT-dir-only resolution)
+
+- **Object:** `Graph`
+- **Signature:** `(nodeIndex, lutPath) -> bool`
+- **Behavior:** SetLUT resolves lutPath ONLY against the master (system) LUT directory and its configured custom LUT paths -- NOT the per-user LUT dir that the dctl tool / Project LUT install writes to. A bare basename in the user dir returns False, and so does an ABSOLUTE path pointing into the user dir; RefreshLUTList() does not change this. A subfolder-relative path under the master root (e.g. 'MCP/Foo.cube') DOES resolve. Net effect: a LUT/DCTL the dctl tool just installed can never be applied by SetLUT as-is, so set_lut used to always return {success: false}. Verified live on Studio 19.1.3.7 (basename and absolute user-dir path both False, before and after RefreshLUTList; master-dir and master-subfolder paths True); the originating report (PR #90) observed the same on 21.0.2, so it is not version-specific.
+- **Workaround / current handling:** On a False return, locate the LUT, copy it into a namespaced subfolder of the master LUT dir (MCP/, so it does not clobber stock LUTs by basename), call RefreshLUTList(), and retry with the master-relative path. graph.set_lut and the granular graph_set_lut now do this automatically via src.utils.lut_paths.ensure_lut_in_master.
+- **Reference:** [issue #90](https://github.com/samuelgursky/davinci-resolve-mcp/issues/90)
+- **Tags:** color, lut, path-resolution, silent-failure

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.63.0"
+VERSION = "2.63.1"
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.63.0",
+  "version": "2.63.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.63.0"
+VERSION = "2.63.1"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.63.0"
+VERSION = "2.63.1"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -564,6 +564,35 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "when mirroring keep-ranges into clipInfos.",
         "tags": ["timeline", "edit", "off-by-one", "readback"],
     },
+    {
+        "symbol": "Graph.SetLUT (master-LUT-dir-only resolution)",
+        "object": "Graph",
+        "signature": "(nodeIndex, lutPath) -> bool",
+        "reality": "SetLUT resolves lutPath ONLY against the master (system) LUT "
+                   "directory and its configured custom LUT paths -- NOT the "
+                   "per-user LUT dir that the dctl tool / Project LUT install "
+                   "writes to. A bare basename in the user dir returns False, and "
+                   "so does an ABSOLUTE path pointing into the user dir; "
+                   "RefreshLUTList() does not change this. A subfolder-relative "
+                   "path under the master root (e.g. 'MCP/Foo.cube') DOES resolve. "
+                   "Net effect: a LUT/DCTL the dctl tool just installed can never "
+                   "be applied by SetLUT as-is, so set_lut used to always return "
+                   "{success: false}. Verified live on Studio 19.1.3.7 (basename "
+                   "and absolute user-dir path both False, before and after "
+                   "RefreshLUTList; master-dir and master-subfolder paths True); "
+                   "the originating report (PR #90) observed the same on 21.0.2, "
+                   "so it is not version-specific.",
+        "recommended": "On a False return, locate the LUT, copy it into a "
+                       "namespaced subfolder of the master LUT dir (MCP/, so it "
+                       "does not clobber stock LUTs by basename), call "
+                       "RefreshLUTList(), and retry with the master-relative path. "
+                       "graph.set_lut and the granular graph_set_lut now do this "
+                       "automatically via src.utils.lut_paths.ensure_lut_in_master.",
+        "tags": ["color", "lut", "path-resolution", "silent-failure"],
+        "submit": "bug",
+        "issue": 90,
+        "mitigation": ["_ensure_lut_in_master"],
+    },
 ]