davinci-resolve-mcp 2.67.1 → 2.68.1

package/src/server.py

@@ -11,11 +11,13 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.67.1"
+VERSION = "2.68.1"
 
 import base64
 import os
 import sys
+import functools
+import inspect
 import json
 import logging
 import math
@@ -122,6 +124,7 @@ from src.utils.fusion_group_settings import (
 from src.utils import analysis_runs as _analysis_runs
 from src.utils import brain_edits as _brain_edits
 from src.utils import edit_engine as _edit_engine_mod
+from src.utils import transcript_edit as _transcript_edit_defaults
 from src.utils import media_pool_changes as _media_pool_changes
 from src.utils import timeline_versioning as _timeline_versioning
 from src.utils import project_spec as _project_spec
@@ -803,11 +806,32 @@ def _is_resolve_handle_live(candidate) -> bool:
         return False
 
 
+def _bridge_requested() -> bool:
+    """Has the operator asked for the in-app bridge?
+
+    Read at call time rather than at import, so a server started before the
+    variable was set still honours it.
+    """
+    try:
+        from src.utils import resolve_bridge_client
+
+        return resolve_bridge_client.bridge_enabled()
+    except Exception:  # pragma: no cover - the client is optional
+        return False
+
+
 def _try_connect():
     """Attempt to connect to Resolve once. Returns resolve object or None."""
     global resolve
     with _resolve_lock:
-        if dvr_script is None:
+        # `dvr_script` is Blackmagic's module, and it ships with the *installer*,
+        # not the App Store build — a free-edition-only machine has no
+        # Developer/Scripting/Modules tree at all, so the import fails. Bailing
+        # here made the bridge unreachable on precisely the configuration it
+        # exists for: `connect_resolve` accepts None in bridge mode, and this
+        # returned before ever calling it. Verified by blocking the import with a
+        # healthy bridge listening — get_resolve() answered None.
+        if dvr_script is None and not _bridge_requested():
             return None
         try:
             candidate = connect_resolve(dvr_script)
@@ -822,13 +846,34 @@ def _try_connect():
             resolve = None
             return None
 
+#: macOS puts the two editions in different places, and only the first was ever
+#: checked — so an auto-launch on a machine with both would start Studio even
+#: when the free edition was the one in use. Ordered installer-first to keep the
+#: previous behaviour where Studio is present.
+_MACOS_RESOLVE_APPS = (
+    "/Applications/DaVinci Resolve/DaVinci Resolve.app",  # installer / Studio
+    "/Applications/DaVinci Resolve.app",                  # App Store, free
+)
+
+
 def _launch_resolve():
     """Launch DaVinci Resolve and wait for it to become available."""
+    if _bridge_requested():
+        # Launching cannot produce a bridge. The listener only exists once
+        # someone runs Workspace > Scripts > resolve_bridge inside an already
+        # running Resolve, so starting the application here would open a window
+        # nobody asked for and still fail to connect.
+        logger.error(
+            "The in-app bridge is enabled but not answering. Start it from "
+            "Workspace > Scripts > resolve_bridge inside the running Resolve; "
+            "launching the application cannot start it."
+        )
+        return False
     sys_name = platform.system().lower()
     if sys_name == "darwin":
-        app_path = "/Applications/DaVinci Resolve/DaVinci Resolve.app"
-        if not os.path.exists(app_path):
-            logger.error(f"DaVinci Resolve not found at {app_path}")
+        app_path = next((p for p in _MACOS_RESOLVE_APPS if os.path.exists(p)), None)
+        if app_path is None:
+            logger.error("DaVinci Resolve not found in %s", list(_MACOS_RESOLVE_APPS))
             return False
         subprocess.Popen(["open", app_path], stdin=subprocess.DEVNULL)
     elif sys_name == "windows":
@@ -1182,6 +1227,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.
@@ -12644,6 +12803,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.
 
@@ -12657,7 +12817,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"],
@@ -12797,6 +12957,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.
 
@@ -12839,7 +13000,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":
@@ -13816,6 +13977,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.
 
@@ -13827,7 +13989,7 @@ 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.")
@@ -13862,6 +14024,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.
 
@@ -13871,7 +14034,7 @@ 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.")
@@ -14772,6 +14935,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.
 
@@ -14813,7 +14977,7 @@ 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.")
@@ -14920,6 +15084,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.
 
@@ -14932,7 +15097,7 @@ 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.")
@@ -14964,6 +15129,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).
 
@@ -14973,7 +15139,7 @@ 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.")
@@ -15002,6 +15168,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.
 
@@ -15010,7 +15177,7 @@ 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.")
@@ -15033,6 +15200,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.
 
@@ -15057,7 +15225,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
@@ -15240,6 +15408,7 @@ _RENDER_KERNEL_ACTIONS = [
     "export_render_boundary_report",
     "list_delivery_targets",
     "resolve_delivery_target",
+    "list_loudness_standards",
     "prepare_delivery_job",
 ]
 
@@ -15618,6 +15787,9 @@ def _resolve_delivery_target_live(proj, p: Dict[str, Any]):
 
     fps = _delivery_timeline_fps(proj)
     qc_spec = _delivery_targets.to_qc_spec(target, timeline_fps=fps)
+    # Loudness is a separate projection feeding advanced `loudness_qc`, not a
+    # deliverable_qc field — the mix sets programme loudness, not the render.
+    loudness = _delivery_targets.to_loudness_target(target)
     return (
         {
             "target": target.id,
@@ -15633,12 +15805,40 @@ def _resolve_delivery_target_live(proj, p: Dict[str, Any]):
                 if qc_spec
                 else "This target renders an image sequence; deliverable_qc probes a single file, so it has no QC spec."
             ),
+            "loudness_target": loudness,
+            "loudness_note": (
+                None
+                if loudness
+                else "This target pins no programme loudness. Name one with "
+                "overrides={'loudness_standard': ...}; see render(action='list_loudness_standards')."
+            ),
             "notes": list(target.notes),
         },
         None,
     )
 
 
+def _list_loudness_standards(proj, p: Dict[str, Any]):
+    """Named programme-loudness contracts, so an agent cites one rather than inventing numbers."""
+    return (
+        {
+            "standards": _delivery_targets.list_loudness_standards(),
+            "lra_advisory_lu": _delivery_targets.LRA_ADVISORY_LU,
+            "usage": (
+                "Attach with render(action='resolve_delivery_target', params={'target': ..., "
+                "'overrides': {'loudness_standard': '<id>'}}), then hand the returned "
+                "loudness_target.target to the advanced server's loudness_qc."
+            ),
+            "note": (
+                "Dialogue-gated standards emit no gradeable integrated value: loudness_qc "
+                "measures full-program loudness, so that figure travels in meta for a "
+                "dialogue-gated meter and only true peak is asserted."
+            ),
+        },
+        None,
+    )
+
+
 def _list_delivery_targets(proj, p: Dict[str, Any]):
     tier = p.get("tier")
     if tier is not None and tier not in _delivery_targets.TIERS:
@@ -15778,6 +15978,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.
 
@@ -15826,7 +16027,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
@@ -15864,6 +16065,9 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     elif action == "resolve_delivery_target":
         _resolved, _target_err = _resolve_delivery_target_live(proj, p)
         return _target_err if _target_err else _ok(**_resolved)
+    elif action == "list_loudness_standards":
+        _standards, _standards_err = _list_loudness_standards(proj, p)
+        return _standards_err if _standards_err else _ok(**_standards)
     elif action == "prepare_delivery_job":
         return _prepare_delivery_job(proj, p)
     elif action == "set_format_and_codec":
@@ -15966,6 +16170,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.
 
@@ -15982,7 +16187,7 @@ 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.")
@@ -16033,6 +16238,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.
@@ -16120,7 +16326,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
@@ -16497,6 +16703,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.
 
@@ -16515,7 +16722,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
@@ -16638,6 +16845,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.
 
@@ -16689,7 +16897,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
@@ -17002,6 +17210,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.
 
@@ -17022,7 +17231,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
@@ -17134,6 +17343,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.
 
@@ -17230,7 +17440,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
@@ -17288,6 +17498,38 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
 
     if action == "capabilities":
         return _media_analysis_capabilities_for_request(ctx)
+    if action == "assess_grade":
+        # Numeric grade-damage QC. Distinct from advanced `verify_grade`, which
+        # asks whether Resolve applied what was asked; this asks whether the
+        # resulting image is damaged. Free and deterministic — the vision block
+        # in the result says whether a paid second opinion is warranted.
+        from src.utils import image_qc as _image_qc_mod
+
+        try:
+            return _ok(**_image_qc_mod.assess_grade(
+                str(p.get("source_path") or p.get("sourcePath") or ""),
+                time_seconds=float(p.get("time_seconds", p.get("timeSeconds", 0.0)) or 0.0),
+                graded_path=(p.get("graded_path") or p.get("gradedPath")) or None,
+                lut_path=(p.get("lut_path") or p.get("lutPath")) or None,
+                working_space=str(p.get("working_space") or p.get("workingSpace") or "rec709"),
+                cost_tier=str(p.get("cost_tier") or p.get("costTier") or _image_qc_mod.DEFAULT_COST_TIER),
+            ))
+        except _image_qc_mod.ImageQcError as exc:
+            return _err(
+                str(exc),
+                code="IMAGE_QC_REFUSED",
+                category="invalid_input",
+                remediation=(
+                    "Supply exactly one of graded_path or lut_path, and declare a display-referred "
+                    "working_space. Log/scene-referred frames must be converted first — these "
+                    "metrics are undefined on them and will not be guessed at."
+                ),
+            )
+    if action == "image_qc_capabilities":
+        from src.utils import image_qc as _image_qc_mod
+
+        return _ok(**_image_qc_mod.capabilities(), cost_tiers=list(_image_qc_mod.COST_TIERS),
+                   default_cost_tier=_image_qc_mod.DEFAULT_COST_TIER)
     if action == "recheck_capabilities":
         # Re-runs detection (shutil.which / importlib.util.find_spec) so a tool
         # an agent just installed flips from missing → available without the
@@ -18197,6 +18439,8 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
     return _unknown(action, [
         "capabilities",
         "recheck_capabilities",
+        "assess_grade",
+        "image_qc_capabilities",
         "install_guidance",
         "resolve_output_root",
         "plan",
@@ -18272,6 +18516,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).
 
@@ -18319,7 +18564,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(
@@ -18644,6 +18889,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.
@@ -18685,7 +18931,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
@@ -18752,6 +18998,71 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             include_audio=str(p.get("include_audio", p.get("includeAudio", True))).strip().lower() not in {"false", "0", "no", "none", "off"},
         )
 
+    if action == "generate_captions":
+        _r, proj, project_root, err = _project_context(need_resolve=False)
+        if err:
+            return err
+        from src.utils import captions as _captions_mod
+        from src.utils import strata as _strata_mod
+
+        conn, clip, clip_err = _strata_mod.resolve_clip(
+            project_root, p.get("clip_ref") or p.get("clipRef") or p.get("clip_id"), require_media=False
+        )
+        if clip_err:
+            return clip_err
+        _words = _strata_mod.read_words(conn, clip["clip_uuid"])
+        _opts = {}
+        for _key, _param in (
+            ("max_chars_per_line", "maxCharsPerLine"), ("max_lines", "maxLines"),
+            ("max_block_seconds", "maxBlockSeconds"), ("min_block_seconds", "minBlockSeconds"),
+            ("min_gap_seconds", "minGapSeconds"), ("pause_break_seconds", "pauseBreakSeconds"),
+        ):
+            _value = p.get(_key, p.get(_param))
+            if _value is not None:
+                _opts[_key] = int(_value) if _key in {"max_chars_per_line", "max_lines"} else float(_value)
+        try:
+            _result = _captions_mod.generate(
+                _words,
+                fmt=str(p.get("format") or p.get("fmt") or "srt").lower(),
+                with_chapters=str(p.get("with_chapters", p.get("withChapters", False))).strip().lower() in {"true", "1", "yes", "on"},
+                **_opts,
+            )
+        except _captions_mod.CaptionError as exc:
+            return _err(str(exc), code="CAPTION_PARAMS_INVALID", category="invalid_input")
+        _result["clip"] = {"clip_uuid": clip["clip_uuid"], "clip_name": clip.get("clip_name")}
+        return _result
+
+    if action == "plan_transcript_tighten":
+        _r, proj, project_root, err = _project_context(need_resolve=False)
+        if err:
+            return err
+        return _edit_engine_mod.plan_transcript_tighten(
+            project_root,
+            clip_ref=p.get("clip_ref") or p.get("clipRef") or p.get("clip_id"),
+            remove_fillers=str(p.get("remove_fillers", p.get("removeFillers", True))).strip().lower() not in {"false", "0", "no", "off"},
+            remove_false_starts=str(p.get("remove_false_starts", p.get("removeFalseStarts", True))).strip().lower() not in {"false", "0", "no", "off"},
+            collapse_pauses=str(p.get("collapse_pauses", p.get("collapsePauses", True))).strip().lower() not in {"false", "0", "no", "off"},
+            max_pause=float(p.get("max_pause", p.get("maxPause", _transcript_edit_defaults.DEFAULT_MAX_PAUSE_S))),
+            handle=float(p.get("handle", _transcript_edit_defaults.DEFAULT_HANDLE_S)),
+            min_cut=float(p.get("min_cut", p.get("minCut", _transcript_edit_defaults.DEFAULT_MIN_CUT_S))),
+        )
+
+    if action == "search_spoken_content":
+        _r, proj, project_root, err = _project_context(need_resolve=False)
+        if err:
+            return err
+        query = p.get("query") or p.get("q")
+        if not isinstance(query, str) or not query.strip():
+            return _err("query is required", code="MISSING_QUERY", category="invalid_input")
+        return _edit_engine_mod.search_spoken_content(
+            project_root,
+            query=query,
+            mode=str(p.get("mode") or "phrase"),
+            context_seconds=float(p.get("context_seconds", p.get("contextSeconds", 1.5))),
+            handle_seconds=float(p.get("handle_seconds", p.get("handleSeconds", 0.5))),
+            max_hits=int(p.get("max_hits", p.get("maxHits", 200))),
+        )
+
     if action == "plan_silence_ripple":
         _r, proj, project_root, err = _project_context(need_resolve=True)
         if err:
@@ -18765,7 +19076,14 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             items=items,
             timeline_name=tl.GetName(),
             timeline_fps=_edit_engine_timeline_fps(tl),
-            threshold_db=float(p.get("threshold_db") if p.get("threshold_db") is not None else p.get("thresholdDb") if p.get("thresholdDb") is not None else _edit_engine_mod.DEFAULT_SILENCE_THRESHOLD_DB),
+            # Omitted => None => the gate is calibrated per item from that
+            # slice's own dynamics. Passing the old fixed default here would
+            # make auto-calibration unreachable through the MCP surface.
+            threshold_db=(
+                float(_th)
+                if (_th := (p.get("threshold_db") if p.get("threshold_db") is not None else p.get("thresholdDb"))) is not None
+                else None
+            ),
             min_strip_frames=float(p.get("min_strip_frames") if p.get("min_strip_frames") is not None else p.get("minStripFrames") if p.get("minStripFrames") is not None else _edit_engine_mod.DEFAULT_SILENCE_MIN_STRIP_FRAMES),
             pre_head_frames=float(p.get("pre_head_frames") if p.get("pre_head_frames") is not None else p.get("preHeadFrames") if p.get("preHeadFrames") is not None else _edit_engine_mod.DEFAULT_SILENCE_PRE_HEAD_FRAMES),
             post_tail_frames=float(p.get("post_tail_frames") if p.get("post_tail_frames") is not None else p.get("postTailFrames") if p.get("postTailFrames") is not None else _edit_engine_mod.DEFAULT_SILENCE_POST_TAIL_FRAMES),
@@ -19344,6 +19662,9 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         "plan_tighten",
         "execute_tighten",
         "plan_silence_ripple",
+        "plan_transcript_tighten",
+        "generate_captions",
+        "search_spoken_content",
         "execute_silence_ripple",
         "plan_swap",
         "execute_swap",
@@ -19375,6 +19696,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.
@@ -19560,7 +19882,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)
@@ -19961,7 +20283,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(
@@ -20148,6 +20470,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.
@@ -20183,7 +20506,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
@@ -20268,6 +20591,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.
@@ -20281,7 +20605,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
@@ -20322,6 +20646,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.
@@ -20373,7 +20698,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
@@ -20561,6 +20886,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).
@@ -20583,7 +20909,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
@@ -20638,6 +20964,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).
@@ -20658,7 +20985,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
@@ -21939,6 +22266,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).
@@ -22029,7 +22357,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)
@@ -22144,6 +22472,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).
@@ -22159,7 +22488,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
@@ -22192,6 +22521,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.
 
@@ -22207,7 +22537,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
@@ -22257,6 +22587,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).
 
@@ -22277,7 +22608,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
@@ -22410,6 +22741,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.
@@ -22449,7 +22781,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")
@@ -22552,6 +22884,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.
 
@@ -22563,7 +22896,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
@@ -23474,6 +23807,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.
 
@@ -23544,7 +23878,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)
@@ -24044,6 +24378,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).
 
@@ -24070,7 +24405,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()}
@@ -24287,6 +24622,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).
 
@@ -24323,7 +24659,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)
@@ -25216,6 +25552,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).
 
@@ -25271,7 +25608,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()