davinci-resolve-mcp 2.63.2 → 2.64.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 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.64.0
+
+Adds opt-in support for DaVinci Resolve's **Network** external-scripting mode
+(PR #91… correction: PR #94, by @double2tea), so the MCP can drive a Resolve
+instance addressed by IP — including a Resolve running on the same machine with
+`External scripting using = Network`. Contributed in PR #94 by @double2tea,
+with two additional connection sites hardened during adoption. Local mode is
+unchanged and remains the default.
+
+### Added
+
+- **Resolve Network scripting mode** — set `RESOLVE_SCRIPT_HOST` to the Resolve
+  host IP (`127.0.0.1` on the same machine) to route connections through
+  Resolve's explicit IP-targeted `scriptapp("Resolve", host, timeout)` overload.
+  `RESOLVE_SCRIPT_TIMEOUT` (positive finite seconds, default 5) bounds the
+  connection wait. When `RESOLVE_SCRIPT_HOST` is absent, the server uses the
+  one-argument Local discovery exactly as before. A shared `connect_resolve`
+  helper centralizes this behavior; the compound server, granular server,
+  analysis dashboard, `scripts/doctor.py`, and the installer's post-install
+  connection probe all route through it. The installer copies
+  `RESOLVE_SCRIPT_HOST`/`RESOLVE_SCRIPT_TIMEOUT` into generated client configs
+  when present in its environment.
+- **`doctor.py` Network flags** — `python3 scripts/doctor.py --resolve-host
+  <ip> [--resolve-timeout <seconds>]` runs the read-only connection check
+  against a Network-mode host.
+
+### Security
+
+- Network scripting permits remote control of Resolve. Documentation (SKILL.md,
+  install.md) advises using Local mode when remote access is unnecessary, and
+  otherwise restricting access with host firewall and network controls.
+
+### Validation
+
+- Live-validated on DaVinci Resolve Studio 19.1.3.7: Local mode (one-argument
+  discovery) and Network mode (`--resolve-host 127.0.0.1 --resolve-timeout 8`)
+  both connect through the shared `connect_resolve` helper. PR author validated
+  against Studio 20.3.2.9 in Network mode. Full offline suite: 1514 tests.
+
 ## What's New in v2.63.2
 
 Installer fix for Windows MSIX builds of Claude Desktop (issue #93, reported by

package/README.md

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

package/docs/SKILL.md

@@ -14,8 +14,14 @@ session — projects, timelines, clips, color grading, Fusion compositions, audi
 render queues, and more — through natural language.
 
 DaVinci Resolve must be running with **Preferences > General > "External scripting
-using"** set to **Local**. The server auto-launches Resolve if it is not running,
-but that first connection can take up to 60 seconds.
+using"** set to **Local**, or set to **Network** with `RESOLVE_SCRIPT_HOST`
+configured to the Resolve host IP (use `127.0.0.1` on the same machine). The
+server auto-launches Resolve if it is not running, but that first connection can
+take up to 60 seconds.
+
+Network scripting permits remote control of Resolve. Use Local mode when remote
+access is unnecessary; otherwise restrict access with host firewall and network
+controls.
 
 **Session-start update note.** The first `resolve_control(action="get_version")`
 of a session returns an `mcp` block with the cached update check

package/docs/install.md

@@ -7,7 +7,9 @@ This guide covers Resolve requirements, the universal installer, supported MCP c
 - **DaVinci Resolve Studio** 18.5+ (macOS, Windows, or Linux) — the free edition does not support external scripting
 - **Python 3.10+** (the MCP SDK requires 3.10). **3.10–3.12 is the lowest-risk
   choice**; 3.13/3.14 also work on recent Resolve builds — see below
-- DaVinci Resolve running with **Preferences > General > "External scripting using"** set to **Local**
+- DaVinci Resolve running with **Preferences > General > "External scripting using"**
+  set to **Local**, or **Network** with `RESOLVE_SCRIPT_HOST` set to the Resolve
+  host IP (`127.0.0.1` when Resolve and the MCP run on the same machine)
 
 > **Python 3.13 / 3.14:** these are **allowed** — setup will use them and warn.
 > Python 3.14 is verified working against DaVinci Resolve Studio 20.3.2. On
@@ -170,6 +172,26 @@ If you prefer to set things up yourself, add to your MCP client config:
 
 On Windows, installer-generated configs also include `PYTHONHOME`. That scopes Resolve's Python binding to the selected interpreter and avoids the Resolve 20.3 multi-Python crash reported in [Issue #26](https://github.com/samuelgursky/davinci-resolve-mcp/issues/26).
 
+For Resolve's **Network** scripting mode, add
+`"RESOLVE_SCRIPT_HOST": "127.0.0.1"` to the `env` object above, replacing the
+address when Resolve runs on another host. When this variable is present, the
+server uses Resolve's explicit IP-targeted `scriptapp` call with a bounded
+connection timeout. Set `RESOLVE_SCRIPT_TIMEOUT` to override the default
+five-second timeout with a positive finite number of seconds. The installer
+includes both values in generated client configs when they are present in its
+environment.
+
+Network scripting permits remote control of Resolve. Prefer Local mode when
+remote access is unnecessary; otherwise restrict access with host firewall and
+network controls.
+
+Run the read-only doctor against Network mode explicitly:
+
+```bash
+python3 scripts/doctor.py --resolve-host 127.0.0.1
+python3 scripts/doctor.py --resolve-host resolve.example.test --resolve-timeout 12.5
+```
+
 When the compound server is running, `resolve_control(action="get_version")`
 includes the local MCP version, the last update-check status, and the current
 update decision under the `mcp` key. `resolve_control(action="mcp_update_status",

package/install.py

@@ -15,6 +15,7 @@ Usage:
 
 import argparse
 import json
+import math
 import os
 import platform
 import shutil
@@ -35,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.63.2"
+VERSION = "2.64.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
@@ -474,6 +475,13 @@ def build_server_env(python_path, api_path, lib_path, system=SYSTEM, python_home
     if system == "Windows":
         env["PYTHONHOME"] = str(python_home or get_python_base_install(python_path))
 
+    host = os.environ.get("RESOLVE_SCRIPT_HOST")
+    if host:
+        env["RESOLVE_SCRIPT_HOST"] = host
+        timeout = os.environ.get("RESOLVE_SCRIPT_TIMEOUT")
+        if timeout:
+            env["RESOLVE_SCRIPT_TIMEOUT"] = timeout
+
     return env
 
 
@@ -810,12 +818,21 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
     env = {**os.environ, **build_server_env(python_path, api_path, lib_path)}
     modules_path = env["PYTHONPATH"]
+    repo_root = str(Path(__file__).resolve().parent)
+    # Route through connect_resolve so Network mode (RESOLVE_SCRIPT_HOST, propagated
+    # into env by build_server_env) uses the explicit IP-targeted overload. Fall
+    # back to Local-mode discovery if the helper cannot be imported.
     test_script = textwrap.dedent(f"""\
         import sys
         sys.path.insert(0, {modules_path!r})
+        sys.path.insert(0, {repo_root!r})
         try:
             import DaVinciResolveScript as dvr
-            resolve = dvr.scriptapp('Resolve')
+            try:
+                from src.utils.resolve_connection import connect_resolve
+            except Exception:
+                connect_resolve = lambda mod: mod.scriptapp('Resolve')
+            resolve = connect_resolve(dvr)
             if resolve:
                 name = resolve.GetProductName()
                 ver = resolve.GetVersionString()
@@ -828,12 +845,22 @@ def verify_resolve_connection(python_path, api_path, lib_path):
             print(f"ERROR: {{e}}")
     """)
 
+    process_timeout = 10.0
+    configured_timeout = env.get("RESOLVE_SCRIPT_TIMEOUT")
+    if configured_timeout:
+        try:
+            network_timeout = float(configured_timeout)
+            if math.isfinite(network_timeout) and network_timeout > 0:
+                process_timeout = max(process_timeout, network_timeout + 2)
+        except ValueError:
+            pass
+
     try:
         result = subprocess.run(
             [str(python_path), "-c", test_script],
             capture_output=True,
             text=True,
-            timeout=10,
+            timeout=process_timeout,
             env=env,
         )
         output = result.stdout.strip() or result.stderr.strip()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.63.2",
+  "version": "2.64.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/doctor.py

@@ -7,16 +7,19 @@ mutating anything. Prints OK/WARN/FAIL lines (or JSON with --json) and exits
 nonzero only when a FAIL is present.
 
 Run: `python3 scripts/doctor.py`
+Network mode: `python3 scripts/doctor.py --resolve-host 127.0.0.1`
 
 Overridable via environment: DAVINCI_MCP_REPO, DAVINCI_MCP_PYTHON,
 CODEX_HOME, CLAUDE_DESKTOP_CONFIG, RESOLVE_APP, RESOLVE_SCRIPT_API,
-RESOLVE_SCRIPT_MODULES, RESOLVE_SCRIPT_LIB.
+RESOLVE_SCRIPT_MODULES, RESOLVE_SCRIPT_LIB, RESOLVE_SCRIPT_HOST,
+RESOLVE_SCRIPT_TIMEOUT.
 """
 
 from __future__ import annotations
 
 import argparse
 import json
+import math
 import os
 import re
 import subprocess
@@ -128,26 +131,41 @@ def git_head() -> str:
     return head["stdout"] or head["stderr"] or "git describe produced no output"
 
 
-def resolve_probe() -> dict[str, Any]:
+def resolve_probe(
+    resolve_host: str | None = None,
+    resolve_timeout: float | None = None,
+) -> dict[str, Any]:
     if not PYTHON.exists():
         return {"import_ok": False, "error": f"{PYTHON} is missing"}
 
     code = f"""
 import json
 import sys
+sys.path.insert(0, {str(REPO)!r})
 sys.path.insert(0, {str(RESOLVE_MODULES)!r})
 try:
     import DaVinciResolveScript as dvr
-    resolve = dvr.scriptapp("Resolve")
-    payload = {{
-        "import_ok": True,
-        "module": getattr(dvr, "__file__", None),
-        "resolve_connected": bool(resolve),
-        "product": resolve.GetProductName() if resolve else None,
-        "version": resolve.GetVersionString() if resolve else None,
-    }}
+    from src.utils.resolve_connection import connect_resolve
 except Exception as exc:
     payload = {{"import_ok": False, "error": repr(exc)}}
+else:
+    try:
+        resolve = connect_resolve(dvr)
+    except Exception as exc:
+        payload = {{
+            "import_ok": True,
+            "module": getattr(dvr, "__file__", None),
+            "resolve_connected": False,
+            "connection_error": repr(exc),
+        }}
+    else:
+        payload = {{
+            "import_ok": True,
+            "module": getattr(dvr, "__file__", None),
+            "resolve_connected": bool(resolve),
+            "product": resolve.GetProductName() if resolve else None,
+            "version": resolve.GetVersionString() if resolve else None,
+        }}
 print(json.dumps(payload))
 """
     env = {
@@ -156,7 +174,26 @@ print(json.dumps(payload))
         "RESOLVE_SCRIPT_LIB": str(RESOLVE_LIB),
         "PYTHONPATH": str(RESOLVE_MODULES),
     }
-    proc = subprocess.run([str(PYTHON), "-c", code], capture_output=True, text=True, timeout=12, env=env)
+    if resolve_host is not None:
+        env["RESOLVE_SCRIPT_HOST"] = resolve_host
+    if resolve_timeout is not None:
+        env["RESOLVE_SCRIPT_TIMEOUT"] = str(resolve_timeout)
+    process_timeout = 12.0
+    configured_timeout = env.get("RESOLVE_SCRIPT_TIMEOUT")
+    if configured_timeout:
+        try:
+            network_timeout = float(configured_timeout)
+            if math.isfinite(network_timeout) and network_timeout > 0:
+                process_timeout = max(process_timeout, network_timeout + 2)
+        except ValueError:
+            pass
+    proc = subprocess.run(
+        [str(PYTHON), "-c", code],
+        capture_output=True,
+        text=True,
+        timeout=process_timeout,
+        env=env,
+    )
     output = (proc.stdout or proc.stderr).strip()
     try:
         payload = json.loads(output)
@@ -166,7 +203,10 @@ print(json.dumps(payload))
     return payload
 
 
-def collect() -> list[dict[str, str]]:
+def collect(
+    resolve_host: str | None = None,
+    resolve_timeout: float | None = None,
+) -> list[dict[str, str]]:
     results: list[dict[str, str]] = []
 
     check(results, "OK" if REPO.exists() else "FAIL", "MCP checkout", str(REPO))
@@ -186,18 +226,27 @@ def collect() -> list[dict[str, str]]:
     pyver = run([str(PYTHON), "--version"]) if PYTHON.exists() else {"ok": False, "stdout": "", "stderr": "missing"}
     check(results, "OK" if pyver["ok"] else "FAIL", "Python version", pyver["stdout"] or pyver["stderr"])
 
-    probe = resolve_probe()
+    probe = resolve_probe(resolve_host, resolve_timeout)
     if probe.get("import_ok"):
         check(results, "OK", "DaVinciResolveScript import", str(probe.get("module")))
         if probe.get("resolve_connected"):
             detail = f"{probe.get('product')} {probe.get('version')}"
             check(results, "OK", "Resolve scripting connection", detail)
+        elif probe.get("connection_error"):
+            check(
+                results,
+                "FAIL",
+                "Resolve scripting connection",
+                str(probe["connection_error"]),
+            )
         else:
             check(
                 results,
                 "WARN",
                 "Resolve scripting connection",
-                'Module import worked, but scriptapp("Resolve") returned no object. Open DaVinci Resolve Studio, set Preferences > General > External scripting using = Local, and restart Resolve.',
+                "Module import worked, but scriptapp returned no object. Use "
+                "External scripting = Local, or Network with --resolve-host "
+                "set to the Resolve host IP, then restart Resolve.",
             )
     else:
         check(results, "FAIL", "DaVinciResolveScript import", str(probe.get("error")))
@@ -211,9 +260,18 @@ def collect() -> list[dict[str, str]]:
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--json", action="store_true", help="Print machine-readable JSON")
+    parser.add_argument(
+        "--resolve-host",
+        help="Resolve host IP for Network scripting mode",
+    )
+    parser.add_argument(
+        "--resolve-timeout",
+        type=float,
+        help="Network connection timeout in seconds (default: 5)",
+    )
     args = parser.parse_args()
 
-    results = collect()
+    results = collect(args.resolve_host, args.resolve_timeout)
     if args.json:
         print(json.dumps({"checks": results}, indent=2))
     else:

package/src/analysis_dashboard.py

@@ -44,6 +44,7 @@ from src.utils.media_analysis_jobs import (
     run_batch_job_slice,
 )
 from src.utils.platform import setup_environment
+from src.utils.resolve_connection import connect_resolve
 from src.utils.analysis_memory import read_panel_state, write_panel_state
 from src.utils import brain_edits as _brain_edits
 from src.utils import timeline_versioning as _timeline_versioning
@@ -11838,7 +11839,7 @@ def _connect_resolve_read_only() -> Tuple[Any, Optional[str]]:
         except Exception as exc:
             return None, f"Resolve scripting API unavailable: {exc}"
         try:
-            resolve = dvr_script.scriptapp("Resolve")
+            resolve = connect_resolve(dvr_script)
         except Exception as exc:
             return None, f"Resolve connection failed: {exc}"
         if resolve is None:

package/src/granular/common.py

@@ -44,6 +44,7 @@ from src.utils.layout_presets import (
 )
 from src.utils.object_inspection import inspect_object, print_object_help
 from src.utils.platform import get_platform, get_resolve_paths
+from src.utils.resolve_connection import connect_resolve
 from src.utils.project_properties import (
     get_all_project_properties,
     get_color_settings,
@@ -80,7 +81,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.63.2"
+VERSION = "2.64.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -233,7 +234,7 @@ dvr_script = None
 try:
     import DaVinciResolveScript as dvr_script  # type: ignore
 
-    resolve = dvr_script.scriptapp("Resolve")
+    resolve = connect_resolve(dvr_script)
     if resolve:
         logger.info(
             f"Connected to DaVinci Resolve: {resolve.GetProductName()} {resolve.GetVersionString()}"
@@ -311,7 +312,7 @@ def _try_connect():
     """Attempt to connect to Resolve once. Returns resolve object or None."""
     global resolve
     try:
-        candidate = dvr_script.scriptapp("Resolve")
+        candidate = connect_resolve(dvr_script)
         if candidate and _is_resolve_handle_live(candidate):
             resolve = candidate
             logger.info(f"Connected: {resolve.GetProductName()} {resolve.GetVersionString()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.63.2"
+VERSION = "2.64.0"
 
 import base64
 import os
@@ -97,6 +97,7 @@ from src.utils.media_analysis_jobs import (
     run_batch_job_slice as run_media_analysis_batch_job_slice,
 )
 from src.utils.platform import get_resolve_paths, get_resolve_plugin_paths
+from src.utils.resolve_connection import connect_resolve
 from src.utils.lut_paths import master_lut_dir, ensure_lut_in_master
 from src.utils import fuse_templates, dctl_templates, script_templates
 from src.utils.timeline_title_text import (
@@ -804,7 +805,7 @@ def _try_connect():
         if dvr_script is None:
             return None
         try:
-            candidate = dvr_script.scriptapp("Resolve")
+            candidate = connect_resolve(dvr_script)
             if candidate and _is_resolve_handle_live(candidate):
                 resolve = candidate
                 logger.info(f"Connected: {resolve.GetProductName()} {resolve.GetVersionString()}")

package/src/utils/resolve_connection.py

@@ -3,35 +3,66 @@
 DaVinci Resolve Connection Utilities
 """
 
-import os
 import logging
+import math
+import os
+
 from .platform import get_platform, get_resolve_paths, setup_environment
 
 logger = logging.getLogger("davinci-resolve-mcp.connection")
 
+DEFAULT_RESOLVE_SCRIPT_TIMEOUT = 5.0
+
+
+def _network_timeout():
+    value = os.environ.get(
+        "RESOLVE_SCRIPT_TIMEOUT",
+        str(DEFAULT_RESOLVE_SCRIPT_TIMEOUT),
+    )
+    try:
+        timeout = float(value)
+    except ValueError as exc:
+        raise ValueError(
+            "RESOLVE_SCRIPT_TIMEOUT must be a positive finite number"
+        ) from exc
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError(
+            "RESOLVE_SCRIPT_TIMEOUT must be a positive finite number"
+        )
+    return timeout
+
+
+def connect_resolve(dvr_script):
+    """Create a Resolve handle, optionally targeting an explicit network host."""
+    host = os.environ.get("RESOLVE_SCRIPT_HOST")
+    if host:
+        return dvr_script.scriptapp("Resolve", host, _network_timeout())
+    return dvr_script.scriptapp("Resolve")
+
+
 def initialize_resolve():
     """Initialize connection to DaVinci Resolve application."""
     try:
         # Import the DaVinci Resolve scripting module
         import DaVinciResolveScript as dvr_script
-        
+
         # Get the resolve object
-        resolve = dvr_script.scriptapp("Resolve")
-        
+        resolve = connect_resolve(dvr_script)
+
         if resolve is None:
             logger.error("Failed to get Resolve object. Is DaVinci Resolve running?")
             return None
-        
+
         logger.info(f"Connected to DaVinci Resolve: {resolve.GetProductName()} {resolve.GetVersionString()}")
         return resolve
-    
+
     except ImportError:
         platform_name = get_platform()
         paths = get_resolve_paths()
-        
+
         logger.error("Failed to import DaVinciResolveScript. Check environment variables.")
         logger.error("RESOLVE_SCRIPT_API, RESOLVE_SCRIPT_LIB, and PYTHONPATH must be set correctly.")
-        
+
         if platform_name == 'darwin':
             logger.error("On macOS, typically:")
             logger.error(f'export RESOLVE_SCRIPT_API="{paths["api_path"]}"')
@@ -47,24 +78,25 @@ def initialize_resolve():
             logger.error(f'export RESOLVE_SCRIPT_API="{paths["api_path"]}"')
             logger.error(f'export RESOLVE_SCRIPT_LIB="{paths["lib_path"]}"')
             logger.error(f'export PYTHONPATH="$PYTHONPATH:{paths["modules_path"]}"')
-        
+
         return None
-    
+
     except Exception as e:
         logger.error(f"Unexpected error initializing Resolve: {str(e)}")
         return None
 
+
 def check_environment_variables():
     """Check if the required environment variables are set."""
     resolve_script_api = os.environ.get("RESOLVE_SCRIPT_API")
     resolve_script_lib = os.environ.get("RESOLVE_SCRIPT_LIB")
-    
+
     missing_vars = []
     if not resolve_script_api:
         missing_vars.append("RESOLVE_SCRIPT_API")
     if not resolve_script_lib:
         missing_vars.append("RESOLVE_SCRIPT_LIB")
-    
+
     return {
         "all_set": len(missing_vars) == 0,
         "missing": missing_vars,
@@ -72,6 +104,7 @@ def check_environment_variables():
         "resolve_script_lib": resolve_script_lib
     }
 
+
 def set_default_environment_variables():
     """Set the default environment variables based on platform."""
-    return setup_environment() 
+    return setup_environment()