davinci-resolve-mcp 2.104.0 → 2.104.2

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 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.104.2
+
+A contributor batch: two merged PRs, one PR converted into its fix, and four
+sharp issues from @andytsai821201-spec — all live- or repro-verified.
+
+**Merged.** PR #166 by @matoberuc-afk routes SetCurrentTimeline and 28 other
+discarded Resolve mutator returns through a checked helper — a refused
+timeline switch now errors instead of silently sending the next edit to
+whatever timeline was current. PR #170 by @FerroQuant makes the doctor and
+installer probes bridge-first and hard-exits probe children after native
+Fusion imports, extending PR #108's fusionscript-teardown rule to the
+remaining short-lived probes.
+
+**Fixed (from PR #165 by @Douglas4000).** `timeline_frame capture` died on the
+free-edition bridge with "unexpected keyword argument 'isInteractiveMode'":
+the bridge proxies Resolve calls positionally, and the single-frame render
+used a keyword. The call is positional now, and the bridge proxy raises a
+TypeError that names the rule instead of the bare stack trace.
+
+**Fixed (#167).** `drt.author`'s hand-typed frame-rate hex table was wrong in
+three of eight entries: 23.976 stored 30000/1001 (a different, plausible
+rate), 29.97 stored 29.9739, and 59.94 stored 0.9367 — while validate stayed
+green. The table is gone; rounded NTSC decimals snap to their exact rationals
+and everything encodes through writeDoubleLE.
+
+**Fixed (#168).** `drt.author` wrote fractional `<StartFrame>` values at
+fractional rates (01:00:00:00 at 30000/1001 → 107892.107…) and ignored the
+spec's `startFrame` field entirely. Frame indexes now round, and an explicit
+startFrame wins over the timecode.
+
+**Fixed (#169).** `project_db` by projectName never searched
+`Resolve Project Library/Resolve Projects` — the root a stock modern Studio
+install actually uses (this repo's own 19.1.3 machine uses the old
+`Resolve Disk Database` name, so both are real). Both Studio roots and the
+sandboxed free-edition root are searched and deduped.
+
+**Fixed (#171).** Resolve honours the sequence name INSIDE an FCP7 XML over
+the `timelineName` import option, so an iterating export→edit→import loop
+with a stale internal name "succeeded" while returning the same existing
+timeline forever. `import_timeline_checked` now rewrites the XML's internal
+sequence name to the requested timelineName before importing (surgical text
+replacement on a temp copy — DOCTYPE and clip names survive byte-for-byte),
+and a format it cannot rewrite that still returns an existing timeline errors
+instead of reporting success. Live-verified on Studio 19.1.3.7 with the
+reporter's exact step sequence. The headless-edit-loop guide documents the
+internal-name rule for raw-API callers.
+
+## What's New in v2.104.1
+
+**The job metadata lies too — verify_output now cross-checks the timeline.**
+Finishing v2.104.0's pending live validation exposed a hole in the new
+`render.verify_output`: in the issue #164 case (content before the timeline
+start) Resolve rewrites the render job's own MarkIn/MarkOut down to the
+collapsed extent. Measured live on Studio 19.1.3.7: 96 frames of content
+placed before the start turned an explicit 96-frame mark range into a 1-frame
+job — Complete at 100%, a 1-frame black stub, and a clean duration ratio,
+because the expected duration was computed from the job's own lying range.
+
+The only truthful readback in that state is the timeline items themselves,
+which report their real positions. `verify_output` now finds the job's
+timeline and cross-checks it: video items starting before the timeline's
+start frame warn (the #164 signature by direct evidence), and a mark range
+under half the items' extent warns (the collapse signature). Callers can also
+pass `expected_frames` or `expected_duration_seconds` outright. Live-verified
+both ways on 19.1.3.7: the healthy render verifies clean, the stub now fails
+with both warnings.
+
+### Fixed
+
+- `render.verify_output` no longer trusts the job's MarkIn/MarkOut as the
+  expected duration — the #164 stub previously verified clean at ratio 1.0.
+
+### Changed
+
+- The api_truth recordFrame entry now documents the mark-range rewrite and
+  the item-readback discriminator; the Blackmagic-facing report regenerated.
+
 ## What's New in v2.104.0
 
 The read/write symmetry audit's worklist, worked. PR #162's AST rewrite left

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.104.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.104.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)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.104.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.104.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.104.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.104.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/guides/headless-edit-loop.md

@@ -61,6 +61,21 @@ name is taken. An iterative loop that reuses one name works exactly once and
 then quietly does nothing, which is the worst possible failure for an automated
 edit cycle. Make the name unique per iteration.
 
+### A unique `timelineName` is still not enough — the file's internal name wins
+
+Resolve honours the sequence name **inside** the interchange file over the
+`timelineName` option (issue #171, measured on Studio 21.0.4.5). Export → edit
+→ re-import with `timelineName: CUT_v002` while the XML still says `CUT_v001`
+and Resolve hands back the **existing** `CUT_v001` timeline: the raw API
+reports the old timeline as if it were the import, and the loop operates on one
+timeline forever. When driving the raw API, bump the `<sequence><name>` inside
+the XML each iteration.
+
+`timeline.import_timeline_checked` handles both halves for you: it rewrites the
+FCP7 XML's internal sequence name to the requested `timelineName` before
+importing, and if a format it cannot rewrite still returns an existing timeline
+it errors instead of reporting success.
+
 ### DRT ignores `timelineName` and re-imports the media
 
 DRT is the native format and the obvious first choice, but it behaves

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.104.0"
+VERSION = "2.104.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
@@ -1329,37 +1329,57 @@ def access_violation_message(returncode, version=None):
 
 
 def verify_resolve_connection(python_path, api_path, lib_path):
-    """Try to import DaVinciResolveScript and connect."""
+    """Probe Resolve without exposing short-lived children to Fusion teardown.
+
+    The persistent bridge is tried before Blackmagic's native scripting module.
+    If direct scripting is genuinely required, the disposable child flushes its
+    result and hard-exits after any native import attempt so fusionscript's
+    background RemoteApp thread cannot race CPython finalization.
+    """
     if not api_path:
         return False, "Resolve API path not found"
 
     env = {**os.environ, **build_server_env(python_path, api_path, lib_path)}
     modules_path = env["PYTHONPATH"]
     repo_root = str(Path(__file__).resolve().parent)
-    # Route through connect_resolve so Network mode (RESOLVE_SCRIPT_HOST, propagated
-    # into env by build_server_env) uses the explicit IP-targeted overload. Fall
-    # back to Local-mode discovery if the helper cannot be imported.
     test_script = textwrap.dedent(f"""\
+        import os
         import sys
         sys.path.insert(0, {modules_path!r})
         sys.path.insert(0, {repo_root!r})
+        native_import_attempted = False
         try:
-            import DaVinciResolveScript as dvr
             try:
                 from src.utils.resolve_connection import connect_resolve
             except Exception:
-                connect_resolve = lambda mod: mod.scriptapp('Resolve')
-            resolve = connect_resolve(dvr)
+                connect_resolve = None
+
+            resolve = None
+            if connect_resolve is not None:
+                resolve = connect_resolve(None)
+
+            if resolve is None:
+                native_import_attempted = True
+                import DaVinciResolveScript as dvr
+                if connect_resolve is not None:
+                    resolve = connect_resolve(dvr)
+                else:
+                    resolve = dvr.scriptapp('Resolve')
+
             if resolve:
                 name = resolve.GetProductName()
                 ver = resolve.GetVersionString()
-                print(f"CONNECTED: {{name}} {{ver}}")
+                print(f"CONNECTED: {{name}} {{ver}}", flush=True)
             else:
-                print("IMPORTED_OK: Module loads but Resolve not running or not responding")
+                print("IMPORTED_OK: Module loads but Resolve not running or not responding", flush=True)
         except ImportError as e:
-            print(f"IMPORT_ERROR: {{e}}")
+            print(f"IMPORT_ERROR: {{e}}", flush=True)
         except Exception as e:
-            print(f"ERROR: {{e}}")
+            print(f"ERROR: {{e}}", flush=True)
+        if native_import_attempted:
+            sys.stdout.flush()
+            sys.stderr.flush()
+            os._exit(0)
     """)
 
     process_timeout = 10.0
@@ -1400,6 +1420,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
     except Exception as e:
         return False, str(e)
 
+
 # ─── Interactive UI ───────────────────────────────────────────────────────────
 
 def print_banner():

package/package.json

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

package/resolve-advanced/server/db-patch.mjs

@@ -18,6 +18,17 @@ const require = createRequire(import.meta.url);
 
 export const DISK_DB_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Disk Database/Resolve Projects');
 
+/**
+ * The other Studio layout. A stock modern Studio install on macOS keeps its
+ * local library under "Resolve Project Library", not "Resolve Disk Database"
+ * (issue #169, confirmed on Studio 21.0.4.5: every local project sits at
+ * Resolve Project Library/Resolve Projects/Users/<dbuser>/Projects/<name>/).
+ * The recursive walk already spans the Users/<dbuser>/Projects segment, so
+ * listing the root is all that is needed. Which root exists depends on how
+ * and when the library was created — search both, dedupe, never guess.
+ */
+export const PROJECT_LIBRARY_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Project Library/Resolve Projects');
+
 /**
  * The FREE edition ships from the App Store and runs SANDBOXED, so its project
  * library is not under Application Support at all — it lives inside the app's
@@ -39,7 +50,7 @@ export const LITE_DB_ROOT = path.join(
 );
 
 /** Every root searched when resolving a project by name, Studio first. */
-export const DB_ROOTS = [DISK_DB_ROOT, LITE_DB_ROOT];
+export const DB_ROOTS = [DISK_DB_ROOT, PROJECT_LIBRARY_ROOT, LITE_DB_ROOT];
 
 export function loadSqlite() {
   try {
@@ -82,8 +93,9 @@ export function resolveDbPath({ projectDb, projectName }) {
   const hits = [...new Set(DB_ROOTS.flatMap((root) => findProjectDb(projectName, root)))];
   if (!hits.length) {
     throw new Error(
-      `no Project.db found for project "${projectName}". Searched the Studio library ` +
-      `(${DISK_DB_ROOT}) and the sandboxed free-edition library (${LITE_DB_ROOT}). ` +
+      `no Project.db found for project "${projectName}". Searched the Studio libraries ` +
+      `(${DISK_DB_ROOT} and ${PROJECT_LIBRARY_ROOT}) and the sandboxed free-edition ` +
+      `library (${LITE_DB_ROOT}). ` +
       'If Resolve keeps its projects elsewhere — a relocated library, a network/Postgres ' +
       'database, or the free edition on Windows/Linux — pass projectDb with the full path.',
     );

package/resolve-advanced/server/offline-ref-db.mjs

@@ -33,6 +33,9 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 
 const DISK_DB_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Disk Database/Resolve Projects');
+// Modern Studio installs keep the local library under "Resolve Project
+// Library" instead (issue #169) — same shape, different root name.
+const PROJECT_LIBRARY_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Project Library/Resolve Projects');
 
 function loadSqlite() {
   try {
@@ -86,8 +89,11 @@ function openDb(dbPath, writable) {
 function resolveDbPath({ projectDb, projectName }) {
   if (projectDb) return projectDb;
   if (!projectName) throw new Error('provide projectDb (path) or projectName');
-  const hits = findProjectDb(projectName);
-  if (!hits.length) throw new Error(`no Project.db found for project "${projectName}" under the Resolve Disk Database`);
+  const hits = [...new Set([
+    ...findProjectDb(projectName, DISK_DB_ROOT),
+    ...findProjectDb(projectName, PROJECT_LIBRARY_ROOT),
+  ])];
+  if (!hits.length) throw new Error(`no Project.db found for project "${projectName}" under ${DISK_DB_ROOT} or ${PROJECT_LIBRARY_ROOT}`);
   if (hits.length > 1) throw new Error(`multiple Project.db match "${projectName}": ${hits.join(', ')} — pass projectDb explicitly`);
   return hits[0];
 }

package/resolve-advanced/vendor/drp-format/__tests__/framerate-encoding.test.js

@@ -0,0 +1,47 @@
+// Issue #167: the hand-typed FRAME_RATE_ENCODINGS table stored 30000/1001 for
+// 23.976, 29.9739 for 29.97, and 0.9367 for 59.94, while validate stayed
+// green. Issue #168: fractional StartFrame at NTSC rates, startFrame ignored.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { encodeFrameRate, snapFrameRate } = require('../xml-builder');
+const { buildSeqContainerFile } = require('../seq-container-builder');
+
+function decode(hex) {
+  return Buffer.from(hex, 'hex').readDoubleLE(0);
+}
+
+test('rounded NTSC decimals snap to their exact rationals', () => {
+  assert.ok(Math.abs(decode(encodeFrameRate(23.976)) - 24000 / 1001) < 1e-9);
+  assert.ok(Math.abs(decode(encodeFrameRate(29.97)) - 30000 / 1001) < 1e-9);
+  assert.ok(Math.abs(decode(encodeFrameRate(59.94)) - 60000 / 1001) < 1e-9);
+  assert.ok(Math.abs(decode(encodeFrameRate(23.98)) - 24000 / 1001) < 1e-9);
+});
+
+test('exact rationals and integers round-trip untouched', () => {
+  for (const fps of [24, 25, 30, 48, 50, 60, 30000 / 1001, 24000 / 1001, 60000 / 1001]) {
+    assert.ok(Math.abs(decode(encodeFrameRate(fps)) - snapFrameRate(fps)) < 1e-12);
+    if (Number.isInteger(fps)) {
+      assert.strictEqual(snapFrameRate(fps), fps, `integer ${fps} must not snap`);
+    }
+  }
+});
+
+test('the three formerly-wrong table rates never reappear', () => {
+  // The old table's values, byte for byte. None may ever be produced again
+  // for the inputs that used to hit them.
+  assert.notStrictEqual(encodeFrameRate(23.976), '286b55e253f83d40');
+  assert.notStrictEqual(encodeFrameRate(29.97), '286b55e253f93d40');
+  assert.notStrictEqual(encodeFrameRate(59.94), '286b55e253f9ed3f');
+});
+
+test('StartFrame is an integer at fractional rates and startFrame wins', async () => {
+  const tl = { name: 'T', videoTracks: [], audioTracks: [] };
+  const fromTc = await buildSeqContainerFile(tl, {
+    frameRate: 30000 / 1001, startTimecode: '01:00:00:00',
+  });
+  assert.match(fromTc, /<StartFrame>107892<\/StartFrame>/);
+  const explicit = await buildSeqContainerFile(tl, {
+    frameRate: 30000 / 1001, startTimecode: '01:00:00:00', startFrame: 99999,
+  });
+  assert.match(explicit, /<StartFrame>99999<\/StartFrame>/);
+});

package/resolve-advanced/vendor/drp-format/drp-packager.js

@@ -93,6 +93,7 @@ async function packageFullDRP(options) {
     const seqContainerXml = await buildSeqContainerFile(timeline, {
       frameRate: timeline.frameRate || 24,
       startTimecode: timeline.startTimecode || '01:00:00:00',
+      startFrame: timeline.startFrame,
       markers: timeline.markers || [],
       resolution: timeline.resolution || '1920x1080',
     });

package/resolve-advanced/vendor/drp-format/seq-container-builder.js

@@ -60,8 +60,11 @@ async function buildSeqContainerFile(timeline, options = {}) {
   // Build lockable blob with markers
   const lockableBlob = buildLockableBlobElement(markers, lockableBlobId, frameRate);
 
-  // Calculate start frame from timecode
-  const startFrame = timecodeToFrames(startTimecode, frameRate);
+  // An explicit startFrame wins; otherwise derive it from the timecode
+  // (issue #168 — the spec field used to be ignored entirely).
+  const startFrame = Number.isFinite(options.startFrame)
+    ? Math.round(options.startFrame)
+    : timecodeToFrames(startTimecode, frameRate);
 
   // Combine video tracks: standard video tracks first, then Rich title tracks
   const allVideoTrackElements = [...videoTrackElements, ...richTitleTrackElements];
@@ -364,7 +367,11 @@ function timecodeToFrames(timecode, fps = 24) {
   if (parts.length !== 4) return 0;
 
   const [hh, mm, ss, ff] = parts;
-  return hh * 3600 * fps + mm * 60 * fps + ss * fps + ff;
+  // A frame index is an integer. At fractional rates the seconds product is
+  // fractional (3600 x 30000/1001 = 107892.107...), and writing it raw put a
+  // fractional <StartFrame> in the XML (issue #168). Non-drop convention:
+  // round the seconds part, then add the frame component.
+  return Math.round(hh * 3600 * fps + mm * 60 * fps + ss * fps) + ff;
 }
 
 // =============================================================================
@@ -549,6 +556,7 @@ async function buildSeqContainerFiles(timelines, options = {}) {
       ...options,
       frameRate: timeline.frameRate || options.frameRate || 24,
       startTimecode: timeline.startTimecode || options.startTimecode || '01:00:00:00',
+      startFrame: timeline.startFrame ?? options.startFrame,
       markers: timeline.markers || options.markers || [],
     });
     results.push({ filename: `SeqContainer${idx + 1}.xml`, content });

package/resolve-advanced/vendor/drp-format/xml-builder.js

@@ -30,19 +30,28 @@ const DEFAULT_PROJECT_SETTINGS = {
 };
 
 /**
- * Frame rate encoding lookup table
- * Maps common frame rates to their hex-encoded double representation
+ * Snap rounded NTSC decimals to their exact rationals.
+ *
+ * A caller writing 23.976 / 29.97 / 59.94 means 24000/1001, 30000/1001,
+ * 60000/1001 — the value Resolve itself stores. Integer rates are left
+ * untouched (24 × 1.001 = 24.024 sits outside the window), and an exact
+ * rational snaps to itself. This replaces a hand-typed hex lookup table whose
+ * 23.976 entry actually held 30000/1001, whose 29.97 entry held 29.9739, and
+ * whose 59.94 entry held 0.9367 (issue #167) — magic constants nobody could
+ * read were wrong for years while every exact input bypassed them.
  */
-const FRAME_RATE_ENCODINGS = {
-  23.976: '286b55e253f83d40',
-  24.0: '0000000000003840',
-  25.0: '0000000000003940',
-  29.97: '286b55e253f93d40',
-  30.0: '0000000000003e40',
-  50.0: '0000000000004940',
-  59.94: '286b55e253f9ed3f',
-  60.0: '0000000000004e40'
-};
+function snapFrameRate(fps) {
+  const scaled = (fps * 1001) / 1000;
+  const nearest = Math.round(scaled);
+  if (
+    nearest > 0 &&
+    Math.abs(scaled - nearest) < 0.02 &&
+    Math.abs(fps - nearest) > 1e-9
+  ) {
+    return (nearest * 1000) / 1001;
+  }
+  return fps;
+}
 
 // ============================================================================
 // HELPER FUNCTIONS
@@ -73,14 +82,9 @@ function generateUUID() {
  * // Returns: "0000000000003840"
  */
 function encodeFrameRate(fps) {
-  // Check if we have a pre-encoded value
-  if (FRAME_RATE_ENCODINGS[fps]) {
-    return FRAME_RATE_ENCODINGS[fps];
-  }
-
   // Encode as IEEE 754 double precision (8 bytes, little-endian)
   const buffer = Buffer.allocUnsafe(8);
-  buffer.writeDoubleLE(fps, 0);
+  buffer.writeDoubleLE(snapFrameRate(fps), 0);
   return buffer.toString('hex');
 }
 
@@ -755,5 +759,5 @@ module.exports = {
 
   // Constants
   DEFAULT_PROJECT_SETTINGS,
-  FRAME_RATE_ENCODINGS
+  snapFrameRate
 };

package/scripts/doctor.py

@@ -275,35 +275,71 @@ def resolve_probe(
     if not PYTHON.exists():
         return {"import_ok": False, "error": f"{PYTHON} is missing"}
 
+    # Disposable probe: ask the persistent bridge before importing Blackmagic's
+    # native Fusion module. fusionscript can leave a RemoteApp thread alive and
+    # crash CPython during interpreter finalization. If native import is needed,
+    # flush the result and hard-exit so those unsafe finalizers never run.
     code = f"""
 import json
+import os
 import sys
 sys.path.insert(0, {str(REPO)!r})
 sys.path.insert(0, {str(RESOLVE_MODULES)!r})
+native_import_attempted = False
 try:
-    import DaVinciResolveScript as dvr
     from src.utils.resolve_connection import connect_resolve
 except Exception as exc:
     payload = {{"import_ok": False, "error": repr(exc)}}
 else:
     try:
-        resolve = connect_resolve(dvr)
+        resolve = connect_resolve(None)
     except Exception as exc:
         payload = {{
-            "import_ok": True,
-            "module": getattr(dvr, "__file__", None),
+            "import_ok": None,
+            "import_skipped": True,
             "resolve_connected": False,
             "connection_error": repr(exc),
         }}
     else:
-        payload = {{
-            "import_ok": True,
-            "module": getattr(dvr, "__file__", None),
-            "resolve_connected": bool(resolve),
-            "product": resolve.GetProductName() if resolve else None,
-            "version": resolve.GetVersionString() if resolve else None,
-        }}
-print(json.dumps(payload))
+        if resolve is not None:
+            payload = {{
+                "import_ok": None,
+                "import_skipped": True,
+                "module": None,
+                "resolve_connected": True,
+                "transport": "bridge",
+                "product": resolve.GetProductName(),
+                "version": resolve.GetVersionString(),
+            }}
+        else:
+            native_import_attempted = True
+            try:
+                import DaVinciResolveScript as dvr
+            except Exception as exc:
+                payload = {{"import_ok": False, "error": repr(exc)}}
+            else:
+                try:
+                    resolve = connect_resolve(dvr)
+                except Exception as exc:
+                    payload = {{
+                        "import_ok": True,
+                        "module": getattr(dvr, "__file__", None),
+                        "resolve_connected": False,
+                        "connection_error": repr(exc),
+                    }}
+                else:
+                    payload = {{
+                        "import_ok": True,
+                        "module": getattr(dvr, "__file__", None),
+                        "resolve_connected": bool(resolve),
+                        "product": resolve.GetProductName() if resolve else None,
+                        "version": resolve.GetVersionString() if resolve else None,
+                    }}
+print(json.dumps(payload), flush=True)
+if native_import_attempted:
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(0)
 """
     env = {
         **os.environ,
@@ -481,37 +517,47 @@ def collect(
     check(results, "OK" if pyver["ok"] else "FAIL", "Python version", pyver["stdout"] or pyver["stderr"])
 
     probe = resolve_probe(resolve_host, resolve_timeout)
-    if probe.get("import_ok"):
+    if probe.get("import_skipped"):
+        check(
+            results,
+            "OK" if probe.get("resolve_connected") else "INFO",
+            "DaVinciResolveScript import",
+            "skipped — persistent bridge answered; native Fusion module not loaded"
+            if probe.get("resolve_connected")
+            else "skipped — bridge mode failed before native Fusion import",
+        )
+    elif probe.get("import_ok"):
         check(results, "OK", "DaVinciResolveScript import", str(probe.get("module")))
-        if probe.get("resolve_connected"):
-            detail = f"{probe.get('product')} {probe.get('version')}"
-            check(results, "OK", "Resolve scripting connection", detail)
-        elif probe.get("connection_error"):
-            check(
-                results,
-                "FAIL",
-                "Resolve scripting connection",
-                str(probe["connection_error"]),
-            )
-        else:
-            # This is also exactly what the free edition looks like: the module
-            # imports fine and scriptapp refuses, because Blackmagic gates
-            # *external* scripting to Studio. Sending someone to toggle a
-            # preference that cannot help them is a dead end, so name the bridge
-            # here too.
-            check(
-                results,
-                "WARN",
-                "Resolve scripting connection",
-                "Module import worked, but scriptapp returned no object. On Studio: "
-                "External scripting = Local, or Network with --resolve-host set to "
-                "the Resolve host IP, then restart Resolve. On the FREE edition "
-                "external scripting is gated off entirely — use the in-app bridge "
-                "(see 'Free-edition bridge' below).",
-            )
     else:
         check(results, "FAIL", "DaVinciResolveScript import", str(probe.get("error")))
 
+    if probe.get("resolve_connected"):
+        detail = f"{probe.get('product')} {probe.get('version')}"
+        check(results, "OK", "Resolve scripting connection", detail)
+    elif probe.get("connection_error"):
+        check(
+            results,
+            "FAIL",
+            "Resolve scripting connection",
+            str(probe["connection_error"]),
+        )
+    elif probe.get("import_ok"):
+        # This is also exactly what the free edition looks like: the module
+        # imports fine and scriptapp refuses, because Blackmagic gates
+        # *external* scripting to Studio. Sending someone to toggle a
+        # preference that cannot help them is a dead end, so name the bridge
+        # here too.
+        check(
+            results,
+            "WARN",
+            "Resolve scripting connection",
+            "Module import worked, but scriptapp returned no object. On Studio: "
+            "External scripting = Local, or Network with --resolve-host set to "
+            "the Resolve host IP, then restart Resolve. On the FREE edition "
+            "external scripting is gated off entirely — use the in-app bridge "
+            "(see 'Free-edition bridge' below).",
+        )
+
     results.extend(bridge_checks(probe))
 
     results.extend(extras_checks())

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.104.0"
+VERSION = "2.104.2"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")