davinci-resolve-mcp 2.87.2 → 2.89.0

package/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 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.89.0
+
+The build gates this server already enforced are now gates an agent can ask
+about, and the capability probe those gates run on no longer lies. Issue #132,
+reported by @magwa101.
+
+### Added
+
+- **`get_version` reports what the connected build is missing.** A new `build`
+  block carries `unavailable_on_this_build` — every recorded API surface this
+  build does not have — plus `known_gates` and the caveat that an absence from
+  that list is not a promise a method exists. #132 happened in a session that
+  opened with `get_version` and was told a number and nothing the number ruled
+  out. `get_resolve_version_fields` gains the same list on the granular server.
+- **The version-gate registry went from 7 recorded surfaces to 41.**
+  `_requires_method(obj, "GetLayoutPresetList", "21.0.4")` appears 44 times
+  across the two servers and gates 31 distinct symbols, but
+  `check_version_support` — the call `resolve-session` step 2 tells an agent to
+  make — answered from a ledger that knew seven of them. So the one question an
+  agent is instructed to ask returned `unknown` for surfaces this server was
+  already routing on. On Studio 19.1.3.7 the session preflight named 7 missing
+  surfaces; it now names 40. The new floors are labelled `documented` rather
+  than `measured`: they come from Blackmagic's release documentation, not a live
+  bisect here, and an agent relaying one should be able to say which.
+- **`tests/test_version_gate_drift.py`** fails when a call site and the ledger
+  disagree, and when a bare method name is gated at two different builds on two
+  different classes (which would make a bare-name lookup a coin flip). A table
+  copied by hand is exactly what drifts back apart.
+- **`src/utils/resolve_probe.py`** — `has_method` and `api_constant`, with the
+  measurement behind them. A companion guard fails the suite on a bare `hasattr`
+  with a Resolve-shaped attribute name.
+
+### Fixed
+
+- **29 capability probes across `src/` used `hasattr` on Resolve API objects,
+  where it is a constant `True`** (measured on Studio 19.1.3.7 across 42 checks,
+  recorded in `api_truth`; re-confirmed live for this release —
+  `hasattr(project, 'GenerateSpeech')` returns `True` on a build that has no
+  such method). It failed in two shapes that look nothing alike:
+  - `if not hasattr(clip, "RemoveMotionBlur")` is a dead branch, so the
+    "requires Resolve 21+" refusal never fired and the call below it raised
+    `AttributeError` on an older build. Eleven of these were the granular
+    server's Resolve 21 AI guards.
+  - `getattr(r, n) if hasattr(r, n) else n` never reaches its `else`, so a build
+    without the constant got `None` where the author wrote a string fallback —
+    no exception, no refusal, just a `None` travelling on into `Export()`. This
+    reached granular timeline export and `ExportLUT`, and three constant
+    lookups on the compound server. Confirmed live: a name Resolve does not
+    define returned `None` under the old form and now falls back correctly.
+    The fallback keys on `is None`, not truthiness, because `EXPORT_AAF` is
+    genuinely `0.0`.
+- **The granular AI tools reported a missing Extras pack as success.** Resolve's
+  AI methods return the reason as a *string* when the pack is absent, and
+  `bool("Required package ... is not installed.")` is `True`. The compound
+  server has normalized that since the 21.0.2.4 measurement; the granular one
+  had not, so folder and clip audio classification returned `{"success": true}`
+  for a call that did not run, and `RemoveMotionBlur` / `GenerateSpeech` walked
+  a string into `.GetName()`. All now route through `_ai_result`, which reports
+  the failure and carries Resolve's own reason.
+- **`Project.ApplyFairlightPresetToCurrentTimeline` was recorded on `Timeline`.**
+  The shipped README lists it under Project and the server calls it there; the
+  method's name is what made the wrong attribution look right.
+
+### Validation
+
+Suite 2560 → 2580. Live-checked against the running Studio 19.1.3.7 for the
+probe semantics, the refusal path, the constant fallback, and the `get_version`
+preflight (40 of 41 gates unavailable, as expected on that build). The Resolve 21
+and 21.0.4 surfaces themselves remain untested here — this machine cannot run
+them — and the Extras-pack failure paths are pinned by a stub that reproduces
+the measured attribute-fabrication behaviour rather than by a live 21 build.
+
+## 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,

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.87.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.89.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.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.89.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.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.89.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.
@@ -489,7 +489,16 @@ you are on the correct page first.
 Key actions:
 - `launch` — connect to or start Resolve; call this first if any tool returns a
   "Not connected" error
-- `get_version` — returns `{product, version, version_string}`
+- `get_version` — returns `{product, version, version_string, build, mcp}`.
+  `build.unavailable_on_this_build` lists every recorded API surface this build
+  does **not** have; read it before offering anything version-gated. An absence
+  from that list is not a promise a method exists — most of the API has never
+  been version-bisected, so `check_version_support` answers `unknown` for it,
+  and `unknown` means probe with `name in dir(obj)`, never bare `hasattr`
+  (constant `True` on Resolve objects)
+- `check_version_support(symbol?, resolve_version?)` — is one named symbol on
+  this build? Without `symbol`, the same missing-surface list `get_version`
+  carries. No connection needed when `resolve_version` is passed
 - `api_truth(query?)` — look up behaviorally-verified facts about quirky/unreliable
   Resolve API behavior (no connection needed); filter by substring
 - `verification_stats` — readback-verification tally (verified/contradicted/

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/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.87.2"
+VERSION = "2.89.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.2",
+  "version": "2.89.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -45,6 +45,7 @@ from src.utils.media_analysis_jobs import (
 )
 from src.utils.platform import setup_environment
 from src.utils.resolve_connection import connect_resolve
+from src.utils.resolve_probe import has_method
 from src.utils.analysis_memory import read_panel_state, write_panel_state
 from src.utils import brain_edits as _brain_edits
 from src.utils import timeline_versioning as _timeline_versioning
@@ -11917,7 +11918,7 @@ HTML = HTML.replace("/* CONTROL_PANEL_I18N */", localization_script())
 
 
 def _safe_call(obj: Any, method_name: str, *args: Any) -> Tuple[Any, Optional[str]]:
-    if obj is None or not hasattr(obj, method_name):
+    if not has_method(obj, method_name):
         return None, f"{method_name} unavailable"
     try:
         return getattr(obj, method_name)(*args), None

package/src/granular/common.py

@@ -49,6 +49,8 @@ from src.utils.render_ids import (
     render_format_id_from_formats,
 )
 from src.utils.resolve_connection import connect_resolve
+from src.utils.resolve_probe import api_constant as _api_constant, has_method
+from src.utils.resolve_versions import availability, gates_unavailable_on
 from src.utils.project_properties import (
     get_all_project_properties,
     get_color_settings,
@@ -85,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.87.2"
+VERSION = "2.89.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -741,11 +743,43 @@ def _get_timeline_item(track_type="video", track_index=1, item_index=0):
     return items[item_index], None
 
 def _has_method(obj, method_name):
-    return callable(getattr(obj, method_name, None))
+    # `hasattr` is a constant True on Resolve objects — see src/utils/resolve_probe.
+    return has_method(obj, method_name)
 
 def _requires_method(obj, method_name, min_version):
     if _has_method(obj, method_name):
         return None
     return {"error": f"{method_name} requires DaVinci Resolve {min_version}+"}
 
+def _ai_result(returned):
+    """Normalize a Resolve 21 AI-method return into (ok, message).
+
+    The AI methods do not agree on how they report a missing Extras pack, and
+    one of the two shapes is a trap. Verified live on Studio 21.0.2.4 with only
+    AI Motion Deblur installed:
+
+      - `AnalyzeForSlate`  -> False
+      - `AnalyzeForIntellisearch` -> "Required package 'AI Intellisearch -
+        Faster' is not installed."
+      - `GenerateSpeech`   -> "Required Package, 'AI Speech Generator' is not
+        Installed."
+
+    A non-empty string is truthy, so `bool(returned)` reports success for a call
+    that definitively did not run, and treating the return as a MediaPoolItem
+    raises AttributeError. This is the compound server's `_ai_result`, kept
+    identical on purpose: the granular tools called the same AI methods with a
+    bare `bool()` and inherited the whole trap.
+    """
+    if isinstance(returned, str):
+        return False, returned.strip() or None
+    return bool(returned), None
+
+def _ai_result_payload(returned):
+    """`{"success": ...}` plus the Resolve-supplied reason when there is one."""
+    ok, message = _ai_result(returned)
+    payload = {"success": ok}
+    if message:
+        payload["error"] = message
+    return payload
+
 __all__ = [name for name in globals() if not name.startswith("__")]

package/src/granular/folder.py

@@ -325,9 +325,10 @@ def folder_perform_audio_classification(folder_path: str = "") -> Dict[str, Any]
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "PerformAudioClassification"):
-        return {"error": "PerformAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(folder.PerformAudioClassification())}
+    missing = _requires_method(folder, "PerformAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(folder.PerformAudioClassification())
 
 
 @mcp.tool()
@@ -343,9 +344,10 @@ def folder_clear_audio_classification(folder_path: str = "") -> Dict[str, Any]:
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "ClearAudioClassification"):
-        return {"error": "ClearAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(folder.ClearAudioClassification())}
+    missing = _requires_method(folder, "ClearAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(folder.ClearAudioClassification())
 
 
 @mcp.tool()
@@ -363,9 +365,10 @@ def folder_analyze_for_intellisearch(folder_path: str = "", identify_faces: bool
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "AnalyzeForIntellisearch"):
-        return {"error": "AnalyzeForIntellisearch requires DaVinci Resolve 21+"}
-    return {"success": bool(folder.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))}
+    missing = _requires_method(folder, "AnalyzeForIntellisearch", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(folder.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))
 
 
 @mcp.tool()
@@ -383,11 +386,12 @@ def folder_analyze_for_slate(folder_path: str = "", marker_color: str = "Blue")
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "AnalyzeForSlate"):
-        return {"error": "AnalyzeForSlate requires DaVinci Resolve 21+"}
+    missing = _requires_method(folder, "AnalyzeForSlate", "21.0")
+    if missing:
+        return missing
     if marker_color not in _MARKER_COLORS:
         return {"error": f"Invalid marker_color '{marker_color}'. Valid: {', '.join(_MARKER_COLORS)}"}
-    return {"success": bool(folder.AnalyzeForSlate(marker_color))}
+    return _ai_result_payload(folder.AnalyzeForSlate(marker_color))
 
 
 @mcp.tool()
@@ -407,9 +411,16 @@ def folder_remove_motion_blur(folder_path: str = "", deblur_option: Optional[Dic
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "RemoveMotionBlur"):
-        return {"error": "RemoveMotionBlur requires DaVinci Resolve 21+"}
+    missing = _requires_method(folder, "RemoveMotionBlur", "21.0")
+    if missing:
+        return missing
     result = folder.RemoveMotionBlur(deblur_option or {})
+    # A missing Extras pack comes back as an error STRING, which is truthy and
+    # also iterable — the loop below would walk it character by character and
+    # report success. Normalize before either.
+    ok, message = _ai_result(result)
+    if not ok:
+        return {"success": False, "error": message} if message else {"success": False}
     created = []
     for pair in (result or []):
         try:
@@ -417,4 +428,4 @@ def folder_remove_motion_blur(folder_path: str = "", deblur_option: Optional[Dic
             created.append({"original": orig.GetName(), "new": new.GetName(), "new_id": new.GetUniqueId()})
         except Exception:
             continue
-    return {"success": bool(result), "created": created}
+    return {"success": True, "created": created}

package/src/granular/media_pool_item.py

@@ -17,13 +17,13 @@ def _invalidate_analysis_registry_for_clip(project, clip, *, reason: str) -> Opt
     if project is None or clip is None:
         return None
     try:
-        project_name = project.GetName() if hasattr(project, "GetName") else None
-        project_id = project.GetUniqueId() if hasattr(project, "GetUniqueId") else None
-        clip_id = clip.GetUniqueId() if hasattr(clip, "GetUniqueId") else None
-        media_id = clip.GetMediaId() if hasattr(clip, "GetMediaId") else None
+        project_name = project.GetName() if _has_method(project, "GetName") else None
+        project_id = project.GetUniqueId() if _has_method(project, "GetUniqueId") else None
+        clip_id = clip.GetUniqueId() if _has_method(clip, "GetUniqueId") else None
+        media_id = clip.GetMediaId() if _has_method(clip, "GetMediaId") else None
         source_file = None
         try:
-            source_file = clip.GetClipProperty("File Path") if hasattr(clip, "GetClipProperty") else None
+            source_file = clip.GetClipProperty("File Path") if _has_method(clip, "GetClipProperty") else None
         except Exception:
             source_file = None
         return _mark_analysis_registry_stale(
@@ -930,9 +930,10 @@ def perform_clip_audio_classification(clip_id: str) -> Dict[str, Any]:
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "PerformAudioClassification"):
-        return {"error": "PerformAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(clip.PerformAudioClassification())}
+    missing = _requires_method(clip, "PerformAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(clip.PerformAudioClassification())
 
 
 @mcp.tool()
@@ -948,9 +949,10 @@ def clear_clip_audio_classification(clip_id: str) -> Dict[str, Any]:
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "ClearAudioClassification"):
-        return {"error": "ClearAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(clip.ClearAudioClassification())}
+    missing = _requires_method(clip, "ClearAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(clip.ClearAudioClassification())
 
 
 @mcp.tool()
@@ -968,9 +970,10 @@ def analyze_clip_for_intellisearch(clip_id: str, identify_faces: bool = False, i
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "AnalyzeForIntellisearch"):
-        return {"error": "AnalyzeForIntellisearch requires DaVinci Resolve 21+"}
-    return {"success": bool(clip.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))}
+    missing = _requires_method(clip, "AnalyzeForIntellisearch", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(clip.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))
 
 
 @mcp.tool()
@@ -988,11 +991,12 @@ def analyze_clip_for_slate(clip_id: str, marker_color: str = "Blue") -> Dict[str
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "AnalyzeForSlate"):
-        return {"error": "AnalyzeForSlate requires DaVinci Resolve 21+"}
+    missing = _requires_method(clip, "AnalyzeForSlate", "21.0")
+    if missing:
+        return missing
     if marker_color not in _MARKER_COLORS:
         return {"error": f"Invalid marker_color '{marker_color}'. Valid: {', '.join(_MARKER_COLORS)}"}
-    return {"success": bool(clip.AnalyzeForSlate(marker_color))}
+    return _ai_result_payload(clip.AnalyzeForSlate(marker_color))
 
 
 @mcp.tool()
@@ -1012,9 +1016,51 @@ def remove_clip_motion_blur(clip_id: str, deblur_option: Optional[Dict[str, Any]
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "RemoveMotionBlur"):
-        return {"error": "RemoveMotionBlur requires DaVinci Resolve 21+"}
+    missing = _requires_method(clip, "RemoveMotionBlur", "21.0")
+    if missing:
+        return missing
     new_clip = clip.RemoveMotionBlur(deblur_option or {})
-    if not new_clip:
-        return {"success": False}
+    # An error string is truthy, so a bare `if not new_clip` let a missing
+    # Extras pack through to .GetName() and raised AttributeError.
+    ok, message = _ai_result(new_clip)
+    if not ok:
+        return {"success": False, "error": message} if message else {"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}