davinci-resolve-mcp 2.33.2 → 2.33.4

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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.4
+
+Internal reliability framework.
+
+- **Added** `verify_by_readback` (`src/utils/readback.py`) — a primitive for
+  mutating Resolve ops that verifies an action by reading the real post-state
+  back instead of trusting the API's frequently-unreliable return value. A
+  contradiction (reported success but a failing readback) is logged as a
+  reliability signal.
+- **Changed** Auto-sync audio now runs through `verify_by_readback` as its first
+  user and reports a `verified` field alongside `linked`/`newly_linked`. Behavior
+  is unchanged; the bespoke readback loop is replaced by the shared primitive.
+
+## What's New in v2.33.3
+
+Two read tools that surface existing project state.
+
+- **Added** `project_settings(action="project_summary")` returns a live
+  structural readout — current page, timeline count and current timeline, and a
+  media-pool inventory (folder/clip counts, clips by type, optional clip
+  sample). A cheap "what's in this project right now" snapshot that needs no
+  prior analysis.
+- **Added** `timeline(action="get_transcript")` reads the current timeline's
+  subtitle track(s) as transcript text `{text, cue_count, has_subtitles, cues}`,
+  with optional per-cue timecodes. Complements the clip-level
+  `get_transcription`.
+
 ## What's New in v2.33.2
 
 Documentation: a guide for hand-authoring DaVinci Resolve `.setting` template

package/README.md

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

@@ -402,7 +402,9 @@ Key actions: `get_name`, `set_name(name)`, `get_setting(name?)`,
 `set_setting(name, value)`, `get_color_groups`, `add_color_group(name)`,
 `delete_color_group(name)`, `export_frame_as_still(path)`,
 `load_burnin_preset(name)`, `insert_audio(media_path, ...)`,
-`apply_fairlight_preset(preset_name)`
+`apply_fairlight_preset(preset_name)`,
+`project_summary(include_clips?, clip_limit?)` — live structural readout
+(current page, timeline count, media-pool inventory by type)
 
 ---
 
@@ -723,6 +725,8 @@ Key actions:
 - `get_current` — current timeline info
 - `set_current(index)` — switch timeline by 1-based index
 - `get_track_count(track_type)` — track_type: `"video"`, `"audio"`, `"subtitle"`
+- `get_transcript(with_timecodes?)` — read the subtitle track(s) as transcript
+  text `{text, cue_count, has_subtitles, cues}`
 - `add_track(track_type, sub_type?)` / `delete_track(track_type, index)`
 - `get_items(track_type, index)` — items on a track
 - `clip_where(track_type?, track_index?, name_contains?, duration_lt?, duration_gt?)` —

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.33.2"
+VERSION = "2.33.4"
 # 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.2",
+  "version": "2.33.4",
   "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.33.2"
+VERSION = "2.33.4"
 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.2"
+VERSION = "2.33.4"
 
 import base64
 import os
@@ -43,6 +43,7 @@ for p in [current_dir, project_dir]:
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
 from src.utils.mcp_stdio import run_fastmcp_stdio
+from src.utils.readback import verify_by_readback
 from src.utils.update_check import (
     check_for_updates,
     clear_update_prompt_preferences,
@@ -1885,6 +1886,89 @@ def _navigate_folder(mp, path):
     return current
 
 
+def _project_summary(proj, *, include_clips=False, clip_limit=50):
+    """Live structural readout of a project: page, timelines, media-pool inventory.
+
+    Distinct from the analysis-derived bin summary — this is a cheap "what's in
+    this project right now" snapshot that needs no prior analysis.
+    """
+    by_type: Dict[str, int] = {}
+    sample_clips: List[Dict[str, Any]] = []
+    folder_count = 0
+    clip_count = 0
+
+    mp = proj.GetMediaPool()
+    root = mp.GetRootFolder() if mp else None
+
+    def walk(folder):
+        nonlocal folder_count, clip_count
+        folder_count += 1
+        for clip in (folder.GetClipList() or []):
+            clip_count += 1
+            try:
+                ctype = clip.GetClipProperty("Type") or "Unknown"
+            except Exception:
+                ctype = "Unknown"
+            by_type[ctype] = by_type.get(ctype, 0) + 1
+            if include_clips and len(sample_clips) < clip_limit:
+                sample_clips.append({
+                    "name": _clip_name(clip),
+                    "type": ctype,
+                    "id": clip.GetUniqueId(),
+                })
+        for sub in (folder.GetSubFolderList() or []):
+            walk(sub)
+
+    if root:
+        walk(root)
+
+    cur_tl = proj.GetCurrentTimeline()
+    r = get_resolve()
+    return {
+        "project": proj.GetName(),
+        "current_page": r.GetCurrentPage() if r else None,
+        "timeline_count": proj.GetTimelineCount(),
+        "current_timeline": cur_tl.GetName() if cur_tl else None,
+        "media_pool": {
+            "folder_count": folder_count,
+            "clip_count": clip_count,
+            "by_type": by_type,
+        },
+        "clips": sample_clips if include_clips else None,
+    }
+
+
+def _timeline_transcript(tl, *, with_timecodes=False):
+    """Read a timeline's subtitle track(s) as transcript text."""
+    try:
+        track_count = tl.GetTrackCount("subtitle")
+    except Exception:
+        track_count = 0
+    cues: List[Dict[str, Any]] = []
+    for ti in range(1, (track_count or 0) + 1):
+        for item in (tl.GetItemListInTrack("subtitle", ti) or []):
+            text = ""
+            try:
+                text = item.GetName() or ""
+            except Exception:
+                text = ""
+            cue = {"text": text}
+            if with_timecodes:
+                try:
+                    cue["start"] = item.GetStart()
+                    cue["end"] = item.GetEnd()
+                except Exception:
+                    pass
+            cues.append(cue)
+    full = " ".join(c["text"] for c in cues if c.get("text"))
+    return {
+        "text": full,
+        "cue_count": len(cues),
+        "has_subtitles": bool(cues),
+        "cues": cues,
+    }
+
+
 def _normalize_record_frame(
     ci: Dict[str, Any],
     index: int,
@@ -5452,19 +5536,34 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
     # Read-back verification: AutoSyncAudio's boolean return is unreliable, so
     # capture each clip's "Synced Audio" linkage before and after and report the
     # delta. Trust `linked`/`newly_linked`, not `success`.
-    before = [_synced_audio(c) for c in clips]
-    ok = bool(mp.AutoSyncAudio(clips, settings))
-    linked, newly_linked, already_linked = [], [], []
-    for c, was in zip(clips, before):
-        name = _clip_name(c)
-        if _synced_audio(c):
-            linked.append(name)
-            (already_linked if was else newly_linked).append(name)
+    def _categorize(before, observed):
+        linked, newly, already = [], [], []
+        for c, was, now in zip(clips, before, observed):
+            if now:
+                name = _clip_name(c)
+                linked.append(name)
+                (already if was else newly).append(name)
+        return {
+            "linked": linked,
+            "newly_linked": newly,
+            "already_linked": already,
+            "verified": bool(linked),
+        }
+
+    res = verify_by_readback(
+        mutate=lambda: mp.AutoSyncAudio(clips, settings),
+        observe=lambda: [_synced_audio(c) for c in clips],
+        snapshot=lambda: [_synced_audio(c) for c in clips],
+        compare=_categorize,
+        label="auto_sync_audio",
+        intent={"clip_count": len(clips)},
+    )
     return {
-        "success": ok,
-        "linked": linked,
-        "newly_linked": newly_linked,
-        "already_linked": already_linked,
+        "success": res["success_raw"],
+        "verified": res["verified"],
+        "linked": res["linked"],
+        "newly_linked": res["newly_linked"],
+        "already_linked": res["already_linked"],
         "count": len(clips),
         "missing": missing,
         "settings": settings,
@@ -12484,6 +12583,8 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
       refresh_luts() -> {success}
       get_gallery() -> {available}
       export_frame_as_still(path) -> {success}
+      project_summary(include_clips?, clip_limit?) -> {project, current_page, timeline_count, current_timeline, media_pool}
+        Live structural readout — what's in this project right now (no analysis needed).
       load_burnin_preset(name) -> {success}
       insert_audio(media_path, start_offset?, duration?) -> {success}
       get_color_groups() -> {groups}
@@ -12524,6 +12625,12 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
         if parent and not os.path.isdir(parent):
             return _err(f"export_frame_as_still target directory does not exist: {parent}")
         return {"success": bool(proj.ExportCurrentFrameAsStill(still_path))}
+    elif action == "project_summary":
+        return _project_summary(
+            proj,
+            include_clips=bool(p.get("include_clips")),
+            clip_limit=int(p.get("clip_limit", 50)),
+        )
     elif action == "load_burnin_preset":
         return {"success": bool(proj.LoadBurnInPreset(p["name"]))}
     elif action == "insert_audio":
@@ -12584,7 +12691,7 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
             return {"success": False}
         return {"success": True, "new": new_item.GetName(), "new_id": new_item.GetUniqueId(),
                 "output_path": _rec.output_path, "output_bytes": _rec.output_bytes}
-    return _unknown(action, ["get_name","set_name","get_setting","set_setting","get_unique_id","get_presets","set_preset","refresh_luts","get_gallery","export_frame_as_still","load_burnin_preset","insert_audio","get_color_groups","add_color_group","delete_color_group","apply_fairlight_preset","generate_speech"])
+    return _unknown(action, ["get_name","set_name","get_setting","set_setting","get_unique_id","get_presets","set_preset","refresh_luts","get_gallery","export_frame_as_still","project_summary","load_burnin_preset","insert_audio","get_color_groups","add_color_group","delete_color_group","apply_fairlight_preset","generate_speech"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -15078,6 +15185,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       get_unique_id() -> {id}
       get_node_graph() -> {available}
       get_media_pool_item() -> {name, id}
+      get_transcript(with_timecodes?) -> {text, cue_count, has_subtitles, cues}
+        Read the timeline's subtitle track(s) as transcript text.
       get_mark_in_out() -> {mark}
       set_mark_in_out(mark_in, mark_out, type?) -> {success}
       clear_mark_in_out(type?) -> {success}
@@ -15363,6 +15472,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "get_media_pool_item":
         mpi = tl.GetMediaPoolItem()
         return {"name": mpi.GetName(), "id": mpi.GetUniqueId()} if mpi else {"name": None, "id": None}
+    elif action == "get_transcript":
+        return _timeline_transcript(tl, with_timecodes=bool(p.get("with_timecodes")))
     elif action == "get_mark_in_out":
         return _ser(tl.GetMarkInOut())
     elif action == "set_mark_in_out":
@@ -15566,7 +15677,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         if mp_err:
             return mp_err
         return _fairlight_boundary_report(proj, mp, tl, p)
-    return _unknown(action, ["list","get_current","set_current","get_name","set_name","get_start_frame","get_end_frame","get_start_timecode","set_start_timecode","get_track_count","add_track","delete_track","get_track_sub_type","set_track_enable","get_track_enabled","set_track_lock","get_track_locked","get_track_name","set_track_name","get_items","delete_clips","set_clips_linked","duplicate","duplicate_clips","copy_clips","move_clips","copy_range","duplicate_range","overwrite_range","lift_range","story_spine_report","create_variant_from_ranges","bulk_set_item_properties","apply_look_to_items","thumbnail_contact_sheet","marker_thumbnail_review","edit_kernel_capabilities","probe_edit_kernel_item","title_property_scan","set_title_text","bulk_set_title_text","create_compound_clip","create_fusion_clip","import_into_timeline","export","get_setting","set_setting","insert_generator","insert_fusion_generator","insert_fusion_composition","insert_ofx_generator","insert_title","insert_fusion_title","get_unique_id","get_node_graph","get_media_pool_item","get_mark_in_out","set_mark_in_out","clear_mark_in_out","convert_to_stereo","get_items_in_track","get_voice_isolation_state","set_voice_isolation_state","extract_source_frame_ranges","audio_mix_capability_report",*_TIMELINE_CONFORM_KERNEL_ACTIONS,*_TIMELINE_AUDIO_KERNEL_ACTIONS])
+    return _unknown(action, ["list","get_current","set_current","get_name","set_name","get_start_frame","get_end_frame","get_start_timecode","set_start_timecode","get_track_count","add_track","delete_track","get_track_sub_type","set_track_enable","get_track_enabled","set_track_lock","get_track_locked","get_track_name","set_track_name","get_items","delete_clips","set_clips_linked","duplicate","duplicate_clips","copy_clips","move_clips","copy_range","duplicate_range","overwrite_range","lift_range","story_spine_report","create_variant_from_ranges","bulk_set_item_properties","apply_look_to_items","thumbnail_contact_sheet","marker_thumbnail_review","edit_kernel_capabilities","probe_edit_kernel_item","title_property_scan","set_title_text","bulk_set_title_text","create_compound_clip","create_fusion_clip","import_into_timeline","export","get_setting","set_setting","insert_generator","insert_fusion_generator","insert_fusion_composition","insert_ofx_generator","insert_title","insert_fusion_title","get_unique_id","get_node_graph","get_media_pool_item","get_transcript","get_mark_in_out","set_mark_in_out","clear_mark_in_out","convert_to_stereo","get_items_in_track","get_voice_isolation_state","set_voice_isolation_state","extract_source_frame_ranges","audio_mix_capability_report",*_TIMELINE_CONFORM_KERNEL_ACTIONS,*_TIMELINE_AUDIO_KERNEL_ACTIONS])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/readback.py

@@ -0,0 +1,70 @@
+"""Readback verification for unreliable Resolve API mutations.
+
+The Resolve scripting API frequently returns a success value that does not
+reflect what actually happened: ``AutoSyncAudio`` returns a boolean unrelated to
+whether clips linked, ``AppendToTimeline`` may not hand back the new item id,
+many setters return ``True`` regardless of effect, and Fusion ``Paste()`` can
+report nothing while creating nothing. The defense is to **verify by reading the
+real post-state back** instead of trusting the return value.
+
+``verify_by_readback`` is the small primitive every mutating op can use. A
+mutation that reports success while the readback disagrees is a *contradiction*
+— the single most valuable reliability signal — and is logged.
+"""
+import logging
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger("davinci-resolve-mcp")
+
+
+def verify_by_readback(
+    mutate: Callable[[], Any],
+    observe: Callable[[], Any],
+    *,
+    snapshot: Optional[Callable[[], Any]] = None,
+    compare: Optional[Callable[[Any, Any], Dict[str, Any]]] = None,
+    intent: Optional[Dict[str, Any]] = None,
+    label: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Run a mutation and verify it by reading actual state back.
+
+    Args:
+        mutate:   performs the Resolve call; its return value is the unreliable
+                  ``success_raw``.
+        observe:  reads the relevant state AFTER the mutation.
+        snapshot: optional — captures pre-state for delta comparisons (passed to
+                  ``compare`` as ``before``).
+        compare:  ``(before, observed) -> dict`` merged into the result. It should
+                  set ``verified: bool``. Defaults to ``verified = truthy(observed)``.
+        intent:   optional description of what we meant to do (for the ledger).
+        label:    optional op name, used in the contradiction log line.
+
+    Returns a dict with at least ``success_raw`` and ``verified``, plus whatever
+    ``compare`` contributed and (if given) ``intent``.
+    """
+    before = snapshot() if snapshot is not None else None
+    raw = mutate()
+    observed = observe()
+
+    result: Dict[str, Any] = {"success_raw": bool(raw), "observed": observed}
+    if compare is not None:
+        result.update(compare(before, observed))
+    else:
+        result["verified"] = bool(observed)
+    if intent is not None:
+        result["intent"] = intent
+
+    # A contradiction — reported success but the readback disagrees — is the
+    # signal worth surfacing loudly.
+    if result.get("success_raw") and not result.get("verified"):
+        logger.warning(
+            "readback contradiction%s: API reported success but post-state "
+            "verification failed%s",
+            f" [{label}]" if label else "",
+            f" (intent={intent})" if intent else "",
+        )
+        result["contradiction"] = True
+    else:
+        result["contradiction"] = False
+
+    return result