davinci-resolve-mcp 4.7.11 → 4.8.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 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.8.0 — one read before planning: `project_manager snapshot`
+
+### Added
+
+- **`project_manager(action="snapshot")`** — a read-only readout of the state an agent
+  inspects before it plans an edit. ([#251](https://github.com/samuelgursky/davinci-resolve-mcp/pull/251), @tpellet)
+  Returns `project`, `timeline` (per-track items), `gaps_overlaps`, `render`
+  (`is_rendering` plus each job's status) and `media_pool` counts in one call, instead
+  of `get_current` + `timeline.get_current` + `probe_timeline_structure` +
+  `detect_gaps_overlaps` + `render.is_rendering` one LLM turn at a time. The
+  motivation is measured: in 8,407 mined agent tool turns from one real project,
+  2,222 were state inspection. It composes the existing helpers, so the values match
+  what those actions already return, and it never switches page, timeline or folder.
+  - `include` picks sections; an unknown name or an empty list is refused rather than
+    widened to everything. `item_limit` (default 200) caps the items returned across
+    tracks and sets `timeline.items_truncated`, while `item_count` and
+    `gaps_overlaps` still cover the whole timeline. A failing section reports
+    `{error}` in its own place; the others still return.
+  - It saves turns and response size, not read time: the timeline sections cost what
+    `probe_timeline_structure` costs and `media_pool` walks every pool clip, so on a
+    large project pass `include` with only the sections you need. `docs/SKILL.md` says
+    so.
+  - Tested against stubs only (16 tests, including parity with the actions it replaces
+    and a sixty-item readout kept under 16 KB); not yet run against a live Resolve.
+
+### Fixed
+
+- **The risk classifier now recognises `project_manager.snapshot` as a LOW read.** Its
+  name carries no read verb, so on the contributed branch it fell to the name-based
+  MEDIUM default with a "risk unestablished" reason on every call — noise on the one
+  read an agent makes before planning. Safe mode would not have blocked it (only an
+  established HIGH/CRITICAL is), but a pure read should not carry that. Explicit
+  verbless reads now live in `RiskClassificationHook._READ_ONLY_PAIRS` beside
+  `dctl.validate_native`; guard test `tests/test_snapshot_read_rule.py` also pins that
+  the table does not widen into a wildcard.
+
 ## What's New in v4.7.11 — `allow_partial_item_delete="false"` no longer lets a range delete take whole clips
 
 ### Fixed

package/README.md

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

package/docs/SKILL.md

@@ -821,6 +821,19 @@ Key actions: `list`, `list_attributes`, `get_current`,
 `notes`, and `liveCollaborationMode` per project in the current folder without
 loading any of them.
 
+`snapshot(include?, track_types?, item_limit?)` is the one read to make before
+planning: `project`, `timeline` (per-track items), `gaps_overlaps`, `render`
+(`is_rendering` plus each job's status) and `media_pool` counts in a single
+read-only call, instead of `get_current` + `timeline.get_current` +
+`probe_timeline_structure` + `detect_gaps_overlaps` + `render.is_rendering` one
+turn at a time. `include` picks sections, `item_limit` (default 200) caps the
+items returned and sets `timeline.items_truncated`, and a section that fails
+reports `{error}` in its own place. It saves turns and response size, not read
+time: the timeline sections cost what `probe_timeline_structure` costs and
+`media_pool` walks every pool clip, so on a large project pass `include` with
+only the sections you need. Frame fields are `probe_timeline_structure`'s,
+unchanged.
+
 Project / Database / Archive kernel actions (v2.15.0+) add guarded project
 lifecycle, settings, database, preset, and archive boundary helpers:
 

package/install.py

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

package/src/granular/common.py

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.7.11"
+VERSION = "4.8.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.7.11"
+VERSION = "4.8.0"
 
 import base64
 import os
@@ -19077,6 +19077,124 @@ def _project_lint_live(r, pm) -> Dict[str, Any]:
     return _ok(**_project_lint.lint_report(state))
 
 
+_SNAPSHOT_SECTIONS = ["project", "timeline", "gaps_overlaps", "render", "media_pool"]
+
+# The per-item fields a planning read needs. probe_timeline_structure carries
+# the rest (file path, media status, seconds, clip properties) for a caller
+# that wants them; repeating them here is what makes a 60-item readout too big
+# to be the first call of every turn.
+_SNAPSHOT_ITEM_FIELDS = (
+    "item_index", "timeline_item_id", "name", "start", "end",
+    "source_start", "source_end", "source_fps", "media_pool_item_id",
+)
+
+
+def _project_state_snapshot(r, proj, p: Dict[str, Any]) -> Dict[str, Any]:
+    """One read-only readout of the state an agent inspects before planning.
+
+    Composes the helpers behind project_summary, probe_timeline_structure,
+    detect_gaps_overlaps and the render status actions, so the numbers match
+    what those actions return. Each section fails on its own: an exception is
+    reported as that section's {"error"}, never as a whole-call failure.
+    """
+    include = p.get("include")
+    if include is None:
+        include = list(_SNAPSHOT_SECTIONS)
+    # An empty include is refused: falling back to every section would hand a
+    # caller that filtered down to nothing the most expensive read instead.
+    if not isinstance(include, list) or not include:
+        return _err("include must be a non-empty list", category="invalid_input")
+    unknown = [name for name in include if name not in _SNAPSHOT_SECTIONS]
+    if unknown:
+        return _err(
+            f"Unknown snapshot section(s): {unknown}",
+            code="UNKNOWN_SECTION", category="invalid_input",
+            state={"unknown": unknown, "supported": list(_SNAPSHOT_SECTIONS)},
+        )
+    track_types = p.get("track_types")
+    if track_types is not None and not isinstance(track_types, list):
+        return _err("track_types must be a list", category="invalid_input")
+    try:
+        item_limit = int(p.get("item_limit", 200))
+    except (TypeError, ValueError):
+        return _err("item_limit must be an integer", category="invalid_input")
+    if item_limit < 0:
+        return _err("item_limit must be 0 or greater", category="invalid_input")
+
+    out: Dict[str, Any] = {}
+
+    if "project" in include:
+        try:
+            section = _project_object_summary(proj) or {}
+            section["current_page"] = r.GetCurrentPage()
+            section["timeline_count"] = proj.GetTimelineCount()
+            section["settings"] = {
+                key: _ser(proj.GetSetting(key))
+                for key in ("timelineFrameRate", "timelineResolutionWidth", "timelineResolutionHeight")
+            }
+            out["project"] = section
+        except Exception as exc:
+            out["project"] = {"error": str(exc)}
+
+    if "timeline" in include or "gaps_overlaps" in include:
+        wanted = [name for name in ("timeline", "gaps_overlaps") if name in include]
+        try:
+            tl = proj.GetCurrentTimeline()
+            if not tl:
+                for name in wanted:
+                    out[name] = {"available": False, "error": "No current timeline"}
+            else:
+                snapshot = _timeline_conform_snapshot(
+                    tl, {"track_types": track_types, "include_markers": False})
+                # Gaps are measured on the whole snapshot, before item_limit
+                # trims what is returned.
+                gaps_overlaps = _detect_gaps_overlaps_from_snapshot(
+                    snapshot, {"track_types": track_types})
+                if "timeline" in include:
+                    snapshot.pop("markers", None)
+                    try:
+                        snapshot["fps"] = float(tl.GetSetting("timelineFrameRate"))
+                    except Exception:
+                        snapshot["fps"] = None
+                    remaining = item_limit
+                    for type_payload in snapshot["tracks"].values():
+                        for track in type_payload["tracks"]:
+                            kept = track["items"][:remaining]
+                            remaining -= len(kept)
+                            track["items"] = [
+                                {field: item.get(field) for field in _SNAPSHOT_ITEM_FIELDS}
+                                for item in kept
+                            ]
+                    snapshot["items_returned"] = item_limit - remaining
+                    snapshot["items_truncated"] = snapshot["items_returned"] < snapshot["item_count"]
+                    out["timeline"] = snapshot
+                if "gaps_overlaps" in include:
+                    out["gaps_overlaps"] = gaps_overlaps
+        except Exception as exc:
+            for name in wanted:
+                out.setdefault(name, {"error": str(exc)})
+
+    if "render" in include:
+        try:
+            jobs = []
+            for job in (proj.GetRenderJobList() or []):
+                row = _ser(job)
+                if isinstance(row, dict) and row.get("JobId"):
+                    row["status"] = _ser(proj.GetRenderJobStatus(row["JobId"]))
+                jobs.append(row)
+            out["render"] = {"is_rendering": bool(proj.IsRenderingInProgress()), "jobs": jobs}
+        except Exception as exc:
+            out["render"] = {"error": str(exc)}
+
+    if "media_pool" in include:
+        try:
+            out["media_pool"] = _project_summary(proj)["media_pool"]
+        except Exception as exc:
+            out["media_pool"] = {"error": str(exc)}
+
+    return out
+
+
 @mcp.tool()
 @_guard_missing_params
 @_destructive_op("project_manager")
@@ -19089,6 +19207,19 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — Resolve 21.0.4+. Per-project attributes for the current folder without
           loading any project.
       get_current() -> {name, id}
+      snapshot(include?, track_types?, item_limit?) -> {project, timeline, gaps_overlaps, render, media_pool}
+        One read-only readout of what an agent inspects before planning; it never
+        switches page, timeline or folder. include picks sections (default all);
+        item_limit caps the items returned across tracks (default 200) and sets
+        timeline.items_truncated, while item_count and gaps_overlaps still cover
+        the whole timeline. item_limit bounds the response, not the read: the
+        timeline sections cost what probe_timeline_structure costs (they scale
+        with item_count) and media_pool walks every pool clip, so on a large
+        project leave out the sections you do not need. A section that fails
+        reports {error} in its own place; an empty include is refused. Frame
+        fields are probe_timeline_structure's, unchanged: start/end
+        are TimelineItem GetStart/GetEnd record frames; source_start/source_end
+        are file-relative frames at source_fps, source_end exclusive.
       create(name, media_location_path?) -> {success, name}
       load(name) -> {success}
       save() -> {success}
@@ -19181,6 +19312,11 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_current":
         proj = pm.GetCurrentProject()
         return {"name": proj.GetName(), "id": proj.GetUniqueId()} if proj else _err("No project open")
+    elif action == "snapshot":
+        proj = pm.GetCurrentProject()
+        if not proj:
+            return _err("No project open")
+        return _project_state_snapshot(r, proj, p)
     elif action == "create":
         if not p.get("name"):
             return _err("create requires name")
@@ -19280,7 +19416,7 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if not p.get("path"):
             return _err("restore requires path")
         return {"success": bool(pm.RestoreProject(p["path"], p.get("name")))}
-    return _unknown(action, ["list","list_attributes","get_current","create","load","save","close","delete","import_project","export_project","archive","restore","lint","diff_to_spec","plan_spec","apply_spec", *_PROJECT_KERNEL_ACTIONS])
+    return _unknown(action, ["list","list_attributes","get_current","snapshot","create","load","save","close","delete","import_project","export_project","archive","restore","lint","diff_to_spec","plan_spec","apply_spec", *_PROJECT_KERNEL_ACTIONS])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/execution_lifecycle.py

@@ -378,6 +378,14 @@ class RiskClassificationHook(LifecycleHook):
         return BlastRadius.TIMELINE, "the timeline node graph (every clip on the timeline)"
 
     _READ_ONLY_PREFIXES = ("get_", "list_", "query_", "probe_", "inspect_", "export_", "check_")
+    #: Reads whose action name carries no read verb. Without an entry here a
+    #: pure read falls to the name-based MEDIUM default and every call reports
+    #: "risk unestablished" — noise on the one call an agent makes before
+    #: planning (project_manager.snapshot, #251).
+    _READ_ONLY_PAIRS = frozenset({
+        ("dctl", "validate_native"),
+        ("project_manager", "snapshot"),
+    })
 
     @classmethod
     def classify(cls, tool_name: str, action: str, params: Dict[str, Any]) -> RiskAssessment:
@@ -448,7 +456,7 @@ class RiskClassificationHook(LifecycleHook):
                 else BlastRadius.ITEM
             )
             reasons.append(f"Recoverable edit to existing state: {action}")
-        elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"} or pair == ("dctl", "validate_native"):
+        elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"} or pair in cls._READ_ONLY_PAIRS:
             level = RiskLevel.LOW
             destructive = False
             radius = BlastRadius.ITEM