davinci-resolve-mcp 2.37.3 → 2.38.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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.38.0
+
+Busy gate for long DaVinci Resolve operations — the first piece of the
+concurrency design for the stdio + networked two-instance setup.
+
+- **Added** cross-process registration for long synchronous Resolve calls
+  (timeline export/import, scene-cut detection, subtitle generation,
+  Dolby Vision analysis, folder/clip audio transcription). A tool call that
+  arrives while one is running now waits up to 5 seconds and then returns a
+  structured `RESOLVE_BUSY` error (new `busy` category, retryable, with
+  `state.busy_with` and `state.age_seconds`) instead of hanging silently
+  inside the scripting bridge. Stale registrations from crashed operations
+  are ignored automatically; an operation never gates its own thread.
+- Design decisions recorded: single-editor/multi-client is the supported
+  concurrency target; confirm tokens stay per-instance; actor identity is
+  deferred to the governance phase.
+
 ## What's New in v2.37.3
 
 Deep-audit fixes, rounds two and three: agent-facing action discovery,

package/README.md

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

package/install.py

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

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.37.3"
+VERSION = "2.38.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.37.3"
+VERSION = "2.38.0"
 
 import base64
 import os
@@ -84,6 +84,8 @@ from src.utils.media_analysis import (
     summarize_reports as summarize_media_analysis_reports,
 )
 from src.utils.sync_detection import detect_sync_events_for_records as detect_media_sync_events
+from src.utils import resolve_busy
+from src.utils.resolve_busy import long_resolve_op
 from src.utils.media_analysis_jobs import (
     MEDIA_EXTENSIONS,
     batch_job_status as media_analysis_batch_job_status,
@@ -830,6 +832,7 @@ ERROR_CATEGORIES = (
     "wrong_page",            # action requires a specific page (Color, Edit, Fairlight…)
     "invalid_input",         # caller-side fixable (bad param shape, unknown enum)
     "resolve_api_failed",    # Resolve returned None/False for unclear reasons
+    "busy",                  # another long Resolve op holds the bridge; retry later
     "destructive_blocked",   # strict-mode/confirm-token refusal
     "pending_user_decision", # confirm_token required
     "unsupported",           # feature/version/method not available
@@ -846,6 +849,7 @@ _CATEGORY_RETRYABLE_DEFAULT: Dict[str, bool] = {
     "wrong_page":            True,   # trivial caller fix; retry after page switch
     "invalid_input":         False,  # caller fix required
     "resolve_api_failed":    True,   # often transient; retry once
+    "busy":                  True,   # another long Resolve op holds the bridge
     "destructive_blocked":   False,  # user decision required
     "pending_user_decision": False,  # confirm_token required
     "unsupported":           False,  # API/version mismatch
@@ -1671,6 +1675,19 @@ def _annotation_boundary_report(tl, p: Dict[str, Any]):
     }
 
 def _check():
+    busy = resolve_busy.wait_until_free()
+    if busy:
+        return None, None, _err(
+            f"Resolve is busy with a long operation: {busy['label']} "
+            f"(running for {busy['age_seconds']}s). Retry after it completes.",
+            code="RESOLVE_BUSY", category="busy",
+            remediation="Wait for the named operation to finish, then retry this call.",
+            state={
+                "busy_with": busy["label"],
+                "age_seconds": busy["age_seconds"],
+                "same_process": busy["same_process"],
+            },
+        )
     resolve = get_resolve()
     if resolve is None:
         return None, None, _err(
@@ -4916,7 +4933,8 @@ def _export_timeline_checked(tl, p: Dict[str, Any]):
     spec = _timeline_export_spec(p, resolve)
     if p.get("dry_run"):
         return _ok(path=path, would_export=True, spec={k: v for k, v in spec.items() if k != "export_type"})
-    success = bool(tl.Export(path, spec["export_type"], spec["export_subtype"]))
+    with long_resolve_op("timeline.export_timeline_checked"):
+        success = bool(tl.Export(path, spec["export_type"], spec["export_subtype"]))
     files = []
     primary_file = path
     if success and os.path.isdir(path):
@@ -4969,7 +4987,8 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
         tl_existing = proj.GetTimelineByIndex(index)
         if tl_existing:
             before_ids.add(str(tl_existing.GetUniqueId()))
-    imported = mp.ImportTimelineFromFile(path, options)
+    with long_resolve_op("timeline.import_timeline_checked"):
+        imported = mp.ImportTimelineFromFile(path, options)
     if not imported:
         return _err("Failed to import timeline")
     imported_id = str(imported.GetUniqueId())
@@ -5937,7 +5956,8 @@ def _subtitle_generation_probe(tl, p: Dict[str, Any]):
         return _ok(would_generate=True, settings=settings, note="Pass allow_generate=True to call CreateSubtitlesFromAudio.")
     if not _has_method(tl, "CreateSubtitlesFromAudio"):
         return _err("CreateSubtitlesFromAudio unavailable")
-    return {"success": bool(tl.CreateSubtitlesFromAudio(settings)), "settings": settings}
+    with long_resolve_op("timeline.create_subtitles_from_audio"):
+        return {"success": bool(tl.CreateSubtitlesFromAudio(settings)), "settings": settings}
 
 
 def _fairlight_boundary_report(proj, mp, tl, p: Dict[str, Any]):
@@ -13811,7 +13831,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     elif action == "setup_multicam_timeline":
         return _setup_multicam_timeline(proj, mp, p)
     elif action == "import_timeline":
-        tl = mp.ImportTimelineFromFile(p["path"], p.get("options", {}))
+        with long_resolve_op("media_pool.import_timeline"):
+            tl = mp.ImportTimelineFromFile(p["path"], p.get("options", {}))
         return _ok(name=tl.GetName()) if tl else _err("Failed to import timeline")
     elif action == "delete_timelines":
         count = proj.GetTimelineCount()
@@ -14021,8 +14042,10 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     elif action == "transcribe_audio":
         usd = _first_param(p, "use_speaker_detection", "useSpeakerDetection")
         if usd is None:
-            return {"success": bool(f.TranscribeAudio())}
-        return {"success": bool(f.TranscribeAudio(bool(usd)))}
+            with long_resolve_op("folder.transcribe_audio"):
+                return {"success": bool(f.TranscribeAudio())}
+        with long_resolve_op("folder.transcribe_audio"):
+            return {"success": bool(f.TranscribeAudio(bool(usd)))}
     elif action == "clear_transcription":
         return {"success": bool(f.ClearTranscription())}
     elif action == "perform_audio_classification":
@@ -14338,8 +14361,10 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "transcribe_audio":
         usd = _first_param(p, "use_speaker_detection", "useSpeakerDetection")
         if usd is None:
-            return {"success": bool(clip.TranscribeAudio())}
-        return {"success": bool(clip.TranscribeAudio(bool(usd)))}
+            with long_resolve_op("media_pool_item.transcribe_audio"):
+                return {"success": bool(clip.TranscribeAudio())}
+        with long_resolve_op("media_pool_item.transcribe_audio"):
+            return {"success": bool(clip.TranscribeAudio(bool(usd)))}
     elif action == "clear_transcription":
         return {"success": bool(clip.ClearTranscription())}
     elif action == "get_transcription":
@@ -15808,7 +15833,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "import_into_timeline":
         return {"success": bool(tl.ImportIntoTimeline(p["path"], p.get("options", {})))}
     elif action == "export":
-        return {"success": bool(tl.Export(p["path"], p["type"], p.get("subtype", "")))}
+        with long_resolve_op("timeline.export"):
+            return {"success": bool(tl.Export(p["path"], p["type"], p.get("subtype", "")))}
     elif action == "get_setting":
         return {"settings": _ser(tl.GetSetting(p.get("name", "")))}
     elif action == "set_setting":
@@ -16249,9 +16275,11 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         return err
 
     if action == "create_subtitles":
-        return {"success": bool(tl.CreateSubtitlesFromAudio(p.get("settings", {})))}
+        with long_resolve_op("timeline_ai.create_subtitles"):
+            return {"success": bool(tl.CreateSubtitlesFromAudio(p.get("settings", {})))}
     elif action == "detect_scene_cuts":
-        return {"success": bool(tl.DetectSceneCuts())}
+        with long_resolve_op("timeline_ai.detect_scene_cuts"):
+            return {"success": bool(tl.DetectSceneCuts())}
     elif action == "analyze_dolby_vision":
         clip_ids = p.get("clip_ids", [])
         items = []
@@ -16262,7 +16290,8 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                         if it.GetUniqueId() in clip_ids:
                             items.append(it)
         analysis_type = p.get("analysis_type")
-        return {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))}
+        with long_resolve_op("timeline_ai.analyze_dolby_vision"):
+            return {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))}
     elif action == "grab_still":
         still = tl.GrabStill()
         return _ok() if still else _err("Failed to grab still")

package/src/utils/resolve_busy.py

@@ -0,0 +1,171 @@
+"""Cross-process visibility for long synchronous DaVinci Resolve operations.
+
+The Resolve scripting bridge executes one call at a time. Most calls return in
+milliseconds, but a handful block for seconds-to-minutes (timeline export and
+import, scene-cut detection, subtitle generation, audio transcription). A
+second tool call issued during one of those — from another thread of this
+server, or from the other instance when stdio and networked servers share one
+Resolve — simply hangs inside fusionscript with no feedback.
+
+This module gives those long operations a name and a presence that every
+instance can see, so the Resolve preflight can wait briefly and then return a
+structured "busy" answer instead of hanging:
+
+    with long_resolve_op("timeline.export"):
+        tl.Export(...)
+
+    op = wait_until_free(timeout_seconds=5.0)   # None when free
+    if op:
+        ... return a RESOLVE_BUSY error naming op["label"] ...
+
+Registration is advisory and best-effort: a sidecar JSON file in the temp dir
+(same approach as page_lock) carries {label, pid, thread, started_at}. Records
+are ignored when their pid is dead or they exceed MAX_OP_AGE_SECONDS, so a
+crashed operation can never wedge the server. The registering thread is exempt
+from its own gate — long operations call Resolve helpers internally.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Optional
+
+_SIDECAR = os.path.join(tempfile.gettempdir(), "davinci_resolve_mcp_busy.json")
+# A long op that has run this long is presumed crashed/leaked and ignored.
+MAX_OP_AGE_SECONDS = 2 * 60 * 60
+# Default time a preflight will wait for the bridge to free up before
+# returning a busy error.
+DEFAULT_WAIT_SECONDS = 5.0
+_POLL_SECONDS = 0.25
+
+_lock = threading.Lock()
+_local_owner: Optional[int] = None  # thread ident of the in-process registrant
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+
+
+def _read_record() -> Optional[Dict[str, Any]]:
+    try:
+        with open(_SIDECAR, "r", encoding="utf-8") as handle:
+            record = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(record, dict) or not record.get("label"):
+        return None
+    started_at = record.get("started_at")
+    if not isinstance(started_at, (int, float)):
+        return None
+    if time.time() - started_at > MAX_OP_AGE_SECONDS:
+        return None
+    pid = record.get("pid")
+    if not isinstance(pid, int) or not _pid_alive(pid):
+        return None
+    return record
+
+
+def _write_record(record: Dict[str, Any]) -> None:
+    tmp_path = f"{_SIDECAR}.tmp-{os.getpid()}-{threading.get_ident()}"
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            json.dump(record, handle)
+        os.replace(tmp_path, _SIDECAR)
+    except OSError:
+        pass
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+
+def _clear_record() -> None:
+    record = None
+    try:
+        with open(_SIDECAR, "r", encoding="utf-8") as handle:
+            record = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        pass
+    # Only the owning process removes the sidecar; never clobber another
+    # instance's registration.
+    if isinstance(record, dict) and record.get("pid") == os.getpid():
+        try:
+            os.remove(_SIDECAR)
+        except OSError:
+            pass
+
+
+def current_long_op() -> Optional[Dict[str, Any]]:
+    """The active long operation visible across instances, or None."""
+    record = _read_record()
+    if record is None:
+        return None
+    return {
+        "label": record.get("label"),
+        "pid": record.get("pid"),
+        "same_process": record.get("pid") == os.getpid(),
+        "started_at": record.get("started_at"),
+        "age_seconds": round(max(0.0, time.time() - float(record.get("started_at", 0.0))), 1),
+    }
+
+
+@contextmanager
+def long_resolve_op(label: str):
+    """Register a long synchronous Resolve call for its duration."""
+    global _local_owner
+    ident = threading.get_ident()
+    with _lock:
+        nested = _local_owner is not None
+        if not nested:
+            _local_owner = ident
+    if not nested:
+        _write_record({
+            "label": str(label),
+            "pid": os.getpid(),
+            "thread": ident,
+            "started_at": time.time(),
+        })
+    try:
+        yield
+    finally:
+        if not nested:
+            with _lock:
+                _local_owner = None
+            _clear_record()
+
+
+def wait_until_free(timeout_seconds: Optional[float] = None) -> Optional[Dict[str, Any]]:
+    """Wait briefly for any long op to finish.
+
+    Returns None when the bridge is free (or becomes free within the timeout),
+    otherwise the still-running operation's info. The thread that registered
+    the current in-process op is never gated by it. timeout_seconds defaults
+    to DEFAULT_WAIT_SECONDS, read at call time so callers/tests can tune it.
+    """
+    if timeout_seconds is None:
+        timeout_seconds = DEFAULT_WAIT_SECONDS
+    deadline = time.monotonic() + max(0.0, float(timeout_seconds))
+    while True:
+        op = current_long_op()
+        if op is None:
+            return None
+        if op["same_process"]:
+            record = _read_record() or {}
+            if record.get("thread") == threading.get_ident():
+                return None
+        if time.monotonic() >= deadline:
+            return op
+        time.sleep(_POLL_SECONDS)