davinci-resolve-mcp 4.15.5 → 4.17.0

package/CHANGELOG.md

@@ -2,6 +2,123 @@
 
 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.17.0 — Power windows for Resolve 21
+
+### Added
+
+- **`drx generate` takes `resolveVersion`** (#328, thanks @hpaul). A major
+  number (`21`) or a version string (`"21.0.4"`). From 21 on, circle and
+  linear power windows are written the way Resolve 21 exports them: corrector
+  type 0x10004 (65540) with the full parameter set, `REF_WIDTH` 288 and an
+  identity transform matrix, and 0x10004 added to the node's corrector-type
+  list. Resolve 21 loads the older corrector-type-4 form into the Window
+  palette but renders an empty mask, which also hides the node's grade.
+  The default is unchanged, so output for Resolve 19/20 is byte-for-byte
+  what it was. Gradient and polygon/curve windows are not rewritten. The
+  format follows justhung69/resolve-mcp (MIT), pixel-verified there on free
+  21.0.4.5.
+- The node's corrector-type list is now varint encoded, because 65540 does
+  not fit in one byte. Every type id below 128 encodes to the same byte as
+  before.
+
+### Validation
+
+- Advanced Node suite on Node 20 with a fresh `npm ci`, PR merged on
+  `main`: 1,214 tests, 1,153 passed, 0 failed, 61 skipped (8 new for the
+  Resolve 21 window layout). PR CI green on Python 3.10/3.11 and Node 20/22.
+- Not live-validated on Resolve 21: the maintainer's box runs Studio
+  19.1.3.7. The window layout is checked against Resolve 21 fixtures only.
+
+## What's New in v4.16.0 — Calls name their timeline, and failures say so
+
+Eight reports from a Studio 21.1 / Windows deployment (#320–#327) and the
+open half of #318. The theme: a call that did something other than what the
+caller asked, or failed, must not look like a success.
+
+### Added
+
+- **Pin a call to a timeline** (#320). `timeline`, `timeline_item*`,
+  `timeline_markers`, `timeline_frame`, `timeline_ai`, `graph` and `render`
+  accept `timeline_id` or `timeline_name`. The server makes that timeline
+  current for the call and restores the caller's timeline afterwards,
+  verified by readback. Unknown ids (`TIMELINE_NOT_FOUND`), ambiguous names
+  (`TIMELINE_NAME_AMBIGUOUS`) and an id/name pair that disagree are refused
+  before the action runs. Before, a `timeline_id` nothing read was dropped,
+  and the write landed on whichever timeline was current.
+- **Results name the timeline acted on** (#320): `_operation.timeline`
+  `{name, id}`, plus `pinned`, `restored_current` or `restore_failed` on a
+  pinned call.
+- **Unread params are reported** (#320). A successful call carrying keys the
+  action never read returns `ignored_params` and an envelope warning. They
+  are reported after the call, not refused before it: the server has no
+  per-action schema, and a static scan of the reachable code could not bound
+  the key set for 25 of the 37 tools.
+- **`timeline_item_id` on the timeline item tools** (#323). On 21.1
+  `item_index` counts transitions, so it shifts whenever one is added or
+  removed. Every tool that resolves an item through the shared lookup
+  accepts the item's `GetUniqueId()` and refuses an unknown id with
+  `ITEM_NOT_FOUND`.
+- **`drx generate` can target the timeline** (#318).
+  `target: "timeline"` writes the grade into `<pTrackVer>`, the block a
+  timeline `ApplyGradeFromDRX` loads, in the shape the reporter applied on
+  Studio 21.1.1.10. The default stays `"clip"`.
+- **`duplicate` takes `make_current`** and returns the copy's `id` and the
+  `current` timeline (#322).
+
+### Fixed
+
+- **Failed calls set MCP `isError: true`** (#321). Every error-envelope
+  result used to arrive with `isError: false`, so spec-following hooks and
+  retry policies counted refusals as successes. The flag is set at the
+  protocol boundary; the JSON body is unchanged. `{"success": false}` without
+  an `error` key is not flagged.
+- **`timeline.duplicate` leaves the original current** (#322) unless
+  `make_current: true`. Resolve makes the copy current, so "duplicate as a
+  backup, then edit" edited the backup.
+- **FCPXML round trip on the server's own export** (#324).
+  `import_timeline_checked` accepts the bundle directory 21.1 writes for
+  FCPXML and imports the `Info.fcpxml` inside.
+- **Online image sequences are not reported missing** (#325). A path like
+  `name.[0000-8999].jpeg` is checked by its first and last frames (printf and
+  `####` patterns by one matching frame). Before, `probe_timeline_structure`
+  said `file_exists: false`, and `detect_missing_media` and
+  `build_relink_plan` listed the clips for relink.
+- **The bridge honours `allowed_media_roots` / `allowed_output_roots`**
+  (#326). `load_config` dropped both, so the policies were always the home
+  folder. The generic `call` path the MCP server uses was never gated by
+  them. The bridge's named path operations now follow the configured roots,
+  including the installer's default output root (`~/Movies`).
+
+### Performance
+
+- **The bridge keeps one connection open** (#327). Each request is still
+  signed with its own nonce; only the TCP connection is reused, retired after
+  20 s idle on the client and 30 s on the bridge. macOS loopback: 0.40 ms a
+  call per connection, 0.17 ms kept alive, and no TIME_WAIT socket per call.
+  Windows was not measured here. Re-run `scripts/install_resolve_bridge.py`
+  to update the in-Resolve copy; an older bridge keeps working, one
+  connection per call.
+
+### Validation
+
+- Full offline suite: 4,289 tests, OK. 47 new tests across the error flag,
+  pinning, unread params, duplicate, item ids, FCPXML bundles, image
+  sequences, bridge roots and bridge keep-alive (over a real loopback
+  bridge).
+- Advanced Node suite on Node 20 with a fresh `npm ci`: 1,206 tests, 0
+  failures (4 new for `target: "timeline"`).
+- Live on Studio 19.1.3.7, over MCP stdio against a disposable project with
+  synthetic media: pinned reads and writes land on the named timeline and
+  the caller's timeline comes back; unknown and conflicting selectors
+  refuse; `ignored_params`; `timeline_item_id` and its `ITEM_NOT_FOUND`;
+  `duplicate` with and without `make_current` and pinned; `isError` on
+  failures and not on successes. 21 checks, 2 cycles. The first cycle found
+  a pinned `duplicate` reporting the pinned timeline as `current` after the
+  caller's had been restored; fixed before release.
+- The 21.1-specific behaviour (transitions in `GetItemListInTrack`, FCPXML
+  bundles, timeline DRX applies) cannot be reproduced on 19.1.3.7 and is
+  not live-validated.
+
 ## What's New in v4.15.5 — DRX applies say which graph changed
 
 `graph.apply_grade_from_drx` and `timeline_item_color.safe_apply_drx` no

package/README.md

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

package/docs/SKILL.md

@@ -215,6 +215,30 @@ tool — did it happen, was it verified, what changed:
   not read a missing `changes` as a no-op.
 - **`warnings`** — present only when there are any.
 - **`execution_id`** — correlates one call across logs and transcripts.
+- **`timeline`** — on timeline-scoped tools, `{name, id}` of the timeline the
+  call acted on. A pinned call (below) adds `pinned: true` and
+  `restored_current`, or `restore_failed: true` if the caller's timeline could
+  not be made current again.
+
+A failed call (an `{"error": {...}}` body) also comes back with MCP
+`isError: true`, so hooks and retry policies that follow the spec see the
+failure without parsing the body.
+
+**Unread params are reported.** When an action succeeds without reading some
+key you passed, the result carries `ignored_params: [...]` and the envelope
+lists them under `warnings`. Treat it as "that key did nothing": a misspelled
+key, an option this action does not take, or an alternative another key
+overrode (an `index` passed alongside `id`).
+
+**Pinning a call to a timeline.** `timeline`, `timeline_item*`,
+`timeline_markers`, `timeline_frame`, `timeline_ai`, `graph` and `render`
+act on the current timeline unless you pass `timeline_id` (preferred) or
+`timeline_name`. The server then makes that timeline current for the call
+and restores yours afterwards, so a user clicking another timeline mid-session
+cannot redirect your write. An unknown id, an ambiguous name or an id/name
+pair that disagree is refused before anything runs. Exceptions, where these
+keys keep their own meaning: `timeline.set_current` (selects by
+`timeline_id`) and the imports (`timeline_name` names the new timeline).
 
 The envelope is namespaced under `_operation` rather than merged into the top
 level because `status`, `operation`, `warnings`, `result` and `changes` are all
@@ -1949,8 +1973,11 @@ Key actions: `create_subtitles(settings?)` (human-readable settings resolved to
 
 Timeline items are identified by `track_type`, `track_index`, and `item_index`
 (all default to `"video"`, `1`, `0` respectively — the first clip on the first
-video track). Always retrieve item IDs via `timeline.get_items` before operating
-on specific items.
+video track), or by `timeline_item_id`, the item's `GetUniqueId()`. Prefer the
+id: on Resolve 21.1 `item_index` also counts transitions, so it shifts whenever
+a transition is added or removed. Read ids with `timeline.get_items` or
+`timeline.probe_timeline_structure`. An unknown id is refused with
+`ITEM_NOT_FOUND`; it never falls back to item 0.
 
 **`timeline_item`** — Properties, transform, speed, audio, keyframes.
 
@@ -2467,6 +2494,8 @@ reports, deletes the project, and removes generated media. See
 | `"No project open"` | No project is currently loaded | Call `project_manager(action="load", params={"name": "..."})` |
 | `"No current timeline"` | Project has no timeline set as current | Call `timeline(action="set_current", params={"index": 1})` |
 | `"No item at index N"` | `item_index` out of range for the track | Call `timeline(action="get_items", ...)` first to find valid indices |
+| `ITEM_NOT_FOUND` | No item with that `timeline_item_id` on the target timeline | Re-read ids; pass `timeline_id` if the item is on another timeline |
+| `TIMELINE_NOT_FOUND` / `TIMELINE_NAME_AMBIGUOUS` | The pin names no timeline, or several share the name | `timeline(action="list")` and pin by `timeline_id` |
 | `"Clip not found"` | Stale or wrong `clip_id` | Re-fetch IDs via `media_pool(action="get_selected")` or `folder(action="get_clips")` |
 | `"Gallery not available"` | Not on Color page | `resolve_control(action="open_page", params={"page": "color"})` |
 | `"GrabStill failed"` | Not on Color page or no clip under playhead | Switch to Color page, move playhead over a clip |

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -62,6 +62,12 @@ Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
 - Source range reporting grouped generated media paths with requested handles.
 - Guarded exports succeeded for FCPXML, DRT, EDL, AAF, and OTIO.
 - FCPXML directory-style exports are normalized with a `primary_file` path.
+  `import_timeline_checked` also accepts the bundle directory itself (the
+  export's `path`) and imports the `Info.fcpxml` inside it.
+- Clip fades set with `SetFades` do not survive an FCPXML round trip (reported
+  on Studio 21.1: imported clips read FadeIn/FadeOut 0 while Cross Dissolves
+  survive). This is likely Resolve's FCPXML writer; it has not been measured
+  on other formats.
 - DRT export/import/compare round-trip succeeded and cleaned up the imported
   timeline.
 - Synthetic-only unlink, missing-media detection, relink candidate planning,

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.15.5"
+VERSION = "4.17.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.15.5",
+  "version": "4.17.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/tools/drx.mjs

@@ -250,6 +250,23 @@ const generateSchema = z.object({
         'units (wheels raw, saturation ~1.0 neutral) for lossless/programmatic callers.'
     ),
   metadata: z.object({}).passthrough().optional().describe('Optional { label, width, height } metadata'),
+  target: z
+    .enum(['clip', 'timeline'])
+    .optional()
+    .describe(
+      "'clip' (default) writes the grade as a clip grade. 'timeline' writes it as the timeline grade " +
+        "(<pTrackVer>), for graph.apply_grade_from_drx with source='timeline'; a clip-target file applied to " +
+        'the timeline is refused (DRX_NO_TIMELINE_GRADE).'
+    ),
+  resolveVersion: z
+    .union([z.number().int().min(1), z.string()])
+    .optional()
+    .describe(
+      "Resolve version the file is for, as a major number (21) or a version string ('21.0.4'). From 21 on, " +
+        'circle and linear power windows are written in the Resolve 21 form (corrector type 0x10004, full parameter ' +
+        'set), which renders on Resolve 21; the older form loads there but renders an empty mask. Default: the ' +
+        'Resolve 19 form. Not live-verified here; the format comes from justhung69/resolve-mcp.'
+    ),
   outputPath: z.string().optional().describe('If set, write the .drx here'),
 });
 
@@ -684,7 +701,12 @@ export const drxTool = {
     if (action === 'generate') {
       const p = generateSchema.parse(args);
       const warnings = [];
-      const out = await drxGenerator().generateDRX(normalizeGradeParams(p.gradeParams, warnings), p.metadata || {});
+      const metadata = {
+        ...(p.metadata || {}),
+        ...(p.target ? { target: p.target } : {}),
+        ...(p.resolveVersion !== undefined ? { resolveVersion: p.resolveVersion } : {}),
+      };
+      const out = await drxGenerator().generateDRX(normalizeGradeParams(p.gradeParams, warnings), metadata);
       const content = typeof out === 'string' ? out : out?.content || out?.drxContent;
       const warn = warnings.length ? { warnings } : {};
       if (p.outputPath && content) {

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

@@ -222,6 +222,7 @@ const PARAM_IDS = {
  * Corrector Type IDs from shared library
  */
 const CORRECTOR_TYPES = drxParams.CORRECTOR_TYPES;
+const POWER_WINDOW_IDS = drxParams.POWER_WINDOWS;
 
 /**
  * Presence marker IDs from shared library
@@ -547,7 +548,7 @@ function buildHSLCurveParams(colorParams) {
  * @param {Object} options - Additional options (label, enabled, correctorTypes)
  */
 function createNode(nodeId, xPos, yPos, colorParams = null, options = {}) {
-  const { label = '', enabled = true, nodeIndex = nodeId } = options;
+  const { label = '', enabled = true, nodeIndex = nodeId, resolveVersion } = options;
 
   // Build node header with fields in order: F1, F2, F4, F5, F6, F7?, F8
   // Native Resolve analysis shows: id(F1), index(F2), pos(F4,F5), label?(F6), F8=44
@@ -749,9 +750,11 @@ function createNode(nodeId, xPos, yPos, colorParams = null, options = {}) {
     }
   }
   if (colorParams) {
-    const win = buildWindowParams(colorParams.window);
+    const win = buildWindowParams(colorParams.window, { resolveVersion });
     if (win.transform.length > 0) {
-      correctorBlocks.push(buildCorrectorBlock(CORRECTOR_TYPES.POWER_WINDOW, win.transform));
+      correctorBlocks.push(buildCorrectorBlock(win.transformType, win.transform));
+      // Resolve 21 also lists its window type in the node's corrector-type list.
+      if (win.transformType !== CORRECTOR_TYPES.POWER_WINDOW && presenceTypes.length > 0) presenceTypes.push(win.transformType);
     }
     if (win.softMask.length > 0) {
       // Linear-window softness mask (0x0870xxxx) lives under corrector type 3 in live data.
@@ -881,7 +884,7 @@ function createNode(nodeId, xPos, yPos, colorParams = null, options = {}) {
 
   // Add compact presence list as F2 (raw byte array of type IDs)
   if (presenceTypes.length > 0) {
-    const presenceBytes = Buffer.from(presenceTypes);
+    const presenceBytes = Buffer.concat(presenceTypes.map(encodeVarint)); // varints: the R21 window type is > 127
     f9Parts.push(protoBytes(2, presenceBytes));
     debugLog('[DRX] Added F2 presence list:', presenceTypes);
   }
@@ -1636,6 +1639,7 @@ function generateProtobuf(gradeParams, options = {}) {
     width = 1920,
     height = 1080,
     label = '',
+    resolveVersion,
   } = options;
 
   const timestamp = generateTimestamp();
@@ -1667,6 +1671,7 @@ function generateProtobuf(gradeParams, options = {}) {
       const node = createNode(nodeId, xPos, yPos, nodeConfig.params, {
         label: nodeConfig.label || `Node ${nodeId}`,
         enabled: nodeConfig.enabled !== false,
+        resolveVersion,
       });
       containerParts.push(node);
     });
@@ -1686,6 +1691,7 @@ function generateProtobuf(gradeParams, options = {}) {
     }
     const node = createNode(1, 500, 300, gradeParams, {
       label: label,
+      resolveVersion,
     });
     containerParts.push(node);
     // firstNodeId and lastNodeId both stay 1
@@ -1752,6 +1758,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
     baseNodeId: passedBaseNodeId,
     firstNodeId: passedFirstNodeId,
     lastNodeId: passedLastNodeId,
+    resolveVersion,
   } = metadata;
 
   const timestamp = generateTimestamp();
@@ -1806,6 +1813,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
         enabled: nodeConfig.enabled !== false,
         nodeIndex: nodeIndex, // Pass separate index for F2 field
         clipVersionId,
+        resolveVersion,
       }
     );
     containerParts.push(node);
@@ -1974,10 +1982,15 @@ async function generateDRX(gradeParams, metadata = {}) {
     sourceTimeline = 'Timeline 1',
     sourceTC = '00:00:00:00',
     recordTC = '01:00:00:00',
+    target = 'clip',
+    resolveVersion,
   } = metadata;
+  if (target !== 'clip' && target !== 'timeline') {
+    throw new Error(`target must be 'clip' or 'timeline', got ${JSON.stringify(target)}`);
+  }
 
   // Generate the body (pass label for single-node mode)
-  const body = await generateDRXBody(gradeParams, { width, height, label });
+  const body = await generateDRXBody(gradeParams, { width, height, label, resolveVersion });
   const bodyHex = body.toString('hex');
 
   // Generate UUIDs
@@ -1988,6 +2001,31 @@ async function generateDRX(gradeParams, metadata = {}) {
   // Current timestamp
   const now = new Date().toISOString().replace('Z', '');
 
+  // A timeline ApplyGradeFromDRX loads <pTrackVer> (VerType 1), not the clip
+  // grade in <pClipFullVer>. This path used to write no <pTrackVer> at all, so a
+  // timeline apply loaded nothing and replaced the timeline graph with an empty
+  // one (#318). target:'timeline' carries the grade in <pTrackVer> and marks the
+  // clip part uncorrected: the shape the #318 reporter applied successfully on
+  // Studio 21.1.1.10 (timeline graph 0 -> 1 node, no other graph changed).
+  const forTimeline = target === 'timeline';
+  const trackSection = forTimeline
+    ? `
+ <pTrackVer>
+  <ListMgt::LmVersion DbId="${uuidv4()}">
+   <FieldsBlob/>
+   <Name/>
+   <HasCorrection>true</HasCorrection>
+   <VerType>1</VerType>
+   <ImplVersion>1</ImplVersion>
+   <IncludedInRecording>true</IncludedInRecording>
+   <FlatPassEnabled>false</FlatPassEnabled>
+   <RGBAOutputEnabled>false</RGBAOutputEnabled>
+   <Body>${bodyHex}</Body>
+   <UseVersionClipProcParams>true</UseVersionClipProcParams>
+  </ListMgt::LmVersion>
+ </pTrackVer>`
+    : '';
+
   // Build DRX XML
   const xml = `<?xml version="1.0" encoding="UTF-8"?>
 <!--DbAppVer="19.1.3.0007" DbPrjVer="14"-->
@@ -2010,7 +2048,7 @@ async function generateDRX(gradeParams, metadata = {}) {
   <ListMgt::LmVersion DbId="${versionId}">
    <FieldsBlob/>
    <Name/>
-   <HasCorrection>true</HasCorrection>
+   <HasCorrection>${forTimeline ? 'false' : 'true'}</HasCorrection>
    <VerType>0</VerType>
    <ImplVersion>1</ImplVersion>
    <IncludedInRecording>true</IncludedInRecording>
@@ -2019,7 +2057,7 @@ async function generateDRX(gradeParams, metadata = {}) {
    <Body>${bodyHex}</Body>
    <UseVersionClipProcParams>true</UseVersionClipProcParams>
   </ListMgt::LmVersion>
- </pClipFullVer>
+ </pClipFullVer>${trackSection}
  <PrimaryCCMode>0</PrimaryCCMode>
 </Gallery::GyStill>
 `;
@@ -2774,8 +2812,8 @@ function buildLumaQualifierParams(lumaParams) {
  * @param {number} [windowParams.soft4=0] - Softness 4 (linear only)
  * @returns {Array} - Parameter entries for window corrector
  */
-function buildWindowParams(windowParams) {
-  const groups = { transform: [], softMask: [], gradient: [], shape: [] };
+function buildWindowParams(windowParams, { resolveVersion } = {}) {
+  const groups = { transform: [], transformType: CORRECTOR_TYPES.POWER_WINDOW, softMask: [], gradient: [], shape: [] };
   const paramEntries = groups.transform;
   const { POWER_WINDOWS } = drxParams;
 
@@ -2911,12 +2949,78 @@ function buildWindowParams(windowParams) {
     paramEntries.push(createParameterEntry(POWER_WINDOWS.SOFT_REF, w.soft1 * 16));
   }
 
+  if (isResolve21(resolveVersion) && !isVertexShape && paramEntries.length > 0) {
+    groups.transform = toResolve21WindowTransform(paramEntries);
+    groups.transformType = CORRECTOR_TYPE_WINDOW_R21;
+  }
+
   if (paramEntries.length > 0 || groups.softMask.length > 0) {
     debugLog('[DRX] Window params built:', paramEntries.length, '+', groups.softMask.length, isLinear ? '(linear: ct4 + ct3 mask)' : '(circle: ct4)');
   }
   return groups;
 }
 
+// Resolve 21 stores a circle/linear window transform as corrector type 0x10004 with the full
+// parameter set, not as corrector type 4 holding only the non-neutral parameters. The type 4
+// form loads into the Window palette on Resolve 21 but renders an empty mask, which also hides
+// the grade of the node. Order and neutral values follow what Resolve 21.0.4 exports for a
+// fresh circle window, as measured and pixel-verified by justhung69 in
+// https://github.com/justhung69/resolve-mcp (server/drx_r21.py, MIT, (c) 2026 Bùi Xuân Hưng).
+const CORRECTOR_TYPE_WINDOW_R21 = 0x10004;
+const R21_WINDOW_ORDER = [
+  [POWER_WINDOW_IDS.ROTATE, 0],
+  [POWER_WINDOW_IDS.ASPECT, 0],
+  [POWER_WINDOW_IDS.SOFT_REF, 0],
+  [POWER_WINDOW_IDS.SIZE, 1],
+  [POWER_WINDOW_IDS.PAN, 0],
+  [POWER_WINDOW_IDS.TILT, 0],
+];
+
+/** True when `resolveVersion` (a major number such as 21, or a string such as "21.0.4") is Resolve 21 or later. */
+function isResolve21(resolveVersion) {
+  return Number.parseInt(resolveVersion, 10) >= 21;
+}
+
+/** Read the parameter id out of an F3 parameter entry built by createParameterEntry. */
+function parameterEntryId(entry) {
+  let i = 1; // skip the F3 tag
+  while (entry[i++] & 0x80); // skip the entry length
+  i++; // skip the F1 tag
+  let id = 0;
+  let shift = 0;
+  let byte;
+  do {
+    byte = entry[i++];
+    id += (byte & 0x7f) * 2 ** shift;
+    shift += 7;
+  } while (byte & 0x80);
+  return id;
+}
+
+function toResolve21WindowTransform(entries) {
+  const byId = new Map(entries.map((entry) => [parameterEntryId(entry), entry]));
+  const take = (id) => {
+    const entry = byId.get(id);
+    byId.delete(id);
+    return entry;
+  };
+  const out = R21_WINDOW_ORDER.map(([id, neutral]) => take(id) || createParameterEntry(id, neutral));
+  take(POWER_WINDOW_IDS.WINDOW_TYPE);
+  const identity = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+  const matrix = protoBytes(3, Buffer.concat([
+    protoVarint(1, POWER_WINDOW_IDS.TRACKING_BLOB),
+    protoBytes(2, protoBytes(10, Buffer.concat(identity.map((v, i) => protoFloat32(i + 1, v))))),
+  ]));
+  out.push(
+    createVarintParameterEntry(POWER_WINDOW_IDS.WINDOW_TYPE, 2),
+    createParameterEntry(POWER_WINDOW_IDS.REF_WIDTH, 288),
+    createParameterEntry(POWER_WINDOW_IDS.UNK_0E, 0),
+    createParameterEntry(POWER_WINDOW_IDS.UNK_0F, 0),
+    take(POWER_WINDOW_IDS.TRACKING_BLOB) || matrix,
+  );
+  return out.concat([...byId.values()]); // e.g. opacity, kept after the measured set
+}
+
 /**
  * Check if any secondary correction tools are used (qualifier, window, HDR wheels)
  * Used to determine if we need to add those corrector blocks

package/src/granular/common.py

@@ -19,6 +19,7 @@ for path in (SRC_DIR, PROJECT_DIR):
 
 from mcp.server.fastmcp import FastMCP
 from mcp.types import ToolAnnotations
+from src.utils.mcp_error_flag import ErrorFlaggingFastMCP
 
 from src.utils.app_control import (
     get_app_state,
@@ -91,14 +92,14 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.15.5"
+VERSION = "4.17.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
 logger.info(f"Using Resolve API path: {RESOLVE_API_PATH}")
 logger.info(f"Using Resolve library path: {RESOLVE_LIB_PATH}")
 
-mcp = FastMCP("DaVinciResolveMCP")
+mcp = ErrorFlaggingFastMCP("DaVinciResolveMCP")
 if hasattr(mcp, "_mcp_server"):
     mcp._mcp_server.version = VERSION