davinci-resolve-mcp 3.1.1 → 3.2.1

package/CHANGELOG.md

@@ -2,6 +2,97 @@
 
 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 v3.2.1 — three correctness fixes to the LUT tool
+
+Contributed by @Dev-next-gen (#225, #226, #227), each found by reading the v3.2.0
+`lut` tool rather than by hitting it in use.
+
+### Fixed
+
+- **`install` reported `overwritten: true` on a fresh write.** The flag was
+  `bool(overwrite and payload is not None)`, and `payload` can never be `None`
+  where that line runs, so the field handed the caller's own `overwrite`
+  argument back instead of an observation. An install passing `overwrite=true`
+  for idempotence, landing on an empty `MCP/`, was reported as having replaced
+  existing work. `execution_lifecycle` rates `lut install` MEDIUM precisely
+  because it "can replace with overwrite=true", so this flag is what a caller
+  and the execution trace read to learn whether an install destroyed anything.
+  It is now the `os.path.exists` observation already taken one line above — the
+  measured pre-state, not the permission. (#225)
+- **`install(source_path=...)` could not copy a binary LUT.** The copy went
+  through a UTF-8 text round-trip, so the two binary extensions this server
+  advertises — `.dat` and `.olut` — raised `UnicodeDecodeError` before anything
+  was written, surfacing as `LUT_ERROR`. So did an ordinary `.cube` whose vendor
+  wrote its `TITLE` line in latin-1. The file-copy branch is now byte-exact; the
+  text branch (`source=`) is unchanged. (#226)
+- **`list` marked siblings of the writable subdir as writable.** The `writable`
+  flag used `realpath(current).startswith(writable_root)`, a string prefix with
+  no separator, so `MCP_old/` left by a hand backup or a vendor pack unpacking
+  as `MCPresets/` cleared it. The listing then contradicted the only tool that
+  consumes the flag: `remove` resolves names inside `MCP/` and refused the very
+  `set_lut_path` the listing had just handed out. It now compares by path
+  segment with `commonpath`, which is what `_is_relative_to` and `resolve_writable`
+  already use elsewhere in this repo. Nothing that worked before stops working —
+  the flag only flips for paths `remove` was already refusing. (#227)
+
+## What's New in v3.2.0 — LUT files: find them, install them, remove them, gated
+
+Contributed by @legionsound (#223), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **The `lut` tool** — `path`, `list`, `read`, `install`, `remove`, `attenuate`,
+  `capabilities` — and seven granular twins. `graph set_lut` could already put
+  a LUT on a node, but nothing answered the question it raises: which LUTs
+  exist? This closes the gap against Blackmagic's own `list_luts` and
+  `delete_lut`, and matches what `dctl` already offered for shaders in the same
+  directory tree. Tool count 36/377 → 37/384.
+- **Reads roam, writes do not.** `list` and `read` walk the whole master LUT
+  root, so stock, vendor and hand-installed LUTs are all discoverable. `install`,
+  `remove` and `attenuate` touch only the namespaced `MCP/` subfolder: stock and
+  vendor LUTs are never modified or removed. Every listing reports `set_lut_path`
+  in the exact form `graph set_lut` accepts.
+- **The master root, not the per-user LUT folder**, because `Graph.SetLUT`
+  resolves names only against the master root.
+
+### Gating
+
+- **Gated from its first release**, the way v3.0.0 gates plugin-folder writes.
+  The tool carries `@_destructive_op`. `install` and `attenuate` are MEDIUM, and
+  `remove` is HIGH, so it is blocked in safe mode. All three honour `dry_run`
+  natively, are audited, and sit in the non-timeline exemption. The
+  write-enforcement ratchet passes with nothing added to its backlog, making this
+  the first new tool to land under it.
+- **No code execution.** Blackmagic's `generate_lut` evaluates a caller-supplied
+  function at every lattice point, and this server does not execute caller code.
+  So authoring is limited to writing a provided `.cube`, and to blending an
+  existing LUT toward identity. `lut capabilities` reports
+  `generate_from_code: false` together with the reason.
+
+### Changed
+
+- Adapted on merge: the granular `remove_lut_file` is labelled
+  `EXTERNAL_DESTRUCTIVE_TOOL` rather than `EXTERNAL_WRITE_TOOL`. The granular
+  server has no gate decorator, so for it the MCP annotation is the signal a
+  client reads, and a file delete labelled a plain write undersold it. A test
+  pins the label.
+
+### Validation
+
+- Full suite green: 3,549 passed, 1 skipped.
+- Live evidence is @legionsound's on Studio 21.1.0.14, and it covers the claim
+  the tool rests on: install → `refresh_luts` → `graph set_lut` → `get_lut`,
+  then a rendered TIFF, through both interfaces. A solid-red clip's centre pixel
+  went from `[255, 0, 0]` to `[0, 255, 0]` under a constant-green LUT, and the
+  relocation fallback did not fire, so the installed path resolved on its own.
+  Discovery listed 249 LUTs identically through both interfaces with Resolve
+  closed. Three containment checks are kept as tests: `../escaped.cube` is
+  refused, removing a stock LUT is refused, and a re-install without
+  `overwrite` is refused. Not reproduced here.
+- **Not claimed**: LUT formats other than 3D `.cube`; `layer_index` above 1 and
+  colour-group graphs; `attenuate` against a real vendor LUT; the Windows and
+  Linux master roots; and a read-only master root.
+
 ## What's New in v3.1.1 — chat-drafted issues are labelled for every reporter
 
 A repository workflow change. Nothing in the server or the npm package behaves

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.1.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.2.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-36%20(377%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(384%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -132,8 +132,8 @@ The command starts a loopback-only server and opens the control panel in your br
 
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
-| Compound | `src/server.py` | 36 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 377 | Power users who want one MCP tool per Resolve API method. |
+| Compound | `src/server.py` | 37 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 384 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -365,7 +365,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **36** compound / **377** granular (live server) |
+| MCP Tools | **37** compound / **384** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-3.1.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.2.0-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-36%20(377%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(384%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v3.1.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v3.2.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -87,8 +87,8 @@ venv/bin/python -m src.control_panel
 
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
-| Compound（复合） | `src/server.py` | 36 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 377 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Compound（复合） | `src/server.py` | 37 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 384 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **36** 复合 / **377** 细粒度（实时服务器） |
+| MCP 工具 | **37** 复合 / **384** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -352,8 +352,8 @@ to the user as verified.
 
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
-| Compound (default) | `src/server.py` | 36 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 377 tools | Power users needing one tool per API method |
+| Compound (default) | `src/server.py` | 37 tools | Most workflows — keeps context lean |
+| Granular (full) | `src/server.py --full` | 384 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades

package/docs/contributing.md

@@ -63,7 +63,7 @@ This MCP server controls DaVinci Resolve via its Scripting API. Some tools perfo
 davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
-│   ├── server.py                # Compound MCP server — 36 tools (default)
+│   ├── server.py                # Compound MCP server — 37 tools (default)
 │   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 377 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers

package/docs/install.md

@@ -143,8 +143,8 @@ The MCP server comes in two modes:
 
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
-| **Compound** (default) | `src/server.py` | 36 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 377 | Power users who want one tool per API method |
+| **Compound** (default) | `src/server.py` | 37 | Most users — fast, clean, low context usage |
+| **Full** | `src/resolve_mcp_server.py` | 384 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 377-tool server
+python src/server.py --full    # Launch full 384-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -23,9 +23,9 @@ additions are tracked separately in the section below.
 
 Every non-deprecated method in the bundled legacy README is represented. This
 does not claim complete coverage of the newer Resolve 21.1 typed API. The
-default compound server exposes **36 tools** that group related operations by
+default compound server exposes **37 tools** that group related operations by
 action parameter, keeping LLM context windows lean. The full granular server
-provides **377 individual tools** for power users. The legacy coverage spans
+provides **384 individual tools** for power users. The legacy coverage spans
 13 API object classes. MCP-level kernel actions are tracked separately in
 [Kernel Action Coverage](../kernels/README.md).
 
@@ -34,6 +34,11 @@ are implemented in both interfaces and were live-measured by a contributor on
 Studio 21.1.0.14. Their evidence and limitations are recorded separately from
 the historical aggregate above.
 
+Parity with Blackmagic's own MCP surfaced one more gap: it exposes
+`list_luts`/`generate_lut`/`delete_lut`, and this server could set a LUT on a
+node but never list, install or remove LUT files. The `lut` tool and its
+granular twins close that. See [LUT file controls](lut-file-controls.md).
+
 The 34th compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the
 version-on-mutate hook that auto-archives the working timeline before any

package/docs/reference/lut-file-controls.md

@@ -0,0 +1,85 @@
+# LUT file controls
+
+`graph set_lut` could already put a LUT on a node, and `export_lut` could pull
+one out of a grade. Nothing answered the question `set_lut` raises: **which
+LUTs exist?** There was no listing, no install and no removal — even though the
+same needs for DCTL shaders are served by the `dctl` tool, in the same directory
+tree, and `project_settings refresh_luts` exists precisely because files get
+added by something else.
+
+Blackmagic's own MCP exposes `list_luts`, `generate_lut` and `delete_lut`. This
+closes that gap.
+
+## Two rules
+
+**Reads roam, writes do not.** `list` and `read` walk the whole master LUT root,
+so stock, vendor and hand-installed LUTs are all discoverable. `install`,
+`remove` and `attenuate` write only inside the namespaced `MCP/` subfolder —
+the same confinement Blackmagic's MCP applies to its own write tools. Stock and
+vendor LUTs are never modified or removed here.
+
+**Master root, not the user LUT dir.** `Graph.SetLUT()` resolves relative names,
+and even absolute paths, only against the master root — never the per-user dir
+the `dctl` tool installs into. That is measured behaviour already recorded in
+`utils/lut_paths.py`, so installs land where `set_lut` can reach them, and every
+listing reports `set_lut_path` in the exact form `set_lut` accepts.
+
+## Live results
+
+Measured against a real LUT tree of 249 LUTs. Resolve was **not** running, which
+is itself worth noting: these are filesystem operations, so discovery works
+whether or not Resolve is up, where Blackmagic's `list_luts` refuses without it.
+
+| Check | Result |
+| --- | --- |
+| LUTs discovered | 249 |
+| Compound and granular listings identical | yes |
+| Install | `MCP/mcp_live_probe.cube`, 179 bytes, appeared in listing, marked writable, count +1 |
+| Read | parsed, size 2, 8 entries, whole table not returned |
+| Re-install without `overwrite` | refused |
+| Path traversal (`../escaped.cube`) | refused, no file created outside the root |
+| Removing a stock LUT | refused, file intact |
+| Cleanup | probe removed, count back to 249 |
+
+## Application proof
+
+The tool's purpose rests on one claim: the `set_lut_path` that `install` returns
+is resolved by `Graph.SetLUT` on a live node. Measured on Studio 21.1.0.14 in a
+disposable project, with a solid-red clip and a constant-green 3D LUT so that
+application is unmistakable in decoded pixels. Each row is a real render.
+
+| Path | set_lut | Readback | Rendered centre pixel |
+| --- | --- | --- | --- |
+| Baseline, no LUT | — | — | `[255, 0, 0]` |
+| Compound: `lut install` → `refresh_luts` → `graph set_lut` → `get_lut` | True, no fallback | `MCP/mcp_apply_probe_compound.cube` | `[0, 255, 0]` |
+| Granular: `install_lut_file` → `refresh_lut_list` → `graph_set_lut` → `graph_get_lut` | True, no fallback | `MCP/mcp_apply_probe_granular.cube` | `[0, 255, 0]` |
+
+"No fallback" matters: the compound `set_lut` has a relocation retry for LUTs
+outside the master root, and a success through that retry would have hidden
+whether the installed path resolved on its own. It did not fire in either run.
+
+Three native facts came out of it. `SetLUT` on a just-installed path works
+immediately after `RefreshLUTList`, with no delay. `GetLUT` reads back the exact
+master-relative path. `SetLUT(1, "")` clears the node.
+
+Two pre-existing behaviours worth knowing, neither changed here: the compound
+`graph` tool targets the **timeline** node graph by default, which had no nodes,
+so `set_lut` on a clip needs `source="item"`; and compound `get_lut` answers
+`{lut}` where granular `graph_get_lut` answers `{lut_path}`.
+
+## Not ported from the official MCP
+
+Its `generate_lut` takes a Python function body from the caller and executes it
+on every lattice point. This server does not execute caller-supplied code, so
+authoring here is limited to declarative operations already implemented in
+`utils/cube_lut.py`: writing a provided `.cube`, and blending an existing one
+toward identity. `capabilities` says so explicitly rather than leaving a caller
+to guess why `generate` is missing.
+
+## Scope
+
+Application was proved for a 3D `.cube` on a clip's first node graph. Other LUT
+formats, `layer_index` > 1 graphs and colour-group graphs were not measured.
+`attenuate` is unit-tested for bounds and missing sources but was not run
+against a real vendor LUT. Windows and Linux master roots, and a read-only
+master root, are untested.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "3.1.1"
+VERSION = "3.2.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
@@ -1543,7 +1543,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "36 compound · 377 full · 3 platforms"
+    subtitle = "37 compound · 384 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "3.1.1"
+VERSION = "3.2.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/granular/graph.py

@@ -2,6 +2,7 @@
 
 from src.granular.common import *  # noqa: F401,F403
 from src.utils.lut_paths import ensure_lut_in_master
+from src.utils import lut_files
 
 resolve = ResolveProxy()
 
@@ -325,3 +326,121 @@ def get_color_group_post_clip_node_graph(group_name: str) -> Dict[str, Any]:
     if graph:
         return {"group": group_name, "graph_type": "post_clip", "num_nodes": graph.GetNumNodes()}
     return {"error": "No post-clip node graph available"}
+
+
+def _lut_error(exc):
+    return {"error": str(exc)}
+
+
+@mcp.tool()
+def get_lut_directories() -> Dict[str, Any]:
+    """Report Resolve's master LUT directory and the folder this server writes to.
+
+    Installs go to the MASTER root, not the per-user LUT dir the dctl tool
+    uses: Graph.SetLUT() resolves LUT names only against the master root.
+    """
+    return {"lut_dir": lut_files.master_lut_dir(),
+            "writable_dir": lut_files.writable_dir()}
+
+
+@mcp.tool()
+def list_lut_files(subdir: Optional[str] = None) -> Dict[str, Any]:
+    """List LUT files Resolve can see, with the path graph_set_lut accepts.
+
+    Walks the whole master LUT root so stock, vendor and installed LUTs all
+    appear. Each entry reports set_lut_path (master-relative, the form
+    Graph.SetLUT resolves) and whether this server may remove it.
+
+    Args:
+        subdir: Optional folder under the master LUT root to limit the walk to.
+    """
+    try:
+        return lut_files.list_luts(subdir)
+    except lut_files.LutPathError as exc:
+        return _lut_error(exc)
+
+
+@mcp.tool()
+def read_lut_file(name: str) -> Dict[str, Any]:
+    """Summarize a 3D .cube LUT: size, title, domain. Never the whole table.
+
+    Args:
+        name: Master-relative path, e.g. "MCP/warm.cube".
+    """
+    try:
+        return lut_files.read_lut_summary(name)
+    except (lut_files.LutPathError, OSError, ValueError) as exc:
+        return _lut_error(exc)
+
+
+@mcp.tool(annotations=EXTERNAL_WRITE_TOOL)
+def install_lut_file(name: str, source: Optional[str] = None,
+                     source_path: Optional[str] = None,
+                     overwrite: bool = False) -> Dict[str, Any]:
+    """Install a LUT into the writable MCP folder under the master LUT root.
+
+    Refuses an existing destination unless overwrite is set. Call
+    refresh_lut_list() afterwards so Resolve picks the file up.
+
+    Args:
+        name: File name, e.g. "warm.cube". Relative only; .cube if no extension.
+        source: LUT file text. Provide this or source_path, not both.
+        source_path: A LUT file on disk to copy in.
+        overwrite: Replace an existing file of the same name.
+    """
+    try:
+        return lut_files.install_lut(name, source=source, source_path=source_path,
+                                     overwrite=overwrite)
+    except (lut_files.LutPathError, OSError) as exc:
+        return _lut_error(exc)
+
+
+@mcp.tool(annotations=EXTERNAL_DESTRUCTIVE_TOOL)
+def remove_lut_file(name: str) -> Dict[str, Any]:
+    """Delete a LUT from the writable MCP folder only.
+
+    Stock and vendor LUTs live outside it and are not removable here.
+
+    Args:
+        name: File name under MCP/, e.g. "warm.cube".
+    """
+    try:
+        return lut_files.remove_lut(name)
+    except (lut_files.LutPathError, OSError) as exc:
+        return _lut_error(exc)
+
+
+@mcp.tool(annotations=EXTERNAL_WRITE_TOOL)
+def attenuate_lut_file(source: str, strength: float, name: str) -> Dict[str, Any]:
+    """Blend an existing .cube toward identity and install the result.
+
+    Reads from anywhere under the master LUT root, writes only into MCP/.
+    Refuses a non-unit DOMAIN_MIN/MAX, because identity is only identity on
+    a 0..1 domain.
+
+    Args:
+        source: Master-relative path of the LUT to weaken.
+        strength: 0.0 (identity) to 1.0 (unchanged).
+        name: Output file name under MCP/.
+    """
+    try:
+        return lut_files.attenuate_lut(source, strength, name)
+    except (lut_files.LutPathError, OSError, ValueError) as exc:
+        return _lut_error(exc)
+
+
+@mcp.tool()
+def get_lut_file_capabilities() -> Dict[str, Any]:
+    """What this server can do with LUT files, and what it refuses.
+
+    Notably it will not generate a LUT from caller-supplied Python code.
+    """
+    from src.utils import cube_lut
+    caps = dict(cube_lut.capabilities())
+    caps["writable_dir"] = lut_files.writable_dir()
+    caps["extensions"] = list(lut_files.LUT_EXTENSIONS)
+    caps["generate_from_code"] = False
+    caps["generate_from_code_reason"] = (
+        "This server does not execute caller-supplied Python. Use "
+        "install_lut_file with .cube text, or attenuate_lut_file.")
+    return caps

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (377 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (384 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -2,7 +2,7 @@
 """
 DaVinci Resolve MCP Server (Compound Tools)
 
-36 compound tools covering 100% of the DaVinci Resolve Scripting API (336 methods)
+37 compound tools covering 100% of the DaVinci Resolve Scripting API (336 methods)
 plus Fusion Fuse, DCTL, and Resolve-page Script authoring tools.
 Each tool groups related operations via an 'action' parameter.
 
@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "3.1.1"
+VERSION = "3.2.1"
 
 import base64
 import os
@@ -52,6 +52,7 @@ from src.utils.resolve211_edits import validate_edit_options, validate_transitio
 
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
+from src.utils import lut_files
 from src.utils import resolve_writes as _resolve_writes
 from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
@@ -384,7 +385,7 @@ def davinci_resolve_workflow() -> str:
     return """Use this DaVinci Resolve MCP server as a guarded post-production control surface.
 
 Core pattern:
-- Prefer the 36 compound tools and their action names over raw scripting.
+- Prefer the 37 compound tools and their action names over raw scripting.
 - Start by probing state: resolve_control.get_version/get_page, project_manager.get_current, timeline.get_current, and media_pool.probe_media_pool.
 - Before mutating timelines, media pools, render settings, grades, projects, databases, or extensions, prefer the matching probe, capabilities, boundary_report, safe_*, or dry_run action when one exists.
 - Preserve source media integrity. Never transcode, proxy, rewrite, move, rename, or create derivatives of source media unless the user explicitly asks. Analysis output belongs in sidecars or analysis directories.
@@ -31199,6 +31200,101 @@ def _validate_dctl_source(source: str) -> Dict[str, Any]:
 _DCTL_VALID_CATEGORIES = ("lut", "aces_idt", "aces_odt")
 
 
+@mcp.tool()
+@_guard_missing_params
+@_destructive_op("lut")
+def lut(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Discover, install and remove LUT files under Resolve's master LUT root.
+
+    `graph set_lut` could already put a LUT on a node, but nothing answered the
+    question it raises — which LUTs exist? These actions do, and they report
+    each LUT's master-relative `set_lut_path`, which is the exact form
+    `set_lut` resolves.
+
+    Reads roam, writes do not. `list` and `read` walk the whole master LUT root
+    so stock, vendor and hand-installed LUTs are discoverable. `install`,
+    `remove` and `attenuate` write only inside the namespaced `MCP/` subfolder,
+    so stock and vendor LUTs are never modified or removed here.
+
+    Installs land in the MASTER root, not the per-user LUT dir the `dctl` tool
+    uses: Graph.SetLUT() resolves names only against the master root (measured;
+    see utils/lut_paths.py). After installing, call
+    project_settings(action='refresh_luts') before applying.
+
+    Actions:
+      path() -> {lut_dir, writable_dir}
+      list(subdir?) -> {luts, count, lut_dir, writable_dir}
+        — each entry: {name, set_lut_path, bytes, writable}
+      read(name) -> {size, title, domain_min, domain_max, entries, ...}
+        — 3D .cube only; reports shape and header, never the whole table.
+      install(name, source | source_path, overwrite?) -> {success, set_lut_path}
+        — source: .cube text. source_path: a file to copy in. Exactly one.
+      remove(name) -> {success, removed}
+        — MCP/ only.
+      attenuate(source, strength, name) -> {success, set_lut_path, ...}
+        — blend an existing .cube toward identity, 0..1, and install the result.
+      capabilities() -> {numpy_available, supported, refused, size_range}
+
+    Not provided: the official MCP's generate_lut executes a caller-supplied
+    Python function body per lattice point. This server does not accept
+    caller-supplied code, so authoring here is limited to writing a provided
+    .cube and attenuating an existing one.
+    """
+    p = _params(params)
+    try:
+        if action == "path":
+            return {"lut_dir": lut_files.master_lut_dir(),
+                    "writable_dir": lut_files.writable_dir()}
+        if action == "list":
+            return lut_files.list_luts(p.get("subdir"))
+        if action == "read":
+            if not p.get("name"):
+                return _err("read requires name")
+            return lut_files.read_lut_summary(p["name"])
+        if action == "capabilities":
+            from src.utils import cube_lut
+            caps = dict(cube_lut.capabilities())
+            caps["writable_dir"] = lut_files.writable_dir()
+            caps["extensions"] = list(lut_files.LUT_EXTENSIONS)
+            caps["generate_from_code"] = False
+            caps["generate_from_code_reason"] = (
+                "This server does not execute caller-supplied Python. Use install "
+                "with .cube text, or attenuate an existing LUT.")
+            return caps
+        if action == "install":
+            if not p.get("name"):
+                return _err("install requires name")
+            if p.get("dry_run"):
+                return _ok(would_install=p["name"], writable_dir=lut_files.writable_dir())
+            return lut_files.install_lut(
+                p["name"], source=p.get("source"), source_path=p.get("source_path"),
+                overwrite=bool(p.get("overwrite", False)))
+        if action == "remove":
+            if not p.get("name"):
+                return _err("remove requires name")
+            if p.get("dry_run"):
+                return _ok(would_remove=p["name"], writable_dir=lut_files.writable_dir())
+            return lut_files.remove_lut(p["name"])
+        if action == "attenuate":
+            for required in ("source", "strength", "name"):
+                if p.get(required) is None:
+                    return _err(f"attenuate requires {required}")
+            if p.get("dry_run"):
+                return _ok(would_write=p["name"], source=p["source"], strength=p["strength"])
+            return lut_files.attenuate_lut(p["source"], p["strength"], p["name"])
+    except lut_files.LutPathError as exc:
+        return _err(str(exc), code="INVALID_LUT_PATH", category="invalid_input")
+    except FileNotFoundError as exc:
+        return _err(str(exc), code="LUT_NOT_FOUND", category="invalid_input")
+    except OSError as exc:
+        return _err(f"{type(exc).__name__}: {exc}", code="LUT_IO_ERROR",
+                    category="filesystem")
+    except Exception as exc:
+        return _err(f"{type(exc).__name__}: {exc}", code="LUT_ERROR")
+    return _unknown(action, ["path", "list", "read", "install", "remove",
+                             "attenuate", "capabilities"])
+
+
 @mcp.tool()
 @_guard_missing_params
 @_destructive_op("dctl")
@@ -32605,5 +32701,5 @@ if __name__ == "__main__":
         logger.error(f"Unknown --transport {transport!r}; use stdio|sse|streamable-http")
         sys.exit(2)
 
-    logger.info("Starting DaVinci Resolve MCP Server (36 compound tools)")
+    logger.info("Starting DaVinci Resolve MCP Server (37 compound tools)")
     run_fastmcp_stdio(mcp)

package/src/utils/destructive_hook.py

@@ -70,6 +70,10 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
     # real. They never mutate the timeline, so NON_TIMELINE_WRITE_TOOLS keeps
     # them out of timeline archiving while every gate still sees them.
     "dctl": frozenset({"encrypt_native", "install", "remove"}),
+    # LUT files under Resolve's master LUT root. Writes are confined to the
+    # namespaced MCP/ subfolder by src/utils/lut_files.py; these entries make
+    # every gate see them as the writes they are.
+    "lut": frozenset({"attenuate", "install", "remove"}),
     "fuse_plugin": frozenset({"install", "remove"}),
     "script_plugin": frozenset({
         "install",
@@ -280,7 +284,7 @@ NO_ARCHIVE_ON_KEYS: Dict[Tuple[str, str], frozenset] = {
 # that there is no project state to log.
 
 NON_TIMELINE_WRITE_TOOLS: frozenset = frozenset({
-    "dctl", "fuse_plugin", "script_plugin",
+    "dctl", "fuse_plugin", "lut", "script_plugin",
     "folder", "gallery_stills", "media_pool_item", "media_pool_item_markers",
     "project_manager", "project_settings", "render", "render_presets",
     "resolve_control",
@@ -354,6 +358,9 @@ NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
     ("script_plugin", "safe_install_extension"),
     ("script_plugin", "safe_remove_extension"),
     ("project_manager", "safe_project_delete"),
+    ("lut", "attenuate"),
+    ("lut", "install"),
+    ("lut", "remove"),
 })
 
 

package/src/utils/execution_lifecycle.py

@@ -142,6 +142,9 @@ class RiskClassificationHook(LifecycleHook):
         ("fuse_plugin", "remove"),
         ("script_plugin", "remove"),
         ("script_plugin", "safe_remove_extension"),
+        # LUT deletes. Confined to the MCP/ subfolder, but permanent, and the
+        # file may be applied on a node in some open project.
+        ("lut", "remove"),
         # Guarded delete: disposable `_mcp_` projects only, and the open one
         # only with close_current=True — but still permanent.
         ("project_manager", "safe_project_delete"),
@@ -262,6 +265,11 @@ class RiskClassificationHook(LifecycleHook):
         ("fuse_plugin", "install"),
         ("script_plugin", "install"),
         ("script_plugin", "safe_install_extension"),
+        # LUT installs write into the folder Resolve loads LUTs from, like the
+        # plugin installs above. `install` can replace with overwrite=true;
+        # `attenuate` refuses an existing destination but writes the same tree.
+        ("lut", "install"),
+        ("lut", "attenuate"),
         # 21.0 AI deblur renders NEW media and never touches the source (it is
         # confirm-token gated for that reason). The `remove_` prefix rule rated
         # it HIGH on its name alone, which would make safe mode block a create.

package/src/utils/lut_files.py

@@ -0,0 +1,305 @@
+"""LUT file discovery and safe installation under Resolve's master LUT root.
+
+The server could already put a LUT on a node (`graph set_lut`) and pull one out
+of a grade (`export_lut`), but nothing could answer the question `set_lut`
+raises: *which LUTs exist?* There was no listing, no install and no removal,
+even though the same needs for DCTL shaders are served by the `dctl` tool and
+the two live in the same directory tree. Blackmagic's own MCP exposes
+`list_luts`, `generate_lut` and `delete_lut`; this closes that gap.
+
+Two rules shape everything here.
+
+**Reads roam, writes do not.** Listing walks the whole master LUT root so
+stock, vendor and hand-installed LUTs are all discoverable. Writing and
+deleting are confined to one namespaced subfolder, `MCP/`, which is the same
+confinement Blackmagic's own MCP applies to `generate_lut`/`delete_lut`. Stock
+and vendor LUTs are never modified or removed by this server.
+
+**Master root, not the user LUT dir.** `Graph.SetLUT()` resolves relative names
+— and even absolute paths — only against the master root, never the per-user
+dir the `dctl` tool installs into. That is measured behaviour recorded in
+`lut_paths`, so installs land where `set_lut` can actually reach them, and
+every listing reports the master-relative path in the exact form `set_lut`
+accepts.
+
+Deliberately **not** ported from the official MCP: its `generate_lut` takes a
+Python function body from the caller and executes it per lattice point. This
+server does not accept caller-supplied code, so LUT authoring here is limited
+to declarative operations already implemented in `cube_lut` — writing a
+provided `.cube` and attenuating an existing one toward identity.
+"""
+
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+from src.utils.lut_paths import MASTER_LUT_RELOCATE_SUBDIR, master_lut_dir
+
+# The extensions Resolve's LUT browser picks up, matching the official MCP's list.
+LUT_EXTENSIONS = (".3dl", ".cube", ".dat", ".lut", ".olut")
+
+# Writes and deletes are confined to this subfolder of the master root.
+WRITABLE_SUBDIR = MASTER_LUT_RELOCATE_SUBDIR
+
+
+class LutPathError(ValueError):
+    """A caller-supplied LUT name or subdir could not be used safely."""
+
+
+def writable_dir() -> str:
+    """The one directory this server installs into and deletes from."""
+    return os.path.join(master_lut_dir(), WRITABLE_SUBDIR)
+
+
+def _is_within(path: str, parent: str) -> bool:
+    """Whether ``path`` is ``parent`` itself or sits under it, compared by segment.
+
+    ``commonpath`` is the comparison the rest of the repo uses for confinement
+    checks (`media_analysis._is_relative_to`), and it is the only one that is
+    correct here: a string prefix test also accepts a sibling whose name merely
+    starts with the same characters.
+    """
+    try:
+        return os.path.commonpath([path, parent]) == parent
+    except (ValueError, OSError):
+        return False
+
+
+def normalize_relative(name: str, *, default_ext: Optional[str] = None) -> str:
+    """Validate a caller-supplied LUT name and return it as a POSIX relative path.
+
+    Rejects absolute paths, drive letters, empty segments and any `.`/`..`
+    segment, so a name can never escape the directory it is resolved against.
+    """
+    if not isinstance(name, str) or not name.strip():
+        raise LutPathError("name is required")
+    candidate = name.strip().replace("\\", "/")
+    if candidate.startswith("/") or (len(candidate) > 1 and candidate[1] == ":"):
+        raise LutPathError(f"name must be relative, not an absolute path: {name!r}")
+    parts = [segment.strip() for segment in candidate.split("/") if segment.strip()]
+    if not parts:
+        raise LutPathError("name is required")
+    for segment in parts:
+        if segment in (".", ".."):
+            raise LutPathError(f"unsafe path segment in {name!r}: {segment!r}")
+    relative = "/".join(parts)
+    if default_ext and not os.path.splitext(relative)[1]:
+        relative += default_ext
+    ext = os.path.splitext(relative)[1].lower()
+    if ext not in LUT_EXTENSIONS:
+        raise LutPathError(
+            f"{relative!r} is not a LUT file. Expected one of: "
+            + ", ".join(LUT_EXTENSIONS)
+        )
+    return relative
+
+
+def resolve_writable(name: str, *, default_ext: Optional[str] = ".cube") -> Tuple[str, str]:
+    """Return ``(absolute_path, master_relative_path)`` inside the writable subdir.
+
+    The second value is what `graph set_lut` wants, so a caller can install and
+    then apply without constructing a path by hand.
+    """
+    relative = normalize_relative(name, default_ext=default_ext)
+    absolute = os.path.join(writable_dir(), *relative.split("/"))
+    root = os.path.realpath(writable_dir())
+    if os.path.commonpath([root, os.path.realpath(os.path.dirname(absolute)) or root]) != root:
+        raise LutPathError(f"{name!r} resolves outside {WRITABLE_SUBDIR}/")
+    return absolute, f"{WRITABLE_SUBDIR}/{relative}"
+
+
+def list_luts(subdir: Optional[str] = None) -> Dict[str, Any]:
+    """Walk the master LUT root and report every LUT Resolve would see.
+
+    Each entry carries `set_lut_path` — the master-relative form `set_lut`
+    resolves — plus `writable`, which says whether this server may remove it.
+    """
+    root = master_lut_dir()
+    base = root
+    if subdir:
+        relative_parts = [s for s in subdir.replace("\\", "/").split("/") if s.strip()]
+        for segment in relative_parts:
+            if segment in (".", ".."):
+                raise LutPathError(f"unsafe subdir segment: {segment!r}")
+        base = os.path.join(root, *relative_parts)
+    if not os.path.isdir(base):
+        return {"lut_dir": root, "searched": base, "exists": False, "luts": [], "count": 0}
+
+    writable_root = os.path.realpath(writable_dir())
+    found: List[Dict[str, Any]] = []
+    for current, _dirs, files in os.walk(base):
+        for filename in sorted(files):
+            if os.path.splitext(filename)[1].lower() not in LUT_EXTENSIONS:
+                continue
+            absolute = os.path.join(current, filename)
+            relative = os.path.relpath(absolute, root).replace(os.sep, "/")
+            try:
+                size = os.path.getsize(absolute)
+            except OSError:
+                size = None
+            try:
+                # Segment-wise, not a string prefix: a sibling of the writable
+                # subdir whose name starts with it -- MCP_old/ after a manual
+                # backup, MCPresets/ from a vendor pack -- cleared
+                # `startswith(writable_root)` and was listed as writable, while
+                # `remove` resolves names under MCP/ and refuses the very path
+                # the listing handed back.
+                is_writable = _is_within(os.path.realpath(current), writable_root)
+            except OSError:
+                is_writable = False
+            found.append({
+                "name": filename,
+                "set_lut_path": relative,
+                "bytes": size,
+                "writable": is_writable,
+            })
+    found.sort(key=lambda row: row["set_lut_path"])
+    return {
+        "lut_dir": root,
+        "searched": base,
+        "exists": True,
+        "writable_dir": writable_dir(),
+        "luts": found,
+        "count": len(found),
+    }
+
+
+def install_lut(name: str, *, source: Optional[str] = None,
+                source_path: Optional[str] = None,
+                overwrite: bool = False) -> Dict[str, Any]:
+    """Write a LUT into the writable subdir from text or by copying a file.
+
+    Refuses an existing destination unless `overwrite` is set, so an install
+    never silently replaces something already in use.
+    """
+    if (source is None) == (source_path is None):
+        raise LutPathError("provide exactly one of source (text) or source_path (a file to copy)")
+    absolute, set_lut_path = resolve_writable(name)
+    existed = os.path.exists(absolute)
+    if existed and not overwrite:
+        raise LutPathError(
+            f"{set_lut_path} already exists. Pass overwrite=true to replace it."
+        )
+    if source_path is not None:
+        if not os.path.isfile(source_path):
+            raise LutPathError(f"source_path not found: {source_path}")
+        # A copy has to be byte-exact. Two of the extensions this server
+        # advertises -- .dat and .olut -- are binary, and a .cube carries its
+        # TITLE in whatever encoding the vendor wrote it in, so decoding the
+        # source as UTF-8 turned "install the LUT I already have on disk" into
+        # a UnicodeDecodeError surfacing as LUT_ERROR.
+        with open(source_path, "rb") as handle:
+            payload = handle.read()
+    else:
+        payload = source
+    if not payload.strip():
+        raise LutPathError("refusing to install an empty LUT")
+    os.makedirs(os.path.dirname(absolute), exist_ok=True)
+    if isinstance(payload, bytes):
+        with open(absolute, "wb") as handle:
+            handle.write(payload)
+    else:
+        with open(absolute, "w", encoding="utf-8") as handle:
+            handle.write(payload)
+    return {
+        "success": True,
+        "path": absolute,
+        "set_lut_path": set_lut_path,
+        "bytes": os.path.getsize(absolute),
+        # Whether a file was actually replaced, not whether the caller allowed
+        # it: `payload is not None` is always true here, so this reported a
+        # replacement for every overwrite=true install, including the ones that
+        # landed on an empty MCP/. This flag is the record of what an install
+        # destroyed -- execution_lifecycle rates `lut install` on the fact that
+        # it "can replace with overwrite=true" -- so it has to be the observed
+        # pre-state, not the permission.
+        "overwritten": existed,
+        "note": ("Call project_settings(action='refresh_luts') so Resolve picks up "
+                 "the new file before applying it."),
+    }
+
+
+def remove_lut(name: str) -> Dict[str, Any]:
+    """Delete a LUT from the writable subdir only.
+
+    Stock and vendor LUTs live outside it and cannot be removed through here.
+    """
+    absolute, set_lut_path = resolve_writable(name)
+    if not os.path.isfile(absolute):
+        raise LutPathError(
+            f"{set_lut_path} is not present in {WRITABLE_SUBDIR}/. This server only "
+            "removes LUTs it can install; stock and vendor LUTs are left alone."
+        )
+    os.remove(absolute)
+    return {"success": True, "removed": set_lut_path, "path": absolute}
+
+
+def read_lut_summary(name: str) -> Dict[str, Any]:
+    """Summarize a `.cube` without returning the whole table.
+
+    A 65-cube is 274,625 rows; handing that back through a tool result is
+    useless to a caller and expensive, so this reports shape and header only.
+    """
+    from src.utils import cube_lut
+
+    root = master_lut_dir()
+    relative = normalize_relative(name)
+    absolute = os.path.join(root, *relative.split("/"))
+    if not os.path.isfile(absolute):
+        raise LutPathError(f"LUT not found under the master LUT dir: {relative}")
+    if os.path.splitext(absolute)[1].lower() != ".cube":
+        return {
+            "set_lut_path": relative,
+            "path": absolute,
+            "bytes": os.path.getsize(absolute),
+            "parsed": False,
+            "note": "Only 3D .cube files are parsed; other formats report size only.",
+        }
+    parsed = cube_lut.read_cube(absolute)
+    return {
+        "set_lut_path": relative,
+        "path": absolute,
+        "bytes": os.path.getsize(absolute),
+        "parsed": True,
+        "size": parsed["size"],
+        "title": parsed["title"],
+        "domain_min": parsed["domain_min"],
+        "domain_max": parsed["domain_max"],
+        "entries": int(parsed["size"]) ** 3,
+    }
+
+
+def attenuate_lut(source: str, strength: float, name: str) -> Dict[str, Any]:
+    """Blend an existing `.cube` toward identity and install the result.
+
+    Reads from anywhere under the master root, writes only into the writable
+    subdir. `cube_lut` refuses a non-unit domain, because identity is only
+    identity on 0..1.
+    """
+    from src.utils import cube_lut
+
+    try:
+        value = float(strength)
+    except (TypeError, ValueError):
+        raise LutPathError("strength must be a number between 0 and 1")
+    if not 0.0 <= value <= 1.0:
+        raise LutPathError(f"strength must be between 0 and 1, got {value}")
+    root = master_lut_dir()
+    source_relative = normalize_relative(source)
+    source_absolute = os.path.join(root, *source_relative.split("/"))
+    if not os.path.isfile(source_absolute):
+        raise LutPathError(f"source LUT not found under the master LUT dir: {source_relative}")
+    absolute, set_lut_path = resolve_writable(name)
+    if os.path.exists(absolute):
+        raise LutPathError(f"{set_lut_path} already exists. Choose another name.")
+    os.makedirs(os.path.dirname(absolute), exist_ok=True)
+    summary = cube_lut.attenuate_file(source_absolute, value, absolute,
+                                      title_suffix=f"@{value:g}")
+    summary.update({
+        "success": True,
+        "source": source_relative,
+        "strength": value,
+        "set_lut_path": set_lut_path,
+        "note": ("Call project_settings(action='refresh_luts') so Resolve picks up "
+                 "the new file before applying it."),
+    })
+    return summary