davinci-resolve-mcp 2.55.1 → 2.56.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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.56.0
+
+Destructive-action registry audit (EX-REG) — a systemic version of the EX2 bug.
+
+Many destructive actions were registered under the **wrong tool key**, so
+`is_destructive()` returned False and **version-on-mutate archiving / change
+logging silently never fired** for them. Examples: `create_timeline`,
+`auto_sync_audio`, `create_stereo_clip`, `append_to_timeline` were filed under
+`timeline` though `media_pool` dispatches them; `set_cdl`, `copy_grades`,
+`export_lut`, the version ops were under `timeline_item` though
+`timeline_item_color` dispatches them; the Fusion-comp and take actions used stale
+names (`add_fusion_comp`, `delete_take`) that matched no real handler.
+
+- **Fixed** rebuilt `DESTRUCTIVE_ACTIONS_BY_TOOL` so every action is keyed under
+  the tool that actually dispatches it (stale names mapped to real ones:
+  `*_fusion_comp` → `*_comp`, `*_take` → `add`/`delete`/`select`/`finalize`,
+  `import_into` → `import_into_timeline`, `create_subtitles_from_audio` →
+  `create_subtitles`). Inert entries whose tool isn't governed (media_pool_item
+  `replace_clip`/`link_*`) were dropped. Catastrophic take/Fusion-comp deletes and
+  the media-pool create/sync ops are now archived as intended.
+- **Added** the registry-drift guard now asserts *every* registry action is a real
+  handler of its tool (broad check enabled), so this class can't regress.
+
+## What's New in v2.55.2
+
+Deep-QC P1 1b — required-param validation. Mutating/destructive actions that
+hard-indexed required params (`p["name"]`, `p["index"]`, `p["color"]`, …) now
+return a structured error instead of crashing with an unhandled `KeyError` (or,
+for `set_clip_enabled`/`set_current`, coercing the value). Guarded actions:
+
+- `timeline`: `set_current`, `set_name`, `set_start_timecode`, `add_track`
+- `timeline_item`: `set_property`, `set_clip_enabled`
+- `project_manager`: `create`, `load`, `import_project`, `export_project`,
+  `archive`, `restore`
+- marker `delete_by_color` (clip / timeline / item — destructive)
+- `layout_presets`: `save`, `export`; `project_settings`: `set_name`, `set_setting`
+
 ## What's New in v2.55.1
 
 Deep-QC P1 — settings/options whitelisting + DeleteProject reliability.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.55.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.56.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-34%20(341%20full)-blue.svg)](#server-modes)

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.55.1"
+VERSION = "2.56.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

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

package/src/granular/common.py

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

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.55.1"
+VERSION = "2.55.2"
 
 import base64
 import os
@@ -12961,12 +12961,20 @@ def layout_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
         return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
 
     if action == "save":
+        if not p.get("name"):
+            return _err("save requires name")
         return {"success": bool(r.SaveLayoutPreset(p["name"]))}
     elif action == "load":
         return {"success": bool(r.LoadLayoutPreset(p["name"]))}
     elif action == "update":
         return {"success": bool(r.UpdateLayoutPreset(p["name"]))}
     elif action == "export":
+        err, _clean = _validate_params(p, {
+            "name": {"type": str, "required": True, "non_empty": True},
+            "path": {"type": str, "required": True, "non_empty": True},
+        })
+        if err:
+            return _err(err)
         return {"success": bool(r.ExportLayoutPreset(p["name"], p["path"]))}
     elif action == "import_preset":
         if "name" in p:
@@ -13982,6 +13990,8 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         proj = pm.GetCurrentProject()
         return {"name": proj.GetName(), "id": proj.GetUniqueId()} if proj else _err("No project open")
     elif action == "create":
+        if not p.get("name"):
+            return _err("create requires name")
         media_location_path = p.get("media_location_path") or p.get("mediaLocationPath")
         if media_location_path:
             version = r.GetVersion() or [0]
@@ -13990,6 +14000,8 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         proj = pm.CreateProject(p["name"], media_location_path) if media_location_path else pm.CreateProject(p["name"])
         return _ok(name=proj.GetName()) if proj else _err(f"Failed to create '{p['name']}'")
     elif action == "load":
+        if not p.get("name"):
+            return _err("load requires name")
         proj = pm.LoadProject(p["name"])
         return _ok() if proj else _err(f"Failed to load '{p['name']}'")
     elif action == "save":
@@ -14004,13 +14016,29 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         deleted = delete_project_safely(pm, p["name"])
         return {"success": bool(deleted.get("success")), "delete_detail": deleted}
     elif action == "import_project":
+        if not p.get("path"):
+            return _err("import_project requires path")
         return {"success": bool(pm.ImportProject(p["path"], p.get("name")))}
     elif action == "export_project":
+        err, _clean = _validate_params(p, {
+            "name": {"type": str, "required": True, "non_empty": True},
+            "path": {"type": str, "required": True, "non_empty": True},
+        })
+        if err:
+            return _err(err)
         return {"success": bool(pm.ExportProject(p["name"], p["path"], p.get("with_stills_and_luts", True)))}
     elif action == "archive":
+        err, _clean = _validate_params(p, {
+            "name": {"type": str, "required": True, "non_empty": True},
+            "path": {"type": str, "required": True, "non_empty": True},
+        })
+        if err:
+            return _err(err)
         return {"success": bool(pm.ArchiveProject(p["name"], p["path"],
             p.get("src_media", True), p.get("render_cache", True), p.get("proxy_media", False)))}
     elif action == "restore":
+        if not p.get("path"):
+            return _err("restore requires path")
         return {"success": bool(pm.RestoreProject(p["path"], p.get("name")))}
     return _unknown(action, ["list","get_current","create","load","save","close","delete","import_project","export_project","archive","restore","lint","diff_to_spec","plan_spec","apply_spec", *_PROJECT_KERNEL_ACTIONS])
 
@@ -14165,10 +14193,16 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
     if action == "get_name":
         return {"name": proj.GetName()}
     elif action == "set_name":
+        if not p.get("name"):
+            return _err("set_name requires name")
         return {"success": bool(proj.SetName(p["name"]))}
     elif action == "get_setting":
         return {"settings": _ser(proj.GetSetting(p.get("name", "")))}
     elif action == "set_setting":
+        if not p.get("name"):
+            return _err("set_setting requires name")
+        if "value" not in p:
+            return _err("set_setting requires value")
         return {"success": bool(proj.SetSetting(p["name"], p["value"]))}
     elif action == "get_unique_id":
         return {"id": proj.GetUniqueId()}
@@ -15868,6 +15902,8 @@ def media_pool_item_markers(action: str, params: Optional[Dict[str, Any]] = None
             return frame_err
         return {"data": clip.GetMarkerCustomData(frame)}
     elif action == "delete_by_color":
+        if not p.get("color"):
+            return _err("delete_by_color requires color")
         return {"success": bool(clip.DeleteMarkersByColor(p["color"]))}
     elif action == "delete_at_frame":
         frame, frame_err = _marker_frame_from_params(p)
@@ -17926,8 +17962,11 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
                 timelines.append({"name": tl.GetName(), "id": tl.GetUniqueId(), "index": i})
         return {"timelines": timelines}
     elif action == "set_current":
-        tl = proj.GetTimelineByIndex(p["index"])
-        return {"success": bool(proj.SetCurrentTimeline(tl))} if tl else _err(f"No timeline at index {p['index']}")
+        err, clean = _validate_params(p, {"index": {"type": int, "required": True, "min": 1}})
+        if err:
+            return _err(err)
+        tl = proj.GetTimelineByIndex(clean["index"])
+        return {"success": bool(proj.SetCurrentTimeline(tl))} if tl else _err(f"No timeline at index {clean['index']}")
     elif action == "edit_kernel_capabilities":
         return _timeline_edit_kernel_capabilities()
     elif action == "conform_capabilities":
@@ -17964,7 +18003,10 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "get_name":
         return {"name": tl.GetName()}
     elif action == "set_name":
-        return {"success": bool(tl.SetName(p["name"]))}
+        err, clean = _validate_params(p, {"name": {"type": str, "required": True, "non_empty": True}})
+        if err:
+            return _err(err)
+        return {"success": bool(tl.SetName(clean["name"]))}
     elif action == "get_start_frame":
         return {"frame": tl.GetStartFrame()}
     elif action == "get_end_frame":
@@ -17972,10 +18014,16 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "get_start_timecode":
         return {"timecode": tl.GetStartTimecode()}
     elif action == "set_start_timecode":
-        return {"success": bool(tl.SetStartTimecode(p["timecode"]))}
+        err, clean = _validate_params(p, {"timecode": {"type": str, "required": True, "non_empty": True}})
+        if err:
+            return _err(err)
+        return {"success": bool(tl.SetStartTimecode(clean["timecode"]))}
     elif action == "get_track_count":
         return {"count": tl.GetTrackCount(p["track_type"])}
     elif action == "add_track":
+        err, _clean = _validate_params(p, {"track_type": {"enum": ["video", "audio", "subtitle"], "required": True}})
+        if err:
+            return _err(err)
         opts_in = p.get("options") or {}
         new_track_options: Dict[str, Any] = {}
         if "audio_type" in opts_in:
@@ -18515,6 +18563,8 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
             return frame_err
         return {"data": tl.GetMarkerCustomData(frame)}
     elif action == "delete_by_color":
+        if not p.get("color"):
+            return _err("delete_by_color requires color")
         return {"success": bool(tl.DeleteMarkersByColor(p["color"]))}
     elif action == "delete_at_frame":
         frame, frame_err = _marker_frame_from_params(p, tl=tl)
@@ -18682,6 +18732,11 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
     elif action == "get_property":
         return {"properties": _ser(item.GetProperty(p.get("key", "")))}
     elif action == "set_property":
+        err, _clean = _validate_params(p, {"key": {"type": str, "required": True, "non_empty": True}})
+        if err:
+            return _err(err)
+        if "value" not in p:
+            return _err("'value' is required")
         return {"success": bool(item.SetProperty(p["key"], p["value"]))}
     elif action == "get_duration":
         return {"duration": item.GetDuration()}
@@ -18702,7 +18757,10 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
     elif action == "get_right_offset":
         return {"offset": item.GetRightOffset()}
     elif action == "set_clip_enabled":
-        return {"success": bool(item.SetClipEnabled(p["enabled"]))}
+        err, clean = _validate_params(p, {"enabled": {"type": bool, "required": True}})
+        if err:
+            return _err(err)
+        return {"success": bool(item.SetClipEnabled(clean["enabled"]))}
     elif action == "get_clip_enabled":
         return {"enabled": bool(item.GetClipEnabled())}
     elif action == "update_sidecar":
@@ -18899,6 +18957,8 @@ def timeline_item_markers(action: str, params: Optional[Dict[str, Any]] = None)
             return frame_err
         return {"data": item.GetMarkerCustomData(frame)}
     elif action == "delete_by_color":
+        if not p.get("color"):
+            return _err("delete_by_color requires color")
         return {"success": bool(item.DeleteMarkersByColor(p["color"]))}
     elif action == "delete_at_frame":
         frame, frame_err = _marker_frame_from_params(p)

package/src/utils/destructive_hook.py

@@ -40,13 +40,17 @@ logger = logging.getLogger("resolve-mcp.destructive-hook")
 # here; (b) optionally add a metric-capture entry below if it has a sensible
 # default metric.
 
+# Each action is keyed under the tool whose @_destructive_op wrapper actually
+# DISPATCHES it. Historically many entries were filed under the wrong tool key
+# (e.g. create_timeline/auto_sync_audio under "timeline" though they are media_pool
+# actions; set_cdl/copy_grades under "timeline_item" though timeline_item_color
+# dispatches them; *_fusion_comp / *_take stale names that never matched), so
+# is_destructive() returned False and version-on-mutate archiving silently did not
+# fire. EX-REG re-filed every action under its real dispatcher and dropped inert
+# entries whose tool is not @_destructive_op-wrapped (e.g. media_pool_item
+# 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]] = {
-    # Real COMPOUND media_pool action strings (the @destructive_op("media_pool")
-    # wrapper queries is_destructive("media_pool", <compound action>)). The prior
-    # entries used granular function names (delete_media_pool_clips, …) and
-    # media_pool_item names that the compound tool never dispatches, so catastrophic
-    # deletes silently bypassed version-on-mutate archiving (EX2). media_pool_item
-    # link/replace actions are governed separately (its own tool is not yet wrapped).
     "media_pool": frozenset({
         "delete_clips",
         "delete_folders",
@@ -54,6 +58,14 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "move_folders",
         "delete_clip_mattes",
         "delete_timelines",
+        "create_timeline",
+        "create_timeline_from_clips",
+        "append_to_timeline",
+        "setup_multicam_timeline",
+        "create_stereo_clip",
+        "auto_sync_audio",
+        "set_clip_marks",
+        "clear_clip_marks",
     }),
     "edit_engine": frozenset({
         "execute_selects",
@@ -61,11 +73,6 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "execute_swap",
     }),
     "timeline": frozenset({
-        "create_timeline",
-        "create_timeline_from_clips",
-        "setup_multicam_timeline",
-        "delete_timelines",
-        "append_to_timeline",
         "delete_clips",
         "move_clips",
         "duplicate_clips",
@@ -75,19 +82,9 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "overwrite_range",
         "lift_range",
         "apply_cuts",
-        "create_stereo_clip",
-        "auto_sync_audio",
         "create_compound_clip",
         "create_fusion_clip",
         "convert_to_stereo",
-        "create_subtitles_from_audio",
-        "set_clip_marks",
-        "clear_clip_marks",
-        "set_clip_property",
-        "set_clip_color",
-        "clear_clip_color",
-        "replace_clip",
-        "replace_clip_preserve_sub_clip",
         "set_clips_linked",
         "duplicate",
         "insert_generator",
@@ -108,7 +105,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "set_mark_in_out",
         "clear_mark_in_out",
         "set_title_text",
-        "import_into",
+        "import_into_timeline",
     }),
     "timeline_markers": frozenset({
         "add",
@@ -120,77 +117,64 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
     "timeline_ai": frozenset({
         "detect_scene_cuts",
         "analyze_dolby_vision",
+        "create_subtitles",
     }),
     "timeline_item": frozenset({
         "set_clip_enabled",
-        "set_clip_color",
-        "clear_clip_color",
-        "add_flag",
-        "clear_flags",
         "set_property",
         "set_name",
-        "assign_to_color_group",
-        "remove_from_color_group",
-        "create_magic_mask",
-        "regenerate_magic_mask",
-        "smart_reframe",
-        "stabilize",
         "set_voice_isolation_state",
-        "set_cdl",
-        "copy_grades",
-        "reset_all_node_colors",
-        "set_color_output_cache",
-        "set_fusion_output_cache",
         "update_sidecar",
-        "export_lut",
-        "add_take",
-        "delete_take",
-        "select_take",
-        "finalize_take",
-        "add_version",
-        "delete_version",
-        "load_version",
-        "rename_version",
         "set_transform",
         "set_crop",
         "set_retime",
         "set_composite",
         "set_audio",
-        "set_stabilization",
     }),
     "timeline_item_markers": frozenset({
         "add",
+        "add_flag",
+        "clear_flags",
+        "set_clip_color",
+        "clear_clip_color",
         "delete_at_frame",
         "delete_by_custom_data",
         "delete_by_color",
         "update_custom_data",
     }),
     "timeline_item_fusion": frozenset({
-        "add_fusion_comp",
-        "delete_fusion_comp",
-        "import_fusion_comp",
-        "load_fusion_comp",
-        "rename_fusion_comp",
+        "add_comp",
+        "delete_comp",
+        "import_comp",
+        "load_comp",
+        "rename_comp",
     }),
     "timeline_item_color": frozenset({
         "set_cdl",
         "copy_grades",
         "reset_all_node_colors",
-        "set_node_enabled",
-        "set_node_cache_mode",
-        "set_lut",
-        "apply_grade_from_drx",
-        "apply_arri_cdl_lut",
+        "assign_color_group",
+        "remove_from_color_group",
+        "create_magic_mask",
+        "regenerate_magic_mask",
+        "smart_reframe",
+        "stabilize",
+        "export_lut",
+        "add_version",
+        "delete_version",
+        "load_version",
+        "rename_version",
+        "set_color_cache",
+        "set_fusion_cache",
     }),
     "timeline_item_takes": frozenset({
-        "add_take",
-        "delete_take",
-        "select_take",
-        "finalize_take",
+        "add",
+        "delete",
+        "select",
+        "finalize",
     }),
     "graph": frozenset({
         "set_lut",
-        "set_node_cache_mode",
         "set_node_enabled",
         "apply_arri_cdl_lut",
         "apply_grade_from_drx",
@@ -227,8 +211,10 @@ NO_ARCHIVE_ON_KEYS: Dict[Tuple[str, str], frozenset] = {
 # first, the user almost certainly wants to know before losing data.
 
 STRICT_DEFAULT_ACTIONS: frozenset = frozenset({
-    ("timeline", "delete_timelines"),
     ("timeline", "delete_track"),
+    # NOTE: delete_timelines is a media_pool action (EX-REG re-keyed it); it is
+    # archive+confirm-token gated (EX3) rather than strict, per the decision that
+    # strict over-blocks deletes when there is nothing to archive.
     # delete_clips with ripple=True is destructive in a way single-clip delete
     # isn't — handled separately in is_strict_required() because it depends on
     # the params payload, not just the action name.