davinci-resolve-mcp 2.33.4 → 2.33.6

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.6
+
+Internal consolidation: a declarative parameter-contract validator and centralized
+subprocess hygiene.
+
+- **Added** `src/utils/contracts.py` `validate(params, rules, invariants)` — one
+  validator for required/type/enum/min/max/non-empty/parent-dir-exists plus custom
+  invariants, returning consistent agent-friendly errors with coercion + defaults
+  applied. Replaces scattered, hand-written validation.
+- **Changed** `export_frame_as_still` and `set_mark_in_out` (clip + timeline) now
+  validate through contracts. Behavior is preserved (same rejections); `mark_in`/
+  `mark_out` are now coerced to int.
+- **Added** `src/utils/proc.py` `safe_run`/`safe_popen` — subprocess wrappers that
+  default `stdin` to DEVNULL so a child can't consume the MCP stdio protocol
+  stream. Inline Python execution now routes through `safe_run`.
+
+## 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.6-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.6"
 # 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.6",
   "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.6"
 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.6"
 
 import base64
 import os
@@ -43,6 +43,9 @@ 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.contracts import validate as _validate_params
+from src.utils.proc import safe_run
 from src.utils.readback import verify_by_readback
 from src.utils.update_check import (
     check_for_updates,
@@ -10575,6 +10578,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 +10600,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 +10692,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 ────────────────
@@ -12618,13 +12628,12 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
         g = proj.GetGallery()
         return {"available": g is not None}
     elif action == "export_frame_as_still":
-        still_path = p.get("path")
-        if not still_path:
-            return _err("export_frame_as_still requires a non-empty 'path'")
-        parent = os.path.dirname(os.path.expanduser(still_path))
-        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))}
+        err, clean = _validate_params(p, {
+            "path": {"type": str, "required": True, "non_empty": True, "parent_dir_exists": True},
+        })
+        if err:
+            return _err(err)
+        return {"success": bool(proj.ExportCurrentFrameAsStill(clean["path"]))}
     elif action == "project_summary":
         return _project_summary(
             proj,
@@ -14071,9 +14080,15 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_mark_in_out":
         return _ser(clip.GetMarkInOut())
     elif action == "set_mark_in_out":
-        if p["mark_in"] > p["mark_out"]:
-            return _err(f"mark_in ({p['mark_in']}) must be <= mark_out ({p['mark_out']})")
-        return {"success": bool(clip.SetMarkInOut(p["mark_in"], p["mark_out"], p.get("type", "all")))}
+        err, clean = _validate_params(
+            p,
+            {"mark_in": {"type": int, "required": True}, "mark_out": {"type": int, "required": True}},
+            invariants=[lambda c: f"mark_in ({c['mark_in']}) must be <= mark_out ({c['mark_out']})"
+                        if c["mark_in"] > c["mark_out"] else None],
+        )
+        if err:
+            return _err(err)
+        return {"success": bool(clip.SetMarkInOut(clean["mark_in"], clean["mark_out"], p.get("type", "all")))}
     elif action == "clear_mark_in_out":
         return {"success": bool(clip.ClearMarkInOut(p.get("type", "all")))}
     return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer"])
@@ -15477,9 +15492,15 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "get_mark_in_out":
         return _ser(tl.GetMarkInOut())
     elif action == "set_mark_in_out":
-        if p["mark_in"] > p["mark_out"]:
-            return _err(f"mark_in ({p['mark_in']}) must be <= mark_out ({p['mark_out']})")
-        return {"success": bool(tl.SetMarkInOut(p["mark_in"], p["mark_out"], p.get("type", "all")))}
+        err, clean = _validate_params(
+            p,
+            {"mark_in": {"type": int, "required": True}, "mark_out": {"type": int, "required": True}},
+            invariants=[lambda c: f"mark_in ({c['mark_in']}) must be <= mark_out ({c['mark_out']})"
+                        if c["mark_in"] > c["mark_out"] else None],
+        )
+        if err:
+            return _err(err)
+        return {"success": bool(tl.SetMarkInOut(clean["mark_in"], clean["mark_out"], p.get("type", "all")))}
     elif action == "clear_mark_in_out":
         return {"success": bool(tl.ClearMarkInOut(p.get("type", "all")))}
     elif action == "convert_to_stereo":
@@ -19749,9 +19770,8 @@ def _execute_python_script(path: str, args: List[str],
     get_resolve()
     cmd = [sys.executable, path] + [str(a) for a in args]
     try:
-        result = subprocess.run(cmd, env=_python_env_for_resolve(),
-                                 capture_output=True, text=True,
-                                 timeout=timeout, stdin=subprocess.DEVNULL)
+        result = safe_run(cmd, env=_python_env_for_resolve(),
+                          capture_output=True, text=True, timeout=timeout)
     except subprocess.TimeoutExpired as e:
         return _err(f"Script timed out after {timeout}s. "
                     f"Partial stdout: {(e.stdout or '')[:1000]}")

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/contracts.py

@@ -0,0 +1,102 @@
+"""Declarative parameter validation for compound-tool actions.
+
+Input validation in the server has historically been scattered: hand-built
+"Must be one of" strings, ad-hoc empty/range/path checks inline in each action.
+This module centralizes it into one declarative validator that emits consistent,
+agent-friendly error messages, so the validation bug class is closed once rather
+than patched action by action.
+
+Usage:
+
+    err, clean = validate(params, {
+        "path": {"type": str, "required": True, "non_empty": True, "parent_dir_exists": True},
+        "mark_in": {"type": int, "required": True},
+        "mark_out": {"type": int, "required": True},
+        "kind": {"enum": ["all", "video", "audio"], "default": "all"},
+    }, invariants=[
+        lambda c: "mark_in must be <= mark_out" if c["mark_in"] > c["mark_out"] else None,
+    ])
+    if err:
+        return _err(err)
+    # use clean[...] — coerced + defaulted
+
+Rule keys: ``type`` (int/str/float/bool), ``required``, ``default``, ``enum``,
+``min``, ``max``, ``non_empty`` (str), ``parent_dir_exists`` (str path).
+"""
+import os
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+
+def _coerce(name: str, value: Any, t: type) -> Tuple[Any, Optional[str]]:
+    if t is bool:
+        if isinstance(value, bool):
+            return value, None
+        if isinstance(value, str):
+            return value.strip().lower() in ("1", "true", "yes", "on"), None
+        return bool(value), None
+    if t is int:
+        try:
+            return int(value), None
+        except (TypeError, ValueError):
+            return None, f"'{name}' must be an integer"
+    if t is float:
+        try:
+            return float(value), None
+        except (TypeError, ValueError):
+            return None, f"'{name}' must be a number"
+    if t is str:
+        if not isinstance(value, str):
+            return None, f"'{name}' must be a string"
+        return value, None
+    return value, None
+
+
+def validate(
+    params: Dict[str, Any],
+    rules: Dict[str, Dict[str, Any]],
+    invariants: Optional[List[Callable[[Dict[str, Any]], Optional[str]]]] = None,
+) -> Tuple[Optional[str], Optional[Dict[str, Any]]]:
+    """Validate ``params`` against ``rules``.
+
+    Returns ``(None, cleaned)`` on success (cleaned has coercions + defaults
+    applied), or ``(error_message, None)`` on the first violation.
+    """
+    cleaned = dict(params)
+
+    for name, rule in rules.items():
+        present = name in params and params[name] is not None
+        if not present:
+            if rule.get("required"):
+                return f"'{name}' is required", None
+            if "default" in rule:
+                cleaned[name] = rule["default"]
+            continue
+
+        val = params[name]
+        t = rule.get("type")
+        if t is not None:
+            val, err = _coerce(name, val, t)
+            if err:
+                return err, None
+
+        if "enum" in rule and val not in rule["enum"]:
+            return f"'{name}' must be one of: {', '.join(map(str, rule['enum']))}", None
+        if rule.get("non_empty") and isinstance(val, str) and not val.strip():
+            return f"'{name}' must be non-empty", None
+        if "min" in rule and val < rule["min"]:
+            return f"'{name}' must be >= {rule['min']}", None
+        if "max" in rule and val > rule["max"]:
+            return f"'{name}' must be <= {rule['max']}", None
+        if rule.get("parent_dir_exists"):
+            parent = os.path.dirname(os.path.expanduser(str(val)))
+            if parent and not os.path.isdir(parent):
+                return f"'{name}' target directory does not exist: {parent}", None
+
+        cleaned[name] = val
+
+    for inv in (invariants or []):
+        msg = inv(cleaned)
+        if msg:
+            return msg, None
+
+    return None, cleaned

package/src/utils/proc.py

@@ -0,0 +1,26 @@
+"""Subprocess helpers that are safe to call while the MCP stdio server is live.
+
+The server owns the JSON-RPC stdin/stdout while serving over stdio. A child
+process that inherits stdin can race-read bytes off the protocol stream and
+corrupt it; ``capture_output`` only redirects stdout/stderr. These wrappers
+default ``stdin`` to ``DEVNULL`` so subprocess hygiene is centralized rather
+than re-applied at every call site.
+"""
+import subprocess
+from typing import Any
+
+
+def safe_run(*args: Any, **kwargs: Any) -> "subprocess.CompletedProcess":
+    """subprocess.run with stdin defaulted to DEVNULL (override by passing stdin).
+
+    If ``input`` is given, stdin is left alone — subprocess forbids passing both.
+    """
+    if "input" not in kwargs:
+        kwargs.setdefault("stdin", subprocess.DEVNULL)
+    return subprocess.run(*args, **kwargs)
+
+
+def safe_popen(*args: Any, **kwargs: Any) -> "subprocess.Popen":
+    """subprocess.Popen with stdin defaulted to DEVNULL (override by passing stdin)."""
+    kwargs.setdefault("stdin", subprocess.DEVNULL)
+    return subprocess.Popen(*args, **kwargs)