davinci-resolve-mcp 2.33.3 → 2.33.5

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.5
+
+A queryable ledger of verified Resolve API behavior.
+
+- **Added** `resolve_control(action="api_truth", query?)` returns
+  behaviorally-verified facts about quirky or unreliable Resolve scripting-API
+  behavior — methods that live on unexpected objects, return values that lie,
+  silently-rejected string keys, and calls that don't exist. Each fact records
+  the reality, a recommended approach, and the Resolve build it was verified on.
+  No connection required. Backed by `src/utils/api_truth.py`, seeded from
+  hard-won findings (AutoSyncAudio, Fusion Paste, FlowView positions,
+  GetTimelineByName, project render methods, transcription truncation, the
+  CreateProject modal, stdio subprocess hygiene) and meant to grow over time.
+
+## 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.

package/README.md

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

@@ -318,6 +318,8 @@ Key actions:
 - `launch` — connect to or start Resolve; call this first if any tool returns a
   "Not connected" error
 - `get_version` — returns `{product, version, version_string}`
+- `api_truth(query?)` — look up behaviorally-verified facts about quirky/unreliable
+  Resolve API behavior (no connection needed); filter by substring
 - `get_page` / `open_page(page)` — read or switch the active page
 - `get_keyframe_mode` / `set_keyframe_mode(mode)`
 - `get_fairlight_presets` — Resolve 20.2.2+; returns available Fairlight

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.33.3"
+VERSION = "2.33.5"
 # 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.3",
+  "version": "2.33.5",
   "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.3"
+VERSION = "2.33.5"
 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.3"
+VERSION = "2.33.5"
 
 import base64
 import os
@@ -43,6 +43,8 @@ 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.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
+from src.utils.readback import verify_by_readback
 from src.utils.update_check import (
     check_for_updates,
     clear_update_prompt_preferences,
@@ -5535,19 +5537,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,
@@ -10559,6 +10576,8 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       ignore_mcp_update() -> {success, version, update, decision}
       snooze_mcp_update(hours?) -> {success, version, update, decision}
       clear_mcp_update_preferences() -> {success, version, update, decision}
+      api_truth(query?) -> {verified_on, count, facts}  — look up behaviorally-verified
+        facts about quirky/unreliable Resolve API behavior (no connection needed).
       get_page() -> {page}
       open_page(page) -> {success}  — page: edit, cut, color, fusion, fairlight, deliver
       get_keyframe_mode() -> {mode}
@@ -10579,6 +10598,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     """
     p = params or {}
 
+    # api_truth is a static knowledge lookup — no Resolve connection needed.
+    if action == "api_truth":
+        facts = lookup_api_truth(p.get("query"))
+        return {"verified_on": _API_TRUTH_VERIFIED_ON, "count": len(facts), "facts": facts}
+
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
         return _open_control_panel(p)
@@ -10666,7 +10690,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return missing
         r.DisableBackgroundTasksForCurrentResolveSession()
         return _ok()
-    return _unknown(action, ["launch","get_version","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","get_version","api_truth","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────

package/src/utils/api_truth.py

@@ -0,0 +1,132 @@
+"""Behaviorally-verified facts about the DaVinci Resolve scripting API.
+
+The Resolve scripting API is under-documented and frequently behaves differently
+from its apparent signature: methods live on objects you wouldn't expect, return
+values lie, string keys are silently rejected, and some documented-looking calls
+don't exist. This module records facts we have *verified against live Resolve* so
+agents and code can look the reality up instead of rediscovering it the hard way.
+
+Each entry is a small dict. Grow it opportunistically — every readback recipe and
+every fix that uncovers a surprising behavior should add an entry. Facts are
+stamped with the Resolve build they were verified on so drift is visible when a
+new version ships.
+"""
+from typing import Any, Dict, List, Optional
+
+VERIFIED_ON = "DaVinci Resolve Studio 21.0.0"
+
+# Each entry: symbol, object, reality, recommended, tags. `signature` optional.
+API_TRUTH: List[Dict[str, Any]] = [
+    {
+        "symbol": "MediaPool.AutoSyncAudio",
+        "object": "MediaPool",
+        "signature": "(clips, settings) -> bool",
+        "reality": "The boolean return does not reflect whether clips actually "
+                   "linked, and string enum keys in `settings` are silently "
+                   "rejected (the call returns False).",
+        "recommended": "Resolve the AUDIO_SYNC_* enum constants via the live "
+                       "resolve handle, and verify by reading each clip's "
+                       "'Synced Audio' property (see verify_by_readback).",
+        "tags": ["unreliable-return", "silent-failure", "audio", "enum"],
+    },
+    {
+        "symbol": "Composition.Paste",
+        "object": "Fusion Composition",
+        "reality": "Passing tool.SaveSettings()'s in-memory table to Paste() / "
+                   "LoadSettings() fails across the Python bridge with an "
+                   "OrderedDict/null-argument error and creates no node, while "
+                   "reporting nothing useful.",
+        "recommended": "Duplicate via AddTool(RegID) + SaveSettings(path)/"
+                       "LoadSettings(path) through a temp .setting FILE, which "
+                       "round-trips reliably. Identify the new node by name diff.",
+        "tags": ["fusion", "bridge", "silent-failure"],
+    },
+    {
+        "symbol": "FlowView.SetPos / FlowView.GetPosTable",
+        "object": "Fusion FlowView (comp.CurrentFrame.FlowView)",
+        "reality": "Node positions are read/written through the FlowView, not the "
+                   "tool. SetPos returns nothing reliable; GetPosTable returns a "
+                   "1-indexed table (or dict/tuple depending on bridge).",
+        "recommended": "Use comp.CurrentFrame.FlowView.SetPos(tool, x, y); confirm "
+                       "with GetPosTable and a liberal position parser.",
+        "tags": ["fusion", "unreliable-return"],
+    },
+    {
+        "symbol": "Timeline.GetTimelineByName",
+        "object": "Project",
+        "reality": "Does not exist. Timelines are looked up by index.",
+        "recommended": "Iterate GetTimelineByIndex(1..GetTimelineCount()).",
+        "tags": ["missing-method", "timeline"],
+    },
+    {
+        "symbol": "Project render methods (AddRenderJob, SetRenderSettings, ...)",
+        "object": "Project",
+        "reality": "Render methods live on the Project object, not on a separate "
+                   "render-settings interface.",
+        "recommended": "Call proj.AddRenderJob(), proj.SetRenderSettings(), "
+                       "proj.LoadRenderPreset() directly on the project.",
+        "tags": ["render"],
+    },
+    {
+        "symbol": "MediaPoolItem.GetClipProperty('Transcription')",
+        "object": "MediaPoolItem",
+        "reality": "Returns a PREVIEW of the transcription that ends in an "
+                   "ellipsis when the full transcript is longer than the property "
+                   "exposes.",
+        "recommended": "Treat a trailing ellipsis as truncation (see "
+                       "media_pool_item get_transcription's `truncated` flag).",
+        "tags": ["transcription", "truncation"],
+    },
+    {
+        "symbol": "ProjectManager.CreateProject (with a dirty Untitled project)",
+        "object": "ProjectManager",
+        "reality": "Returns None and pops a modal 'Save Current Project' dialog "
+                   "when the current unsaved/Untitled project blocks the switch. "
+                   "SaveProject() on an Untitled project re-triggers the same modal.",
+        "recommended": "CloseProject(current) to discard the untitled project "
+                       "without a prompt, then CreateProject; restore with "
+                       "LoadProject afterward.",
+        "tags": ["project", "modal", "silent-failure"],
+    },
+    {
+        "symbol": "Timeline.InsertFusionCompositionIntoTimeline",
+        "object": "Timeline",
+        "reality": "Reliable way to obtain a Fusion comp on an otherwise empty "
+                   "timeline: it inserts a Fusion composition clip whose comp is "
+                   "then reachable via GetFusionCompByIndex(1).",
+        "recommended": "Use it (rather than InsertGeneratorIntoTimeline) when you "
+                       "need a comp to operate on.",
+        "tags": ["fusion", "timeline"],
+    },
+    {
+        "symbol": "subprocess inheriting stdin under the MCP stdio server",
+        "object": "(server runtime)",
+        "reality": "A child process that inherits stdin can race-read bytes off "
+                   "the JSON-RPC protocol stream and corrupt it; capture_output "
+                   "redirects only stdout/stderr.",
+        "recommended": "Pass stdin=subprocess.DEVNULL on every subprocess that can "
+                       "run while serving over stdio.",
+        "tags": ["runtime", "stdio", "subprocess"],
+    },
+]
+
+
+def lookup_api_truth(query: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Return verified facts matching `query`, or all facts if no query.
+
+    Matches a case-insensitive substring against the symbol, tags, and reality.
+    """
+    if not query:
+        return list(API_TRUTH)
+    q = query.lower()
+    out = []
+    for e in API_TRUTH:
+        hay = " ".join([
+            e.get("symbol", ""),
+            e.get("object", ""),
+            e.get("reality", ""),
+            " ".join(e.get("tags", [])),
+        ]).lower()
+        if q in hay:
+            out.append(e)
+    return out

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