davinci-resolve-mcp 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 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.4.0 — 85 granular tools stop lying to clients about what they do
+
+Granular tools infer their MCP safety annotation from the leading verb in the tool
+name. `delete_marker` matched; `ti_delete_marker` did not, because the namespace sits
+in front of the verb. Every `ti_*`, `timeline_*`, `graph_*` and `folder_*` tool —
+132 of them — matched no verb rule and took the plain-write default.
+
+### Fixed
+
+- **43 destructive granular tools were advertised as ordinary writes.** Deletes,
+  clears, resets, sets and loads — `ti_delete_version`, `ti_clear_flags`,
+  `timeline_delete_track`, `timeline_delete_clips`, `folder_clear_transcription`,
+  `graph_reset_all_grades` and the rest — all carried `destructiveHint=False`. A
+  client that gates on that hint, by prompting the user or refusing in a read-only
+  mode, was told every one of them was safe. v4.3.0 fixed this for `ti_copy_grades`
+  by hand; the other 42 needed the classifier fixed instead.
+
+- **42 pure readers were advertised as writes.** Every namespaced `*_get_*` tool —
+  `ti_get_info`, `timeline_get_markers`, `graph_get_lut` — claimed it could mutate,
+  so a read-only client had to refuse work it could safely have done.
+
+- **`detect_` was a read prefix, and `Timeline.DetectSceneCuts` adds cuts.** The one
+  tool using it, `timeline_detect_scene_cuts`, was only ever classified correctly
+  because its namespace hid it from that list — teaching the classifier to see past
+  the namespace would have promoted a tool that restructures the timeline to
+  read-only. `detect_` is gone from the read list and the tool is now explicitly
+  destructive, matching how the compound server already rates it.
+
+- **A bare `<namespace>_<verb>` name matched nothing even after stripping.** Every
+  verb prefix ends in `_`, so `timeline_export` became `export`, which does not start
+  with `export_`. `timeline_export`, `folder_export` and `timeline_duplicate` fell
+  through. The verb probe now appends the separator before matching.
+
+### Added
+
+- **`tests/test_granular_tool_annotations.py` guards the classifier, not the names.**
+  Three properties, each pinning a way this failed:
+  - no tool hinted `readOnlyHint=True` calls a Resolve method outside the
+    `Get`/`Is`/`Has`/`List`/`Find`/`Export` shapes — this is what catches the next
+    `DetectSceneCuts`, and it is a property of the body, not of the name;
+  - no namespaced tool falls through to the default, checked against the verb lists
+    directly so a deliberate `WRITE` passes and a fallthrough does not;
+  - the allow-list of ruleless verbs must stay exact in both directions, so an entry
+    that later matches a verb has to be removed rather than left to rot.
+
+### Changed
+
+- The verb lists move to module level in `src/granular/common.py`
+  (`READ_PREFIXES`, `DESTRUCTIVE_PREFIXES`, `WRITE_PREFIXES`) alongside
+  `NAMESPACE_PREFIXES` and `matches_a_verb`, so the guards can tell a deliberate
+  write from a name that matched nothing — the distinction the old code could not
+  express, and the reason the bug was invisible.
+
+### Validation
+
+- Full offline suite: **3,640 passed, 1 skipped, 0 failed**, 1,269 subtests.
+- Every one of the 387 granular tools was classified before and after. 85 changed:
+  43 write→destructive, 42 write→read. The 42 that became *less* restrictive are all
+  `*_get_*` getters, and the read-only guard above independently confirms none of
+  them calls a mutating Resolve method — that check is the evidence, not the naming.
+- All release drift guards green. No Resolve behaviour changed: annotations are
+  metadata a client reads before calling, and no tool body was touched except
+  `timeline_detect_scene_cuts`, which gained a docstring warning and its annotation.
+
 ## What's New in v4.3.0 — the granular grade-copy stops replacing grades on clips nobody named
 
 v4.2.0 gated the compound `timeline_item_color copy_grades`. Its granular twin,

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.3.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.4.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-37%20(387%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

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

package/install.py

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

package/src/granular/common.py

@@ -92,7 +92,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.3.0"
+VERSION = "4.4.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -145,65 +145,112 @@ EXTERNAL_DESTRUCTIVE_TOOL = ToolAnnotations(
 )
 
 
+#: Namespace segments that sit in FRONT of the verb in a granular tool name.
+#:
+#: The prefix heuristic below reads the leading verb, so a tool called
+#: `ti_delete_marker_at_frame` matched none of the verb lists and fell through to
+#: the plain write default — 86 tools were mis-hinted this way, 43 destructive ones
+#: advertised as ordinary writes (a client gating on `destructiveHint` was told
+#: `ti_copy_grades` was safe) and 43 pure readers advertised as writes. Every tool
+#: carrying one of these is `<namespace>_<verb>_...`, so one strip exposes the verb.
+NAMESPACE_PREFIXES = (
+    "ti_",
+    "timeline_",
+    "graph_",
+    "folder_",
+)
+
+
+def _strip_namespace(name: str) -> str:
+    """Drop one leading namespace segment so the verb heuristic can see the verb."""
+    for prefix in NAMESPACE_PREFIXES:
+        if name.startswith(prefix):
+            return name[len(prefix):]
+    return name
+
+
+def _verb_probe(tool_name: str) -> str:
+    """The stripped name, shaped so a BARE verb still matches its prefix.
+
+    Every verb prefix ends in "_", so `timeline_export` -> `export` would match
+    nothing: the tool name is exactly `<namespace>_<verb>` with no suffix. The
+    trailing "_" makes `export` match `export_` without loosening anything else.
+    """
+    return _strip_namespace((tool_name or "").lower()) + "_"
+
+
+#: Verb prefixes, checked in this order against the name AFTER its namespace is
+#: stripped. Module-level so `tests/test_granular_tool_annotations.py` can tell a
+#: deliberate write from a name that matched nothing and fell through to the default.
+READ_PREFIXES = (
+    "get_",
+    "list_",
+    "inspect_",
+    "probe_",
+    "validate_",
+    "compare_",
+    # NOT "detect_": Timeline.DetectSceneCuts adds cuts to the timeline, and the
+    # compound server rates detect_scene_cuts destructive. It only ever looked like
+    # a read because the `timeline_` namespace hid it from this list.
+    "summarize_",
+    "review_",
+    "is_",
+    "has_",
+)
+DESTRUCTIVE_PREFIXES = (
+    "delete_",
+    "remove_",
+    "clear_",
+    "reset_",
+    "replace_",
+    "unlink_",
+    "quit",
+    "restart",
+    "close_",
+    "stop_",
+    "overwrite_",
+    "lift_",
+    "set_",
+    "load_",
+    "switch_",
+)
+WRITE_PREFIXES = (
+    "add_",
+    "append_",
+    "apply_",
+    "assign_",
+    "copy_",
+    "create_",
+    "duplicate_",
+    "export_",
+    "import_",
+    "insert_",
+    "link_",
+    "move_",
+    "open_",
+    "render_",
+    "rename_",
+    "save_",
+    "start_",
+    "sync_",
+    "transcribe_",
+)
+
+
+def matches_a_verb(tool_name: str) -> bool:
+    """Did the name resolve to a verb rule, or fall through to the default?"""
+    return _verb_probe(tool_name).startswith(
+        READ_PREFIXES + DESTRUCTIVE_PREFIXES + WRITE_PREFIXES)
+
+
 def _annotations_for_tool_name(tool_name: str) -> ToolAnnotations:
     """Infer conservative MCP client-safety hints for legacy granular tools."""
-    name = (tool_name or "").lower()
-    read_prefixes = (
-        "get_",
-        "list_",
-        "inspect_",
-        "probe_",
-        "validate_",
-        "compare_",
-        "detect_",
-        "summarize_",
-        "review_",
-        "is_",
-        "has_",
-    )
-    destructive_prefixes = (
-        "delete_",
-        "remove_",
-        "clear_",
-        "reset_",
-        "replace_",
-        "unlink_",
-        "quit",
-        "restart",
-        "close_",
-        "stop_",
-        "overwrite_",
-        "lift_",
-        "set_",
-        "load_",
-        "switch_",
-    )
-    write_prefixes = (
-        "add_",
-        "append_",
-        "apply_",
-        "assign_",
-        "copy_",
-        "create_",
-        "duplicate_",
-        "export_",
-        "import_",
-        "insert_",
-        "link_",
-        "move_",
-        "open_",
-        "render_",
-        "rename_",
-        "save_",
-        "start_",
-        "sync_",
-        "transcribe_",
-    )
-    if name.startswith(read_prefixes):
+    name = _verb_probe(tool_name)
+    if name.startswith(READ_PREFIXES):
         return READ_ONLY_TOOL
-    if name.startswith(destructive_prefixes):
+    if name.startswith(DESTRUCTIVE_PREFIXES):
         return DESTRUCTIVE_TOOL
-    if name.startswith(write_prefixes):
+    if name.startswith(WRITE_PREFIXES):
         return WRITE_TOOL
     return WRITE_TOOL
 

package/src/granular/timeline.py

@@ -878,9 +878,12 @@ def timeline_create_subtitles_from_audio(
     return {"success": bool(result)}
 
 
-@mcp.tool()
+# Explicit: the verb heuristic has no rule for "detect", and this one restructures
+# the timeline by adding cuts. The compound server rates timeline_ai.detect_scene_cuts
+# destructive; this is the same Resolve call, so it carries the same hint.
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
 def timeline_detect_scene_cuts() -> Dict[str, Any]:
-    """Detect scene cuts in the current timeline."""
+    """Detect scene cuts in the current timeline. DESTRUCTIVE — adds cuts to the timeline."""
     _, tl, err = _get_timeline()
     if err:
         return err

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.3.0"
+VERSION = "4.4.0"
 
 import base64
 import os