davinci-resolve-mcp 2.33.4 → 2.33.5

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.33.4-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.4"
+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.4",
+  "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.4"
+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.4"
+VERSION = "2.33.5"
 
 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.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,
@@ -10575,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}
@@ -10595,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)
@@ -10682,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