davinci-resolve-mcp 2.210.0 → 2.211.0

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 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 v2.211.0 — dry_run on an action that cannot honour it now refuses instead of executing
+
+### Changed
+
+- **An explicit `dry_run=true` on a destructive action with no native dry-run path is refused, not executed.**
+  102 of the 108 registered destructive actions never read the flag, so
+  `timeline_markers.add` with `dry_run=true` added a real marker and
+  `timeline.delete_track` with `dry_run=true` deleted the track — and the
+  agent guidance says to prefer `dry_run` where it exists, which cannot be
+  told from outside. The destructive-operation wrapper now returns
+  `DRY_RUN_UNAVAILABLE` (`status: dry_run_unavailable`, `dry_run: true`,
+  `simulated: false`, `executed: false`, the same static risk block as
+  `inspect_operation`, and a remediation) before any archive, state lookup,
+  or handler execution. The security audit log records it as
+  `blocked` / `dry_run_unavailable`. This is a refusal, not a synthesised
+  preview — the lifecycle pipeline's original interceptor answered
+  `success: true` for calls it never ran and was removed for it.
+
+- **The six actions that do honour `dry_run` are an allowlist, `NATIVE_DRY_RUN_ACTIONS`.**
+  `media_pool.set_clip_marks`, `media_pool.clear_clip_marks`,
+  `media_pool.setup_multicam_timeline`, `timeline.apply_cuts`,
+  `timeline.ripple_insert`, `timeline_ai.create_subtitles`. A static drift
+  test pins the list to the handlers by following the params object into
+  helper calls; that is what excluded `edit_engine.execute_tighten` and
+  `execute_silence_ripple`, which call a dry_run-aware helper but hand it a
+  fresh dict without the flag. Add a native dry-run branch and the test says
+  to list it; list an action without one and the test refuses.
+
+- **The refusal is keyed on registry membership, not on `is_destructive()`**, so
+  the no-archive filters (a Notes edit) cannot let a dry-run request through to
+  a handler that would execute it.
+
+- Adapted from PR #190 by @Rohitkanithi, which introduced the refusal shape
+  as a denylist of the fourteen marker actions; landed as an allowlist so the
+  other 88 actions that ignore the flag are covered too.
+
+## What's New in v2.210.1 — frame capture and verify_output no longer read JobStatus in English
+
+### Fixed
+
+- **Single-frame capture failed with `RENDER_FAILED` on every non-English Resolve (issue #191).**
+  `GetRenderJobStatus()["JobStatus"]` is a localized display string — `"Concluso"`
+  on an Italian install — and the capture gate compared it to the English word,
+  so a finished render with the file already on disk reported "Render did not
+  complete". Completion is now decided by `_render_job_completed()` on
+  `CompletionPercentage` and `Error`, which are locale-independent, with the
+  file-written check as the real proof. `render.verify_output` carried the same
+  comparison in its "not Complete" warning and its missing-file warning; both
+  use the same rule now, so a localized finished job verifies and a localized
+  failed job still does not. Reported with an exact API readback by
+  @gabrieleleonardi-sya.
+
+### Documentation
+
+- New API truth entry for the localized `JobStatus` field, submitted to the
+  Blackmagic-facing report as a missing locale-independent status code, and a
+  regenerated `docs/reference/api-limitations.md`.
+
+### Validation
+
+- Unit tests cover the reporter's readback (`Concluso` at 100%), a localized
+  failed job carrying `Error`, and a localized incomplete job without one; the
+  English fast path is unchanged. No localized Resolve is available on the
+  release machine, so the live evidence is the reporter's session on Studio
+  21.0.2.4.
+
 ## What's New in v2.210.0 — every destructive action now carries a real risk rating
 
 ### Changed

package/README.md

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

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -289,12 +289,20 @@ Example trace shape returned by `resolve_control(action="get_execution_trace")`:
   availability was not determined, never that there is none; and
   `pre_state_available` separates "no project open" from "state never read".
   For an actual preview, use the action's own `dry_run` where it has one.
+  Where it has none, an explicit `dry_run=true` on a registered destructive
+  action is refused with `DRY_RUN_UNAVAILABLE` (`status: dry_run_unavailable`,
+  `simulated: false`, `executed: false`, plus the same static risk block)
+  before any archive, state lookup, or handler execution. Until v2.211.0 the
+  flag was silently ignored on those actions and the mutation ran; the
+  actions that do honour it are listed in `NATIVE_DRY_RUN_ACTIONS`
+  (`src/utils/destructive_hook.py`) and pinned to the handlers by a test.
 - **`list_lifecycle_hooks()`**: Returns active execution lifecycle pipeline hooks
   (`risk_classification`, `resolve_state_inspection`, `readback_verification`,
   `drift_detection`, `provenance_trace`). All of them observe; none replaces a
-  tool result. `dry_run` therefore always reaches the real handler — a tool
-  either implements it or does not, and nothing synthesises a preview on its
-  behalf.
+  tool result. `dry_run` is therefore never answered on a handler's behalf:
+  an action with a native dry-run path runs it, and every other registered
+  destructive action refuses the flag instead of either simulating or
+  executing.
 
 Explicit correlation is also supported per-call: pass `params={"execution_id": ...}`
 or `params={"trace_id": ...}` in any tool call to associate it with a specific trace.

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 41 missing capabilities, 50 bugs / unreliable behaviors.
+**Totals:** 42 missing capabilities, 50 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -228,6 +228,15 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** capture_media_template harvests mediaStartTime and the native clip elements; drt.assemble clones the source's own captured clip per cut (render-verified: the TC-bearing source plays picture and audio, and the full AAF route renders frame-accurately). Re-capture templates for TC-bearing media. The assemble bridge merges identical audio channel legs (report.audioChannelLegsMerged) instead of refusing them as a same-track overlap.
 - **Tags:** timecode, aaf, audio, drt, silent-failure
 
+### Project.GetRenderJobStatus JobStatus (localized display string)
+
+- **Object:** `Project`
+- **Signature:** `(jobId) -> {JobStatus, CompletionPercentage, TimeTakenToRenderInMs, Error?}`
+- **Behavior:** JobStatus is a display string that follows the application language, not an enum. An English install reports "Complete"; an Italian install reports "Concluso" for the same finished job — read back as {JobStatus: "Concluso", CompletionPercentage: 100, TimeTakenToRenderInMs: 1225} on Studio 21.0.2.4 / macOS 15 with the output file complete on disk (issue #191, reporter's session). Any code that compares the field to the English word fails every non-English Resolve with an error that says the opposite of what happened; this server's single-frame capture did exactly that until v2.210.1. CompletionPercentage is numeric and locale-independent, and Error is populated on a failed job in every language.
+- **Workaround / current handling:** Never gate on the JobStatus string. Treat a job as finished when CompletionPercentage reaches 100 and Error is empty, then confirm the output file exists — the file is the real proof either way (see the recordFrame entry above for a Complete job that wrote a stub). Report JobStatus verbatim for humans only. This server's _render_job_completed() applies the rule to frame capture and render.verify_output.
+- **Reference:** [issue #191](https://github.com/samuelgursky/davinci-resolve-mcp/issues/191)
+- **Tags:** render, localization, silent-failure
+
 ### MediaPool.ImportMedia (current-folder destination only)
 
 - **Object:** `MediaPool`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.210.0"
+VERSION = "2.211.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": "2.210.0",
+  "version": "2.211.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 = "2.210.0"
+VERSION = "2.211.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 353-tool granular server instead
 """
 
-VERSION = "2.210.0"
+VERSION = "2.211.0"
 
 import base64
 import os
@@ -14823,6 +14823,28 @@ def _playhead_frame_preview(tl, p: Dict[str, Any]):
             _restore_playhead(tl, original_tc, what="the thumbnail capture")
 
 
+def _render_job_completed(status: Optional[Dict[str, Any]]) -> bool:
+    """Whether GetRenderJobStatus says the job finished — without reading English.
+
+    JobStatus is a localized display string that follows the application
+    language: "Complete" on an English install, "Concluso" on an Italian one
+    (issue #191). Comparing it to the English literal fails every non-English
+    Resolve with an error that says the opposite of what happened. The
+    locale-independent signals are CompletionPercentage (numeric) and Error
+    (populated on a failed job), so those decide; the English literal is kept
+    only as a fast path for the common case.
+    """
+    status = status or {}
+    if str(status.get("JobStatus") or "") == "Complete":
+        return True
+    if status.get("Error"):
+        return False
+    try:
+        return float(status.get("CompletionPercentage")) >= 100
+    except (TypeError, ValueError):
+        return False
+
+
 def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
     """Render exactly one frame — the only frame-accurate capture route.
 
@@ -14944,9 +14966,14 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
             time.sleep(0.25)
             waited += 0.25
         status = _ser(proj.GetRenderJobStatus(job)) or {}
-        if status.get("JobStatus") != "Complete":
+        # Localized JobStatus ("Concluso" on an Italian install, issue #191)
+        # cannot be compared to the English word; the file check below is the
+        # real proof anyway.
+        if not _render_job_completed(status):
             return _err(
-                f"Render did not complete: {status.get('JobStatus')}",
+                f"Render did not complete: JobStatus {status.get('JobStatus')!r} "
+                f"at {status.get('CompletionPercentage')}%"
+                + (f" — {status.get('Error')}" if status.get("Error") else ""),
                 code="RENDER_FAILED", category="api_error",
                 state={"status": status, "frame": frame},
             )
@@ -20350,16 +20377,19 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
                                 "issue #164)."
                             )
             else:
-                if status.get("JobStatus") == "Complete":
+                if _render_job_completed(status):
                     warnings.append(
-                        "JobStatus is Complete but the output file does not exist."
+                        f"JobStatus is {job_status!r} (complete) but the output "
+                        "file does not exist."
                     )
-        if job_status and job_status != "Complete":
+        if job_status and not _render_job_completed(status):
             # Spotted live: a Failed job that wrote a stub file otherwise
             # produced verified:true — a duration ratio means nothing when
-            # Resolve itself says the job did not complete.
+            # Resolve itself says the job did not complete. Decided on the
+            # locale-independent fields, not the JobStatus word (issue #191).
             warnings.append(
-                f"JobStatus is {job_status!r}, not Complete"
+                f"JobStatus is {job_status!r} at "
+                f"{status.get('CompletionPercentage')}%, not complete"
                 + (f": {status.get('Error')}" if status.get("Error") else "")
             )
         result["warnings"] = warnings

package/src/utils/api_truth.py

@@ -2182,6 +2182,37 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["timeline", "edit", "render", "silent-failure", "media-pool"],
         "issue": 164,
     },
+    {
+        "symbol": "Project.GetRenderJobStatus JobStatus (localized display string)",
+        "object": "Project",
+        "signature": "(jobId) -> {JobStatus, CompletionPercentage, "
+                     "TimeTakenToRenderInMs, Error?}",
+        "reality": "JobStatus is a display string that follows the application "
+                   "language, not an enum. An English install reports "
+                   "\"Complete\"; an Italian install reports \"Concluso\" for "
+                   "the same finished job — read back as {JobStatus: "
+                   "\"Concluso\", CompletionPercentage: 100, "
+                   "TimeTakenToRenderInMs: 1225} on Studio 21.0.2.4 / macOS 15 "
+                   "with the output file complete on disk (issue #191, "
+                   "reporter's session). Any code that compares the field to "
+                   "the English word fails every non-English Resolve with an "
+                   "error that says the opposite of what happened; this "
+                   "server's single-frame capture did exactly that until "
+                   "v2.210.1. CompletionPercentage is numeric and "
+                   "locale-independent, and Error is populated on a failed "
+                   "job in every language.",
+        "recommended": "Never gate on the JobStatus string. Treat a job as "
+                       "finished when CompletionPercentage reaches 100 and "
+                       "Error is empty, then confirm the output file exists — "
+                       "the file is the real proof either way (see the "
+                       "recordFrame entry above for a Complete job that wrote "
+                       "a stub). Report JobStatus verbatim for humans only. "
+                       "This server's _render_job_completed() applies the rule "
+                       "to frame capture and render.verify_output.",
+        "tags": ["render", "localization", "silent-failure"],
+        "submit": "missing",
+        "issue": 191,
+    },
     {
         "symbol": "Timeline.DeleteClips (requires the Edit page; flaky first attempt)",
         "object": "Timeline",

package/src/utils/destructive_hook.py

@@ -252,6 +252,104 @@ DRY_RUN_DEFAULT_TRUE_ACTIONS: frozenset = frozenset({
 })
 
 
+# ── Native dry-run allowlist ────────────────────────────────────────────────
+#
+# Registered destructive actions whose handler genuinely reads `dry_run` and
+# returns a plan instead of mutating. Every OTHER registered destructive action
+# ignores the flag: `timeline_markers.add` with `dry_run=true` added a real
+# marker, `timeline.delete_track` with `dry_run=true` deleted the track. An
+# agent following the guidance "prefer dry_run where it exists" cannot tell
+# the two apart from the outside, so an explicit `dry_run=true` on a registered
+# destructive action outside this set is REFUSED (DRY_RUN_UNAVAILABLE) before
+# archive, state lookup, or handler execution — nothing simulated, nothing
+# executed, and the response says so.
+#
+# This is deliberately a refusal and not a synthesised preview: the lifecycle
+# pipeline's original dry-run interceptor answered `success: true` for calls
+# it never ran and was removed for it (see
+# execution_lifecycle.LifecyclePipeline._register_default_hooks). A dry run
+# that always succeeds is worse than none, because it is trusted.
+#
+# The set is pinned by tests.test_destructive_hook against a static scan of
+# src/server.py that follows the params object into helpers: add a native
+# dry-run branch to a handler and the test tells you to list it here; list an
+# action here without one and the test refuses.
+
+NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
+    ("media_pool", "clear_clip_marks"),
+    ("media_pool", "set_clip_marks"),
+    ("media_pool", "setup_multicam_timeline"),
+    ("timeline", "apply_cuts"),
+    ("timeline", "ripple_insert"),
+    ("timeline_ai", "create_subtitles"),
+})
+
+
+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
+
+
+def lacks_native_dry_run(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """True when the caller asked for a dry run this destructive action cannot honour.
+
+    Keyed on the destructive registry rather than `is_destructive()` so the
+    no-archive filters (a Notes edit, say) cannot let a dry-run request slip
+    through to a handler that would execute it for real.
+    """
+    return (
+        _explicit_dry_run_requested(params)
+        and action in DESTRUCTIVE_ACTIONS_BY_TOOL.get(tool_name, frozenset())
+        and (tool_name, action) not in NATIVE_DRY_RUN_ACTIONS
+    )
+
+
+def _dry_run_unavailable_response(
+    *,
+    operation_id: str,
+    tool_name: str,
+    action: str,
+    assessment: RiskAssessment,
+) -> Dict[str, Any]:
+    return {
+        "success": False,
+        "status": "dry_run_unavailable",
+        "dry_run": True,
+        "simulated": False,
+        "executed": False,
+        "operation_id": operation_id,
+        "security": {
+            "risk_level": assessment.level.value,
+            "risk_established": assessment.recognised,
+            "safe_mode": _safe_mode_enabled(),
+            "blocked": True,
+            "policy": "destructive.dry_run_support",
+        },
+        "risk": assessment.to_dict(),
+        "error": {
+            "message": (
+                f"'{tool_name}.{action}' has no native dry-run path, so dry_run=true "
+                "cannot be honoured. Nothing was simulated and nothing was executed."
+            ),
+            "code": "DRY_RUN_UNAVAILABLE",
+            "category": "dry_run_unavailable",
+            "retryable": False,
+            "remediation": (
+                "Use inspect_operation for the static risk assessment, use a "
+                "probe_*/safe_* action where one exists, or call again without "
+                "dry_run once the operation has been reviewed."
+            ),
+        },
+    }
+
+
 def _payload_is_plan_only(
     tool_name: str, action: str, params: Optional[Dict[str, Any]],
 ) -> bool:
@@ -627,6 +725,29 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
     def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
         @functools.wraps(fn)
         def wrapper(action: str, params: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Any:
+            if lacks_native_dry_run(tool_name, action, params):
+                # An explicit dry-run request this handler would silently
+                # execute for real. Refuse before archive, state lookup, or the
+                # handler itself; see NATIVE_DRY_RUN_ACTIONS.
+                operation_id = f"op_{uuid.uuid4().hex[:12]}"
+                assessment = assess_action_risk(tool_name, action, params)
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=assessment.level.value,
+                    status="blocked",
+                    params=params,
+                    reason="dry_run_unavailable",
+                    recognised=assessment.recognised,
+                )
+                return _dry_run_unavailable_response(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    assessment=assessment,
+                )
+
             if not is_destructive(tool_name, action, params):
                 return fn(action, params, *args, **kwargs)