davinci-resolve-mcp 2.59.0 → 2.60.0

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 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.60.0
+
+A community bug-fix bundle — three external contributions plus the three issues
+they filed, integrated with the contributors credited as co-authors.
+
+### Fixed
+
+- **Frame accuracy (`edit_engine`)** — `MediaPool.AppendToTimeline` clipInfo
+  `endFrame` is an *exclusive* bound (duration = `endFrame - startFrame`), but
+  three plan builders wrote an inclusive end (`round(t*fps) - 1`) and
+  `execute_selects` advanced its record cursor by `end - start + 1`. Result:
+  `plan_tighten` kept ranges were one frame short per segment (~4.3s across 130
+  segments), `plan_selects`/`plan_swap` source ranges were one frame short, and
+  `execute_selects` left a 1-frame gap between selects. Now half-open everywhere.
+  (#82, thanks @chenyuxiaojin)
+- **Timeline rename no longer archives (`destructive_hook`)** — `timeline.set_name`
+  was version-on-mutate, so renames spawned redundant `_archived` timelines
+  (and renaming an archive archived the archive). A rename is content-preserving,
+  so it's out of the destructive registry. (#83, thanks @chenyuxiaojin)
+- **Windows startup (`server`)** — initialize the Resolve scripting env
+  (PYTHONHOME, PATH, `os.add_dll_directory`) before importing the fusionscript
+  bridge, avoiding a native access violation that crashed network transports
+  before bind. No-op off Windows. (#78, thanks @POLEPALLIANVESH)
+- Fixed a stale offline test that patched a refactored-away seam
+  (`project_manager` delete routing), restoring a fully green baseline.
+
+### Added
+
+- **`execute_tighten(..., include_details?)`** — the readback `structural_diff`
+  is compact by default (counts + a small head/tail sample) instead of embedding
+  every before/after item id (226 KB for a 130-segment tighten). The full
+  per-item diff is persisted in the plan record (`get_plan` →
+  `execution_summary.structural_diff`) and returned inline with
+  `include_details=true`. (#84, thanks @chenyuxiaojin)
+- **`plan_tighten` skip dedup** — identical `(item, reason)` skip rows collapse
+  into one entry with a `count` (an unanalyzed layer no longer repeats the same
+  row once per segment). (#81, thanks @chenyuxiaojin)
+
+### Documentation
+
+- Recorded the `AppendToTimeline` `endFrame` exclusive-bound semantics in the
+  `api_truth` ledger (internal quirk entry). (#80, thanks @chenyuxiaojin)
+
+### Validation
+
+- Full offline suite green (1343 tests). Static/drift guards pass.
+- Live Resolve validation of the #82 frame-accuracy fix (selects butt-join +
+  tighten frame-exact keep ranges) on a disposable project.
+
 ## What's New in v2.59.0
 
 First-class conform ingest for **AAF** and **DRP**, an offline **Premiere `.prproj`** reader with

package/README.md

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

@@ -794,8 +794,10 @@ clip-count readback plus `brain_edits` rationale rows.
   media-id fallback), and `readback` carries per-track-type
   `track_counts` plus an `audio_accounting` block so swap symmetry is
   verifiable. `execute_tighten` readback gains `structural_diff` (source
-  vs variant, via the same engine as `diff_timelines`); `execute_selects`
-  readback gains a `usage_summary`.
+  vs variant, via the same engine as `diff_timelines`) — compact by
+  default (counts + a small sample; full per-item diff persisted in the
+  plan record via `get_plan`, or inline with `include_details=true`);
+  `execute_selects` readback gains a `usage_summary`.
 - `list_plans(limit?)` / `get_plan(plan_id)`.
 
 The engine needs the analysis substrate: analyzed clips in the DB (run

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.59.0"
+VERSION = "2.60.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.59.0",
+  "version": "2.60.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.59.0"
+VERSION = "2.60.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.59.0"
+VERSION = "2.60.0"
 
 import base64
 import os
@@ -745,6 +745,32 @@ resolve = None
 dvr_script = None
 _resolve_lock = threading.RLock()
 
+# On Windows the fusionscript native bridge DLL must be locatable before the
+# Python import machinery attempts to load it.  Setting PYTHONHOME, prepending
+# the Resolve install directory to PATH, and registering it with
+# os.add_dll_directory() ensures the dynamic loader can find fusionscript.dll
+# and its dependencies even when the server is launched from a virtual-env or
+# a working directory that is not the Resolve install directory.  These steps
+# MUST happen before `import DaVinciResolveScript` or the import triggers a
+# native access-violation on Windows (crash before port bind in network mode).
+if sys.platform.startswith("win") and RESOLVE_LIB_PATH:
+    _resolve_install_dir = os.path.dirname(RESOLVE_LIB_PATH)
+    if os.path.isdir(_resolve_install_dir):
+        # Ensure Python's own runtime DLLs are discoverable by the bridge.
+        if not os.environ.get("PYTHONHOME"):
+            os.environ["PYTHONHOME"] = sys.base_prefix
+        # Prepend Resolve's install dir to PATH so the loader finds
+        # fusionscript.dll and sibling DLLs even without a system-wide install.
+        _cur_path = os.environ.get("PATH", "")
+        if _resolve_install_dir.lower() not in _cur_path.lower():
+            os.environ["PATH"] = _resolve_install_dir + os.pathsep + _cur_path
+        # os.add_dll_directory is available on Python 3.8+ (Windows only).
+        if hasattr(os, "add_dll_directory"):
+            try:
+                os.add_dll_directory(_resolve_install_dir)
+            except OSError:
+                pass
+
 try:
     import DaVinciResolveScript as dvr_script
     logger.info("DaVinciResolveScript module loaded")
@@ -17880,6 +17906,47 @@ def _edit_engine_capture(tl) -> Dict[str, Any]:
     return out
 
 
+def _compact_structural_diff(diff: Any, *, sample_n: int = 3) -> Any:
+    """Trim a compare_usage_snapshots result for the default execute response.
+
+    The full added/removed/moved/trimmed rows (one per timeline item, each with
+    media_pool_item_id + track + in/out frames) dominate large tighten
+    responses — 226 KB for a 130-segment tighten (issue #84). The counts already
+    live in `summary`; keep those plus a small head/tail sample per change kind.
+    The full diff is persisted in the executed plan record (edit_engine
+    get_plan(plan_id) → plan.execution_summary.structural_diff) and returned
+    inline when the caller passes include_details=true.
+    """
+    if not isinstance(diff, dict):
+        return diff
+    # An error stand-in (diff failed) or an already-compact payload: pass through.
+    if "summary" not in diff:
+        return diff
+    sample: Dict[str, Any] = {}
+    omitted = 0
+    for kind in ("added", "removed", "moved", "trimmed"):
+        rows = diff.get(kind)
+        if not isinstance(rows, list) or not rows:
+            continue
+        if len(rows) <= sample_n:
+            sample[kind] = list(rows)
+            continue
+        # Head sample + final row so the caller sees both ends of the change set.
+        sample[kind] = list(rows[: sample_n - 1]) + [rows[-1]]
+        omitted += len(rows) - sample_n
+    return {
+        "summary": diff.get("summary"),
+        "sample": sample,
+        "truncated": True,
+        "omitted_rows": omitted,
+        "detail_hint": (
+            "Full per-item diff persisted in the plan record — retrieve via "
+            "edit_engine get_plan(plan_id) → plan.execution_summary.structural_diff, "
+            "or re-run with include_details=true to inline it."
+        ),
+    }
+
+
 def _edit_engine_track_counts(tl) -> Dict[str, int]:
     """Per-track-type item counts — the swap symmetry signal in readback."""
     counts: Dict[str, int] = {}
@@ -18001,9 +18068,12 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       evidence for the current (or named) timeline. Kept ranges mirror onto the
       items' linked audio tracks by default so the variant is audible; pass
       include_audio=false for a video-only (silent) assembly.
-    - execute_tighten(plan_id, confirm_token?) — assembles a tightened VARIANT
-      timeline from the plan's keep ranges (video + mirrored audio), never
-      mutating the original. Readback includes an audio_accounting block.
+    - execute_tighten(plan_id, confirm_token?, include_details?) — assembles a
+      tightened VARIANT timeline from the plan's keep ranges (video + mirrored
+      audio), never mutating the original. Readback includes an audio_accounting
+      block and a compact structural_diff (counts + a small sample); the full
+      per-item diff is persisted in the plan record (get_plan → execution_summary)
+      and returned inline only when include_details=true.
     - plan_swap(track_index?, timeline_start_frame | item_name, kind?, limit?)
       — alternates for one timeline item via the similarity index.
     - execute_swap(plan_id, alternate_index, confirm_token?) — replaces the
@@ -18161,7 +18231,10 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 build_errors.append({"index": i, "error": row_err.get("error")})
                 continue
             built.append(row)
-            record_cursor += int(append_ci.get("end_frame", 0)) - int(append_ci.get("start_frame", 0)) + 1
+            # AppendToTimeline endFrame is exclusive: the item occupies
+            # (end - start) frames. Advancing by +1 more leaves a 1-frame gap
+            # (black flash) between consecutive selects. See api_truth endFrame entry.
+            record_cursor += int(append_ci.get("end_frame", 0)) - int(append_ci.get("start_frame", 0))
         appended = mp.AppendToTimeline(built) if built else None
         readback = _edit_engine_capture(tl)
         # A diff against a source timeline is meaningless for a fresh assembly;
@@ -18291,12 +18364,20 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             )
         except Exception:
             pass
+        # The full per-item structural diff is persisted in the plan record so it
+        # stays retrievable (edit_engine get_plan) without bloating every
+        # response — see issue #84. The MCP response carries a compact form by
+        # default and the full diff only when include_details=true.
+        include_details = _media_analysis_bool(
+            p.get("include_details", p.get("includeDetails")), False
+        )
         _edit_engine_mod.mark_plan_executed(project_root, plan["plan_id"], {
             "variant_timeline": variant.get("name") or variant_name,
             "keep_ranges": len(keep_ranges),
             "lifts": len(lifts),
             "before": before,
             "after": after,
+            "structural_diff": structural_diff,
         })
         return {
             "success": True,
@@ -18316,7 +18397,10 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     if before.get("duration_seconds") is not None and after.get("duration_seconds") is not None
                     else None
                 ),
-                "structural_diff": structural_diff,
+                "structural_diff": (
+                    structural_diff if include_details
+                    else _compact_structural_diff(structural_diff)
+                ),
                 "audio_accounting": {
                     "planned_audio_ranges": audio_keep_ranges,
                     "planned_video_ranges": video_keep_ranges,

package/src/utils/api_truth.py

@@ -508,6 +508,30 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "pass-through.",
         "tags": ["silent-failure", "color", "node-graph", "layout", "drx"],
     },
+    {
+        "symbol": "MediaPool.AppendToTimeline clipInfo endFrame (exclusive bound)",
+        "object": "MediaPool",
+        "signature": "([{mediaPoolItem, startFrame, endFrame, recordFrame, "
+                     "trackIndex, mediaType}]) -> [TimelineItem]",
+        "reality": "clipInfo endFrame is an EXCLUSIVE bound: the appended item's "
+                   "duration is endFrame - startFrame frames, not "
+                   "endFrame - startFrame + 1. Verified by readback probe on "
+                   "Resolve Studio 21.0 — appending {startFrame: 6254, "
+                   "endFrame: 6348} yields a 94-frame item, and 130 such "
+                   "appends whose absolute recordFrames advance by exactly "
+                   "(endFrame - startFrame) assemble a gap-free track whose "
+                   "total length equals the sum of (end - start). Code that "
+                   "assumes an inclusive bound drifts one frame per clip: "
+                   "advancing a record cursor by (end - start + 1) leaves a "
+                   "1-frame hole between consecutive clips, and converting a "
+                   "half-open range with (end - 1) shaves the range's last "
+                   "frame.",
+        "recommended": "Treat [startFrame, endFrame) as half-open everywhere: "
+                       "duration = endFrame - startFrame; next recordFrame = "
+                       "previous recordFrame + duration; no ±1 corrections "
+                       "when mirroring keep-ranges into clipInfos.",
+        "tags": ["timeline", "edit", "off-by-one", "readback"],
+    },
 ]
 
 

package/src/utils/destructive_hook.py

@@ -99,7 +99,10 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "set_track_enable",
         "set_track_name",
         "set_voice_isolation_state",
-        "set_name",
+        # NOTE: timeline.set_name (rename) is intentionally NOT here. A rename is
+        # content-preserving and trivially reversible, so version-on-mutate added
+        # no recovery value — it only spawned redundant `_archived` copies (one per
+        # rename, and renaming an archive archived the archive). Issue #83.
         "set_start_timecode",
         "set_setting",
         "set_mark_in_out",

package/src/utils/edit_engine.py

@@ -262,7 +262,10 @@ def plan_selects(
         if isinstance(clip_duration, (int, float)) and clip_duration:
             src_end = min(src_end, float(clip_duration))
         start_frame = int(round(src_start * fps))
-        end_frame = max(start_frame + 1, int(round(src_end * fps)) - 1)
+        # AppendToTimeline clipInfo endFrame is a half-open (exclusive) bound —
+        # duration = endFrame - startFrame. See api_truth "AppendToTimeline
+        # clipInfo endFrame". No -1: that would shave the last frame of every select.
+        end_frame = max(start_frame + 1, int(round(src_end * fps)))
         decision = {k: v for k, v in candidate.items() if not k.startswith("_")}
         decision["source_frame_range"] = [start_frame, end_frame]
         decisions.append(decision)
@@ -339,6 +342,29 @@ def _gaps_in_range(
     return gaps
 
 
+def _dedupe_skipped(skipped: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Collapse identical (item, reason) skip rows into one entry with a count.
+
+    A timeline layer cut into many segments from one unanalyzed source clip
+    otherwise reports the same skip once per segment (87 identical rows in a
+    real two-layer session), which bloats the plan payload without adding
+    signal. First occurrence order is preserved.
+    """
+    out: List[Dict[str, Any]] = []
+    index: Dict[Tuple[Any, Any], Dict[str, Any]] = {}
+    for row in skipped:
+        key = (row.get("item"), row.get("reason"))
+        hit = index.get(key)
+        if hit is None:
+            hit = dict(row)
+            hit["count"] = 1
+            index[key] = hit
+            out.append(hit)
+        else:
+            hit["count"] += 1
+    return out
+
+
 def plan_tighten(
     project_root: str,
     *,
@@ -440,6 +466,7 @@ def plan_tighten(
                 },
             })
 
+    skipped = _dedupe_skipped(skipped)
     if not lifts:
         return {
             "success": False,
@@ -492,7 +519,9 @@ def plan_tighten(
                 audio_indices = [1]
         for seg_start, seg_end in segments:
             start_frame = int(round(seg_start * clip_fps))
-            end_frame = max(start_frame + 1, int(round(seg_end * clip_fps)) - 1)
+            # Half-open (exclusive) endFrame — duration = end - start. No -1, else
+            # every kept segment loses its last frame (see api_truth endFrame entry).
+            end_frame = max(start_frame + 1, int(round(seg_end * clip_fps)))
             keep_ranges.append({
                 "clip_id": spec["resolve_clip_id"],
                 "start_frame": start_frame,
@@ -642,7 +671,9 @@ def plan_swap(
         alt = dict(alt_clip)
         alt_fps = _clip_fps(alt)
         start_frame = int(round(float(alt_start) * alt_fps))
-        end_frame = start_frame + int(round(needed_seconds * alt_fps)) - 1
+        # Half-open (exclusive) endFrame — duration = end - start fills the slot
+        # exactly. No -1, else the replacement lands one frame short of the slot.
+        end_frame = start_frame + int(round(needed_seconds * alt_fps))
         return {
             "score": score,
             "clip_uuid": clip_uuid,