davinci-resolve-mcp 2.82.1 → 2.86.2

package/docs/reference/api-coverage.md

@@ -8,12 +8,12 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 |--------|-------|
 | MCP Tools | **34** compound (default) / **341** granular |
 | Kernel Actions | **136** guarded MCP workflow actions across 9 compound tools |
-| API Methods Covered | **349/349** (100%) |
-| Methods Live Tested | **338/349** (96.8%) |
+| API Methods Covered | **351/351** (100%) |
+| Methods Live Tested | **338/351** (96.3%) |
 | Live Test Pass Rate | **338/338** (100%) |
 | API Object Classes | 13 |
-| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio |
-| Compatibility Note | 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.0 additions are version-guarded and live-tested on 21.0.2 (see the Resolve 21 delta row below — five wrappers need AI Extras packs and stay untested without one, and one is deliberately not executed) |
+| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio + Resolve 21.0.3 **free** (via the in-app bridge) |
+| Compatibility Note | 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.0 additions are version-guarded and live-tested on 21.0.2 (see the Resolve 21 delta row below — five wrappers need AI Extras packs and stay untested without one, and one is deliberately not executed). The Resolve 21.0.4 additions are version-guarded and unit-tested, but not live-tested here — the validation machine carries Studio 19.1.3 and free 21.0.3, neither of which is 21.0.4. Note the free build is reachable only through the in-app bridge, since the free edition refuses external scripting |
 
 ## API Coverage
 
@@ -109,7 +109,7 @@ source, these summaries are downstream of it:
 | Phase 5 | 6/6 | 100% | Scene cuts, subtitles from audio, graph node cache/tools/enable |
 | Resolve 20 delta | 12/12 | 100% | Resolve 20.0-20.2.2 scripting additions live-tested on 20.3.2 |
 | Resolve 21 delta | 7/7 | 100% | Resolve 21.0 additions that could be executed, live-tested on Studio 21.0.2.4 (`tests/live_resolve21_validation.py`). The other 6 need an AI Extras pack or are unsafe to run — counted as untested, not as passes |
-| **Total** | **338/338** | **100%** | **96.8% of the 349 covered methods tested live** |
+| **Total** | **338/338** | **100%** | **96.3% of the 351 covered methods tested live** |
 
 #### Resolve 21 delta detail
 
@@ -130,7 +130,7 @@ marked 🔬 rather than ⚠️.
 | `Project.GenerateSpeech` | 🔬 | Requires AI Speech Generator; returned an error **string**, not a MediaPoolItem |
 | `Resolve.DisableBackgroundTasksForCurrentResolveSession` | 🔬 | Present in `dir()`; **not executed** — session-wide, returns None, and has no `Enable...` counterpart, so there is no undo short of restarting Resolve |
 
-### Untested Methods (11 of 349)
+### Untested Methods (13 of 351)
 
 Every ☁️ and 🔬 row from the reference tables, listed here so the count is
 checkable rather than asserted.
@@ -148,10 +148,15 @@ checkable rather than asserted.
 | `MPI.AnalyzeForSlate` | Requires the AI Slate ID Extra | Yes |
 | `Project.GenerateSpeech` | Requires the AI Speech Generator Extra | Yes |
 | `Resolve.DisableBackgroundTasksForCurrentResolveSession` | Deliberately not executed: session-wide, returns `None`, and has no `Enable...` counterpart, so there is no undo short of restarting Resolve | No |
+| `MPI.GetTimeline` | Requires a Resolve 21.0.4 build; the validation machine runs Studio 19.1.3 and free 21.0.3 | Yes |
+| `TL.GetSelectedClips` | Requires a Resolve 21.0.4 build; the validation machine runs 19.1.3 | Yes |
 
 The five AI Extras rows are untested for want of a downloadable pack, not because
 the wrappers are suspect — a report from anyone who has the packs installed would
-close them. The last one is a decision rather than a gap: it is reachable, and
+close them. The two 21.0.4 rows are untested for want of the build: this machine
+runs 19.1.3, so they are guarded and unit-tested against stubs and carry a
+contributor's report rather than a result of ours. The remaining one is a
+decision rather than a gap: it is reachable, and
 running it during a validation sweep would disable background tasks for every
 project open in that Resolve instance.
 
@@ -192,7 +197,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 19 | `ExportBurnInPreset(presetName, exportPath)` | ⚠️ | API accepts; needs valid preset name |
 | 20 | `GetKeyframeMode()` | ✅ | Returns keyframe mode |
 | 21 | `SetKeyframeMode(keyframeMode)` | ⚠️ | API accepts; mode must match valid enum |
-| 22 | `GetFairlightPresets()` | ✅ | Resolve 20.3.2 live test returns preset map |
+| 22 | `GetFairlightPresets()` | ✅ | Returns a preset map. Live on 20.3.2 Studio and 21.0.3 free; **absent below 20.2.2** — confirmed missing on 19.1.3, so the version floor is verified from both sides |
 | 23 | `DisableBackgroundTasksForCurrentResolveSession()` | 🔬 | Resolve 21.0. Present in `dir()`; **not executed** — session-wide, returns `None`, no `Enable...` counterpart, so no undo short of restarting Resolve |
 
 ### ProjectManager
@@ -250,7 +255,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 19 | `LoadRenderPreset(presetName)` | ✅ | Loads render preset |
 | 20 | `SaveAsNewRenderPreset(presetName)` | ✅ | Creates render preset |
 | 21 | `DeleteRenderPreset(presetName)` | ✅ | Deletes render preset |
-| 22 | `SetRenderSettings({settings})` | ✅ | Applies render settings; Resolve 20.2 adds `ExportSubtitle` and `SubtitleFormat` keys |
+| 22 | `SetRenderSettings({settings})` | ✅ | Applies render settings; Resolve 20.2 adds `ExportSubtitle` and `SubtitleFormat` keys; Resolve 21.0.4 adds `UseFullExtents`, `AddFrameHandles` and `DataBurnIn` — `AddFrameHandles` is accepted and then ignored while `UseFullExtents` is true, so the server returns it as a warning |
 | 23 | `GetRenderJobStatus(jobId)` | ✅ | Returns `{JobStatus, CompletionPercentage}` |
 | 24 | `GetQuickExportRenderPresets()` | ✅ | Returns preset names |
 | 25 | `RenderWithQuickExport(preset, {params})` | ✅ | Initiates quick export |
@@ -271,7 +276,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 40 | `GetColorGroupsList()` | ✅ | Returns color group list |
 | 41 | `AddColorGroup(groupName)` | ✅ | Returns ColorGroup object |
 | 42 | `DeleteColorGroup(colorGroup)` | ✅ | Deletes color group |
-| 43 | `ApplyFairlightPresetToCurrentTimeline(presetName)` | ⚠️ | Resolve 20.3.2 live test accepts call; returns `False` without a named preset |
+| 43 | `ApplyFairlightPresetToCurrentTimeline(presetName)` | ⚠️ | Accepts the call and returns `False` when handed a name that does not exist. **Never exercised against a genuinely saved preset**, so a `True` path has not been observed — the API has no way to create one, and `GetFairlightPresets` reported an empty map on both test machines. To clear this: save a mix as a Fairlight preset in the UI, then apply it by that name. Requires 20.2.2+ |
 | 44 | `GenerateSpeech({speechGenerationSettings}, timecode)` | 🔬 | Resolve 21.0. Requires the AI Speech Generator Extra; without it returns an error **string**, not a MediaPoolItem |
 | 45 | `ResetIntellisearchAnalysis()` | ✅ | Resolve 21.0.2 live test returns `True` |
 
@@ -382,6 +387,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 39 | `AnalyzeForIntellisearch(identifyFaces, isBetterMode)` | 🔬 | Resolve 21.0. Requires the AI IntelliSearch Extra; without it returns an error **string**, not `False` |
 | 40 | `AnalyzeForSlate(markerColor)` | 🔬 | Resolve 21.0. Requires the AI Slate ID Extra. Documented `resolve.MARKER_*` constants do not exist on the handle |
 | 41 | `RemoveMotionBlur({deblurOption})` | ✅ | Resolve 21.0.2 live test returns the new MediaPoolItem; source media path unchanged. Requires the AI Motion Deblur Extra |
+| 42 | `GetTimeline()` | 🔬 | Resolve 21.0.4. Not executed here — no 21.0.4 build on hand; reported working on Studio 21.0.4.5 in issue #131 |
 
 ### Timeline
 
@@ -445,6 +451,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 56 | `ClearMarkInOut(type)` | ✅ | Clears mark in/out |
 | 57 | `GetVoiceIsolationState(trackIndex)` | ✅ | Resolve 20.3.2 live test returns voice isolation state |
 | 58 | `SetVoiceIsolationState(trackIndex, {state})` | ✅ | Resolve 20.3.2 live test sets voice isolation state |
+| 59 | `GetSelectedClips()` | 🔬 | Resolve 21.0.4. First name tried by the selection probe, ahead of the two legacy speculative names. Not executed here — no 21.0.4 build on hand; reported working on Studio 21.0.4.5 in issue #131 |
 
 ### TimelineItem
 

package/docs/reference/api-limitations.md

@@ -182,7 +182,7 @@ equivalent, blocking full automation.
 
 - **Object:** `TimelineItem / Timeline / Project`
 - **Behavior:** There is no API method to set or query subtitle font family, font size, text color, background color, outline, shadow, position, alignment, or to apply/query subtitle style presets. TimelineItem.GetProperty() on subtitle items returns only transform/composite keys. Timeline.GetSetting() and Project.GetSetting() return None for all probed subtitle-style keys (e.g. 'subtitleFontName', 'subtitleFontSize', 'subtitleTextColor', 'subtitleBackgroundColor', 'subtitlePosition', 'subtitleAlignment', 'subtitlePreset', 'subtitleStyle'). Verified via dir(), GetProperty(), and GetSetting() on Resolve 21.0.0.48.
-- **Workaround / current handling:** No API workaround exists, but the style IS reachable below the API: it lives in Sm2TiTrack.FieldsBlob for Type=2 tracks, as an EffectFiltersBA payload whose effect 136 carries a Qt QFont descriptor (param 18) and a normalised position vector (param 17). Exposed as project_db list_subtitle_styles / set_subtitle_style (font family/size/weight/italic + position). Confirmed live on Studio 19.1.3 (2026-08-06): Resolve opens a patched track and re-serialises it back to its own zstd form with the patched values intact, so it genuinely parses the write. Caveats: whole-TRACK style not per-caption, project must be CLOSED, Resolve must be fully quit and relaunched afterwards, and the track must already carry a style blob (a freshly added subtitle track has none until it is styled once in the UI). Burn-in overlays via Fusion titles remain a visual alternative but do not produce subtitle tracks.
+- **Workaround / current handling:** No API workaround exists, but the style IS reachable below the API: it lives in Sm2TiTrack.FieldsBlob for Type=2 tracks, as an EffectFiltersBA payload whose effect 136 carries a Qt QFont descriptor (param 18) and a normalised position vector (param 17). Exposed as project_db list_subtitle_styles / set_subtitle_style (font family/size/weight/italic + position). Confirmed live on BOTH editions 2026-08-06 — Studio 19.1.3 and free 21.0.3, identical behaviour: Resolve opens a patched track and re-serialises it back to its own zstd form with the patched values intact, so it genuinely parses the write. Caveats: whole-TRACK style not per-caption, project must be CLOSED, Resolve must be fully quit and relaunched afterwards, and the track must already carry a style blob (a freshly added subtitle track has none until it is styled once in the UI). Burn-in overlays via Fusion titles remain a visual alternative but do not produce subtitle tracks.
 - **Tags:** missing-method, subtitle, style, preset
 
 ### Speech recognition engine selection and SRT import
@@ -226,7 +226,7 @@ equivalent, blocking full automation.
 
 - **Object:** `TimelineItem / MediaPoolItem`
 - **Signature:** `(colorName) -> bool`
-- **Behavior:** SetClipColor accepts exactly 16 names — the Edit-page clip-colour palette — and refuses everything else with a bare False, no exception and no other signal. Enumerated live on Studio 19.1.3.7 (2026-08-06) against both objects; the accepted set is IDENTICAL on TimelineItem and MediaPoolItem: Orange, Apricot, Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, Pink, Tan, Beige, Brown, Chocolate. The empty string is refused too. The trap is that the scripting reference documents colorName as a bare string with no enumerated values, while exporting the MARKER palette as constants (resolve.MARKER_ROSE, resolve.MARKER_FUCHSIA, ...) — so the only colour vocabulary reachable from the API surface is the wrong one. Cyan, Red, Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa and Cream are all marker-only and all refused. Five names overlap both palettes (Blue, Green, Yellow, Pink, Purple), which is why the decoy survives: reasoning from the marker constants scores 5 of 16 and looks like the right vocabulary with a few gaps.
+- **Behavior:** SetClipColor accepts exactly 16 names — the Edit-page clip-colour palette — and refuses everything else with a bare False, no exception and no other signal. Enumerated live on Studio 19.1.3.7 (2026-08-06) against both objects; the accepted set is IDENTICAL on TimelineItem and MediaPoolItem: Orange, Apricot, Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, Pink, Tan, Beige, Brown, Chocolate. The empty string is refused too. The trap is that the scripting reference documents colorName as a bare string with no enumerated values, while exporting the MARKER palette as constants (resolve.MARKER_ROSE, resolve.MARKER_FUCHSIA, ...) — so the only colour vocabulary reachable from the API surface is the wrong one. Cyan, Red, Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa and Cream are all marker-only and all refused. Five names overlap both palettes (Blue, Green, Yellow, Pink, Purple), which is why the decoy survives: reasoning from the marker constants scores 5 of 16 and looks like the right vocabulary with a few gaps. The reporter's field experience sharpens this — the trap is not that a decoy vocabulary exists, it is that the decoy HALF-WORKS. Intermittent successes read as an unreliable API rather than as a wrong vocabulary, so the wrong conclusion is the natural one; a clean 0-for-8 would have exposed the mechanism immediately.
 - **Workaround / current handling:** Pass only the 16 clip-colour names; on False, treat it as an invalid name rather than an item/lock/page problem. The set is pinned in utils/clip_colors.py and named in the refusal remediation, but deliberately NOT enforced — it was measured on one build and a later Resolve could extend it.
 - **Reference:** [issue #124](https://github.com/samuelgursky/davinci-resolve-mcp/issues/124)
 - **Tags:** timeline-item, media-pool, silent-failure, undocumented-enum
@@ -385,8 +385,8 @@ values, or automation-hostile modal prompts.
 ### hasattr() / getattr() on Resolve API objects (attribute fabrication)
 
 - **Object:** `(all Resolve scripting objects)`
-- **Behavior:** UNRESOLVED — the two measurements do not test the same thing. On 21.0.0 the bridge was recorded as returning a callable for ANY attribute name, making capability detection by hasattr impossible; the evidence was REAL API method names borrowed from other object types (SetStart, Razor, AddNode, GenerateProxy, AddSmartBin reported present on objects that do not have them). A 21.0.2.4 control probe of the invented name 'TotallyMadeUpMethod_xyz123' returned getattr-callable False on all eight object types, matching dir() in every case. That does NOT refute the 21.0.0 record: if the bridge resolves any name known to the RemoteObject method table rather than literally any string, an invented name is correctly rejected on both builds and the probe never exercised the failing case. Re-running the probe with those five real names is what would settle it; until then, assume fabrication is possible.
-- **Workaround / current handling:** Use dir(obj) membership for capability probes. It is correct on every build measured, and it is the only form not affected by whichever way this resolves. server._has_method uses hasattr/getattr and so may over-report on builds where fabrication is live — that is the case _requires_method gates guard, so it matters most exactly where it is least tested. Calling a fabricated method typically returns None/False with no error.
+- **Behavior:** UNRESOLVED — the two measurements do not test the same thing. On 21.0.0 the bridge was recorded as returning a callable for ANY attribute name, making capability detection by hasattr impossible; the evidence was REAL API method names borrowed from other object types (SetStart, Razor, AddNode, GenerateProxy, AddSmartBin reported present on objects that do not have them). A 21.0.2.4 control probe of the invented name 'TotallyMadeUpMethod_xyz123' returned getattr-callable False on all eight object types, matching dir() in every case. That does NOT refute the 21.0.0 record: if the bridge resolves any name known to the RemoteObject method table rather than literally any string, an invented name is correctly rejected on both builds and the probe never exercised the failing case. PARTLY SETTLED 2026-08-06 on Studio 19.1.3.7, DIRECT connection (not the bridge): the five real borrowed names were re-run as the entry asked, across Resolve, ProjectManager, Project, MediaPool, Timeline, Folder and TimelineItem — 42 checks. Every one returned getattr-callable False and dir()-absent, agreeing in all 42 cases, exactly like the invented control. So NO fabrication on the direct path on this build, and the borrowed-name case the 21.0.2.4 probe missed is now covered there. What the same run DID establish is narrower and worse than expected: bare hasattr() returns True for EVERY name on every object — real, borrowed or invented — while getattr returns None. hasattr alone is therefore not a weak probe, it is a constant True and carries no information at all. STILL OPEN: the 21.0.0 record was against the BRIDGE, which this run did not exercise, so bridge-side fabrication remains untested and the recommendation below stands unchanged.
+- **Workaround / current handling:** Use dir(obj) membership for capability probes. It is correct on every build measured, and it is the only form not affected by whichever way this resolves. NEVER use bare hasattr(): it is a constant True on Resolve objects and cannot distinguish anything. server._has_method uses callable(getattr(...)), which agreed with dir() in all 42 direct-path checks on 19.1.3.7 but may still over-report on a bridge build where fabrication is live — that is the case _requires_method gates guard, so it matters most exactly where it is least tested. Calling a fabricated method typically returns None/False with no error.
 - **Tags:** bridge, introspection, silent-failure
 
 ### Resolve 21 AI methods (AnalyzeForIntellisearch, GenerateSpeech, AnalyzeForSlate) — inconsistent failure return type

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.82.1"
+VERSION = "2.86.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
@@ -1748,8 +1748,8 @@ def main():
                         "               python scripts/install_resolve_bridge.py"
                     )
                     print(
-                        "               then Workspace > Scripts > resolve_bridge, "
-                        "and set DAVINCI_RESOLVE_BRIDGE=1"
+                        "               then Workspace > Scripts > resolve_bridge "
+                        "(used automatically once running)"
                     )
                 else:
                     print(f"  Resolve:   {yellow('Not running')} — start Resolve to use MCP tools")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.82.1",
+  "version": "2.86.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,29 @@ 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 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
+ * container, under a differently-named root ("Resolve Project Library", not
+ * "Resolve Disk Database"). Confirmed on free 21.0.3.7, macOS.
+ *
+ * Without this, `project_db` resolved by projectName could never find a
+ * free-edition project: it searched only the Studio root and reported "no
+ * Project.db found", sending exactly the users the in-app bridge exists to serve
+ * hunting for a path they have no reason to know.
+ *
+ * macOS-only: the sandbox container is an Apple construct. Where the free
+ * edition keeps its library on Windows and Linux is NOT verified here, so
+ * nothing is guessed for those platforms — pass `projectDb` explicitly there.
+ */
+export const LITE_DB_ROOT = path.join(
+  os.homedir(),
+  'Library/Containers/com.blackmagic-design.DaVinciResolveLite/Data/Library/Application Support/Resolve Project Library/Resolve Projects',
+);
+
+/** Every root searched when resolving a project by name, Studio first. */
+export const DB_ROOTS = [DISK_DB_ROOT, LITE_DB_ROOT];
+
 export function loadSqlite() {
   try {
     return require('better-sqlite3');
@@ -26,7 +49,10 @@ export function loadSqlite() {
   }
 }
 
-/** Recursively locate <projectName>/Project.db under the Resolve Disk Database. */
+/**
+ * Recursively locate <projectName>/Project.db under a project-library root.
+ * Called once per root by resolveDbPath; pass `root` to search just one.
+ */
 export function findProjectDb(projectName, root = DISK_DB_ROOT) {
   const hits = [];
   const walk = (dir, depth) => {
@@ -51,9 +77,22 @@ export function findProjectDb(projectName, root = DISK_DB_ROOT) {
 export 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`);
-  if (hits.length > 1) throw new Error(`multiple Project.db match "${projectName}": pass projectDb explicitly`);
+  // Deduplicate: a project present under both roots must not read as ambiguous
+  // just because the same file was found twice.
+  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}). ` +
+      '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.',
+    );
+  }
+  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/subtitle-style.js

@@ -167,11 +167,17 @@ function unwrapEffectFilters(raw) {
  * *compressor* (the bundled fzstd is decompress-only); the cost is a larger
  * blob, which does not matter here.
  *
- * Confirmed live against Resolve Studio 19.1.3 (2026-08-06): a subtitle track patched with
- * a 0x80 payload opens without error, and once Resolve next re-serialises that
- * track it writes the style back out as 0x81 zstd with the font descriptor and
- * position preserved exactly — i.e. Resolve genuinely parses the 0x80 form into
- * its in-memory model rather than passing the bytes through untouched.
+ * Confirmed live on BOTH editions (2026-08-06) — Studio 19.1.3 and free 21.0.3:
+ * a subtitle track patched with a 0x80 payload opens without error, and once
+ * Resolve next re-serialises that track it writes the style back out as 0x81
+ * zstd with the font descriptor and position preserved exactly. Resolve
+ * genuinely parses the 0x80 form into its in-memory model rather than passing
+ * the bytes through untouched. Both versions behaved identically, down to
+ * dropping the same neighbouring key on rewrite.
+ *
+ * Also identical across both: a freshly added subtitle track carries NO style
+ * blob (a ~111-byte NumLayers stub), so there is nothing to patch until the
+ * track has been styled once in the UI.
  */
 function wrapEffectFilters(protobuf, version = 2) {
   const head = Buffer.alloc(9);

package/scripts/doctor.py

@@ -338,8 +338,10 @@ def bridge_checks(probe: dict[str, Any]) -> list[dict[str, str]]:
     elif installed_at:
         check(
             results, "INFO", "DAVINCI_RESOLVE_BRIDGE",
-            "not set — the bridge is installed but will not be used. "
-            "export DAVINCI_RESOLVE_BRIDGE=1 to enable it.",
+            "not set — the bridge is still used automatically if external scripting "
+            "is unavailable and the in-Resolve script is running. Set it to 1 to make "
+            "the bridge the only transport tried, so its faults surface directly "
+            "instead of falling back.",
         )
     return results
 

package/scripts/resolve_bridge_launcher.py

@@ -168,7 +168,8 @@ def main():
         print("  operations  : %d" % len(resolve_bridge_ops.ResolveOperations.OPERATIONS))
         print("  generation  : %d" % generation)
         print()
-        print("  The MCP server connects with DAVINCI_RESOLVE_BRIDGE=1.")
+        print("  The MCP server uses this bridge automatically when external")
+        print("  scripting is unavailable. DAVINCI_RESOLVE_BRIDGE=1 forces it.")
         if model["blocking_required"]:
             print("  This script now HOLDS the listener open and will look busy until")
             print("  Resolve exits. That is expected — closing it stops the bridge.")

package/src/analysis_dashboard.py

@@ -12023,8 +12023,8 @@ def _not_connected_message(bridge_on: bool) -> str:
                 "Workspace > Scripts > resolve_bridge; launching Resolve cannot start it.")
     return ("DaVinci Resolve is not connected. On Studio, enable Preferences > General > "
             "'External scripting using' = Local. On the free edition, install the in-app "
-            "bridge, run Workspace > Scripts > resolve_bridge, and set "
-            "DAVINCI_RESOLVE_BRIDGE=1.")
+            "bridge and run Workspace > Scripts > resolve_bridge — once running it is used "
+            "automatically, no environment variable needed.")
 
 
 @_serialize_resolve

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.82.1"
+VERSION = "2.86.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 341-tool granular server instead
 """
 
-VERSION = "2.82.1"
+VERSION = "2.86.2"
 
 import base64
 import os
@@ -47,6 +47,7 @@ from src.utils.cdl import normalize_cdl_payload
 from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
 from src.utils import clip_colors as _clip_colors
+from src.utils import resolve_versions as _resolve_versions
 from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import (
@@ -180,9 +181,10 @@ mcp = FastMCP(
         "if one is already running they never launch a second. "
         "On a connection error, read the error's own remediation field — it names the "
         "fix that applies. External scripting is Studio-only, but the free edition is "
-        "reachable via the in-app bridge (Workspace > Scripts > resolve_bridge, with "
-        "DAVINCI_RESOLVE_BRIDGE=1), so a connection error does NOT mean the free "
-        "edition is unsupported."
+        "reachable via the in-app bridge (Workspace > Scripts > resolve_bridge — it is "
+        "used automatically when external scripting is unavailable; "
+        "DAVINCI_RESOLVE_BRIDGE=1 only forces it), so a connection error does NOT mean "
+        "the free edition is unsupported."
     ),
 )
 
@@ -937,8 +939,8 @@ def get_resolve():
                 "DaVinci Resolve is already running but is not answering the scripting API, "
                 "so it will NOT be launched again. Either enable Preferences > General > "
                 "'External scripting using' = Local (Studio only), or, on the free edition, "
-                "use the in-app bridge: install it, run Workspace > Scripts > resolve_bridge, "
-                "and set DAVINCI_RESOLVE_BRIDGE=1."
+                "use the in-app bridge: install it and run Workspace > Scripts > resolve_bridge "
+                "— once running it is used automatically, no environment variable needed."
             )
             return None
         if already_running is None:
@@ -991,8 +993,10 @@ def _not_connected_error():
             reason="External scripting is a Studio feature; the free edition refuses it "
                    "regardless of the preference. Resolve was NOT launched again.",
             remediation="On Studio: Preferences > General > 'External scripting using' = Local. "
-                        "On the free edition: install the in-app bridge, run "
-                        "Workspace > Scripts > resolve_bridge, and set DAVINCI_RESOLVE_BRIDGE=1.",
+                        "On the free edition: install the in-app bridge and run "
+                        "Workspace > Scripts > resolve_bridge — once it is running it is used "
+                        "automatically, no environment variable needed "
+                        "(DAVINCI_RESOLVE_BRIDGE=1 only forces it and disables this fallback).",
             # Which Resolve is refusing matters to the reader: a headless render
             # worker and the editor the user is looking at warrant different
             # responses, and the in-app bridge is not an option for the former.
@@ -3542,7 +3546,9 @@ def _coerce_item_list(value):
 
 def _get_selected_timeline_items(tl):
     warnings = []
-    for method_name in ("GetSelectedTimelineItems", "GetSelectedItems", "GetSelectedClips"):
+    # GetSelectedClips is the documented name since Resolve 21.0.4; the other two
+    # are legacy speculative probes kept for older/renamed builds.
+    for method_name in ("GetSelectedClips", "GetSelectedTimelineItems", "GetSelectedItems"):
         method = getattr(tl, method_name, None)
         if not callable(method):
             continue
@@ -7732,6 +7738,7 @@ _MEDIA_POOL_ITEM_METHODS = [
     "GetMarkInOut",
     "SetMarkInOut",
     "ClearMarkInOut",
+    "GetTimeline",
 ]
 
 _MEDIA_POOL_METHODS = [
@@ -13547,8 +13554,18 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       ignore_mcp_update() -> {success, version, update, decision}
       snooze_mcp_update(hours?) -> {success, version, update, decision}
       clear_mcp_update_preferences() -> {success, version, update, decision}
-      api_truth(query?) -> {verified_on, count, facts}  — look up behaviorally-verified
-        facts about quirky/unreliable Resolve API behavior (no connection needed).
+      api_truth(query?, resolve_version?) -> {verified_on, count, facts, live_version?}
+        — look up behaviorally-verified facts about quirky/unreliable Resolve API
+        behavior (no connection needed; never connects). When a build is already
+        connected or resolve_version is passed, each fact carries a
+        version_context saying whether it was measured on an older, newer or
+        identical build — the API changes per PATCH release, so a fact from
+        another build is a prior, not a finding.
+      check_version_support(symbol?, resolve_version?) -> {live_version, support|unavailable_on_this_build}
+        — does THIS build have that method? Answers "unknown" unless a gate is
+        recorded, because most of the API has never been version-bisected and a
+        false "available" is how an agent insists a missing method exists.
+        Omit symbol for every recorded gate this build does not clear.
       verification_stats() -> {stats}  — readback-verification tally
         (verified/contradicted/unverified) since server start (no connection needed).
       job_status(job_id) -> {id, label, status, result?, error?, started_at, ended_at}
@@ -13576,10 +13593,72 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     """
     p = _params(params)
 
-    # api_truth is a static knowledge lookup — no Resolve connection needed.
+    # api_truth is a static knowledge lookup — no Resolve connection needed, and
+    # that property is worth keeping: it is the one call that still answers when
+    # Resolve is down or unreachable. So the live build is used only if one is
+    # ALREADY connected, or if the caller names it. Never connect for this.
     if action == "api_truth":
         facts = lookup_api_truth(p.get("query"))
-        return {"verified_on": _API_TRUTH_VERIFIED_ON, "count": len(facts), "facts": facts}
+        live_version = p.get("resolve_version")
+        if not live_version and resolve is not None:
+            try:
+                live_version = resolve.GetVersionString()
+            except Exception:
+                live_version = None
+        result = {
+            "verified_on": _API_TRUTH_VERIFIED_ON,
+            "count": len(facts),
+            "facts": _resolve_versions.annotate_facts(
+                facts, live_version, ledger_verified_on=_API_TRUTH_VERIFIED_ON
+            ),
+        }
+        if live_version:
+            result["live_version"] = str(live_version)
+            unavailable = _resolve_versions.gates_unavailable_on(live_version)
+            if unavailable:
+                result["unavailable_on_this_build"] = unavailable
+        else:
+            result["version_context"] = (
+                "No live build known, so facts are unannotated. The scripting API "
+                "changes per PATCH release, so a fact measured on another build is a "
+                "prior rather than a finding. Pass resolve_version, or call "
+                "get_version first."
+            )
+        return result
+    if action == "check_version_support":
+        # "Does THIS build have it?" asked directly, instead of inferred from
+        # prose. Answers `unknown` unless a gate is recorded — see
+        # utils/resolve_versions.py for why that default is the load-bearing one.
+        live_version = p.get("resolve_version")
+        if not live_version and resolve is not None:
+            try:
+                live_version = resolve.GetVersionString()
+            except Exception:
+                live_version = None
+        if not live_version:
+            return _err(
+                "No Resolve version available",
+                code="VERSION_UNKNOWN",
+                category="invalid_input",
+                reason="Nothing is connected and no resolve_version was passed.",
+                remediation="Call get_version first, or pass resolve_version='21.0.4.5'.",
+            )
+        symbol = p.get("symbol")
+        if symbol:
+            return {
+                "live_version": str(live_version),
+                "support": _resolve_versions.availability(symbol, live_version),
+            }
+        return {
+            "live_version": str(live_version),
+            "unavailable_on_this_build": _resolve_versions.gates_unavailable_on(live_version),
+            "known_gates": len(_resolve_versions.VERSION_GATES),
+            "note": (
+                "Only surfaces with recorded evidence appear here. Most of the "
+                "scripting API has never been version-bisected, so an absence from "
+                "this list is not a promise that a method exists."
+            ),
+        }
     if action == "verification_stats":
         # Process-level readback-verification tally — no connection needed.
         stats = _verification_stats()
@@ -13737,7 +13816,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return missing
         r.DisableBackgroundTasksForCurrentResolveSession()
         return _ok()
-    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","verification_stats","job_status","list_jobs","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────
@@ -16028,6 +16107,9 @@ _RENDER_SETTING_KEYS = [
     "ReplaceExistingFilesInPlace",
     "ExportSubtitle",
     "SubtitleFormat",
+    "UseFullExtents",
+    "AddFrameHandles",
+    "DataBurnIn",
 ]
 
 _RENDER_KERNEL_ACTIONS = [
@@ -16247,6 +16329,24 @@ def _render_preset_pin(proj, preset_name: str):
     return {"preset": preset_name, "loaded": True}, None
 
 
+def _render_settings_warnings(settings: Dict[str, Any]):
+    """Inter-key combinations Resolve accepts and then silently ignores.
+
+    SetRenderSettings returns True for these, so nothing downstream would ever
+    tell the caller the key did nothing — the same silent-no-op class as the
+    unknown-key drop that `_filter_to_keys` covers on the set path.
+    """
+    warnings = []
+    if not isinstance(settings, dict):
+        return warnings
+    if settings.get("UseFullExtents") is True and isinstance(settings.get("AddFrameHandles"), int) and settings["AddFrameHandles"] > 0:
+        warnings.append(
+            "AddFrameHandles is ignored while UseFullExtents is true: Resolve renders the "
+            "clip's full extents and the handle count silently does nothing. Drop one of the two."
+        )
+    return warnings
+
+
 def _validate_render_settings_payload(settings: Dict[str, Any], *, require_temp_target: bool = False):
     if not isinstance(settings, dict) or not settings:
         return None, _err("settings must be a non-empty object")
@@ -16262,15 +16362,20 @@ def _validate_render_settings_payload(settings: Dict[str, Any], *, require_temp_
             errors.append("TargetDir must be under the system temp directory for this safe operation")
     elif require_temp_target:
         errors.append("TargetDir is required for this safe operation")
-    for key in ("FormatWidth", "FormatHeight", "MarkIn", "MarkOut", "AudioBitDepth", "AudioSampleRate"):
+    for key in ("FormatWidth", "FormatHeight", "MarkIn", "MarkOut", "AudioBitDepth", "AudioSampleRate", "AddFrameHandles"):
         if key in settings and not isinstance(settings[key], int):
             errors.append(f"{key} must be an integer")
-    for key in ("SelectAllFrames", "ExportVideo", "ExportAudio", "ExportAlpha", "MultiPassEncode", "NetworkOptimization", "ReplaceExistingFilesInPlace", "ExportSubtitle"):
+    for key in ("SelectAllFrames", "ExportVideo", "ExportAudio", "ExportAlpha", "MultiPassEncode", "NetworkOptimization", "ReplaceExistingFilesInPlace", "ExportSubtitle", "UseFullExtents"):
         if key in settings and not isinstance(settings[key], bool):
             errors.append(f"{key} must be a boolean")
+    if "AddFrameHandles" in settings and isinstance(settings["AddFrameHandles"], int) and settings["AddFrameHandles"] < 0:
+        errors.append("AddFrameHandles must be >= 0")
+    if "DataBurnIn" in settings and not isinstance(settings["DataBurnIn"], str):
+        errors.append("DataBurnIn must be a string (a burn-in preset name, 'Same as project', or 'None')")
     if "MarkIn" in settings and "MarkOut" in settings and settings["MarkOut"] < settings["MarkIn"]:
         errors.append("MarkOut must be greater than or equal to MarkIn")
-    result = {"valid": not errors, "unknown_keys": unknown, "errors": errors, "settings": dict(settings)}
+    result = {"valid": not errors, "unknown_keys": unknown, "errors": errors,
+              "warnings": _render_settings_warnings(settings), "settings": dict(settings)}
     return result, None
 
 
@@ -16721,7 +16826,12 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
       set_mode(mode) -> {success}
       get_resolutions(format, codec) -> {resolutions}
       get_settings() -> {settings}  (alias for set_render_settings with get)
-      set_settings(settings) -> {success}
+      set_settings(settings) -> {success, ignored_settings?, warnings?}
+        Resolve 21.0.4+ settings keys: UseFullExtents (bool),
+        AddFrameHandles (int >= 0), DataBurnIn (burn-in preset name,
+        "Same as project", or "None"). AddFrameHandles is ignored while
+        UseFullExtents is true — the call still succeeds, so that pairing
+        comes back in warnings rather than silently doing nothing.
       list_presets() -> {presets}
       load_preset(name) -> {success}
       save_preset(name) -> {success}
@@ -16845,6 +16955,11 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         result = {"success": bool(proj.SetRenderSettings(settings))}
         if ignored_settings:
             result["ignored_settings"] = ignored_settings
+        # Accepted-then-ignored key combinations (21.0.4 AddFrameHandles under
+        # UseFullExtents) read as a clean success without this.
+        warnings = _render_settings_warnings(settings)
+        if warnings:
+            result["warnings"] = warnings
         return result
     elif action == "list_presets":
         return {"presets": proj.GetRenderPresetList()}
@@ -17672,6 +17787,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       get_mark_in_out(clip_id) -> {mark}
       set_mark_in_out(clip_id, mark_in, mark_out, type?) -> {success}
       clear_mark_in_out(clip_id, type?) -> {success}
+      get_timeline(clip_id) -> {is_timeline, timeline: {name, unique_id?, start_frame?, end_frame?}}
+        — Resolve 21.0.4+. Resolves a Media Pool timeline entry to its timeline
+          object summary; is_timeline=false for ordinary clips.
       open_in_viewer(clip_id, page?, mark_in_seconds?, mark_out_seconds?, clear_marks?) -> {success, clip_id, clip_name, folder_name, page, mark_set}
         — Switches to Media page (default) and selects the clip in the bin.
           Resolve auto-loads the selected clip into the source viewer on Media page.
@@ -18000,7 +18118,28 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"success": bool(clip.SetMarkInOut(clean["mark_in"], clean["mark_out"], p.get("type", "all")))}
     elif action == "clear_mark_in_out":
         return {"success": bool(clip.ClearMarkInOut(p.get("type", "all")))}
-    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","extract_frames","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer"])
+    elif action == "get_timeline":
+        missing = _requires_method(clip, "GetTimeline", "21.0.4")
+        if missing:
+            return missing
+        try:
+            tl_obj = clip.GetTimeline()
+        except Exception as exc:
+            return _err(f"GetTimeline failed: {exc}")
+        if not tl_obj:
+            return {"is_timeline": False, "timeline": None,
+                    "note": "This media pool item is not a timeline entry."}
+        summary = {}
+        for getter, key in (("GetName", "name"), ("GetUniqueId", "unique_id"),
+                            ("GetStartFrame", "start_frame"), ("GetEndFrame", "end_frame")):
+            if _has_method(tl_obj, getter):
+                try:
+                    summary[key] = getattr(tl_obj, getter)()
+                except Exception:
+                    pass
+        return {"is_timeline": True, "timeline": summary,
+                "note": "Address this timeline by name via the timeline tool."}
+    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","extract_frames","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer","get_timeline"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════