davinci-resolve-mcp 2.55.0 → 2.55.2

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 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.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.
+
+- **Fixed** options/settings dicts passed to several Resolve APIs are now
+  whitelisted to their documented keys, so a typo'd key is reported instead of
+  silently dropped (`_filter_to_keys` → `ignored_options`/`ignored_settings`):
+  `media_pool.import_timeline` (ImportTimelineFromFile), `timeline.import_into_timeline`
+  (ImportIntoTimeline), raw `render.set_settings` (SetRenderSettings) and
+  `render.quick_export`, and `set_voice_isolation_state` (track + item).
+- **Fixed** `ProjectManager.DeleteProject` is flaky — it silently returns False
+  when the target is/was the current project. All callers (the safe and raw
+  `project_manager.delete` actions and the granular `delete_project`) now route
+  through `delete_project_safely` (switch-away + retry) and report `delete_detail`.
+  Added an `api_truth` entry.
+- **Added** a destructive-registry drift guard (`tests/test_destructive_registry_drift.py`)
+  that asserts token-gated actions map to real handlers and locks in the media-pool
+  delete governance from v2.55.0. (It also surfaced a pre-existing registry
+  mis-keying issue now tracked for a dedicated audit.)
+
 ## What's New in v2.55.0
 
 Governance for catastrophic Media Pool deletes (exhaustive audit EX2/EX3).

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.55.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.55.2-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.0"
+VERSION = "2.55.2"
 # 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.0",
+  "version": "2.55.2",
   "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.0"
+VERSION = "2.55.2"
 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/project.py

@@ -786,8 +786,12 @@ def delete_project(project_name: str) -> Dict[str, Any]:
     if resolve is None:
         return {"error": "Not connected to DaVinci Resolve"}
     pm = resolve.GetProjectManager()
-    result = pm.DeleteProject(project_name)
-    return {"success": bool(result), "project_name": project_name}
+    # DeleteProject is flaky (silently returns False when the target is/was
+    # current, transient first-attempt failures); route through the retry+switch
+    # guard (#19).
+    from src.utils.project_cleanup import delete_project_safely
+    deleted = delete_project_safely(pm, project_name)
+    return {"success": bool(deleted.get("success")), "project_name": project_name, "delete_detail": deleted}
 
 
 @mcp.tool()

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.55.0"
+VERSION = "2.55.2"
 
 import base64
 import os
@@ -7508,6 +7508,36 @@ def _safe_int(value: Any, default: int, *, minimum: Optional[int] = None, maximu
     return parsed
 
 
+def _filter_to_keys(settings: Any, allowed) -> Tuple[Dict[str, Any], list]:
+    """Whitelist a settings/options dict to the keys a Resolve API documents.
+
+    Resolve silently ignores unrecognized keys in several options dicts (import
+    options, render settings, voice-isolation state), so a typo'd key is dropped
+    with no signal. This returns ``(filtered, ignored)`` — only known keys are
+    forwarded; ``ignored`` lists the dropped keys so the caller can surface them
+    in ``ignored_settings`` (P1 / deep-QC #4-6,23-25)."""
+    if not isinstance(settings, dict):
+        return {}, []
+    allowed_set = set(allowed)
+    filtered = {k: v for k, v in settings.items() if k in allowed_set}
+    ignored = sorted(str(k) for k in settings if k not in allowed_set)
+    return filtered, ignored
+
+
+# Documented option/state key sets (docs/reference/resolve_scripting_api.txt).
+_IMPORT_TIMELINE_OPTION_KEYS = frozenset({
+    "timelineName", "importSourceClips", "sourceClipsPath",
+    "sourceClipsFolders", "interlaceProcessing",
+})
+_IMPORT_INTO_TIMELINE_OPTION_KEYS = frozenset({
+    "autoImportSourceClipsIntoMediaPool", "ignoreFileExtensionsWhenMatching",
+    "linkToSourceCameraFiles", "useSizingInfo",
+    "importMultiChannelAudioTracksAsLinkedGroups", "insertAdditionalTracks",
+    "insertWithOffset", "sourceClipsPath", "sourceClipsFolders",
+})
+_VOICE_ISOLATION_STATE_KEYS = frozenset({"isEnabled", "amount"})
+
+
 def _setup_marker_limit(value: Any, default: int = 12) -> int:
     if isinstance(value, str) and _setup_text_key(value) in {"unlimited", "no_limit", "nolimit", "all"}:
         return 0
@@ -12931,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:
@@ -13405,6 +13443,9 @@ def _safe_project_delete(pm, p: Dict[str, Any]) -> Dict[str, Any]:
     if p.get("dry_run"):
         return _ok(would_delete=True, name=name)
     current = pm.GetCurrentProject()
+    # Route through delete_project_safely: DeleteProject silently returns False
+    # when the target is/was current and is flaky on the first attempt (#19).
+    from src.utils.project_cleanup import delete_project_safely
     current_name = current.GetName() if current and _has_method(current, "GetName") else None
     if current_name == name:
         if not p.get("close_current", False):
@@ -13413,11 +13454,13 @@ def _safe_project_delete(pm, p: Dict[str, Any]) -> Dict[str, Any]:
         closed = bool(pm.CloseProject(current))
         if not closed:
             return _err(f"Failed to close current project '{name}' before delete")
-        result = {"success": bool(pm.DeleteProject(name))}
+        deleted = delete_project_safely(pm, name)
+        result = {"success": bool(deleted.get("success")), "delete_detail": deleted}
         if saved is False:
             result["warning"] = "SaveProject returned False before close; unsaved changes may have been discarded"
         return result
-    return {"success": bool(pm.DeleteProject(name))}
+    deleted = delete_project_safely(pm, name)
+    return {"success": bool(deleted.get("success")), "delete_detail": deleted}
 
 
 def _database_capabilities(pm) -> Dict[str, Any]:
@@ -13947,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]
@@ -13955,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":
@@ -13963,15 +14010,35 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         proj = pm.GetCurrentProject()
         return {"success": bool(pm.CloseProject(proj))} if proj else _err("No project open")
     elif action == "delete":
-        return {"success": bool(pm.DeleteProject(p["name"]))}
+        if not p.get("name"):
+            return _err("delete requires name")
+        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}
     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])
 
@@ -14126,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()}
@@ -14718,7 +14791,15 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
             return missing
         return {"settings": _ser(proj.GetRenderSettings())}
     elif action == "set_settings":
-        return {"success": bool(proj.SetRenderSettings(p["settings"]))}
+        if "settings" not in p or not isinstance(p["settings"], dict):
+            return _err("set_settings requires a settings object")
+        # Whitelist to documented keys; SetRenderSettings silently ignores unknown
+        # keys, so a typo'd setting would be dropped with no signal (P1 #6).
+        settings, ignored_settings = _filter_to_keys(p["settings"], _RENDER_SETTING_KEYS)
+        result = {"success": bool(proj.SetRenderSettings(settings))}
+        if ignored_settings:
+            result["ignored_settings"] = ignored_settings
+        return result
     elif action == "list_presets":
         return {"presets": proj.GetRenderPresetList()}
     elif action == "load_preset":
@@ -14730,7 +14811,17 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     elif action == "quick_export_presets":
         return {"presets": proj.GetQuickExportRenderPresets()}
     elif action == "quick_export":
-        return _ser(proj.RenderWithQuickExport(p["preset"], p.get("params", {})))
+        if "preset" not in p:
+            return _err("quick_export requires a preset")
+        # Whitelist the documented quick-export params (unknown keys silently
+        # ignored by Resolve) (P1 #23).
+        qe_params, ignored_params = _filter_to_keys(
+            p.get("params", {}), {"TargetDir", "CustomName", "VideoQuality", "EnableUpload"}
+        )
+        out = _ser(proj.RenderWithQuickExport(p["preset"], qe_params))
+        if ignored_params and isinstance(out, dict):
+            out["ignored_params"] = ignored_params
+        return out
     elif action == "render_capabilities":
         return _render_capabilities(proj)
     elif action == "probe_render_matrix":
@@ -15036,9 +15127,17 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     elif action == "setup_multicam_timeline":
         return _setup_multicam_timeline(proj, mp, p)
     elif action == "import_timeline":
+        # Whitelist options to the documented keys; Resolve silently ignores
+        # unknown keys, so a typo would be dropped with no signal (P1 #4).
+        options, ignored_opts = _filter_to_keys(p.get("options", {}), _IMPORT_TIMELINE_OPTION_KEYS)
         with long_resolve_op("media_pool.import_timeline"):
-            tl = mp.ImportTimelineFromFile(p["path"], p.get("options", {}))
-        return _ok(name=tl.GetName()) if tl else _err("Failed to import timeline")
+            tl = mp.ImportTimelineFromFile(p["path"], options)
+        if not tl:
+            return _err("Failed to import timeline")
+        result = _ok(name=tl.GetName())
+        if ignored_opts:
+            result["ignored_options"] = ignored_opts
+        return result
     elif action == "delete_timelines":
         count = proj.GetTimelineCount()
         timelines = []
@@ -15803,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)
@@ -17861,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":
@@ -17899,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":
@@ -17907,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:
@@ -18057,7 +18170,11 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         result = tl.CreateFusionClip(found)
         return _ok() if result else _err("Failed to create Fusion clip")
     elif action == "import_into_timeline":
-        return {"success": bool(tl.ImportIntoTimeline(p["path"], p.get("options", {})))}
+        options, ignored_opts = _filter_to_keys(p.get("options", {}), _IMPORT_INTO_TIMELINE_OPTION_KEYS)
+        result = {"success": bool(tl.ImportIntoTimeline(p["path"], options))}
+        if ignored_opts:
+            result["ignored_options"] = ignored_opts
+        return result
     elif action == "export":
         # Timeline.Export needs resolved resolve.EXPORT_* enum *values*, which a
         # JSON/MCP caller cannot pass — handing it a string silently fails. Resolve
@@ -18193,7 +18310,11 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         missing = _requires_method(tl, "SetVoiceIsolationState", "20.1")
         if missing:
             return missing
-        return {"success": bool(tl.SetVoiceIsolationState(p["track_index"], p["state"]))}
+        state, ignored_state = _filter_to_keys(p["state"], _VOICE_ISOLATION_STATE_KEYS)
+        result = {"success": bool(tl.SetVoiceIsolationState(p["track_index"], state))}
+        if ignored_state:
+            result["ignored_state_keys"] = ignored_state
+        return result
     elif action == "extract_source_frame_ranges":
         p = params or {}
         handles = int(p.get("handles", 24))
@@ -18442,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)
@@ -18609,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()}
@@ -18629,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":
@@ -18670,7 +18801,11 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
         missing = _requires_method(item, "SetVoiceIsolationState", "20.1")
         if missing:
             return missing
-        return {"success": bool(item.SetVoiceIsolationState(p["state"]))}
+        state, ignored_state = _filter_to_keys(p["state"], _VOICE_ISOLATION_STATE_KEYS)
+        result = {"success": bool(item.SetVoiceIsolationState(state))}
+        if ignored_state:
+            result["ignored_state_keys"] = ignored_state
+        return result
 
     # ── Retime ──
     elif action == "get_retime":
@@ -18822,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/api_truth.py

@@ -77,6 +77,18 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["silent-failure", "timeline", "export", "enum"],
         "mitigation": ["_timeline_export_spec", "_timeline_export_value"],
     },
+    {
+        "symbol": "ProjectManager.DeleteProject",
+        "object": "ProjectManager",
+        "signature": "(projectName) -> bool",
+        "reality": "Returns False (no deletion) when the target project is, or "
+                   "recently was, the current project, and is flaky on the first "
+                   "attempt — so a single bool() call leaves the project undeleted "
+                   "with no useful error.",
+        "recommended": "Load/close away from the target first, then retry; use "
+                       "src/utils/project_cleanup.py:delete_project_safely.",
+        "tags": ["unreliable-return", "project", "flaky"],
+    },
     {
         "symbol": "Composition.Paste",
         "object": "Fusion Composition",