davinci-resolve-mcp 4.1.3 → 4.2.0

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 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.2.0 — the raw grade-copy asks before it overwrites, and an injected grade shows as graded
+
+Contributed by [@Rohitkanithi](https://github.com/Rohitkanithi) in
+[#231](https://github.com/samuelgursky/davinci-resolve-mcp/pull/231), plus a
+fix to the offline `.drp` grade-injection tier.
+
+### Added
+
+- **`timeline_item_color copy_grades` now takes a `confirm_token` and requires
+  one before it calls `TimelineItem.CopyGrades`.** The raw action reaches an API
+  that replaces the target's entire node graph with the source's, with no
+  recovery version — reconfirmed on Studio 21.1.0.14 in
+  [#207](https://github.com/samuelgursky/davinci-resolve-mcp/issues/207), where
+  the target's exported grade became byte-identical to the source and the
+  version list stayed `['Version 1']` throughout. Until now the trap
+  acknowledgement was the only barrier, and acknowledging a trap is a statement
+  about understanding the API, not about the clips in front of you.
+
+  The first call now returns `confirmation_required` with a preview built from
+  the targets it actually resolved — how many, which IDs, and which IDs were not
+  found on any video track — and a one-time token bound to the action and a
+  fingerprint of the params. Change `target_ids` after receiving the token and
+  the token no longer matches. The trap gate still runs first, so the sequence is
+  acknowledge, inspect the resolved targets, then commit. The safe siblings
+  (`safe_copy_grade`, `bulk_match_to_hero`) already gated their own writes; this
+  closes the raw path that bypassed them.
+
+  A side effect of routing target resolution through the existing
+  `_timeline_items_for_grade_copy` helper: IDs that resolve to nothing are now
+  **reported** rather than silently dropped, which is the "No target existence
+  check" the action's own docstring had been warning about.
+
+### Fixed
+
+- **An injected grade rendered correctly but the Color page listed the clip as
+  ungraded.** Resolve decides "graded" from the per-version `<HasCorrection>`
+  element beside the `Body`, not from the body bytes. `injectGrades` replaced the
+  `Body` and left the flag as it found it, so on a 352-clip balance pass the
+  grades were live while the page showed them missing. The version element lists
+  `HasCorrection` before `Body`, so the last `HasCorrection` preceding the
+  replaced `Body` is the owner's; it is now flipped to true and untouched clips
+  keep their flag. The test builds an ungraded two-clip DRP, injects one, and
+  asserts the target reads true while the sibling still reads false, with an
+  already-corrected fixture as the null control.
+
+### Validation
+
+- Full offline suite on the merged result: **3,620 passed, 1 skipped,
+  1,257 subtests passed, zero failures.** The `drp-format` Node tests pass
+  (8 passed, 1 skipped), including the new `HasCorrection` case.
+- All release drift guards green, including `test_write_enforcement_ratchet`,
+  `test_doc_tool_counts`, `test_action_list_drift` and
+  `test_release_surface_drift`.
+- No Resolve live run: the confirm-token gate is server-side control flow, and
+  the `.drp` change is offline file authoring covered by its own round-trip test.
+  Neither alters what Resolve is asked to do once a call is allowed through.
+
 ## What's New in v4.1.3 — every live harness could no longer start, and a probe that could never pass
 
 Reported and measured by [@legionsound](https://github.com/legionsound) in

package/README.md

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

package/resolve-advanced/vendor/drp-format/__tests__/inject-grades.test.js

@@ -244,3 +244,39 @@ test('injectGrades: internals — extractDrxBodyHex throws on missing Body', ()
 test.skip('injectGrades: rendered frame matches direct DRX apply '
   + '(covered by tests/live_drp_roundtrip_verification.py — grade-render compare still TODO)',
 () => {});
+
+test('injectGrades: flips the owning version\'s HasCorrection to true (Resolve reads the flag, not the body)', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'inject-hc-'));
+  const src = path.join(dir, 'src.drp');
+  const out = path.join(dir, 'out.drp');
+  const buf = await drpFormat.buildDRP({
+    projectName: 'inject-hc-test',
+    timelines: [{
+      name: 'T1', frameRate: 24, startTimecode: '01:00:00:00', resolution: '1920x1080',
+      videoTracks: [{ clips: [
+        { start: 0, duration: 24, in: 0, mediaFilePath: '/synthetic/a.mov', grade: { body: BASELINE_BODY, hasCorrection: false, versionName: 'V1' } },
+        { start: 24, duration: 24, in: 0, mediaFilePath: '/synthetic/b.mov', grade: { body: ORIGINAL_BODY_CLIP_2, hasCorrection: false, versionName: 'V1' } },
+      ] }],
+      audioTracks: [],
+    }],
+  });
+  await fs.writeFile(src, buf);
+  const before = await readSeqContainer(src);
+  assert.equal((before.match(/<HasCorrection>true<\/HasCorrection>/g) || []).length, 0, 'fixture starts ungraded');
+  const ids = [...before.matchAll(/<(?:Sm2TiVideoClip|Sm2VideoClip)[^>]*?DbId="([^"]+)"/g)].map((m) => m[1]);
+  assert.equal(ids.length, 2);
+  await drpFormat.injectGrades(src, [{ clipId: ids[0], drxContent: makeSyntheticDrx(INJECTED_BODY) }], { outputPath: out });
+  const after = await readSeqContainer(out);
+  const clipBlock = (xml, id) => {
+    const i = xml.indexOf(`DbId="${id}"`);
+    const j = xml.indexOf('</Sm2TiVideoClip>', i);
+    return xml.slice(i, j);
+  };
+  assert.match(clipBlock(after, ids[0]), /<HasCorrection>true<\/HasCorrection>/, 'targeted clip is now marked corrected');
+  assert.match(clipBlock(after, ids[0]), new RegExp(`<Body>${INJECTED_BODY}</Body>`));
+  assert.match(clipBlock(after, ids[1]), /<HasCorrection>false<\/HasCorrection>/, 'untouched clip keeps its flag');
+  assert.doesNotMatch(clipBlock(after, ids[1]), /<HasCorrection>true/);
+  // Null control: injecting into an already-corrected version changes nothing but the body.
+  const already = await readSeqContainer(src);
+  assert.equal((already.match(/<HasCorrection>/g) || []).length, 2);
+});

package/resolve-advanced/vendor/drp-format/inject-grades.js

@@ -56,7 +56,8 @@ function extractDrxBodyHex(drxContent) {
  *
  * Scoping: the regex anchors on `<Sm2TiVideoClip ... DbId="<id>"` and
  * runs forward to the matching `</Sm2TiVideoClip>`. Inside that range we
- * replace exactly one <Body>HEX</Body>. If a clip has no Body yet (a
+ * replace exactly one <Body>HEX</Body> and flip the owning version's
+ * <HasCorrection> to true. If a clip has no Body yet (a
  * brand-new clip with no grade) we don't synthesize the surrounding
  * LmVersionTable scaffolding — that's a builder responsibility, not an
  * injector one. Callers wanting to add grades to clean clips should
@@ -100,12 +101,32 @@ function replaceBodyForClip(seqXml, targetDbId, newBodyHex) {
   // 3. Within the clip's range, replace exactly one <Body>...</Body>.
   const clipRange = seqXml.slice(openStart, clipEnd);
   const bodyRe = /<Body>([\s\S]*?)<\/Body>/;
-  if (!bodyRe.test(clipRange)) return null;
-  const newClipRange = clipRange.replace(
+  const bodyAt = clipRange.search(bodyRe);
+  if (bodyAt < 0) return null;
+  let newClipRange = clipRange.replace(
     bodyRe,
     `<Body>${newBodyHex}</Body>`,
   );
 
+  // 4. Mark the owning version as corrected. Resolve keeps a per-version
+  //    <HasCorrection> flag beside the Body and its UI reads THAT (clip strip
+  //    "graded"/"ungraded", clip filters), not the body bytes — a body
+  //    injected into a version left at false renders the grade but shows the
+  //    clip as ungraded (JREG2, 2026-09-13). The version element lists
+  //    HasCorrection before Body, so the last HasCorrection preceding the
+  //    replaced Body is the owner's.
+  const head = newClipRange.slice(0, bodyAt);
+  const hcAt = head.lastIndexOf('<HasCorrection>');
+  if (hcAt >= 0) {
+    const hcEnd = head.indexOf('</HasCorrection>', hcAt);
+    if (hcEnd > hcAt) {
+      newClipRange =
+        head.slice(0, hcAt) +
+        '<HasCorrection>true</HasCorrection>' +
+        newClipRange.slice(hcEnd + '</HasCorrection>'.length);
+    }
+  }
+
   return seqXml.slice(0, openStart) + newClipRange + seqXml.slice(clipEnd);
 }
 

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.1.3"
+VERSION = "4.2.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.1.3"
+VERSION = "4.2.0"
 
 import base64
 import os
@@ -28657,8 +28657,8 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
     Raw mutators (UNSAFE direct mutation — prefer the safe_* sibling):
       set_cdl(cdl, ...) -> {success}
         UNSAFE. No validation; no dry_run. Prefer safe_set_cdl.
-      copy_grades(target_ids, ...) -> {success}
-        UNSAFE. No target existence check. Prefer safe_copy_grade.
+      copy_grades(target_ids, confirm_token?, ...) -> {success}
+        UNSAFE. Replaces target grades and is confirm-token gated. Prefer safe_copy_grade.
       export_lut(type, path, ...) -> {success}
         UNSAFE. No path sandboxing. Prefer safe_export_lut.
       reset_all_node_colors(...) -> {success}
@@ -28738,14 +28738,23 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
     elif action == "copy_grades":
         # Find target items by IDs
         _, tl, _ = _get_tl()
-        targets = []
-        target_ids = set(p["target_ids"])
+        target_ids = p["target_ids"]
         if tl:
-            for tt in ["video"]:
-                for ti in range(1, tl.GetTrackCount(tt) + 1):
-                    for it in (tl.GetItemListInTrack(tt, ti) or []):
-                        if it.GetUniqueId() in target_ids:
-                            targets.append(it)
+            targets, missing = _timeline_items_for_grade_copy(tl, target_ids)
+        else:
+            targets, missing = [], sorted(set(target_ids or []))
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            preview = {
+                "operation": "timeline_item_color.copy_grades",
+                "warning": "Replaces the entire node graph on every successfully resolved target item.",
+                "target_count": len(targets),
+                "target_ids": [target.GetUniqueId() for target in targets],
+                "missing": missing,
+            }
+            return _issue_confirm_token(action="timeline_item_color.copy_grades", params=p, preview=preview)
+        blocked = _consume_confirm_token(action="timeline_item_color.copy_grades", params=p)
+        if blocked:
+            return blocked
         return {"success": bool(item.CopyGrades(targets))}
     elif action == "add_version":
         return {"success": bool(item.AddVersion(p["name"], p.get("type", 0)))}