davinci-resolve-mcp 2.205.0 → 2.205.2

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 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.205.2 — #184: background analysis actually starts
+
+### Fixed
+
+- **`background=true` / `async_job=true` silently never ran.**
+  `start_batch_job` derived the runner's project root with
+  `str(plan["output_root"])`, but that field holds the *mapping*
+  `resolve_output_root()` returns, not a path. `str()` on it produced a dict
+  repr — and because that repr is a **non-empty** string it satisfied the
+  `if wants_runner and job_id and project_root` guard, so the runner was handed
+  a "directory" naming nothing on disk. It found no job store, returned
+  `job_not_found`, and the caller was told to go debug a job that existed and
+  was perfectly healthy. Reported and fixed in #184 by @turapins, who also
+  established that `batch_cli` and the analysis dashboard already read the
+  field as a mapping — `server.py` was the single consumer out of step, so the
+  fix belonged there rather than in the mapping's shape.
+
+## What's New in v2.205.1 — #182: the bridge preflight checks both halves of Resolve's Python lookup
+
+### Fixed
+
+- **A `PYTHON3HOME` prefix with a dylib but no `bin/python3` is no longer
+  reported as usable.** fusionscript.so does two things with the prefix — runs
+  `<prefix>/bin/python3` and dlopens `<prefix>/lib/libpython3.X.dylib`, whose
+  strings sit adjacent in the binary — and the preflight validated only the
+  second. It answered `python3_home.usable: true` and
+  `resolve_will_list_python_scripts: true` while Resolve listed **zero** Python
+  scripts and logged nothing, which is the worst shape this failure can take:
+  the user has been told the thing is configured correctly, so the real cause
+  is the last place they look. Reported in #182, with the root cause and the
+  fix both correct as filed.
+- **The interpreter has to be there under the unversioned name.** `python3` is
+  the literal name in the binary, and that is what makes this trap easy to hit:
+  a Homebrew framework prefix carries a perfectly good
+  `lib/libpython3.13.dylib` next to a `bin/` that has `python3.13` and no
+  `python3`. It is formula-dependent — `python@3.14` ships one, `python@3.11`
+  and `python@3.13` do not — so the same "Homebrew Python" advice works on one
+  machine and silently fails on the next. `framework_pythons()` has always
+  required `bin/python3`; this is the same rule applied to the route that
+  skipped it.
+- **A set-but-unusable `PYTHON3HOME` is now called out even when another
+  discovery route exists.** Resolve reads it first, and whether it falls back
+  after choosing a prefix it cannot use is inferred from string adjacency
+  rather than established — so resting a clean bill of health on a route
+  Resolve may never reach is the same false all-clear in a new place. The
+  preflight names the mismatch, prints the exact `ln -s` that repairs it, and
+  suggests `launchctl unsetenv` as the alternative.
+
+### Changed
+
+- **The advice says that `launchctl setenv` does not survive a reboot.** A
+  bridge that listed for weeks and then stopped, with no error anywhere, is
+  usually that, and nobody connects it back to a step they ran a month
+  earlier. `sudo ln -s "$(command -v python3)" /usr/local/bin/python3` is
+  offered as the persistent alternative, with the `PATH` caveat — presented
+  alongside the sudo-free route rather than replacing it, since avoiding a
+  system-wide install is the whole point of the #143 fix.
+
 ## What's New in v2.205.0 — a standard operation envelope on every tool result
 
 Adapted from the design contributed in PR #181.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.205.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.205.2-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-36%20(353%20full)-blue.svg)](#server-modes)
@@ -80,6 +80,20 @@ never sees your shell's environment. Restart Resolve afterwards. A Lua canary is
 installed alongside so you can tell "Python not detected" apart from a wrong
 folder.
 
+Two things that bite (#182). The prefix must contain **both**
+`lib/libpython3.X.dylib` and `bin/python3` under that exact **unversioned**
+name — Homebrew's framework builds often ship only `bin/python3.13`, which is
+half a Python as far as Resolve is concerned, and the installer's preflight now
+says so instead of reporting a usable prefix. And `launchctl setenv` **does not
+survive a reboot**; if scripts stop listing weeks later with no error, that is
+why. For something persistent, put an interpreter where Resolve already looks
+(this one needs `sudo`, and check that `/usr/local/bin` does not precede your
+normal Python on `PATH`):
+
+```bash
+sudo ln -s "$(command -v python3)" /usr/local/bin/python3
+```
+
 Validated on free 21.0.3.7 and Studio 19.1.3.7, both macOS. The Windows paths
 added in v2.70.1 (issue #106) shipped unverified; reports on free 21.0.1.11
 (issue #109) and free 21.0.3.7 (issue #112) have since shown the bridge

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.205.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.205.2-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-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![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)
 
-> 本翻译对应 v2.205.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.205.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -61,6 +61,12 @@ launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
 
 必须用 `launchctl setenv` 而不是 `export`——Resolve 从 Dock 启动，看不到你 shell 的环境变量。之后重启 Resolve。安装时会顺带装一个 Lua 金丝雀脚本，帮你区分"Python 未被检测到"和"目录放错"。
 
+有两个坑（#182）。前缀里必须**同时**有 `lib/libpython3.X.dylib` 和 `bin/python3`——而且是这个**不带版本号**的名字。Homebrew 的 framework 构建经常只提供 `bin/python3.13`，在 Resolve 眼里这只算半个 Python；安装器的预检现在会明说这一点，而不是报告前缀可用。另外，`launchctl setenv` **在重启后不会保留**；如果几周之后脚本又不列出来了且没有任何报错，通常就是这个原因。想要持久生效，就把解释器放到 Resolve 本来就会查的位置（这条需要 `sudo`，并且先确认 `/usr/local/bin` 没有排在你常用 Python 的 `PATH` 前面）：
+
+```bash
+sudo ln -s "$(command -v python3)" /usr/local/bin/python3
+```
+
 已在免费版 21.0.3.7 和 Studio 19.1.3.7 上验证（均为 macOS）。v2.70.1（issue #106）加入的 Windows 路径发布时未经验证；后续免费版 21.0.1.11（issue #109）和免费版 21.0.3.7（issue #112）的用户报告证实，Windows 11 上桥接在 `%PROGRAMDATA%` 和 `%APPDATA%` **两处**都能安装、列出并正常服务，这些路径现在是已证实而非假设。Linux 同样已获证实：免费版 20.3.2.9 的用户报告（issue #129，Fedora 43）显示桥接可安装到 `~/.local/share/DaVinciResolve/Fusion/Scripts/Utility`，用系统 Python 就能直接枚举脚本（Linux 完全没有这套查找问题），并能端到端正常服务。现在没有任何平台停留在假设上：macOS 为本项目直接验证，Windows 和 Linux 来自用户报告。
 
 注意：桥接在服务期间会一直占用端口。v2.70.3 之前，Windows 上的桥接可能在 Resolve 退出后存活，挡住下一个会话的监听器；如果你用的是旧版本且桥接不响应了，检查是否有残留的 `fuscript.exe` 还占着端口。

package/docs/SKILL.md

@@ -41,6 +41,14 @@ Existing tool call sites work unchanged. Two things to know when diagnosing it:
   canary, which always lists, so "Python not detected" is distinguishable from
   "wrong folder". The preflight is macOS-only — off macOS Resolve finds Python
   by other means, and running the check there was a false alarm (#106).
+  Two follow-ups from #182 worth having in hand when a user says the menu is
+  empty despite a set `PYTHON3HOME`: the prefix needs **both**
+  `lib/libpython3.X.dylib` and `bin/python3` under that **unversioned** name
+  (Homebrew framework builds often ship only `python3.X`, so half the check
+  passes on the very interpreter people reach for), and `launchctl setenv` does
+  not survive a reboot — a bridge that listed for weeks and then stopped, with
+  no error anywhere, is usually that. `sudo ln -s "$(command -v python3)"
+  /usr/local/bin/python3` is the persistent alternative.
 - **Windows: both script folders confirmed.** `%PROGRAMDATA%` (#109) and
   `%APPDATA%` (#112) have each been shown serving the bridge on Windows 11 free
   builds. If a user reports the menu entry missing on Windows, ask whether the

package/install.py

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

package/scripts/install_resolve_bridge.py

@@ -286,10 +286,14 @@ _LUA_CANARY = """-- Installed by davinci-resolve-mcp as an enumeration canary.
 -- Resolve is listing Lua and silently skipping Python: it cannot find a Python 3.
 -- It looks at PYTHON3HOME, then /usr/local/bin/python3 -- and nowhere else, which
 -- is why Homebrew, pyenv, uv and conda interpreters go unseen. Either point it at
--- the one you have (no sudo):
+-- the one you have (no sudo, but does NOT survive a reboot):
 --   launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
--- (launchctl, not export -- Resolve never sees your shell), or install a
--- python.org build, which creates /usr/local/bin/python3. Restart Resolve after.
+-- (launchctl, not export -- Resolve never sees your shell; and the prefix needs
+-- BOTH lib/libpython3.X.dylib and bin/python3 under that unversioned name --
+-- Homebrew framework builds often ship only python3.X), or put one where Resolve
+-- already looks, which persists:
+--   sudo ln -s "$(command -v python3)" /usr/local/bin/python3
+-- A python.org build creates that symlink for you. Restart Resolve after.
 print("Resolve is enumerating scripts. If the Python probe is missing, Resolve")
 print("cannot find a Python 3: set PYTHON3HOME with launchctl setenv, or install")
 print("a python.org build. Homebrew/pyenv/uv/conda are not looked at directly.")
@@ -335,12 +339,28 @@ def launchd_env(name: str) -> str | None:
 
 
 def python3_home_prefix() -> dict:
-    """Is PYTHON3HOME set for Resolve, and does it point at a loadable Python 3?
+    """Is PYTHON3HOME set for Resolve, and does it point at a usable Python 3?
 
-    "Loadable" means the `lib/libpython3.X.dylib` that fusionscript.so dlopens.
-    An interpreter that cannot supply one is reported as set-but-unusable rather
-    than counted, because the silent-non-enumeration symptom is identical and the
-    remedy is not.
+    Usable means BOTH halves of what fusionscript.so does with the prefix, whose
+    strings sit adjacent in the binary:
+
+        python3 -c 'import sys; ...sys.prefix...'   # run <prefix>/bin/python3
+        /libpython                                  # dlopen <prefix>/lib/libpython3.X.dylib
+
+    Checking only the dylib reported `usable: true` for a prefix Resolve cannot
+    run, and then Resolve listed zero Python scripts — the exact false all-clear
+    this function's docstring already warned about, since "the silent
+    non-enumeration symptom is identical and the remedy is not" (issue #182).
+
+    The interpreter must be there under the **unversioned** name. That is the
+    literal name in the binary, and it is what makes this trap so easy to hit:
+    a Homebrew framework prefix has `bin/python3.13` but no `bin/python3`
+    (formula-dependent — python@3.14 ships one, python@3.11 and python@3.13 do
+    not), while carrying a perfectly good `lib/libpython3.13.dylib`. Half the
+    check passes on exactly the interpreter most likely to be tried.
+
+    `framework_pythons()` has always required `bin/python3`; this is the same
+    rule applied to the route that skipped it.
     """
     value = launchd_env("PYTHON3HOME")
     result = {
@@ -348,20 +368,70 @@ def python3_home_prefix() -> dict:
         "in_launchd": value is not None,
         "in_this_shell": os.environ.get("PYTHON3HOME") or None,
         "dylib": None,
+        "interpreter": None,
+        "reason": None,
         "usable": False,
     }
     if not value:
         return result
+
+    prefix = Path(value)
     try:
-        dylibs = sorted(Path(value).glob("lib/libpython3.*.dylib"))
+        dylibs = sorted(prefix.glob("lib/libpython3.*.dylib"))
     except OSError:
         dylibs = []
+    interpreter = prefix / "bin" / "python3"
+    try:
+        # .exists() follows symlinks, so a dangling one reads as absent — which
+        # is what it is to a Resolve trying to execute it.
+        has_interpreter = interpreter.exists()
+    except OSError:
+        has_interpreter = False
+
     if dylibs:
         result["dylib"] = str(dylibs[0])
-        result["usable"] = True
+    if has_interpreter:
+        result["interpreter"] = str(interpreter)
+    result["usable"] = bool(dylibs) and has_interpreter
+
+    if result["usable"]:
+        return result
+    if dylibs and not has_interpreter:
+        versioned = sorted(
+            child.name for child in _safe_iterdir(prefix / "bin")
+            if child.name.startswith("python3.")
+            and not child.name.endswith("-config")
+        )
+        result["reason"] = (
+            f"{prefix}/lib has a libpython dylib but {interpreter} does not "
+            f"exist. Resolve runs the UNVERSIONED name `python3`"
+            + (f"; this prefix ships only {', '.join(versioned)}. " if versioned else ". ")
+            + "Homebrew framework builds are the common case. Either symlink it "
+            f"inside the prefix (ln -s {versioned[0] if versioned else 'python3.X'} "
+            f"{prefix}/bin/python3), or point PYTHON3HOME at a prefix that has both."
+        )
+    elif has_interpreter and not dylibs:
+        result["reason"] = (
+            f"{interpreter} exists but {prefix}/lib has no libpython3.X.dylib "
+            "for Resolve to dlopen. A static or non-shared build cannot be "
+            "embedded; point PYTHON3HOME at a prefix built with a shared library."
+        )
+    else:
+        result["reason"] = (
+            f"{prefix} has neither bin/python3 nor lib/libpython3.X.dylib. "
+            "Check the path — it should be a Python `sys.prefix`, which "
+            "`python3 -c 'import sys; print(sys.prefix)'` prints."
+        )
     return result
 
 
+def _safe_iterdir(directory: Path) -> list[Path]:
+    try:
+        return sorted(directory.iterdir())
+    except OSError:
+        return []
+
+
 def fallback_python3() -> dict:
     """`/usr/local/bin/python3` — the path baked into fusionscript.so.
 
@@ -414,7 +484,27 @@ def python_preflight() -> dict:
     # the order the binary's strings imply, and it is the one the user chose.
     found = home["usable"] or fallback["exists"] or bool(frameworks)
     advice = None
-    if not found:
+    if home["in_launchd"] and not home["usable"]:
+        # A set-but-broken PYTHON3HOME has to be said out loud even when another
+        # route exists. PYTHON3HOME is read FIRST, and whether Resolve falls
+        # back after choosing a prefix it cannot use is not established — the
+        # ordering here is inferred from string adjacency in fusionscript.so,
+        # not from decompiled control flow. Reporting a clean bill of health on
+        # the strength of a route Resolve may never reach is the failure this
+        # whole check exists to prevent (issue #182).
+        advice = (
+            "PYTHON3HOME is set for Resolve but does not point at a Python 3 it "
+            f"can use.\n{home['reason']}\n"
+            + ("Another discovery route is present on this machine, but Resolve "
+               "reads PYTHON3HOME first and it is NOT established that it falls "
+               "back after picking a prefix it cannot use. Fix the prefix or "
+               "unset it (launchctl unsetenv PYTHON3HOME) rather than relying "
+               "on the fallback.\n" if found else "")
+            + "Restart Resolve after changing it. The Lua canary installed "
+            "alongside lists regardless, so 'Python not detected' stays "
+            "distinguishable from 'wrong folder'."
+        )
+    elif not found:
         advice = (
             "Resolve cannot find a Python 3, so it will silently ignore every "
             ".py script in its Scripts folders — they will simply not appear in "
@@ -428,8 +518,16 @@ def python_preflight() -> dict:
             "print(sys.prefix)')\"\n"
             "     Use launchctl, NOT export — Resolve is launched from the Dock "
             "and never sees your shell's environment. The prefix must contain "
-            "lib/libpython3.X.dylib.\n"
-            "  2. Or install a python.org build, which creates "
+            "BOTH lib/libpython3.X.dylib and bin/python3 under that exact "
+            "unversioned name. Note that launchctl setenv does not survive a "
+            "reboot: if scripts stop listing weeks later with no error, this is "
+            "why.\n"
+            "  2. Or symlink an interpreter where Resolve already looks, which "
+            "is a file on disk and does persist (needs sudo):\n"
+            "       sudo ln -s \"$(command -v python3)\" /usr/local/bin/python3\n"
+            "     Check that /usr/local/bin does not precede your normal Python "
+            "on PATH before doing this.\n"
+            "  3. Or install a python.org build, which creates "
             "/usr/local/bin/python3 for you.\n"
             "Restart Resolve either way, then re-check. The Lua canary installed "
             "alongside will list regardless, so you can tell 'Python not "

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.205.0"
+VERSION = "2.205.2"
 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 353-tool granular server instead
 """
 
-VERSION = "2.205.0"
+VERSION = "2.205.2"
 
 import base64
 import os
@@ -9733,6 +9733,20 @@ def _media_analysis_bool(value: Any, default: bool = False) -> bool:
     return bool(value)
 
 
+def _media_analysis_plan_project_root(created: Any) -> str:
+    """Extract the project root path from a created batch job.
+
+    `plan["output_root"]` holds the mapping `resolve_output_root()` returns
+    ({"success", "base_root", "project_root", "project_directory", ...}), not a
+    path. `str()` on it yields a dict repr, which is a non-empty string and so
+    passes a truthiness guard while naming no directory that exists.
+    """
+    output_root = (created.get("plan") or {}).get("output_root") or ""
+    if isinstance(output_root, dict):
+        output_root = output_root.get("project_root") or ""
+    return str(output_root)
+
+
 MEDIA_ANALYSIS_ASYNC_QUEUED = "queued"
 MEDIA_ANALYSIS_ASYNC_RUNNING = "running"
 
@@ -22310,7 +22324,7 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         # get a runner. Reached either by the analyze_* divert (which sets
         # _async_mode) or by calling start_batch_job with background=true.
         job_id = str((created.get("job") or {}).get("job_id") or "")
-        project_root = str((created.get("plan") or {}).get("output_root") or "")
+        project_root = _media_analysis_plan_project_root(created)
         wants_runner = p.get("_async_mode") == MEDIA_ANALYSIS_ASYNC_RUNNING or (
             _media_analysis_bool(p.get("background"), False)
             or _media_analysis_bool(p.get("async_job"), False)