davinci-resolve-mcp 2.91.0 → 2.92.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 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.92.0
+
+Two corrections to advice this project was giving confidently and wrongly, both
+from issues filed by users who hit them.
+
+### Fixed
+
+- **`PYTHON3HOME` satisfies the macOS bridge preflight — uv/pixi/conda need no
+  `sudo`.** The preflight demanded a *framework* Python and sent everyone else
+  to a system-wide python.org install, which managed machines often forbid.
+  `uv`, `pixi` and conda-forge ship no `--enable-framework` build at all, so
+  their users got the warning no matter what they did. Reported by @rusanivsky
+  in #143, who had free Resolve 21.0.4.5 serving the bridge on uv-managed
+  CPython 3.12.13 with no python.org Python on the machine.
+
+  Framework-ness was never the variable. In `fusionscript.so` — read here on
+  Studio 19.1.3.7, a January 2025 binary — every `Python.framework` reference is
+  Python **2.7**, and there is no `Python.framework/Versions/3` string anywhere.
+  Python 3 is found through `PYTHON3HOME`, else `/usr/local/bin/python3`, then
+  probed for `sys.prefix` and dlopened as `<prefix>/lib/libpython3.X.dylib`.
+  python.org installs work because that installer creates
+  `/usr/local/bin/python3` — verified here, where it is a symlink into
+  `Python.framework/Versions/3.11`. Homebrew (`/opt/homebrew`), pyenv, uv and
+  conda land in neither place, which is the whole of the "framework Pythons
+  only" folklore.
+
+  The preflight now accepts either route and reports both. `PYTHON3HOME` is read
+  with `launchctl getenv`, never `os.environ`: Resolve is GUI-launched and
+  inherits launchd's environment, so reading our own shell would report a hit in
+  exactly the case that does not work. A `PYTHON3HOME` exported in the shell but
+  absent from launchd is called out, because it is the natural thing to try. The
+  old advice is corrected in the Lua canary, the `BRIDGE_UNAVAILABLE`
+  remediation, both READMEs and `docs/SKILL.md`.
+
+### Added
+
+- **Domain skills ask the build what it cannot do.** v2.89.0 taught
+  `get_version` to report a connected build's missing surfaces, but only the
+  session skill ever asked — an agent entering through
+  `/timeline_edit_workflow` or `/color_grade_workflow` got identical guidance
+  whatever it was attached to. That is the hole @magwa101 fell into on DR 21 in
+  #132. `resolve-edit`, `resolve-color`, `resolve-conform` and
+  `resolve-media-analysis` now name the gated surfaces in their own domain, with
+  the floor and what to do instead, sourced from `resolve_versions.VERSION_GATES`
+  rather than prose. Each section also has to say that an empty list means
+  nothing *recorded* is missing, that probes use `name in dir(obj)` and never
+  bare `hasattr` (which returns `True` for every name on a Resolve object), and
+  that *gated* is not *absent* — clip speed is unreachable on every build and no
+  upgrade will help.
+- `tests/test_skill_version_gates.py` fails when a skill quotes a floor the
+  ledger disagrees with. Confirmed it bites by mis-stating a floor and watching
+  it fail, not by trusting a green run.
+
+### Validation
+
+- Suite: 2621 passed, 1 skipped. Static checks and drift guards clean.
+- The binary strings and the `/usr/local/bin/python3` mechanism were confirmed
+  here on Studio 19.1.3.7. **Not reproduced here:** the live positive on free
+  21.0.4.5 with uv Python — that is the reporter's, and is labelled as such in
+  the code comment.
+- No Resolve scripting behavior changed; the bridge change is installer
+  preflight and advice text.
+
 ## What's New in v2.91.0
 
 A timeline item's source frames are counted in the **media's** frame rate, not

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.91.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.92.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(353%20full)-blue.svg)](#server-modes)
@@ -59,11 +59,21 @@ transport tried, so a bridge that stops answering reports its own fault rather
 than quietly falling back to another transport. Use it when the bridge is the
 path you intend to depend on.
 
-On **macOS**, this requires a **framework Python** (python.org). Resolve
-enumerates `.py` scripts only when it finds one — Homebrew, pyenv and conda
-interpreters are not detected, and the script silently never appears in the
-menu. A Lua canary is installed alongside so you can tell that apart from a
-wrong folder.
+On **macOS**, Resolve looks for Python 3 in exactly two places: the
+`PYTHON3HOME` environment variable, then `/usr/local/bin/python3`. Homebrew,
+pyenv, uv and conda land in neither, so the script silently never appears in the
+menu. A python.org install works because its installer creates
+`/usr/local/bin/python3` — but you do not need one: point Resolve at the
+interpreter you already have, no `sudo` required.
+
+```bash
+launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
+```
+
+Use `launchctl setenv`, not `export` — Resolve is launched from the Dock and
+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.
 
 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
@@ -72,7 +82,7 @@ installing, listing and serving from **both** `%PROGRAMDATA%` and `%APPDATA%` on
 Windows 11, so those paths are now confirmed rather than assumed. Linux is
 confirmed as well: a report on free 20.3.2.9 (issue #129, Fedora 43) shows the
 bridge installing to `~/.local/share/DaVinciResolve/Fusion/Scripts/Utility`,
-listing against the system Python — no framework-Python requirement on Linux —
+listing against the system Python — Linux has none of this discovery problem —
 and serving end-to-end. No platform now rests on an assumption: macOS was
 validated directly, Windows and Linux on user reports.
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.91.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.92.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(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.91.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.92.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -53,9 +53,15 @@ python scripts/install_resolve_bridge.py
 `DAVINCI_RESOLVE_BRIDGE=1` 则是*强制*走桥接：它会成为唯一尝试的传输方式，因此桥接一旦停止响应会
 直接报错，而不会悄悄回退到其他传输。当你明确要依赖桥接时使用它。
 
-在 **macOS** 上，这需要 **framework 版 Python**（python.org 官网安装包）。Resolve 只有找到 framework Python 才会枚举 `.py` 脚本——Homebrew、pyenv、conda 的解释器都不被识别，脚本会静默地不出现在菜单里。安装时会顺带装一个 Lua 金丝雀脚本，帮你区分"Python 不对"和"目录放错"。
+在 **macOS** 上，Resolve 只在两个位置查找 Python 3：环境变量 `PYTHON3HOME`，然后是 `/usr/local/bin/python3`。Homebrew、pyenv、uv、conda 都不装在这两处，因此脚本会静默地不出现在菜单里。python.org 安装包之所以有效，是因为它的安装程序会创建 `/usr/local/bin/python3`——但你并不需要它：直接把 Resolve 指向你已有的解释器即可，无需 `sudo`。
 
-已在免费版 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 不需要 framework 版 Python），并能端到端正常服务。现在没有任何平台停留在假设上：macOS 为本项目直接验证，Windows 和 Linux 来自用户报告。
+```bash
+launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
+```
+
+必须用 `launchctl setenv` 而不是 `export`——Resolve 从 Dock 启动，看不到你 shell 的环境变量。之后重启 Resolve。安装时会顺带装一个 Lua 金丝雀脚本，帮你区分"Python 未被检测到"和"目录放错"。
+
+已在免费版 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

@@ -30,12 +30,17 @@ scripting is unavailable, with no environment variable needed.
 tried, so its faults surface directly instead of degrading to another path.
 Existing tool call sites work unchanged. Two things to know when diagnosing it:
 
-- On macOS, Resolve lists `.py` scripts only when it can find a **framework
-  Python** (python.org). Homebrew/pyenv/conda are not detected and the script
-  simply never appears, with no error. The installer preflights this and ships a
-  Lua 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).
+- On macOS, Resolve finds Python 3 through **`PYTHON3HOME`, then
+  `/usr/local/bin/python3`** — and nowhere else, so Homebrew/pyenv/uv/conda
+  interpreters simply never appear, with no error. python.org installs work
+  because that installer creates `/usr/local/bin/python3`; framework-ness itself
+  is not the variable (#143). The sudo-free fix is
+  `launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"`
+  — `launchctl`, not `export`, because Resolve is GUI-launched and inherits
+  launchd's environment. The installer preflights both routes and ships a Lua
+  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).
 - **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

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

package/scripts/install_resolve_bridge.py

@@ -223,22 +223,69 @@ def stale_container_warning(targets: list[Path]) -> str | None:
     )
 
 
-#: Resolve enumerates `.py` scripts in Workspace > Scripts only when it finds a
-#: **framework** Python. Homebrew/pyenv/conda interpreters are not detected, and
-#: the failure is completely silent: the script sits in the right folder with the
-#: right permissions and simply never appears. Lua is embedded, so `.lua` always
-#: lists — which is why a Lua canary is installed alongside the probe.
+#: Resolve enumerates `.py` scripts in Workspace > Scripts only when it can find
+#: and load a Python 3, and the failure is completely silent: the script sits in
+#: the right folder with the right permissions and simply never appears. Lua is
+#: embedded, so `.lua` always lists — which is why a Lua canary is installed
+#: alongside the probe.
+#:
+#: **What it actually looks for (issue #143, corrected 2026-08-10).** This check
+#: used to require a *framework* build and send everyone else to python.org. That
+#: was the right remedy for the wrong reason, and it turned a one-line fix into a
+#: system-wide `sudo` install that managed machines often forbid. In
+#: `fusionscript.so` — read on Studio 19.1.3.7, a January 2025 binary, matching
+#: what the reporter read on 21.0.4.5 — every `Python.framework` reference is
+#: Python **2.7**:
+#:
+#:     /Library/Frameworks/Python.framework/Versions/2.7/
+#:     /System/Library/Frameworks/Python.framework/Versions/2.7/
+#:
+#: There is no `Python.framework/Versions/3` string at all. Python 3 is found by
+#: a different mechanism entirely, whose pieces sit adjacent in the binary:
+#:
+#:     PYTHON3HOME
+#:     /usr/local/bin/python3
+#:     python3 -c 'import sys; sys.stdout.write("%s.%s|%s" % (sys.version_info.major, sys.version_info.minor, sys.prefix))'
+#:     /libpython
+#:
+#: i.e. resolve `PYTHON3HOME`, else `/usr/local/bin/python3`; probe it for its
+#: version and `sys.prefix`; `dlopen` `<prefix>/lib/libpython3.X.dylib`. The
+#: ordering is inferred from adjacency rather than decompiled control flow, but
+#: the two entry points are not in doubt.
+#:
+#: That explains every observation the old rule was built on. python.org works
+#: because its installer creates `/usr/local/bin/python3` — verified here, where
+#: it is a symlink into `Python.framework/Versions/3.11`. Homebrew on Apple
+#: silicon installs to `/opt/homebrew/bin`, pyenv to `~/.pyenv/shims`, and uv to
+#: `~/.local/share/uv/...`; none of them land `/usr/local/bin/python3`, so none
+#: are found. Framework-ness was never the variable — it was correlated with it.
+#:
+#: So a non-framework interpreter works once Resolve can see it, and `uv`/`pixi`/
+#: conda-forge users are not stuck: they can point `PYTHON3HOME` at their prefix
+#: without touching a system directory. It must be set with `launchctl setenv`,
+#: not `export` — Resolve is GUI-launched and inherits launchd's environment, not
+#: any shell's.
 _FRAMEWORK_PYTHON_ROOTS = (
     Path("/Library/Frameworks/Python.framework/Versions"),
     Path("/System/Library/Frameworks/Python.framework/Versions"),
 )
 
+#: The interpreter path baked into fusionscript.so as the fallback when
+#: PYTHON3HOME is unset. This is the one python.org's installer creates.
+_FALLBACK_PYTHON3 = Path("/usr/local/bin/python3")
+
 _LUA_CANARY = """-- Installed by davinci-resolve-mcp as an enumeration canary.
 -- If THIS appears under Workspace > Scripts but resolve_bridge_probe does not,
--- Resolve is listing Lua and silently skipping Python: it cannot find a
--- framework Python install. Install one from python.org and restart Resolve.
-print("Resolve is enumerating scripts. If the Python probe is missing, install a")
-print("framework Python from python.org (Homebrew/pyenv are NOT detected).")
+-- 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):
+--   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.
+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.")
 """
 
 
@@ -258,37 +305,145 @@ def framework_pythons() -> list[str]:
     return found
 
 
+def launchd_env(name: str) -> str | None:
+    """A variable's value as a GUI-launched Resolve sees it.
+
+    Deliberately NOT ``os.environ``. Resolve is started from the Dock or Finder,
+    so it inherits launchd's environment; a ``export PYTHON3HOME=...`` in the
+    terminal running this installer is invisible to it. Reading our own
+    environment would report a hit in precisely the case where the user has done
+    the wrong thing and needs to be told so.
+    """
+    import subprocess
+
+    try:
+        completed = subprocess.run(
+            ["launchctl", "getenv", name],
+            capture_output=True, text=True, timeout=10, check=False,
+        )
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    value = (completed.stdout or "").strip()
+    return value or None
+
+
+def python3_home_prefix() -> dict:
+    """Is PYTHON3HOME set for Resolve, and does it point at a loadable 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.
+    """
+    value = launchd_env("PYTHON3HOME")
+    result = {
+        "value": value,
+        "in_launchd": value is not None,
+        "in_this_shell": os.environ.get("PYTHON3HOME") or None,
+        "dylib": None,
+        "usable": False,
+    }
+    if not value:
+        return result
+    try:
+        dylibs = sorted(Path(value).glob("lib/libpython3.*.dylib"))
+    except OSError:
+        dylibs = []
+    if dylibs:
+        result["dylib"] = str(dylibs[0])
+        result["usable"] = True
+    return result
+
+
+def fallback_python3() -> dict:
+    """`/usr/local/bin/python3` — the path baked into fusionscript.so.
+
+    Present for a python.org install (its installer creates it) and absent for
+    Homebrew, pyenv, uv and conda, which is the whole of the "framework Pythons
+    only" folklore.
+    """
+    result = {"path": str(_FALLBACK_PYTHON3), "exists": False, "resolves_to": None}
+    try:
+        if not _FALLBACK_PYTHON3.exists():
+            return result
+        result["exists"] = True
+        result["resolves_to"] = str(_FALLBACK_PYTHON3.resolve())
+    except OSError:
+        pass
+    return result
+
+
 def python_preflight() -> dict:
     """Will Resolve list the Python probe we are about to install?
 
-    The framework-Python trap is **macOS-only**: `/Library/Frameworks/...` does
-    not exist on Windows or Linux, where Resolve finds Python by other means (the
-    registry, or the system interpreter). Running the macOS check there always
-    found nothing and emitted the macOS remediation — telling the Windows 11 user
-    in issue #106, who had a working python.org 3.12, to go install the Python
-    they already had. Report "no known reason it will not list" off macOS rather
-    than a false alarm; the Lua canary still ships either way, so a genuine
-    enumeration problem remains diagnosable.
+    The trap is **macOS-only**: `/Library/Frameworks/...` and
+    `/usr/local/bin/python3` are not how Resolve finds Python on Windows or
+    Linux (the registry, or the system interpreter). Running the macOS check
+    there always found nothing and emitted the macOS remediation — telling the
+    Windows 11 user in issue #106, who had a working python.org 3.12, to go
+    install the Python they already had. Report "no known reason it will not
+    list" off macOS rather than a false alarm; the Lua canary still ships either
+    way, so a genuine enumeration problem remains diagnosable.
+
+    On macOS, Resolve is satisfied by EITHER discovery route (see the note on
+    `_FRAMEWORK_PYTHON_ROOTS`), so requiring a framework build failed a `uv` or
+    `pixi` user who had a perfectly good interpreter and sent them to a
+    system-wide `sudo` install they may not be permitted to run — issue #143,
+    where free Resolve 21.0.4.5 ran the bridge on uv-managed CPython 3.12.13
+    with no python.org Python on the machine at all.
     """
     if sys.platform != "darwin":
         return {
             "framework_pythons": [],
+            "python3_home": None,
+            "fallback_python3": None,
             "resolve_will_list_python_scripts": True,
             "advice": None,
         }
     frameworks = framework_pythons()
+    home = python3_home_prefix()
+    fallback = fallback_python3()
+    # Either route is sufficient. PYTHON3HOME wins when both are present: that is
+    # 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:
+        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 "
+            "Workspace > Scripts, with no error. It looks in exactly two places: "
+            "the PYTHON3HOME environment variable, then /usr/local/bin/python3. "
+            "Homebrew (/opt/homebrew/bin), pyenv, uv and conda land in neither, "
+            "which is why they appear 'unsupported'.\n"
+            "Fix it either way:\n"
+            "  1. Point Resolve at the interpreter you already have, no sudo:\n"
+            "       launchctl setenv PYTHON3HOME \"$(python3 -c 'import sys; "
+            "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 "
+            "/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 "
+            "detected' apart from 'wrong folder'."
+        )
+    elif home["in_this_shell"] and not home["in_launchd"]:
+        # Found by another route, but the user has clearly tried this one and it
+        # will not survive into Resolve. Say so before they conclude it worked.
+        advice = (
+            "PYTHON3HOME is set in this shell but not in launchd, so Resolve "
+            "will not see it — Resolve is GUI-launched and inherits launchd's "
+            "environment, not your shell's. Python will still be found via "
+            "another route this time. To make PYTHON3HOME the one that counts: "
+            "launchctl setenv PYTHON3HOME \"$PYTHON3HOME\", then restart Resolve."
+        )
     return {
         "framework_pythons": frameworks,
-        "resolve_will_list_python_scripts": bool(frameworks),
-        "advice": None if frameworks else (
-            "No framework Python found. Resolve will silently ignore every .py "
-            "script in its Scripts folders — they will simply not appear in "
-            "Workspace > Scripts, with no error. Homebrew, pyenv and conda "
-            "interpreters are NOT detected. Install a framework build from "
-            "python.org (any recent 3.x), restart Resolve, and re-check. The "
-            "Lua canary installed alongside will list either way, so you can "
-            "tell 'Python not detected' apart from 'wrong folder'."
-        ),
+        "python3_home": home,
+        "fallback_python3": fallback,
+        "resolve_will_list_python_scripts": found,
+        "advice": advice,
     }
 
 

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.91.0"
+VERSION = "2.92.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 353-tool granular server instead
 """
 
-VERSION = "2.91.0"
+VERSION = "2.92.0"
 
 import base64
 import os
@@ -980,8 +980,10 @@ def _not_connected_error():
             reason="DAVINCI_RESOLVE_BRIDGE is set, so no other transport is tried.",
             remediation="In Resolve, run Workspace > Scripts > resolve_bridge. If it is not in "
                         "that menu, run `python scripts/install_resolve_bridge.py` and restart "
-                        "Resolve; a framework Python from python.org is required for Resolve to "
-                        "list .py scripts at all.",
+                        "Resolve. On macOS, Resolve lists .py scripts only if it can find a "
+                        "Python 3 via PYTHON3HOME or /usr/local/bin/python3; if neither exists, "
+                        "run `launchctl setenv PYTHON3HOME \"$(python3 -c 'import sys; "
+                        "print(sys.prefix)')\"` (launchctl, not export) and restart Resolve.",
             state={"resolve_running": running, "bridge_enabled": True},
         )
     if running: