davinci-resolve-mcp 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 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.0.1 — project deletion is gated, and the open project is refused by default
+
+A security fix, published as [GHSA-gmp7-qjp9-m7gm](https://github.com/samuelgursky/davinci-resolve-mcp/security/advisories/GHSA-gmp7-qjp9-m7gm).
+One behaviour change existing callers may notice is called out below.
+
+### Security
+
+- **`project_manager delete` permanently deleted any named project — including
+  the one open in Resolve — without confirmation, and no gate saw it.** It runs
+  through `delete_project_safely`, a *reliability* helper that works around
+  DeleteProject's flakiness and session lock by closing the open project and
+  then deleting it. The `project_manager` tool carried no `@_destructive_op`,
+  `delete` was not registered, and the CRITICAL risk rule written for project
+  deletion named `delete_project`, an action no tool dispatches. So it matched
+  nothing: safe mode, dry-run refusal and the security audit log never saw a
+  project deletion.
+- **Thirteen further deletes that the classifier already rated HIGH were not
+  enforced, for the same reason.** They are the three `render` deletes,
+  `render_presets.delete_burnin`, `gallery_stills.delete_stills`, `fusion_comp`
+  `delete_tool` and `delete_keyframe`, `timeline_item.delete_keyframe`, the three
+  `media_pool_item_markers` deletes, `project_settings.delete_color_group` and
+  `resolve_control.delete_user_preferences_preset`. Safe mode is enforced only
+  by the decorator, and only for registered actions, so these ratings were a
+  promise nothing kept.
+
+### Changed
+
+- **The raw `delete` now refuses the currently open project unless
+  `close_current=True`**, matching `safe_project_delete`. This is the one change
+  existing callers may notice: a call that used to close and delete the open
+  project now returns an error, until it passes `close_current=True`.
+- All of the actions above are registered and their tools decorated. The project
+  delete is CRITICAL, and `safe_project_delete` and the thirteen others are HIGH,
+  so all are blocked while safe mode is on. An explicit dry run is refused
+  unless the action honours it natively; only `safe_project_delete` does, and
+  keeps working. Every call is audited. None of them archives the timeline,
+  except the keyframe deletes on `fusion_comp` and `timeline_item`, which change
+  timeline items and so still do.
+- **`remove_motion_blur`** (on `folder` and `media_pool_item`) is **re-rated
+  MEDIUM**. It renders new media and never touches the source, and was already
+  confirm-gated for exactly that reason, but the `remove_` name-prefix rule had
+  rated it HIGH on its name alone. It is now audited, and not blocked by safe
+  mode.
+- **The name-prefix rule is now a fallback for unlisted actions**: an explicit
+  lower rating wins. Before, it fired ahead of the LOW and MEDIUM tables and
+  could not be overridden. No existing rating changed except `remove_motion_blur`
+  — no LOW, MEDIUM or graph-LUT entry started with `delete_` or `remove_`.
+
+### Fixed
+
+- **Nine risk rules named actions that no tool dispatches, and so protected
+  nothing.** On `project_manager`: `delete_project`, now repointed at the real
+  `delete`, plus `close_project_without_saving` and `save_project_as`. On
+  `edit_engine`: `auto_cut_silence` and `ripple_trim`. On `timeline`: `cut_clip`,
+  `delete_clip_by_id`, `delete_markers` and `ripple_delete` — which is a CutList
+  entry kind inside `apply_cuts`, not an action. The rest were removed; since
+  they never matched, removing them changes nothing at runtime. An existing test
+  even asserted that the dead `delete_project` rule classified as CRITICAL — true
+  of a name no tool uses, and part of how it survived. It now tests the real
+  `delete`.
+- **The bridge installer's Lua canary gave only the pre-21.1 diagnosis** — that
+  Resolve cannot find a Python 3. On free 21.1 that is wrong, because Python
+  scripting moved to Studio (#203). Its comments and printed output now give both
+  causes, the newer first (#219). The printed post-install guidance was already
+  corrected in v2.224.1.
+
+### Added
+
+- **`tests/test_write_enforcement_ratchet.py`** fails the suite in three cases:
+  - an action is rated destructive but not enforced;
+  - a risk rule names an action no tool dispatches;
+  - a new write-style action appears with neither a rating nor a registry entry.
+
+  The 144 unrated write-style actions that exist today are frozen as a backlog.
+  Rating one forces its removal from the list, so it can only shrink. This is
+  the second instance of this gap in two days, and the first time it cannot
+  come back unnoticed.
+- `tests/test_project_delete_guard.py` pins the delete guard, its rating and its
+  enforcement.
+
+### Documentation
+
+- Removed a stale tool count from `docs/authoring/script-plugin-authoring.md`.
+
+### Validation
+
+- Full suite green: 3,482 passed, 1 skipped. Every static and drift gate is clean, including
+  the native-dry-run scan. That scan requires the native-dry-run list to match,
+  exactly, the registered actions whose handlers read `dry_run`, which is how
+  `safe_project_delete` was confirmed as the only one.
+- No live Resolve run. The gating is decorator-level and verified offline. The
+  delete guard is tested against a fake project manager, deliberately:
+  exercising it live means deleting a real project.
+
 ## What's New in v3.0.0 — the server no longer executes caller-supplied code, and every plugin write is gated
 
 **A breaking release.** Two public actions are removed. The rest of the change

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.0.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)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.0.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)](#服务器模式)
@@ -12,7 +12,7 @@
 [![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.0.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v3.0.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/authoring/script-plugin-authoring.md

@@ -19,7 +19,7 @@ automation.
 | Custom workflow you want as a permanent menu item | `script_plugin('install', ...)`, then the user runs it from Workspace → Scripts |
 | Image-processing node for the Fusion page | `fuse_plugin` |
 | Color-page programmable transform | `dctl` |
-| Anything the existing 28 wrapped Resolve API tools already cover | The wrapped tool — no scripting needed |
+| Anything the wrapped Resolve API tools already cover | The wrapped tool — no scripting needed |
 
 ## Two template kinds
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "3.0.0"
+VERSION = "3.0.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": "3.0.0",
+  "version": "3.0.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/install_resolve_bridge.py

@@ -288,7 +288,9 @@ _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.
+-- Resolve is listing Lua and silently skipping Python. On Resolve 21.1+ FREE
+-- that is expected: Python scripting moved to Studio (issue #203), and nothing
+-- below will change it. On Studio, or 21.0.x and earlier, it cannot find a Python 3.
 -- It looks at PYTHON3HOME, then /usr/local/bin/python3 -- and nowhere else, which
 -- is why Homebrew, pyenv, uv and conda interpreters go unseen. Either point it at
 -- the one you have (no sudo, but does NOT survive a reboot):
@@ -299,9 +301,12 @@ _LUA_CANARY = """-- Installed by davinci-resolve-mcp as an enumeration canary.
 -- already looks, which persists:
 --   sudo ln -s "$(command -v python3)" /usr/local/bin/python3
 -- A python.org build creates that symlink for you. Restart Resolve after.
-print("Resolve is enumerating scripts. If the Python probe is missing, Resolve")
-print("cannot find a Python 3: set PYTHON3HOME with launchctl setenv, or install")
-print("a python.org build. Homebrew/pyenv/uv/conda are not looked at directly.")
+print("Resolve is enumerating scripts. If the Python probe is missing:")
+print("- Resolve 21.1+ FREE: Python scripting moved to Studio, so .py scripts")
+print("  no longer list at all (issue #203). No Python setting changes that.")
+print("- Studio, or 21.0.x and earlier: Resolve cannot find a Python 3. Set")
+print("  PYTHON3HOME with launchctl setenv, or install a python.org build.")
+print("  Homebrew/pyenv/uv/conda are not looked at directly.")
 """
 
 

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "3.0.0"
+VERSION = "3.0.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 377-tool granular server instead
 """
 
-VERSION = "3.0.0"
+VERSION = "3.0.1"
 
 import base64
 import os
@@ -16575,6 +16575,7 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("resolve_control")
 def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """App-level DaVinci Resolve operations.
 
@@ -18072,6 +18073,7 @@ def layout_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("render_presets")
 def render_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Import/export render and burn-in presets.
 
@@ -19030,6 +19032,7 @@ def _project_lint_live(r, pm) -> Dict[str, Any]:
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("project_manager")
 def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage DaVinci Resolve projects.
 
@@ -19047,7 +19050,7 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         render and wedges Resolve's pipeline until restart (stuck
         IsRenderingInProgress, 0% jobs, refused Quit). stop_render=true stops
         the render, waits for the flag to clear, then closes.
-      delete(name) -> {success}
+      delete(name, close_current?) -> {success}
       import_project(path, name?) -> {success}
       export_project(name, path, with_stills_and_luts?) -> {success}
       archive(name, path, src_media?, render_cache?, proxy_media?) -> {success}
@@ -19180,6 +19183,18 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "delete":
         if not p.get("name"):
             return _err("delete requires name")
+        # Refuse the open project unless the caller says so, as
+        # safe_project_delete does. delete_project_safely closes and deletes the
+        # current project without asking — the call that loses a project someone
+        # is working in. If the current project cannot be read, DeleteProject on
+        # an open project fails anyway (the session holds its lock).
+        try:
+            _open = pm.GetCurrentProject()
+            _open_name = _open.GetName() if _open else None
+        except Exception:
+            _open_name = None
+        if _open_name == p["name"] and not p.get("close_current", False):
+            return _err("Refusing to delete the currently open project; pass close_current=True")
         from src.utils.project_cleanup import delete_project_safely
         deleted = delete_project_safely(pm, p["name"])
         return {"success": bool(deleted.get("success")), "delete_detail": deleted}
@@ -19364,6 +19379,7 @@ def _setting_limitation(name: Any, obj: str = "Project") -> Optional[Dict[str, A
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("project_settings")
 def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Project metadata, settings, and color groups.
 
@@ -20340,6 +20356,7 @@ def _export_render_boundary_report(proj, p: Dict[str, Any]):
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("render")
 def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Render pipeline: jobs, presets, formats, codecs, and rendering.
 
@@ -21319,6 +21336,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("folder")
 def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Operations on Media Pool folders.
 
@@ -21491,6 +21509,7 @@ def _keyed_get(getter, key):
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("media_pool_item")
 def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Operations on a media pool clip. Identify clip by clip_id.
 
@@ -21955,6 +21974,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("media_pool_item_markers")
 def media_pool_item_markers(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Markers and flags on media pool clips. Identify clip by clip_id.
 
@@ -28805,6 +28825,7 @@ def gallery(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, A
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("gallery_stills")
 def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage stills in gallery albums (best results on Color page).
 
@@ -30261,6 +30282,7 @@ def _fusion_get_text_plus(comp, p: Dict[str, Any]) -> Dict[str, Any]:
 
 @mcp.tool()
 @_guard_missing_params
+@_destructive_op("fusion_comp")
 def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Fusion composition node graph operations.
 

package/src/utils/destructive_hook.py

@@ -77,6 +77,24 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "safe_install_extension",
         "safe_remove_extension",
     }),
+    # Deletes the classifier already rated HIGH (CRITICAL for the raw project
+    # delete) on tools that carried no @_destructive_op, so safe mode never saw
+    # them. Plus the 21.0 AI deblur, rated MEDIUM: it creates media, and is
+    # registered so it is audited and its dry run is honest.
+    "folder": frozenset({"remove_motion_blur"}),
+    "fusion_comp": frozenset({"delete_keyframe", "delete_tool"}),
+    "gallery_stills": frozenset({"delete_stills"}),
+    "media_pool_item": frozenset({"remove_motion_blur"}),
+    "media_pool_item_markers": frozenset({
+        "delete_at_frame",
+        "delete_by_color",
+        "delete_by_custom_data",
+    }),
+    "project_manager": frozenset({"delete", "safe_project_delete"}),
+    "project_settings": frozenset({"delete_color_group"}),
+    "render": frozenset({"delete_all_jobs", "delete_job", "delete_preset"}),
+    "render_presets": frozenset({"delete_burnin"}),
+    "resolve_control": frozenset({"delete_user_preferences_preset"}),
     "media_pool": frozenset({
         "delete_clips",
         "delete_folders",
@@ -155,6 +173,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "create_subtitles",
     }),
     "timeline_item": frozenset({
+        "delete_keyframe",
         "set_output_blanking",
         "set_use_timeline_for_output_blanking",
         "set_clip_enabled",
@@ -250,7 +269,9 @@ NO_ARCHIVE_ON_KEYS: Dict[Tuple[str, str], frozenset] = {
 
 # ── Non-timeline write tools ────────────────────────────────────────────────
 #
-# Tools whose registered actions write the filesystem, not the timeline. Every
+# Tools whose registered actions do not mutate the working timeline: they write
+# plugin folders, or act on projects, the render queue, presets, the gallery,
+# pool items or app preferences. Every
 # gate applies to them — safe mode, dry-run refusal, the audit log — but they
 # skip version-on-mutate archiving, and skip resolving the versioning context
 # at all: that goes through the project-root provider, which reaches Resolve,
@@ -258,7 +279,12 @@ NO_ARCHIVE_ON_KEYS: Dict[Tuple[str, str], frozenset] = {
 # Resolve. `media_pool` has its own branch for the same reason; these differ in
 # that there is no project state to log.
 
-NON_TIMELINE_WRITE_TOOLS: frozenset = frozenset({"dctl", "fuse_plugin", "script_plugin"})
+NON_TIMELINE_WRITE_TOOLS: frozenset = frozenset({
+    "dctl", "fuse_plugin", "script_plugin",
+    "folder", "gallery_stills", "media_pool_item", "media_pool_item_markers",
+    "project_manager", "project_settings", "render", "render_presets",
+    "resolve_control",
+})
 
 
 # ── Strict-mode allowlist ───────────────────────────────────────────────────
@@ -327,6 +353,7 @@ NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
     ("timeline_ai", "create_subtitles"),
     ("script_plugin", "safe_install_extension"),
     ("script_plugin", "safe_remove_extension"),
+    ("project_manager", "safe_project_delete"),
 })
 
 

package/src/utils/execution_lifecycle.py

@@ -125,8 +125,10 @@ class RiskClassificationHook(LifecycleHook):
     name = "risk_classification"
 
     _CRITICAL_ACTIONS: Set[Tuple[str, str]] = {
-        ("project_manager", "delete_project"),
-        ("project_manager", "close_project_without_saving"),
+        # Raw project delete. This rule used to name `delete_project`, which
+        # no tool dispatches, so it matched nothing and deleting a project
+        # passed every gate.
+        ("project_manager", "delete"),
         ("media_pool", "delete_timelines"),
         ("media_pool", "delete_clips"),
     }
@@ -140,15 +142,11 @@ class RiskClassificationHook(LifecycleHook):
         ("fuse_plugin", "remove"),
         ("script_plugin", "remove"),
         ("script_plugin", "safe_remove_extension"),
+        # Guarded delete: disposable `_mcp_` projects only, and the open one
+        # only with close_current=True — but still permanent.
+        ("project_manager", "safe_project_delete"),
         ("timeline", "delete_clips"),
-        ("timeline", "delete_clip_by_id"),
-        ("timeline", "delete_markers"),
-        ("timeline", "ripple_delete"),
-        ("timeline", "cut_clip"),
         ("edit_engine", "execute_selects"),
-        ("edit_engine", "auto_cut_silence"),
-        ("edit_engine", "ripple_trim"),
-        ("project_manager", "save_project_as"),
         ("media_pool", "delete_folders"),
         ("timeline", "delete_track"),
         ("timeline", "lift_range"),
@@ -264,6 +262,11 @@ class RiskClassificationHook(LifecycleHook):
         ("fuse_plugin", "install"),
         ("script_plugin", "install"),
         ("script_plugin", "safe_install_extension"),
+        # 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.
+        ("folder", "remove_motion_blur"),
+        ("media_pool_item", "remove_motion_blur"),
         # Additive edits that place content into an existing timeline. Nothing
         # is deleted (`overwrite_range`, which does delete, is HIGH), but the
         # timeline is no longer what it was.
@@ -378,7 +381,16 @@ class RiskClassificationHook(LifecycleHook):
             radius = BlastRadius.PROJECT if "project" in tool_name else BlastRadius.TIMELINE
             conf_required = True
             reasons.append(f"Action '{action}' is permanently destructive across {radius.value}")
-        elif pair in cls._HIGH_RISK_ACTIONS or action.startswith("delete_") or action.startswith("remove_"):
+        elif pair in cls._HIGH_RISK_ACTIONS or (
+            # The name-prefix rule is a fallback for UNLISTED actions: an
+            # explicit lower rating wins. It used to fire first and so could
+            # not be overridden — `remove_motion_blur` creates media, yet read
+            # HIGH on its name.
+            pair not in cls._LOW_RISK_ACTIONS
+            and pair not in cls._MEDIUM_RISK_ACTIONS
+            and pair not in cls._GRAPH_LUT_ACTIONS
+            and (action.startswith("delete_") or action.startswith("remove_"))
+        ):
             level = RiskLevel.HIGH
             destructive = True
             if params.get("ripple", False):