davinci-resolve-mcp 4.8.18 → 4.8.19

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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.8.19 — generated OFX nodes bind their params on Resolve 21.0
+
+### Fixed
+
+- **Generated OFX nodes could apply but run on the plugin's defaults.** ([#267](https://github.com/samuelgursky/davinci-resolve-mcp/pull/267), @noah1234j)
+  In a native Resolve capture the tool-list instance entry carries
+  `<context>_<clip-version DbId>_<node id>`, while the OFX container keeps the bare
+  context name. The DRX generator wrote the bare name in both slots. On Studio
+  21.0.0.48 the contributor measured that the plugin's stored params then do not
+  bind, so a Color Space Transform ignores its input/output spaces.
+  `generateMultiNodeDRX` now creates the clip-version id before the nodes and emits
+  the keyed form in the tool-list slot. An explicit `options.instanceKey` still wins.
+  Reported fix: the generated CST's 33-pt LUT is bit-identical to a hand-built CST
+  on 21.0.0.48.
+  Measured here on Studio 19.1.3.7: both forms already bind on that build, and the
+  new generator's LUTs are bit-identical to the old one's for every variant tested
+  (CC only, CST with default params, two different CST parameter sets), so nothing
+  changes on 19.1.3.
+- **Integer/choice OFX params round-trip.** `buildOFXToolEntry` encodes `{int: n}`
+  and booleans as varint F3 (e.g. CST `doFwdOOTF` / `doInvOOTF`), and
+  `extract-ofx-params` now decodes F3 to `{int: n}` instead of `null`, so parse →
+  generate keeps them. Guard test: `vendor/drx-codec/__tests__/ofx-instance-key.test.js`.
+
 ## What's New in v4.8.18 — `copy_clip_annotations` honours `include_*="false"`
 
 ### Fixed

package/README.md

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

package/resolve-advanced/vendor/drx-codec/__tests__/ofx-instance-key.test.js

@@ -0,0 +1,96 @@
+/**
+ * OFX instance binding + integer params in generated DRX.
+ *
+ * Native Resolve (Studio 21.0 CST capture) writes the tool-list instance entry
+ * (0xC000005E) as "<context>_<clip-version DbId>_<node id>" while the OFX
+ * container's F3 keeps the bare context. With the bare context in both slots
+ * the node applies but the plugin's stored params never bind — verified live by
+ * exporting a 33-pt LUT: the generated CST only matched a hand-built CST
+ * (bit-identical, 35,937/35,937 points) once the keyed form was emitted.
+ *
+ * Integer params (doFwdOOTF / doInvOOTF) are varint F3 on the wire.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const zlib = require('node:zlib');
+
+const { drxGenerator, drxParser } = require('..');
+
+const CST = 'com.blackmagicdesign.resolvefx.colorspacetransformv2';
+
+function decompressClipBody(xml) {
+  const hex = xml.match(/<pClipFullVer>[\s\S]*?<Body>([0-9a-f]+)<\/Body>/)[1];
+  const body = Buffer.from(hex, 'hex');
+  assert.equal(body[0], 0x81);
+  const decompress = zlib.zstdDecompressSync
+    ? (b) => zlib.zstdDecompressSync(b)
+    : (b) => Buffer.from(require('fzstd').decompress(b));
+  return decompress(body.subarray(1));
+}
+
+async function generateCstGraph() {
+  const nodes = [
+    { label: 'CC' },
+    {
+      label: 'CST 709',
+      params: {
+        ofx: {
+          pluginId: CST,
+          params: {
+            inputColorSpace: 'DWG_COLORSPACE',
+            inputGamma: 'DAV_INTER_OETF_GAMMA',
+            outputColorSpace: 'REC709_COLORSPACE',
+            outputGamma: 'TWOPOINTFOUR_GAMMA',
+            doFwdOOTF: { int: 1 },
+            doInvOOTF: { int: 0 },
+          },
+          options: { version: '1.4' },
+        },
+      },
+    },
+  ];
+  return drxGenerator.generateMultiNodeDRX(nodes, [{ from: 1, to: 2 }], { label: 'test' });
+}
+
+test('tool-list instance entry is keyed by clip version DbId and node id', async () => {
+  const xml = await generateCstGraph();
+  const versionId = xml.match(/<pClipFullVer>\s*<ListMgt::LmVersion DbId="([0-9a-f-]+)"/)[1];
+  const raw = decompressClipBody(xml);
+  // Fresh mode numbers nodes from 2, so the CST (second node) has id 3.
+  const keyed = Buffer.from(`OfxImageEffectContextFilter_${versionId}_3`, 'utf-8');
+  assert.ok(raw.includes(keyed), 'keyed instance id present in tool list');
+});
+
+test('OFX container keeps the bare context name', async () => {
+  const xml = await generateCstGraph();
+  const parsed = await drxParser.parseDRXContent(xml);
+  const tool = parsed.nodes[1].ofxTools[0];
+  assert.equal(tool.pluginId, CST);
+  assert.equal(tool.instanceId, 'OfxImageEffectContextFilter');
+});
+
+test('integer params round-trip as {int} via varint F3', async () => {
+  const xml = await generateCstGraph();
+  const parsed = await drxParser.parseDRXContent(xml);
+  const params = parsed.nodes[1].ofxTools[0].params;
+  assert.deepEqual(params.doFwdOOTF, { int: 1 });
+  assert.deepEqual(params.doInvOOTF, { int: 0 });
+  assert.equal(params.inputColorSpace, 'DWG_COLORSPACE');
+  assert.equal(params.outputGamma, 'TWOPOINTFOUR_GAMMA');
+
+  // wire check: name entry followed by F2{F3 varint 1}
+  const raw = decompressClipBody(xml);
+  const name = Buffer.from('doFwdOOTF', 'utf-8');
+  const expected = Buffer.concat([Buffer.from([0x0a, name.length]), name, Buffer.from([0x12, 0x02, 0x18, 0x01])]);
+  assert.ok(raw.includes(expected), 'doFwdOOTF encoded as varint F3');
+});
+
+test('explicit instanceKey option is honoured', async () => {
+  const xml = await drxGenerator.generateMultiNodeDRX(
+    [{ label: 'X', params: { ofx: { pluginId: CST, params: {}, options: { instanceKey: 'Custom_key_9' } } } }],
+    [],
+    { label: 'test' },
+  );
+  assert.ok(decompressClipBody(xml).includes(Buffer.from('Custom_key_9')));
+});

package/resolve-advanced/vendor/drx-codec/drx-generator.js

@@ -900,7 +900,12 @@ function createNode(nodeId, xPos, yPos, colorParams = null, options = {}) {
   // OFX spec ({ofx:{pluginId, params, options?}}), emit the full OFX container instead
   // (params are self-describing name/value pairs on the wire — see extract-ofx-params).
   if (colorParams && colorParams.ofx && colorParams.ofx.pluginId) {
-    parts.push(buildOFXToolEntry(colorParams.ofx.pluginId, colorParams.ofx.params || {}, colorParams.ofx.options || {}));
+    const ofxOptions = { ...(colorParams.ofx.options || {}) };
+    if (options.clipVersionId && !ofxOptions.instanceKey) {
+      const ctx = ofxOptions.instanceId || 'OfxImageEffectContextFilter';
+      ofxOptions.instanceKey = `${ctx}_${options.clipVersionId}_${nodeId}`;
+    }
+    parts.push(buildOFXToolEntry(colorParams.ofx.pluginId, colorParams.ofx.params || {}, ofxOptions));
   } else {
     // Structure: F10 = {F1 = {F1=0xC0000001, F2={F2=2}}}
     const f10InnerInner = Buffer.concat([
@@ -1750,6 +1755,8 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
   } = metadata;
 
   const timestamp = generateTimestamp();
+  // The clip version DbId is also the key Resolve embeds in each OFX node's instance id.
+  const clipVersionId = require('node:crypto').randomUUID();
 
   // Determine node ID scheme
   let baseNodeId, firstNodeId, lastNodeId;
@@ -1798,6 +1805,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
         label: nodeConfig.label || `Node ${nodeIndex}`,
         enabled: nodeConfig.enabled !== false,
         nodeIndex: nodeIndex, // Pass separate index for F2 field
+        clipVersionId,
       }
     );
     containerParts.push(node);
@@ -1861,7 +1869,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
   // Generate UUIDs
   const { randomUUID: uuidv4 } = require('node:crypto');
   const stillId = uuidv4();
-  const clipVersionId = uuidv4();
+  // clipVersionId is generated before the nodes (it keys OFX instances).
 
   const now = new Date().toISOString().replace('Z', '');
 
@@ -3981,6 +3989,16 @@ function buildOFXToolEntry(pluginId, params, options = {}) {
   // plugin un-instantiated: node applies but the effect never engages — found live
   // 2026-07-03). Callers can still override for generator/transition contexts.
   const instanceId = options.instanceId || 'OfxImageEffectContextFilter';
+  // The tool-list instance entry (0xC000005E) is NOT the bare context name in native
+  // captures: Resolve writes "<context>_<clip-version DbId>_<node id>" there (e.g.
+  // "OfxImageEffectContextFilter_06aff833-..._5", Resolve Studio 21.0 CST capture),
+  // while the container's F3 keeps the bare context. With the bare name in both
+  // slots the node applies but the plugin's stored params do not bind, so it runs on
+  // defaults. generateMultiNodeDRX supplies the keyed form via options.instanceKey.
+  // Version scope: the unbound-params failure was reported on Studio 21.0.0.48
+  // (PR #267). On Studio 19.1.3.7 both forms bind: generated CSTs exported
+  // bit-identical 33-pt LUTs with the bare and the keyed id (measured 2026-09-23).
+  const instanceKey = options.instanceKey || instanceId;
 
   // Build F5 repeated param entries. Native containers always carry resolvefxVersion
   // and serialize params in name order — mirror both.
@@ -3993,6 +4011,11 @@ function buildOFXToolEntry(pluginId, params, options = {}) {
     if (typeof value === 'string') {
       const strBuf = Buffer.from(value, 'utf-8');
       valueBuf = protoBytes(5, strBuf);
+    } else if (typeof value === 'boolean') {
+      valueBuf = protoVarint(3, value ? 1 : 0);
+    } else if (value && typeof value === 'object' && Number.isInteger(value.int)) {
+      // Integer/choice params (e.g. CST doFwdOOTF) are varint F3 on the wire, not F2 doubles.
+      valueBuf = protoVarint(3, value.int);
     } else {
       valueBuf = protoFloat64(2, value);
     }
@@ -4023,10 +4046,10 @@ function buildOFXToolEntry(pluginId, params, options = {}) {
       protoVarint(1, ID_PLUGIN),
       protoBytes(2, protoBytes(5, Buffer.from(pluginId, 'utf-8'))),
     ])),
-    // Instance ID
+    // Instance ID (keyed form — see instanceKey above)
     protoBytes(1, Buffer.concat([
       protoVarint(1, ID_INSTANCE),
-      protoBytes(2, protoBytes(5, Buffer.from(instanceId, 'utf-8'))),
+      protoBytes(2, protoBytes(5, Buffer.from(instanceKey, 'utf-8'))),
     ])),
     // Enable flag (native captures carry 0 here for enabled plugins)
     protoBytes(1, Buffer.concat([

package/resolve-advanced/vendor/drx-codec/extract-ofx-params.js

@@ -88,7 +88,11 @@ const OFY_MARKER = 0x4F4659;
 /**
  * Decode an F5 param-entry buffer to {name, value}.
  * F1 = name (length-delimited UTF-8)
- * F2 = wrapped value (F2 = float64 OR F5 = UTF-8 string)
+ * F2 = wrapped value (F2 = float64, F3 = varint int/choice, OR F5 = UTF-8 string)
+ *
+ * Integer params (e.g. Color Space Transform doFwdOOTF / doInvOOTF) come back as
+ * {int: n} — the same shape buildOFXToolEntry accepts — so a parse → generate
+ * round-trip re-emits them as varints instead of dropping or float-encoding them.
  */
 function decodeParamEntry(entryBuf) {
   let name = '';
@@ -103,6 +107,8 @@ function decodeParamEntry(entryBuf) {
       for (const inn of inner) {
         if (inn.fieldNum === 2 && inn.wireType === 1) {
           value = inn.value; // float64
+        } else if (inn.fieldNum === 3 && inn.wireType === 0) {
+          value = { int: Number(inn.value) };
         } else if (inn.fieldNum === 5 && inn.wireType === 2) {
           value = utf8(inn.value);
         }

package/src/granular/common.py

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