davinci-resolve-mcp 2.82.0 → 2.86.1

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

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 26 missing capabilities, 29 bugs / unreliable behaviors.
+**Totals:** 27 missing capabilities, 30 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -131,7 +131,7 @@ equivalent, blocking full automation.
 ### Fairlight audio levels / pan / EQ / automation / FairlightFX
 
 - **Object:** `TimelineItem / Timeline`
-- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs AND by live mutating attempt on 21.0.0: SetProperty('Volume'|'Level'|'Gain'|'AudioVolume', 0) all return False (note 'Pan' is the VIDEO transform key, not audio pan, so it misleadingly succeeds). The gap is PER-PARAMETER control specifically: a whole saved mix CAN be applied wholesale via Project.ApplyFairlightPresetToCurrentTimeline(name), with the available names from Resolve.GetFairlightPresets() — so 'no Fairlight write path exists' would be too strong.
+- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs AND by live mutating attempt on 21.0.0: SetProperty('Volume'|'Level'|'Gain'|'AudioVolume', 0) all return False (note 'Pan' is the VIDEO transform key, not audio pan, so it misleadingly succeeds). The gap is PER-PARAMETER control specifically: a whole saved mix CAN be applied wholesale via Project.ApplyFairlightPresetToCurrentTimeline(name), with the available names from Resolve.GetFairlightPresets() — so 'no Fairlight write path exists' would be too strong. Both methods require Resolve 20.2.2+; on 19.1.3 they are absent (confirmed live 2026-08-06), so on older builds the per-parameter gap really is the whole story.
 - **Workaround / current handling:** To reapply a known mix, save it once as a Fairlight preset in the UI and apply it per-timeline with ApplyFairlightPresetToCurrentTimeline (exposed as resolve_control get_fairlight_presets + project_settings apply_fairlight_preset). Dial individual levels/pan/EQ/automation/FairlightFX in the Fairlight UI; beyond presets, only voice-isolation state and channel-mapping reads are scriptable.
 - **Tags:** missing-method, audio, fairlight
 
@@ -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 21.0 (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
@@ -222,6 +222,15 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** SetCurrentFolder to the target bin first (media_pool set_current_folder), import, then restore the previous current folder if it matters.
 - **Tags:** media-pool, import
 
+### SetClipColor (undocumented value space; marker constants are a decoy)
+
+- **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. 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
+
 ### Project.SetCurrentRenderFormatAndCodec
 
 - **Object:** `Project`
@@ -376,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
@@ -443,6 +452,15 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #59](https://github.com/samuelgursky/davinci-resolve-mcp/issues/59)
 - **Tags:** render, deliver, silent-failure, id-vs-label
 
+### TimelineItem.SetClipColor on generator/title items
+
+- **Object:** `TimelineItem`
+- **Signature:** `(colorName) -> bool`
+- **Behavior:** On a generator or title item SetClipColor returns True with a VALID colour name and the colour does not persist — GetClipColor still reads '' immediately afterwards, and ClearClipColor changes nothing because there is nothing to clear. Measured on Studio 19.1.3.7 (2026-08-06) on a Solid Color generator. A media-backed item on the SAME timeline in the same session persists correctly (SetClipColor('Teal') -> True, GetClipColor -> 'Teal'), so the bool is honest for some items and a lie for others, with nothing in the return value to tell them apart. A timeline item's colour is also independent of its backing MediaPoolItem's: colouring the item leaves the pool clip at ''.
+- **Workaround / current handling:** Never trust the bool alone — read GetClipColor back and compare. To mark a generator or title, use a timeline marker at its start instead; markers read back reliably.
+- **Reference:** [issue #124](https://github.com/samuelgursky/davinci-resolve-mcp/issues/124)
+- **Tags:** timeline-item, silent-failure, generator, readback-lies
+
 ### Project.SetRenderSettings (inherits the loaded preset)
 
 - **Object:** `Project`

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.82.0"
+VERSION = "2.86.1"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -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.0",
+  "version": "2.86.1",
   "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 21 (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.0"
+VERSION = "2.86.1"
 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/granular/timeline_item.py

@@ -1,6 +1,7 @@
 """Timeline item property, keyframe, and clip-level tools."""
 
 from src.granular.common import *  # noqa: F401,F403
+from src.utils.clip_colors import clip_color_refusal
 
 resolve = ResolveProxy()
 
@@ -1528,7 +1529,32 @@ def ti_set_clip_color(color: str, item_index: int = 0, track_type: str = "video"
     item, err = _get_timeline_item(track_type, track_index, item_index)
     if err:
         return err
-    return {"success": bool(item.SetClipColor(color))}
+    returned = bool(item.SetClipColor(color))
+    readback = item.GetClipColor() or ""
+    if not returned:
+        refusal = clip_color_refusal(color)
+        return {
+            "success": False,
+            "color": color,
+            "error": f"SetClipColor refused '{color}'",
+            "reason": refusal["reason"],
+            "remediation": refusal["remediation"],
+            "valid_colors": refusal["state"]["valid_colors"],
+        }
+    if readback != color:
+        # Generator and title items take the call, return True, and drop the
+        # colour (issue #124, Studio 19.1.3.7). Media-backed items persist.
+        return {
+            "success": False,
+            "color": color,
+            "readback": readback,
+            "error": "SetClipColor returned True but the colour did not persist",
+            "remediation": (
+                "Generator and title items accept and discard clip colours; colour "
+                "a media-backed item, or use a timeline marker instead."
+            ),
+        }
+    return {"success": True, "color": color, "readback": readback}
 
 
 @mcp.tool()