davinci-resolve-mcp 2.67.1 → 2.68.0

package/scripts/resolve_capability_probe.py

@@ -0,0 +1,270 @@
+"""Resolve Scripts-menu capability probe: what does THIS edition's API expose?
+
+Run from **Workspace ▸ Scripts ▸ resolve_capability_probe**, on whichever
+edition you want to characterise.
+
+The free edition gates *features* (noise reduction, Magic Mask, Super Scale,
+some codecs, some resolutions). What it does to the *scripting API* is a
+separate question and is not documented anywhere authoritative: a method may be
+absent, or present and always return False, or present and work. Those three
+cases need completely different handling in a connector, and guessing which is
+which is how you ship a tool that lies about what it did.
+
+So this asks the running application, on the edition in front of you.
+
+**Strictly read-only.** It enumerates methods, calls only getters, and creates,
+modifies and deletes nothing. Safe to run on a real project — though it reads
+whatever project is open, so use a scratch one if you would rather not have your
+timeline names in the report.
+
+Writes to ``~/.config/davinci-resolve-mcp/capability-probe-<edition>.json`` and
+prints a summary. Self-contained: no repository imports.
+"""
+
+import json
+import os
+import sys
+import time
+
+REPORT_DIR = os.path.expanduser("~/.config/davinci-resolve-mcp")
+
+#: Methods worth knowing about, grouped by the object they live on. Chosen for
+#: what a connector actually needs, not for completeness.
+SURFACE = {
+    "Resolve": [
+        "GetProductName", "GetVersionString", "GetCurrentPage", "OpenPage",
+        "GetProjectManager", "GetMediaStorage", "ImportRenderPreset",
+        "ExportRenderPreset", "ImportBurnInPreset", "Quit",
+    ],
+    "ProjectManager": [
+        "GetCurrentProject", "GetProjectListInCurrentFolder", "GetCurrentFolder",
+        "GetCurrentDatabase", "GetDatabaseList", "CreateProject", "LoadProject",
+        "SaveProject", "CloseProject", "DeleteProject", "ExportProject",
+        "ImportProject", "CreateFolder", "ArchiveProject",
+    ],
+    "Project": [
+        "GetName", "GetTimelineCount", "GetTimelineByIndex", "GetCurrentTimeline",
+        "SetCurrentTimeline", "GetMediaPool", "GetGallery", "GetSetting",
+        "SetSetting", "GetRenderFormats", "GetRenderCodecs",
+        "GetCurrentRenderFormatAndCodec", "GetRenderPresetList", "AddRenderJob",
+        "StartRendering", "IsRenderingInProgress", "GetRenderJobList",
+        "GetQuickExportRenderPresets", "RefreshLUTList", "GetUniqueId",
+    ],
+    "MediaPool": [
+        "GetRootFolder", "GetCurrentFolder", "AddSubFolder", "ImportMedia",
+        "CreateEmptyTimeline", "CreateTimelineFromClips", "AppendToTimeline",
+        "DeleteTimelines", "DeleteClips", "ImportTimelineFromFile",
+        "GetTimelineMatte", "RefreshFolders",
+    ],
+    "Timeline": [
+        "GetName", "SetName", "GetStartFrame", "GetEndFrame", "GetTrackCount",
+        "GetItemListInTrack", "GetTrackName", "GetIsTrackEnabled",
+        "AddTrack", "DeleteTrack", "AddMarker", "GetMarkers",
+        "DuplicateTimeline", "Export", "GetCurrentTimecode", "SetCurrentTimecode",
+        "InsertFusionTitleIntoTimeline", "InsertTitleIntoTimeline",
+        "CreateSubtitlesFromAudio", "DetectSceneCuts", "GetSetting",
+    ],
+    "TimelineItem": [
+        "GetName", "GetDuration", "GetStart", "GetEnd", "GetProperty",
+        "SetProperty", "GetNumNodes", "SetLUT", "GetLUT", "SetCDL",
+        "AddMarker", "GetMarkers", "GetFusionCompCount", "AddFusionComp",
+        "SetClipEnabled", "GetMediaPoolItem", "CreateMagicMask",
+        "SmartReframe", "GetNodeLabel",
+    ],
+    "MediaPoolItem": [
+        "GetName", "GetClipProperty", "SetClipProperty", "GetMetadata",
+        "SetMetadata", "GetMediaId", "AddMarker", "GetMarkers", "LinkProxyMedia",
+        "TranscribeAudio", "ClearTranscription",
+    ],
+}
+
+#: Getters that are safe to actually call, to separate "method exists" from
+#: "method works". A method can be present and still be inert on this edition.
+SAFE_CALLS = {
+    "Resolve": ["GetProductName", "GetVersionString", "GetCurrentPage"],
+    "ProjectManager": ["GetProjectListInCurrentFolder", "GetCurrentFolder"],
+    "Project": [
+        "GetName", "GetTimelineCount", "GetRenderFormats",
+        "GetCurrentRenderFormatAndCodec", "GetRenderPresetList",
+        "IsRenderingInProgress", "GetRenderJobList",
+    ],
+    "MediaPool": ["GetRootFolder", "GetCurrentFolder"],
+    "Timeline": [
+        "GetName", "GetStartFrame", "GetEndFrame", "GetCurrentTimecode", "GetMarkers",
+    ],
+}
+
+
+def acquire_resolve():
+    candidate = globals().get("resolve")
+    if candidate is not None:
+        return candidate
+    bmd = globals().get("bmd")
+    if bmd is not None:
+        try:
+            return bmd.scriptapp("Resolve")
+        except Exception:
+            return None
+    try:
+        import DaVinciResolveScript as script_module
+        return script_module.scriptapp("Resolve")
+    except Exception:
+        return None
+
+
+def classify(obj, names):
+    """Which of `names` exist on `obj`."""
+    if obj is None:
+        return {"reachable": False, "note": "object not sampled in this context",
+                "present": [], "missing": sorted(names)}
+    present, missing = [], []
+    for name in names:
+        (present if callable(getattr(obj, name, None)) else missing).append(name)
+    return {"reachable": True, "present": sorted(present), "missing": sorted(missing)}
+
+
+def try_calls(obj, names):
+    """Call safe getters; record value shape or the failure. Never mutates."""
+    out = {}
+    if obj is None:
+        return out
+    for name in names:
+        fn = getattr(obj, name, None)
+        if not callable(fn):
+            out[name] = {"ok": False, "why": "absent"}
+            continue
+        try:
+            value = fn()
+        except Exception as exc:
+            out[name] = {"ok": False, "why": "raised: %s" % type(exc).__name__}
+            continue
+        if value is None:
+            out[name] = {"ok": False, "why": "returned None"}
+        elif isinstance(value, bool):
+            # A bool getter answering False is a real answer, not a failure.
+            # Scoring it as one is how "nothing is rendering" reads as "broken".
+            out[name] = {"ok": True, "type": "bool", "value": value}
+        elif isinstance(value, dict):
+            out[name] = {"ok": True, "type": "dict", "size": len(value),
+                         "sample": sorted(list(value)[:8])}
+        elif isinstance(value, (list, tuple)):
+            out[name] = {"ok": True, "type": "list", "size": len(value),
+                         "sample": [str(v)[:40] for v in list(value)[:8]]}
+        else:
+            out[name] = {"ok": True, "type": type(value).__name__, "value": str(value)[:120]}
+    return out
+
+
+def main():
+    resolve = acquire_resolve()
+    if resolve is None:
+        print("Could not get the resolve object. Run this from Workspace > Scripts.")
+        return None
+
+    report = {"probed_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+              "interpreter": sys.executable}
+    try:
+        product = resolve.GetProductName()
+        report["product"] = product
+        report["version"] = resolve.GetVersionString()
+        report["edition"] = "studio" if "studio" in str(product).lower() else "free"
+    except Exception as exc:
+        report["product_error"] = type(exc).__name__
+        report["edition"] = "unknown"
+
+    manager = getattr(resolve, "GetProjectManager", lambda: None)()
+    project = getattr(manager, "GetCurrentProject", lambda: None)() if manager else None
+    pool = getattr(project, "GetMediaPool", lambda: None)() if project else None
+    timeline = getattr(project, "GetCurrentTimeline", lambda: None)() if project else None
+
+    item = None
+    if timeline is not None:
+        try:
+            for index in range(1, int(timeline.GetTrackCount("video") or 0) + 1):
+                items = timeline.GetItemListInTrack("video", index) or []
+                if items:
+                    item = items[0]
+                    break
+        except Exception:
+            item = None
+    media_item = None
+    if pool is not None:
+        try:
+            clips = pool.GetRootFolder().GetClipList() or []
+            media_item = clips[0] if clips else None
+        except Exception:
+            media_item = None
+
+    objects = {
+        "Resolve": resolve, "ProjectManager": manager, "Project": project,
+        "MediaPool": pool, "Timeline": timeline, "TimelineItem": item,
+        "MediaPoolItem": media_item,
+    }
+    report["surface"] = {k: classify(objects.get(k), v) for k, v in SURFACE.items()}
+    report["calls"] = {k: try_calls(objects.get(k), v) for k, v in SAFE_CALLS.items()}
+    report["context"] = {
+        "project_open": project is not None,
+        "timeline_open": timeline is not None,
+        "timeline_item_sampled": item is not None,
+        "media_item_sampled": media_item is not None,
+    }
+
+    # The render matrix is where free/Studio differ most visibly.
+    if project is not None:
+        try:
+            formats = project.GetRenderFormats() or {}
+            matrix = {}
+            for label in sorted(formats)[:40]:
+                try:
+                    codecs = project.GetRenderCodecs(formats[label]) or {}
+                    matrix[label] = sorted(codecs)
+                except Exception:
+                    matrix[label] = ["<error>"]
+            report["render_matrix"] = matrix
+            report["render_format_count"] = len(formats)
+            report["render_pair_count"] = sum(len(v) for v in matrix.values())
+        except Exception as exc:
+            report["render_matrix_error"] = type(exc).__name__
+
+    edition = report.get("edition", "unknown")
+    path = os.path.join(REPORT_DIR, "capability-probe-%s.json" % edition)
+    try:
+        if not os.path.isdir(REPORT_DIR):
+            os.makedirs(REPORT_DIR)
+        with open(path, "w") as handle:
+            json.dump(report, handle, indent=2, sort_keys=True)
+        written = path
+    except (OSError, IOError) as exc:
+        written = "could not write (%s)" % type(exc).__name__
+
+    print("=" * 70)
+    print("Resolve capability probe - %s %s (%s)" % (
+        report.get("product", "?"), report.get("version", "?"), edition))
+    print("=" * 70)
+    for group, result in report["surface"].items():
+        if not result.get("reachable"):
+            print("  %-16s not sampled (%s)" % (group, result.get("note")))
+            continue
+        total = len(result["present"]) + len(result["missing"])
+        print("  %-16s %d/%d present" % (group, len(result["present"]), total))
+        if result["missing"]:
+            print("       missing: %s" % ", ".join(result["missing"]))
+    print()
+    failed = [(g, n, r["why"]) for g, calls in report["calls"].items()
+              for n, r in calls.items() if not r["ok"]]
+    print("  safe getter calls: %d ok, %d not" % (
+        sum(1 for g, c in report["calls"].items() for r in c.values() if r["ok"]), len(failed)))
+    for group, name, why in failed:
+        print("       %s.%s -> %s" % (group, name, why))
+    if "render_format_count" in report:
+        print()
+        print("  render matrix: %d formats, %d format/codec pairs" % (
+            report["render_format_count"], report["render_pair_count"]))
+    print()
+    print("  context: %s" % json.dumps(report["context"]))
+    print("  report:  %s" % written)
+    print("=" * 70)
+    return report
+
+
+main()

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.67.1"
+VERSION = "2.68.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -234,6 +234,11 @@ mcp.tool = _tool_with_default_annotations
 
 resolve = None
 dvr_script = None
+#: `dvr_script` may be None when Resolve is not installed; every use passes it
+#: to `connect_resolve()`, which treats None as "not available" and returns None.
+_OPTIONAL_DEPENDENCY_CONTRACT = (
+    "DaVinciResolveScript: always routed through connect_resolve(), which is None-tolerant"
+)
 
 try:
     import DaVinciResolveScript as dvr_script  # type: ignore

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.67.1"
+VERSION = "2.68.0"
 
 import base64
 import os
@@ -122,6 +122,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 +804,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 +844,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":
@@ -15240,6 +15283,7 @@ _RENDER_KERNEL_ACTIONS = [
     "export_render_boundary_report",
     "list_delivery_targets",
     "resolve_delivery_target",
+    "list_loudness_standards",
     "prepare_delivery_job",
 ]
 
@@ -15618,6 +15662,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 +15680,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:
@@ -15864,6 +15939,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":
@@ -17288,6 +17366,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 +18307,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",
@@ -18752,6 +18864,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 +18942,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 +19528,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",