davinci-resolve-mcp 2.26.0 → 2.26.1

package/AGENTS.md

@@ -93,7 +93,9 @@ venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
 ```
 
-Python 3.10-3.12 is recommended for Resolve scripting compatibility.
+Python 3.10+ is required (the MCP SDK floor). 3.10-3.12 is the lowest-risk range
+for Resolve scripting; 3.13/3.14 are accepted and verified on Resolve Studio
+20.3.2, but older Resolve builds may fail to connect on 3.13+.
 
 ## Development Notes
 

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.26.1
+
+**Python 3.13 / 3.14 support (issue #45)** — `npx davinci-resolve-mcp setup`
+previously hard-refused any interpreter outside 3.10–3.12, so it failed outright
+on Python 3.14. The 3.12 ceiling was based on a stale assumption that Resolve's
+scripting bridge has ABI incompatibilities on 3.13+. Verified empirically against
+DaVinci Resolve Studio 20.3.2.9: Python 3.14.4 connects and exercises the
+dict/list marshalling paths cleanly. The launcher and installer now enforce only
+the 3.10 floor (the `mcp[cli]` SDK requirement) with no upper cap. Python 3.13/3.14
+are accepted with a soft heads-up; `setup`/`doctor` surface a precise,
+connection-aware hint only when Resolve is running but the bridge returns no
+connection on 3.13+. Sub-3.10 interpreters get an actionable error instead of a
+dead end. `server.py` warns (never exits) on 3.13+. Adds 6 version-gate unit tests.
+
 ## What's New in v2.26.0
 
 **Fusion group-settings helpers** — Three new `fusion_comp` actions for

package/README.md

@@ -1,12 +1,12 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.26.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.26.1-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-32%20(329%20full)-blue.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
-[![Python](https://img.shields.io/badge/python-3.10--3.12-green.svg)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.
@@ -133,7 +133,7 @@ Extension authoring references live in [docs/authoring](docs/authoring/). Resolv
 ## Requirements
 
 - DaVinci Resolve Studio 18.5+ on macOS, Windows, or Linux. The free edition does not support external scripting.
-- Python 3.10-3.12 recommended. Python 3.13+ may have ABI incompatibilities with Resolve's scripting library.
+- Python 3.10+ (3.10-3.12 is the lowest-risk range). Python 3.13/3.14 also work on recent Resolve builds (verified on Studio 20.3.2); older builds may fail to connect on 3.13+, in which case use 3.10-3.12.
 - Resolve external scripting set to **Local**.
 
 Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21 beta APIs are intentionally deferred until stable.

package/bin/davinci-resolve-mcp.mjs

@@ -11,6 +11,16 @@ const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
 const VERSION = readPackageVersion();
 const MANAGED_MARKER = ".davinci-resolve-mcp-managed.json";
 
+// The only hard Python floor is the MCP SDK: mcp[cli] requires 3.10+.
+// We do NOT cap the upper bound. Resolve's scripting bridge (fusionscript)
+// loads cleanly into newer interpreters on recent builds — Python 3.14 is
+// verified working against Resolve Studio 20.3.2. Older Resolve builds may
+// fail to connect on 3.13+, but the version number is a poor proxy for that;
+// the connection check in `setup`/`doctor` is the real signal, so we proceed
+// with a soft heads-up rather than refusing to run.
+const PY_MIN_MINOR = 10;
+const PY_ABI_RISK_MINOR = 13;
+
 const SYNC_ITEMS = [
   "bin",
   "src",
@@ -54,7 +64,8 @@ Examples:
 
 Environment:
   DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
-  DAVINCI_RESOLVE_MCP_PYTHON         Python executable to use.
+  DAVINCI_RESOLVE_MCP_PYTHON         Python executable to use (3.10+). Set this to
+                                     pin a specific interpreter, e.g. python3.12.
   PYTHON                             Fallback Python executable to use.
 `;
 }
@@ -193,17 +204,24 @@ function pythonCandidates() {
   if (explicit) {
     candidates.push(explicit);
   }
+  // Prefer the lowest-ABI-risk interpreters first, then newer ones, then the
+  // generic launchers. All 3.10+ are accepted; ordering just picks the safest
+  // when several are installed.
   if (process.platform === "win32" && commandExists("py")) {
     candidates.push(
       { command: "py", args: ["-3.12"] },
       { command: "py", args: ["-3.11"] },
-      { command: "py", args: ["-3.10"] }
+      { command: "py", args: ["-3.10"] },
+      { command: "py", args: ["-3.13"] },
+      { command: "py", args: ["-3.14"] }
     );
   }
   candidates.push(
     { command: "python3.12", args: [] },
     { command: "python3.11", args: [] },
     { command: "python3.10", args: [] },
+    { command: "python3.13", args: [] },
+    { command: "python3.14", args: [] },
     { command: "python3", args: [] },
     { command: "python", args: [] }
   );
@@ -224,8 +242,9 @@ function checkPython(candidate) {
   }
   try {
     const info = JSON.parse(result.stdout.trim());
-    const supported = info.major === 3 && info.minor >= 10 && info.minor <= 12;
-    return { ...candidate, ...info, supported };
+    const supported = info.major === 3 && info.minor >= PY_MIN_MINOR;
+    const abiRisk = info.major === 3 && info.minor >= PY_ABI_RISK_MINOR;
+    return { ...candidate, ...info, supported, abiRisk };
   } catch {
     return null;
   }
@@ -244,8 +263,40 @@ function findSupportedPython() {
     }
   }
 
-  const suffix = checked.length ? ` Found: ${checked.join(", ")}.` : "";
-  throw new Error(`Python 3.10-3.12 is required for Resolve scripting compatibility.${suffix}`);
+  throw new Error(unsupportedPythonMessage(checked));
+}
+
+// Print the 3.13+ heads-up for run modes that never invoke install.py
+// (server/control-panel/batch). setup/doctor stay quiet here because
+// install.py emits a richer, connection-aware note of its own.
+function maybeWarnAbiRisk(info) {
+  if (info && info.abiRisk) {
+    console.warn(abiRiskNote(info));
+  }
+}
+
+function abiRiskNote(info) {
+  return (
+    `Note: using Python ${info.major}.${info.minor}.${info.micro}. ` +
+    `This is verified working on recent Resolve builds (Studio 20.3.2). ` +
+    `If Resolve fails to connect (scriptapp("Resolve") returns None), install ` +
+    `Python 3.10-3.12 and pin it with DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12.`
+  );
+}
+
+function unsupportedPythonMessage(checked) {
+  const found = checked.length ? ` Found: ${checked.join(", ")}.` : "";
+  const lines = [
+    `Python 3.${PY_MIN_MINOR} or newer is required (the MCP SDK needs Python 3.${PY_MIN_MINOR}+).${found}`,
+    "",
+    "How to fix:",
+    "  - Install Python 3.12 (the lowest-risk version for Resolve), e.g.:",
+    "      macOS:   brew install python@3.12   (or: pyenv install 3.12)",
+    "      Linux:   pyenv install 3.12          (or your distro's python3.12 package)",
+    "      Windows: install Python 3.12 from python.org",
+    `  - Point the launcher at it:  DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12 npx ${APP_NAME} setup`,
+  ];
+  return lines.join("\n");
 }
 
 function venvPython(root) {
@@ -258,7 +309,10 @@ function venvPython(root) {
   }
   const info = checkPython({ command: executable, args: [] });
   if (!info || !info.supported) {
-    throw new Error(`Managed venv Python must be 3.10-3.12. Re-run setup to recreate it: ${executable}`);
+    throw new Error(
+      `Managed venv Python must be 3.${PY_MIN_MINOR} or newer. ` +
+        `Re-run setup to recreate it: ${executable}`
+    );
   }
   return info;
 }
@@ -326,6 +380,7 @@ function commandDoctor(args) {
 function commandServer(args) {
   const root = syncManagedInstall(installRoot());
   const python = venvPython(root) || findSupportedPython();
+  maybeWarnAbiRisk(python);
   const serverScript = path.join(root, "src", "server.py");
   const [command, ...commandArgs] = pythonCommandLine(python, [serverScript, ...args]);
   run(command, commandArgs, { cwd: root });
@@ -334,6 +389,7 @@ function commandServer(args) {
 function commandControlPanel(args) {
   const root = syncManagedInstall(installRoot());
   const python = venvPython(root) || findSupportedPython();
+  maybeWarnAbiRisk(python);
   const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.control_panel", ...args]);
   run(command, commandArgs, { cwd: root });
 }
@@ -341,6 +397,7 @@ function commandControlPanel(args) {
 function commandBatch(args) {
   const root = syncManagedInstall(installRoot());
   const python = venvPython(root) || findSupportedPython();
+  maybeWarnAbiRisk(python);
   const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.batch_cli", ...args]);
   run(command, commandArgs, { cwd: root });
 }

package/docs/SKILL.md

@@ -1247,9 +1247,13 @@ timeline item returns `False` in Resolve. Use `get_node_graph` without a
 if the Gallery panel is open in the Resolve UI on the Color page. Instruct the
 user to open it via Workspace menu if export fails.
 
-**Python version** — Resolve's scripting library works best with Python 3.10–3.12.
-Python 3.13+ may cause `scriptapp("Resolve")` to return `None` due to ABI
-incompatibilities.
+**Python version** — the only hard requirement is Python **3.10+** (the MCP SDK
+floor). There is no upper cap: 3.13/3.14 are accepted, and Python 3.14 is verified
+working against Resolve Studio 20.3.2. On *older* Resolve builds the scripting
+bridge may still fail to load on 3.13+ (`scriptapp("Resolve")` returns `None`);
+`setup`/`doctor` warn on 3.13+ and their connection check surfaces a real failure.
+If that happens, recreate the venv with Python 3.10–3.12 (the lowest-risk range).
+The running server only warns on 3.13+ rather than exiting.
 
 **Resolve version guards** — Resolve 20-specific actions return a clear
 `requires DaVinci Resolve 20.x+` error when called against older builds. Resolve

package/docs/install.md

@@ -5,9 +5,18 @@ This guide covers Resolve requirements, the universal installer, supported MCP c
 ## Requirements
 
 - **DaVinci Resolve Studio** 18.5+ (macOS, Windows, or Linux) — the free edition does not support external scripting
-- **Python 3.10–3.12** recommended (3.13+ may have ABI incompatibilities with Resolve's scripting library)
+- **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**
 
+> **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
+> *older* Resolve builds the scripting bridge may fail to load on 3.13+
+> (`scriptapp("Resolve")` returns `None`); setup's connection check will tell you
+> if that happens. If it does, install a 3.10–3.12 interpreter
+> (`brew install python@3.12`, `pyenv install 3.12`, or python.org on Windows) and
+> point the launcher at it with `DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12`.
+
 Validated live coverage is based on **DaVinci Resolve 19.1.3 Studio** for the original API surface, plus **DaVinci Resolve 20.3.2 Studio** for the Resolve 20.0-20.2.2 scripting additions. Resolve 21 beta APIs are intentionally deferred until a stable release.
 
 ## Quick Start

package/install.py

@@ -35,9 +35,14 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.26.0"
+VERSION = "2.26.1"
+# 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
+# may fail to connect on 3.13+, but the connection check is the real signal,
+# so we proceed with a heads-up rather than refusing to run.
 SUPPORTED_PYTHON_MIN = (3, 10)
-SUPPORTED_PYTHON_MAX = (3, 12)
+PYTHON_ABI_RISK_MIN = (3, 13)
 
 # ─── Colors (disabled on Windows cmd without ANSI support) ────────────────────
 
@@ -77,7 +82,12 @@ def platform_name():
 
 def is_supported_python_version(version):
     major, minor = version[:2]
-    return major == 3 and SUPPORTED_PYTHON_MIN[1] <= minor <= SUPPORTED_PYTHON_MAX[1]
+    return major == 3 and minor >= SUPPORTED_PYTHON_MIN[1]
+
+
+def is_abi_risk_python_version(version):
+    major, minor = version[:2]
+    return major == 3 and minor >= PYTHON_ABI_RISK_MIN[1]
 
 
 def format_python_version(version):
@@ -85,9 +95,38 @@ def format_python_version(version):
 
 
 def python_requirement_text():
+    return f"Python {SUPPORTED_PYTHON_MIN[0]}.{SUPPORTED_PYTHON_MIN[1]} or newer"
+
+
+_ABI_NOTE_PRINTED = False
+
+
+def print_abi_risk_note_once(version, label="Python"):
+    """Emit the 3.13+ heads-up at most once per installer run."""
+    global _ABI_NOTE_PRINTED
+    if _ABI_NOTE_PRINTED:
+        return
+    _ABI_NOTE_PRINTED = True
+    print(f"  {yellow(label + ':')} {python_abi_risk_note(version)}")
+
+
+def python_abi_risk_note(version):
+    return (
+        f"Using Python {format_python_version(version)}. Verified working on recent "
+        f"Resolve builds (Studio 20.3.2). If Resolve fails to connect "
+        f"(scriptapp(\"Resolve\") returns None), install Python 3.10-3.12 and re-run "
+        f"with it, e.g.: python3.12 install.py"
+    )
+
+
+def python_fix_hint():
     return (
-        f"Python {SUPPORTED_PYTHON_MIN[0]}.{SUPPORTED_PYTHON_MIN[1]}-"
-        f"{SUPPORTED_PYTHON_MAX[0]}.{SUPPORTED_PYTHON_MAX[1]}"
+        "  How to fix:\n"
+        "    - Install Python 3.12 (the lowest-risk version for Resolve), e.g.:\n"
+        "        macOS:   brew install python@3.12   (or: pyenv install 3.12)\n"
+        "        Linux:   pyenv install 3.12          (or your distro's python3.12 package)\n"
+        "        Windows: install Python 3.12 from python.org\n"
+        "    - Re-run with that interpreter, e.g.:  python3.12 install.py"
     )
 
 
@@ -120,10 +159,13 @@ def require_supported_python(python_path, label="Python"):
     if not is_supported_python_version(version):
         print(
             f"  {red(label + ':')} {python_requirement_text()} is required "
-            f"for Resolve scripting compatibility; found {format_python_version(version)} "
+            f"(the MCP SDK needs 3.10+); found {format_python_version(version)} "
             f"at {python_path}"
         )
+        print(python_fix_hint())
         sys.exit(1)
+    if is_abi_risk_python_version(version):
+        print_abi_risk_note_once(version, label)
     return version
 
 
@@ -132,10 +174,13 @@ def require_current_python(label="Python"):
     if not is_supported_python_version(version):
         print(
             f"  {red(label + ':')} {python_requirement_text()} is required "
-            f"for Resolve scripting compatibility; current interpreter is "
+            f"(the MCP SDK needs 3.10+); current interpreter is "
             f"{format_python_version(version)} at {sys.executable}"
         )
+        print(python_fix_hint())
         sys.exit(1)
+    if is_abi_risk_python_version(version):
+        print_abi_risk_note_once(version, label)
     return version
 
 # ─── Resolve Path Detection ──────────────────────────────────────────────────
@@ -1411,14 +1456,34 @@ def main():
 
     if api_path:
         success, message = verify_resolve_connection(python_path, api_path, lib_path)
+        try:
+            py_abi_risk = is_abi_risk_python_version(_version_for_python(python_path))
+        except Exception:
+            py_abi_risk = False
         if success:
             if "not running" in message.lower():
                 print(f"  API:       {green('Module loads OK')}")
-                print(f"  Resolve:   {yellow('Not running')} — start Resolve to use MCP tools")
+                # If Resolve IS running but the bridge still reported no connection
+                # on a 3.13+ interpreter, that is the ABI-mismatch signature.
+                if resolve_running and py_abi_risk:
+                    print(
+                        f"  Resolve:   {yellow('Running, but the scripting bridge returned no connection')}"
+                    )
+                    print(
+                        f"             This can happen on Python 3.13+ with older Resolve builds. "
+                        f"If MCP tools fail, recreate the venv with Python 3.10-3.12."
+                    )
+                else:
+                    print(f"  Resolve:   {yellow('Not running')} — start Resolve to use MCP tools")
             else:
                 print(f"  Connected: {green(message)}")
         else:
             print(f"  Verify:    {yellow(message)}")
+            if py_abi_risk:
+                print(
+                    f"             On Python 3.13+ this may be an ABI mismatch with Resolve's "
+                    f"scripting library — try Python 3.10-3.12 if it persists."
+                )
     else:
         print(f"  {yellow('Skipped')} — Resolve API path not detected")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.26.0",
+  "version": "2.26.1",
   "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.26.0"
+VERSION = "2.26.1"
 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 329-tool granular server instead
 """
 
-VERSION = "2.26.0"
+VERSION = "2.26.1"
 
 import base64
 import os
@@ -498,9 +498,10 @@ def prep_color_handoff(output_dir: str = "") -> str:
 _py_ver = sys.version_info[:2]
 if _py_ver >= (3, 13):
     logger.warning(
-        f"Python {_py_ver[0]}.{_py_ver[1]} detected. DaVinci Resolve's scripting API "
-        f"may not work with Python 3.13+. If scriptapp('Resolve') returns None, "
-        f"recreate the venv with Python 3.10-3.12."
+        f"Python {_py_ver[0]}.{_py_ver[1]} detected. This is verified working on recent "
+        f"Resolve builds (Studio 20.3.2), but older builds may not load the scripting "
+        f"bridge on 3.13+. If scriptapp('Resolve') returns None, recreate the venv with "
+        f"Python 3.10-3.12."
     )
 
 # ─── Resolve Connection (lazy) ───────────────────────────────────────────────