davinci-resolve-mcp 4.5.0 → 4.5.1

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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

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.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)

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.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.5.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.5.1 版 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.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.5.0",
+  "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

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.5.0"
+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/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.1"
 
 import base64
 import os

package/src/utils/destructive_hook.py

@@ -991,6 +991,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,13 +1076,13 @@ 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",
-                )
+                ))
 
             result = fn(*args, **kwargs)
             _audit_security_event(