davinci-resolve-mcp 2.76.0 → 2.77.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 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.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.77.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.77.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.77.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.76.0"
+VERSION = "2.77.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.77.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 []