davinci-resolve-mcp 4.4.2 → 4.5.1

package/CHANGELOG.md

@@ -2,6 +2,135 @@
 
 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 v4.5.1 — the safe-mode refusal reaches the caller on 27 more tools
+
+v4.5.0 gave the granular server a working safe-mode gate. On 27 tools it then threw
+the answer away.
+
+### Fixed
+
+- **A blocked call raised `ToolError` instead of returning the refusal.** FastMCP
+  builds an output schema from a tool's return annotation and validates against it,
+  so handing the block dict to a tool annotated `-> str` failed validation:
+
+  ```
+  ToolError: ...Output / result / Input should be a valid string
+  ```
+
+  The caller received a generic execution error carrying none of the
+  `SAFE_MODE_BLOCKED` code, reason or remediation — the gate fired correctly and its
+  answer was destroyed on the way out. Measured on the real `--full` entry path
+  against shipped v4.5.0: `clear_folder_transcription` raised rather than refusing.
+
+  It lands hardest exactly where it matters. The HIGH-rated string-returning tools
+  are the calls safe mode exists to stop: `clear_folder_transcription`,
+  `unlink_proxy_media`, `replace_clip`, `delete_keyframe`, `quit_app`, `restart_app`.
+
+  A `-> str` tool is now refused with the message and its remediation as text,
+  prefixed with the code. That loses the machine-readable field, which is a real
+  cost and worth stating plainly — but a refusal the client can read beats a
+  `ToolError` that discards it, and it is the only shape that tool's own schema will
+  accept. The 105 tools annotated `-> Dict[str, Any]` or `-> dict` keep the
+  structured envelope unchanged.
+
+### Validation
+
+- Full offline suite: **3,684 passed, 1 skipped, 0 failed**, 1,412 subtests.
+- Both new assertions were confirmed to **fail with the fix reverted**, then pass on
+  restore — the guard is not vacuous.
+- Verified end-to-end through the real registry with `destructive.safe_mode` on: a
+  `-> str` tool returns readable refusal text, a `-> dict` tool returns the full
+  envelope, and `allow_risky_operation=true` still lets a permitted call through on
+  both paths.
+- A static check now walks every destructive-decorated tool annotated `-> str` and
+  asserts the hook would hand it a string, so tool number 28 cannot reintroduce this.
+
+## What's New in v4.5.0 — safe mode and the audit log reach the granular server
+
+v4.4.1 froze 131 destructive-hinted granular tools in a backlog and said plainly
+that nothing enforced anything about them: no safe-mode refusal, no audit row. A
+user running with `destructive.safe_mode` on was protected on the compound server
+and not on the `--full` one, with nothing saying so. This release works that
+backlog to zero.
+
+### Added
+
+- **`@granular_destructive_op()` on every destructive-hinted granular tool** — the
+  131 in the backlog plus `ti_copy_grades`, 132 in all. The hook does two things
+  and only two: while `destructive.safe_mode` is on, a HIGH-risk call is refused
+  unless that call passes `allow_risky_operation: true`; and every call, refused
+  or run, writes a row to the security audit log. A dict result is annotated with
+  `operation_id` and `security` exactly as compound results are; a list, string or
+  boolean result comes back untouched, because several granular tools return
+  those.
+- **`allow_risky_operation` is now a parameter on each hooked tool.** Granular
+  tools have no `params` object for the compound override to live in, so the hook
+  adds the parameter to the tool's own MCP schema (via `__signature__`, which
+  FastMCP honours). Every other property of every schema is unchanged — a test
+  diffs each hooked tool's advertised properties against its original signature.
+- **Risk is rated from the verb, with one ledger override.** `delete`, `remove`,
+  `clear`, `reset`, `replace`, `unlink`, `overwrite`, `quit` and `restart` are
+  HIGH; `set`, `load`, `switch`, `close`, `stop` and `lift` are MEDIUM; anything
+  else is MEDIUM, never HIGH, so an unassessed verb cannot make safe mode
+  over-block. A tool whose body reaches a symbol the `api_truth` ledger marks
+  `destroys_prior_work` takes HIGH from the ledger instead: `ti_copy_grades` rates
+  MEDIUM by verb and HIGH in fact, mechanically, because `CopyGrades` is in the
+  ledger. Flagging a new ledger entry re-rates every tool that reaches it.
+- **The ratchet now counts the hook, and keeps the tiers apart.**
+  `UNGATED_GRANULAR_DESTRUCTIVE` is empty; a new destructive-hinted tool without
+  the hook fails the suite, and so does a hook placed *outside* `@mcp.tool()`
+  (that order registers the bare function — decorated, and enforcing nothing).
+  The `destroys_prior_work` test still demands the full `acknowledge_trap` +
+  confirm-token gate; the enforcement hook does not satisfy it and must not.
+  Enforcement and confirmation are separate tiers — a two-step confirmation on
+  `ti_set_clip_color` would make the granular server unusable.
+- **`tests/test_granular_destructive_op.py`** — refusal, override, audit rows for
+  allowed and blocked calls, an unwritable audit path that cannot break the call,
+  list/scalar passthrough, positional arguments audited by name, and the override
+  travelling end-to-end through FastMCP's `call_tool`.
+
+### Not added, on purpose
+
+- **No archive.** The compound hook duplicates the timeline into an Archive bin
+  before mutating it. Doing that around 132 granular calls would bury a project in
+  versions for operations as small as a clip-colour change. A granular write
+  therefore has **no recovery version**: it is refused, or it is recorded — never
+  recovered. `docs/SKILL.md` and the README now say so rather than implying parity.
+
+### Fixed
+
+- **The first draft of the hook was cosmetic.** It rated verbs `"HIGH"` while the
+  safe-mode gate holds `RiskLevel.HIGH.value == "high"`; nothing matched, and a
+  HIGH tool ran with safe mode on. Reproduced with a probe before the fix, pinned
+  by a vocabulary test that asserts every rating is a `RiskLevel` value, and by a
+  refusal test that asserts the body never ran.
+- **The refusal names the right argument.** On the granular server the override
+  is `allow_risky_operation=true` on the call, not `params.allow_risky_operation`;
+  the message and remediation say which.
+
+### Validation
+
+- Static checks: API parity audit, api-limitations, read/write symmetry,
+  agent-rules, release-surface drift, `git diff --check`.
+- Full offline suite: 3679 passed, 1 skipped, 0 failed, 1412 subtests (v4.4.2 baseline plus the new guards; no count drop).
+- Every new guard was made to fail before it was trusted — nine regressions were
+  re-introduced one at a time and restored from a byte copy: hook removed (fails),
+  hook outside `@mcp.tool` (fails), bare `@granular_destructive_op` without
+  parentheses (the granular package no longer imports — pydantic cannot build a
+  schema for the decorator factory), `"HIGH"` casing (3 tests fail), a list result
+  mutated (fails), the ledger override removed (2 fail), the confirm-token
+  redemption dropped from `ti_copy_grades` with the hook still present (the
+  confirmation-tier test fails on its own), `__signature__` not set (133 fail — the
+  override never reaches the hook), and an audit write error re-raised (fails).
+- Live, DaVinci Resolve Studio 19.1.3.7, on a disposable project: with safe mode
+  on, `set_project_setting` (MEDIUM) ran, returned its plain string untouched and
+  was audited `allowed`; `delete_project` (HIGH) was refused with
+  `SAFE_MODE_BLOCKED` and audited `blocked`; the same call with
+  `allow_risky_operation=true` reached the body and was audited `allowed`. Resolve's
+  own `DeleteProject` returned False for the just-created project, which was also
+  absent from the folder listing before and after — an artifact of an unsaved new
+  project on a PostgreSQL database, not hook behaviour. No project was left behind.
+
 ## What's New in v4.4.2 — a refused option now says which one, and why
 
 Reported as [#232](https://github.com/samuelgursky/davinci-resolve-mcp/issues/232):

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.4.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.5.1-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-37%20(387%20full)-blue.svg)](#server-modes)
@@ -404,7 +404,7 @@ This project treats camera originals and source media as immutable. Analysis too
 
 ## Security Posture
 
-The default server is a local stdio process launched by your MCP client; it does not expose a network listener or built-in multi-user auth surface. The two opt-in local HTTP surfaces — the control panel and the networked MCP transport — bind loopback only and require a per-launch bearer token on every request, with Host/Origin checks against DNS rebinding and CSRF. Tool metadata includes MCP client-safety hints for read-only, destructive, idempotent, and external-resource operations. See [Security Policy](SECURITY.md) for operational boundaries, confirmation guidance, and vulnerability reporting.
+The default server is a local stdio process launched by your MCP client; it does not expose a network listener or built-in multi-user auth surface. The two opt-in local HTTP surfaces — the control panel and the networked MCP transport — bind loopback only and require a per-launch bearer token on every request, with Host/Origin checks against DNS rebinding and CSRF. Tool metadata includes MCP client-safety hints for read-only, destructive, idempotent, and external-resource operations. Destructive writes on both servers honour `destructive.safe_mode` and the security audit log; only the compound server archives a timeline before mutating it — granular writes are refused or recorded, never recovered. See [Security Policy](SECURITY.md) for operational boundaries, confirmation guidance, and vulnerability reporting.
 
 ## Key Stats
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.4.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.5.1-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-37%20(387%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)
 
-> 本翻译对应 v4.4.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.5.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -220,7 +220,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 ## 安全态势
 
-默认服务器是由你的 MCP 客户端启动的本地 stdio 进程；它不暴露网络监听器，也没有内置多用户认证面。两个可选的本地 HTTP 面——控制面板与联网 MCP 传输——仅绑定回环地址，每个请求都需要每次启动生成的 bearer 令牌，并校验 Host/Origin 以防 DNS 重绑定和 CSRF。工具元数据包含面向 MCP 客户端的安全提示（只读、破坏性、幂等、外部资源操作）。操作边界、确认指引和漏洞报告见 [安全策略](SECURITY.md)。
+默认服务器是由你的 MCP 客户端启动的本地 stdio 进程；它不暴露网络监听器，也没有内置多用户认证面。两个可选的本地 HTTP 面——控制面板与联网 MCP 传输——仅绑定回环地址，每个请求都需要每次启动生成的 bearer 令牌，并校验 Host/Origin 以防 DNS 重绑定和 CSRF。工具元数据包含面向 MCP 客户端的安全提示（只读、破坏性、幂等、外部资源操作）。两个服务器上的破坏性写入都遵守 `destructive.safe_mode` 并写入安全审计日志；只有复合服务器会在修改前归档时间线——细粒度写入只会被拒绝或被记录，绝不会被恢复。操作边界、确认指引和漏洞报告见 [安全策略](SECURITY.md)。
 
 ## 关键数据
 

package/docs/SKILL.md

@@ -362,6 +362,21 @@ and blanking in both server interfaces. These readers do not invoke setters.
 This skill document covers the **compound server** (the default). Each compound
 tool accepts an `action` string and an optional `params` object.
 
+**Granular writes are enforced, not archived.** Every destructive-hinted granular
+tool (deletes, clears, resets, replaces, sets, loads — 132 of the 387) runs
+through `granular_destructive_op`: while `destructive.safe_mode` is on, a
+HIGH-risk call is refused unless that call passes `allow_risky_operation: true`
+(a parameter the hook adds to each hooked tool's schema), and every call writes
+a row to the security audit log. Risk is read from the verb — `delete`/`remove`/
+`clear`/`reset`/`replace`/`unlink`/`quit`/`restart` are HIGH, `set`/`load`/
+`switch`/`close`/`stop` are MEDIUM — except that a tool reaching a symbol the
+`api_truth` ledger marks `destroys_prior_work` is HIGH from the ledger
+(`ti_copy_grades`), and those tools also keep their `acknowledge_trap` +
+confirm-token gate. What the granular hook does **not** do is duplicate the
+timeline into an Archive bin first, as the compound hook does: a granular write
+has no recovery version, and a refused-or-audited call is the whole of its
+safety. Use the compound server when you want the archive.
+
 ### The advanced server (`davinci-resolve-advanced-mcp`)
 
 The same package ships an optional third surface: an offline Node server (18

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.4.2"
+VERSION = "4.5.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

package/package.json

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

package/src/granular/common.py

@@ -28,6 +28,7 @@ from src.utils.app_control import (
     restart_resolve_app,
 )
 from src.utils.cdl import normalize_cdl_payload
+from src.utils.destructive_hook import granular_destructive_op
 from src.utils.confirm_tokens import (
     ConfirmTokenStore,
     gate_required_from,
@@ -92,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.4.2"
+VERSION = "4.5.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/folder.py

@@ -111,6 +111,7 @@ def transcribe_folder_audio(folder_name: str, use_speaker_detection: Optional[bo
 
 
 @mcp.tool()
+@granular_destructive_op()
 def clear_folder_transcription(folder_name: str) -> str:
     """Clear audio transcription for all clips in a folder.
     
@@ -277,6 +278,7 @@ def folder_transcribe_audio(folder_path: str = "") -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def folder_clear_transcription(folder_path: str = "") -> Dict[str, Any]:
     """Clear transcription for all clips in a Media Pool folder.
 
@@ -332,6 +334,7 @@ def folder_perform_audio_classification(folder_path: str = "") -> Dict[str, Any]
 
 
 @mcp.tool()
+@granular_destructive_op()
 def folder_clear_audio_classification(folder_path: str = "") -> Dict[str, Any]:
     """Clear audio classification for all clips in a Media Pool folder (Resolve 21+).
 
@@ -395,6 +398,7 @@ def folder_analyze_for_slate(folder_path: str = "", marker_color: str = "Blue")
 
 
 @mcp.tool()
+@granular_destructive_op()
 def folder_remove_motion_blur(folder_path: str = "", deblur_option: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Render motion-deblurred copies of all clips in a folder (Resolve 21+).
 

package/src/granular/gallery.py

@@ -21,6 +21,7 @@ def get_gallery_album_name() -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_gallery_album_name(name: str) -> Dict[str, Any]:
     """Set the name of the current gallery album.
 
@@ -89,6 +90,7 @@ def get_current_still_album() -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_current_still_album(album_index: int) -> Dict[str, Any]:
     """Set the current still album by index.
 
@@ -206,6 +208,7 @@ def get_still_label(album_index: int, still_index: int) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_still_label(album_index: int, still_index: int, label: str) -> Dict[str, Any]:
     """Set the label of a still in a gallery album.
 
@@ -281,6 +284,7 @@ def export_stills_from_album(album_index: int, folder_path: str, file_prefix: st
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_stills_from_album(album_index: int, still_indices: List[int]) -> Dict[str, Any]:
     """Delete stills from a gallery album.
 

package/src/granular/graph.py

@@ -25,6 +25,7 @@ def graph_get_num_nodes(item_index: int = 0, track_type: str = "video", track_in
 
 
 @mcp.tool()
+@granular_destructive_op()
 def graph_set_lut(node_index: int, lut_path: str, item_index: int = 0, track_type: str = "video", track_index: int = 1) -> Dict[str, Any]:
     """Set LUT on a node in the color graph.
 
@@ -83,6 +84,7 @@ def graph_get_lut(node_index: int, item_index: int = 0, track_type: str = "video
 
 
 @mcp.tool()
+@granular_destructive_op()
 def graph_set_node_cache_mode(node_index: int, cache_value: int, item_index: int = 0, track_type: str = "video", track_index: int = 1) -> Dict[str, Any]:
     """Set the cache mode on a node.
 
@@ -165,6 +167,7 @@ def graph_get_tools_in_node(node_index: int, item_index: int = 0, track_type: st
 
 
 @mcp.tool()
+@granular_destructive_op()
 def graph_set_node_enabled(node_index: int, is_enabled: bool, item_index: int = 0, track_type: str = "video", track_index: int = 1) -> Dict[str, Any]:
     """Enable or disable a node.
 
@@ -226,6 +229,7 @@ def graph_apply_arri_cdl_lut(item_index: int = 0, track_type: str = "video", tra
 
 
 @mcp.tool()
+@granular_destructive_op()
 def graph_reset_all_grades(item_index: int = 0, track_type: str = "video", track_index: int = 1) -> Dict[str, Any]:
     """Reset all grades on a timeline item's graph.
 

package/src/granular/media_pool.py

@@ -420,6 +420,7 @@ def import_timeline_from_file(file_path: str, import_options: Optional[Dict[str,
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_timelines_by_id(timeline_ids: List[str]) -> Dict[str, Any]:
     """Delete timelines by their unique IDs.
 
@@ -441,6 +442,7 @@ def delete_timelines_by_id(timeline_ids: List[str]) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_current_media_pool_folder(folder_path: str) -> Dict[str, Any]:
     """Navigate to a specific folder in the Media Pool.
 
@@ -458,6 +460,7 @@ def set_current_media_pool_folder(folder_path: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_media_pool_clips(clip_ids: List[str]) -> Dict[str, Any]:
     """Delete clips from the Media Pool by their unique IDs.
 
@@ -489,6 +492,7 @@ def import_folder_from_file(file_path: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_media_pool_folders(folder_names: List[str]) -> Dict[str, Any]:
     """Delete folders from the current Media Pool location.
 
@@ -589,6 +593,7 @@ def get_timeline_matte_list(item_index: int = 0, track_type: str = "video", trac
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_clip_mattes(clip_id: str, matte_paths: List[str]) -> Dict[str, Any]:
     """Delete clip mattes from a MediaPoolItem.
 
@@ -671,6 +676,7 @@ def get_selected_clips() -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_selected_clip(clip_id: str) -> Dict[str, Any]:
     """Set a clip as selected in the Media Pool.
 

package/src/granular/media_pool_item.py

@@ -80,6 +80,7 @@ def link_proxy_media(clip_name: str, proxy_file_path: str) -> str:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def unlink_proxy_media(clip_name: str) -> str:
     """Unlink proxy media from a clip.
     
@@ -117,6 +118,7 @@ def unlink_proxy_media(clip_name: str) -> str:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def replace_clip(clip_name: str, replacement_path: str) -> str:
     """Replace a clip with another media file.
     
@@ -209,6 +211,7 @@ def transcribe_audio(clip_name: str, use_speaker_detection: Optional[bool] = Non
 
 
 @mcp.tool()
+@granular_destructive_op()
 def clear_transcription(clip_name: str) -> str:
     """Clear audio transcription for a clip.
     
@@ -267,6 +270,7 @@ def get_clip_metadata(clip_id: str, metadata_type: str = "") -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_clip_metadata(clip_id: str, metadata: Dict[str, str]) -> Dict[str, Any]:
     """Set metadata on a Media Pool clip.
 
@@ -306,6 +310,7 @@ def get_clip_third_party_metadata(clip_id: str, metadata_key: str = "") -> Dict[
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_clip_third_party_metadata(clip_id: str, metadata: Dict[str, str]) -> Dict[str, Any]:
     """Set third-party metadata on a clip.
 
@@ -436,6 +441,7 @@ def get_clip_marker_custom_data(clip_id: str, frame_id: int) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_clip_markers_by_color(clip_id: str, color: str) -> Dict[str, Any]:
     """Delete all markers of a specific color on a clip.
 
@@ -454,6 +460,7 @@ def delete_clip_markers_by_color(clip_id: str, color: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_clip_marker_at_frame(clip_id: str, frame_id: int) -> Dict[str, Any]:
     """Delete a marker at a specific frame on a clip.
 
@@ -472,6 +479,7 @@ def delete_clip_marker_at_frame(clip_id: str, frame_id: int) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def delete_clip_marker_by_custom_data(clip_id: str, custom_data: str) -> Dict[str, Any]:
     """Delete a marker by its custom data string.
 
@@ -525,6 +533,7 @@ def get_clip_flag_list(clip_id: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def clear_clip_flags(clip_id: str, color: str = "") -> Dict[str, Any]:
     """Clear flags on a clip.
 
@@ -560,6 +569,7 @@ def get_clip_color(clip_id: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_clip_color(clip_id: str, color: str) -> Dict[str, Any]:
     """Set the clip color of a Media Pool item.
 
@@ -578,6 +588,7 @@ def set_clip_color(clip_id: str, color: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def clear_clip_color(clip_id: str) -> Dict[str, Any]:
     """Clear the clip color of a Media Pool item.
 
@@ -595,6 +606,7 @@ def clear_clip_color(clip_id: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_clip_property(clip_id: str, property_name: str, property_value: str) -> Dict[str, Any]:
     """Set a property on a Media Pool clip.
 
@@ -635,6 +647,7 @@ def get_clip_property(clip_id: str, property_name: str = "") -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_media_pool_clip_name(clip_id: str, new_name: str) -> Dict[str, Any]:
     """Rename a Media Pool clip.
 
@@ -695,6 +708,7 @@ def link_clip_full_resolution_media(clip_id: str, full_res_media_path: str) -> D
 
 
 @mcp.tool()
+@granular_destructive_op()
 def unlink_clip_proxy_media(clip_id: str) -> Dict[str, Any]:
     """Unlink proxy media from a clip.
 
@@ -712,6 +726,7 @@ def unlink_clip_proxy_media(clip_id: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def replace_media_pool_clip(clip_id: str, new_file_path: str) -> Dict[str, Any]:
     """Replace a clip with a new media file.
 
@@ -737,6 +752,7 @@ def replace_media_pool_clip(clip_id: str, new_file_path: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def replace_media_pool_clip_preserve_sub_clip(clip_id: str, file_path: str) -> Dict[str, Any]:
     """Replace a clip's underlying media while preserving subclip extents.
 
@@ -825,6 +841,7 @@ def transcribe_clip_audio(clip_id: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def clear_clip_transcription(clip_id: str) -> Dict[str, Any]:
     """Clear transcription for a specific clip.
 
@@ -876,6 +893,7 @@ def get_clip_mark_in_out(clip_id: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def set_clip_mark_in_out(clip_id: str, mark_in: int, mark_out: int) -> Dict[str, Any]:
     """Set mark in/out points for a clip.
 
@@ -895,6 +913,7 @@ def set_clip_mark_in_out(clip_id: str, mark_in: int, mark_out: int) -> Dict[str,
 
 
 @mcp.tool()
+@granular_destructive_op()
 def clear_clip_mark_in_out(clip_id: str) -> Dict[str, Any]:
     """Clear mark in/out points for a clip.
 
@@ -937,6 +956,7 @@ def perform_clip_audio_classification(clip_id: str) -> Dict[str, Any]:
 
 
 @mcp.tool()
+@granular_destructive_op()
 def clear_clip_audio_classification(clip_id: str) -> Dict[str, Any]:
     """Clear a clip's audio classification (Resolve 21+).
 
@@ -1000,6 +1020,7 @@ def analyze_clip_for_slate(clip_id: str, marker_color: str = "Blue") -> Dict[str
 
 
 @mcp.tool()
+@granular_destructive_op()
 def remove_clip_motion_blur(clip_id: str, deblur_option: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Render a motion-deblurred copy of a clip (Resolve 21+).