davinci-resolve-mcp 2.208.0 → 2.208.1

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 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.208.1 — #188: variant item counts come from the timeline
+
+### Fixed
+
+- **A silence ripple under-reported what it built, by exactly half.**
+  `execute_silence_ripple` returned `variant_video_items: 250` and
+  `variant_audio_items: 250` for a variant that really held 432 of each. The
+  bridge's `ResolveOperations._encode` truncated every proxied container to
+  `max_items` (500) with no signal anywhere, and `plan_silence_ripple`
+  interleaves video and audio — so a 432-range plan became 864 clipInfos in one
+  `AppendToTimeline`, Resolve placed and returned all 864, and the first 500
+  encoded are precisely 250 video plus 250 audio. The same response's
+  `readback.after.clip_count` said 864 and was right the whole time, because it
+  re-reads per track: two numbers from two sources in one payload, one of them
+  silently short. "Planned 432, got 250" reads exactly like 182 ranges failing
+  to land, which on a silence ripple is the operator's central fear, and
+  establishing that it was benign cost a full review cycle of hand-auditing
+  both tracks. Reported and fixed in #188 by @mart0vip.
+- **Dropped elements are now reported, never silent.** `op_call` and
+  `op_get_attribute` carry a `truncated` block naming the count, limit and
+  containers; the client records it on `transport.truncations` and logs the
+  method. It warns rather than raises deliberately — the native call has
+  already run by the time the reply is encoded, so raising would turn a
+  completed 864-item assembly into an error and orphan the timeline. A short
+  list that looks complete was the failure mode; the bound itself is
+  legitimate.
+- **The item ceiling no longer exceeds the handle table.** `max_items` was
+  clamped to 5000 against a 4096-entry `MAX_HANDLES`, so a long enough list
+  evicted its own earliest handles while it was still being minted and handed
+  the client ids that were already `stale_handle`. It now clamps to
+  `MAX_HANDLES`, with the default raised 500 → 2000.
+- **Counts come from the timeline, not the append reply.**
+  `create_variant_from_ranges` reports `placed_item_counts` from the
+  post-assembly per-track re-read it was already taking for gap detection — no
+  extra Resolve calls — and `execute_silence_ripple` and `execute_tighten` now
+  share one accounting helper, tighten having carried the identical bug. A
+  planned-vs-placed disagreement is stated outright instead of left to a hand
+  audit.
+- Beyond reporting: under the old ceiling a `cdl` applied to a large variant
+  only reached the first 250 video items.
+
 ## What's New in v2.208.0 — agent execution lifecycle & pre-flight risk inspection
 
 Adapted from the design contributed in PR #187.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.208.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.208.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-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.208.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.208.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-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.208.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.208.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.208.0"
+VERSION = "2.208.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 353-tool granular server instead
 """
 
-VERSION = "2.208.0"
+VERSION = "2.208.1"
 
 import base64
 import os
@@ -6606,6 +6606,26 @@ def _variant_item_placement(item) -> Dict[str, Any]:
     }
 
 
+def _snapshot_track_item_counts(snapshot: Dict[str, Any]) -> Dict[str, int]:
+    """Per-track-type item counts read from a conform snapshot of a live timeline.
+
+    This is the ONLY honest answer to "what did the assembly actually place".
+    The obvious alternative — counting what `MediaPool.AppendToTimeline`
+    returned — is a witness derived from the same call it would be checking, and
+    it lies in two measured ways: the in-app bridge caps any proxied list at
+    `max_items` (an 864-clipInfo append came back as 500 items, so a variant
+    holding 432 video + 432 audio was reported as 250 + 250), and Resolve drops
+    colliding records from the reply without an error (see the api_truth entry
+    "MediaPool.AppendToTimeline (overlapping records — earlier item wins)").
+    Re-reading the timeline per track cannot be fooled by either.
+    """
+    counts: Dict[str, int] = {}
+    for track_type, block in (snapshot.get("tracks") or {}).items():
+        rows = (block or {}).get("tracks") or []
+        counts[str(track_type)] = sum(int(row.get("item_count") or 0) for row in rows)
+    return counts
+
+
 def _variant_audio_summary(built):
     """Video/audio range counts for an assembled variant, warning when it carries
     no audio. create_variant_from_ranges places exactly the ranges given, so a
@@ -6618,6 +6638,61 @@ def _variant_audio_summary(built):
     return summary
 
 
+def _variant_audio_accounting(variant: Dict[str, Any], *, planned_video: int,
+                              planned_audio: int) -> Dict[str, Any]:
+    """The planned-vs-placed block on a tighten / silence-ripple readback.
+
+    Shared by execute_tighten and execute_silence_ripple so the two cannot
+    drift: they answer the same operator question, "did every range I planned
+    actually land in the variant".
+
+    Placed counts come from the assembler's post-assembly re-read of the
+    timeline, never from what `AppendToTimeline` returned — see
+    `_snapshot_track_item_counts` for why the append's reply is not evidence.
+    A count that is short for a *reporting* reason and a count that is short
+    because material was dropped must never look the same here: on a silence
+    ripple the operator's whole fear is dropped material, so a disagreement is
+    stated outright rather than left to be discovered by hand-auditing tracks.
+    """
+    placed = variant.get("placed_item_counts")
+    video = (placed or {}).get("video")
+    audio = (placed or {}).get("audio")
+    accounting: Dict[str, Any] = {
+        "planned_audio_ranges": planned_audio,
+        "planned_video_ranges": planned_video,
+        "variant_audio_items": audio,
+        "variant_video_items": video,
+        "counts_source": "post-assembly per-track read of the variant timeline",
+    }
+    if video is None or audio is None:
+        accounting["note"] = (
+            "Placed item counts are UNAVAILABLE — the variant could not be re-read "
+            "after assembly. Verify with timeline_item get_items_in_track before "
+            "using this variant."
+        )
+        return accounting
+    disagreements = []
+    if video != planned_video:
+        disagreements.append(f"video {video}/{planned_video}")
+    if audio != planned_audio:
+        disagreements.append(f"audio {audio}/{planned_audio}")
+    if disagreements:
+        accounting["note"] = (
+            "PLACED COUNT DISAGREES WITH THE PLAN (placed/planned: "
+            + ", ".join(disagreements)
+            + ") — ranges did not land. Resolve drops colliding records from an "
+            "append without erroring; check readback.gaps_overlaps and the "
+            "tracks themselves before using this variant."
+        )
+    elif planned_audio:
+        accounting["note"] = "Variant carries audio mirrored from the video cuts."
+    else:
+        accounting["note"] = (
+            "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
+        )
+    return accounting
+
+
 def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) -> Dict[str, Any]:
     ranges = p.get("ranges") or p.get("clip_infos")
     if not isinstance(ranges, list) or not ranges:
@@ -6768,16 +6843,21 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
     if p.get("cdl"):
         target_ids = [row.get("timeline_item_id") for row in items_out if row.get("timeline_item_id") and row.get("range", {}).get("media_type") == 1]
         look_result = _timeline_apply_look_to_items(new_tl, {"target_ids": target_ids, "cdl": p.get("cdl")})
+    # One snapshot, two consumers: gap detection and the placed-item counts.
+    # `items` above is only as complete as the append's REPLY, so it is not
+    # evidence of what landed — `placed_item_counts` re-reads the timeline.
+    snapshot = _timeline_conform_snapshot(new_tl, {})
     return {
         "success": True,
         "name": new_tl.GetName(),
         "id": new_tl.GetUniqueId(),
         "items": items_out,
+        "placed_item_counts": _snapshot_track_item_counts(snapshot),
         "placement_mismatches": placement_mismatches,
         "audio": _variant_audio_summary(built),
         "markers": marker_results,
         "look": look_result,
-        "gaps_overlaps": _detect_gaps_overlaps_from_snapshot(_timeline_conform_snapshot(new_tl, {}), {}),
+        "gaps_overlaps": _detect_gaps_overlaps_from_snapshot(snapshot, {}),
     }
 
 
@@ -24172,24 +24252,11 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     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,
-                    # variant_* count placed items; variant["audio"] counts requested ranges.
-                    "variant_audio_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 2
-                    ),
-                    "variant_video_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 1
-                    ),
-                    "note": (
-                        "Variant carries audio mirrored from the video cuts."
-                        if audio_keep_ranges
-                        else "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
-                    ),
-                },
+                # variant_* count PLACED items, re-read from the variant;
+                # variant["audio"] counts requested ranges.
+                "audio_accounting": _variant_audio_accounting(
+                    variant, planned_video=video_keep_ranges, planned_audio=audio_keep_ranges,
+                ),
             },
             "plan_id": plan.get("plan_id"),
         }
@@ -24308,23 +24375,9 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     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,
-                    "variant_audio_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 2
-                    ),
-                    "variant_video_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 1
-                    ),
-                    "note": (
-                        "Variant carries audio mirrored from the video cuts."
-                        if audio_keep_ranges
-                        else "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
-                    ),
-                },
+                "audio_accounting": _variant_audio_accounting(
+                    variant, planned_video=video_keep_ranges, planned_audio=audio_keep_ranges,
+                ),
             },
             "plan_id": plan.get("plan_id"),
         }

package/src/utils/resolve_bridge_client.py

@@ -33,6 +33,18 @@ proxy deliberately does not.
   timeline item-by-item is the shape that bites.
 - **Bridge absence.** If the in-Resolve script is not running, construction fails
   with a clear message rather than pretending; there is nothing to fall back to.
+- **Incomplete replies.** A returned container longer than the surface's
+  `max_items` comes back short. That used to be invisible, and a short list is
+  indistinguishable from a genuinely short result — an 864-clipInfo
+  `AppendToTimeline` returned 500 items and a caller counted them as the whole
+  answer. The surface now reports every drop and `_BoundMethod` surfaces it
+  (`transport.truncations`, plus a warning naming the method).
+
+  It warns rather than raising, deliberately: the native call has already *run*
+  by the time the reply is encoded, so raising would turn completed Resolve work
+  — a placed 864-item assembly — into an error and orphan the result. The honest
+  handling is for the caller to stop treating a returned list as a count, which
+  is why the tools that report item counts re-read them from the timeline.
 """
 
 from __future__ import annotations
@@ -117,6 +129,31 @@ class BridgeTransport:
         # keeps request/response pairing simple and matches the _bridge_lock
         # discipline the rest of the server already follows.
         self._lock = threading.RLock()
+        #: Replies the surface reported as incomplete, newest last: one row per
+        #: (method, dropped, total). Kept so a caller that suspects a short
+        #: enumeration can prove it instead of inferring it from a count that
+        #: looks plausible. Bounded — this is a diagnostic, not a log.
+        self.truncations: List[Dict[str, Any]] = []
+
+    def note_truncation(self, method: str, truncated: Any) -> None:
+        """Record and announce a reply the surface could not carry in full."""
+        if not isinstance(truncated, dict):
+            return
+        row = {"method": method, **truncated}
+        with self._lock:
+            self.truncations.append(row)
+            del self.truncations[:-32]
+        # Shapes here come off the wire from a bridge that may be older than
+        # this client, so nothing is indexed or assumed present.
+        containers = truncated.get("containers")
+        first = containers[0] if isinstance(containers, list) and containers else {}
+        logger.warning(
+            "bridge reply for %s was TRUNCATED: %s of %s elements dropped (limit %s). "
+            "The returned list is not a count — re-read the object instead.",
+            method, truncated.get("dropped"),
+            first.get("total") if isinstance(first, dict) else None,
+            truncated.get("limit"),
+        )
 
     def request(self, operation: str, arguments: Dict[str, Any]) -> Any:
         payload = {
@@ -251,6 +288,7 @@ class _BoundMethod:
             {"target": self._handle, "method": self._name,
              "args": [_encode_argument(a) for a in args]},
         )
+        self._transport.note_truncation(self._name, (result or {}).get("truncated"))
         return _decode_value(self._transport, (result or {}).get("value"))
 
     def __repr__(self) -> str:  # pragma: no cover - debugging aid
@@ -345,6 +383,7 @@ class BridgeProxy:
                 probe = self._transport.request("get_attribute",
                                                 {"target": self._handle, "name": name}) or {}
                 if probe.get("kind") == "value":
+                    self._transport.note_truncation(name, probe.get("truncated"))
                     return _decode_value(self._transport, probe.get("value"))
                 if (name in _FUSION_UNENUMERATED_METHODS
                         and self._methods() & _FUSION_OBJECT_MARKERS):

package/src/utils/resolve_bridge_ops.py

@@ -174,13 +174,22 @@ class ResolveOperations:
     #: loses a handle gets a clear `stale_handle` error and can re-fetch.
     MAX_HANDLES = 4096
 
+    #: Elements carried out of one encoded return value. A timeline-scale
+    #: enumeration has to fit: the old 500 silently halved an 864-item
+    #: `AppendToTimeline` return, and the caller counted the 500 it got as the
+    #: whole truth (a 432+432 variant read back as 250+250, issue: silence-ripple
+    #: audio_accounting). Whatever the ceiling is, exceeding it is now REPORTED
+    #: — see `_encode` — because a short list that looks complete is the failure
+    #: mode, not the bound itself.
+    DEFAULT_MAX_ITEMS = 2000
+
     def __init__(
         self,
         resolve: Any,
         *,
         media_roots: List[str],
         output_roots: List[str],
-        max_items: int = 500,
+        max_items: int = DEFAULT_MAX_ITEMS,
         lifecycle: Optional[Callable[[str], Dict[str, Any]]] = None,
     ) -> None:
         if resolve is None:
@@ -191,7 +200,16 @@ class ResolveOperations:
         # pretending to stop something they have no handle on.
         self._lifecycle = lifecycle
         self.policy = PathPolicy(media_roots, output_roots)
-        self.max_items = max(1, min(int(max_items), 5000))
+        # Capped at MAX_HANDLES, not at some larger round number: every live
+        # object in an encoded list mints a handle, so a list longer than the
+        # table evicts its own earliest entries before the client can use them
+        # and hands back handles that are already `stale_handle`. A ceiling
+        # above the table would trade a short list for a poisoned one.
+        self.max_items = max(1, min(int(max_items), self.MAX_HANDLES))
+        #: Set by `_encode` when a return value did not fit, read by the ops
+        #: that encode. Not a counter across calls — it answers "was THIS reply
+        #: complete", which is the only question a caller can act on.
+        self._encode_truncation: List[Dict[str, Any]] = []
         self._routes: Dict[str, Callable[[Dict[str, Any]], Any]] = {
             name: getattr(self, f"op_{name}") for name in self.OPERATIONS
         }
@@ -507,21 +525,68 @@ class ResolveOperations:
         Every object produced by one call carries the same shape, including the
         elements of a returned list — a track's timeline items are homogeneous,
         which is exactly the case where sharing a cached method set pays.
+
+        **Dropping elements is recorded, never silent.** A container longer than
+        `max_items` used to come back shortened with nothing anywhere saying so,
+        and a short list is indistinguishable from a genuinely short result: an
+        864-clipInfo `AppendToTimeline` returned 500 items, the caller counted
+        them, and a variant holding 432 video + 432 audio was reported to the
+        operator as 250 + 250 — which reads exactly like 182 ranges failing to
+        land. The bound itself is legitimate (see `max_items`); hiding it is
+        not, so every drop is reported alongside the value.
         """
         if value is None or isinstance(value, (bool, int, float, str)):
             return value
         if depth > 6:
             return str(value)
         if isinstance(value, (list, tuple)):
-            return [self._encode(v, depth + 1, shape) for v in list(value)[: self.max_items]]
+            items = list(value)
+            self._note_truncation(len(items), "list", depth, shape)
+            return [self._encode(v, depth + 1, shape) for v in items[: self.max_items]]
         if isinstance(value, dict):
-            return {str(k): self._encode(v, depth + 1, shape) for k, v in list(value.items())[: self.max_items]}
+            pairs = list(value.items())
+            self._note_truncation(len(pairs), "dict", depth, shape)
+            return {str(k): self._encode(v, depth + 1, shape) for k, v in pairs[: self.max_items]}
         return {
             "__handle__": self._mint(value, shape),
             "__type__": type(value).__name__,
             "__shape__": shape,
         }
 
+    def _note_truncation(self, total: int, kind: str, depth: int, shape: str) -> None:
+        if total <= self.max_items:
+            return
+        self._encode_truncation.append({
+            "shape": shape, "kind": kind, "depth": depth,
+            "returned": self.max_items, "total": total,
+            "dropped": total - self.max_items,
+        })
+
+    def _encoded(self, value: Any, shape: str) -> Dict[str, Any]:
+        """Encode one return value into a reply, carrying any truncation with it.
+
+        The `truncated` block is the whole point: a caller that reads `value` as
+        a complete answer is wrong exactly when this key is present, and it
+        cannot know that from the value alone.
+        """
+        self._encode_truncation = []
+        encoded = self._encode(value, shape=shape)
+        reply: Dict[str, Any] = {"value": encoded}
+        if self._encode_truncation:
+            dropped = sum(row["dropped"] for row in self._encode_truncation)
+            reply["truncated"] = {
+                "dropped": dropped,
+                "limit": self.max_items,
+                "containers": self._encode_truncation[:8],
+                "hint": (
+                    "This reply is INCOMPLETE — the value is not evidence of how many "
+                    "items exist. Re-read in smaller pieces, or count from the object "
+                    "itself rather than from this list."
+                ),
+            }
+            self._encode_truncation = []
+        return reply
+
     def _decode(self, value: Any) -> Any:
         """Argument -> live object, rehydrating handles the bridge itself issued."""
         if isinstance(value, dict):
@@ -571,7 +636,7 @@ class ResolveOperations:
                 "resolve_raised",
                 f"Resolve raised while running {method}: {str(exc)[:200]}",
             )
-        return {"value": self._encode(result, shape=f"{self._shape_of(target_key)}.{method}")}
+        return self._encoded(result, shape=f"{self._shape_of(target_key)}.{method}")
 
     def op_list_methods(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
         """The public attribute names on a target — what `hasattr` should answer.
@@ -690,7 +755,8 @@ class ResolveOperations:
             return {"kind": "none",
                     "note": "present-but-None; on Resolve objects this is indistinguishable "
                             "from absent, because getattr never raises"}
-        return {"kind": "value", "value": self._encode(value, shape=f"{self._shape_of(arguments.get('target', 'resolve'))}.{name}")}
+        encoded = self._encoded(value, shape=f"{self._shape_of(arguments.get('target', 'resolve'))}.{name}")
+        return {"kind": "value", **encoded}
 
     def op_release_handles(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
         """Drop handles a client no longer needs, or all of them."""