davinci-resolve-mcp 2.87.0 → 2.87.2

package/AGENTS.md

@@ -73,7 +73,13 @@ semantics.
   `docs/reference/api-limitations.md` — when you document a new Resolve API
   limitation, add a `submit`-tagged entry to `src/utils/api_truth.py` and
   regenerate with `scripts/gen_api_limitations.py` (a drift guard enforces it)
-- Bundled Resolve API text: `docs/reference/resolve_scripting_api.txt`
+- Bundled Resolve API text: `docs/reference/resolve_scripting_api.txt` — refresh
+  it by copying the shipped `Developer/Scripting/README.txt` over it wholesale,
+  never by hand-adding the lines you already know about. The file's only value
+  is that a diff against it is trustworthy; a hand-patch carries a newer
+  `Last Updated:` header while still hiding everything you did not know to look
+  for. That is exactly how it sat eight weeks stale at 26 May 2026 while ten
+  documented 21.0.4 methods went unwired (PR #139)
 
 ## Key Paths
 

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 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.87.2
+
+A refused `SetSetting` now says why, when the ledger already knows. Issue #141,
+reported by @jus-kim.
+
+### Fixed
+
+- **`project_settings set_setting` returned a bare `{"success": false}` for a
+  key that can never be written.** `Project.SetSetting('timelinePlaybackFrameRate')`
+  refuses every value form, before and after a timeline exists — measured in
+  PR #99, written into `api_truth`, published in `api-limitations.md`, and
+  invisible at the one moment it mattered. A bare `false` reads as *your value
+  was wrong*, which sends a caller into retrying string, int, and float for a
+  key with no writable path at all. A refusal now carries the ledger entry for
+  that key: what is really happening, and the UI step that is the way through.
+  `timeline set_setting` gets the same treatment.
+- The match is deliberately narrow. It requires the exact quoted key on the
+  right object — `Project.SetSetting('x')` will not be handed to a `Timeline`
+  refusal, and a substring like `timeline` will not collect the
+  `timelinePlaybackFrameRate` entry. An unmeasured refusal stays bare, because
+  inventing an explanation for a failure nobody measured is the thing this
+  ledger exists to prevent. The write is always attempted first, so a key that
+  starts working in a later build reports plain success.
+
+### Documentation
+
+- **The `timelinePlaybackFrameRate` ledger entry carries the second report.**
+  Issue #141 confirms it independently on **Resolve 20.2**, against a freshly
+  created project whose timeline rate already read 60 — so a matching
+  `timelineFrameRate` does not unlock the write, which the PR #99 measurement
+  alone left open. The reporter's workaround is now recorded too: for repeat
+  setups, duplicate a project that already carries the wanted playback rate
+  rather than creating one and trying to write it.
+
+## What's New in v2.87.1
+
+Follow-up evidence from @legionsound on PR #139, plus the process fix for the
+tooling failure that PR exposed.
+
+### Changed
+
+- **`import_user_preferences_preset` now says what the preset ended up called.**
+  The no-name path was the one branch in v2.87.0 with nothing behind it — it
+  calls the single-argument binding, which would have been a `TypeError` rather
+  than a graceful failure if the binding wanted two positionals. Round-tripped
+  on Studio 21.0.4.5 (export → delete → import both ways): the single-arg form
+  returns `True`, and the imported preset is **named after the file**. The
+  answer now carries that, so a caller who passed no name knows to read the
+  name back with `list_user_preferences_presets` instead of guessing.
+
+### Documentation
+
+- **`api-coverage.md`: the import/export rows carry the round-trip**, not
+  `dir()` membership. Still 🔬 and still 23 untested of 361 — the counting
+  convention is unchanged, because none of this was executed here. What changed
+  is the strength of the contributor's evidence behind two of the rows.
+- **`AGENTS.md` now states how the API snapshot must be refreshed:** copy the
+  shipped `Developer/Scripting/README.txt` over it wholesale, never hand-add the
+  lines you already know about. A hand-patch carries a newer `Last Updated:`
+  header while hiding everything you did not know to look for — which is
+  precisely how the file sat eight weeks stale at 26 May 2026 while ten
+  documented 21.0.4 methods went unwired. The v2.87.0 snapshot was verified as a
+  wholesale replace (md5 `d732b3f6c1da08dc516bc8f80c5acd92`, byte-identical to
+  the 21.0.4.5 shipped file per the contributor).
+
 ## What's New in v2.87.0
 
 The ten Resolve 21.0.4 scripting surfaces that the 24 Jul 2026 README refresh

package/README.md

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

package/docs/reference/api-coverage.md

@@ -157,7 +157,7 @@ checkable rather than asserted.
 | `Resolve.SaveUserPreferencesPreset` | Requires a Resolve 21.0.4 build; the validation machine runs Studio 19.1.3 and free 21.0.3 | Yes |
 | `Resolve.LoadUserPreferencesPreset` | Deliberately not executed even by the reporter: swaps the user's global preferences session-wide | No |
 | `Resolve.DeleteUserPreferencesPreset` | Requires a Resolve 21.0.4 build; the validation machine runs Studio 19.1.3 and free 21.0.3 | Yes |
-| `Resolve.ImportUserPreferencesPreset` | Requires a Resolve 21.0.4 build and a preset file to import | Yes |
+| `Resolve.ImportUserPreferencesPreset` | Requires a Resolve 21.0.4 build; round-tripped by the reporter on 21.0.4.5 in both call shapes (PR #139), not here | Yes |
 | `Resolve.ExportUserPreferencesPreset` | Requires a Resolve 21.0.4 build; the validation machine runs Studio 19.1.3 and free 21.0.3 | Yes |
 | `PM.GetProjectAttributesInCurrentFolder` | Requires a Resolve 21.0.4 build; the validation machine runs Studio 19.1.3 and free 21.0.3 | Yes |
 
@@ -218,8 +218,8 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 28 | `SaveUserPreferencesPreset(presetName)` | 🔬 | Resolve 21.0.4. Not executed here; part of the issue #138 round-trip on 21.0.4.5 |
 | 29 | `LoadUserPreferencesPreset(presetName)` | 🔬 | Resolve 21.0.4. `dir()`-present on 21.0.4.5; **not executed** even by the reporter — swaps the user's global preferences session-wide (issue #138) |
 | 30 | `DeleteUserPreferencesPreset(presetName)` | 🔬 | Resolve 21.0.4. Not executed here; part of the issue #138 round-trip on 21.0.4.5 |
-| 31 | `ImportUserPreferencesPreset(presetFilePath, presetName)` | 🔬 | Resolve 21.0.4. `dir()`-present on 21.0.4.5 only (issue #138) — no preset file was on hand. Per the README the imported preset is **not** auto-loaded |
-| 32 | `ExportUserPreferencesPreset(presetName, exportPath)` | 🔬 | Resolve 21.0.4. `dir()`-present on 21.0.4.5 only (issue #138) |
+| 31 | `ImportUserPreferencesPreset(presetFilePath, presetName)` | 🔬 | Resolve 21.0.4. Not executed here; reporter's export→delete→import round-trip on 21.0.4.5 (PR #139) covers **both** call shapes — single-arg returns `True` rather than a `TypeError`, and the imported preset is then named after the file; the two-arg form takes the given name. Per the README the imported preset is **not** auto-loaded, and the round-trip did not load either import |
+| 32 | `ExportUserPreferencesPreset(presetName, exportPath)` | 🔬 | Resolve 21.0.4. Not executed here; reported writing the file at the given path with no extension appended, on 21.0.4.5 (PR #139) |
 
 ### ProjectManager
 

package/docs/reference/api-limitations.md

@@ -44,8 +44,8 @@ equivalent, blocking full automation.
 ### Project.SetSetting('timelinePlaybackFrameRate')
 
 - **Object:** `Project`
-- **Behavior:** Returns False for every value form tried (string, int, float), both before and after a timeline exists, so the playback frame rate cannot be set from the API at all. Reported by a community contributor against Resolve Studio while assembling a vertical timeline (PR #99).
-- **Workaround / current handling:** Ask the user to set it in Project Settings > Master Settings > Playback frame rate as a SETUP step, before any timeline exists. Read it back to confirm; do not report it as set on the strength of the call alone.
+- **Behavior:** Returns False for every value form tried (string, int, float), both before and after a timeline exists, so the playback frame rate cannot be set from the API at all. Reported by a community contributor against Resolve Studio while assembling a vertical timeline (PR #99), and independently on Resolve 20.2 against a freshly created project whose timeline rate already read 60 (issue #141) — so a matching timelineFrameRate does not unlock the write.
+- **Workaround / current handling:** Ask the user to set it in Project Settings > Master Settings > Playback frame rate as a SETUP step, before any timeline exists. Read it back to confirm; do not report it as set on the strength of the call alone. The issue #141 reporter's workaround is worth passing on for repeat setups: duplicate a project that already carries the wanted playback rate rather than creating one and trying to write it.
 - **Tags:** project-settings, silent-failure, timeline
 
 ### Timeline.GetCurrentClipThumbnailImage (Color page only)

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.87.0"
+VERSION = "2.87.2"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

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

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.87.0"
+VERSION = "2.87.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.87.0"
+VERSION = "2.87.2"
 
 import base64
 import os
@@ -13589,7 +13589,10 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       delete_user_preferences_preset(name) -> {success}  — Resolve 21.0.4+
       import_user_preferences_preset(path, name?) -> {success}  — Resolve 21.0.4+.
         The imported preset is NOT auto-loaded; follow with
-        load_user_preferences_preset to activate it.
+        load_user_preferences_preset to activate it. Omitting name is safe
+        (reported on 21.0.4.5: single-arg returns True, not a TypeError) and
+        the preset is then named after the file, so pass name when the preset
+        should be called something the filename does not say.
       export_user_preferences_preset(name, path) -> {success}  — Resolve 21.0.4+
       open_control_panel(port?, host?, open_browser?) -> {success, url, pid, port, status}
         — Launches the analysis control panel (src/analysis_dashboard.py) as a background process.
@@ -13862,8 +13865,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             ok = bool(r.ImportUserPreferencesPreset(p["path"], p["name"]))
         else:
             ok = bool(r.ImportUserPreferencesPreset(p["path"]))
-        return {"success": ok,
-                "note": "The imported preset is not auto-loaded; use load_user_preferences_preset to activate it."}
+        note = "The imported preset is not auto-loaded; use load_user_preferences_preset to activate it."
+        if not p.get("name"):
+            note += (" No name was given, so the preset takes its name from the file — "
+                     "list_user_preferences_presets to read it back.")
+        return {"success": ok, "note": note}
     elif action == "export_user_preferences_preset":
         missing = _requires_method(r, "ExportUserPreferencesPreset", "21.0.4")
         if missing:
@@ -16011,6 +16017,37 @@ def project_manager_database(action: str, params: Optional[Dict[str, Any]] = Non
 # TOOL 8: project_settings
 # ═══════════════════════════════════════════════════════════════════════════════
 
+def _setting_limitation(name: Any, obj: str = "Project") -> Optional[Dict[str, Any]]:
+    """The api_truth entry for a settings key on `obj`, when one exists.
+
+    `SetSetting` reports a refusal as a bare `False` with no reason, and for
+    several keys this repo has already measured the reason and written it down —
+    `timelinePlaybackFrameRate` returns False for every value form, before and
+    after a timeline exists (issue #141, PR #99). A caller who gets
+    `{"success": false}` has no way to tell "you passed a bad value" from "this
+    key cannot be written from the API at all", and the second one is a
+    different task: it has to go to the user as a UI step.
+
+    Matched narrowly on purpose. The entry must name this exact key *and* be
+    `obj.SetSetting`, because attaching an unrelated explanation to a failure is
+    worse than attaching none — it reads as a diagnosis. `Project` and
+    `Timeline` both have a `SetSetting` and their keys overlap by name, so the
+    object is part of the match rather than assumed.
+    """
+    if not isinstance(name, str) or not name:
+        return None
+    prefix = f"{obj}.SetSetting"
+    quoted = f"'{name}'"
+    for entry in lookup_api_truth(name):
+        symbol = entry.get("symbol", "")
+        # The quoted form is what makes this an exact key match: `name in
+        # symbol` would hand the timelinePlaybackFrameRate entry to anything
+        # that is a substring of it, "timeline" included.
+        if symbol.startswith(prefix) and quoted in symbol:
+            return entry
+    return None
+
+
 @mcp.tool()
 @_guard_missing_params
 def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -16020,7 +16057,9 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
       get_name() -> {name}
       set_name(name) -> {success}
       get_setting(name?) -> {settings}  — omit name for all settings
-      set_setting(name, value) -> {success}
+      set_setting(name, value) -> {success, known_limitation?}
+        A refusal carries the api_truth entry for that key when one exists —
+        several settings cannot be written from the API at all.
       get_unique_id() -> {id}
       get_presets() -> {presets}
       set_preset(name) -> {success}
@@ -16056,7 +16095,20 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
             return _err("set_setting requires name")
         if "value" not in p:
             return _err("set_setting requires value")
-        return {"success": bool(proj.SetSetting(p["name"], p["value"]))}
+        if bool(proj.SetSetting(p["name"], p["value"])):
+            return {"success": True}
+        known = _setting_limitation(p["name"])
+        if not known:
+            return {"success": False}
+        return {
+            "success": False,
+            "known_limitation": {
+                "symbol": known.get("symbol"),
+                "reality": known.get("reality"),
+                "recommended": known.get("recommended"),
+                "ledger_verified_on": _API_TRUTH_VERIFIED_ON,
+            },
+        }
     elif action == "get_unique_id":
         return {"id": proj.GetUniqueId()}
     elif action == "get_presets":
@@ -21396,7 +21448,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       export(path, type, subtype?, background?) -> {success | job_id}  — type: AAF, EDL, FCPXML, etc.
         UNSAFE. No path sandboxing. Prefer export_timeline_checked.
       get_setting(name?) -> {settings}
-      set_setting(name, value) -> {success}
+      set_setting(name, value) -> {success, known_limitation?}
+        A refusal carries the api_truth entry for that key when one exists.
       insert_generator(name) -> {success}
       insert_fusion_generator(name) -> {success}
       insert_fusion_composition() -> {success}
@@ -21756,7 +21809,20 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "get_setting":
         return {"settings": _ser(tl.GetSetting(p.get("name", "")))}
     elif action == "set_setting":
-        return {"success": bool(tl.SetSetting(p["name"], p["value"]))}
+        if bool(tl.SetSetting(p["name"], p["value"])):
+            return {"success": True}
+        known = _setting_limitation(p["name"], obj="Timeline")
+        if not known:
+            return {"success": False}
+        return {
+            "success": False,
+            "known_limitation": {
+                "symbol": known.get("symbol"),
+                "reality": known.get("reality"),
+                "recommended": known.get("recommended"),
+                "ledger_verified_on": _API_TRUTH_VERIFIED_ON,
+            },
+        }
     elif action == "insert_generator":
         r = tl.InsertGeneratorIntoTimeline(p["name"])
         return _ok() if r else _err("Failed to insert generator")

package/src/utils/api_truth.py

@@ -124,11 +124,18 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "float), both before and after a timeline exists, so the "
                    "playback frame rate cannot be set from the API at all. "
                    "Reported by a community contributor against Resolve Studio "
-                   "while assembling a vertical timeline (PR #99).",
+                   "while assembling a vertical timeline (PR #99), and "
+                   "independently on Resolve 20.2 against a freshly created "
+                   "project whose timeline rate already read 60 (issue #141) — "
+                   "so a matching timelineFrameRate does not unlock the write.",
         "recommended": "Ask the user to set it in Project Settings > Master "
                        "Settings > Playback frame rate as a SETUP step, before "
                        "any timeline exists. Read it back to confirm; do not "
-                       "report it as set on the strength of the call alone.",
+                       "report it as set on the strength of the call alone. The "
+                       "issue #141 reporter's workaround is worth passing on "
+                       "for repeat setups: duplicate a project that already "
+                       "carries the wanted playback rate rather than creating "
+                       "one and trying to write it.",
         "tags": ["project-settings", "silent-failure", "timeline"],
         "submit": "missing",
     },