davinci-resolve-mcp 2.68.0 → 2.68.2

package/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 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.68.2
+
+Bug fixes. The server no longer opens a second DaVinci Resolve, and a failed
+connection now tells the caller what is actually wrong.
+
+### Fixed
+
+- **The server launched Resolve when one was already running — usually the wrong
+  one.** The free edition refuses external scripting by design, so on a machine
+  where only it is running `scriptapp("Resolve")` always returns None.
+  `get_resolve()` read that as *"Resolve is not running"* and ran `open` on the
+  application; with both editions installed that started **Studio**, a second and
+  different application, on every tool call.
+
+  `resolve_is_running()` now answers the question that was being assumed. It
+  returns None when it cannot tell, deliberately — "cannot tell" must never decay
+  into "nothing is running", because that is the answer that leads to launching
+  something. A genuinely absent Resolve is still launched, as documented, and the
+  macOS candidate list now contains **both** editions rather than only the
+  installer path.
+- **The error a caller received described something that had not happened.**
+  Eleven sites asserted that Resolve was not running, that starting it had been
+  tried and failed, and that the reader should check their Studio install. After
+  the fix above none of that was true, and the accurate guidance was only reaching
+  the log. `_not_connected_error()` derives the message from the situation and
+  names the applicable remedy — external scripting on Studio, or the in-app bridge
+  on the free edition, including the framework-Python prerequisite. Three codes:
+  `SCRIPTING_UNAVAILABLE`, `BRIDGE_UNAVAILABLE`, `RESOLVE_NOT_RUNNING`.
+- **Those two are marked `retryable: false`.** The `not_connected` category
+  defaults to retryable because auto-launch may succeed next time; neither of
+  these can — one needs a preference changed, the other a script started inside
+  Resolve — and reporting them as retryable sends an agent into a loop it cannot
+  win.
+- **The offline test suite opened Resolve, and connected to whatever was running.**
+  A stub-based audio test reached for `AUDIO_SYNC_*`, which are attributes on the
+  *live* object, so it called `get_resolve()`, found nothing, and started Resolve;
+  when Resolve *was* open it connected instead, making the test's result depend on
+  the state of the machine. `tests/conftest.py` closes both suite-wide and names
+  any launch attempt in the terminal summary.
+- **`src/server.py` reported the wrong tool count to every agent.** Its module
+  docstring said "34 compound tools" while the agent-facing workflow prompt and
+  the startup log line said 32. The drift guard only required the correct number
+  to appear *somewhere* in the file, so the wrong one shipped. It now rejects any
+  other count in front of that phrase, and counts decorators from the parsed
+  syntax tree rather than by matching text — a docstring mentioning
+  `@mcp.tool()` had been counted as a 35th tool.
+- **The bridge harness graded the wrong clip and reported a known trap as a
+  finding.** It took the first video item, which is often a generator or title
+  that has no MediaPoolItem and answers None to every node query, so the grading
+  surface read as unreachable; it now takes the first gradeable item. And it
+  passed the codec *description* `"H.264"` to `SetCurrentRenderFormatAndCodec`,
+  which only accepts the id `"H264"`, making that observation permanently false
+  for a documented reason.
+
+### Changed
+
+- `scripts/install_resolve_bridge.py` no longer claims Resolve ignores Fusion's
+  standalone script tree. Measured on free 21.0.3.7: markers left in two
+  undocumented container paths both appeared under Workspace ▸ Scripts, so Lite
+  scans more locations than the README documents. Install behaviour is unchanged —
+  the documented paths work, and each extra target is another chance for the macOS
+  App Management prompt to stall the copy — but the stated reason is now the true
+  one.
+
+### Validated
+
+Free edition alone (21.0.3.7, App Store), Studio never launched at any point,
+confirmed by process check after every stage: 165/165 read-shaped MCP actions
+clean with Blackmagic's module blocked; 109/112 API read methods exercised; render
+to a non-empty file with `set_format` true; AAF/DRT/EDL/FCPXML all written;
+SetLUT clears and reads back. Suite 1913 passing.
+
+## What's New in v2.68.1
+
+Bug fix. A missing tool argument now returns the structured error envelope the
+rest of the surface uses, instead of escaping as a raw `KeyError`.
+
+### Fixed
+
+- **A missing argument reached the client as an unroutable crash.** Actions read
+  `p["track_type"]` directly; when the key was absent the resulting `KeyError`
+  escaped the action, escaped the tool, and arrived as
+  `ToolError: Error executing tool timeline: 'track_type'` — no code, no
+  category, no remediation. Walking the whole surface found **99 of 512 declared
+  actions** failing this way across 16 tools (`timeline`, `graph`, `render`,
+  `media_pool`, `media_storage`, `fusion_comp`, `folder`, `gallery_stills`,
+  `layout_presets`, `project_settings`, `project_manager_*`, `render_presets`,
+  `resolve_control`, `timeline_markers`). They now return, for example:
+
+      {"error": {"message": "'track_type' is required",
+                 "code": "MISSING_TRACK_TYPE", "category": "invalid_input",
+                 "retryable": false, "remediation": "...", "state": {...}}}
+
+  `retryable: false` matters as much as the code: an input error the caller must
+  fix was previously reported through a path that defaulted to retryable, which
+  sends an agent into a loop it cannot win.
+
+  The mechanism is a params dict whose missing keys raise a dedicated
+  `KeyError` subclass, caught at the tool boundary. Catching plain `KeyError`
+  there would have been simpler and wrong — it cannot tell a missing argument
+  from an internal lookup failure on some other dict, so our own bugs would have
+  been relabelled as the caller's mistake. `contracts.validate` remains the
+  preferred tool where a type, range or enum also needs checking, and the actions
+  already using it are unchanged.
+
+### Added
+
+- `tests/test_tool_argument_validation.py` walks **every declared action** with an
+  empty params dict and asserts none leaks a `KeyError`. Reading the source cannot
+  find this class — `p[...]` after a guard is correct and `p[...]` without one is a
+  bug — so the walk executes each branch against a stub Resolve. It fails on the
+  pre-fix tree and runs in 2 s.
+
+### Changed
+
+- `test_doc_tool_counts` counts `@mcp.tool()` decorators from the parsed syntax
+  tree rather than by matching the text. A docstring explaining where the
+  decorator has to sit was counted as a 35th tool; prose that mentions a
+  decorator is not a tool.
+
 ## What's New in v2.68.0
 
 Six engines that let an agent judge its own output before shipping it — audio

package/README.md

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

package/install.py

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

package/scripts/bridge_differential.py

@@ -75,11 +75,21 @@ def scenario_render(resolve: Any, workspace: Path) -> Dict[str, Any]:
     observations: Dict[str, Any] = {}
     formats = project.GetRenderFormats() or {}
     observations["format_count"] = len(formats)
-    observations["codec_count_for_mov"] = len(project.GetRenderCodecs("mov") or {})
+    codecs = project.GetRenderCodecs("mov") or {}
+    observations["codec_count_for_mov"] = len(codecs)
 
     output = workspace / "bridge_render_probe"
     output.mkdir(parents=True, exist_ok=True)
-    observations["set_format"] = project.SetCurrentRenderFormatAndCodec("mov", "H.264")
+    # `GetRenderCodecs` returns {description: id} and only the **id** is accepted.
+    # Passing the description shown in the Deliver page returns False — verified
+    # again here on free 21.0.3.7: 'H.264' -> False, 'H264' -> True. Feeding it the
+    # description made this observation permanently False for a documented reason,
+    # which is a harness reporting a known trap as if it were a finding.
+    codec_id = codecs.get("H.264") or next(iter(codecs.values()), None)
+    observations["codec_id"] = codec_id
+    observations["set_format"] = (
+        project.SetCurrentRenderFormatAndCodec("mov", codec_id) if codec_id else False
+    )
     observations["set_settings"] = project.SetRenderSettings({
         "TargetDir": str(output),
         "CustomName": "bridge_render_probe",
@@ -147,8 +157,16 @@ def scenario_set_lut(resolve: Any, _workspace: Path) -> Dict[str, Any]:
     items = timeline.GetItemListInTrack("video", 1) or []
     if not items:
         return {"skipped": "no clip on video track 1"}
-    item = items[0]
-    observations: Dict[str, Any] = {"node_count": item.GetNumNodes()}
+    # Not items[0]: a generator or title has no MediaPoolItem and answers None to
+    # every node question, so grading it silently produces a row of nulls that
+    # reads like a bridge failure. Measured on a real timeline — SMPTE Color Bar
+    # returns None for GetNumNodes and GetNodeGraph, the clip beside it returns 1
+    # and a live graph.
+    item = next((i for i in items if i.GetMediaPoolItem()), None)
+    if item is None:
+        return {"skipped": "video track 1 holds only generators/titles, which cannot be graded",
+                "items_seen": len(items)}
+    observations: Dict[str, Any] = {"clip": item.GetName(), "node_count": item.GetNumNodes()}
     original = item.GetLUT(1)
     observations["lut_before"] = original
     # An empty path is the documented way to clear a node's LUT, so it is a

package/scripts/install_resolve_bridge.py

@@ -37,9 +37,9 @@ _SCRIPTS_SUFFIX = "Library/Application Support/Blackmagic Design/DaVinci Resolve
 #: Two traps, both hit on a real install:
 #:
 #: 1. `<container>/Data/Library/Application Support/Fusion/Scripts/Utility`
-#:    exists and is pre-scaffolded with Color/Comp/Deliver/Edit/Tool/Utility —
-#:    but that is **Fusion's standalone tree**, not Resolve's, and Resolve does
-#:    not scan it. Keying on "which directory already exists" picks the decoy.
+#:    exists and is pre-scaffolded with Color/Comp/Deliver/Edit/Tool/Utility, but
+#:    it is **Fusion's standalone tree**, not Resolve's. Keying on "which
+#:    directory already exists" picks it over the one the README documents.
 #: 2. Resolve does not create its own `Fusion/Scripts` tree until a script is
 #:    installed, so requiring the target to pre-exist skips the free edition
 #:    entirely — the one build the bridge exists for.
@@ -47,6 +47,16 @@ _SCRIPTS_SUFFIX = "Library/Application Support/Blackmagic Design/DaVinci Resolve
 #: So: a container that exists means the edition is installed, and the tree is
 #: *created*. Blackmagic's README is the authority on the suffix, not the
 #: filesystem.
+#:
+#: **Correction, measured on free 21.0.3.7:** an earlier version of trap 1 said
+#: Resolve "does not scan" the Fusion standalone tree. It does — a marker left in
+#: `<container>/Data/Library/Application Support/Fusion/Scripts/Utility` appeared
+#: under Workspace ▸ Scripts, as did one in
+#: `<container>/Data/Documents/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility`.
+#: So Lite scans more locations than the README documents. That changes nothing
+#: about *where to install* — the documented paths work, and each extra target is
+#: another chance for the App Management prompt to stall the copy — but the reason
+#: to prefer them is that they are documented, not that the others are dead.
 _SANDBOX_MARKER = "com.blackmagic-design."
 #: Containers that are not Resolve (RAW Player, Speed Test, the IO XPC helper).
 _NON_RESOLVE_CONTAINERS = ("BlackmagicRaw", "IOXPC")

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.68.0"
+VERSION = "2.68.2"
 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,11 +11,13 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.68.0"
+VERSION = "2.68.2"
 
 import base64
 import os
 import sys
+import functools
+import inspect
 import json
 import logging
 import math
@@ -294,7 +296,7 @@ def davinci_resolve_workflow() -> str:
     return """Use this DaVinci Resolve MCP server as a guarded post-production control surface.
 
 Core pattern:
-- Prefer the 32 compound tools and their action names over raw scripting.
+- Prefer the 34 compound tools and their action names over raw scripting.
 - Start by probing state: resolve_control.get_version/get_page, project_manager.get_current, timeline.get_current, and media_pool.probe_media_pool.
 - Before mutating timelines, media pools, render settings, grades, projects, databases, or extensions, prefer the matching probe, capabilities, boundary_report, safe_*, or dry_run action when one exists.
 - Preserve source media integrity. Never transcode, proxy, rewrite, move, rename, or create derivatives of source media unless the user explicitly asks. Analysis output belongs in sidecars or analysis directories.
@@ -897,6 +899,37 @@ def _launch_resolve():
     logger.warning("Resolve did not respond within 60s after launch")
     return False
 
+#: Process names that mean a DaVinci Resolve application is already running.
+#: Deliberately not the full path: the App Store build lives at
+#: `/Applications/DaVinci Resolve.app` and the installer build inside
+#: `/Applications/DaVinci Resolve/`, and either one counts.
+_RESOLVE_PROCESS_PATTERNS = (
+    "DaVinci Resolve.app/Contents/MacOS/Resolve",   # macOS, both editions
+    "Resolve.exe",                                  # Windows
+    "/opt/resolve/bin/resolve",                     # Linux
+)
+
+
+def resolve_is_running() -> Optional[bool]:
+    """Is a Resolve application already up? None when it cannot be determined.
+
+    Best-effort and dependency-free. `None` rather than `False` on failure, so an
+    unanswerable question never silently becomes "nothing is running" — which is
+    the answer that leads to launching something.
+    """
+    try:
+        if platform.system().lower() == "windows":
+            out = subprocess.run(["tasklist"], capture_output=True, text=True, timeout=10, check=False)
+        else:
+            out = subprocess.run(["ps", "-Ao", "command="], capture_output=True, text=True, timeout=10, check=False)
+        if out.returncode != 0 and not out.stdout:
+            return None
+        listing = out.stdout or ""
+    except Exception:  # pragma: no cover - defensive; an unknown answer is None
+        return None
+    return any(pattern in listing for pattern in _RESOLVE_PROCESS_PATTERNS)
+
+
 def get_resolve():
     """Lazy connection to Resolve — connects on first tool call, auto-launches if needed."""
     global resolve
@@ -907,12 +940,84 @@ def get_resolve():
         # Try to connect to an already-running Resolve.
         if _try_connect():
             return resolve
-        # Not running — launch it automatically.
+        # Failing to connect is NOT the same as nothing running, and conflating
+        # them opened an application nobody asked for. The free edition refuses
+        # external scripting by design, so on a machine where only it is running
+        # `_try_connect` always fails — and this then launched *Studio*, a second,
+        # different application, on every tool call. Reported three times before
+        # it was traced.
+        already_running = resolve_is_running()
+        if already_running:
+            logger.error(
+                "DaVinci Resolve is already running but is not answering the scripting API, "
+                "so it will NOT be launched again. Either enable Preferences > General > "
+                "'External scripting using' = Local (Studio only), or, on the free edition, "
+                "use the in-app bridge: install it, run Workspace > Scripts > resolve_bridge, "
+                "and set DAVINCI_RESOLVE_BRIDGE=1."
+            )
+            return None
+        if already_running is None:
+            logger.warning("Could not determine whether Resolve is running; not launching it.")
+            return None
         logger.info("Resolve not running, attempting to launch automatically...")
         _launch_resolve()
         return resolve
 
 
+def _not_connected_error():
+    """The caller-facing "no Resolve" error, describing what is actually the case.
+
+    Eleven call sites used to assert that Resolve was not running, that starting it
+    had been tried and failed, and that the reader should check their Studio
+    install. Once `get_resolve` stopped launching a second application, all three
+    claims were wrong: nothing was launched, Resolve *is* running, and a
+    free-edition user was being sent to check an install they may not have. The
+    accurate guidance was only reaching the log.
+
+    So the message is derived from the situation instead of asserted, and it names
+    the fix that applies: enable external scripting on Studio, or use the in-app
+    bridge on the free edition.
+    """
+    running = resolve_is_running()
+    bridge_on = _bridge_requested()
+    if bridge_on:
+        return _err(
+            "The in-app bridge is enabled but not answering.",
+            code="BRIDGE_UNAVAILABLE", category="not_connected",
+            # `not_connected` defaults to retryable because auto-launch may
+            # succeed next time. Nothing here will: the listener only appears once
+            # someone runs the script inside Resolve, so an agent retrying on a
+            # loop it cannot win is strictly worse than being told to stop.
+            retryable=False,
+            reason="DAVINCI_RESOLVE_BRIDGE is set, so no other transport is tried.",
+            remediation="In Resolve, run Workspace > Scripts > resolve_bridge. If it is not in "
+                        "that menu, run `python scripts/install_resolve_bridge.py` and restart "
+                        "Resolve; a framework Python from python.org is required for Resolve to "
+                        "list .py scripts at all.",
+            state={"resolve_running": running, "bridge_enabled": True},
+        )
+    if running:
+        return _err(
+            "DaVinci Resolve is running but is not answering the scripting API.",
+            code="SCRIPTING_UNAVAILABLE", category="not_connected",
+            # Not retryable: a preference has to change, or the bridge has to be
+            # started. Retrying the same call cannot make either happen.
+            retryable=False,
+            reason="External scripting is a Studio feature; the free edition refuses it "
+                   "regardless of the preference. Resolve was NOT launched again.",
+            remediation="On Studio: Preferences > General > 'External scripting using' = Local. "
+                        "On the free edition: install the in-app bridge, run "
+                        "Workspace > Scripts > resolve_bridge, and set DAVINCI_RESOLVE_BRIDGE=1.",
+            state={"resolve_running": True, "bridge_enabled": False},
+        )
+    return _err(
+        "DaVinci Resolve is not running and could not be started.",
+        code="RESOLVE_NOT_RUNNING", category="not_connected",
+        remediation="Start DaVinci Resolve and open a project, then retry.",
+        state={"resolve_running": bool(running), "bridge_enabled": False},
+    )
+
+
 def _destructive_versioning_provider() -> Optional[Tuple[Any, Any, str, Optional[str]]]:
     """Provider used by the C6 version-on-mutate hook.
 
@@ -1225,6 +1330,120 @@ _CATEGORY_RETRYABLE_DEFAULT: Dict[str, bool] = {
 _RETRYABLE_UNSET = object()
 
 
+class _MissingParam(KeyError):
+    """A tool action subscripted a parameter the caller did not supply.
+
+    Subclasses `KeyError` so any existing `except KeyError` in the codebase keeps
+    behaving as it did; what it adds is the ability to tell a *missing argument*
+    apart from a KeyError on some other dict — a Resolve settings map, a parsed
+    JSON body — which would otherwise be reported to the caller as "you forgot an
+    argument" when the real fault is ours.
+    """
+
+
+class _Params(dict):
+    """The params dict, wired so a missing key is a diagnosable refusal.
+
+    Actions have historically reached into `p["track_type"]` directly. When the
+    key is absent that raises a bare `KeyError`, which escapes the action, escapes
+    the tool, and reaches the client as
+    `ToolError: Error executing tool timeline: 'track_type'` — no code, no
+    category, no remediation, and nothing an agent can route on. Measured across
+    the whole surface: **99 of 512 declared actions** failed that way.
+
+    Two ways to fix that were available. Rewriting all 99 sites to use
+    `contracts.validate` gives the best individual errors but is 99 chances to get
+    a spec wrong, and leaves the 100th site to be written next month. Catching
+    `KeyError` at the tool boundary closes the class in one place but cannot tell
+    which dict raised, so an unrelated internal KeyError would be mislabelled as
+    the caller's mistake.
+
+    This is the third option: keep the boundary catch, but make the *parameters*
+    raise something only they can raise. False positives become impossible by
+    construction.
+
+    `contracts.validate` remains the better tool wherever a type, a range or an
+    enum also needs checking, and the actions that already use it keep doing so.
+    This is deliberately **not** a migration of the 99 — rewriting them would add
+    99 opportunities to write a spec wrong without improving the defect being
+    fixed here, and it would still leave the next new action unguarded. What is
+    lost by not migrating is bounded: a *wrong* value still reaches Resolve, which
+    answers None or False, so the result is a truthful failure rather than a
+    misleading success.
+    """
+
+    def __missing__(self, key):
+        raise _MissingParam(key)
+
+
+def _params(params: Optional[Dict[str, Any]]) -> "_Params":
+    """Every tool body starts here, so every action gets the diagnosable dict.
+
+    Note `_Params(params or {})` rather than a truthiness dance: an empty
+    `_Params` is falsy like any empty dict, so `p = params or {}` would have
+    quietly handed back a *plain* dict in exactly the no-arguments case this
+    exists to serve.
+    """
+    return _Params(params or {})
+
+
+def _missing_param_error(exc: _MissingParam, action: str) -> Dict[str, Any]:
+    """Turn a missing parameter into the envelope the rest of the surface uses."""
+    name = exc.args[0] if exc.args else "parameter"
+    slug = re.sub(r"[^A-Z0-9]+", "_", str(name).upper()).strip("_") or "PARAMETER"
+    return _err(
+        f"'{name}' is required",
+        code=f"MISSING_{slug}",
+        category="invalid_input",
+        remediation=f"pass {name} in params, e.g. params={{\"{name}\": ...}}",
+        state={"action": action, "missing": str(name)},
+    )
+
+
+def _guarded_action_name(args, kwargs) -> str:
+    """The `action` this call was for, wherever it was passed."""
+    if "action" in kwargs:
+        return str(kwargs["action"])
+    return str(args[0]) if args else "?"
+
+
+def _guard_missing_params(fn):
+    """Tool decorator: report a missing parameter instead of leaking a KeyError.
+
+    Sits *under* `@mcp.tool()` so FastMCP registers the guarded callable.
+    `functools.wraps` keeps the name, docstring and signature FastMCP builds the
+    tool schema from.
+
+    Two things this has to preserve, both learned by breaking them:
+
+    - **Async tools must stay coroutine functions.** `media_analysis` is `async`,
+      and a synchronous wrapper around it returned an un-awaited coroutine that
+      FastMCP could not use — the tool stopped answering entirely, taking its 71
+      actions with it. `inspect.iscoroutinefunction` decides which wrapper to
+      build, and a test now pins that async tools are still async afterwards.
+    - **The signature is not (action, params).** `media_analysis` also takes
+      `ctx: Optional[Context]`, so the wrapper forwards `*args, **kwargs` rather
+      than naming parameters it does not know about.
+    """
+    if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await fn(*args, **kwargs)
+            except _MissingParam as exc:
+                return _missing_param_error(exc, _guarded_action_name(args, kwargs))
+    else:
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            try:
+                return fn(*args, **kwargs)
+            except _MissingParam as exc:
+                return _missing_param_error(exc, _guarded_action_name(args, kwargs))
+
+    wrapper.__wrapped_by_missing_param_guard__ = True
+    return wrapper
+
+
 def _err(message, *, code=None, category=None, retryable=_RETRYABLE_UNSET,
          remediation=None, reason=None, state=None):
     """Return a structured error envelope.
@@ -12687,6 +12906,7 @@ def _setup_clear_defaults(keys: Any, dry_run: bool) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@_guard_missing_params
 def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Configure MCP conversational defaults and setup preferences.
 
@@ -12700,7 +12920,7 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
       media_analysis.*: analysis, metadata, marker, reporting, and workflow defaults
       updates.*: MCP update policy, interval, and snooze defaults
     """
-    p = params or {}
+    p = _params(params)
     if action in {"schema", "capabilities", "options"}:
         return {
             "actions": ["schema", "get_defaults", "set_defaults", "clear_defaults"],
@@ -12840,6 +13060,7 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
 
 
 @mcp.tool()
+@_guard_missing_params
 def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """App-level DaVinci Resolve operations.
 
@@ -12882,7 +13103,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       restore_state(state_token) -> {success, restored: {...}}
         — Returns Resolve to a previously-saved state.
     """
-    p = params or {}
+    p = _params(params)
 
     # api_truth is a static knowledge lookup — no Resolve connection needed.
     if action == "api_truth":
@@ -12947,11 +13168,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         r = get_resolve()  # auto-launches if not running
         if r is not None:
             return _ok(message="DaVinci Resolve is running and connected.")
-        return _err("Could not connect to DaVinci Resolve. Check that Resolve Studio is installed and 'External scripting using' is set to Local in Preferences.")
+        return _not_connected_error()
 
     r = get_resolve()  # auto-launches if not running
     if r is None:
-        return _err("Could not connect to DaVinci Resolve after auto-launch attempt. Check that Resolve Studio is installed.")
+        return _not_connected_error()
 
     if action == "get_version":
         update_env = _setup_update_env()
@@ -13859,6 +14080,7 @@ def _close_control_panel() -> Dict[str, Any]:
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def layout_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage DaVinci Resolve UI layout presets.
 
@@ -13870,10 +14092,10 @@ def layout_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
       import_preset(path, name?) -> {success}
       delete(name) -> {success}
     """
-    p = params or {}
+    p = _params(params)
     r = get_resolve()
     if r is None:
-        return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
+        return _not_connected_error()
 
     if action == "save":
         if not p.get("name"):
@@ -13905,6 +14127,7 @@ def layout_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def render_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Import/export render and burn-in presets.
 
@@ -13914,10 +14137,10 @@ def render_presets(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
       import_burnin(path) -> {success}
       export_burnin(name, path) -> {success}
     """
-    p = params or {}
+    p = _params(params)
     r = get_resolve()
     if r is None:
-        return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
+        return _not_connected_error()
 
     if action == "import_render":
         return {"success": bool(r.ImportRenderPreset(p["path"]))}
@@ -14815,6 +15038,7 @@ def _project_lint_live(r, pm) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@_guard_missing_params
 def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage DaVinci Resolve projects.
 
@@ -14856,10 +15080,10 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         settings are applied in dependency order; markers only added if absent. Hooks run only
         when run_hooks=true (executes shell from the spec — opt-in).
     """
-    p = params or {}
+    p = _params(params)
     r = get_resolve()
     if r is None:
-        return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
+        return _not_connected_error()
     pm = r.GetProjectManager()
 
     if action == "lint":
@@ -14963,6 +15187,7 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def project_manager_folders(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Navigate and manage project folders in the Project Manager.
 
@@ -14975,10 +15200,10 @@ def project_manager_folders(action: str, params: Optional[Dict[str, Any]] = None
       goto_root() -> {success}
       goto_parent() -> {success}
     """
-    p = params or {}
+    p = _params(params)
     r = get_resolve()
     if r is None:
-        return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
+        return _not_connected_error()
     pm = r.GetProjectManager()
 
     if action == "list":
@@ -15007,6 +15232,7 @@ def project_manager_folders(action: str, params: Optional[Dict[str, Any]] = None
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def project_manager_cloud(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Cloud project operations (requires DaVinci Resolve cloud infrastructure).
 
@@ -15016,10 +15242,10 @@ def project_manager_cloud(action: str, params: Optional[Dict[str, Any]] = None)
       import_project(path, settings) -> {success}
       restore(folder_path, settings) -> {success}
     """
-    p = params or {}
+    p = _params(params)
     r = get_resolve()
     if r is None:
-        return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
+        return _not_connected_error()
     pm = r.GetProjectManager()
 
     # cloudSettings is enum-keyed (CLOUD_SETTING_*/CLOUD_SYNC_*); resolve string
@@ -15045,6 +15271,7 @@ def project_manager_cloud(action: str, params: Optional[Dict[str, Any]] = None)
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def project_manager_database(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage DaVinci Resolve project databases.
 
@@ -15053,10 +15280,10 @@ def project_manager_database(action: str, params: Optional[Dict[str, Any]] = Non
       list() -> {databases}
       set_current(db_info) -> {success}  — db_info: {DbType, DbName}
     """
-    p = params or {}
+    p = _params(params)
     r = get_resolve()
     if r is None:
-        return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
+        return _not_connected_error()
     pm = r.GetProjectManager()
 
     if action == "get_current":
@@ -15076,6 +15303,7 @@ def project_manager_database(action: str, params: Optional[Dict[str, Any]] = Non
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Project metadata, settings, and color groups.
 
@@ -15100,7 +15328,7 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
       apply_fairlight_preset(preset_name) -> {success}
       generate_speech(speech_generation_settings, timecode?) -> {success, new, new_id}  — Resolve 21+, AI Speech Generator; creates new audio media (confirm-gated)
     """
-    p = params or {}
+    p = _params(params)
     _, proj, err = _check()
     if err:
         return err
@@ -15853,6 +16081,7 @@ def _export_render_boundary_report(proj, p: Dict[str, Any]):
 
 
 @mcp.tool()
+@_guard_missing_params
 def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Render pipeline: jobs, presets, formats, codecs, and rendering.
 
@@ -15901,7 +16130,7 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     resolved against the live matrix, so an intent unavailable on this
     machine/license fails with the actual available lists.
     """
-    p = params or {}
+    p = _params(params)
     _, proj, err = _check()
     if err:
         return err
@@ -16044,6 +16273,7 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def media_storage(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Browse storage volumes and import media into the Media Pool.
 
@@ -16060,10 +16290,10 @@ def media_storage(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
       add_clip_mattes(clip_id, paths, stereo_eye?) -> {success}
       add_timeline_mattes(paths) -> {items}
     """
-    p = params or {}
+    p = _params(params)
     r = get_resolve()
     if r is None:
-        return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
+        return _not_connected_error()
     ms = r.GetMediaStorage()
 
     if action == "get_volumes":
@@ -16111,6 +16341,7 @@ def media_storage(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("media_pool")
 def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage the Media Pool: folders, clips, timelines, import/export.
@@ -16198,7 +16429,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
       copy_clip_annotations(source_clip_id, target_clip_ids, include_markers?, include_flags?, include_clip_color?, dry_run?) -> {success, results}
       media_pool_boundary_report(depth?, clip_ids?, selected?) -> {capabilities, media_pool, items?}
     """
-    p = params or {}
+    p = _params(params)
     _, proj, mp, err = _get_mp()
     if err:
         return err
@@ -16575,6 +16806,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Operations on Media Pool folders.
 
@@ -16593,7 +16825,7 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
       analyze_for_slate(path?, marker_color?) -> {success}  — Resolve 21+, AI Slate ID Extra
       remove_motion_blur(path?, deblur_option?) -> {success, created}  — Resolve 21+; renders NEW media (confirm-gated)
     """
-    p = params or {}
+    p = _params(params)
     _, _, mp, err = _get_mp()
     if err:
         return err
@@ -16716,6 +16948,7 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Operations on a media pool clip. Identify clip by clip_id.
 
@@ -16767,7 +17000,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
           verified empirically on Resolve Studio 20.3.2.9. If BMD changes the
           behavior the clip will still be selected — editor double-clicks to load.
     """
-    p = params or {}
+    p = _params(params)
     _, _, mp, err = _get_mp()
     if err:
         return err
@@ -17080,6 +17313,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def media_pool_item_markers(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Markers and flags on media pool clips. Identify clip by clip_id.
 
@@ -17100,7 +17334,7 @@ def media_pool_item_markers(action: str, params: Optional[Dict[str, Any]] = None
       monitor_growing_file(clip_id) -> {success}
       replace_clip_preserve_sub_clip(clip_id, path) -> {success}
     """
-    p = params or {}
+    p = _params(params)
     _, _, mp, err = _get_mp()
     if err:
         return err
@@ -17212,6 +17446,7 @@ def _opt_number(value: Any) -> Optional[float]:
 
 
 @mcp.tool()
+@_guard_missing_params
 async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, ctx: Optional[Context] = None) -> Dict[str, Any]:
     """Project-scoped media analysis and guarded metadata publishing.
 
@@ -17308,7 +17543,7 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
     vision-dependent metadata to Resolve. Works with any MCP client whose chat
     model is vision-capable; no sampling/createMessage support required.
     """
-    p = _media_analysis_apply_setup_defaults(action, dict(params or {}))
+    p = _params(_media_analysis_apply_setup_defaults(action, dict(params or {})))
 
     # First-run frame-sampling prompt: if the user has never chosen a sampling
     # mode (and didn't pass one this call), ask before spending any vision
@@ -18384,6 +18619,7 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def timeline_versioning(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Timeline version-on-mutate, archive, rollback, and brain-edit history (C6).
 
@@ -18431,7 +18667,7 @@ def timeline_versioning(action: str, params: Optional[Dict[str, Any]] = None) ->
     if ctx is None:
         return _err("No current project / can't resolve project root")
     resolve_h, project_h, project_root, project_name = ctx
-    p = params or {}
+    p = _params(params)
 
     if action == "begin_run":
         return _analysis_runs.begin_run(
@@ -18756,6 +18992,7 @@ def _edit_engine_linked_audio_tracks(
 
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("edit_engine")
 def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Evidence-driven edit loops (Phase E): selects assembly, tighten, swap.
@@ -18797,7 +19034,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       timeline (version-archived first).
     - list_plans(limit?) / get_plan(plan_id)
     """
-    p = params or {}
+    p = _params(params)
 
     def _project_context(*, need_resolve: bool) -> Tuple[Optional[Any], Optional[Any], Optional[str], Optional[Dict[str, Any]]]:
         # An explicit analysis_root always wins — the evidence DB the caller
@@ -19562,6 +19799,7 @@ _TIMELINE_ACTIONS = [
 
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline")
 def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Timeline operations: tracks, clips, import/export, generators, titles.
@@ -19747,7 +19985,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     For long-form per-action guidance and a worked example, call:
       timeline(action="action_help", params={"name": "<action>"})
     """
-    p = params or {}
+    p = _params(params)
     # action_help is pull-on-demand metadata; no Resolve connection needed.
     if action == "action_help":
         return _action_help("timeline", p)
@@ -20148,7 +20386,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
             result["ignored_state_keys"] = ignored_state
         return result
     elif action == "extract_source_frame_ranges":
-        p = params or {}
+        p = _params(params)
         handles = int(p.get("handles", 24))
         gap_max = int(p.get("gap_max", 30))
         audio_ext = tuple(
@@ -20335,6 +20573,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline_markers")
 def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
     """Markers and playhead operations on the current timeline.
@@ -20370,7 +20609,7 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
       export_review_report(scope?, include_capabilities?) -> {title, annotations, capabilities?}
       annotation_boundary_report(scope?) -> {capabilities, annotations}
     """
-    p = params or {}
+    p = _params(params)
     _, tl, err = _get_tl()
     if err:
         return err
@@ -20455,6 +20694,7 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline_ai")
 def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """AI and analysis operations on the current timeline.
@@ -20468,7 +20708,7 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       grab_still() -> {success}
       grab_all_stills(source?) -> {count}
     """
-    p = params or {}
+    p = _params(params)
     _, tl, err = _get_tl()
     if err:
         return err
@@ -20509,6 +20749,7 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline_item")
 def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Properties, transforms, speed, keyframes, and metadata for a timeline item.
@@ -20560,7 +20801,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
 
     Default: track_type="video", track_index=1, item_index=0
     """
-    p = params or {}
+    p = _params(params)
     tl, item, err = _get_item(p)
     if err:
         return err
@@ -20748,6 +20989,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline_item_markers")
 def timeline_item_markers(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Markers, flags, and clip color on timeline items. Identify by track_type, track_index, item_index (item_index is 0-BASED: 0 = first clip; track_index is 1-based).
@@ -20770,7 +21012,7 @@ def timeline_item_markers(action: str, params: Optional[Dict[str, Any]] = None)
 
     Default: track_type="video", track_index=1, item_index=0
     """
-    p = params or {}
+    p = _params(params)
     _, item, err = _get_item(p)
     if err:
         return err
@@ -20825,6 +21067,7 @@ def timeline_item_markers(action: str, params: Optional[Dict[str, Any]] = None)
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline_item_fusion")
 def timeline_item_fusion(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Fusion composition operations on timeline items. Identify by track_type, track_index, item_index (item_index is 0-BASED: 0 = first clip; track_index is 1-based).
@@ -20845,7 +21088,7 @@ def timeline_item_fusion(action: str, params: Optional[Dict[str, Any]] = None) -
 
     Default: track_type="video", track_index=1, item_index=0
     """
-    p = params or {}
+    p = _params(params)
     _, item, err = _get_item(p)
     if err:
         return err
@@ -22126,6 +22369,7 @@ def _grade_evidence_base(proj, item, p: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline_item_color")
 def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Color grading, versions, LUTs, cache, and AI tools on timeline items. Identify by track_type, track_index, item_index (item_index is 0-BASED: 0 = first clip; track_index is 1-based).
@@ -22216,7 +22460,7 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
     For long-form per-action guidance and a worked example, call:
       timeline_item_color(action="action_help", params={"name": "<action>"})
     """
-    p = params or {}
+    p = _params(params)
     if action == "action_help":
         return _action_help("timeline_item_color", p)
     _, item, err = _get_item(p)
@@ -22331,6 +22575,7 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("timeline_item_takes")
 def timeline_item_takes(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Take management on timeline items. Identify by track_type, track_index, item_index (item_index is 0-BASED: 0 = first clip; track_index is 1-based).
@@ -22346,7 +22591,7 @@ def timeline_item_takes(action: str, params: Optional[Dict[str, Any]] = None) ->
 
     Default: track_type="video", track_index=1, item_index=0
     """
-    p = params or {}
+    p = _params(params)
     _, item, err = _get_item(p)
     if err:
         return err
@@ -22379,6 +22624,7 @@ def timeline_item_takes(action: str, params: Optional[Dict[str, Any]] = None) ->
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def gallery(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Gallery album management.
 
@@ -22394,7 +22640,7 @@ def gallery(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, A
 
     album_index is 0-based into the still albums list.
     """
-    p = params or {}
+    p = _params(params)
     _, proj, err = _check()
     if err:
         return err
@@ -22444,6 +22690,7 @@ def gallery(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, A
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage stills in gallery albums (best results on Color page).
 
@@ -22464,7 +22711,7 @@ def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
     File data is inlined in the response (DRX as text, images as base64).
     cleanup (default true) deletes exported files from disk after inlining.
     """
-    p = params or {}
+    p = _params(params)
     _, proj, err = _check()
     if err:
         return err
@@ -22597,6 +22844,7 @@ def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 @_destructive_op("graph")
 def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Node graph operations (color grading nodes). Source can be timeline, timeline item, or color group.
@@ -22636,7 +22884,7 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
     For long-form per-action guidance and a worked example, call:
       graph(action="action_help", params={"name": "<action>"})
     """
-    p = params or {}
+    p = _params(params)
     if action == "action_help":
         return _action_help("graph", p)
     source = p.get("source", "timeline")
@@ -22739,6 +22987,7 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
 # ═══════════════════════════════════════════════════════════════════════════════
 
 @mcp.tool()
+@_guard_missing_params
 def color_group(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Manage color groups and their node graphs.
 
@@ -22750,7 +22999,7 @@ def color_group(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       get_pre_clip_graph(group_name) -> {available, num_nodes}
       get_post_clip_graph(group_name) -> {available, num_nodes}
     """
-    p = params or {}
+    p = _params(params)
     _, proj, err = _check()
     if err:
         return err
@@ -23661,6 +23910,7 @@ def _fusion_get_text_plus(comp, p: Dict[str, Any]) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@_guard_missing_params
 def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Fusion composition node graph operations.
 
@@ -23731,7 +23981,7 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       ColorCorrector, RectangleMask, EllipseMask, Tracker, MediaIn, MediaOut,
       Loader, Saver, Glow, FilmGrain, CornerPositioner, DeltaKeyer, UltraKeyer
     """
-    p = params or {}
+    p = _params(params)
 
     if action == "bulk_set_inputs":
         return _fusion_comp_bulk_set_inputs(p)
@@ -24231,6 +24481,7 @@ def _validate_glsl_minimal(source: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@_guard_missing_params
 def fuse_plugin(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Author and install Fusion Fuse plugins (.fuse files).
 
@@ -24257,7 +24508,7 @@ def fuse_plugin(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
           docs/authoring/fuse-dctl-authoring.md for the per-kind option spec.
       list_templates() -> {kinds}
     """
-    p = params or {}
+    p = _params(params)
 
     if action == "path":
         return {"fuses_dir": _fuses_dir()}
@@ -24474,6 +24725,7 @@ _DCTL_VALID_CATEGORIES = ("lut", "aces_idt", "aces_odt")
 
 
 @mcp.tool()
+@_guard_missing_params
 def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Author and install DCTL files (Color page custom shaders + ACES transforms).
 
@@ -24510,7 +24762,7 @@ def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
           pass that as the `category` argument to install().
       list_templates() -> {kinds, kind_categories}
     """
-    p = params or {}
+    p = _params(params)
 
     def _category(default: str = "lut") -> Tuple[Optional[Dict[str, Any]], str]:
         cat = p.get("category", default)
@@ -24787,8 +25039,7 @@ def _execute_python_script(path: str, args: List[str],
 def _execute_lua_script(path: str) -> Dict[str, Any]:
     r = get_resolve()
     if r is None:
-        return _err("Cannot run Lua script — Resolve isn't running and "
-                    "auto-launch failed.")
+        return _not_connected_error()
     fusion = r.Fusion()
     if fusion is None:
         return _err("handle.Fusion() returned None — cannot run Lua scripts.")
@@ -24853,7 +25104,7 @@ def _run_inline_lua(source: str) -> Dict[str, Any]:
     """
     r = get_resolve()
     if r is None:
-        return _err("Cannot run Lua — Resolve isn't running and auto-launch failed.")
+        return _not_connected_error()
     fusion = r.Fusion()
     if fusion is None:
         return _err("handle.Fusion() returned None — cannot run inline Lua.")
@@ -25403,6 +25654,7 @@ def _extension_boundary_report(p: Dict[str, Any]) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@_guard_missing_params
 def script_plugin(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Author and install Resolve-page Lua/Python scripts (Workspace → Scripts menu).
 
@@ -25458,7 +25710,7 @@ def script_plugin(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
       refresh_or_restart_required(extension_type, category?) -> {refresh_luts, restart_required}
       extension_boundary_report(include_template_matrix?) -> {capabilities, template_matrix, dry_run_probes}
     """
-    p = params or {}
+    p = _params(params)
 
     if action == "extension_capabilities":
         return _extension_capabilities()
@@ -25962,5 +26214,5 @@ if __name__ == "__main__":
         logger.error(f"Unknown --transport {transport!r}; use stdio|sse|streamable-http")
         sys.exit(2)
 
-    logger.info(f"Starting DaVinci Resolve MCP Server (32 compound tools)")
+    logger.info("Starting DaVinci Resolve MCP Server (34 compound tools)")
     run_fastmcp_stdio(mcp)

package/src/utils/bridge_differential.py

@@ -182,12 +182,22 @@ def probe_surface(roots: Sequence[str] = SOURCE_ROOTS) -> Dict[str, Any]:
 #: MediaPoolItem or Graph — which between them carry most of the read surface
 #: worth qualifying (LUTs, node graphs, source timings, metadata).
 _INDEX = "[]"
+#: Pick the first element of a returned list for which `method()` is truthy.
+#: Indexing blindly is not good enough: a timeline's first video item is often a
+#: generator or a title, which has no MediaPoolItem and answers None to every
+#: node-graph question. Measured on a real timeline — `GetNumNodes` and
+#: `GetNodeGraph` both None on an SMPTE Color Bar, and 1 and a live graph on the
+#: clip sitting next to it. Taking index 0 therefore reported the whole grading
+#: surface as unreachable, which is the silent coverage gap this module exists to
+#: refuse.
+_FIRST_WITH = "[first-with]"
 
 _PM = ("GetProjectManager", ())
 _PROJECT = (_PM, ("GetCurrentProject", ()))
 _POOL = _PROJECT + (("GetMediaPool", ()),)
 _TIMELINE = _PROJECT + (("GetCurrentTimeline", ()),)
-_TIMELINE_ITEM = _TIMELINE + (("GetItemListInTrack", ("video", 1)), (_INDEX, (0,)))
+_TIMELINE_ITEM = _TIMELINE + (("GetItemListInTrack", ("video", 1)),
+                              (_FIRST_WITH, ("GetMediaPoolItem",)))
 _GALLERY = _PROJECT + (("GetGallery", ()),)
 
 OBJECT_GRAPH: Tuple[Tuple[str, Tuple[Any, ...]], ...] = (
@@ -229,6 +239,22 @@ def walk(resolve: Any, chain: Iterable[Tuple[str, Tuple[Any, ...]]]) -> Any:
                 return None
             current = current[index]
             continue
+        if method == _FIRST_WITH:
+            if not isinstance(current, (list, tuple)):
+                return None
+            probe = args[0]
+            chosen = None
+            for candidate in current:
+                try:
+                    if getattr(candidate, probe, lambda: None)():
+                        chosen = candidate
+                        break
+                except Exception:  # noqa: BLE001 - an unusable candidate, not a verdict
+                    continue
+            if chosen is None:
+                return None
+            current = chosen
+            continue
         function = getattr(current, method, None)
         if function is None:
             return None