davinci-resolve-mcp 2.25.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,58 @@
 
 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
+authoring and patching `GroupOperator` macros without leaving the kernel.
+`group_settings_export` writes a live group to a `.setting` file and returns a
+parsed `published_inputs` summary using a balanced-brace walker so nested
+`UserControls` / `ControlGroup` tables are bounded correctly (the original
+flat-regex parser truncated `InstanceInput` bodies at the first inner `}`).
+`group_settings_splice_inputs` replaces the `Inputs = ordered() { ... }` block
+of one `.setting` with the matching block from another, preserving the source's
+outer structure and inner `Tools`. `group_settings_load` applies a `.setting`
+to a live group with an automatic timestamped backup, wrapped in
+`StartUndo`/`Lock`/`LoadSettings`/`Unlock`/`EndUndo(True)` so Fusion's Ctrl+Z
+reverses the change — verified live via direct BMD API.
+
+**bulk_set_expressions** — Companion to the existing `bulk_set_inputs`. Batch
+attach Fusion expressions across many timeline-item comps in one call. Each op
+requires timeline scope plus `tool_name`, `input_name`, `expression`. Returns
+per-op `success`/`error` rows + `op_count`, matching the bulk-inputs contract.
+Useful for animating many controls at once (`time/30`, etc.) under a single
+chat turn.
+
+**Headless batch-runner CLI** — New
+`davinci-resolve-mcp batch <plan|run|status|list|resume|cancel>` subcommand
+drives `src/utils/media_analysis_jobs` from outside an MCP/chat client so long
+analysis batches can run via cron, CI, or terminal without holding a chat turn
+open. The orchestration loop and durable state stay in the existing jobs
+engine; the CLI only handles argv, progress streaming, and exit codes
+(`0` ok / `2` partial / `3` fatal / `130` Ctrl+C). JSON mode (`--json`)
+emits one record per progress event for log scraping. Closes #42.
+
+**Adapted from PR #40** — Group-settings work originated as a contribution
+from @RaincloudTheDragon; PR #43 retains the keepable parts (parser, exporter,
+splicer, loader, `bulk_set_expressions`) with a balanced-brace fix on the
+parser and an undo+lock wrap on `group_settings_load`. The two AMZ-specific
+templates and the static checklist from #40 were dropped as out-of-scope for a
+general kernel.
+
 ## What's New in v2.25.0
 
 **Agentic flow improvements** — A second-pass review against the Claude

package/README.md

@@ -1,12 +1,12 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.25.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",
@@ -41,6 +51,7 @@ Usage:
   davinci-resolve-mcp doctor [install.py options]
   davinci-resolve-mcp server [server.py options]
   davinci-resolve-mcp control-panel [control panel options]
+  davinci-resolve-mcp batch <plan|run|status|list|resume|cancel> [options]
   davinci-resolve-mcp --version
   davinci-resolve-mcp --help
 
@@ -48,10 +59,13 @@ Examples:
   npx davinci-resolve-mcp setup
   npx davinci-resolve-mcp setup --clients cursor,claude-desktop
   npx davinci-resolve-mcp doctor
+  npx davinci-resolve-mcp batch run /path/to/footage --depth standard
+  npx davinci-resolve-mcp batch run /path/to/footage --json > progress.log
 
 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.
 `;
 }
@@ -190,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: [] }
   );
@@ -221,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;
   }
@@ -241,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) {
@@ -255,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;
 }
@@ -323,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 });
@@ -331,10 +389,19 @@ 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 });
 }
 
+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 });
+}
+
 function main() {
   const argv = process.argv.slice(2);
   // No args → run the MCP stdio server. Anything printed to stdout would
@@ -366,6 +433,10 @@ function main() {
       commandControlPanel(args);
       return;
     }
+    if (command === "batch") {
+      commandBatch(args);
+      return;
+    }
 
     console.error(`Unknown command: ${command}\n`);
     console.error(usage());

package/docs/SKILL.md

@@ -923,6 +923,18 @@ Key actions:
 - `start_undo(name?)` / `end_undo(keep?)`
 - `bulk_set_inputs(ops)` — batch set inputs across multiple timeline item comps in
   one call; each op requires timeline scope plus `tool_name`, `input_name`, `value`
+- `bulk_set_expressions(ops)` — batch attach expressions across multiple timeline
+  item comps in one call; each op requires timeline scope plus `tool_name`,
+  `input_name`, `expression`
+- `group_settings_export(group_name, path, include_advisory?)` — write a
+  `GroupOperator` to disk and return a parsed published-input summary
+- `group_settings_splice_inputs(source_path, template_path, dest_path?, source_group_name?, template_group_name?)` —
+  replace one `.setting` file's `Inputs = ordered() { ... }` block with the
+  matching block from another, preserving inner tools and outer structure;
+  balanced-brace parser handles nested `UserControls`
+- `group_settings_load(group_name, settings_path, backup_path?, undo_name?)` —
+  apply a `.setting` to a live group with an auto backup and an undo wrap so
+  Ctrl+Z reverses the change
 
 Fusion Composition kernel actions (v2.12.0+) add safer graph inspection and
 mutation wrappers around the raw Fusion API:
@@ -1235,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/docs/kernels/fusion-composition-kernel.md

@@ -30,10 +30,40 @@ All actions are exposed through `fusion_comp`.
 | `safe_set_inputs` | Batch write inputs on one tool with optional readback classification. |
 | `safe_connect_tools` | Validate source/target tools before connecting a source output to a target input. |
 | `fusion_boundary_report` | Return graph capabilities plus a composition snapshot for the selected comp scope. |
+| `bulk_set_expressions` | Batch `SetExpression` across scoped timeline-item Fusion comps. Each op needs `tool_name`, `input_name`, `expression`, plus a timeline scope. Wraps each op in `StartUndo`/`EndUndo` + `comp.Lock`. |
+| `group_settings_export` | Save a named `GroupOperator`'s settings to a `.setting` file via `SaveSettings`, returning a parsed published-input summary. |
+| `group_settings_splice_inputs` | Replace the `Inputs = ordered() { ... }` block of `source_path` with the matching block from `template_path` and write `dest_path`. Read-only against Resolve; pure file operation. |
+| `group_settings_load` | Backup the current group state, then `LoadSettings` from a `.setting` file. Wrapped in `StartUndo`/`EndUndo` + `comp.Lock` so Fusion's Ctrl+Z can reverse it. Backup path is returned alongside any error. |
+| `probe_group_published_inputs` | Read live published `Input1..InputN` slots off a `GroupOperator`, optionally cross-referenced with a `.setting` file summary. |
 
 The pre-existing `bulk_set_inputs` action remains the batch path for applying
 input writes across multiple explicitly scoped timeline-item Fusion comps.
 
+### `group_settings_splice_inputs` notes
+
+The Fusion `.setting` format is a Lua-like nested structure: an InstanceInput
+commonly contains `UserControls = ordered() { Custom = { ... } }` tables, so any
+parsing that uses a flat regex will truncate bodies at the first inner `}`. This
+kernel uses balanced-brace scanning end-to-end. Practical implications:
+
+- The action only swaps the published `Inputs = ordered() { ... }` block. The
+  group's outer name, inner `Tools = ordered() { ... }` section, and surrounding
+  structure are preserved byte-for-byte.
+- You must provide the *new* layout as a real `.setting` file (typically
+  exported from a known-good group via `group_settings_export`). The kernel does
+  not ship hardcoded templates.
+- `template_group_name` is optional when the template file contains a single
+  `GroupOperator`; pass it when the template file contains multiple groups and
+  you want a specific one.
+
+### `group_settings_load` Edit-page caveat
+
+`LoadSettings` may update inner tool wiring but not refresh Edit-page
+`InstanceInput` order until the group is selected in Fusion and reloaded via UI.
+This is a Resolve quirk, not a kernel bug. The action always backs up the group
+to a timestamped sibling of `settings_path` first; the backup path is returned
+in success and in error responses.
+
 ## Scope Matrix
 
 | Scope | Probe Support | Mutation Support | Notes |

package/install.py

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