davinci-resolve-mcp 2.217.0 → 2.218.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 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.218.0 — native Resolve 21.1 transition creation
+
+Contributed by @legionsound (#209), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **`timeline_item add_transition`**, with the granular twin
+  `add_timeline_item_transition`, calling 21.1's native `AddTransition`. The
+  `options` dictionary requires `type` (e.g. `"Cross Dissolve"`), `category`
+  (`simple` | `fusion` | `ofx` | `audio`), `position` (`start` | `end`) and
+  `alignment` (`left` | `center` | `right`); `duration` in frames is optional
+  and, when omitted or null, is forwarded as given rather than replaced with an
+  invented default. Unknown keys, blank types, unrecognised enum values and
+  non-positive or fractional durations are refused before any write. A native
+  `None` or `False` stays `success: false`; a build without the method returns
+  the 21.1 floor error, confirmed here on Studio 19.1.3.7.
+- The result reports the **transition Resolve actually created** — its id, name,
+  start, end and duration read back off the returned object — rather than
+  echoing the requested duration. Inserting a transition can change the track's
+  item indexes, and the tool documentation says so.
+
+### Changed
+
+- `add_transition` is registered in **both** write tables: the
+  `destructive_hook` action registry and the MEDIUM-risk set in
+  `execution_lifecycle`. Without both, safe mode, the dry-run refusal, the audit
+  log and the operation log would all treat a timeline mutation as a read. Tool
+  count 367 → 368 across the docs and the generated agent-rule files.
+- The existing offline `.drp` transition workflow is unchanged and still the
+  render-proven route on builds below 21.1; the native call is an addition, not
+  a replacement.
+
+### Documentation
+
+- `docs/reference/resolve211-native-transitions.md` records the fixture and its
+  limits, and the `api_truth` entry for `TimelineItem.AddTransition` is upgraded
+  from "signature only, never invoked" to a contributor measurement — while
+  keeping the standing 21.1 gap it does not close: there is still no accessor
+  for an existing transition's type, alignment or duration beyond its name and
+  frame range, and no clone verb.
+
+### Validation
+
+- Full suite green: 3,436 passed, 1 skipped. Static checks, drift guards and
+  the agent-rule generator all clean.
+- Write registration probed directly rather than inferred:
+  `classify_operation_risk("timeline_item", "add_transition")` returns MEDIUM /
+  destructive / recognised, and `destructive_hook.is_destructive` agrees.
+- No live Resolve run on this machine, which is Studio 19.1.3.7 — below the 21.1
+  floor, where every one of these calls correctly refuses. The rendered
+  evidence is @legionsound's, measured on Studio 21.1.0.14: a 24-frame centered
+  Cross Dissolve with source handles landed at frames 59–83 around a cut at 71
+  with adjacent clip spans unchanged, both server modes rendered byte-identical
+  142-frame ProRes movies with a progressive red-to-blue blend, and the
+  zero-handle case failed cleanly with no transition written. That covers the
+  tested Cross Dissolve fixture, not every effect the API accepts — other
+  alignments, automatic duration, audio and Fusion/OFX transitions, and repeated
+  insertion remain unverified.
+
 ## What's New in v2.217.0 — native Resolve 21.1 speed and fade setters, registered as the mutations they are
 
 Contributed by @legionsound (#208), 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.217.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.218.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(367%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(368%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` | 367 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 368 | 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 / **367** granular (live server) |
+| MCP Tools | **36** compound / **368** 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.217.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.218.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(367%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(368%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.217.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.218.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` | 367 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 368 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **36** 复合 / **367** 细粒度（实时服务器） |
+| MCP 工具 | **36** 复合 / **368** 细粒度（实时服务器） |
 | 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` | 367 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 368 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
@@ -2481,3 +2481,5 @@ setups:
 The full API reference is in `docs/reference/resolve_scripting_api.txt`.
 
 Native Resolve 21.1 speed and fade setters: see [speed/fades](reference/resolve211-speed-fades.md) for options, version guards and contributor validation limits.
+
+Native 21.1 transition creation: see [transition controls](reference/resolve211-native-transitions.md) for options, item-index changes and contributor-rendered evidence.

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 — 367 tools
+│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 368 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` | 367 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 368 | 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 367-tool server
+python src/server.py --full    # Launch full 368-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 **367 individual tools** for power users. The legacy coverage spans
+provides **368 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).
 
@@ -631,3 +631,5 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 ---
 
 Native speed and fade setters in both interfaces are documented in [Resolve 21.1 speed/fades](resolve211-speed-fades.md), including sampled video validation and unverified cases.
+
+Native 21.1 transition creation: see [transition controls](resolve211-native-transitions.md) for options, item-index changes and contributor-rendered evidence.

package/docs/reference/api-limitations.md

@@ -82,7 +82,7 @@ equivalent, blocking full automation.
 ### Transition create / copy / clone
 
 - **Object:** `Timeline / TimelineItem`
-- **Behavior:** CREATION IS FIXED IN 21.1, READBACK IS NOT. Reported by @billcarroll (PR #197) from an attribute probe on Studio 21.1.0.14 (2026-09-08; not reproduced here, no 21.1 install): TimelineItem.AddTransition resolves to a <BlackmagicFusion.PyFunctionCall object>, not None. Its stub signature is AddTransition(transitionOptions) -> TimelineItem | None, where transitionOptions carries type (e.g. 'Cross Dissolve'), category ('simple'|'fusion'|'ofx'|'audio'), position ('start'|'end'), alignment ('left'|'center'|'right') and an optional duration in frames. It was NOT invoked (a call mutates the user's timeline), so this entry claims existence and signature only. WHAT REMAINS MISSING ON 21.1: reading a transition back. There is still no accessor for an existing transition's type, alignment or duration beyond its name string and frame range, and no clone verb — alignment and duration are write-only arguments to AddTransition. The pre-21.1 statement, kept as the historical record: there was no method to ADD or CLONE an edit transition — no AddTransition/CreateTransition/AddVideoTransition on Timeline or TimelineItem (dir(), 21.0.4.5). CORRECTION, measured on Studio 21.0.4.5 (2026-08-12): this entry previously said transitions applied in the UI are 'invisible to and unmodifiable by scripts'. BOTH HALVES WERE WRONG and are withdrawn. A transition IS a first-class timeline item: a 12-frame Cross Dissolve applied through the Edit-page right-click menu enumerates in GetItemListInTrack('video', 1) as GetName()=='Cross Dissolve', GetStart()==86426, GetDuration()==12 — centered on a cut at 86432 — with a stable GetUniqueId() and a working GetTrackTypeAndIndex(). A transition authored offline into a .drp and imported reads IDENTICALLY, so the route that created it does not matter. It is also REMOVABLE: Timeline.DeleteClips([transition], False) returns True and deletes it, leaving both adjacent clips at their original starts and durations. THE DISCRIMINATOR between a transition item and a clip item is GetProperty(): a transition returns an EMPTY dict where a video clip returns 26 transform keys; it also has no MediaPoolItem and no Fusion comp. WHAT IS GENUINELY MISSING (pre-21.1: creation too; on 21.1+ read the paragraph above): cloning, and any type/alignment/parameter detail — the transition's kind is knowable ONLY from its name string, and there is no way to read its alignment (centered/start/end) or edit its duration. AUDIO NUANCE (measured 2026-09-01 on 19.1.3.7, E113): an audio cross-fade enumerates in GetItemListInTrack('audio', n) with an EMPTY GetName() (24 frames, centered on the cut, between the two clips) — so on audio lanes even the kind is not readable from the name. The discriminator that holds for BOTH: GetMediaPoolItem() is None AND GetProperty() is empty — BUT a Solid Color generator AND a subtitle item read the same way (GetProperty() None, no MediaPoolItem; measured E115), so that pair only separates clips from non-clips. What separates a transition from a generator is GEOMETRY: a transition straddles a cut (one neighbour ends inside its span, another starts inside it) while a generator owns its span. timeline.get_items reports `kind` on that basis.
+- **Behavior:** CREATION IS FIXED IN 21.1, READBACK IS NOT. Reported by @billcarroll (PR #197) from an attribute probe on Studio 21.1.0.14 (2026-09-08; not reproduced here, no 21.1 install): TimelineItem.AddTransition resolves to a <BlackmagicFusion.PyFunctionCall object>, not None. Its stub signature is AddTransition(transitionOptions) -> TimelineItem | None, where transitionOptions carries type (e.g. 'Cross Dissolve'), category ('simple'|'fusion'|'ofx'|'audio'), position ('start'|'end'), alignment ('left'|'center'|'right') and an optional duration in frames. That original probe did not invoke the method. UPDATE, contributor-validated by @legionsound on Studio 21.1.0.14, macOS, 2026-09-09 (not reproduced by the maintainer on 19.1.3.7): a synthetic red/blue pair with handles accepted a 24-frame centered Cross Dissolve. GetStart/End returned 59/83 around cut 71, GetDuration returned 24, and source clip spans were unchanged. Both community interfaces rendered identical 142-frame movies with a progressive red-to-blue blend. With zero handles the native call returned None. This validates that fixture, not other effects, audio transitions or alignments. See resolve211-native-transitions.md. WHAT REMAINS MISSING ON 21.1: reading a transition back. There is still no accessor for an existing transition's type, alignment or duration beyond its name string and frame range, and no clone verb — alignment and duration are write-only arguments to AddTransition. The pre-21.1 statement, kept as the historical record: there was no method to ADD or CLONE an edit transition — no AddTransition/CreateTransition/AddVideoTransition on Timeline or TimelineItem (dir(), 21.0.4.5). CORRECTION, measured on Studio 21.0.4.5 (2026-08-12): this entry previously said transitions applied in the UI are 'invisible to and unmodifiable by scripts'. BOTH HALVES WERE WRONG and are withdrawn. A transition IS a first-class timeline item: a 12-frame Cross Dissolve applied through the Edit-page right-click menu enumerates in GetItemListInTrack('video', 1) as GetName()=='Cross Dissolve', GetStart()==86426, GetDuration()==12 — centered on a cut at 86432 — with a stable GetUniqueId() and a working GetTrackTypeAndIndex(). A transition authored offline into a .drp and imported reads IDENTICALLY, so the route that created it does not matter. It is also REMOVABLE: Timeline.DeleteClips([transition], False) returns True and deletes it, leaving both adjacent clips at their original starts and durations. THE DISCRIMINATOR between a transition item and a clip item is GetProperty(): a transition returns an EMPTY dict where a video clip returns 26 transform keys; it also has no MediaPoolItem and no Fusion comp. WHAT IS GENUINELY MISSING (pre-21.1: creation too; on 21.1+ read the paragraph above): cloning, and any type/alignment/parameter detail — the transition's kind is knowable ONLY from its name string, and there is no way to read its alignment (centered/start/end) or edit its duration. AUDIO NUANCE (measured 2026-09-01 on 19.1.3.7, E113): an audio cross-fade enumerates in GetItemListInTrack('audio', n) with an EMPTY GetName() (24 frames, centered on the cut, between the two clips) — so on audio lanes even the kind is not readable from the name. The discriminator that holds for BOTH: GetMediaPoolItem() is None AND GetProperty() is empty — BUT a Solid Color generator AND a subtitle item read the same way (GetProperty() None, no MediaPoolItem; measured E115), so that pair only separates clips from non-clips. What separates a transition from a generator is GEOMETRY: a transition straddles a cut (one neighbour ends inside its span, another starts inside it) while a generator owns its span. timeline.get_items reports `kind` on that basis.
 - **Workaround / current handling:** Automated QC of existing transitions IS possible and is the main practical need — enumerate GetItemListInTrack, treat any item whose GetProperty() is empty and whose GetMediaPoolItem() is None as a transition, and read its name, start and duration. Removal is scriptable via Timeline.DeleteClips. To CREATE one, either apply it in the Resolve UI, or author it offline and import: the advanced server's drp place_transition writes a cross dissolve at an abutting cut ({track, atFrame, durationFrames}) and it round-trips into Resolve 21.0.4.5 reading back at the expected centered range. On 21.1+ prefer TimelineItem.AddTransition, which takes the type, category, edge, alignment and duration directly.
 - **Tags:** missing-method, timeline, transition
 

package/docs/reference/readwrite-symmetry.md

@@ -2,7 +2,7 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **119**
+- write-style action occurrences scanned: **120**
 - write-style action occurrences with a matching read: **73**
 - distinct high-signal `set_` actions without a direct/known readback: **4**
 
@@ -13,6 +13,6 @@
 - `set_keyframe_interpolation`
 - `set_node_enabled`
 
-## Low-signal (create/add/insert/apply/import — usually expected): 41 distinct names
+## Low-signal (create/add/insert/apply/import — usually expected): 42 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_transition`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/docs/reference/resolve211-native-transitions.md

@@ -0,0 +1,65 @@
+# Native Resolve 21.1 transitions
+
+`timeline_item("add_transition", {"options": {...}, ...})` and granular
+`add_timeline_item_transition(options, track_type="video", track_index=1,
+item_index=0)` call TimelineItem.AddTransition. This is an additional native
+route; the existing offline project-file transition workflow remains available.
+
+Required options are `type` (non-empty native transition name), `category`
+(`simple`, `fusion`, `ofx`, `audio`), `position` (`start`, `end`) and `alignment`
+(`left`, `center`, `right`). Optional `duration` is a positive integer in frames,
+or null/omitted to request Resolve's automatic duration. Unknown keys and malformed
+values are refused before writes. The wrapper does not guess which transition
+names are installed, calculate source handles, or silently substitute an effect.
+
+Example options:
+
+```json
+{"type":"Cross Dissolve","category":"simple","position":"end","alignment":"center","duration":24}
+```
+
+The result is `success: false` when the native API returns None/False. Otherwise
+`transition` contains its actual id, name, start, end and duration. Actual values
+come from the returned item, not the requested options. A created object is not
+proof of a correct render; verify output for each effect and source configuration.
+
+Native transitions appear in GetItemListInTrack on the measured build. Adding one
+therefore changes subsequent item indexes. Re-query the track before selecting
+another item. Track indexes remain 1-based and item indexes 0-based.
+
+The method has a 21.1 floor and is registered as a destructive write and MEDIUM
+risk in both classifier tables. Explicit compound dry-run requests are refused
+before the handler because this action has no native dry-run implementation.
+Granular tool annotations also identify a destructive, non-idempotent write.
+
+## Contributor evidence and limits
+
+Contributor-validated on macOS Studio **21.1.0.14**, using generated red/blue
+six-second clips in a disposable 24 fps project. A 24-frame centered Cross
+Dissolve with source handles returned start 59/end 83 around cut 71, without
+moving either source clip. ProRes movie rendering completed. The rendered
+boundary changed from red through a red/blue blend to blue. The same request
+with zero outgoing/incoming handles returned failure and no transition.
+
+The included scratch test exercises both community interfaces and creates render
+jobs for independent movie inspection. Unit tests cover actual returned spans,
+missing native methods, None/False failures, malformed options, optional duration,
+write classification, and dry-run refusal. Audio transitions, Fusion/OFX effects,
+other alignments, automatic duration and repeated insertion are not live-validated
+by this contribution. Support for their documented options is pass-through.
+
+`python tests/live_resolve211_transitions.py OUTPUT_DIR` requires a disposable
+project named `Codex Native Transition Validation 20260909`, set to 640x360/24 fps,
+with synthetic red.mov and blue.mov in its root bin. Generate each with FFmpeg:
+
+```sh
+ffmpeg -f lavfi -i 'color=c=red:s=640x360:r=24:d=6' \
+  -c:v prores_ks -profile:v 0 -pix_fmt yuv422p10le red.mov
+ffmpeg -f lavfi -i 'color=c=blue:s=640x360:r=24:d=6' \
+  -c:v prores_ks -profile:v 0 -pix_fmt yuv422p10le blue.mov
+```
+
+It creates disposable timelines, renders movies and saves the scratch project.
+Do not supply production media. Inspect frames 47, 65, 71, 77 and 95 in the
+resulting movies: red before the overlap, progressively more blue through the
+transition, then blue afterward. Also verify frame count and source-clip spans.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.217.0"
+VERSION = "2.218.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 · 367 full · 3 platforms"
+    subtitle = "36 compound · 368 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.217.0",
+  "version": "2.218.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.217.0"
+VERSION = "2.218.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,7 +1,7 @@
 """Native Resolve 21.1 discovery and editing controls."""
-from src.utils.resolve211_edits import validate_edit_options
+from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 from src.granular.common import (
-    mcp, READ_ONLY_TOOL, WRITE_TOOL, get_resolve, get_current_project,
+    mcp, READ_ONLY_TOOL, WRITE_TOOL, DESTRUCTIVE_TOOL, get_resolve, get_current_project,
     _get_timeline, _get_timeline_item, _requires_method, has_method,
 )
 
@@ -181,3 +181,20 @@ def set_timeline_item_fades(options: dict, track_type: str = "video", track_inde
     if missing:
         return missing
     return {"success": bool(item.SetFades(dict(options)))}
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def add_timeline_item_transition(options: dict, track_type: str = "video", track_index: int = 1, item_index: int = 0) -> dict:
+    """Add a native 21.1 transition using type/category/position/alignment and optional duration in frames. Returns actual span; clip indexes can change after insertion."""
+    error = validate_transition_options(options)
+    if error:
+        return {"error": error}
+    if track_type not in ("video", "audio") or track_index < 1 or item_index < 0:
+        return {"error": "Use video/audio, a 1-based track index and a non-negative item index"}
+    item, error = _get_timeline_item(track_type, track_index, item_index)
+    if error:
+        return error
+    missing = _requires_method(item, "AddTransition", "21.1")
+    if missing:
+        return missing
+    return transition_result(item.AddTransition(dict(options)))

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} (367 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (368 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 367-tool granular server instead
+    python src/server.py --full       # Start the 368-tool granular server instead
 """
 
-VERSION = "2.217.0"
+VERSION = "2.218.0"
 
 import base64
 import os
@@ -42,7 +42,7 @@ for p in [current_dir, project_dir]:
     if p not in sys.path:
         sys.path.insert(0, p)
 
-from src.utils.resolve211_edits import validate_edit_options
+from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
@@ -26274,6 +26274,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
     Identify by track_type, track_index, item_index (item_index is 0-BASED: 0 = first clip; track_index is 1-based).
 
     Actions:
+      add_transition(options, ...) -> {success, transition?} — native 21.1 transition; reports actual span.
       set_speed(options, ...) -> {success} — native 21.1 speed options; RippleTimeline defaults false.
       set_fades(options, ...) -> {success} — native 21.1 FadeIn/FadeOut integer frames.
       get_speed(...) -> {speed} — documented on Resolve 21.1+.
@@ -26330,6 +26331,16 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
     if err:
         return err
 
+    if action == "add_transition":
+        options = p.get("options")
+        error = validate_transition_options(options)
+        if error:
+            return _err(error)
+        missing = _requires_method(item, "AddTransition", "21.1")
+        if missing:
+            return missing
+        return transition_result(item.AddTransition(dict(options)))
+
     if action in ("set_speed", "set_fades"):
         options = p.get("options")
         error = validate_edit_options(action, options)
@@ -26541,7 +26552,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
             return _err(f"Invalid interpolation. Must be one of: {', '.join(valid)}")
         return {"success": bool(item.SetKeyframeInterpolation(p["property"], p["frame"], p["interpolation"]))}
 
-    return _unknown(action, ["set_speed","set_fades","get_speed","get_fades","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
+    return _unknown(action, ["add_transition","set_speed","set_fades","get_speed","get_fades","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -32663,9 +32674,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 367-tool granular server instead
+    # Support --full flag to run the 368-tool granular server instead
     if "--full" in sys.argv:
-        logger.info("Starting full 367-tool granular server...")
+        logger.info("Starting full 368-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

@@ -904,9 +904,18 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "None, where transitionOptions carries type (e.g. 'Cross "
                    "Dissolve'), category ('simple'|'fusion'|'ofx'|'audio'), position "
                    "('start'|'end'), alignment ('left'|'center'|'right') and an "
-                   "optional duration in frames. It was NOT invoked (a call mutates "
-                   "the user's timeline), so this entry claims existence and "
-                   "signature only. WHAT REMAINS MISSING ON 21.1: reading a "
+                   "optional duration in frames. That original probe did not invoke "
+                   "the method. UPDATE, contributor-validated by @legionsound on "
+                   "Studio 21.1.0.14, macOS, 2026-09-09 (not reproduced by the "
+                   "maintainer on 19.1.3.7): a synthetic red/blue pair with handles "
+                   "accepted a 24-frame centered Cross Dissolve. GetStart/End "
+                   "returned 59/83 around cut 71, GetDuration returned 24, and "
+                   "source clip spans were unchanged. Both community interfaces "
+                   "rendered identical 142-frame movies with a progressive "
+                   "red-to-blue blend. With zero handles the native call returned "
+                   "None. This validates that fixture, not other effects, audio "
+                   "transitions or alignments. See resolve211-native-transitions.md. "
+                   "WHAT REMAINS MISSING ON 21.1: reading a "
                    "transition back. There is still no accessor for an existing "
                    "transition's type, alignment or duration beyond its name string "
                    "and frame range, and no clone verb — alignment and duration are "

package/src/utils/destructive_hook.py

@@ -151,6 +151,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         # classifier did not recognise them, so safe mode, the dry-run refusal,
         # the audit log and the operation log all skipped a call that rewrites a
         # clip's speed — and, with RippleTimeline true, moves every clip after it.
+        "add_transition",
         "set_speed",
         "set_fades",
     }),

package/src/utils/execution_lifecycle.py

@@ -274,6 +274,7 @@ class RiskClassificationHook(LifecycleHook):
         # Native 21.1 setters (#208): `set_speed` changes duration and, with
         # RippleTimeline true, moves every clip after it; `set_fades` rewrites
         # how the clip's edges render. Existing content altered, not deleted.
+        ("timeline_item", "add_transition"),
         ("timeline_item", "set_speed"),
         ("timeline_item", "set_fades"),
         # Pool reorganisation: clips and bins move, nothing is destroyed, but

package/src/utils/resolve211_edits.py

@@ -24,3 +24,32 @@ def validate_edit_options(action, options):
             if not finite:
                 return key + " must be a finite number"
     return None
+
+
+def validate_transition_options(options):
+    if not isinstance(options, dict) or not options:
+        return "options must be a non-empty dictionary"
+    allowed = {"type", "category", "position", "alignment", "duration"}
+    if set(options) - allowed:
+        return "Unknown transition options: " + ", ".join(sorted(map(str, set(options) - allowed)))
+    if not isinstance(options.get("type"), str) or not options["type"].strip():
+        return "type must be a non-empty transition name"
+    for key, choices in (("category", ("simple", "fusion", "ofx", "audio")),
+                         ("position", ("start", "end")),
+                         ("alignment", ("left", "center", "right"))):
+        if options.get(key) not in choices:
+            return key + " must be one of: " + ", ".join(choices)
+    duration = options.get("duration")
+    if duration is not None and (type(duration) is not int or duration <= 0):
+        return "duration must be a positive integer number of frames or null"
+    return None
+
+
+def transition_result(transition):
+    if transition is None or transition is False:
+        return {"success": False}
+    return {"success": True, "transition": {
+        "id": transition.GetUniqueId(), "name": transition.GetName(),
+        "start": transition.GetStart(), "end": transition.GetEnd(),
+        "duration": transition.GetDuration(),
+    }}

package/src/utils/resolve_versions.py

@@ -225,6 +225,7 @@ _EVIDENCE_GATES: List[Dict[str, Any]] = [
 # disagree, which is what keeps the two from drifting apart again.
 
 CODE_FLOORS: Dict[str, str] = {
+    "TimelineItem.AddTransition": "21.1",
     "TimelineItem.SetSpeed": "21.1",
     "TimelineItem.SetFades": "21.1",
     # Documented in the shipped 21.1 scripting CHANGELOG; read-only contributor