davinci-resolve-mcp 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 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.1.0 — `timeline_markers add` can be previewed, and "false" stops meaning true
+
+Contributed by @Rohitkanithi (#218), adapted onto v4.0.0.
+
+### Added
+
+- **`timeline_markers add` accepts `dry_run` / `dryRun` natively.** The preview
+  resolves the marker frame through the same path as a real add — including the
+  current-playhead default when frame and timecode are both omitted —
+  normalizes the colour through the existing validator, applies the same
+  defaults for name, note, duration and custom data, and returns a
+  `would_change` block with `executed: false` without calling Resolve's
+  `AddMarker`. It sits *after* payload resolution and *before* the write, so
+  the preview reports the values that would actually have been sent rather than
+  a synthesized guess, and a payload the real handler would reject is rejected
+  here too instead of previewing a success that could not happen.
+- Registered in `NATIVE_DRY_RUN_ACTIONS`, so an explicit dry run is treated as
+  plan-only: no timeline archive and no versioning row for a request that
+  mutates nothing. A normal add keeps the full safety and versioning path, and
+  marker actions *without* a native preview still refuse with
+  `DRY_RUN_UNAVAILABLE` rather than pretending to simulate.
+
+### Fixed
+
+- **`dry_run="false"` meant true.** Both the destructive hook and the operation
+  log tested the flag with a bare `bool(...)`, and every non-empty string is
+  truthy — so a caller passing the string `"false"`, which is what several MCP
+  clients send for a boolean, got the dry-run path when they had explicitly
+  asked not to. The mutation silently did not happen. Both now share
+  `src/utils/bool_params.py`, which reads `"true"/"1"/"yes"/"on"` and
+  `"false"/"0"/"no"/"off"`, so the safety layer and the log cannot drift on the
+  question of whether a dry run was actually requested.
+- **This also closes a bypass in the v4.0.0 trap guard.** That guard exempts an
+  explicit dry run from the `CopyGrades` refusal, on the correct grounds that a
+  preview destroys nothing — but it decided "explicit dry run" with the same
+  truthy test. A call carrying `dry_run="false"` therefore read as a dry run and
+  skipped the refusal. It was caught downstream by `lacks_native_dry_run`, which
+  shared the same flaw and refused with `DRY_RUN_UNAVAILABLE`, so nothing
+  destructive got through — but the guard was being answered by a bug rather
+  than by its own logic. Both now go through the shared helper.
+
+### Changed
+
+- Successful dry-run entries in the operation log summarize as previews
+  (`timeline_markers.add dry-run preview`), so a JSONL scan distinguishes a
+  preview from a mutation without parsing the payload.
+
 ## What's New in v4.0.0 — verified API facts reach the caller, and one of them refuses
 
 Contributed by @Grimthereapper (#217). **Major**, because a call that previously

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.1.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.0.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.1.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.0.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.1.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.0.0"
+VERSION = "4.1.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.0.0",
+  "version": "4.1.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.0.0"
+VERSION = "4.1.0"
 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.0.0"
+VERSION = "4.1.0"
 
 import base64
 import os
@@ -72,6 +72,7 @@ from src.utils.proc import safe_run
 from src.utils.readback import verify_by_readback, verification_stats as _verification_stats
 from src.utils import operation_result as _operation_result
 from src.utils import operation_log as _operation_log
+from src.utils.bool_params import explicit_bool_param as _explicit_bool_param
 from src.utils.operation_result import (
     build_operation_envelope as _build_operation_envelope,
     get_envelope_mode as _get_envelope_mode,
@@ -26145,7 +26146,7 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
     itself refuses sub-start timecodes with a bare False.
 
     Actions:
-      add(frame|frame_id|frameId|timecode?, color?, name?, note?, duration?, custom_data?) -> {success, frame}
+      add(frame|frame_id|frameId|timecode?, color?, name?, note?, duration?, custom_data?, dry_run?/dryRun?) -> {success, frame} or dry-run preview
         If frame/timecode is omitted, add uses the current playhead timecode.
       get_all() -> {markers}
       get_by_custom_data(custom_data) -> {markers}
@@ -26178,6 +26179,21 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
         marker, marker_err = _marker_add_payload(p, tl=tl, default_to_current=True)
         if marker_err:
             return marker_err
+        if _explicit_bool_param(p, "dry_run", "dryRun") is True:
+            return {
+                "success": True,
+                "dry_run": True,
+                "executed": False,
+                "would_change": {
+                    "operation": "timeline_markers.add",
+                    "frame": marker["frame"],
+                    "color": marker["color"],
+                    "name": marker["name"],
+                    "note": marker["note"],
+                    "duration": marker["duration"],
+                    "custom_data": marker["custom_data"],
+                },
+            }
         return _add_marker(tl, marker)
     elif action == "get_all":
         return {"markers": _ser(tl.GetMarkers())}

package/src/utils/bool_params.py

@@ -0,0 +1,33 @@
+"""Boolean coercion helpers for tool parameters and preferences."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+_TRUE_STRINGS = {"1", "true", "yes", "on"}
+_FALSE_STRINGS = {"0", "false", "no", "off"}
+
+
+def coerce_bool(value: Any, default: bool = False) -> bool:
+    """Return a predictable bool for user-facing params and config values."""
+    if value is None:
+        return default
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in _TRUE_STRINGS:
+            return True
+        if lowered in _FALSE_STRINGS:
+            return False
+        return default
+    return bool(value)
+
+
+def explicit_bool_param(params: Optional[Dict[str, Any]], *keys: str) -> Optional[bool]:
+    """Coerce the first present key, or None when none of the keys are present."""
+    if not isinstance(params, dict):
+        return None
+    for key in keys:
+        if key in params:
+            return coerce_bool(params[key])
+    return None

package/src/utils/destructive_hook.py

@@ -34,6 +34,7 @@ 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 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
 
 logger = logging.getLogger("resolve-mcp.destructive-hook")
@@ -350,6 +351,7 @@ DRY_RUN_DEFAULT_TRUE_ACTIONS: frozenset = frozenset({
 
 NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
     ("media_pool", "clear_clip_marks"),
+    ("timeline_markers", "add"),
     ("timeline_item_color", "apply_trace_plan"),
     ("media_pool", "set_clip_marks"),
     ("media_pool", "setup_multicam_timeline"),
@@ -366,13 +368,7 @@ NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
 
 
 def _explicit_dry_run_requested(params: Optional[Dict[str, Any]]) -> bool:
-    if not isinstance(params, dict):
-        return False
-    if "dry_run" in params:
-        return bool(params["dry_run"])
-    if "dryRun" in params:
-        return bool(params["dryRun"])
-    return False
+    return explicit_bool_param(params, "dry_run", "dryRun") is True
 
 
 def lacks_native_dry_run(
@@ -434,11 +430,14 @@ def _payload_is_plan_only(
     tool_name: str, action: str, params: Optional[Dict[str, Any]],
 ) -> bool:
     """True iff this call only produces a plan and mutates nothing."""
+    dry_run = explicit_bool_param(params, "dry_run", "dryRun")
+    if (tool_name, action) in NATIVE_DRY_RUN_ACTIONS and dry_run is True:
+        return True
     if (tool_name, action) not in DRY_RUN_DEFAULT_TRUE_ACTIONS:
         return False
-    if not isinstance(params, dict):
+    if dry_run is None:
         return True  # dry_run defaults to True for these actions
-    return bool(params.get("dry_run", params.get("dryRun", True)))
+    return dry_run
 
 
 def _payload_only_touches_no_archive_keys(
@@ -571,16 +570,7 @@ def _read_preference(key: str, default: Any = None) -> Any:
 
 
 def _coerce_bool(value: Any, default: bool = False) -> bool:
-    if value is None:
-        return default
-    if isinstance(value, str):
-        lowered = value.strip().lower()
-        if lowered in {"1", "true", "yes", "on"}:
-            return True
-        if lowered in {"0", "false", "no", "off"}:
-            return False
-        return default
-    return bool(value)
+    return coerce_bool(value, default)
 
 
 def _safe_mode_enabled() -> bool:

package/src/utils/operation_log.py

@@ -16,6 +16,7 @@ import uuid
 from pathlib import Path
 from typing import Any, Callable, Dict, Optional
 
+from src.utils.bool_params import coerce_bool, explicit_bool_param
 from src.utils import operation_result
 
 logger = logging.getLogger("resolve-mcp.operation-log")
@@ -41,16 +42,7 @@ def _read_preference(key: str, default: Any = None) -> Any:
 
 
 def _coerce_bool(value: Any, default: bool = False) -> bool:
-    if value is None:
-        return default
-    if isinstance(value, str):
-        lowered = value.strip().lower()
-        if lowered in {"1", "true", "yes", "on"}:
-            return True
-        if lowered in {"0", "false", "no", "off"}:
-            return False
-        return default
-    return bool(value)
+    return coerce_bool(value, default)
 
 
 def operation_log_enabled() -> bool:
@@ -72,12 +64,12 @@ def _now_iso() -> str:
 
 
 def _dry_run_requested(params: Optional[Dict[str, Any]], result: Any) -> bool:
-    if isinstance(params, dict):
-        if "dry_run" in params:
-            return bool(params["dry_run"])
-        if "dryRun" in params:
-            return bool(params["dryRun"])
-    return bool(isinstance(result, dict) and result.get("dry_run") is True)
+    requested = explicit_bool_param(params, "dry_run", "dryRun")
+    if requested is not None:
+        return requested
+    if isinstance(result, dict) and "dry_run" in result:
+        return coerce_bool(result.get("dry_run"))
+    return False
 
 
 def _envelope(result: Any) -> Dict[str, Any]:
@@ -119,9 +111,18 @@ def _status(result: Any, envelope: Dict[str, Any]) -> str:
     return str(envelope.get("status") or operation_result.normalize_status(result))
 
 
-def _summary(tool_name: str, action: str, status: str, envelope: Dict[str, Any]) -> str:
+def _summary(
+    tool_name: str,
+    action: str,
+    status: str,
+    envelope: Dict[str, Any],
+    *,
+    dry_run: bool = False,
+) -> str:
     operation = f"{tool_name}.{action}"
     changes = envelope.get("changes")
+    if dry_run and status == "success":
+        return f"{operation} dry-run preview"
     if isinstance(changes, dict) and changes:
         parts = [f"{key}={value}" for key, value in sorted(changes.items())[:4]]
         return f"{operation} {status}; " + ", ".join(parts)
@@ -140,6 +141,7 @@ def build_record(
 ) -> Dict[str, Any]:
     env = _envelope(result)
     status = _status(result, env)
+    dry_run = _dry_run_requested(params, result)
     record = {
         "operation_id": _operation_id(result, env),
         "tool": tool_name,
@@ -147,9 +149,9 @@ def build_record(
         "operation": f"{tool_name}.{action}",
         "risk_level": risk.get("level", "unknown"),
         "risk_established": risk.get("recognised"),
-        "dry_run": _dry_run_requested(params, result),
+        "dry_run": dry_run,
         "timestamp": _now_iso(),
-        "summary": _summary(tool_name, action, status, env),
+        "summary": _summary(tool_name, action, status, env, dry_run=dry_run),
         "status": status,
     }
     if env.get("execution_id") and env.get("execution_id") != record["operation_id"]: