davinci-resolve-mcp 2.87.1 → 2.88.0

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 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.88.0
+
+The twelve Resolve 21.0.4 surfaces that only existed on the compound server now
+exist on the granular one too. Issue #140, PR #142 by @legionsound.
+
+### Added
+
+- **Twelve granular tools closing the 21.0.4 delta.** `get_layout_preset_list`,
+  `get_burn_in_preset_list` and `delete_burn_in_preset`; the six
+  `*_user_preferences_preset` tools; `get_project_attributes_in_current_folder`;
+  `get_clip_timeline`; and `get_selected_timeline_items`. Each is guarded with
+  `_requires_method` at 21.0.4, so an older build gets a named version error
+  rather than an attribute crash, and each returns the same shape its compound
+  counterpart does. `get_selected_timeline_items` is deliberately not called
+  `get_selected_clips` — that name belongs to the Media Pool selection tool, and
+  the collision was the confusion the issue reported. The granular server is now
+  353 tools.
+- **`load_user_preferences_preset` carries the SESSION-WIDE warning** in its
+  docstring, matching the compound action. It swaps the user's global Resolve
+  preferences, not a project setting.
+
+### Fixed
+
+- **Four places still said 341 after the count moved to 353, and the guard that
+  exists to catch exactly that was not looking at any of them.** The literal in
+  `tests/test_import.py` was the one that bit: that file is pytest-style, so
+  `unittest discover` never collects it, and a green 2560-test run said nothing
+  while `python tests/test_import.py` — the smoke step in the publish workflow
+  and step one of the release process — failed. The other three were the startup
+  log line in `src/resolve_mcp_server.py`, `docs/install.md` (which had also been
+  quoting 32 compound tools since the compound server reached 34), and the badge,
+  server-modes table and metrics table in `README.zh-CN.md`. All six files are in
+  `test_doc_tool_counts` now, along with the English README's Tools badge, so the
+  next count change fails offline instead of at publish time.
+
+### Validation
+
+- 2560 offline tests OK; `python tests/test_import.py` exits 0; agent-rules
+  drift check in sync.
+- The twelve 21.0.4 methods were exercised live on Studio 21.0.4.5 by the
+  contributor — full round-trips for the layout, burn-in and user-preferences
+  preset families, project attributes across 8 projects, and both branches of
+  `get_clip_timeline`. `LoadUserPreferencesPreset` was deliberately not executed,
+  by them or here. The validation machine for this repo runs 19.1.3, so the live
+  results stay attributed to the reporter in `docs/reference/api-coverage.md`.
+- What could be checked live here was: against a running Studio 19.1.3.7, the
+  new tools return their named `requires DaVinci Resolve 21.0.4+` error rather
+  than crashing on a missing attribute — the guard path exercised against a real
+  Resolve object, not a stub.
+
+## 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

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.87.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.88.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
-[![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(353%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -100,7 +100,7 @@ The command starts a localhost server and opens the control panel in your browse
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 34 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 341 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 353 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -262,7 +262,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **34** compound / **341** granular (live server) |
+| MCP Tools | **34** compound / **353** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.87.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.88.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
-[![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(353%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![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.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.88.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -76,7 +76,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 34 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 341 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 353 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -190,7 +190,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **34** 复合 / **341** 细粒度（实时服务器） |
+| MCP 工具 | **34** 复合 / **353** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -158,7 +158,7 @@ before mutating Resolve state.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 34 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 341 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 353 tools | Power users needing one tool per API method |
 
 This skill document covers the **compound server** (the default). Each compound
 tool accepts an `action` string and an optional `params` object.

package/docs/contributing.md

@@ -64,7 +64,7 @@ davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
 │   ├── server.py                # Compound MCP server — 34 tools (default)
-│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 341 tools
+│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 353 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers
 ├── tests/                       # offline suite (test_*.py) + live harnesses (live_*.py):

package/docs/install.md

@@ -132,8 +132,8 @@ The MCP server comes in two modes:
 
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
-| **Compound** (default) | `src/server.py` | 32 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 341 | Power users who want one tool per API method |
+| **Compound** (default) | `src/server.py` | 34 | Most users — fast, clean, low context usage |
+| **Full** | `src/resolve_mcp_server.py` | 353 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -148,7 +148,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 341-tool server
+python src/server.py --full    # Launch full 353-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -6,7 +6,7 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **34** compound (default) / **341** granular |
+| MCP Tools | **34** compound (default) / **353** granular |
 | Kernel Actions | **136** guarded MCP workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |
 | Methods Live Tested | **338/361** (93.6%) |
@@ -17,7 +17,7 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 ## API Coverage
 
-Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **34 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **341 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
+Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **34 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **353 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
 
 The 34th compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the

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.1"
+VERSION = "2.88.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.87.1",
+  "version": "2.88.0",
   "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.1"
+VERSION = "2.88.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/media_pool_item.py

@@ -1018,3 +1018,41 @@ def remove_clip_motion_blur(clip_id: str, deblur_option: Optional[Dict[str, Any]
     if not new_clip:
         return {"success": False}
     return {"success": True, "new": new_clip.GetName(), "new_id": new_clip.GetUniqueId()}
+
+
+@mcp.tool()
+def get_clip_timeline(clip_id: str) -> Dict[str, Any]:
+    """Resolve a Media Pool timeline entry to its timeline summary (Resolve 21.0.4+).
+
+    Calls MediaPoolItem.GetTimeline(). Returns is_timeline=false for ordinary
+    clips — that is an answer, not a failure.
+
+    Args:
+        clip_id: Unique ID of the Media Pool item.
+    """
+    _, mp, err = _get_mp()
+    if err:
+        return err
+    clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
+    if not clip:
+        return {"error": f"Clip {clip_id} not found"}
+    missing = _requires_method(clip, "GetTimeline", "21.0.4")
+    if missing:
+        return missing
+    try:
+        tl_obj = clip.GetTimeline()
+    except Exception as exc:
+        return {"error": 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")):
+        method = getattr(tl_obj, getter, None)
+        if callable(method):
+            try:
+                summary[key] = method()
+            except Exception:
+                pass
+    return {"is_timeline": True, "timeline": summary}

package/src/granular/project.py

@@ -1667,3 +1667,21 @@ def generate_speech(text_input: str, voice_model: str = "", timecode: str = "",
     if not new_item:
         return {"success": False, "error": "GenerateSpeech returned no media item"}
     return {"success": True, "new": new_item.GetName(), "new_id": new_item.GetUniqueId()}
+
+
+@mcp.tool()
+def get_project_attributes_in_current_folder() -> Dict[str, Any]:
+    """Get per-project attributes for every project in the current folder (Resolve 21.0.4+).
+
+    Calls ProjectManager.GetProjectAttributesInCurrentFolder(). Returns a dict
+    keyed by project name with 'lastModifiedDate', 'creationDate', 'notes' and
+    'liveCollaborationMode' — without loading any project.
+    """
+    project_manager = get_project_manager()
+    if not project_manager:
+        return {"error": "Failed to get Project Manager"}
+    missing = _requires_method(project_manager, "GetProjectAttributesInCurrentFolder", "21.0.4")
+    if missing:
+        return missing
+    attributes = project_manager.GetProjectAttributesInCurrentFolder()
+    return {"projects": attributes if attributes else {}}

package/src/granular/resolve_control.py

@@ -536,3 +536,172 @@ def quit_resolve() -> Dict[str, Any]:
         return {"error": "Not connected to DaVinci Resolve"}
     resolve.Quit()
     return {"success": True, "message": "DaVinci Resolve is quitting"}
+
+
+@mcp.tool()
+def get_layout_preset_list() -> Dict[str, Any]:
+    """Get the names of all saved UI layout presets (Resolve 21.0.4+).
+
+    Calls Resolve.GetLayoutPresetList(). These are the names accepted by
+    load_layout_preset_tool, update_layout_preset, export_layout_preset_tool
+    and delete_layout_preset_tool.
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "GetLayoutPresetList", "21.0.4")
+    if missing:
+        return missing
+    presets = resolve.GetLayoutPresetList()
+    return {"presets": presets if presets else []}
+
+
+@mcp.tool()
+def get_burn_in_preset_list() -> Dict[str, Any]:
+    """Get the names of all saved data burn-in presets (Resolve 21.0.4+).
+
+    Calls Resolve.GetBurnInPresetList(). These are the names accepted by the
+    'DataBurnIn' render setting, project load_burn_in_preset, and
+    export_burn_in_preset.
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "GetBurnInPresetList", "21.0.4")
+    if missing:
+        return missing
+    presets = resolve.GetBurnInPresetList()
+    return {"presets": presets if presets else []}
+
+
+@mcp.tool()
+def delete_burn_in_preset(preset_name: str) -> Dict[str, Any]:
+    """Delete a data burn-in preset by name (Resolve 21.0.4+).
+
+    Args:
+        preset_name: Name of the burn-in preset to delete.
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "DeleteBurnInPreset", "21.0.4")
+    if missing:
+        return missing
+    result = resolve.DeleteBurnInPreset(preset_name)
+    return {"success": bool(result), "preset_name": preset_name}
+
+
+@mcp.tool()
+def get_user_preferences_preset_list() -> Dict[str, Any]:
+    """Get the names of all saved user-preferences presets (Resolve 21.0.4+).
+
+    Calls Resolve.GetUserPreferencesPresetList().
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "GetUserPreferencesPresetList", "21.0.4")
+    if missing:
+        return missing
+    presets = resolve.GetUserPreferencesPresetList()
+    return {"presets": presets if presets else []}
+
+
+@mcp.tool()
+def save_user_preferences_preset(preset_name: str) -> Dict[str, Any]:
+    """Save the current user preferences as a named preset (Resolve 21.0.4+).
+
+    Args:
+        preset_name: Name for the new user-preferences preset.
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "SaveUserPreferencesPreset", "21.0.4")
+    if missing:
+        return missing
+    result = resolve.SaveUserPreferencesPreset(preset_name)
+    return {"success": bool(result), "preset_name": preset_name}
+
+
+@mcp.tool()
+def load_user_preferences_preset(preset_name: str) -> Dict[str, Any]:
+    """Load a user-preferences preset (Resolve 21.0.4+).
+
+    SESSION-WIDE: this swaps the user's global Resolve preferences, not a
+    project setting. It affects every project open in this Resolve instance.
+    Only call when the user explicitly asked for the switch.
+
+    Args:
+        preset_name: Name of the user-preferences preset to load.
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "LoadUserPreferencesPreset", "21.0.4")
+    if missing:
+        return missing
+    result = resolve.LoadUserPreferencesPreset(preset_name)
+    return {"success": bool(result), "preset_name": preset_name}
+
+
+@mcp.tool()
+def delete_user_preferences_preset(preset_name: str) -> Dict[str, Any]:
+    """Delete a user-preferences preset by name (Resolve 21.0.4+).
+
+    Args:
+        preset_name: Name of the user-preferences preset to delete.
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "DeleteUserPreferencesPreset", "21.0.4")
+    if missing:
+        return missing
+    result = resolve.DeleteUserPreferencesPreset(preset_name)
+    return {"success": bool(result), "preset_name": preset_name}
+
+
+@mcp.tool()
+def import_user_preferences_preset(import_path: str, preset_name: str = None) -> Dict[str, Any]:
+    """Import a user-preferences preset from a file (Resolve 21.0.4+).
+
+    The imported preset is NOT auto-loaded; it takes its name from the file
+    when preset_name is omitted (measured on Studio 21.0.4.5). Follow with
+    load_user_preferences_preset to activate it.
+
+    Args:
+        import_path: Absolute path to the preset file to import.
+        preset_name: Name to save the imported preset as (filename if None).
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "ImportUserPreferencesPreset", "21.0.4")
+    if missing:
+        return missing
+    if preset_name:
+        result = resolve.ImportUserPreferencesPreset(import_path, preset_name)
+    else:
+        result = resolve.ImportUserPreferencesPreset(import_path)
+        preset_name = os.path.splitext(os.path.basename(import_path))[0]
+    return {"success": bool(result), "preset_name": preset_name, "import_path": import_path,
+            "note": "The imported preset is not auto-loaded; use load_user_preferences_preset to activate it."}
+
+
+@mcp.tool()
+def export_user_preferences_preset(preset_name: str, export_path: str) -> Dict[str, Any]:
+    """Export a user-preferences preset to a file (Resolve 21.0.4+).
+
+    Args:
+        preset_name: Name of the user-preferences preset to export.
+        export_path: Absolute path where the preset file will be saved.
+    """
+    resolve = get_resolve()
+    if resolve is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(resolve, "ExportUserPreferencesPreset", "21.0.4")
+    if missing:
+        return missing
+    result = resolve.ExportUserPreferencesPreset(preset_name, export_path)
+    return {"success": bool(result), "preset_name": preset_name, "export_path": export_path}

package/src/granular/timeline.py

@@ -1087,3 +1087,33 @@ def set_timeline_setting(setting_name: str, setting_value: str) -> Dict[str, Any
         return err
     result = tl.SetSetting(setting_name, setting_value)
     return {"success": bool(result), "setting_name": setting_name, "setting_value": setting_value}
+
+
+@mcp.tool()
+def get_selected_timeline_items() -> Dict[str, Any]:
+    """Get the timeline items currently selected in the timeline (Resolve 21.0.4+).
+
+    Calls Timeline.GetSelectedClips() on the current timeline. An empty list
+    means nothing is selected — that is an answer, not a failure. (Distinct
+    from get_selected_clips, which reads the Media Pool selection.)
+    """
+    _, tl, err = _get_timeline()
+    if err:
+        return err
+    missing = _requires_method(tl, "GetSelectedClips", "21.0.4")
+    if missing:
+        return missing
+    items = tl.GetSelectedClips() or []
+    summaries = []
+    for item in items:
+        entry = {}
+        for getter, key in (("GetName", "name"), ("GetUniqueId", "unique_id"),
+                            ("GetStart", "start"), ("GetEnd", "end")):
+            method = getattr(item, getter, None)
+            if callable(method):
+                try:
+                    entry[key] = method()
+                except Exception:
+                    pass
+        summaries.append(entry)
+    return {"count": len(summaries), "items": summaries}

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (341 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (353 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -8,10 +8,10 @@ Each tool groups related operations via an 'action' parameter.
 
 Usage:
     python src/server.py              # Start the MCP server
-    python src/server.py --full       # Start the 341-tool granular server instead
+    python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.87.1"
+VERSION = "2.88.0"
 
 import base64
 import os
@@ -16017,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]:
@@ -16026,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}
@@ -16062,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":
@@ -21402,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}
@@ -21762,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")
@@ -27736,9 +27796,9 @@ if __name__ == "__main__":
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
     _install_threaded_tool_dispatch(mcp)
 
-    # Support --full flag to run the 341-tool granular server instead
+    # Support --full flag to run the 353-tool granular server instead
     if "--full" in sys.argv:
-        logger.info("Starting full 341-tool granular server...")
+        logger.info("Starting full 353-tool granular server...")
         sys.argv = [arg for arg in sys.argv if arg != "--full"]
         from src.granular import mcp as granular_mcp
 

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",
     },