davinci-resolve-mcp 2.52.1 → 2.53.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 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.53.0
+
+Two improvements to audio sync reliability and inventory control.
+
+`safe_auto_sync_audio` / `media_pool.auto_sync_audio` no longer fail silently on
+human-readable settings (issue #70). The previous normalizer recognized
+`syncBy`/`mode` but not `method`, and it forwarded *every* unrecognized key
+(`group_id`, `primary_clip_id`, …) straight into `MediaPool.AutoSyncAudio` —
+which silently rejects the whole call when it sees a key it doesn't understand,
+returning `False` with nothing linked and no error.
+
+- **Fixed** `method` (matching the tool's own parameter naming) is now accepted
+  as an alias for the sync mode alongside `syncBy`/`sync_by`/`mode`/`syncMode`.
+- **Fixed** unrecognized settings keys are dropped instead of forwarded, so a
+  stray `group_id`/`primary_clip_id` no longer poisons the call. Dropped keys
+  are reported back in a new `ignored_settings` field on the response, so a
+  rejection is no longer invisible.
+- **Fixed** the raw `media_pool.auto_sync_audio` action now routes settings
+  through the same live `AUDIO_SYNC_*` enum resolution as the safe wrapper
+  (previously it passed strings straight through).
+
+The Media Pool inventory walk is now configurable:
+
+- **Added** `media_analysis.inventory_exclude_bins` — a comma-separated list of
+  folder names to skip entirely during the inventory walk (recursively). Empty
+  by default, so every folder is indexed unless you opt out.
+- **Added** `media_analysis.inventory_limit` — the maximum clips to index per
+  walk, configurable from the control panel and `setup`. The hard ceiling is
+  raised from 2000 to 10000.
+- Adapted from PR #69 by @rgxdev; the default was changed to exclude nothing
+  (the PR defaulted to excluding an `assets` bin, which would have silently
+  stopped indexing existing `assets` folders on upgrade).
+
 ## What's New in v2.52.1
 
 Analysis reuse no longer blocks on missing capabilities when every clip is

package/README.md

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

@@ -999,7 +999,11 @@ helpers:
 - `audio_mix_capability_report(...)`
 - `voice_isolation_capabilities(track_index?, track_type?, item_index?)`
 - `audio_mapping_report(clip_ids?)`
-- `safe_auto_sync_audio(clip_ids|selected, settings?, dry_run?)`
+- `safe_auto_sync_audio(clip_ids|selected, settings?, dry_run?)` — `settings`
+  accepts human-readable keys: `method`/`mode` (`waveform`|`timecode`),
+  `channel` (`auto`|`mix`|int), `retain_embedded_audio`, `retain_video_metadata`.
+  Unrecognized keys are dropped and echoed back in `ignored_settings` rather than
+  silently failing the call.
 - `transcription_capabilities(clip_ids?|selected?)`
 - `subtitle_generation_probe(settings?, allow_generate?)`
 - `fairlight_boundary_report`

package/install.py

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

package/src/analysis_dashboard.py

@@ -4790,6 +4790,12 @@ HTML = r"""<!doctype html>
               <button type="button" class="secondary path-browse" data-browse-target="prefPreferredGeneratedMediaFolder">Browse…</button>
             </div>
           </label>
+          <label>Inventory limit
+            <input id="prefInventoryLimit" type="number" min="1" max="10000" placeholder="Default 500">
+          </label>
+          <label>Inventory exclude bins (comma separated)
+            <input id="prefInventoryExcludeBins" type="text" placeholder="None — index every folder">
+          </label>
           <label>Post-operation page
             <select id="prefPostOperationPage">
               <option value="stay_put">stay put</option>
@@ -5088,6 +5094,8 @@ HTML = r"""<!doctype html>
       prefDryRunFirstDefault: 'Prefers a preview pass before committing metadata or marker changes.',
       prefPreferredAnalysisRoot: 'Optional absolute path for analysis databases and reports. Empty uses the project analysis root.',
       prefPreferredGeneratedMediaFolder: 'Optional folder for generated sidecars or scratch outputs when a workflow needs them.',
+      prefInventoryLimit: 'Maximum number of clips to index during the Media Pool inventory walk (1–10000).',
+      prefInventoryExcludeBins: 'Comma-separated folder names to skip entirely during the inventory walk. Empty indexes every folder.',
       prefPostOperationPage: 'Resolve page to open after an operation completes, or stay put.',
       prefUpdateMode: 'Controls update checks for the MCP package.',
       prefUpdateIntervalHours: 'Minimum time between best-effort release checks.',
@@ -10233,6 +10241,8 @@ HTML = r"""<!doctype html>
       setControlChecked('prefDryRunFirstDefault', media.dry_run_first_default);
       setControlValue('prefPreferredAnalysisRoot', media.preferred_analysis_root || '');
       setControlValue('prefPreferredGeneratedMediaFolder', media.preferred_generated_media_folder || '');
+      setControlValue('prefInventoryLimit', media.inventory_limit || 500);
+      setControlValue('prefInventoryExcludeBins', media.inventory_exclude_bins || '');
       setControlValue('prefPostOperationPage', media.default_post_operation_page);
       setControlValue('prefUpdateMode', updates.mode);
       setControlValue('prefUpdateIntervalHours', updates.check_interval_hours);
@@ -10361,6 +10371,8 @@ HTML = r"""<!doctype html>
           dry_run_first_default: $('prefDryRunFirstDefault').checked,
           preferred_analysis_root: $('prefPreferredAnalysisRoot').value.trim() || 'clear',
           preferred_generated_media_folder: $('prefPreferredGeneratedMediaFolder').value.trim() || 'clear',
+          inventory_limit: parseInt($('prefInventoryLimit').value, 10) || 500,
+          inventory_exclude_bins: $('prefInventoryExcludeBins').value.trim(),
           default_post_operation_page: $('prefPostOperationPage').value,
         },
         updates: {
@@ -12013,6 +12025,7 @@ def _append_folder_media(
     records: List[Dict[str, Any]],
     warnings: List[str],
     limit: int,
+    exclude_bins: Optional[set] = None,
 ) -> bool:
     clips, clip_err = _safe_call(folder, "GetClipList")
     if clip_err:
@@ -12033,6 +12046,8 @@ def _append_folder_media(
         if len(records) >= limit:
             return True
         child_name = _safe_name(subfolder, "Unnamed")
+        if exclude_bins and child_name in exclude_bins:
+            continue
         truncated = _append_folder_media(
             subfolder,
             bin_path=f"{bin_path}/{child_name}",
@@ -12041,6 +12056,7 @@ def _append_folder_media(
             records=records,
             warnings=warnings,
             limit=limit,
+            exclude_bins=exclude_bins,
         )
         if truncated:
             return True
@@ -12256,12 +12272,13 @@ def resolve_media_inventory(
     project_root: str,
     *,
     limit: Any = 500,
+    exclude_bins: Optional[set] = None,
     recursive: bool = True,
     probe_paths: bool = True,
     reuse_cached: bool = False,
 ) -> Dict[str, Any]:
     try:
-        max_items = max(1, min(int(limit), 2000))
+        max_items = max(1, min(int(limit), 10000))
     except (TypeError, ValueError):
         max_items = 500
 
@@ -12349,6 +12366,7 @@ def resolve_media_inventory(
             records=records,
             warnings=warnings,
             limit=max_items,
+            exclude_bins=exclude_bins,
         )
         project_info = {
             "name": _safe_name(project, "Resolve Project"),
@@ -14655,6 +14673,25 @@ def _setup_defaults(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     return server_setup(action, params or {})
 
 
+def _inventory_prefs() -> Tuple[int, Optional[set]]:
+    """Return (limit, exclude_bins) for the inventory walk from media-analysis
+    preferences. ``exclude_bins`` is None when nothing is configured, so the walk
+    indexes every folder by default."""
+    try:
+        from src.server import _media_analysis_effective_preferences
+
+        prefs = _media_analysis_effective_preferences()
+    except Exception:  # noqa: BLE001 — fall back to built-in defaults
+        prefs = {}
+    try:
+        limit = max(1, min(int(prefs.get("inventory_limit", 500)), 10000))
+    except (TypeError, ValueError):
+        limit = 500
+    raw = prefs.get("inventory_exclude_bins")
+    exclude = {part.strip() for part in str(raw).split(",") if part.strip()} if raw else None
+    return limit, (exclude or None)
+
+
 class Handler(BaseHTTPRequestHandler):
     state: DashboardState
 
@@ -14838,10 +14875,12 @@ class Handler(BaseHTTPRequestHandler):
             self._json(_setup_defaults("get_defaults"))
             return
         if path == "/api/resolve/media":
+            pref_limit, exclude_bins = _inventory_prefs()
             self._json_etag(
                 resolve_media_inventory(
                     self.state.project_root,
-                    limit=(query.get("limit") or [500])[0],
+                    limit=(query.get("limit") or [pref_limit])[0],
+                    exclude_bins=exclude_bins,
                     recursive=(query.get("recursive") or ["true"])[0].lower() not in {"0", "false", "no"},
                     probe_paths=(query.get("probe") or ["1"])[0].lower() not in {"0", "false", "no"},
                     reuse_cached=(query.get("reuse") or ["0"])[0].lower() in {"1", "true", "yes"},
@@ -15429,7 +15468,8 @@ def _warm_inventory_cache(project_root: str) -> None:
     first real request builds normally.
     """
     try:
-        resolve_media_inventory(project_root)
+        pref_limit, exclude_bins = _inventory_prefs()
+        resolve_media_inventory(project_root, limit=pref_limit, exclude_bins=exclude_bins)
     except Exception:  # noqa: BLE001 — warm-up must never crash startup
         pass
 

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.52.1"
+VERSION = "2.53.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.52.1"
+VERSION = "2.53.0"
 
 import base64
 import os
@@ -5932,9 +5932,9 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
     # until populated and can be reset to None by a mid-call reconnect. A None
     # here makes _normalize_auto_sync_settings fall back to string enum keys,
     # which AutoSyncAudio silently rejects (returns False).
-    settings = _normalize_auto_sync_settings(dict(p.get("settings") or {}), get_resolve())
+    settings, ignored_settings = _normalize_auto_sync_settings(dict(p.get("settings") or {}), get_resolve())
     if p.get("dry_run", True):
-        return _ok(would_auto_sync=True, clips=_clip_summaries(clips), missing=missing, settings=settings)
+        return _ok(would_auto_sync=True, clips=_clip_summaries(clips), missing=missing, settings=settings, ignored_settings=ignored_settings)
     # Read-back verification: AutoSyncAudio's boolean return is unreliable, so
     # capture each clip's "Synced Audio" linkage before and after and report the
     # delta. Trust `linked`/`newly_linked`, not `success`.
@@ -5969,6 +5969,7 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
         "count": len(clips),
         "missing": missing,
         "settings": settings,
+        "ignored_settings": ignored_settings,
     }
 
 
@@ -5979,14 +5980,36 @@ def _resolve_audio_constant(resolve_obj, name: str, fallback):
 
 
 def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
+    """Translate human-readable AutoSyncAudio settings into live ``AUDIO_SYNC_*``
+    enum keys/values.
+
+    Returns ``(normalized, ignored)`` where ``ignored`` is the sorted list of
+    settings keys AutoSyncAudio does not understand (e.g. ``group_id``,
+    ``primary_clip_id``). Those are dropped rather than forwarded: passing any
+    unrecognized key makes ``MediaPool.AutoSyncAudio`` silently reject the whole
+    call (returns ``False``, nothing links). Callers surface ``ignored`` so the
+    rejection is no longer invisible. See utils/api_truth.py: MediaPool.AutoSyncAudio.
+    """
     if not settings:
-        return settings
+        return {}, []
     normalized = {}
     mode_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_MODE", "syncMode")
     channel_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_CHANNEL_NUMBER", "channelNumber")
     retain_embedded_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_RETAIN_EMBEDDED_AUDIO", "retainEmbeddedAudio")
     retain_metadata_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_RETAIN_VIDEO_METADATA", "retainVideoMetadata")
-    mode = settings.get("syncBy", settings.get("sync_by", settings.get("mode", settings.get(mode_key))))
+
+    consumed: set = set()
+
+    def _pick(*keys):
+        for key in keys:
+            if key in settings:
+                consumed.add(key)
+                return settings[key]
+        return None
+
+    # "method" is a natural alias for the sync mode (the tool advertises
+    # method="waveform"); accept it alongside syncBy/mode and a pre-resolved key.
+    mode = _pick("syncBy", "sync_by", "mode", "method", "syncMode", "sync_mode", mode_key)
     if isinstance(mode, str):
         mode_norm = mode.strip().lower()
         if mode_norm in {"waveform", "audio_waveform", "audio_sync_waveform"}:
@@ -5995,7 +6018,8 @@ def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
             mode = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_TIMECODE", mode)
     if mode is not None:
         normalized[mode_key] = mode
-    channel = settings.get("channelNumber", settings.get("channel_number", settings.get("channel", settings.get(channel_key))))
+
+    channel = _pick("channelNumber", "channel_number", "channel", channel_key)
     if isinstance(channel, str):
         channel_norm = channel.strip().lower()
         if channel_norm in {"auto", "automatic"}:
@@ -6004,18 +6028,16 @@ def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
             channel = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_CHANNEL_MIX", -2)
     if channel is not None:
         normalized[channel_key] = channel
-    for source_key, target_key in (
-        ("retainEmbeddedAudio", retain_embedded_key),
-        ("retain_embedded_audio", retain_embedded_key),
-        ("retainVideoMetadata", retain_metadata_key),
-        ("retain_video_metadata", retain_metadata_key),
-    ):
-        if source_key in settings:
-            normalized[target_key] = bool(settings[source_key])
-    for key, value in settings.items():
-        if key not in {"syncBy", "sync_by", "mode", "channelNumber", "channel_number", "channel", "retainEmbeddedAudio", "retain_embedded_audio", "retainVideoMetadata", "retain_video_metadata"}:
-            normalized.setdefault(key, value)
-    return normalized
+
+    retain_embedded = _pick("retainEmbeddedAudio", "retain_embedded_audio")
+    if retain_embedded is not None:
+        normalized[retain_embedded_key] = bool(retain_embedded)
+    retain_metadata = _pick("retainVideoMetadata", "retain_video_metadata")
+    if retain_metadata is not None:
+        normalized[retain_metadata_key] = bool(retain_metadata)
+
+    ignored = sorted(str(key) for key in settings if key not in consumed)
+    return normalized, ignored
 
 
 def _transcription_capabilities(mp, p: Dict[str, Any]):
@@ -7033,6 +7055,11 @@ _MEDIA_ANALYSIS_DEFAULT_PREFS = {
     "sampling_frame_ceiling": 80,
     "preferred_analysis_root": None,
     "preferred_generated_media_folder": None,
+    # Inventory walk tuning. inventory_limit caps how many clips the Media Pool
+    # walk indexes (clamped 1..10000). inventory_exclude_bins is a comma-separated
+    # list of folder names to skip entirely; empty means index every folder.
+    "inventory_limit": 500,
+    "inventory_exclude_bins": "",
     "default_post_operation_page": "stay_put",
     "marker_custom_data": "namespaced",
     "metadata_writeback_default": True,
@@ -7286,6 +7313,12 @@ def _media_analysis_effective_preferences() -> Dict[str, Any]:
     ] or list(_MEDIA_ANALYSIS_DEFAULT_PUBLISH_FIELDS)
     effective["include_confidence_scores"] = _media_analysis_bool(effective.get("include_confidence_scores"), True)
     effective["include_source_time_notes"] = _media_analysis_bool(effective.get("include_source_time_notes"), True)
+    effective["inventory_limit"] = _setup_positive_int(effective.get("inventory_limit"), 500, 1, 10000)
+    effective["inventory_exclude_bins"] = (
+        str(effective.get("inventory_exclude_bins")).strip()
+        if effective.get("inventory_exclude_bins") is not None
+        else ""
+    )
     effective["analysis_summary_style"] = _normalize_setup_choice(
         effective.get("analysis_summary_style"),
         ["full", "concise", "creative", "technical"],
@@ -10983,6 +11016,12 @@ def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run:
         "preferredgeneratedmediafolder": "preferred_generated_media_folder",
         "generated_media_folder": "preferred_generated_media_folder",
         "generatedmediafolder": "preferred_generated_media_folder",
+        "inventory_limit": "inventory_limit",
+        "inventorylimit": "inventory_limit",
+        "inventory_exclude_bins": "inventory_exclude_bins",
+        "inventoryexcludebins": "inventory_exclude_bins",
+        "exclude_bins": "inventory_exclude_bins",
+        "excludebins": "inventory_exclude_bins",
         "default_post_operation_page": "default_post_operation_page",
         "defaultpostoperationpage": "default_post_operation_page",
         "post_operation_page": "default_post_operation_page",
@@ -11205,6 +11244,16 @@ def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run:
             if normalized is None:
                 return _err("Unsupported marker_custom_data. Use namespaced or minimal.")
             set_or_clear(key, raw_value, normalized)
+        elif key == "inventory_limit":
+            try:
+                n = int(raw_value) if not isinstance(raw_value, bool) else 500
+            except (TypeError, ValueError):
+                return _err("inventory_limit must be an integer between 1 and 10000.")
+            set_or_clear(key, raw_value, max(1, min(10000, n)))
+        elif key == "inventory_exclude_bins":
+            # Normalize a comma-separated list of folder names; empty excludes nothing.
+            parts = [part.strip() for part in str(raw_value).split(",") if part.strip()]
+            set_or_clear(key, raw_value, ",".join(parts))
         elif key in {"preferred_analysis_root", "preferred_generated_media_folder"}:
             path = None if clear_requested(raw_value) else os.path.realpath(os.path.abspath(os.path.expanduser(str(raw_value))))
             set_or_clear(key, raw_value, path)
@@ -11449,6 +11498,8 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 "media_analysis.report_format": {"values": ["compact", "full", "machine_readable"], "storage": _media_analysis_preferences_path()},
                 "media_analysis.preferred_analysis_root": {"values": "absolute or expandable path", "storage": _media_analysis_preferences_path()},
                 "media_analysis.preferred_generated_media_folder": {"values": "absolute or expandable path", "storage": _media_analysis_preferences_path()},
+                "media_analysis.inventory_limit": {"description": "Maximum clips indexed during the Media Pool inventory walk.", "values": "integer 1..10000 (default 500)", "storage": _media_analysis_preferences_path()},
+                "media_analysis.inventory_exclude_bins": {"description": "Comma-separated folder names to skip entirely during the inventory walk. Empty indexes every folder.", "values": "comma-separated folder names (default none)", "storage": _media_analysis_preferences_path()},
                 "media_analysis.default_post_operation_page": {"values": ["stay_put", "media", "cut", "edit", "fusion", "color", "fairlight", "deliver"], "storage": _media_analysis_preferences_path()},
                 "media_analysis.marker_custom_data": {"values": ["namespaced", "minimal"], "storage": _media_analysis_preferences_path()},
                 "media_analysis.metadata_writeback_default": {"values": [True, False], "storage": _media_analysis_preferences_path()},
@@ -14770,7 +14821,13 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     elif action == "auto_sync_audio":
         clips = [_find_clip(root, cid) for cid in p["clip_ids"]]
         clips = [c for c in clips if c]
-        return {"success": bool(mp.AutoSyncAudio(clips, p.get("settings", {})))}
+        # Normalize string settings into live AUDIO_SYNC_* enum keys; passing raw
+        # human-readable keys makes AutoSyncAudio silently reject the call.
+        settings, ignored = _normalize_auto_sync_settings(dict(p.get("settings") or {}), get_resolve())
+        result = {"success": bool(mp.AutoSyncAudio(clips, settings))}
+        if ignored:
+            result["ignored_settings"] = ignored
+        return result
     elif action == "get_selected":
         sel = mp.GetSelectedClips()
         if not sel: