davinci-resolve-mcp 2.76.0 → 2.78.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 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.78.0
+
+The AAF probe reports where in the *source* an event actually lives, not where it
+lives in the consolidated fragment the AAF happens to reference.
+
+### Fixed
+
+- **`srcIn`/`srcOut` were handle offsets, not positions in the take.** A
+  `SourceClip`'s `start` is an offset into whatever mob it references *directly*,
+  and for consolidated media that mob is a per-cut fragment carrying handles — not
+  the take. On a real turnover 774 of 878 events reported `srcIn <= 45`, and one
+  take used thirteen times reported `srcIn 40` all thirteen times; two cuts of one
+  take cannot both begin at frame 42 of it. A consumer placing those numbers
+  against camera originals lands on the right cut of the right take showing the
+  **wrong moment**, and the number fits inside the file, so no range check catches
+  it. The consumer measured 2 of 526 cuts matching its picture reference before
+  this.
+
+### Added
+
+- **Physical source position and timecode per event** — `srcPos`, `srcTcFrame`,
+  `srcTc`, `srcTcFps`, `srcTcDrop`. The chase sums `start` down the mob chain and
+  reads the nearest mob's timecode slot, so a consumer that links camera originals
+  can place `sourceTc − fileStartTc` instead of a fragment-relative number. Emitted
+  only when actually read: a chain that adds nothing emits nothing rather than
+  restating `srcIn`, and per-sequence `sourcePositionCoverage` counters let a
+  consumer distinguish "this AAF carries none" from "this probe is too old to emit
+  it." `srcIn`/`srcOut` are unchanged — this is additive.
+
+Verified on the fixture: 869/878 events carry `srcPos`, 876 carry source timecode,
+and the take used thirteen times separates into thirteen distinct positions.
+Frame-exact against an independent witness — at the frame the turnover's own
+picture reference burned 21:19:28:21, the probe says 21:19:28:21.
+
+## What's New in v2.77.0
+
+Folder addressing fails loud instead of quietly answering about whichever bin the
+UI happens to have open. Contributed by [@billcarroll](https://github.com/billcarroll)
+in [#116](https://github.com/samuelgursky/davinci-resolve-mcp/pull/116).
+
+### Fixed
+
+- **An unresolvable folder address no longer falls back to the current bin.**
+  `media_pool add_subfolder` and `media_pool get_timeline_mattes` resolved their
+  folder argument with `_navigate_folder(...) or fallback`, so a typo'd path was
+  dropped and the action proceeded against the current bin (or root) with a
+  `success` envelope. For a read that is a wrong answer indistinguishable from a
+  right one; for `add_subfolder` it creates the folder wherever the UI happens to
+  be pointed. All three sites now share one resolver that returns
+  `FOLDER_NOT_FOUND` / `invalid_input` when a supplied address does not resolve,
+  with remediation naming `get_subfolders`.
+- **A bad folder path came back marked retryable.** The `folder` tool did already
+  error on an unresolvable `path`, but with a bare message, so the envelope
+  defaulted to `resolve_api_failed` and told the caller to retry an address that
+  would never resolve. It is now `invalid_input`, non-retryable — the caller's to
+  fix.
+
+### Added
+
+- **`folder_id` is accepted as a folder address**, alongside `path`, on the
+  `folder` tool, `media_pool add_subfolder`, and `media_pool get_timeline_mattes`.
+  `get_subfolders` hands out ids, and having no way to spend them is what invited
+  agents to guess a `folder_id` argument that no action read — which was silently
+  dropped, returned the current bin's contents with `success`, and made the tools
+  look like they ignored their arguments. Omitting every address still means what
+  it did before: the current folder for the `folder` tool, the root folder for the
+  two `media_pool` actions.
+
+### Known limitation
+
+Only `path`/`folder_path`/`folderPath` and `folder_id`/`folderId` are recognised
+as addresses. Any other invented key (`id`, `bin`, `folderName`) is still dropped,
+and the action still answers about its default folder with `success`. This release
+narrows the silent-wrong-folder class to a known key set rather than closing it;
+closing it needs unknown-parameter rejection at the dispatch layer.
+
 ## What's New in v2.76.0
 
 Three AAF conform-fidelity fixes found by placing a full 83-minute Avid turnover and

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.76.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.78.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-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -617,9 +617,25 @@ switching, and flattening remain Resolve UI workflows; see
 Note: `folder path` arguments use slash notation like `"Master/SubFolder"`.
 `"Master"` or `"/"` refers to the root folder.
 
+Address a folder either by `path` or by `folder_id` — the id `get_subfolders`
+returns for each entry (v2.77.0+; the same pair works for `media_pool
+add_subfolder` via `parent_path`/`folder_id` and for `media_pool
+get_timeline_mattes` via `folder_path`/`folder_id`). Omit both to get the
+action's default: the current folder for the `folder` tool, the root folder for
+those two `media_pool` actions. An address that is supplied but does not resolve
+is a `FOLDER_NOT_FOUND` / `invalid_input` error — it never quietly falls back to
+the current bin.
+
+That fallback is what these tools used to do, so treat a pre-v2.77.0 server as
+unable to tell you when it answered about the wrong folder. Note also that only
+`path`/`folder_path`/`folderPath` and `folder_id`/`folderId` are recognised as
+addresses: any other key you invent (`id`, `bin`, `folderName`) is still
+silently dropped, and the action still answers about its default folder with
+`success`. Use the documented names.
+
 **`folder`** — Operations on a specific Media Pool folder.
 
-Key actions: `get_clips(path?)`, `get_subfolders(path?)`, `export(path?, export_path)`,
+Key actions: `get_clips(path?|folder_id?)`, `get_subfolders(path?|folder_id?)`, `export(path?, export_path)`,
 `transcribe_audio(path?, use_speaker_detection?)`, `clear_transcription(path?)`,
 `perform_audio_classification(path?)`, `analyze_for_intellisearch(path?, identify_faces?, is_better_mode?)`,
 `analyze_for_slate(path?, marker_color?)`, `remove_motion_blur(path?, deblur_option?)` (Resolve 21+;

package/install.py

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

package/resolve-advanced/server/aaf_probe.py

@@ -160,6 +160,133 @@ def _source_name(clip):
     return _usable_name(clip) or "UNKNOWN"
 
 
+# ── Physical source position + timecode (the "which frames" question) ─────────
+#
+# MEASURED 2026-08-05 on a consolidated Avid turnover: a SourceClip's own
+# `start` is the offset into whatever mob it references DIRECTLY, and for
+# consolidated media that is a per-cut fragment with ~40-frame handles — so 774
+# of 878 events reported srcIn <= 45, and takes used several times all reported
+# the SAME srcIn with different lengths. Two different cuts of one take cannot
+# both begin at frame 42 of that take; those 42s were handles on separate
+# fragments.
+#
+# The real position is the SUM of the `start` offsets down the mob chain, and
+# the anchor that survives relinking to different media is the physical source
+# TIMECODE: the referenced mob's timecode start plus that accumulated offset.
+# A consumer that links camera originals can then place
+# `sourceTc - fileStartTc` instead of a fragment-relative number that merely
+# FITS inside the file.
+#
+# Emitted per event as srcPos / srcTcFrame / srcTc / srcTcFps / srcTcDrop, and
+# only when actually found — a consumer must be able to tell "this AAF carries
+# no source timecode" from "this probe is too old to emit it", which is what
+# the per-sequence sourceTimecodeCoverage counters are for.
+
+
+def _mob_timecode(mob, _cache={}):
+    """(startFrame, rate, drop) from a mob's timecode slot, or None."""
+    try:
+        key = str(getattr(mob, "mob_id", "") or id(mob))
+    except Exception:
+        key = str(id(mob))
+    if key in _cache:
+        return _cache[key]
+    found = None
+    for slot in getattr(mob, "slots", None) or []:
+        try:
+            if _slot_media_kind(slot) != _TIMECODE_KIND:
+                continue
+        except Exception:
+            continue
+        tc = _timecode_component(getattr(slot, "segment", None))
+        if tc is None:
+            continue
+        try:
+            start = int(getattr(tc, "start"))
+            rate = int(round(float(getattr(tc, "fps", 0) or 0)))
+            drop = bool(getattr(tc, "drop", False))
+        except Exception:
+            continue
+        if rate > 0 and start >= 0:
+            found = (start, rate, drop)
+            break
+    _cache[key] = found
+    return found
+
+
+def _chase_source_position(clip):
+    """Physical source position + timecode for a SourceClip's FIRST frame.
+
+    Walks clip -> referenced mob -> that mob's own SourceClip, accumulating each
+    hop's `start`. Returns (position, timecode_or_None) where `timecode` is
+    (tc_start, rate, drop, position_at_that_mob) for the NEAREST mob carrying a
+    timecode slot. Bounded and cycle-guarded like _source_name.
+    """
+    current = clip
+    position = 0
+    timecode = None
+    seen = set()
+    for _ in range(_MAX_MOB_CHASE):
+        try:
+            position += int(getattr(current, "start", 0) or 0)
+        except Exception:
+            pass
+        try:
+            mob = getattr(current, "mob", None)
+        except Exception:
+            mob = None
+        if mob is None:
+            break
+        try:
+            key = str(getattr(mob, "mob_id", "") or id(mob))
+        except Exception:
+            key = str(id(mob))
+        if key in seen:
+            break  # reference cycle — stop rather than spin
+        seen.add(key)
+        if timecode is None:
+            tc = _mob_timecode(mob)
+            if tc is not None:
+                timecode = (tc[0], tc[1], tc[2], position)
+        nxt = None
+        for slot in getattr(mob, "slots", None) or []:
+            nxt = _find_source_clip(getattr(slot, "segment", None))
+            if nxt is not None:
+                break
+        if nxt is None:
+            break
+        current = nxt
+    return position, timecode
+
+
+def _source_position_fields(clip):
+    """The srcPos/srcTc* keys for an event. Empty dict when nothing is knowable."""
+    try:
+        position, timecode = _chase_source_position(clip)
+    except Exception:
+        return {}
+    fields = {}
+    try:
+        own_start = int(getattr(clip, "start", 0) or 0)
+    except Exception:
+        own_start = 0
+    if position != own_start:
+        # Only meaningful when the chain actually went deeper than the clip's
+        # own reference — otherwise srcPos would just restate srcIn.
+        fields["srcPos"] = position
+    if timecode is not None:
+        tc_start, rate, drop, at = timecode
+        fields.update(
+            {
+                "srcTcFrame": tc_start + at,
+                "srcTc": _frames_to_timecode(tc_start + at, rate, drop),
+                "srcTcFps": rate,
+                "srcTcDrop": drop,
+            }
+        )
+    return fields
+
+
 def _emit_source_clip(clip, *, index, track, rec, fps, transition=None):
     """Turn a SourceClip into a normalized event. Returns (event, length)."""
     try:
@@ -183,6 +310,7 @@ def _emit_source_clip(clip, *, index, track, rec, fps, transition=None):
         "transition": transition,
         "fps": fps,
     }
+    event.update(_source_position_fields(clip))
     return event, length
 
 
@@ -884,6 +1012,15 @@ def probe(path):
                     "name": str(name) if name else f"Sequence {len(sequences) + 1}",
                     "eventCount": len(events),
                     **_sequence_start_timecode(mob, edit_fps),
+                    # How much of this sequence carries a physical source position
+                    # / timecode. Always present, so a consumer can tell "this AAF
+                    # has none" (zeros) from "this probe is too old to emit it"
+                    # (key absent) — the same reasoning as _NO_START_TIMECODE.
+                    "sourcePositionCoverage": {
+                        "events": len(events),
+                        "withSourcePosition": sum(1 for e in events if "srcPos" in e),
+                        "withSourceTimecode": sum(1 for e in events if "srcTcFrame" in e),
+                    },
                     # Component classes we could not model, by name+count. Empty {} means
                     # a structurally complete read; non-empty means events are INCOMPLETE.
                     "unhandled": dict(sorted(state["unhandled"].items())),

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.76.0"
+VERSION = "2.78.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 341-tool granular server instead
 """
 
-VERSION = "2.76.0"
+VERSION = "2.78.0"
 
 import base64
 import os
@@ -2579,6 +2579,54 @@ def _find_clip_with_parent(folder, clip_id, _parent=None):
             return found_clip, found_parent
     return None, None
 
+def _find_folder_by_id(folder, folder_id):
+    if folder.GetUniqueId() == folder_id:
+        return folder
+    for sub in (folder.GetSubFolderList() or []):
+        found = _find_folder_by_id(sub, folder_id)
+        if found:
+            return found
+    return None
+
+
+def _folder_from_params(mp, p, *path_keys, no_address="current"):
+    """Resolve the folder an action was aimed at. Returns (folder, error).
+
+    Naming no folder falls back to the action's documented default (see
+    `no_address`). What must never happen is the middle case: an addressing argument was
+    supplied, did not resolve, and the action answered about the current bin
+    anyway. That reports success for a different question than the caller asked,
+    and it is indistinguishable from the tool working. It cost one session an
+    afternoon: `folder_id` is not a key any action read, so it was dropped, the
+    current bin's clips came back, and the tools were written off as broken.
+
+    So: unresolvable-but-supplied is an error, and the id that `get_subfolders`
+    hands out is accepted as an address, since being given an id and having no
+    way to use it is what invited the guess.
+
+    `no_address` preserves each action's historical no-argument default: "current"
+    for the folder tool, "root" for the media_pool actions (whose old code hit
+    `_navigate_folder(mp, "")`, which returns root). This fix must not also
+    change what omitting the address means.
+    """
+    remediation = ("List folders with folder get_subfolders (walking down from "
+                   "path=\"Master\") and address by exact path or folder_id.")
+    path = _first_param(p, *path_keys)
+    if path:
+        f = _navigate_folder(mp, path)
+        return (f, None) if f else (None, _err(
+            f"Folder not found: {path}", code="FOLDER_NOT_FOUND",
+            category="invalid_input", remediation=remediation))
+    folder_id = _first_param(p, "folder_id", "folderId")
+    if folder_id:
+        f = _find_folder_by_id(mp.GetRootFolder(), str(folder_id))
+        return (f, None) if f else (None, _err(
+            f"Folder not found: {folder_id}", code="FOLDER_NOT_FOUND",
+            category="invalid_input", remediation=remediation))
+    f = mp.GetRootFolder() if no_address == "root" else mp.GetCurrentFolder()
+    return (f, None) if f else (None, _err("No current Media Pool folder"))
+
+
 def _navigate_folder(mp, path):
     root = mp.GetRootFolder()
     if not path or path in ("Master", "/", ""):
@@ -16666,7 +16714,9 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
             return _err(f"Folder not found: {p.get('path')}")
         return {"success": bool(mp.SetCurrentFolder(f))}
     elif action == "add_subfolder":
-        parent = _navigate_folder(mp, p.get("parent_path", "")) or mp.GetCurrentFolder()
+        parent, folder_err = _folder_from_params(mp, p, "parent_path", "parentPath", no_address="root")
+        if folder_err:
+            return folder_err
         f = mp.AddSubFolder(parent, p["name"])
         return _ok(name=f.GetName(), id=f.GetUniqueId()) if f else _err("Failed to create subfolder")
     elif action == "delete_folders":
@@ -16973,7 +17023,9 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         clip = _find_clip(root, p["clip_id"])
         return {"mattes": mp.GetClipMatteList(clip)} if clip else _err("Clip not found")
     elif action == "get_timeline_mattes":
-        folder = _navigate_folder(mp, p.get("folder_path", "")) or mp.GetCurrentFolder()
+        folder, folder_err = _folder_from_params(mp, p, "folder_path", "folderPath", no_address="root")
+        if folder_err:
+            return folder_err
         result = mp.GetTimelineMatteList(folder)
         return {"mattes": len(result) if result else 0}
     elif action == "delete_clip_mattes":
@@ -17037,6 +17089,11 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
 def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """Operations on Media Pool folders.
 
+    Address a folder with `path` ("Master/SubFolder") or with `folder_id` (the id
+    get_subfolders returns). Omit both for the current folder. An address that is
+    supplied but does not resolve is an error — it never falls back to the current
+    folder.
+
     Actions:
       get_clips(path?) -> {clips}  — path like "Master/SubFolder", omit for current
       get_name(path?) -> {name}
@@ -17057,10 +17114,9 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     if err:
         return err
 
-    folder_path = p.get("path", "")
-    f = _navigate_folder(mp, folder_path) if folder_path else mp.GetCurrentFolder()
-    if not f:
-        return _err(f"Folder not found: {folder_path}")
+    f, folder_err = _folder_from_params(mp, p, "path", "folder_path", "folderPath")
+    if folder_err:
+        return folder_err
 
     if action == "get_clips":
         clips = f.GetClipList() or []