davinci-resolve-mcp 2.54.5 → 2.55.1

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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.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).
+
+**Behavior change:** `media_pool` `delete_clips`, `delete_folders`, and
+`delete_timelines` now require a confirm token, the same two-step handshake
+`timeline.delete_track` already uses — the first call returns
+`status: "confirmation_required"` with a `confirm_token` and a preview (count +
+names); re-call with `params.confirm_token` to execute. Callers that disable
+gating via the `destructive.require_confirm_token=false` preference are
+unaffected.
+
+- **Fixed** the destructive-action registry listed granular function names
+  (`delete_media_pool_clips`, `move_media_pool_folders`, …) that the compound
+  `media_pool` tool never dispatches, so `is_destructive()` returned False and
+  these catastrophic deletes silently skipped version-on-mutate archiving and
+  change logging. The registry now uses the real compound action strings, so the
+  deletes are archived/logged as intended.
+- **Added** confirm-token gating + previews to the three deletes (EX3). The
+  registry fix also re-enables the existing media-pool change log for them.
+- Live-validated against DaVinci Resolve Studio 21.0.0 (non-destructively): the
+  no-token call returns `confirmation_required` and deletes nothing.
+
 ## What's New in v2.54.5
 
 Reliability + security hardening from the exhaustive reliability audit (Wave A).

package/README.md

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

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.54.5"
+VERSION = "2.55.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": "2.54.5",
+  "version": "2.55.1",
   "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.54.5"
+VERSION = "2.55.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/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.54.5"
+VERSION = "2.55.1"
 
 import base64
 import os
@@ -784,6 +784,11 @@ _destructive_hook.register_preference_provider(_destructive_preference_provider)
 _TOKEN_GATED_DESTRUCTIVE_ACTIONS = frozenset({
     ("timeline", "delete_track"),
     ("timeline", "apply_cuts"),
+    # Catastrophic media-pool deletes (EX3): irreversibly destroy clips/folders/
+    # timelines. Gated like delete_track; also archive-on-mutate via the registry.
+    ("media_pool", "delete_clips"),
+    ("media_pool", "delete_folders"),
+    ("media_pool", "delete_timelines"),
     # Phase E edit-engine loops: plan → confirm → execute.
     ("edit_engine", "execute_selects"),
     ("edit_engine", "execute_tighten"),
@@ -7503,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
@@ -13400,6 +13435,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):
@@ -13408,11 +13446,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]:
@@ -13958,7 +13998,11 @@ 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":
         return {"success": bool(pm.ImportProject(p["path"], p.get("name")))}
     elif action == "export_project":
@@ -14713,7 +14757,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":
@@ -14725,7 +14777,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":
@@ -14935,7 +14997,20 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
             for sub in (root.GetSubFolderList() or []):
                 if sub.GetUniqueId() == fid:
                     folders.append(sub)
-        return {"success": bool(mp.DeleteFolders(folders))} if folders else _err("No folders found")
+        if not folders:
+            return _err("No folders found")
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            return _issue_confirm_token(
+                action="media_pool.delete_folders", params=p,
+                preview={"operation": "media_pool.delete_folders",
+                         "warning": "Permanently deletes folders AND every clip they contain.",
+                         "folders_lost": len(folders),
+                         "names": [_clip_name(f) for f in folders][:25]},
+            )
+        blocked = _consume_confirm_token(action="media_pool.delete_folders", params=p)
+        if blocked:
+            return blocked
+        return {"success": bool(mp.DeleteFolders(folders))}
     elif action == "move_folders":
         target = _navigate_folder(mp, p["target_path"])
         if not target:
@@ -15018,9 +15093,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 = []
@@ -15028,7 +15111,20 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
             tl = proj.GetTimelineByIndex(i)
             if tl and tl.GetUniqueId() in p["timeline_ids"]:
                 timelines.append(tl)
-        return {"success": bool(mp.DeleteTimelines(timelines))} if timelines else _err("No timelines found")
+        if not timelines:
+            return _err("No timelines found")
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            return _issue_confirm_token(
+                action="media_pool.delete_timelines", params=p,
+                preview={"operation": "media_pool.delete_timelines",
+                         "warning": "Permanently deletes timelines.",
+                         "timelines_lost": len(timelines),
+                         "names": [t.GetName() for t in timelines][:25]},
+            )
+        blocked = _consume_confirm_token(action="media_pool.delete_timelines", params=p)
+        if blocked:
+            return blocked
+        return {"success": bool(mp.DeleteTimelines(timelines))}
     elif action == "append_to_timeline":
         if p.get("clip_infos") is not None:
             raw = p["clip_infos"]
@@ -15115,7 +15211,20 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     elif action == "delete_clips":
         clips = [_find_clip(root, cid) for cid in p["clip_ids"]]
         clips = [c for c in clips if c]
-        return {"success": bool(mp.DeleteClips(clips))} if clips else _err("No clips found")
+        if not clips:
+            return _err("No clips found")
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            return _issue_confirm_token(
+                action="media_pool.delete_clips", params=p,
+                preview={"operation": "media_pool.delete_clips",
+                         "warning": "Permanently deletes Media Pool clips.",
+                         "clips_lost": len(clips),
+                         "names": [_clip_name(c) for c in clips][:25]},
+            )
+        blocked = _consume_confirm_token(action="media_pool.delete_clips", params=p)
+        if blocked:
+            return blocked
+        return {"success": bool(mp.DeleteClips(clips))}
     elif action == "move_clips":
         target = _navigate_folder(mp, p["target_path"])
         if not target:
@@ -18013,7 +18122,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
@@ -18149,7 +18262,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))
@@ -18626,7 +18743,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":

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",

package/src/utils/destructive_hook.py

@@ -41,18 +41,17 @@ logger = logging.getLogger("resolve-mcp.destructive-hook")
 # default metric.
 
 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_media_pool_clips",
-        "delete_media_pool_folders",
+        "delete_clips",
+        "delete_folders",
         "move_clips",
-        "move_media_pool_folders",
-        "replace_clip",
-        "replace_clip_preserve_sub_clip",
-        "link_clip_proxy_media",
-        "unlink_clip_proxy_media",
-        "link_proxy_media",
-        "unlink_proxy_media",
-        "link_clip_full_resolution_media",
+        "move_folders",
         "delete_clip_mattes",
         "delete_timelines",
     }),