davinci-resolve-mcp 2.169.0 → 2.170.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.170.0 — E113: `get_items` knows a transition from a clip
+
+### Added
+
+- **`timeline.get_items` reports `kind`** — `clip`, `transition`, or
+  `generator`. `GetItemListInTrack` lists transitions as items, and a video
+  Cross Dissolve enumerates by name; an AUDIO cross-fade enumerates with an
+  EMPTY name (measured on 19.1.3.7 on an assembled AAF turnover: 24 frames,
+  centered on the cut, between the two dialog clips), so the name can never
+  be the discriminator. A transition has no MediaPoolItem and an empty
+  property dict; a Solid Color generator has no media but transform keys;
+  everything else is a clip. An API surprise on the probe never demotes a
+  clip.
+
+### Measured (filed in api-limitations)
+
+- The transition entry now records the nameless audio form and the
+  media-pool/property discriminator, measured on both kinds.
+
 ## What's New in v2.169.0 — E112: round-trip QC is colour-aware
 
 `verify_roundtrip` merged every generator leg out of the compare as "black",

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.169.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.170.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(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

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

package/docs/reference/api-limitations.md

@@ -89,7 +89,7 @@ equivalent, blocking full automation.
 ### Transition create / copy / clone
 
 - **Object:** `Timeline / TimelineItem`
-- **Behavior:** There is 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: creation, 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.
+- **Behavior:** There is 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: creation, 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; a Solid Color generator has no MediaPoolItem either but DOES return transform keys. timeline.get_items reports `kind`.
 - **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.
 - **Tags:** missing-method, timeline, transition
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.169.0"
+VERSION = "2.170.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": "2.169.0",
+  "version": "2.170.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.169.0"
+VERSION = "2.170.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.169.0"
+VERSION = "2.170.0"
 
 import base64
 import os
@@ -2604,6 +2604,35 @@ def _find_timeline_item_by_id(tl, timeline_item_id) -> Optional[Any]:
     return None
 
 
+def _describe_track_item(it) -> Dict[str, Any]:
+    """One GetItemListInTrack entry → {name, id, start, end, duration, kind}.
+
+    Transitions ARE items in that list (api_truth): a video Cross Dissolve
+    enumerates by its name, but an AUDIO cross-fade enumerates with an EMPTY
+    name (measured 2026-09-01, Studio 19.1.3.7, E113) — so the name string can
+    never be the discriminator. A transition has no MediaPoolItem and an empty
+    GetProperty() dict; a clip has both. `kind` reports that.
+    """
+    kind = "clip"
+    try:
+        has_media = it.GetMediaPoolItem() is not None
+    except Exception:
+        has_media = True  # an API surprise must not demote a clip to a transition
+    if not has_media:
+        try:
+            props = it.GetProperty()
+        except Exception:
+            props = None
+        if not props:
+            kind = "transition"
+        else:
+            kind = "generator"  # no media, but transform keys: Solid Color / titles
+    return {
+        "name": it.GetName(), "id": it.GetUniqueId(), "start": it.GetStart(),
+        "end": it.GetEnd(), "duration": it.GetDuration(), "kind": kind,
+    }
+
+
 def _get_timeline_item_for_fusion(p: Dict[str, Any]):
     """Resolve optional timeline scope for fusion_comp."""
     if not _has_fusion_timeline_scope(p):
@@ -24415,7 +24444,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         if err:
             return _err(err)
         items = tl.GetItemListInTrack(track_type, track_index)
-        return {"items": [{"name": it.GetName(), "id": it.GetUniqueId(), "start": it.GetStart(), "end": it.GetEnd(), "duration": it.GetDuration()} for it in (items or [])]}
+        return {"items": [_describe_track_item(it) for it in (items or [])]}
     elif action == "delete_clips":
         # Find timeline items by unique IDs
         ids_set = set(p["clip_ids"])
@@ -26203,9 +26232,9 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
     },
     "timeline": {
         "get_items": {
-            "summary": "List items on one track as a summary (name/id/start/end/duration).",
+            "summary": "List items on one track as a summary (name/id/start/end/duration/kind). Transitions ARE items — a video Cross Dissolve by name, an AUDIO cross-fade with an EMPTY name — so `kind` (clip | transition | generator) is the discriminator, never the name.",
             "params": "track_type (video|audio|subtitle), index|track_index (1-based)",
-            "returns": "{items: [{name, id, start, end, duration}]}",
+            "returns": "{items: [{name, id, start, end, duration, kind}]}",
             "example": 'timeline(action="get_items", params={"track_type": "video", "index": 1})',
         },
         "get_items_in_track": {

package/src/utils/api_truth.py

@@ -889,7 +889,15 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "comp. WHAT IS GENUINELY MISSING: creation, 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.",
+                   "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; "
+                   "a Solid Color generator has no MediaPoolItem either but DOES "
+                   "return transform keys. timeline.get_items reports `kind`.",
         "recommended": "Automated QC of existing transitions IS possible and is "
                        "the main practical need — enumerate GetItemListInTrack, "
                        "treat any item whose GetProperty() is empty and whose "