davinci-resolve-mcp 4.4.0 → 4.4.2

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 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.2 — a refused option now says which one, and why
+
+Reported as [#232](https://github.com/samuelgursky/davinci-resolve-mcp/issues/232):
+`timeline.normalize_audio_level` "rejects every documented option schema". It does
+not, and a test now pins all seven documented `NormalizeAudioOptions` shapes reaching
+the native call. The defect was the refusal itself.
+
+### Fixed
+
+- **One error message covered two unrelated failures.** `Unknown normalization
+  options or non-dictionary options` named neither the offending key nor the type
+  actually received, and listed nothing that *would* have been accepted — so a typo
+  and a malformed payload were indistinguishable, to the caller and to the bug
+  report. The only way to produce that message while passing documented keys is an
+  `options` that arrived as a **JSON string**, which some MCP clients produce when
+  they serialise a nested object. That caller is looking at a payload that appears
+  correct, so the refusal now says so in as many words:
+
+  ```
+  normalization options must be an object with any of normalizationMode,
+  targetLevel, targetLoudness, setLevelMode; received a string. It looks like a
+  JSON string — send options as a nested object, not as encoded text.
+  ```
+
+  An unknown key reads differently, because the cause and the fix are different:
+
+  ```
+  Unknown normalization option 'normalisationMode'; accepted keys are
+  normalizationMode, targetLevel, targetLoudness, setLevelMode.
+  ```
+
+- **`auto_align_clips` carried the identical conflation** and now shares the same
+  builder, `src/utils/option_errors.py`.
+
+### Validation
+
+- Full offline suite: **3,655 passed, 1 skipped, 0 failed**, 1,276 subtests.
+- **No behaviour change to accepted input.** The same options are accepted and reach
+  the same native call; a test asserts each of the seven documented shapes arrives at
+  `NormalizeAudioLevel`, and that a JSON-string payload is refused *without* reaching
+  it. No Resolve live run: nothing about the native call changed.
+
+### Still unconfirmed
+
+The reporter has not replied, so the JSON-string diagnosis remains the most likely
+cause rather than a measured one. If their payload was something else, the new
+message will now say what — which is the actual fix here.
+
+## What's New in v4.4.1 — the safety ratchet stops scanning only half the project
+
+The write-enforcement ratchet read `src/server.py` and nothing else. The granular
+server's 387 tools were covered by no guard at all — not a risk table, not the
+destructive registry, not the ratchet. That is how `ti_copy_grades` reached
+`TimelineItem.CopyGrades`, which replaces a node graph with no recovery version,
+behind nothing. v4.3.0 fixed that one tool by hand; nothing would have caught the
+next one.
+
+### Added
+
+- **`tests/test_write_enforcement_ratchet.py` now scans both servers.** They are
+  built differently, so the granular tests claim different things and the module
+  docstring says which is which:
+
+  - **Enforcement.** A granular tool that calls a symbol the ledger marks
+    `destroys_prior_work` must be gated — `acknowledge_trap` plus a confirm token —
+    and must be hinted destructive, so a client that refuses destructive tools never
+    reaches the confirmation at all. `TRAP_METHODS` is derived from `API_TRUTH`
+    rather than written out, so flagging a new entry extends this guard without
+    anyone remembering that this file exists.
+  - **Visibility.** The other **131** destructive-hinted granular tools are frozen
+    in a backlog that can only shrink. This does **not** make them safe: the
+    granular server has no enforcement hook — `@_destructive_op` wraps an
+    `(action, params)` signature granular tools do not have — so there is no
+    archive, no safe-mode refusal and no audit row behind any of them. The backlog
+    makes the number known, and makes the 132nd fail the suite.
+
+### Fixed
+
+- **The first draft of the gate detector could be fooled by dead code.** It looked
+  for the string `CONFIRM_TOKENS` in the function body, so deleting the token
+  *redemption* while leaving the *issuance* behind still read as gated — and issuing
+  a token nobody checks is exactly the regression worth catching. Gating is now
+  detected as AST call nodes (`issue` **and** `consume` on `CONFIRM_TOKENS`) plus
+  the real `acknowledge_trap` and `confirm_token` parameters.
+
+### Validation
+
+- Five regressions re-introduced deliberately, each confirming a guard fires rather
+  than passing vacuously: delete the redemption, drop `acknowledge_trap`, drop the
+  destructive annotation, add a new ungated destructive tool, and gate a tool still
+  on the backlog. **Two of the five passed against the first draft** — the dead-code
+  hole above, and a probe that silently did nothing because `ast.unparse` drops
+  comments. Both the guard and the probes were fixed until all five failed on
+  demand and passed on restore.
+- Full offline suite: **3,644 passed, 1 skipped, 0 failed**, 1,269 subtests. All
+  release drift guards green.
+- Tests only; no server behaviour changed and no Resolve call was made.
+
 ## 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

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.4.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.4.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.4.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.4.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.4.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.4.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.4.0"
+VERSION = "4.4.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.4.0",
+  "version": "4.4.2",
   "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.4.0"
+VERSION = "4.4.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.4.0"
+VERSION = "4.4.2"
 
 import base64
 import os

package/src/utils/option_errors.py

@@ -0,0 +1,77 @@
+"""Say which option was wrong, and how — not merely that something was.
+
+Issue #232 reported that `timeline.normalize_audio_level` "rejects every documented
+option schema". It does not: every shape in `NormalizeAudioOptions` is accepted. But
+the refusal read
+
+    Unknown normalization options or non-dictionary options
+
+which folds two unrelated failures into one sentence, names neither the offending
+key nor the type actually received, and lists nothing that *would* be accepted. A
+caller whose MCP client had serialised `options` to a JSON string — the one way to
+produce that message while passing documented keys — had no way to tell that from a
+typo, and neither did the report.
+
+So the message is the bug worth fixing. These builders make a refusal answer three
+questions: what was wrong, what was received, and what would have been accepted.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+
+def _type_name(value: Any) -> str:
+    """A type name a caller will recognise from their own client's payload."""
+    return {
+        str: "a string",
+        list: "a list",
+        tuple: "a list",
+        int: "a number",
+        float: "a number",
+        bool: "a boolean",
+        type(None): "null",
+    }.get(type(value), f"a {type(value).__name__}")
+
+
+def reject_option_keys(
+    options: Any,
+    accepted: Iterable[str],
+    label: str,
+    *,
+    allow_empty: bool = True,
+) -> Optional[str]:
+    """Refuse a malformed options mapping, or return None when it is usable.
+
+    The two failures are reported separately because they have different causes and
+    different fixes: a non-mapping is almost always the client serialising a nested
+    object, while an unknown key is a typo or a stale field name.
+    """
+    accepted = tuple(accepted)
+    if not isinstance(options, dict):
+        hint = ""
+        if isinstance(options, str):
+            # By far the likeliest way to reach here with correct keys: some MCP
+            # clients JSON-encode nested objects. Say so, because the caller is
+            # looking at a payload that appears correct.
+            hint = (
+                " It looks like a JSON string — send options as a nested object, "
+                "not as encoded text."
+            )
+        return (
+            f"{label} options must be an object with any of "
+            f"{', '.join(accepted)}; received {_type_name(options)}.{hint}"
+        )
+    if not options and not allow_empty:
+        return (
+            f"{label} options must not be empty; accepted keys are "
+            f"{', '.join(accepted)}."
+        )
+    unknown = sorted(set(options) - set(accepted))
+    if unknown:
+        return (
+            f"Unknown {label} option{'s' if len(unknown) > 1 else ''} "
+            f"{', '.join(repr(k) for k in unknown)}; accepted keys are "
+            f"{', '.join(accepted)}."
+        )
+    return None

package/src/utils/resolve211_alignment.py

@@ -1,4 +1,5 @@
 """Native alignment with strict ID resolution before any timeline mutation."""
+from src.utils.option_errors import reject_option_keys
 from src.utils.resolve211_multicam import resolve_constant
 
 OPTIONS = {
@@ -12,8 +13,9 @@ def auto_align(r, timeline, item_ids, options):
         return {'error':'item_ids must be a non-empty list of timeline item unique IDs'}
     if len(set(item_ids))!=len(item_ids):
         return {'error':'item_ids must not contain duplicates'}
-    if not isinstance(options,dict) or set(options)-set(OPTIONS):
-        return {'error':'options must contain only SyncUsing and/or UseTrack'}
+    error = reject_option_keys(options, tuple(OPTIONS), 'alignment')
+    if error:
+        return {'error': error}
     normalized={}
     for key,value in options.items():
         normalized[key],error=resolve_constant(r,value,OPTIONS[key])

package/src/utils/resolve211_normalization.py

@@ -1,6 +1,11 @@
 """Native normalization: validate explicit audio-item selection before writes."""
 import math
 
+from src.utils.option_errors import reject_option_keys
+
+#: The full NormalizeAudioOptions surface, per the shipped typed API stub.
+OPTION_KEYS = ('normalizationMode', 'targetLevel', 'targetLoudness', 'setLevelMode')
+
 
 def finite_number(value):
     try:
@@ -14,8 +19,9 @@ def normalize_audio(r, timeline, item_ids, options):
         return {'error':'item_ids must be a non-empty list of audio timeline item unique IDs'}
     if len(set(item_ids))!=len(item_ids):
         return {'error':'item_ids must not contain duplicates'}
-    if not isinstance(options,dict) or set(options)-{'normalizationMode','targetLevel','targetLoudness','setLevelMode'}:
-        return {'error':'Unknown normalization options or non-dictionary options'}
+    error = reject_option_keys(options, OPTION_KEYS, 'normalization')
+    if error:
+        return {'error': error}
     normalized=dict(options)
     for key,value in options.items():
         if key=='normalizationMode':