davinci-resolve-mcp 2.221.0 → 2.223.0

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 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.223.0 — native Resolve 21.1 DCTL validation
+
+Contributed by @legionsound (#215), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **`dctl validate_native`**, with the granular twin `validate_dctl_native`,
+  calling Resolve 21.1's own `ValidateDCTL`. The existing `dctl validate`
+  remains the static offline checker — this is new surface beside it, not a
+  change to what that action claims. Tool count 375 → 376.
+- **Source layout is passed through unchanged and native diagnostics are
+  returned verbatim.** That is the rule recorded in the ledger back in
+  v2.216.1, when @legionsound narrowed `ValidateDCTL` to being sensitive to
+  source layout — the same function validates multi-line and fails on one line
+  — and it is now implemented rather than merely written down: a wrapper that
+  reflowed the user's source to make validation pass would be hiding the very
+  behaviour the ledger entry exists to warn about.
+- `None` means valid, strings mean invalid, and an **unexpected native result
+  type is an error rather than a false success** — the distinction that keeps a
+  changed API from silently reading as "your shader is fine".
+- Version-gated and explicitly classified **read-only**: verified here as LOW /
+  non-destructive. It does not install, encrypt, apply or render a DCTL, and
+  a successful validation is not a rendered shader test.
+
+### Validation
+
+- Full suite green: 3,470 passed, 1 skipped. Focused contracts cover CRLF and
+  Unicode preservation, so the source that reaches Resolve is byte-for-byte
+  what the caller supplied.
+- Live evidence is @legionsound's on Studio 21.1.0.14, checked against the
+  official Resolve MCP and both community interfaces: the multi-line identity
+  fixture validates, its one-line form reproduces the known missing-return
+  diagnostic, and invalid source returns the missing-entry-function
+  diagnostic — with both wrappers matching native results exactly. Not
+  reproduced here; this machine is Studio 19.1.3.7, below the 21.1 floor.
+- **Not claimed**: encryption, and any statement that validation implies a
+  shader renders correctly.
+
+### Changed
+
+- Adapted on merge, as with #212, #213 and #214: counts resolved to **376**,
+  confirmed by the agent-rule generator, generated files regenerated rather
+  than hand-merged. No behaviour changed in the adaptation.
+
+## What's New in v2.222.0 — native Resolve 21.1 timecode and waveform alignment
+
+Contributed by @legionsound (#212), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **`timeline auto_align_clips`**, with the granular twin
+  `auto_align_timeline_clips`, calling native 21.1 `AutoAlignClips` on explicit
+  timeline item IDs, with the documented `SyncUsing` and `UseTrack` options
+  accepting either constant names or integral native values. Every ID resolves
+  before anything moves, order is preserved, malformed input is refused, and a
+  native `false` stays `false`. Tool count 374 → 375.
+- **The wrapper does not silently expand the selection.** On the measured
+  build, waveform alignment refused a video-only selection, and an audio-only
+  selection aligned the audio while leaving its linked video at the old
+  position. Rather than quietly adding the linked items — which would move
+  clips the caller never named — the tool documentation tells callers to
+  include both sides of a linked pair, and an incomplete selection gets an
+  honest refusal it can act on.
+
+### Validation
+
+- Full suite green: 3,465 passed, 1 skipped. `timeline.auto_align_clips`
+  probed directly: MEDIUM / destructive / recognised, and present in the
+  destructive registry.
+- Live evidence is @legionsound's on Studio 21.1.0.14, and the two modes carry
+  **different strengths of evidence**, kept distinct rather than averaged:
+  timecode alignment is a position result (sources one second apart, starts
+  0/48 moving to 0/24), while waveform/MIX was verified against rendered
+  output — identical speech starts 0/24 moving to 0/0, with complete decoded
+  video **and PCM audio** matching independently positioned manual reference
+  timelines exactly, for both wrappers. Not reproduced here; this machine is
+  Studio 19.1.3.7, below the 21.1 floor.
+- **Not claimed**: other microphones, drift, variable frame rates, other track
+  selections and long recordings. Smart Switch remains separate and unstarted.
+
+### Changed
+
+- Adapted on merge, as with #213 and #214: counts resolved to **375**,
+  confirmed by the agent-rule generator, generated files regenerated rather
+  than hand-merged. No behaviour changed in the adaptation.
+
 ## What's New in v2.221.0 — native Resolve 21.1 audio level normalization
 
 Contributed by @legionsound (#214), live-validated on Studio 21.1.0.14.

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.221.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.223.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(374%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(376%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -133,7 +133,7 @@ The command starts a loopback-only server and opens the control panel in your br
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 36 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 374 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 376 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -365,7 +365,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **36** compound / **374** granular (live server) |
+| MCP Tools | **36** compound / **376** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.221.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.223.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(374%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(376%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![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.221.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.223.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 36 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 374 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 376 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **36** 复合 / **374** 细粒度（实时服务器） |
+| MCP 工具 | **36** 复合 / **376** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -345,7 +345,7 @@ to the user as verified.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 36 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 374 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 376 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades
@@ -2488,3 +2488,7 @@ Native multicam creation and flattening: [21.1 controls](reference/resolve211-mu
 Native timeline/clip output blanking: [21.1 controls](reference/resolve211-blanking.md), with explicit inheritance and pixel-bound evidence.
 
 Native audio normalization: [21.1 controls](reference/resolve211-normalization.md), with independently measured exported-audio evidence.
+
+Native timecode/waveform alignment: [21.1 controls](reference/resolve211-alignment.md), including linked-item selection semantics and rendered video/audio evidence.
+
+Resolve-native DCTL validation: [21.1 controls](reference/resolve211-dctl-validation.md), separate from static validation and shader rendering.

package/docs/contributing.md

@@ -64,7 +64,7 @@ davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
 │   ├── server.py                # Compound MCP server — 36 tools (default)
-│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 374 tools
+│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 376 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers
 ├── tests/                       # offline suite (test_*.py) + live harnesses (live_*.py):

package/docs/install.md

@@ -144,7 +144,7 @@ The MCP server comes in two modes:
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
 | **Compound** (default) | `src/server.py` | 36 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 374 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 376 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 374-tool server
+python src/server.py --full    # Launch full 376-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -25,7 +25,7 @@ Every non-deprecated method in the bundled legacy README is represented. This
 does not claim complete coverage of the newer Resolve 21.1 typed API. The
 default compound server exposes **36 tools** that group related operations by
 action parameter, keeping LLM context windows lean. The full granular server
-provides **374 individual tools** for power users. The legacy coverage spans
+provides **376 individual tools** for power users. The legacy coverage spans
 13 API object classes. MCP-level kernel actions are tracked separately in
 [Kernel Action Coverage](../kernels/README.md).
 
@@ -638,3 +638,7 @@ Native multicam creation and flattening: [21.1 controls](resolve211-multicam.md)
 Native timeline/clip output blanking: [21.1 controls](resolve211-blanking.md), with explicit inheritance and pixel-bound evidence.
 
 Native audio normalization: [21.1 controls](resolve211-normalization.md), with independently measured exported-audio evidence.
+
+Native timecode/waveform alignment: [21.1 controls](resolve211-alignment.md), including linked-item selection semantics and rendered video/audio evidence.
+
+Resolve-native DCTL validation: [21.1 controls](resolve211-dctl-validation.md), separate from static validation and shader rendering.

package/docs/reference/api-limitations.md

@@ -766,5 +766,5 @@ values, or automation-hostile modal prompts.
 - **Object:** `Resolve`
 - **Signature:** `(dctlSource) -> str | None  (21.1+)`
 - **Behavior:** Reported by @legionsound (issue #207) from Studio 21.1.0.14 on macOS; NOT reproduced here (no 21.1 install). The documented success result is None. A minimal identity transform written across several lines — `__DEVICE__ float3 transform(...)` with the body on its own lines — validates (None). The SAME function collapsed onto one line consistently returns 'DCTL Error: main DCTL function does not have return value.', which is false: the return statement is there. A genuinely invalid source returns 'cannot find main DCTL function.', so the validator does distinguish; it is the single-line layout it misreads. An earlier multi-line timeout did not reproduce after a Resolve restart with a 30-second limit. Nothing establishes a GPU compiler or render defect — this is the validator's parse, not the DCTL's execution. EncryptDCTL untested.
-- **Workaround / current handling:** Any wrapper around ValidateDCTL must pass the native diagnostic through verbatim and must not reflow or rewrite the user's source to dodge it; ship the multi-line identity fixture as the known-good control. A 'no return value' error on a one-line function is this quirk, not a missing return — re-run the validation with the function laid out across lines before believing it. This server's own `dctl validate` is a static, offline check (entry point, brace balance, float suffixes) and does not call ValidateDCTL at all.
+- **Workaround / current handling:** Any wrapper around ValidateDCTL must pass the native diagnostic through verbatim and must not reflow or rewrite the user's source to dodge it; ship the multi-line identity fixture as the known-good control. A 'no return value' error on a one-line function is this quirk, not a missing return — re-run the validation with the function laid out across lines before believing it. This server's own `dctl validate` is a static, offline check (entry point, brace balance, float suffixes) and does not call ValidateDCTL at all. The separate `dctl validate_native` and granular `validate_dctl_native` now expose the native validator without changing source or diagnostics. Both interfaces were contributor-validated against the three fixtures on Studio 21.1.0.14; see resolve211-dctl-validation.md.
 - **Tags:** dctl, validation, unreliable-return, version-gated, reported

package/docs/reference/resolve211-alignment.md

@@ -0,0 +1,54 @@
+# Native Resolve 21.1 timeline alignment
+
+Compound `timeline auto_align_clips` and granular `auto_align_timeline_clips`
+accept `item_ids` (timeline item unique IDs, not media-pool IDs) and optional
+`options`. All IDs must resolve in the current timeline's video/audio tracks;
+missing or duplicate IDs are refused before writes. The requested order and
+selection are preserved. This command does not implicitly add linked items.
+
+**Include both video and linked audio IDs when synchronizing camera clips.**
+Contributor observation on 21.1.0.14: waveform alignment of the video items alone
+returned false; audio-only selection moved the audio while linked video stayed
+put. Explicitly selecting all video/audio items aligned the complete fixture.
+Do not assume that selecting one half of a linked pair moves the other half.
+
+Options follow AutoAlignOptions: SyncUsing accepts
+AUTO_ALIGN_CLIPS_USING_TIMECODE or AUTO_ALIGN_CLIPS_USING_WAVEFORM; UseTrack
+accepts a native track number or AUTO_ALIGN_CLIPS_WAVEFORM_TRACK_MIX /
+AUTO_ALIGN_CLIPS_WAVEFORM_TRACK_AUTOMATIC. Constant names resolve against the
+live Resolve object; integral numeric native values are also accepted. Omitted
+options stay omitted, using native defaults. Unknown keys, invalid named
+constants and malformed types are rejected. Native false stays success:false.
+
+The callable method and 21.1 floor are checked. The compound action is registered
+as a destructive MEDIUM-risk write in both classifier tables. Explicit dry-run
+requests are refused before mutation. Granular annotations mark a destructive,
+non-idempotent write.
+
+## Contributor validation and limits
+
+Contributor-validated on macOS Studio 21.1.0.14, using synthetic speech and color
+cards in a disposable 640x360/24 fps project. The two sources contain the same
+speech but source timecodes differ by one second.
+
+- Timecode fixture: deliberately placed at frames0/48, both wrappers moved the
+  selected video/audio to frames0/24, matching source timecodes.
+- Waveform fixture with MIX: deliberately placed at frames0/24, both wrappers
+  moved all selected video/audio to frame0, matching identical speech content.
+- For each mode, both wrappers' complete decoded ProRes video and PCM audio
+  matched an independently positioned manual reference exactly. This is full
+  rendered video/audio comparison, not just position readback.
+
+Other audio track selections, dissimilar microphones, drift, variable frame rates,
+long-form recordings and partly overlapping selections are not established by
+this fixture. A failed chirp/video-only probe is not proof of a native bug.
+Smart Switch is a separate operation and remains follow-up work.
+
+`tests/live_resolve211_alignment.py OUTPUT_DIR` requires the disposable project
+Codex Alignment Validation 20260909, with speech-red.mov and speech-blue.mov in
+its root bin. Both are 24 fps color-card movies using the same synthetic spoken
+recording; red timecode00:00:00:00 and blue timecode00:00:01:00. It creates manual,
+compound and granular timelines for each mode, renders six movies and saves the
+scratch project. Never substitute production media. Compare each mode's full
+decoded video and audio against its manual reference. The helper tests also pin
+ID ordering, malformed/missing input refusal, native failure and write gates.

package/docs/reference/resolve211-dctl-validation.md

@@ -0,0 +1,31 @@
+# Native DCTL validation in Resolve 21.1
+
+Compound `dctl validate_native` and granular `validate_dctl_native` accept a
+`source` string and call Resolve.ValidateDCTL. They return `valid`, `diagnostic`
+and `checker: resolve_native`. The source is passed unchanged, including its
+line layout. Native None means valid; a native string means invalid and is
+returned verbatim, including whitespace. An unexpected native result type is a
+protocol error, not a claim that the shader validated.
+
+The existing `dctl validate` remains the static offline checker. Native validation
+requires running Resolve 21.1 and a callable ValidateDCTL method. It does not
+install a DCTL, encrypt it, apply a grade or render the shader. A successful
+validation is not rendered-output evidence. The granular tool is read-only and
+the compound action is explicitly classified as non-destructive.
+
+## Contributor validation
+
+Contributor-validated on macOS Studio 21.1.0.14 against the official MCP and both
+actual community interfaces. The multiline identity fixture returns None. The
+same function on one line returns `DCTL Error: main DCTL function does not have
+return value.` Invalid source returns `cannot find main DCTL function.` Both
+wrappers preserve these diagnostics exactly. The source-layout limitation is
+already in api_truth; this wrapper exposes it honestly rather than reformatting
+user code to hide it.
+
+`python tests/live_resolve211_dctl.py` compares raw/native and both wrapper
+results for all three fixtures. It neither changes projects nor installs files.
+Unit tests also cover verbatim CRLF/Unicode source and diagnostic handling,
+invalid inputs, missing methods, unexpected native result types, read-only risk
+classification and preservation of the static checker route. Encryption and
+actual GPU execution remain separate work.

package/docs/reference/resolve211-multicam.md

@@ -48,11 +48,11 @@ Use the synthetic FFmpeg fixture commands in resolve211-native-transitions.md;
 never run the fixture against production media. Compare complete decoded frames
 from compound-before/compound-flattened/granular-before/granular-flattened.mov.
 
-Smart Switch and AutoAlignClips remain separate work. Native timecode alignment
-has positive position-readback evidence, but rendered/waveform acceptance remains
-open. Silent color-card Smart Switch returned false and is not a meaningful
-positive speaking-camera test. This contribution does not claim the entire
-multicam family completed.
+Smart Switch remains separate work. Native timecode and waveform alignment now
+have dedicated wrappers and rendered video/audio comparisons documented in
+[alignment controls](resolve211-alignment.md). Silent color-card Smart Switch
+returned false and is not a meaningful positive speaking-camera test. This
+does not claim the entire multicam family completed.
 
 Do not infer angle order from clip_ids order. The wrapper forwards the requested
 source order, but this measurement establishes the selected angle and its

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.221.0"
+VERSION = "2.223.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
@@ -1543,7 +1543,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "36 compound · 374 full · 3 platforms"
+    subtitle = "36 compound · 376 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.221.0",
+  "version": "2.223.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.221.0"
+VERSION = "2.223.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/granular/resolve_211.py

@@ -1,4 +1,6 @@
 """Native Resolve 21.1 discovery and editing controls."""
+from src.utils.resolve211_dctl import native_dctl_result
+from src.utils.resolve211_alignment import auto_align
 from src.utils.resolve211_normalization import normalize_audio
 from src.utils.resolve211_blanking import validate_blanking
 from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
@@ -291,3 +293,29 @@ def normalize_timeline_audio_level(item_ids: list[str], options: dict | None = N
     if missing:
         return missing
     return normalize_audio(get_resolve(), timeline, item_ids, {} if options is None else options)
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def auto_align_timeline_clips(item_ids: list[str], options: dict | None = None) -> dict:
+    """Native 21.1 alignment of current video/audio items by unique ID. Include linked audio AND video IDs to move both; selection is not expanded. Options SyncUsing and UseTrack accept documented constant names or integral native values."""
+    _, timeline, error = _get_timeline()
+    if error:
+        return error
+    missing = _requires_method(timeline, "AutoAlignClips", "21.1")
+    if missing:
+        return missing
+    return auto_align(get_resolve(), timeline, item_ids, {} if options is None else options)
+
+
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def validate_dctl_native(source: str) -> dict:
+    """Validate shader source with Resolve 21.1. Source layout and native diagnostics are preserved; success means validation, not a rendered shader test."""
+    if not isinstance(source, str):
+        return {"error": "source must be a string"}
+    r = get_resolve()
+    if r is None:
+        return {"error": "Not connected to DaVinci Resolve"}
+    missing = _requires_method(r, "ValidateDCTL", "21.1")
+    if missing:
+        return missing
+    return native_dctl_result(r, source)

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (374 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (376 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -8,10 +8,10 @@ Each tool groups related operations via an 'action' parameter.
 
 Usage:
     python src/server.py              # Start the MCP server
-    python src/server.py --full       # Start the 374-tool granular server instead
+    python src/server.py --full       # Start the 376-tool granular server instead
 """
 
-VERSION = "2.221.0"
+VERSION = "2.223.0"
 
 import base64
 import os
@@ -44,6 +44,8 @@ for p in [current_dir, project_dir]:
 
 from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
 from src.utils.resolve211_blanking import validate_blanking
+from src.utils.resolve211_alignment import auto_align
+from src.utils.resolve211_dctl import native_dctl_result
 from src.utils.resolve211_normalization import normalize_audio
 from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 
@@ -25054,7 +25056,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 
 
 _TIMELINE_ACTIONS = [
-    "set_output_blanking", "normalize_audio_level", "get_normalize_audio_modes", "get_output_blanking",
+    "set_output_blanking", "normalize_audio_level", "auto_align_clips", "get_normalize_audio_modes", "get_output_blanking",
     # Offline authoring — served without a Resolve connection, above the _check() gate.
     "author_offline", "offline_fallback_capabilities",
     "list", "get_current", "set_current", "get_name", "set_name", "get_start_frame",
@@ -25105,6 +25107,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     Actions:
       set_output_blanking(options) -> {success} — native 21.1 pixel coordinates.
       normalize_audio_level(item_ids, options?) -> {success} — native 21.1 normalization; audio timeline item IDs.
+      auto_align_clips(item_ids, options?) -> {success} — native 21.1 timecode/waveform alignment; include both video/audio IDs to move linked pairs.
       get_normalize_audio_modes() -> {modes} — documented on Resolve 21.1+.
       get_output_blanking() -> {blanking} — documented on Resolve 21.1+. Pixel coordinates; empty on a clip inheriting timeline blanking.
       list() -> {timelines}
@@ -25423,6 +25426,12 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     if not tl:
         return _err("No current timeline")
 
+    if action == "auto_align_clips":
+        missing = _requires_method(tl, "AutoAlignClips", "21.1")
+        if missing:
+            return missing
+        return auto_align(get_resolve(), tl, p.get("item_ids"), {} if p.get("options") is None else p["options"])
+
     if action == "normalize_audio_level":
         missing = _requires_method(tl, "NormalizeAudioLevel", "21.1")
         if missing:
@@ -31134,6 +31143,7 @@ def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
       remove(name, category?, subdir?, ext?) -> {success}
       read(name, category?, subdir?, ext?) -> {source, encrypted}
       validate(source) -> {valid, errors, warnings, checker}
+      validate_native(source) -> {valid, diagnostic, checker} — Resolve 21.1 validation; source and diagnostic unchanged.
       template(kind, name, options?) -> {source, kind, name, suggested_category}
         — kind: 'transform' | 'transform_alpha' | 'transition' | 'matrix' |
                 'kernel' | 'lut_apply' | 'aces_idt' | 'aces_odt'
@@ -31287,6 +31297,18 @@ def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
         return {"source": src, "path": target,
                 "encrypted": ext == ".dctle", "category": cat}
 
+    if action == "validate_native":
+        source = p.get("source")
+        if not isinstance(source, str):
+            return _err("validate_native requires a source string")
+        r = get_resolve()
+        if r is None:
+            return _not_connected_error()
+        missing = _requires_method(r, "ValidateDCTL", "21.1")
+        if missing:
+            return missing
+        return native_dctl_result(r, source)
+
     if action == "validate":
         source = p.get("source")
         if not isinstance(source, str):
@@ -31313,7 +31335,7 @@ def dctl(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
         }
 
     return _unknown(action, ["path", "list", "install", "remove", "read",
-                             "validate", "template", "list_templates"])
+                             "validate_native", "validate", "template", "list_templates"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -32729,9 +32751,9 @@ if __name__ == "__main__":
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
     _install_threaded_tool_dispatch(mcp)
 
-    # Support --full flag to run the 374-tool granular server instead
+    # Support --full flag to run the 376-tool granular server instead
     if "--full" in sys.argv:
-        logger.info("Starting full 374-tool granular server...")
+        logger.info("Starting full 376-tool granular server...")
         sys.argv = [arg for arg in sys.argv if arg != "--full"]
         from src.granular import mcp as granular_mcp
 

package/src/utils/api_truth.py

@@ -3263,7 +3263,12 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "across lines before believing it. This server's own "
                        "`dctl validate` is a static, offline check (entry point, "
                        "brace balance, float suffixes) and does not call "
-                       "ValidateDCTL at all.",
+                       "ValidateDCTL at all. The separate `dctl validate_native` and "
+                       "granular `validate_dctl_native` now expose the native "
+                       "validator without changing source or diagnostics. Both "
+                       "interfaces were contributor-validated against the three "
+                       "fixtures on Studio 21.1.0.14; see "
+                       "resolve211-dctl-validation.md.",
         "tags": ["dctl", "validation", "unreliable-return", "version-gated", "reported"],
         "submit": "bug",
     },

package/src/utils/destructive_hook.py

@@ -89,6 +89,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
     "timeline": frozenset({
         "set_output_blanking",
         "normalize_audio_level",
+        "auto_align_clips",
         "delete_clips",
         "move_clips",
         "duplicate_clips",

package/src/utils/execution_lifecycle.py

@@ -275,6 +275,7 @@ class RiskClassificationHook(LifecycleHook):
         # RippleTimeline true, moves every clip after it; `set_fades` rewrites
         # how the clip's edges render. Existing content altered, not deleted.
         ("media_pool", "create_multicam_clip"),
+        ("timeline", "auto_align_clips"),
         ("timeline_item", "flatten_multicam"),
         ("timeline", "set_output_blanking"),
         ("timeline_item", "set_output_blanking"),
@@ -403,7 +404,7 @@ class RiskClassificationHook(LifecycleHook):
                 else BlastRadius.ITEM
             )
             reasons.append(f"Recoverable edit to existing state: {action}")
-        elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"}:
+        elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"} or pair == ("dctl", "validate_native"):
             level = RiskLevel.LOW
             destructive = False
             radius = BlastRadius.ITEM

package/src/utils/resolve211_alignment.py

@@ -0,0 +1,32 @@
+"""Native alignment with strict ID resolution before any timeline mutation."""
+from src.utils.resolve211_multicam import resolve_constant
+
+OPTIONS = {
+    'SyncUsing': ('AUTO_ALIGN_CLIPS_USING_TIMECODE','AUTO_ALIGN_CLIPS_USING_WAVEFORM'),
+    'UseTrack': ('AUTO_ALIGN_CLIPS_WAVEFORM_TRACK_MIX','AUTO_ALIGN_CLIPS_WAVEFORM_TRACK_AUTOMATIC'),
+}
+
+
+def auto_align(r, timeline, item_ids, options):
+    if not isinstance(item_ids,list) or not item_ids or any(not isinstance(i,str) or not i for i in item_ids):
+        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'}
+    normalized={}
+    for key,value in options.items():
+        normalized[key],error=resolve_constant(r,value,OPTIONS[key])
+        if error:
+            return {'error':key+': '+error}
+    wanted=set(item_ids)
+    found={}
+    for track_type in ('video','audio'):
+        for index in range(1,timeline.GetTrackCount(track_type)+1):
+            for item in timeline.GetItemListInTrack(track_type,index) or []:
+                uid=item.GetUniqueId()
+                if uid in wanted:
+                    found[uid]=item
+    if any(uid not in found for uid in item_ids):
+        return {'error':'One or more item_ids were not found in current video/audio tracks; no alignment performed'}
+    return {'success':bool(timeline.AutoAlignClips([found[uid] for uid in item_ids],normalized))}

package/src/utils/resolve211_dctl.py

@@ -0,0 +1,8 @@
+"""Native DCTL diagnostics are evidence; never reformat the user's shader source."""
+
+
+def native_dctl_result(resolve, source):
+    diagnostic=resolve.ValidateDCTL(source)
+    if diagnostic is not None and not isinstance(diagnostic,str):
+        return {'error':'ValidateDCTL returned an unexpected diagnostic type'}
+    return {'valid':diagnostic is None,'diagnostic':diagnostic,'checker':'resolve_native'}

package/src/utils/resolve_versions.py

@@ -225,6 +225,8 @@ _EVIDENCE_GATES: List[Dict[str, Any]] = [
 # disagree, which is what keeps the two from drifting apart again.
 
 CODE_FLOORS: Dict[str, str] = {
+    "Timeline.AutoAlignClips": "21.1",
+    "Resolve.ValidateDCTL": "21.1",
     "MediaPool.CreateMulticamClip": "21.1",
     "TimelineItem.FlattenMulticam": "21.1",
     "Timeline.SetOutputBlanking": "21.1",