davinci-resolve-mcp 2.71.0 → 2.71.1

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 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.71.1
+
+`Timeline.DeleteClips` can lie about whether it worked. #111 recorded four
+behaviours from a live edit session; #114 mitigates the first of them. Both by
+@billcarroll.
+
+### DeleteClips readback-and-retry
+
+`Timeline.DeleteClips` can return `False` on a first call even when every item
+passed is a valid, present `TimelineItem`, with an identical retry succeeding.
+`_timeline_delete_clips_verified` reads the tracks back on a `False` and retries
+once if the items are still there. All four timeline call sites route through
+it: the `delete_clips` action, `lift_range`, `duplicate_clips` and `copy_range`.
+
+The readback is deliberately **tri-state**. A walk that raised, enumerated no
+track at all, or covered items whose unique ID cannot be read is `unknown`, not
+`absent` — so an unverifiable delete is never reported as success, and never
+spends a second destructive call buying information it cannot read. An earlier
+draft collapsed unknown into absent, which turned a failed delete into a
+reported success; that is the exact silent-lie class this series exists to
+remove, so it is worth naming.
+
+The `ripple=True` non-idempotence of a retry is recorded in the docstring rather
+than claimed to be solved: if the first call deleted some items and left others,
+the retry passes the original list back in, stale handles included. It could not
+be made to misbehave against a fake.
+
+### Four edit-session behaviours recorded
+
+- **`DeleteClips` flaky first attempt.** The entry states plainly that the cause
+  is **unknown**, and specifically that this is *not* the
+  `ProjectManager.DeleteProject` shape — that one has an identified mechanism
+  which retrying does not clear, whereas a single retry cleared this in the one
+  instance seen. One observation is not a mechanism.
+- **`DeleteClips` leaves linked audio.** The API deletes exactly the items
+  passed; the UI's linked-selection behaviour does not apply, so orphaned audio
+  collides with later appends.
+- **`AppendToTimeline` mixed-fps duration floor.** Source-to-timeline frame
+  conversion rounds down, landing a planned range one frame short.
+- **`ImportMedia` current-folder only.** No destination parameter; imports land
+  in the current bin.
+
 ## What's New in v2.71.0
 
 Keyed metadata getters honor a list of keys, and `delete_timelines` names the

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.71.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.71.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/docs/SKILL.md

@@ -1307,7 +1307,12 @@ Key actions:
   instead of walking tracks by hand. Filters may be passed inline or as a
   `filters` dict; a mistyped filter name is rejected rather than silently
   matching everything. Returns `{clips, match_count, total_clips}`.
-- `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`
+- `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`.
+  Two verified quirks (see `api_truth`): the call can return `success: false`
+  on the first attempt with valid IDs — re-list and retry once before failing;
+  and deleting a video item does NOT delete its linked audio — pass the linked
+  audio item IDs explicitly, then `detect_gaps_overlaps` across both track
+  types.
 - `duplicate_clips(clip_ids?, selected?, target_track_index?, track_offset?, placement?, record_frame?, record_frame_offset?, copy_properties?, include_linked?)` —
   duplicate existing video timeline items by re-appending the same Media Pool
   item with the same source trim; `selected=True` uses Resolve's selected/current
@@ -1723,6 +1728,14 @@ media_pool(action="append_to_timeline", params={"clip_infos": [
 ]})
 ```
 
+Mixed-fps caution: `start_frame`/`end_frame` are SOURCE frames, and a source
+whose fps differs from the timeline's rounds DOWN on conversion — a 24.0 or
+29.97 clip appended into a 23.976 timeline can land one frame short of its
+slot. Plan durations in timeline frames, extend `end_frame` by a source frame
+when the floor misses, and finish with `detect_gaps_overlaps` (see
+`api_truth`). `import_media` always lands in the CURRENT bin — call
+`set_current_folder` first; there is no destination parameter.
+
 ### 4. Inspect and annotate timeline items
 
 ```

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 22 missing capabilities, 20 bugs / unreliable behaviors.
+**Totals:** 23 missing capabilities, 22 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -192,6 +192,14 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Delete and recreate the folder with the desired name, or rename in the Resolve UI.
 - **Tags:** missing-method, media-pool, folder
 
+### MediaPool.ImportMedia (current-folder destination only)
+
+- **Object:** `MediaPool`
+- **Signature:** `([paths] | [clipInfos]) -> [MediaPoolItem]`
+- **Behavior:** Imports always land in the CURRENT media pool folder; the call has no destination-folder parameter, and passing an unrecognized one to the MCP tool is silently ignored.
+- **Workaround / current handling:** SetCurrentFolder to the target bin first (media_pool set_current_folder), import, then restore the previous current folder if it matters.
+- **Tags:** media-pool, import
+
 ### Project.SetCurrentRenderFormatAndCodec
 
 - **Object:** `Project`
@@ -327,6 +335,22 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
 - **Tags:** unreliable-return, silent-failure, metadata, reel-name
 
+### Timeline.DeleteClips (flaky first attempt)
+
+- **Object:** `Timeline`
+- **Signature:** `([TimelineItem], ripple) -> bool`
+- **Behavior:** Can return False on the first call even when every item in the list is a valid, present TimelineItem; an identical immediate retry succeeds. Observed once, on Studio 21.0 during a cut-video edit session (items confirmed still present after the False, deleted cleanly on retry). Cause unknown — do NOT read this as the ProjectManager.DeleteProject shape: that one has an identified mechanism (the project being, or recently having been, current) that retrying does not clear, whereas a single retry cleared this in the one instance seen. One observation is not a mechanism; if a retry is ever seen to fail repeatedly here, this entry needs revisiting.
+- **Workaround / current handling:** Treat a False return as advisory: re-list the track and check whether the items are actually gone; if still present, retry the identical call once before failing. A readback that raised, enumerated nothing, or covered items whose unique ID cannot be read is UNKNOWN, not gone — never report an unverifiable delete as success, and do not spend a second destructive call on an outcome you equally cannot read.
+- **Tags:** unreliable-return, flaky, timeline, edit
+
+### MediaPool.AppendToTimeline with mixed-fps sources (duration floor)
+
+- **Object:** `MediaPool`
+- **Signature:** `([{mediaPoolItem, startFrame, endFrame, recordFrame, ...}]) -> [TimelineItem]`
+- **Behavior:** start/endFrame are in SOURCE frames. When the source fps differs from the timeline fps (e.g. 24.0 or 29.97 source in a 23.976 timeline), Resolve converts the source range to timeline frames by flooring — so a range planned to fill an exact record slot lands one frame short, leaving a 1-frame gap before the next clip.
+- **Workaround / current handling:** Plan durations in timeline frames (floor(src_frames * timeline_fps / source_fps)); if the floored duration misses the slot, extend endFrame by a source frame and re-check. Always finish with detect_gaps_overlaps.
+- **Tags:** timeline, edit, off-by-one, mixed-fps
+
 ### Graph.SetLUT (master-LUT-dir-only resolution)
 
 - **Object:** `Graph`

package/install.py

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

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.71.0"
+VERSION = "2.71.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 341-tool granular server instead
 """
 
-VERSION = "2.71.0"
+VERSION = "2.71.1"
 
 import base64
 import os
@@ -3795,6 +3795,81 @@ def _timeline_item_ids(items):
     return ids
 
 
+def _timeline_items_presence(tl, items):
+    """Are these timeline items still on the timeline? present/absent/unknown.
+
+    'absent' is a positive finding: every item was identifiable and a
+    completed track walk did not see any of them. A walk that raised, that
+    could not enumerate a single track, or items whose unique ID cannot be
+    read all yield 'unknown' — the readback saw nothing, which is not the
+    same as nothing being there. Callers must never treat 'unknown' as
+    verified-gone.
+    """
+    target_ids = []
+    unreadable_item = False
+    for item in items:
+        item_id = _safe_timeline_item_id(item)
+        if item_id:
+            target_ids.append(item_id)
+        else:
+            unreadable_item = True
+    target_ids = set(target_ids)
+
+    tracks_walked = 0
+    walk_failed = False
+    for track_type in ("video", "audio", "subtitle"):
+        try:
+            track_count = int(tl.GetTrackCount(track_type) or 0)
+        except Exception:
+            walk_failed = True
+            continue
+        for index in range(1, track_count + 1):
+            try:
+                track_items = tl.GetItemListInTrack(track_type, index) or []
+            except Exception:
+                walk_failed = True
+                continue
+            tracks_walked += 1
+            for track_item in track_items:
+                # A sighting is definitive even if another track failed.
+                if _safe_timeline_item_id(track_item) in target_ids:
+                    return "present"
+
+    if walk_failed or tracks_walked == 0 or unreadable_item or not target_ids:
+        return "unknown"
+    return "absent"
+
+
+def _timeline_delete_clips_verified(tl, items, ripple):
+    """Timeline.DeleteClips with readback-and-retry.
+
+    api_truth 'Timeline.DeleteClips (flaky first attempt)': the call can
+    return False while every item is still present, and an identical retry
+    then succeeds. On a False, read the tracks back:
+
+      absent  -> the delete landed despite the False; report success.
+      present -> retry the identical call once, then read back again.
+      unknown -> report failure and do NOT retry. An unverifiable delete must
+                 not be claimed as success, and a retry whose outcome we
+                 equally cannot read is a second destructive call bought with
+                 no information.
+
+    ripple=True caveat: a retry is not idempotent in principle. If the first
+    call deleted some items and left others, the readback reports 'present'
+    for the survivors and the retry passes the original list back in — stale
+    handles to already-deleted items included. That could not be made to
+    misbehave against a fake; it is recorded, not resolved.
+    """
+    if bool(tl.DeleteClips(items, ripple)):
+        return True
+    presence = _timeline_items_presence(tl, items)
+    if presence != "present":
+        return presence == "absent"
+    if bool(tl.DeleteClips(items, ripple)):
+        return True
+    return _timeline_items_presence(tl, items) == "absent"
+
+
 def _timeline_items_by_ids(tl, ids, track_types=("video", "audio", "subtitle")):
     ids_set = {str(item_id) for item_id in ids if item_id is not None}
     found = []
@@ -4168,7 +4243,7 @@ def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_source
                 seen_delete_ids.add(item_id)
         if delete_items:
             try:
-                out["deleted_sources"] = bool(tl.DeleteClips(delete_items, bool(p.get("ripple", False))))
+                out["deleted_sources"] = _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)))
                 out["deleted_source_ids"] = _timeline_item_ids(delete_items)
             except Exception as exc:
                 out["deleted_sources"] = False
@@ -4283,7 +4358,7 @@ def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool =
                     if existing_start < dest_end and existing_end > dest_start:
                         delete_targets.append(existing)
         if delete_targets:
-            deleted = bool(tl.DeleteClips(delete_targets, False))
+            deleted = _timeline_delete_clips_verified(tl, delete_targets, False)
 
     results = []
     for track_type, source_track, item, overlap_start, overlap_end in items:
@@ -4376,7 +4451,7 @@ def _timeline_lift_range_impl(tl, p: Dict[str, Any]):
         return {"success": True, "deleted": 0, "range": {"start": start, "end": end}}
     deleted_ids = _timeline_item_ids(delete_items)
     return {
-        "success": bool(tl.DeleteClips(delete_items, bool(p.get("ripple", False)))),
+        "success": _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False))),
         "deleted": len(delete_items),
         "deleted_ids": deleted_ids,
         "range": {"start": start, "end": end},
@@ -20773,7 +20848,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
             blocked = _consume_confirm_token(action="timeline.delete_clips_ripple", params=p)
             if blocked:
                 return blocked
-        return {"success": bool(tl.DeleteClips(found, ripple))}
+        return {"success": _timeline_delete_clips_verified(tl, found, ripple)}
     elif action == "set_clips_linked":
         ids_set = set(p["clip_ids"])
         found = []

package/src/utils/api_truth.py

@@ -807,6 +807,81 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "when mirroring keep-ranges into clipInfos.",
         "tags": ["timeline", "edit", "off-by-one", "readback"],
     },
+    {
+        "symbol": "Timeline.DeleteClips (flaky first attempt)",
+        "object": "Timeline",
+        "signature": "([TimelineItem], ripple) -> bool",
+        "reality": "Can return False on the first call even when every item in "
+                   "the list is a valid, present TimelineItem; an identical "
+                   "immediate retry succeeds. Observed once, on Studio 21.0 "
+                   "during a cut-video edit session (items confirmed still "
+                   "present after the False, deleted cleanly on retry). Cause "
+                   "unknown — do NOT read this as the ProjectManager."
+                   "DeleteProject shape: that one has an identified mechanism "
+                   "(the project being, or recently having been, current) that "
+                   "retrying does not clear, whereas a single retry cleared "
+                   "this in the one instance seen. One observation is not a "
+                   "mechanism; if a retry is ever seen to fail repeatedly here, "
+                   "this entry needs revisiting.",
+        "recommended": "Treat a False return as advisory: re-list the track and "
+                       "check whether the items are actually gone; if still "
+                       "present, retry the identical call once before failing. "
+                       "A readback that raised, enumerated nothing, or covered "
+                       "items whose unique ID cannot be read is UNKNOWN, not "
+                       "gone — never report an unverifiable delete as success, "
+                       "and do not spend a second destructive call on an "
+                       "outcome you equally cannot read.",
+        "tags": ["unreliable-return", "flaky", "timeline", "edit"],
+        "submit": "bug",
+        "mitigation": ["_timeline_delete_clips_verified", "_timeline_items_presence"],
+    },
+    {
+        "symbol": "Timeline.DeleteClips (linked audio not deleted)",
+        "object": "Timeline",
+        "signature": "([TimelineItem], ripple) -> bool",
+        "reality": "Deleting video items does NOT delete their linked audio "
+                   "items — the UI's linked-selection behavior does not apply "
+                   "to the API, which deletes exactly the items passed. The "
+                   "orphaned audio stays on its track and collides with any "
+                   "later append into the same record range.",
+        "recommended": "When deleting a video item that has linked audio, list "
+                       "the audio track(s) (timeline get_items, track_type "
+                       "'audio'), find the overlapping linked items, and pass "
+                       "their IDs in the same delete. Verify with "
+                       "detect_gaps_overlaps across both track types.",
+        "tags": ["timeline", "edit", "audio", "silent-failure"],
+    },
+    {
+        "symbol": "MediaPool.AppendToTimeline with mixed-fps sources (duration floor)",
+        "object": "MediaPool",
+        "signature": "([{mediaPoolItem, startFrame, endFrame, recordFrame, ...}]) -> [TimelineItem]",
+        "reality": "start/endFrame are in SOURCE frames. When the source fps "
+                   "differs from the timeline fps (e.g. 24.0 or 29.97 source in "
+                   "a 23.976 timeline), Resolve converts the source range to "
+                   "timeline frames by flooring — so a range planned to fill an "
+                   "exact record slot lands one frame short, leaving a 1-frame "
+                   "gap before the next clip.",
+        "recommended": "Plan durations in timeline frames "
+                       "(floor(src_frames * timeline_fps / source_fps)); if the "
+                       "floored duration misses the slot, extend endFrame by a "
+                       "source frame and re-check. Always finish with "
+                       "detect_gaps_overlaps.",
+        "tags": ["timeline", "edit", "off-by-one", "mixed-fps"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.ImportMedia (current-folder destination only)",
+        "object": "MediaPool",
+        "signature": "([paths] | [clipInfos]) -> [MediaPoolItem]",
+        "reality": "Imports always land in the CURRENT media pool folder; the "
+                   "call has no destination-folder parameter, and passing an "
+                   "unrecognized one to the MCP tool is silently ignored.",
+        "recommended": "SetCurrentFolder to the target bin first (media_pool "
+                       "set_current_folder), import, then restore the previous "
+                       "current folder if it matters.",
+        "tags": ["media-pool", "import"],
+        "submit": "missing",
+    },
     {
         "symbol": "Graph.SetLUT (master-LUT-dir-only resolution)",
         "object": "Graph",