davinci-resolve-mcp 4.5.0 → 4.5.2

package/CHANGELOG.md

@@ -2,6 +2,112 @@
 
 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.2 — granular safety stops guessing, and the audit log stops lying
+
+Two findings from a review of the v4.5.0 enforcement hook, both measured before and
+after rather than reasoned about.
+
+### Fixed
+
+- **The verb table was the sole authority on risk, and it disagreed with the
+  compound server on 20 tools.** The same operation is exposed on both servers under
+  the same action name, and the compound tables are where someone actually assessed
+  it. Three granular tools were rated **below** their compound assessment — the
+  direction that matters, because safe mode then lets them through:
+
+  | tool | was | now |
+  |---|---|---|
+  | `ti_copy_grades` | medium | **high** |
+  | `timeline_delete_clips` | high | **critical** |
+  | `timeline_detect_scene_cuts` | medium | **high** |
+
+  `ti_copy_grades` is the tool this entire effort began with — the one that reaches
+  `TimelineItem.CopyGrades` and replaces a node graph with no recovery version. The
+  verb table called it MEDIUM, because `copy` appears in no table, so safe mode did
+  not stop it.
+
+  The other seventeen were rated **above** their compound assessment: `clear_*` and
+  `set_*` tools called HIGH here while compound rates them LOW. That is not the safe
+  direction either — `_safe_mode_allows` documents why at length. A gate that refuses
+  work the compound server considers low-risk teaches people to switch safe mode off,
+  and a setting left off protects nothing.
+
+  Rating order is now: a symbol the ledger marks `destroys_prior_work`, then the
+  compound server's established rating for the same action name, then the verb.
+  Most-severe-wins where two compound tools rate one name differently, because a gate
+  should resolve ambiguity by refusing more rather than less.
+
+- **The audit log misreported two of its three outcomes.** It is this surface's only
+  record of what ran — there is no archive behind it — so a row that overstates, or
+  is simply absent, is the whole artifact failing:
+
+  - a first call that only minted a confirm token was recorded `allowed`, claiming a
+    mutation that had not happened. It is now `pending_confirmation`, matching what
+    the compound hook records for the same case.
+  - **an exception wrote no row at all**, so the log went silent exactly when
+    something broke. It is now `failed`, carrying the exception type. The hook is a
+    witness, not a handler: the exception is re-raised untouched.
+
+### Changed
+
+- Four existing tests asserted the old verb ratings. `ti_clear_flags` is LOW now
+  because compound rates `clear_flags` LOW — the change working, not a regression —
+  so the two behavioural tests moved to `ti_delete_version` as their HIGH exemplar,
+  and namespace stripping is asserted directly rather than through a rating that may
+  now come from the compound tables.
+
+### Validation
+
+- Full offline suite: **3,693 passed, 1 skipped, 0 failed**, 1,419 subtests.
+- Each fix was reverted in turn to confirm its guard fails rather than passing
+  vacuously — 9, 1 and 1 failures respectively, all green on restore.
+- A guard now walks every decorated tool and fails if any is rated *below* the
+  compound server's established assessment, so the class cannot return one tool at a
+  time. A trap-symbol tool may still be raised above it.
+
+## 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

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.5.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.5.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-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.5.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.5.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-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.5.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.5.2 版 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.5.0"
+VERSION = "4.5.2"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

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

package/src/granular/common.py

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.5.0"
+VERSION = "4.5.2"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

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

package/src/utils/destructive_hook.py

@@ -38,7 +38,12 @@ from typing import Any, Callable, Dict, FrozenSet, Optional, Tuple
 from src.utils import analysis_runs, brain_edits, media_pool_changes, timeline_versioning
 from src.utils.api_truth import API_TRUTH, traps_for, trap_notice
 from src.utils.bool_params import coerce_bool, explicit_bool_param
-from src.utils.execution_lifecycle import RiskAssessment, RiskLevel, classify_operation_risk
+from src.utils.execution_lifecycle import (
+    RiskAssessment,
+    RiskClassificationHook,
+    RiskLevel,
+    classify_operation_risk,
+)
 
 logger = logging.getLogger("resolve-mcp.destructive-hook")
 
@@ -947,22 +952,72 @@ def _reaches_trap_symbol(fn: Callable[..., Any]) -> bool:
     return False
 
 
+_RISK_ORDER = {
+    RiskLevel.LOW.value: 0,
+    RiskLevel.MEDIUM.value: 1,
+    RiskLevel.HIGH.value: 2,
+    RiskLevel.CRITICAL.value: 3,
+}
+
+
+@functools.lru_cache(maxsize=1)
+def _established_compound_ratings() -> Dict[str, str]:
+    """Compound risk ratings keyed by action name, most severe wins.
+
+    The same operation is often exposed on both servers under the same action
+    name — `clear_flags`, `delete_clips`, `copy_grades` — and the compound tables
+    are where someone actually assessed it. Guessing from the verb when a real
+    rating exists produced 20 disagreements, three of them UNDER-rating: the verb
+    table called `ti_copy_grades` MEDIUM (so safe mode let it through) while the
+    compound tables rate `copy_grades` HIGH, and `delete_clips` is CRITICAL there
+    against HIGH here.
+
+    Most-severe-wins because a name rated differently by two compound tools is
+    ambiguous, and a gate should resolve ambiguity by refusing more, not less.
+    """
+    ratings: Dict[str, str] = {}
+    for table, level in (
+        ("_CRITICAL_ACTIONS", RiskLevel.CRITICAL.value),
+        ("_HIGH_RISK_ACTIONS", RiskLevel.HIGH.value),
+        ("_MEDIUM_RISK_ACTIONS", RiskLevel.MEDIUM.value),
+        ("_LOW_RISK_ACTIONS", RiskLevel.LOW.value),
+    ):
+        for _tool, action in getattr(RiskClassificationHook, table, ()) or ():
+            current = ratings.get(action)
+            if current is None or _RISK_ORDER[level] > _RISK_ORDER[current]:
+                ratings[action] = level
+    return ratings
+
+
+def _granular_action_name(tool_name: str) -> str:
+    """The tool name with its namespace removed — the compound action name."""
+    name = (tool_name or "").lower()
+    for prefix in _GRANULAR_NAMESPACES:
+        if name.startswith(prefix):
+            return name[len(prefix):]
+    return name
+
+
 def granular_risk_level(tool_name: str, fn: Optional[Callable[..., Any]] = None) -> str:
-    """Rate a granular tool: HIGH from the ledger if it reaches a trap symbol,
-    otherwise from its verb. Unknown verbs are MEDIUM, never HIGH.
+    """Rate a granular tool, preferring an assessment over a guess.
+
+    In order: HIGH if the body reaches a symbol the ledger marks
+    `destroys_prior_work`; else the compound server's established rating for the
+    same action name; else the verb. Unknown verbs are MEDIUM, never HIGH.
 
     Rating an unrecognised verb HIGH would let safe mode block writes nobody has
     assessed, which is the failure `_safe_mode_allows` documents: over-blocking
     teaches people to switch the setting off, and a setting left off protects
-    nothing.
+    nothing. The compound lookup cuts both ways for the same reason — it raises
+    `copy_grades` to HIGH, and it lowers the seventeen `clear_*`/`set_*` tools the
+    verb table called HIGH while compound rates them LOW.
     """
     if fn is not None and _reaches_trap_symbol(fn):
         return RiskLevel.HIGH.value
-    name = (tool_name or "").lower()
-    for prefix in _GRANULAR_NAMESPACES:
-        if name.startswith(prefix):
-            name = name[len(prefix):]
-            break
+    name = _granular_action_name(tool_name)
+    established = _established_compound_ratings().get(name)
+    if established is not None:
+        return established
     return GRANULAR_RISK_BY_VERB.get(name.split("_", 1)[0], RiskLevel.MEDIUM.value)
 
 
@@ -991,6 +1046,39 @@ def _with_override_param(fn: Callable[..., Any]) -> Tuple[inspect.Signature, boo
     return sig.replace(parameters=head + [extra] + tail), True
 
 
+def _returns_plain_string(fn: Callable[..., Any]) -> bool:
+    """Does this tool declare `-> str`?
+
+    FastMCP builds an output schema from the return annotation and validates
+    against it, so handing a dict to a tool annotated `-> str` raises ToolError
+    and the caller never sees the refusal — only a generic execution error with
+    none of its code or remediation. 27 granular tools declare `-> str`, and the
+    HIGH-risk ones among them are exactly the calls safe mode exists to stop.
+    """
+    annotation = getattr(fn, "__annotations__", {}).get("return")
+    return annotation is str or annotation in ("str", "'str'")
+
+
+def _block_for(fn: Callable[..., Any], block: Dict[str, Any]) -> Any:
+    """The refusal, shaped to the contract the tool declares.
+
+    A string-returning tool gets the message and its remediation as text. That
+    loses the machine-readable `code`, which is a real cost — but a refusal the
+    client can read beats a ToolError that discards it entirely, and it is the
+    only shape that tool's own schema will accept.
+    """
+    if not _returns_plain_string(fn):
+        return block
+    error = block.get("error") or {}
+    message = error.get("message") or "Blocked by destructive.safe_mode."
+    remediation = error.get("remediation")
+    code = error.get("code")
+    parts = [f"{code}: {message}" if code else message]
+    if remediation:
+        parts.append(remediation)
+    return " ".join(parts)
+
+
 def granular_destructive_op(
     tool_name: Optional[str] = None,
     *,
@@ -1043,23 +1131,46 @@ def granular_destructive_op(
                     params=params,
                     reason="safe_mode",
                 )
-                return _security_block_response(
+                return _block_for(fn, _security_block_response(
                     operation_id=operation_id,
                     tool_name="granular",
                     action=action,
                     risk_level=level,
                     override_hint=f"{GRANULAR_OVERRIDE_PARAM}=true",
+                ))
+
+            try:
+                result = fn(*args, **kwargs)
+            except BaseException as exc:
+                # A call that reached Resolve and then failed used to leave no row
+                # at all. The audit log is this surface's only record of what ran,
+                # so going silent precisely when something broke is the worst place
+                # to have a gap. Record it, then let the exception continue
+                # untouched — the hook is a witness, not a handler.
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name="granular",
+                    action=action,
+                    risk_level=level,
+                    status="failed",
+                    params=params,
+                    reason=type(exc).__name__,
                 )
+                raise
 
-            result = fn(*args, **kwargs)
+            # A first call that mints a confirm token has not mutated anything, and
+            # recording it as "allowed" overstates what happened — the compound hook
+            # distinguishes the same case via _PENDING_CONFIRM_CHECK.
+            pending = (isinstance(result, dict)
+                       and result.get("status") == "confirmation_required")
             _audit_security_event(
                 operation_id=operation_id,
                 tool_name="granular",
                 action=action,
                 risk_level=level,
-                status="allowed",
+                status="pending_confirmation" if pending else "allowed",
                 params=params,
-                reason="no_archive_on_granular",
+                reason="confirm_token_required" if pending else "no_archive_on_granular",
             )
             return _annotate_security(result, operation_id=operation_id, risk_level=level)