davinci-resolve-mcp 2.33.6 → 2.33.8

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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.33.8
+
+Bridge-call performance instrumentation.
+
+- **Added** `src/utils/bridge_metrics.py` — a counting proxy that wraps a Resolve
+  handle and tallies attribute accesses and method calls (each a COM/socket
+  round-trip), so the real bridge cost of an operation is measured rather than
+  guessed.
+- **Added** `scripts/measure_bridge_cost.py` — runs a representative media-pool
+  traversal through the proxy and reports round-trips per clip. A minimal
+  name+type walk measured ~6.7 round-trips per clip, confirming round-trips scale
+  linearly with traversal size. A property cache remains gated on profiling
+  *repeated*-read patterns in real workflows (don't cache blind).
+
+## What's New in v2.33.7
+
+Read/write symmetry audit and a gap it surfaced.
+
+- **Added** `scripts/audit_readwrite_symmetry.py` + generated
+  `docs/reference/readwrite-symmetry.md` — scans every tool's action surface and
+  reports `set_`/`add_`/`create_` writes that lack a read counterpart, so
+  write-without-read gaps surface before users hit them. A repeatable
+  feature-discovery method.
+- **Added** `fusion_comp(action="get_frame_range")` — reads the comp's render
+  frame range, the read counterpart to `set_frame_range` (a gap the audit found).
+
 ## What's New in v2.33.6
 
 Internal consolidation: a declarative parameter-contract validator and centralized

package/README.md

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

package/docs/SKILL.md

@@ -997,7 +997,7 @@ Key actions:
   temp `.setting` file), optionally renaming and repositioning it
 - `auto_arrange(tool_names?, direction?, spacing?, x?, y?)` — lay tools out in a row
   (`direction="horizontal"`, default) or column (`"vertical"`)
-- `get_comp_info`, `set_frame_range(start, end)`, `render`
+- `get_comp_info`, `set_frame_range(start, end)`, `get_frame_range`, `render`
 - `start_undo(name?)` / `end_undo(keep?)`
 - `bulk_set_inputs(ops)` — batch set inputs across multiple timeline item comps in
   one call; each op requires timeline scope plus `tool_name`, `input_name`, `value`

package/docs/reference/readwrite-symmetry.md

@@ -0,0 +1,25 @@
+<!-- Generated by scripts/audit_readwrite_symmetry.py — do not edit by hand. -->
+
+# Read/Write Symmetry Audit
+
+- write-style actions scanned: **106**
+- with a matching read: **57**
+- `set_` actions with no `get_`/`list_` (real readback gaps): **11**
+
+## High-signal gaps — `set_` with no read counterpart
+
+- `set_cache`
+- `set_cdl`
+- `set_clips_linked`
+- `set_high_priority`
+- `set_keyframe_interpolation`
+- `set_mcp_update_policy`
+- `set_name`
+- `set_node_enabled`
+- `set_title_text`
+- `set_track_enable`
+- `set_track_lock`
+
+## Low-signal (create/add/insert/import — usually expected): 37
+
+`add_clip_mattes`, `add_comp`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_burnin`, `import_comp`, `import_folder`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/install.py

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

package/scripts/audit_readwrite_symmetry.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Audit read/write symmetry across the compound server's action surface.
+
+For every mutating action (set_/add_/clear_/enable_/...) it checks whether a
+matching read action (get_/list_/...) exists on the same tool, and reports the
+asymmetries. The goal is to find write-without-read gaps before users have to —
+the repeatable feature-discovery method behind R5.
+
+Reads the `_unknown(action, [...])` lists in src/server.py, which enumerate every
+action a tool accepts. Prints a markdown report.
+"""
+import ast
+import os
+import re
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+SERVER = os.path.join(ROOT, "src", "server.py")
+
+READ_PREFIXES = ("get_", "list_", "probe_", "is_", "has_", "find_")
+# `set_` is the high-signal class: a set with no get is a genuine readback gap.
+# create_/add_/insert_/import_ are inherently writes that usually have no paired
+# read of the same noun, so they're reported separately as low-signal.
+HIGH_SIGNAL = ("set_",)
+LOW_SIGNAL = ("add_", "create_", "insert_", "apply_", "import_")
+
+
+def _action_lists(src: str):
+    """Yield lists of action-name string literals from each _unknown(action, [...])."""
+    for m in re.finditer(r"_unknown\(action,\s*\[(.*?)\]\)", src, re.DOTALL):
+        names = re.findall(r'"([a-z][a-z0-9_]*)"', m.group(1))
+        if names:
+            yield names
+
+
+def _has_read(stem: str, aset: set) -> bool:
+    # Match get_<stem>, list_<stem>, and plural get_<stem>s (e.g. add_keyframe -> get_keyframes).
+    candidates = {rp + stem for rp in READ_PREFIXES}
+    candidates |= {rp + stem + "s" for rp in READ_PREFIXES}
+    candidates |= {rp + stem.rstrip("s") for rp in READ_PREFIXES}
+    return bool(candidates & aset)
+
+
+def audit(src: str):
+    high, low, covered, total = set(), set(), 0, 0
+    for actions in _action_lists(src):
+        aset = set(actions)
+        for a in actions:
+            for wp in HIGH_SIGNAL + LOW_SIGNAL:
+                if a.startswith(wp):
+                    total += 1
+                    stem = a[len(wp):]
+                    if _has_read(stem, aset):
+                        covered += 1
+                    elif wp in HIGH_SIGNAL:
+                        high.add(a)
+                    else:
+                        low.add(a)
+                    break
+    return total, covered, sorted(high), sorted(low)
+
+
+def main():
+    src = open(SERVER, encoding="utf-8").read()
+    total, covered, high, low = audit(src)
+    print("# Read/Write Symmetry Audit\n")
+    print(f"- write-style actions scanned: **{total}**")
+    print(f"- with a matching read: **{covered}**")
+    print(f"- `set_` actions with no `get_`/`list_` (real readback gaps): **{len(high)}**\n")
+    if high:
+        print("## High-signal gaps — `set_` with no read counterpart\n")
+        for a in high:
+            print(f"- `{a}`")
+    print(f"\n## Low-signal (create/add/insert/import — usually expected): {len(low)}\n")
+    print(", ".join(f"`{a}`" for a in low))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/measure_bridge_cost.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Measure DaVinci Resolve bridge round-trips for representative operations.
+
+Wraps the live project in a counting proxy and runs a few common traversals,
+reporting how many attribute accesses + method calls (each a bridge round-trip)
+they cost. This is the measurement that gates whether a property cache is worth
+building. Run against an OPEN project; it only reads.
+
+    PYTHONPATH=. venv/bin/python scripts/measure_bridge_cost.py
+"""
+import sys
+
+import src.server as s
+from src.utils.bridge_metrics import measure
+
+
+def _walk_media_pool(project_proxy):
+    """A typical media-pool traversal: every folder, every clip, name + a property."""
+    mp = project_proxy.GetMediaPool()
+    root = mp.GetRootFolder()
+    clips_seen = 0
+
+    def walk(folder):
+        nonlocal clips_seen
+        for clip in (folder.GetClipList() or []):
+            clip.GetName()
+            clip.GetClipProperty("Type")
+            clips_seen += 1
+        for sub in (folder.GetSubFolderList() or []):
+            walk(sub)
+
+    walk(root)
+    return clips_seen
+
+
+def main():
+    r = s.get_resolve()
+    if not r:
+        print("Not connected to Resolve.")
+        return 1
+    proj = r.GetProjectManager().GetCurrentProject()
+    if not proj:
+        print("No project open.")
+        return 1
+
+    clips_holder = {}
+
+    def op(proj_proxy):
+        clips_holder["n"] = _walk_media_pool(proj_proxy)
+
+    counts = measure(op, proj)
+    n = clips_holder.get("n", 0)
+    total = counts["attr_access"] + counts["calls"]
+    print(f"project: {proj.GetName()!r}")
+    print(f"clips walked: {n}")
+    print(f"bridge attr-accesses: {counts['attr_access']}")
+    print(f"bridge method-calls:  {counts['calls']}")
+    print(f"total round-trips:    {total}")
+    if n:
+        print(f"round-trips per clip: {total / n:.1f}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.33.6"
+VERSION = "2.33.8"
 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.33.6"
+VERSION = "2.33.8"
 
 import base64
 import os
@@ -18730,6 +18730,7 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       auto_arrange(tool_names?, direction?, spacing?, x?, y?) -> {success, arranged, count}
         Lay tools out in a row (direction="horizontal", default) or column ("vertical").
       set_frame_range(start, end) -> {success}
+      get_frame_range() -> {start, end}  — read the comp's render frame range
       render() -> {success}
       start_undo(name?) -> {success}
       end_undo(keep?) -> {success}
@@ -19021,6 +19022,13 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         comp.SetAttrs({"COMPN_RenderStartTime": p["start"], "COMPN_RenderEndTime": p["end"]})
         return _ok()
 
+    elif action == "get_frame_range":
+        attrs = comp.GetAttrs() or {}
+        return {
+            "start": attrs.get("COMPN_RenderStartTime"),
+            "end": attrs.get("COMPN_RenderEndTime"),
+        }
+
     elif action == "render":
         comp.Render()
         return _ok()
@@ -19159,7 +19167,7 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         "connect","disconnect","get_inputs","get_outputs",
         "set_input","get_input","set_attrs","get_attrs",
         "add_keyframe","get_keyframes","delete_keyframe",
-        "get_comp_info","set_frame_range","render",
+        "get_comp_info","set_frame_range","get_frame_range","render",
         "start_undo","end_undo",
         "get_position","set_position","copy_tool","auto_arrange",
         "bulk_set_inputs",

package/src/utils/bridge_metrics.py

@@ -0,0 +1,76 @@
+"""Instrumentation for counting DaVinci Resolve bridge round-trips.
+
+Every attribute access and method call on a Resolve object is a COM/socket
+round-trip — the dominant cost of most operations. Before optimizing (or adding
+a cache), you have to *measure* where the round-trips concentrate. This module
+provides an opt-in counting proxy that wraps a Resolve handle and tallies
+attribute accesses and method calls, so a hot path's real bridge cost is
+visible instead of guessed.
+
+This is the measurement half of the bridge-perf work. A property cache is only
+worth building once measurement shows a clear, repeated-read hot spot — don't
+cache blind.
+
+Example:
+
+    counts = {}
+    rp = CountingProxy(resolve, counts)
+    rp.GetProjectManager().GetCurrentProject().GetName()
+    print(counts)  # {'attr_access': N, 'calls': M}
+"""
+from typing import Any, Dict, Optional
+
+
+class CountingProxy:
+    """Wrap a Resolve object, counting attribute accesses and method calls.
+
+    Method return values that are themselves objects are wrapped too, so a whole
+    call chain through the bridge is counted. Primitives are returned as-is.
+    """
+
+    __slots__ = ("_target", "_counter")
+
+    def __init__(self, target: Any, counter: Dict[str, int]):
+        object.__setattr__(self, "_target", target)
+        object.__setattr__(self, "_counter", counter)
+        counter.setdefault("attr_access", 0)
+        counter.setdefault("calls", 0)
+
+    def __getattr__(self, name: str) -> Any:
+        counter = object.__getattribute__(self, "_counter")
+        target = object.__getattribute__(self, "_target")
+        counter["attr_access"] += 1
+        attr = getattr(target, name)
+        if callable(attr):
+            def wrapped(*args: Any, **kwargs: Any) -> Any:
+                counter["calls"] += 1
+                result = attr(*args, **kwargs)
+                return _maybe_wrap(result, counter)
+            return wrapped
+        return _maybe_wrap(attr, counter)
+
+
+_PRIMITIVE = (str, int, float, bool, bytes, type(None))
+
+
+def _maybe_wrap(value: Any, counter: Dict[str, int]) -> Any:
+    if isinstance(value, _PRIMITIVE):
+        return value
+    if isinstance(value, (list, tuple)):
+        # Wrap object elements so traversals (e.g. clip lists) are counted.
+        return type(value)(_maybe_wrap(v, counter) for v in value)
+    if isinstance(value, dict):
+        return {k: _maybe_wrap(v, counter) for k, v in value.items()}
+    # Likely a Resolve API object — wrap so its further use is counted.
+    return CountingProxy(value, counter)
+
+
+def measure(fn, target: Any) -> Dict[str, int]:
+    """Run ``fn(proxy)`` against a counting proxy of ``target``; return the counts.
+
+    ``fn`` receives the proxy and should exercise the operation under study.
+    """
+    counter: Dict[str, int] = {}
+    proxy = CountingProxy(target, counter)
+    fn(proxy)
+    return counter