davinci-resolve-mcp 2.72.1 → 2.73.1

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 v2.73.1
+
+Packaging fix. The npm package shipped the AAF reader's Node half without its
+Python half, so offline AAF preview could never have worked from an npm install.
+
+### Fixed
+
+- **`aaf_probe.py` was missing from the published npm package.** The `files`
+  allowlist was written in v2.58.0 as `resolve-advanced/server/**/*.mjs`, and
+  when `aaf_probe.py` landed in v2.59.0 the allowlist was not extended. `aaf.mjs`
+  shipped and shelled out to a file that did not exist on disk, so every
+  `parse_interchange` / `list_sequences` call against a `.aaf` failed for
+  npm-installed users. Repository clones were unaffected, which is why it
+  survived a year of releases unnoticed.
+
+  The failure was at least loud rather than a fake parse — but its remediation
+  was actively misleading. The probe exited 2 (`can't open file …aaf_probe.py`),
+  which fell through to the generic branch and appended "Install the offline AAF
+  reader (`pip install pyaaf2`)". Installing pyaaf2 cannot fix a file that was
+  never packaged, so the message sent anyone who hit it down a dead end.
+
+  This means the v2.73.0 multi-layer AAF fix did not reach npm users at all;
+  2.73.1 is what actually delivers it.
+
+## What's New in v2.73.0
+
+The offline AAF reader could not read a multi-layer Avid timeline, and said so
+in the worst possible way: `ok: true` with an empty event list, indistinguishable
+from an empty timeline. Any caller gating on a successful parse would proceed to
+conform nothing.
+
+### Fixed
+
+- **AAF: multi-layer timelines returned zero events while reporting success.**
+  Avid exports a multi-layer video timeline as a `NestedScope` segment, which the
+  offline reader never traversed — `NestedScope` carries `.slots`, not
+  `.components`, so the whole timeline fell through the walker's lone-`SourceClip`
+  fallback and emitted nothing. Two further drops sat on the same path and had to
+  be fixed with it: `OperationGroup.segments` holds a nested `Sequence` rather than
+  a direct `SourceClip`, so effect-wrapped clips — the majority of any real
+  turnover — were dropped even once `NestedScope` was traversed; and source-name
+  resolution stopped one mob hop short of the MasterMob, because Avid routes
+  timeline clips through an unnamed intermediate `CompositionMob`, resolving most
+  clips to `UNKNOWN`. `Selector` segments are now followed (via the AAF `Selected`
+  property — pyaaf2 does not expose it as an attribute), and non-editorial slots
+  are skipped by media kind rather than segment class, so `Pulldown`-wrapped
+  timecode tracks no longer leak through as editorial.
+
+  Verified against a real 83-minute Avid picture turnover: **0 → 878 events**
+  across 5 layers, **0 `UNKNOWN` sources** (779 distinct camera rolls), no
+  unhandled component classes, ~1.5 s.
+
+### Added
+
+- AAF probe and `listAafSequences` now report an `unhandled` map (component class
+  → count) per sequence. A structural miss is visible instead of masquerading as
+  an empty timeline.
+
+### Known limitations, stated deliberately
+
+- **Motion Control retimes are flagged, not quantified.** They carry
+  `effect: "Motion Control"` with `speed: 100`, because the ratio is not
+  recoverable offline. A consumer reading `speed` alone will treat them as full
+  speed. Pre-existing behaviour, preserved on purpose — flag over fabricate.
+- **Effect-only layers correctly produce no events.** Layers that wrap
+  `ScopeReference` (subtitle burns, blends, mattes) apply to what shows through
+  from below and reference no media of their own. OTIO reports such layers as
+  tracks of gaps, so its track count can exceed the number of layers with media;
+  "6 layers" is not "6 layers with media". Events were not fabricated to make the
+  counts match.
+- **Only `NestedScope` layers are numbered `V1..Vn`.** Non-nested slots keep the
+  flat `V`/`A` label, a deliberate scope limit that keeps the blast radius off
+  simple AAFs — notably `editorial.mjs`'s `track === 'A'` audio-follows-video
+  heuristic, which reads that label.
+
 ## What's New in v2.72.1
 
 Documentation only. The API coverage page stated its method counts in four

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.72.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.73.1-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/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.72.1"
+VERSION = "2.73.1"
 # 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.72.1",
+  "version": "2.73.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",
@@ -37,6 +37,7 @@
     "bin/",
     "src/**/*.py",
     "resolve-advanced/server/**/*.mjs",
+    "resolve-advanced/server/**/*.py",
     "resolve-advanced/vendor/**",
     "resolve-advanced/package.json",
     "resolve-advanced/README.md",

package/resolve-advanced/README.md

@@ -173,6 +173,25 @@ status + install hints):
 Missing features fail with a clear, actionable message rather than crashing; the server logs a one-line
 "needs setup" summary to stderr at startup.
 
+> **Pinning the AAF interpreter.** `aaf_probe.py` runs under `AAF_PROBE_PYTHON`, falling back to
+> `PYTHON` and then plain `python3` on PATH. `install.py` sets that pin **only inside the `mcpServers`
+> JSON entry it writes**, so a host that spawns this advanced server some other way must pin it itself —
+> otherwise the reader resolves a `python3` without `pyaaf2` and honest-refuses every AAF.
+
+### AAF multi-layer reading — what it does and does not tell you
+Avid exports a multi-layer video timeline as a `NestedScope` segment holding one nested `Sequence` per
+layer; those layers are traversed and numbered `V1..Vn`. Each parsed sequence also carries an
+`unhandled` map (component class → count) so a structural miss is visible rather than arriving as a
+plausible-looking short event list. Three limits are deliberate:
+
+- **Motion Control retimes are flagged, not quantified** — `effect: "Motion Control"` with `speed: 100`,
+  because the ratio is not recoverable offline. Reading `speed` alone reports them as full speed.
+- **Effect-only layers produce no events.** A layer wrapping `ScopeReference` (subtitle burns, blends,
+  mattes) applies to what shows through from below and references no media of its own. OTIO materializes
+  such layers as tracks of gaps, so its track count can exceed the number of layers with media.
+- **Only `NestedScope` layers are numbered.** Non-nested slots keep the flat `V`/`A` label, which is what
+  `editorial.mjs`'s `track === 'A'` audio-follows-video heuristic reads.
+
 ## Provenance & license
 Vendored libraries are clean offline format-interop and deterministic compute code: no secrets, no
 external service coupling, no network calls, no LLM dependency. Where a feature can take a second

package/resolve-advanced/server/aaf.mjs

@@ -94,11 +94,21 @@ export async function parseAAF(contentOrPath) {
 
 /**
  * Enumerate the sequences inside an AAF for the picker.
+ *
+ * `unhandled` is carried through deliberately: a structural miss in the probe
+ * (a component class it cannot walk) otherwise looks identical to a genuinely
+ * empty timeline, and the caller would gate on a successful parse and conform
+ * nothing. A NestedScope — Avid's multi-layer video stack — used to land in
+ * exactly that hole: eventCount 0 alongside ok:true. Absent means clean.
  * @param {string} contentOrPath absolute .aaf path
- * @returns {Promise<Array<{id:string,name:string,eventCount:number}>>}
+ * @returns {Promise<Array<{id:string,name:string,eventCount:number,unhandled?:Object}>>}
  */
 export async function listAafSequences(contentOrPath) {
   const aafPath = resolveAafPath(contentOrPath);
   const { sequences } = await runProbe(aafPath);
-  return (sequences || []).map((s) => ({ id: String(s.id), name: String(s.name), eventCount: Number(s.eventCount || 0) }));
+  return (sequences || []).map((s) => {
+    const out = { id: String(s.id), name: String(s.name), eventCount: Number(s.eventCount || 0) };
+    if (s.unhandled && Object.keys(s.unhandled).length) out.unhandled = s.unhandled;
+    return out;
+  });
 }

package/resolve-advanced/server/aaf_probe.py

@@ -0,0 +1,457 @@
+#!/usr/bin/env python3
+"""
+aaf_probe — offline AAF (.aaf) reader for the editorial `parse_interchange` /
+`list_sequences` picker+preview.
+
+AAF is a binary Structured-Storage container; there is no pure-JS reader worth
+trusting, so the Node server shells out to this helper, which uses the pure-Python
+`aaf2` library (pyaaf2). It emits ONE JSON object on stdout:
+
+    {
+      "ok": true,
+      "sequences": [
+        { "id": <mob-id str>, "name": <str>, "eventCount": <int>,
+          "unhandled": { "<ComponentClass>": <int>, ... },
+          "events": [ {normalized-event}, ... ] }
+      ]
+    }
+
+Normalized event shape mirrors resolve-advanced/server/editorial.mjs `evt()`:
+    { index, track, source, srcIn, srcOut, recIn, recOut, speed, reverse, transition, fps }
+
+Honest-refuse discipline (no fake parses):
+  * exit 3  → pyaaf2 not installed        (stderr: AAF_PROBE_NO_PYAAF2)
+  * exit 4  → file unreadable / not an AAF (stderr: AAF_PROBE_UNREADABLE: <detail>)
+  * exit 2  → bad invocation
+Per-sequence event extraction is best-effort and defensive: if a component can't
+be decoded we still report the sequence with its clip count — we never fabricate.
+
+`unhandled` is the teeth behind that promise. A structural miss (a component class
+this walker does not model) used to be swallowed silently, so a whole multi-layer
+timeline could come back as `ok:true` with `eventCount: 0` — indistinguishable from
+an genuinely empty sequence, and worse than an honest refusal because downstream
+consumers gate on `ok`. Every component we skip is now counted by class name and
+reported per sequence, so a miss is VISIBLE without changing the exit-code contract.
+
+Segment model (Avid Media Composer picture turnovers):
+  * NestedScope  — a multi-layer video track. Its `.slots` are the layers (V1..Vn);
+                   it has NO `.components`. Layers are PARALLEL, so each layer's
+                   record position restarts at 0.
+  * Sequence     — ordered `.components`, laid end to end.
+  * OperationGroup — effect wrapper. Its `.segments` are the effect INPUTS, and the
+                   primary input is usually a nested Sequence (not a bare SourceClip).
+  * Selector     — an enabled/disabled layer variant; the live one is `Selected`.
+  * ScopeReference — "show the NestedScope layer beneath me": real record time, no
+                   clip of this layer's own. Treated as a gap, like Filler.
+"""
+
+import json
+import os
+import sys
+
+
+def _fps_from_edit_rate(edit_rate):
+    try:
+        return round(float(edit_rate), 6)
+    except Exception:
+        return None
+
+
+# How far to chase the mob reference chain looking for a named mob (see _source_name).
+_MAX_MOB_CHASE = 8
+
+
+def _usable_name(obj):
+    """A real name, or None. pyaaf2 returns the CLASS NAME for an unset `.name`, so a
+    value equal to the object's type name means "absent", not a source called SourceClip."""
+    try:
+        v = getattr(obj, "name", None)
+    except Exception:
+        return None
+    if not v:
+        return None
+    text = str(v).strip()
+    if not text or text == type(obj).__name__:
+        return None
+    return text
+
+
+def _find_source_clip(segment, depth=0):
+    """First SourceClip inside an arbitrary segment tree (bounded)."""
+    if segment is None or depth > 8:
+        return None
+    cls = type(segment).__name__
+    if cls == "SourceClip":
+        return segment
+    if cls == "Selector":
+        return _find_source_clip(_selector_selected(segment), depth + 1)
+    if cls == "Sequence":
+        children = getattr(segment, "components", None) or []
+    elif cls == "OperationGroup":
+        children = getattr(segment, "segments", None) or []
+    elif cls == "NestedScope":
+        children = _nested_layers(segment)
+    else:
+        return None
+    for child in children:
+        found = _find_source_clip(child, depth + 1)
+        if found is not None:
+            return found
+    return None
+
+
+def _source_name(clip):
+    """Best-effort human name for a SourceClip: the nearest NAMED mob it references.
+
+    Avid does not point a timeline SourceClip straight at a MasterMob. Subclips, group
+    clips and motion-effect sources go through one or more UNNAMED intermediate
+    CompositionMobs, so stopping at `clip.mob.name` yields nothing for the majority of
+    a real turnover's clips. Chase the reference chain — mob → its slot's SourceClip →
+    that clip's mob — until a mob actually carries a name (typically the MasterMob, e.g.
+    "A001C001_240101_AB01.new.01"). Bounded and cycle-guarded.
+    """
+    current = clip
+    seen = set()
+    for _ in range(_MAX_MOB_CHASE):
+        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)
+        name = _usable_name(mob)
+        if name:
+            return name
+        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
+    # No named mob anywhere in the chain — fall back to the clip's own name.
+    return _usable_name(clip) or "UNKNOWN"
+
+
+def _emit_source_clip(clip, *, index, track, rec, fps, transition=None):
+    """Turn a SourceClip into a normalized event. Returns (event, length)."""
+    try:
+        length = int(getattr(clip, "length", 0) or 0)
+    except Exception:
+        length = 0
+    try:
+        start = int(getattr(clip, "start", 0) or 0)
+    except Exception:
+        start = 0
+    event = {
+        "index": index,
+        "track": track,
+        "source": _source_name(clip),
+        "srcIn": start,
+        "srcOut": start + length,
+        "recIn": rec,
+        "recOut": rec + length,
+        "speed": 100,
+        "reverse": False,
+        "transition": transition,
+        "fps": fps,
+    }
+    return event, length
+
+
+# Depth guard: AAF nesting is a graph and a malformed file could cycle. Real Avid
+# turnovers nest ~4 deep (NestedScope > Sequence > Selector > OperationGroup > Sequence).
+_MAX_DEPTH = 24
+
+
+def _length(obj):
+    try:
+        return int(getattr(obj, "length", 0) or 0)
+    except Exception:
+        return 0
+
+
+def _note_unhandled(state, cls):
+    """Record a component class we could not turn into events. See module docstring."""
+    state["unhandled"][cls] = state["unhandled"].get(cls, 0) + 1
+
+
+def _nested_layers(scope):
+    """The parallel layers of a NestedScope.
+
+    pyaaf2 hands back the layer Segments directly for this class, but tolerate a
+    slot-like wrapper (`.segment`) too so we work across pyaaf2 versions.
+    """
+    layers = []
+    for item in getattr(scope, "slots", []) or []:
+        inner = getattr(item, "segment", None)
+        layers.append(inner if inner is not None else item)
+    return layers
+
+
+def _selector_selected(comp):
+    """The live variant of a Selector (Avid enabled/disabled layer variants).
+
+    This is the AAF `Selected` PROPERTY — pyaaf2 does not expose it as a `.selected`
+    python attribute, so read it via getvalue()/[] first and only then fall back.
+    """
+    for getter in (
+        lambda c: c.getvalue("Selected"),
+        lambda c: c["Selected"].value,
+        lambda c: getattr(c, "selected", None),
+    ):
+        try:
+            v = getter(comp)
+            if v is not None:
+                return v
+        except Exception:
+            pass
+    return None
+
+
+def _operation_name(comp):
+    try:
+        return str(getattr(getattr(comp, "operation", None), "name", "") or "")
+    except Exception:
+        return ""
+
+
+def _walk_segment(segment, *, track, fps, rec, state, depth=0, transition=None):
+    """
+    Emit normalized events for ONE segment placed at record position `rec`.
+
+    Appends to `state["events"]` (indices from the monotonic `state["idx"]`) and
+    counts anything it cannot model into `state["unhandled"]`.
+
+    Returns the number of RECORD frames this segment occupies, so a caller laying
+    components end to end can advance. Container classes return their own declared
+    length rather than the sum of what we managed to decode — a partial decode must
+    not silently slide every later clip earlier on the timeline.
+    """
+    cls = type(segment).__name__
+    declared = _length(segment)
+
+    if depth > _MAX_DEPTH:
+        _note_unhandled(state, cls)
+        return declared
+
+    if cls == "SourceClip":
+        ev, length = _emit_source_clip(
+            segment, index=state["idx"], track=track, rec=rec, fps=fps, transition=transition
+        )
+        state["events"].append(ev)
+        state["idx"] += 1
+        return length
+
+    if cls in ("Filler", "ScopeReference"):
+        # Filler = a real gap. ScopeReference = "the NestedScope layer beneath shows
+        # through here" — real record time, but no clip of THIS layer's own.
+        return declared
+
+    if cls == "Sequence":
+        return _walk_components(segment, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+
+    if cls == "NestedScope":
+        # Layers are parallel in time: every one starts at this segment's own rec.
+        for layer in _nested_layers(segment):
+            _walk_segment(layer, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+        return declared
+
+    if cls == "Selector":
+        selected = _selector_selected(segment)
+        if selected is None:
+            _note_unhandled(state, cls)
+        else:
+            _walk_segment(selected, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+        return declared
+
+    if cls == "OperationGroup":
+        # Effect wrapper (retime, paint, resize, blend, matte key...). Its `.segments`
+        # are the effect INPUTS, and the primary is usually a nested Sequence, NOT a
+        # bare SourceClip — only descending to a direct SourceClip finds nothing.
+        #
+        # EVERY input is walked, not just the primary: an SBlend B-side or a matte
+        # key's fill/key are real referenced media that a conform has to relink, and
+        # dropping them is the same data loss this walker exists to prevent. They share
+        # the primary's record span (that is what a blend IS), so they intentionally
+        # overlap it on the same track label. Callers already cannot assume events are
+        # non-overlapping — parallel NestedScope layers overlap by construction.
+        before = len(state["events"])
+        for inp in getattr(segment, "segments", None) or []:
+            _walk_segment(inp, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+        op_name = _operation_name(segment)
+        if op_name and ("speed" in op_name.lower() or "motion" in op_name.lower()):
+            # We can detect that a retime is present but not reliably its ratio
+            # offline; flag it honestly rather than fake a speed number.
+            for ev in state["events"][before:]:
+                ev["effect"] = op_name
+        return declared
+
+    # Unknown component — advance by its declared length, don't fake an event, and
+    # make the miss loud so it cannot masquerade as an empty timeline.
+    _note_unhandled(state, cls)
+    return declared
+
+
+def _walk_components(sequence, *, track, fps, rec, state, depth, transition=None):
+    """Lay a Sequence's components end to end. Returns the record length consumed."""
+    start = rec
+    pending_transition = transition
+    components = getattr(sequence, "components", None)
+    if components is None:
+        components = [sequence]
+    for comp in components:
+        cls = type(comp).__name__
+        try:
+            if cls == "Transition":
+                # A transition overlaps its neighbours; it does not advance rec itself.
+                pending_transition = {"type": "dissolve", "duration": _length(comp)}
+                continue
+            rec += _walk_segment(
+                comp, track=track, fps=fps, rec=rec, state=state, depth=depth, transition=pending_transition
+            )
+            pending_transition = None
+        except Exception:
+            # Never let one bad component abort the whole sequence — but say so.
+            _note_unhandled(state, cls)
+            pending_transition = None
+            continue
+    return rec - start
+
+
+def _walk_slot(segment, *, prefix, fps, state):
+    """
+    Walk one mob slot's top-level segment into `state`.
+
+    A NestedScope slot is a multi-layer track: each layer gets its own numbered label
+    (V1..Vn / A1..An) and restarts at record 0, because layers are parallel, not
+    sequential. A plain (single-layer) slot keeps the flat "V"/"A" label.
+    """
+    if type(segment).__name__ == "NestedScope":
+        for n, layer in enumerate(_nested_layers(segment), start=1):
+            _walk_segment(layer, track=f"{prefix}{n}", fps=fps, rec=0, state=state, depth=1)
+        return
+    _walk_segment(segment, track=prefix, fps=fps, rec=0, state=state, depth=0)
+
+
+# Slot media kinds that carry no editorial cuts. Matched on MEDIA KIND, not on the
+# segment's class name: Avid wraps timecode slots in a Pulldown (segment class
+# "Pulldown", media_kind "Timecode"), so a class-name-only skip let them through and
+# they polluted both the events and the unhandled counter.
+_NON_EDITORIAL_KINDS = frozenset(
+    {"timecode", "edgecode", "descriptivemetadata", "soundmastertrack"}
+)
+
+
+def _norm_kind(value):
+    try:
+        return "".join(str(value or "").split()).lower()
+    except Exception:
+        return ""
+
+
+def _slot_media_kind(slot):
+    """Media kind of a slot, falling back to its segment's."""
+    for owner in (slot, getattr(slot, "segment", None)):
+        kind = _norm_kind(getattr(owner, "media_kind", None))
+        if kind:
+            return kind
+    return ""
+
+
+def _is_editorial_slot(slot):
+    return _slot_media_kind(slot) not in _NON_EDITORIAL_KINDS
+
+
+def _media_kind_to_track(slot):
+    return "A" if _slot_media_kind(slot).startswith("sound") else "V"
+
+
+def probe(path):
+    import aaf2
+
+    sequences = []
+    with aaf2.open(path, "r") as f:
+        toplevel = list(f.content.toplevel())
+        # Fall back to all composition mobs if no explicit top-level usage is set.
+        if not toplevel:
+            try:
+                toplevel = [m for m in f.content.mobs if type(m).__name__ == "CompositionMob"]
+            except Exception:
+                toplevel = []
+        for mob in toplevel:
+            try:
+                mob_id = str(getattr(mob, "mob_id", "") or "")
+            except Exception:
+                mob_id = ""
+            name = None
+            try:
+                name = getattr(mob, "name", None)
+            except Exception:
+                name = None
+            # `idx` is monotonic across the WHOLE mob, every slot and every nested layer.
+            state = {"idx": 1, "events": [], "unhandled": {}}
+            for slot in getattr(mob, "slots", []) or []:
+                seg = getattr(slot, "segment", None)
+                if seg is None:
+                    continue
+                # Skip non-editorial slots by MEDIA KIND (timecode/edgecode/descriptive
+                # metadata/sound master) — see _NON_EDITORIAL_KINDS.
+                if not _is_editorial_slot(slot):
+                    continue
+                _walk_slot(
+                    seg,
+                    prefix=_media_kind_to_track(slot),
+                    fps=_fps_from_edit_rate(getattr(slot, "edit_rate", None)),
+                    state=state,
+                )
+            events = state["events"]
+            sequences.append(
+                {
+                    "id": mob_id or (str(name) if name else f"seq{len(sequences) + 1}"),
+                    "name": str(name) if name else f"Sequence {len(sequences) + 1}",
+                    "eventCount": len(events),
+                    # 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())),
+                    "events": events,
+                }
+            )
+    return sequences
+
+
+def main(argv):
+    if len(argv) < 2:
+        sys.stderr.write("AAF_PROBE_USAGE: aaf_probe.py <path.aaf>\n")
+        return 2
+    path = argv[1]
+    if not os.path.exists(path):
+        sys.stderr.write(f"AAF_PROBE_UNREADABLE: no such file: {path}\n")
+        return 4
+    try:
+        import aaf2  # noqa: F401
+    except Exception:
+        sys.stderr.write(
+            "AAF_PROBE_NO_PYAAF2: the pure-Python 'aaf2' package (pyaaf2) is not installed\n"
+        )
+        return 3
+    try:
+        sequences = probe(path)
+    except Exception as e:  # unreadable / not an AAF / decode failure
+        sys.stderr.write(f"AAF_PROBE_UNREADABLE: {type(e).__name__}: {e}\n")
+        return 4
+    json.dump({"ok": True, "sequences": sequences}, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.72.1"
+VERSION = "2.73.1"
 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.72.1"
+VERSION = "2.73.1"
 
 import base64
 import os