davinci-resolve-mcp 2.35.0 → 2.35.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.35.2
+
+Verification observability and a validator consolidation.
+
+- **Added** `resolve_control(action="verification_stats")` returns a
+  process-level tally of readback-verification outcomes
+  (verified / contradicted / unverified) since server start. A rising
+  `contradicted` count means the Resolve API reported success but a readback
+  disagreed. No connection required.
+- **Changed** `open_page` now validates its `page` argument through the declarative
+  contract layer (`contracts.validate`) instead of a hand-written enum check —
+  behavior unchanged; part of folding scattered validation into one place.
+
+## What's New in v2.35.1
+
+- **Added** `media_pool_item(action="extract_frames", clip_id, timestamps, output_dir?)`
+  extracts still JPEGs from a clip's source media at the given timestamps (seconds)
+  via ffmpeg. Source-safe: it reads the source and writes only to a scratch output
+  directory — it never modifies, transcodes, or proxies the source. (Closes a
+  read/write-symmetry gap: the analysis sampler existed internally but had no
+  standalone frame-extraction tool.)
+
 ## What's New in v2.35.0
 
 The Cut-IR executor — transcript-driven editing now closes the loop onto the

package/README.md

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

package/docs/SKILL.md

@@ -320,6 +320,8 @@ Key actions:
 - `get_version` — returns `{product, version, version_string}`
 - `api_truth(query?)` — look up behaviorally-verified facts about quirky/unreliable
   Resolve API behavior (no connection needed); filter by substring
+- `verification_stats` — readback-verification tally (verified/contradicted/
+  unverified) since server start (no connection needed)
 - `get_page` / `open_page(page)` — read or switch the active page
 - `get_keyframe_mode` / `set_keyframe_mode(mode)`
 - `get_fairlight_presets` — Resolve 20.2.2+; returns available Fairlight

package/install.py

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

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.35.0"
+VERSION = "2.35.2"
 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.35.0"
+VERSION = "2.35.2"
 
 import base64
 import os
@@ -48,7 +48,7 @@ from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import open_page_serialized as _open_page_serialized
 from src.utils.proc import safe_run
-from src.utils.readback import verify_by_readback
+from src.utils.readback import verify_by_readback, verification_stats as _verification_stats
 from src.utils.update_check import (
     check_for_updates,
     clear_update_prompt_preferences,
@@ -5510,6 +5510,55 @@ def _audio_mapping_report(mp, tl, p: Dict[str, Any]):
     return {"timeline_items": timeline_items, "media_pool_items": clip_rows}
 
 
+def _extract_clip_frames(clip, p: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract still frames from a clip's source media at given timestamps.
+
+    Source-safe: reads the source file with ffmpeg and writes JPEGs to a scratch
+    output directory only — it never modifies, transcodes, or proxies the source.
+    `timestamps` is a list of seconds. Returns the written frame paths.
+    """
+    try:
+        src = clip.GetClipProperty("File Path")
+    except Exception:
+        src = None
+    if not src or not os.path.isfile(src):
+        return _err("Clip has no readable source file (File Path)")
+    timestamps = p.get("timestamps")
+    if not isinstance(timestamps, list) or not timestamps:
+        return _err("extract_frames requires 'timestamps' (a non-empty list of seconds)")
+    if not shutil.which("ffmpeg"):
+        return _err("ffmpeg not found on PATH")
+    out_dir = p.get("output_dir") or tempfile.mkdtemp(prefix="mcp_frames_")
+    try:
+        os.makedirs(out_dir, exist_ok=True)
+    except OSError as exc:
+        return _err(f"Could not create output_dir: {exc}")
+    paths, errors = [], []
+    for i, ts in enumerate(timestamps):
+        out_path = os.path.join(out_dir, f"frame_{i:04d}.jpg")
+        try:
+            safe_run(
+                ["ffmpeg", "-y", "-ss", str(float(ts)), "-i", src,
+                 "-frames:v", "1", "-q:v", "2", out_path],
+                capture_output=True, timeout=60,
+            )
+        except (OSError, subprocess.SubprocessError, ValueError) as exc:
+            errors.append({"timestamp": ts, "error": str(exc)})
+            continue
+        if os.path.isfile(out_path):
+            paths.append(out_path)
+        else:
+            errors.append({"timestamp": ts, "error": "no frame written (timestamp out of range?)"})
+    return {
+        "success": bool(paths),
+        "source": src,
+        "output_dir": out_dir,
+        "frame_paths": paths,
+        "count": len(paths),
+        "errors": errors,
+    }
+
+
 def _clip_name(clip):
     try:
         return clip.GetName()
@@ -10583,6 +10632,8 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       clear_mcp_update_preferences() -> {success, version, update, decision}
       api_truth(query?) -> {verified_on, count, facts}  — look up behaviorally-verified
         facts about quirky/unreliable Resolve API behavior (no connection needed).
+      verification_stats() -> {stats}  — readback-verification tally
+        (verified/contradicted/unverified) since server start (no connection needed).
       get_page() -> {page}
       open_page(page) -> {success}  — page: edit, cut, color, fusion, fairlight, deliver
       get_keyframe_mode() -> {mode}
@@ -10607,6 +10658,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     if action == "api_truth":
         facts = lookup_api_truth(p.get("query"))
         return {"verified_on": _API_TRUTH_VERIFIED_ON, "count": len(facts), "facts": facts}
+    if action == "verification_stats":
+        # Process-level readback-verification tally — no connection needed.
+        stats = _verification_stats()
+        return {"stats": stats, "note": "Counts since server start. A rising "
+                "'contradicted' count means the API reported success but a readback disagreed."}
 
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
@@ -10671,12 +10727,15 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_page":
         return {"page": r.GetCurrentPage()}
     elif action == "open_page":
-        valid_pages = ["media", "cut", "edit", "color", "fusion", "fairlight", "deliver"]
-        if p["page"] not in valid_pages:
-            return _err(f"Invalid page '{p['page']}'. Valid pages: {', '.join(valid_pages)}")
+        err, clean = _validate_params(p, {
+            "page": {"enum": ["media", "cut", "edit", "color", "fusion", "fairlight", "deliver"],
+                     "required": True},
+        })
+        if err:
+            return _err(err)
         # Serialize page switches so concurrent agents can't flip the single
         # globally-active page underneath each other.
-        return {"success": bool(_open_page_serialized(r, p["page"]))}
+        return {"success": bool(_open_page_serialized(r, clean["page"]))}
     elif action == "get_keyframe_mode":
         return {"mode": r.GetKeyframeMode()}
     elif action == "set_keyframe_mode":
@@ -10697,7 +10756,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return missing
         r.DisableBackgroundTasksForCurrentResolveSession()
         return _ok()
-    return _unknown(action, ["launch","get_version","api_truth","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","get_version","api_truth","verification_stats","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────
@@ -13797,6 +13856,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       get_transcription(clip_id) -> {text, truncated, status, has_transcription}
         Read a clip's transcription. `truncated` flags when Resolve's preview
         property cut the text off (the full transcript is longer).
+      extract_frames(clip_id, timestamps, output_dir?) -> {frame_paths, output_dir, count, errors}
+        Extract still JPEGs from the clip's source at the given timestamps (seconds)
+        via ffmpeg. Source-safe: reads source, writes only to a scratch dir.
       perform_audio_classification(clip_id) -> {success}  — Resolve 21+
       clear_audio_classification(clip_id) -> {success}  — Resolve 21+
       analyze_for_intellisearch(clip_id, identify_faces?, is_better_mode?) -> {success}  — Resolve 21+, AI IntelliSearch Extra
@@ -14012,6 +14074,8 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             "status": status or None,
             "has_transcription": bool(text.strip()),
         }
+    elif action == "extract_frames":
+        return _extract_clip_frames(clip, p)
     elif action == "perform_audio_classification":
         missing = _requires_method(clip, "PerformAudioClassification", "21.0")
         if missing:
@@ -14096,7 +14160,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"success": bool(clip.SetMarkInOut(clean["mark_in"], clean["mark_out"], p.get("type", "all")))}
     elif action == "clear_mark_in_out":
         return {"success": bool(clip.ClearMarkInOut(p.get("type", "all")))}
-    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer"])
+    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","extract_frames","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/readback.py

@@ -16,6 +16,21 @@ from typing import Any, Callable, Dict, Optional
 
 logger = logging.getLogger("davinci-resolve-mcp")
 
+# Process-level tally of verification outcomes — lightweight observability into
+# how often the Resolve API's self-reported success matches reality. A rising
+# `contradicted` count is the signal worth watching.
+_STATS = {"total": 0, "verified": 0, "contradicted": 0, "unverified": 0}
+
+
+def verification_stats():
+    """Return a copy of the process-level verification tally."""
+    return dict(_STATS)
+
+
+def reset_verification_stats():
+    for k in _STATS:
+        _STATS[k] = 0
+
 
 def verify_by_readback(
     mutate: Callable[[], Any],
@@ -56,6 +71,7 @@ def verify_by_readback(
 
     # A contradiction — reported success but the readback disagrees — is the
     # signal worth surfacing loudly.
+    _STATS["total"] += 1
     if result.get("success_raw") and not result.get("verified"):
         logger.warning(
             "readback contradiction%s: API reported success but post-state "
@@ -64,7 +80,12 @@ def verify_by_readback(
             f" (intent={intent})" if intent else "",
         )
         result["contradiction"] = True
+        _STATS["contradicted"] += 1
     else:
         result["contradiction"] = False
+        if result.get("verified"):
+            _STATS["verified"] += 1
+        else:
+            _STATS["unverified"] += 1
 
     return result