davinci-resolve-mcp 4.8.29 → 4.9.0

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 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.9.0 — bounded Media Pool import
+
+### Added
+
+- **`media_pool(action="import_bounded_media")`** creates one bounded Media
+  Pool item from a source file through
+  `MediaStorage.AddItemListToMediaPool([{media, startFrame, endFrame}])`.
+  Params: `source_path` (absolute, must exist), `start_frame`, `end_frame`,
+  `destination_folder` (must already exist) and `name`. The import lands in
+  the destination folder, which is made current only for the one call; the
+  previous current folder is restored afterwards, including when the import
+  fails. The result carries the item summary and the range properties
+  Resolve reports for it (`bounded_import_properties`). `start_frame` and
+  `end_frame` are passed through unchanged; the wrapper does not adjust for
+  end-frame inclusivity. If the rename fails after Resolve has created the
+  item, the error says the item exists under Resolve's default name and
+  returns its id in `state`, so it can be renamed or deleted rather than
+  imported twice. `media_storage.import_to_pool(item_infos)` remains the
+  raw passthrough. Contributed by @dmourati (#275).
+- Contributor-validated on Studio 21.1.1 Build 10: this itemInfo form created
+  a native subclip, and `endFrame` was inclusive (0–300 gave 301 frames).
+  That is one tested configuration, not a guarantee for other builds or
+  media types; not measured on this project's 19.1.3.7 machine.
+
+### Safety
+
+- The action is registered as a write (`destructive_hook`) and rated LOW
+  (`execution_lifecycle`): it only adds an item, and neither the source nor
+  existing pool contents change. Safe mode, the dry-run refusal and the
+  operation log now see it. `docs/reference/readwrite-symmetry.md`
+  regenerated.
+
+### Tests
+
+- `tests/test_media_pool_ingest_probe.py`: input validation never reaches
+  Resolve, the folder is restored on success and failure, `MediaStorage`
+  comes from the Resolve object rather than the project manager, and a
+  failed rename reports the created item.
+- `tests/test_execution_lifecycle.py`: the action classifies as a
+  recognised, destructive, LOW-risk write.
+
+### Validation
+
+- Offline suite green. The live result above is the contributor's, on
+  Studio 21.1.1 Build 10.
+
+## What's New in v4.8.30 — conform_lint reports every reuse of one source
+
+### Fixed
+
+- **`editorial(action="conform_lint")` reported only the first reuse when
+  several pulls came from inside one long pull.** `check_duplicate_usage`
+  sorted each source's pulls by in-point and compared each one only with the
+  pull just before it. A long take followed by short callbacks lifted from
+  inside it therefore compared the second callback against the first, which
+  it does not overlap, and the reuse of the long take went unreported from
+  then on. An interview used at 0–5000 with callbacks at 100–200 and 300–400
+  reported one reuse instead of two. Each pull is now compared with the
+  earlier pull that reaches furthest, so every pull that overlaps any earlier
+  pull is flagged. Where out-points already increase that is the previous
+  pull, so ordinary material is reported exactly as before; adjacent pulls
+  are still two shots, not a duplicate. Contributed by @Dev-next-gen (#276).
+
+### Tests
+
+- `tests/test_conform_lint.py` gains `DuplicateUsageTests`, the check's first
+  tests: adjacent pulls stay unreported, and every callback inside one long
+  pull is reported. The second fails on v4.8.29 with the
+  `INTERVIEW`/`CALLBACK 2` pair missing.
+
+### Validation
+
+- `lint_timeline` is a pure function over a timeline snapshot; no Resolve
+  scripting call changed, so no live run was required.
+
 ## What's New in v4.8.29 — optional granular arguments accept an explicit null
 
 ### Fixed

package/README.md

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

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -2194,6 +2194,19 @@ media_pool(action="safe_import_sequence", params={
   "end_index": 1048,
   "target_folder": "Master/Plates"
 })
+media_pool(action="import_bounded_media", params={
+  "source_path": "/absolute/path/source.mov",
+  "start_frame": 100,
+  "end_frame": 240,
+  "destination_folder": "Master/Selects",
+  "name": "Selected range"
+})
+# start_frame/end_frame are raw Resolve startFrame/endFrame values. The MCP does
+# not add or subtract a frame; inspect bounded_import_properties after creation.
+# Contributor-validated on DaVinci Resolve Studio 21.1.1 Build 10 (#275): this
+# itemInfo form created a native subclip, and endFrame was inclusive (0–300
+# reported 301 frames). Treat that as an observed configuration-specific result,
+# not a guarantee for every Resolve version or media type.
 media_pool(action="media_pool_boundary_report", params={"selected": True, "depth": 2})
 # Positioned append (MediaPool.AppendToTimeline([{clipInfo}, ...])) — e.g. rebuild a subtitle row after delete_clips
 media_pool(action="append_to_timeline", params={"clip_infos": [

package/docs/reference/readwrite-symmetry.md

@@ -2,7 +2,7 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **125**
+- write-style action occurrences scanned: **126**
 - write-style action occurrences with a matching read: **76**
 - 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): 44 distinct names
+## Low-signal (create/add/insert/apply/import — usually expected): 45 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_modifier`, `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_multicam_clip`, `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_modifier`, `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_multicam_clip`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_bounded_media`, `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/install.py

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

package/src/granular/common.py

@@ -91,7 +91,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.8.29"
+VERSION = "4.9.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 377-tool granular server instead
 """
 
-VERSION = "4.8.29"
+VERSION = "4.9.0"
 
 import base64
 import os
@@ -13530,6 +13530,106 @@ def _safe_import_media(mp, p: Dict[str, Any]):
         _restore_current_folder(mp, previous)
 
 
+def _import_bounded_media(mp, ms, p: Dict[str, Any]):
+    """Create one bounded Media Pool item through MediaStorage.
+
+    Resolve's AddItemListToMediaPool itemInfo form is the public scripting API
+    for this operation. ``media_storage.import_to_pool(item_infos)`` passes its
+    ``{media, startFrame, endFrame}`` maps straight through; this wrapper adds
+    destination-folder scoping, naming, and created-item readback. ``start_frame``
+    and ``end_frame`` are passed unchanged as Resolve's ``startFrame`` and
+    ``endFrame`` values; this wrapper does not infer or compensate for end-frame
+    inclusivity. It imports into the *current* folder, so this helper deliberately
+    scopes and restores that UI state around the one API call.
+    """
+    source_path = p.get("source_path")
+    if not isinstance(source_path, str) or not source_path:
+        return _err("source_path must be a non-empty string", category="invalid_input")
+    if not os.path.isabs(source_path):
+        return _err("source_path must be an absolute path", category="invalid_input")
+    path_err = _path_error(source_path, must_be_file=True)
+    if path_err:
+        return _err(path_err, category="invalid_input")
+
+    frames = {}
+    for key in ("start_frame", "end_frame"):
+        value = p.get(key)
+        if isinstance(value, bool) or not isinstance(value, int):
+            return _err(f"{key} must be an integer", category="invalid_input")
+        frames[key] = value
+    if frames["start_frame"] < 0:
+        return _err("start_frame must be greater than or equal to 0", category="invalid_input")
+    if frames["end_frame"] < frames["start_frame"]:
+        return _err("end_frame must be greater than or equal to start_frame", category="invalid_input")
+
+    destination_folder = p.get("destination_folder")
+    if not isinstance(destination_folder, str) or not destination_folder:
+        return _err("destination_folder must be a non-empty Media Pool folder path", category="invalid_input")
+    if not _navigate_folder(mp, destination_folder):
+        return _err(f"Target folder not found: {destination_folder}",
+                    code="FOLDER_NOT_FOUND", category="invalid_input",
+                    remediation=_FOLDER_ID_REMEDIATION)
+
+    name = p.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return _err("name must be a non-empty string", category="invalid_input")
+
+    previous, folder_err = _set_current_folder_temporarily(mp, destination_folder)
+    if folder_err:
+        return folder_err
+    try:
+        item_info = {
+            "media": source_path,
+            "startFrame": frames["start_frame"],
+            "endFrame": frames["end_frame"],
+        }
+        try:
+            items = ms.AddItemListToMediaPool([item_info])
+        except Exception as exc:
+            return _err(f"AddItemListToMediaPool failed: {exc}")
+        if not isinstance(items, list) or len(items) != 1:
+            return _err(
+                "Bounded import must return exactly one MediaPoolItem",
+                code="BOUNDED_IMPORT_ITEM_COUNT_MISMATCH",
+                category="resolve_api_failed",
+                state={"returned_item_count": len(items) if isinstance(items, list) else None},
+            )
+        item = items[0]
+        try:
+            renamed = bool(item.SetName(name))
+        except Exception as exc:
+            return _err(
+                f"Failed to rename bounded MediaPoolItem: {exc}; the item exists with Resolve's default name",
+                state={"item": _media_pool_item_summary(item)},
+            )
+        if not renamed:
+            return _err(
+                "Failed to rename bounded MediaPoolItem; the item exists with Resolve's default name",
+                state={"item": _media_pool_item_summary(item)},
+            )
+
+        properties, _ = _safe_clip_call(item, "GetClipProperty", "")
+        range_property_keys = (
+            "File Path", "FPS", "Frames", "Duration", "Start TC", "End TC",
+            "Sub Clip", "SubClip", "Is Sub Clip", "IsSubClip", "Is Subclip",
+        )
+        bounded_import_properties = {
+            key: properties[key]
+            for key in range_property_keys
+            if isinstance(properties, dict) and properties.get(key) not in (None, "")
+        }
+        return _ok(
+            source_path=source_path,
+            start_frame=frames["start_frame"],
+            end_frame=frames["end_frame"],
+            destination_folder=destination_folder,
+            item=_media_pool_item_summary(item),
+            bounded_import_properties=bounded_import_properties,
+        )
+    finally:
+        _restore_current_folder(mp, previous)
+
+
 def _safe_import_sequence(mp, p: Dict[str, Any]):
     pattern = p.get("FilePath") or p.get("file_path") or p.get("pattern")
     if not pattern:
@@ -21438,6 +21538,14 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         — image sequences: params.clip_infos is a list of
           {FilePath, StartIndex, EndIndex} dicts (PascalCase keys per Resolve docs).
           Example: [{"FilePath": "frame_%03d.dpx", "StartIndex": 1, "EndIndex": 100}]
+      import_bounded_media(source_path, start_frame, end_frame, destination_folder, name)
+        -> {success, source_path, start_frame, end_frame, destination_folder, item,
+            bounded_import_properties}
+        — creates one bounded Media Pool item through
+          MediaStorage.AddItemListToMediaPool([{media, startFrame, endFrame}]).
+          start_frame/end_frame pass through unchanged as raw Resolve API values;
+          observed range semantics are reported from the created item properties.
+          destination_folder must already exist; the previous current folder is restored.
       delete_clips(clip_ids) -> {success}
         DESTRUCTIVE. Removes clips from the Media Pool (does not touch source files).
         An id matching no clip fails the whole call (CLIP_NOT_FOUND) rather than
@@ -21752,6 +21860,14 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
                 return _err("Provide paths (simple) or clip_infos (image sequences)")
             result = mp.ImportMedia(paths)
         return {"imported": len(result) if result else 0}
+    elif action == "import_bounded_media":
+        # _get_mp() returns the ProjectManager as its first value, not the
+        # Resolve application object. MediaStorage belongs to Resolve.
+        resolve = get_resolve()
+        ms = resolve.GetMediaStorage() if resolve else None
+        if not ms:
+            return _err("Failed to get MediaStorage")
+        return _import_bounded_media(mp, ms, p)
     elif action == "delete_clips":
         clips, clips_err = _clips_from_ids(root, p["clip_ids"], verb="deleted")
         if clips_err:
@@ -21887,7 +22003,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         return _copy_clip_annotations(root, p)
     elif action == "media_pool_boundary_report":
         return _media_pool_boundary_report(mp, p)
-    return _unknown(action, ["create_multicam_clip","get_root_folder","get_current_folder","set_current_folder","add_subfolder","delete_folders","move_folders","refresh","create_timeline","create_timeline_from_clips","import_timeline","delete_timelines","append_to_timeline","import_media","delete_clips","move_clips","relink","unlink","export_metadata","get_unique_id","create_stereo_clip","auto_sync_audio","get_selected","set_selected","get_clip_mattes","get_timeline_mattes","delete_clip_mattes","import_folder",*_MEDIA_POOL_KERNEL_ACTIONS])
+    return _unknown(action, ["create_multicam_clip","get_root_folder","get_current_folder","set_current_folder","add_subfolder","delete_folders","move_folders","refresh","create_timeline","create_timeline_from_clips","import_timeline","delete_timelines","append_to_timeline","import_media","import_bounded_media","delete_clips","move_clips","relink","unlink","export_metadata","get_unique_id","create_stereo_clip","auto_sync_audio","get_selected","set_selected","get_clip_mattes","get_timeline_mattes","delete_clip_mattes","import_folder",*_MEDIA_POOL_KERNEL_ACTIONS])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/conform_lint.py

@@ -337,7 +337,17 @@ def check_duplicate_usage(items: Sequence[Mapping[str, Any]]) -> List[Dict[str,
                 length = int(entry["timeline_end_frame"]) - int(entry["timeline_start_frame"])
             spans.append((start, start + max(0, length), _name(entry)))
         spans.sort()
-        for (a_start, a_end, a_name), (b_start, b_end, b_name) in zip(spans, spans[1:]):
+        # Each pull is compared against the furthest-reaching EARLIER pull, not
+        # against its immediate predecessor. Sorted by source in-point, one long
+        # pull is followed by every short callback lifted from inside it, so
+        # `spans[i - 1]` is the previous CALLBACK — which the next callback need
+        # not overlap — and the reuse of the long pull went unreported from the
+        # second callback onward. Where the out-points already increase the
+        # furthest pull *is* the predecessor, so ordinary material is unchanged.
+        furthest = spans[0]
+        for current in spans[1:]:
+            b_start, b_end, b_name = current
+            a_start, a_end, a_name = furthest
             if b_start < a_end:
                 dupes.append({
                     "source": str(ref),
@@ -345,6 +355,8 @@ def check_duplicate_usage(items: Sequence[Mapping[str, Any]]) -> List[Dict[str,
                     "second": b_name,
                     "overlap_frames": min(a_end, b_end) - b_start,
                 })
+            if b_end > a_end:
+                furthest = current
     if not dupes:
         return []
     return [_finding(

package/src/utils/destructive_hook.py

@@ -123,6 +123,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "setup_multicam_timeline",
         "create_multicam_clip",
         "create_stereo_clip",
+        "import_bounded_media",
         "auto_sync_audio",
         "set_clip_marks",
         "clear_clip_marks",

package/src/utils/execution_lifecycle.py

@@ -236,6 +236,8 @@ class RiskClassificationHook(LifecycleHook):
         ("media_pool", "create_timeline"),
         ("media_pool", "create_timeline_from_clips"),
         ("media_pool", "create_stereo_clip"),
+        # Adds one bounded item; the source and existing pool contents remain intact.
+        ("media_pool", "import_bounded_media"),
         # Per-item display properties: set them back and the item is as it was.
         ("timeline_item", "set_clip_enabled"),
         ("timeline_item", "set_name"),