davinci-resolve-mcp 2.223.0 → 2.224.1

package/CHANGELOG.md

@@ -2,6 +2,113 @@
 
 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.224.1 — the bridge installer explains the outcome it was built to detect
+
+Reported by @hemna (#219). No behaviour changed; the installer writes exactly
+what it wrote before and says considerably more about it.
+
+### Fixed
+
+- **The canary-only outcome had no printed guidance at all.** Seeing
+  `resolve_bridge_canary` in Workspace ▸ Scripts while `resolve_bridge_probe`
+  is absent is not a failed install — it is the single most informative thing
+  the installer can tell you, and the exact signal the Lua canary exists to
+  produce. But the printed steps were a fixed four-line list that assumed the
+  Python probe had listed, so a user in this case followed step 3 to a menu
+  entry that cannot exist. The explanation was written down the whole time —
+  inside the canary's own Lua comments, which nobody has any reason to open.
+  There is now a real branch for it that says the install worked, says not to
+  re-run it, and explains what the missing probe means.
+- **Duplicate canary entries are now expected rather than alarming.** The
+  installer writes into every Scripts/Utility folder Resolve scans, giving the
+  canary the same filename in each, so Resolve lists it once per folder with no
+  way to tell them apart. The reporter saw two and reasonably read it as a
+  broken install; a real run on the maintainer's machine produces **four**. The
+  guidance now names the number and says running any one of them is the same as
+  running any other. The count is derived from what was actually installed, and
+  the filename now has a single definition shared by the writer and the
+  counter — those two disagreeing would produce guidance promising entries that
+  are not there.
+- **The Console is named.** The canary reports through `print()`, which lands in
+  Workspace ▸ Console and nowhere else. The installer had never mentioned the
+  Console — the string does not appear in it — so running the canary with no
+  Console open looks exactly like nothing happening, which is what was
+  reported.
+
+### Changed
+
+- The canary-only explanation is **split by edition instead of asserting a
+  single cause**. The canary's own text predates Resolve 21.1 and blames Python
+  discovery — `PYTHON3HOME`, then `/usr/local/bin/python3`, and nowhere else.
+  That is still right on Studio and on 21.0.x and earlier, but on **free 21.1
+  it is wrong**: Python scripting moved to the Studio edition (#203), so `.py`
+  files do not list there whatever Python is installed, and the older advice
+  would send a user chasing a setting that cannot fix their problem. Both
+  branches are now stated, newer cause first.
+
+### Validation
+
+- Full suite green: 3,484 passed, 1 skipped. Six new tests cover the duplicate
+  count and its wording, the absence of that wording for a single canary, the
+  canary-only branch, the Console pointer, both edition branches with the
+  newer one ordered first, and the single-definition guarantee on the canary
+  filename.
+- Verified by running the installer for real on this machine, which is where
+  the four-entry figure comes from.
+- **Still open in #219**: the canary's own embedded remediation text carries
+  the pre-21.1 single-cause diagnosis. Correcting what it says to a specific
+  user needs their edition, which has been asked for; the printed guidance
+  above no longer depends on that answer.
+
+## What's New in v2.224.0 — native Resolve 21.1 DCTL encryption
+
+Contributed by @legionsound (#216), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **`dctl encrypt_native`**, with the granular twin `encrypt_dctl_native`,
+  calling native 21.1 DCTL encryption. The caller supplies an existing `.dctl`
+  input, a new `.dctle` output path and an optional expiry; the wrapper reports
+  the actual final path, size and hash. Tool count 376 → 377.
+- **A destination is never replaced.** Resolve writes into isolated staging and
+  only a verified non-empty regular file is published. The publish uses
+  `O_EXCL` creation at `0o600`, so a file that appears *during* encryption
+  cannot be clobbered, and the existence check uses `lexists` so a **dangling
+  symlink** counts as an occupied destination rather than a free one — the case
+  a plain existence test silently gets wrong. The cross-volume fallback removes
+  its own partial output if the copy fails.
+- Source bytes are preserved, and the action neither installs nor applies the
+  shader.
+
+### Changed
+
+- Classified **LOW** risk rather than MEDIUM, with a destructive-action hook
+  entry and dry-run refusal coverage. LOW is the honest rating here: the action
+  only ever creates a new file and is incapable of overwriting one, so grouping
+  it with operations that rewrite existing work would make the rating mean
+  less. Verified: `dctl.encrypt_native` classifies LOW / destructive /
+  recognised, and is in the destructive registry.
+- Two native boundaries handled explicitly rather than papered over: Resolve
+  appends `.dctle` itself, so a fixed staging stem prevents a doubled suffix on
+  a user-supplied name; and an empty expiry string is normalized to null,
+  because an isolated probe measured the native call returning false for `""`
+  and true for null or omission. Other expiry strings pass through untouched.
+
+### Validation
+
+- Full suite green: 3,478 passed, 1 skipped. Drift guards, api-parity and read/write
+  symmetry all clean with the 377 count.
+- Live evidence is @legionsound's on Studio 21.1.0.14, through both interfaces
+  with synthetic identity code: each exported a non-empty file, reported
+  correct size and hash, preserved the source bytes, produced owner-only
+  permissions, and refused a repeat export without altering the destination.
+  Not reproduced here; this machine is Studio 19.1.3.7, below the 21.1 floor.
+- **Not claimed**: that an encrypted shader is accepted by a render, and
+  nothing at all about cipher strength. Observed file sizes are recorded as
+  observations, not format guarantees.
+- This PR was branched from current `main` and merged **without adaptation** —
+  the first in the 21.1 series to need none.
+
 ## What's New in v2.223.0 — native Resolve 21.1 DCTL validation
 
 Contributed by @legionsound (#215), live-validated on Studio 21.1.0.14.

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.223.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.224.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(376%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(377%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)
@@ -133,7 +133,7 @@ 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` | 376 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 377 | 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 / **376** granular (live server) |
+| MCP Tools | **36** compound / **377** 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-2.223.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.224.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(376%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(377%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)
 
-> 本翻译对应 v2.223.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.224.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ 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` | 376 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 377 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **36** 复合 / **376** 细粒度（实时服务器） |
+| MCP 工具 | **36** 复合 / **377** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -345,7 +345,7 @@ 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` | 376 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 377 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
@@ -2492,3 +2492,5 @@ Native audio normalization: [21.1 controls](reference/resolve211-normalization.m
 Native timecode/waveform alignment: [21.1 controls](reference/resolve211-alignment.md), including linked-item selection semantics and rendered video/audio evidence.
 
 Resolve-native DCTL validation: [21.1 controls](reference/resolve211-dctl-validation.md), separate from static validation and shader rendering.
+
+Native DCTL encryption: [21.1 controls](reference/resolve211-encryption.md), with explicit destination handling and export-evidence limits.

package/docs/contributing.md

@@ -64,7 +64,7 @@ davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
 │   ├── server.py                # Compound MCP server — 36 tools (default)
-│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 376 tools
+│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 377 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers
 ├── tests/                       # offline suite (test_*.py) + live harnesses (live_*.py):

package/docs/install.md

@@ -144,7 +144,7 @@ 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` | 376 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 377 | 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 376-tool server
+python src/server.py --full    # Launch full 377-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -25,7 +25,7 @@ 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
 action parameter, keeping LLM context windows lean. The full granular server
-provides **376 individual tools** for power users. The legacy coverage spans
+provides **377 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).
 
@@ -642,3 +642,5 @@ Native audio normalization: [21.1 controls](resolve211-normalization.md), with i
 Native timecode/waveform alignment: [21.1 controls](resolve211-alignment.md), including linked-item selection semantics and rendered video/audio evidence.
 
 Resolve-native DCTL validation: [21.1 controls](resolve211-dctl-validation.md), separate from static validation and shader rendering.
+
+Native DCTL encryption: [21.1 controls](resolve211-encryption.md), with explicit destination handling and export-evidence limits.

package/docs/reference/resolve211-encryption.md

@@ -0,0 +1,48 @@
+# Native Resolve 21.1 DCTL encryption
+
+Compound `dctl encrypt_native` and granular `encrypt_dctl_native` accept
+`input_path`, `output_path` and optional `expiry`. Input must be an existing .dctl;
+output must be a new .dctle. Existing destinations, including dangling symlinks,
+are refused. The source is never modified by the wrapper.
+
+The native Name and OutputFolder options are derived from an isolated staging
+file, then the completed file is published to the requested output path. This
+avoids native filename surprises: Resolve appends .dctle even when Name already
+ends with that suffix. Expiry null/omission means no expiry. Empty string is
+normalized to null because native empty-string expiry returned false in the
+contributor fixture while null succeeded. Other strings pass through as native
+ISO 8601 expiry requests; native failure is preserved.
+
+Resolve-facing staging uses the existing safe-directory helper. A successful
+native return must be accompanied by a non-empty regular encrypted file. An
+atomic no-replace hard link publishes it; filesystems without that support use
+exclusive file creation and copy. A failed copy removes only the new partial
+output. An output appearing during encryption is not overwritten. New files
+use owner-only permissions where the platform supports them. The result reports
+actual path, byte length and SHA-256, not a guessed native filename.
+
+The method has a 21.1 floor. The dctl tool has the destructive-action hook, and
+encrypt_native is registered/rated LOW because it only creates new output and
+never replaces existing content. Explicit compound dry runs refuse before the
+handler. The granular tool declares a write. No DCTL is installed or applied by
+this operation.
+
+## Contributor evidence and limits
+
+Contributor-validated on macOS Studio 21.1.0.14 via official MCP probes and both
+actual community wrappers, using a synthetic multiline identity shader. Native
+omitted/null expiry and a future date succeeded; empty string returned false in
+the isolated probe. Both wrappers created 2032-byte files in the tested runs,
+returned matching file hashes/sizes, left source bytes unchanged and refused a
+repeat export without changing the destination. These byte lengths are observed,
+not format requirements. Ciphertext equality across separate encryptions is not
+assumed.
+
+Tests exercise output races, missing native output, native false, cross-volume
+fallback, failed-copy cleanup, dangling symlinks, bad arguments and write gates.
+This is encryption/export evidence, not shader application or rendered-image
+acceptance, and not a security assessment of Blackmagic's encryption scheme.
+
+`tests/live_resolve211_encryption.py SOURCE_DCTL OUTPUT_DIR` uses a synthetic
+identity source and a fresh output directory. It does not install the results or
+change a project. Never substitute someone else's shader without authorization.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.223.0"
+VERSION = "2.224.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 · 376 full · 3 platforms"
+    subtitle = "36 compound · 377 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

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

package/scripts/install_resolve_bridge.py

@@ -281,6 +281,11 @@ _FRAMEWORK_PYTHON_ROOTS = (
 #: PYTHON3HOME is unset. This is the one python.org's installer creates.
 _FALLBACK_PYTHON3 = Path("/usr/local/bin/python3")
 
+#: Filename of the Lua enumeration canary. Named once: the installer writes it
+#: and the post-install guidance counts it, and those two disagreeing is how a
+#: user ends up told to expect entries that are not there.
+_CANARY_NAME = "resolve_bridge_canary.lua"
+
 _LUA_CANARY = """-- Installed by davinci-resolve-mcp as an enumeration canary.
 -- If THIS appears under Workspace > Scripts but resolve_bridge_probe does not,
 -- Resolve is listing Lua and silently skipping Python: it cannot find a Python 3.
@@ -650,7 +655,7 @@ def _install_to(target: Path, *, probe_only: bool, installed: list[str]) -> None
         installed.append(str(target / probe))
     # Lua always enumerates; Python only with a framework install. The canary
     # makes "Python not detected" distinguishable from "wrong folder".
-    canary = target / "resolve_bridge_canary.lua"
+    canary = target / _CANARY_NAME
     canary.write_text(_LUA_CANARY, encoding="utf-8")
     installed.append(str(canary))
     if probe_only:
@@ -686,6 +691,65 @@ def _install_to(target: Path, *, probe_only: bool, installed: list[str]) -> None
     installed.append(str(launcher_path))
 
 
+def canary_count(result: dict) -> int:
+    """How many identical `resolve_bridge_canary` entries Resolve will list.
+
+    One per Scripts/Utility folder installed into, all with the same filename,
+    so they are indistinguishable in the menu. Reported in issue #219 by a user
+    who reasonably read two identical entries as a broken install.
+    """
+    return sum(1 for path in result.get("installed", [])
+               if str(path).endswith(_CANARY_NAME))
+
+
+def next_steps(result: dict) -> list:
+    """The post-install instructions, as lines.
+
+    Built rather than printed inline so the canary-only branch is testable: it
+    is the single most likely outcome on macOS and, until issue #219, the only
+    one the installer had no words for. The user followed step 3 to a menu
+    entry that cannot exist, and the explanation was sitting in a Lua comment
+    they had no reason to open.
+    """
+    lines = [
+        "Next:",
+        "  1. Restart DaVinci Resolve so it re-scans the Scripts folders.",
+        "  2. Open a saved project (the Scripts menu is empty in Project Manager).",
+        "  3. Workspace > Scripts > resolve_bridge_probe  — run it TWICE.",
+        # The probe runs INSIDE Resolve, which never sees the shell's
+        # DAVINCI_RESOLVE_BRIDGE_CONFIG — it always writes to the fixed default
+        # directory, so the guidance must not follow the override.
+        "  4. Read ~/.config/davinci-resolve-mcp/host-model-probe.json",
+    ]
+    count = canary_count(result)
+    if count > 1:
+        lines += [
+            "",
+            f"Expect {count} identical 'resolve_bridge_canary' entries — one per Scripts",
+            "folder this installed into. That is normal, not a double install; running",
+            "any one of them is the same as running any other.",
+        ]
+    lines += [
+        "",
+        "If step 3 shows no 'resolve_bridge_probe' and you can only see",
+        "'resolve_bridge_canary':",
+        "  - The install worked. Do not re-run it. That is the canary doing its job:",
+        "    Resolve is enumerating scripts, listing Lua, and skipping Python.",
+        "  - Run 'resolve_bridge_canary' and read its output in Workspace > Console.",
+        "    It reports with print(), not a dialog, so with no Console open it looks",
+        "    like nothing happened.",
+        "  - What it means depends on your edition:",
+        "      * Resolve 21.1+ FREE — Python scripting moved to the Studio edition,",
+        "        so .py files no longer list there at all and no Python setting will",
+        "        change that. See issue #203.",
+        "      * Studio, or 21.0.x and earlier — Resolve cannot find a Python 3. It",
+        "        looks at PYTHON3HOME and then /usr/local/bin/python3 and nowhere",
+        "        else, which is why Homebrew, pyenv, uv and conda builds go unseen.",
+        "        The canary's own output carries the fix.",
+    ]
+    return lines
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--probe-only", action="store_true",
@@ -709,14 +773,8 @@ def main() -> int:
         print("WARNING: " + warning)
         print("!" * 72)
         print()
-    print("Next:")
-    print("  1. Restart DaVinci Resolve so it re-scans the Scripts folders.")
-    print("  2. Open a saved project (the Scripts menu is empty in Project Manager).")
-    print("  3. Workspace > Scripts > resolve_bridge_probe  — run it TWICE.")
-    # The probe runs INSIDE Resolve, which never sees the shell's
-    # DAVINCI_RESOLVE_BRIDGE_CONFIG — it always writes to the fixed default
-    # directory, so the guidance must not follow the override.
-    print("  4. Read ~/.config/davinci-resolve-mcp/host-model-probe.json")
+    for line in next_steps(result):
+        print(line)
     return 0
 
 

package/src/granular/common.py

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

@@ -3,11 +3,12 @@ from src.utils.resolve211_dctl import native_dctl_result
 from src.utils.resolve211_alignment import auto_align
 from src.utils.resolve211_normalization import normalize_audio
 from src.utils.resolve211_blanking import validate_blanking
+from src.utils.resolve211_encryption import encrypt_dctl
 from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
 from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 from src.granular.common import (
     mcp, READ_ONLY_TOOL, WRITE_TOOL, DESTRUCTIVE_TOOL, get_resolve, get_current_project,
-    _get_timeline, _get_timeline_item, _find_clip_by_id, _requires_method, has_method,
+    _get_timeline, _get_timeline_item, _resolve_safe_dir, _find_clip_by_id, _requires_method, has_method,
 )
 
 
@@ -319,3 +320,14 @@ def validate_dctl_native(source: str) -> dict:
     if missing:
         return missing
     return native_dctl_result(r, source)
+
+@mcp.tool(annotations=WRITE_TOOL)
+def encrypt_dctl_native(input_path: str, output_path: str, expiry: str | None = None) -> dict:
+    """Encrypt a .dctl to a new .dctle using Resolve 21.1. Never overwrites. Empty/null expiry means no expiry; ISO 8601 strings pass to Resolve. Source is unchanged."""
+    r = get_resolve()
+    if r is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(r, "EncryptDCTL", "21.1")
+    if missing:
+        return missing
+    return encrypt_dctl(r, input_path, output_path, expiry, _resolve_safe_dir)

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} (376 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (377 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -8,10 +8,10 @@ Each tool groups related operations via an 'action' parameter.
 
 Usage:
     python src/server.py              # Start the MCP server
-    python src/server.py --full       # Start the 376-tool granular server instead
+    python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "2.223.0"
+VERSION = "2.224.1"
 
 import base64
 import os
@@ -42,6 +42,7 @@ for p in [current_dir, project_dir]:
     if p not in sys.path:
         sys.path.insert(0, p)
 
+from src.utils.resolve211_encryption import encrypt_dctl
 from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
 from src.utils.resolve211_blanking import validate_blanking
 from src.utils.resolve211_alignment import auto_align
@@ -31114,6 +31115,7 @@ _DCTL_VALID_CATEGORIES = ("lut", "aces_idt", "aces_odt")
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("dctl")
 def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Author and install DCTL files (Color page custom shaders + ACES transforms).
 
@@ -31142,6 +31144,7 @@ def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
         — ext: '.dctl' (default) or '.dctle' (encrypted)
       remove(name, category?, subdir?, ext?) -> {success}
       read(name, category?, subdir?, ext?) -> {source, encrypted}
+      encrypt_native(input_path, output_path, expiry?) -> {success, path?, bytes?, sha256?} — native 21.1; never overwrites.
       validate(source) -> {valid, errors, warnings, checker}
       validate_native(source) -> {valid, diagnostic, checker} — Resolve 21.1 validation; source and diagnostic unchanged.
       template(kind, name, options?) -> {source, kind, name, suggested_category}
@@ -31309,6 +31312,15 @@ def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
             return missing
         return native_dctl_result(r, source)
 
+    if action == "encrypt_native":
+        r = get_resolve()
+        if r is None:
+            return _not_connected_error()
+        missing = _requires_method(r, "EncryptDCTL", "21.1")
+        if missing:
+            return missing
+        return encrypt_dctl(r, p.get("input_path"), p.get("output_path"), p.get("expiry"), _resolve_safe_dir)
+
     if action == "validate":
         source = p.get("source")
         if not isinstance(source, str):
@@ -31335,7 +31347,7 @@ def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
         }
 
     return _unknown(action, ["path", "list", "install", "remove", "read",
-                             "validate_native", "validate", "template", "list_templates"])
+                             "encrypt_native", "validate_native", "validate", "template", "list_templates"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -32751,9 +32763,9 @@ if __name__ == "__main__":
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
     _install_threaded_tool_dispatch(mcp)
 
-    # Support --full flag to run the 376-tool granular server instead
+    # Support --full flag to run the 377-tool granular server instead
     if "--full" in sys.argv:
-        logger.info("Starting full 376-tool granular server...")
+        logger.info("Starting full 377-tool granular server...")
         sys.argv = [arg for arg in sys.argv if arg != "--full"]
         from src.granular import mcp as granular_mcp
 

package/src/utils/destructive_hook.py

@@ -63,6 +63,7 @@ SAFE_MODE_BLOCKED_RISK_LEVELS: FrozenSet[str] = frozenset({
 # replace_clip/link_*). The test_destructive_registry_drift guard asserts every
 # string here is a real handler so this can't regress.
 DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
+    "dctl": frozenset({"encrypt_native"}),
     "media_pool": frozenset({
         "delete_clips",
         "delete_folders",

package/src/utils/execution_lifecycle.py

@@ -193,6 +193,7 @@ class RiskClassificationHook(LifecycleHook):
     #: them unrecognised, i.e. it warns that the risk is unestablished for the
     #: actions whose risk is the best established of any we dispatch.
     _LOW_RISK_ACTIONS: Set[Tuple[str, str]] = {
+        ("dctl", "encrypt_native"),  # Creates a new file; never replaces existing content.
         ("timeline_markers", "add"),
         ("timeline_markers", "update_custom_data"),
         ("timeline_item_markers", "add"),

package/src/utils/resolve211_encryption.py

@@ -0,0 +1,59 @@
+"""Stage native DCTL encryption, then publish without replacing an existing file."""
+import errno
+import hashlib
+import os
+from pathlib import Path
+import shutil
+import tempfile
+
+
+def encrypt_dctl(r, input_path, output_path, expiry, safe_dir):
+    if not isinstance(input_path,str) or not input_path or not isinstance(output_path,str) or not output_path:
+        return {'error':'input_path and output_path must be non-empty strings'}
+    if expiry is not None and not isinstance(expiry,str):
+        return {'error':'expiry must be an ISO 8601 string or null'}
+    source=Path(input_path).expanduser().absolute()
+    target=Path(output_path).expanduser().absolute()
+    if source.suffix.lower()!='.dctl' or not source.is_file():
+        return {'error':'input_path must name an existing .dctl file'}
+    if target.suffix.lower()!='.dctle':
+        return {'error':'output_path must end in .dctle'}
+    if os.path.lexists(target):
+        return {'error':'Output already exists; refusing to overwrite','success':False}
+    try:
+        target.parent.mkdir(parents=True,exist_ok=True)
+        staging_root=Path(safe_dir(str(target.parent.resolve())))
+        staging_root.mkdir(parents=True,exist_ok=True)
+        with tempfile.TemporaryDirectory(prefix='resolve-mcp-dctl-',dir=staging_root) as stage:
+            # Native Name is a stem: Resolve appends .dctle itself. Use a fixed
+            # staging name, so user filename characters never become native paths.
+            options={'Name':'encrypted','OutputFolder':stage,'Expiry':None if expiry=='' else expiry}
+            if not r.EncryptDCTL(str(source),options):
+                return {'success':False}
+            encrypted=Path(stage)/'encrypted.dctle'
+            if encrypted.is_symlink() or not encrypted.is_file() or encrypted.stat().st_size==0:
+                return {'success':False,'error':'Resolve reported success without a non-empty encrypted file'}
+            os.chmod(encrypted,0o600)
+            digest=hashlib.sha256(encrypted.read_bytes()).hexdigest()
+            size=encrypted.stat().st_size
+            try:
+                os.link(encrypted,target)
+            except OSError as exc:
+                if exc.errno not in (errno.EXDEV,errno.EPERM,errno.EOPNOTSUPP,errno.ENOSYS):
+                    raise
+                # Cross-volume/no-hardlink filesystem: exclusive creation still
+                # prevents overwriting an existing target, including a symlink.
+                fd=os.open(target,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+                try:
+                    with os.fdopen(fd,'wb') as out, encrypted.open('rb') as src:
+                        shutil.copyfileobj(src,out)
+                        out.flush()
+                        os.fsync(out.fileno())
+                except BaseException:
+                    target.unlink(missing_ok=True)
+                    raise
+            return {'success':True,'path':str(target),'bytes':size,'sha256':digest}
+    except FileExistsError:
+        return {'success':False,'error':'Output appeared during encryption; refusing to overwrite'}
+    except Exception as exc:
+        return {'success':False,'error':'Encryption/export failed: '+(str(exc) or type(exc).__name__)}

package/src/utils/resolve_versions.py

@@ -227,6 +227,8 @@ _EVIDENCE_GATES: List[Dict[str, Any]] = [
 CODE_FLOORS: Dict[str, str] = {
     "Timeline.AutoAlignClips": "21.1",
     "Resolve.ValidateDCTL": "21.1",
+
+    "Resolve.EncryptDCTL": "21.1",
     "MediaPool.CreateMulticamClip": "21.1",
     "TimelineItem.FlattenMulticam": "21.1",
     "Timeline.SetOutputBlanking": "21.1",