davinci-resolve-mcp 2.40.0 → 2.42.0

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 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.42.0
+
+Deep shot-level vision tier — Phase B of the analysis + edit-engine program.
+Opt-in, estimate-first per-shot field filling for the Visual / Content /
+Production / Editorial / Cuttability groups the shot pages already render.
+
+- **Added** `src/utils/deep_vision.py` and three `media_analysis` actions:
+  `deepen` (estimate → confirm_token → deferred host-vision payload per
+  clip/shot), `commit_shot_vision` (writes `vision_deep_v1` provenance rows,
+  updates the canonical blob, re-exports analysis.json in lockstep), and
+  `vision_pending_sweep` (lists clips stuck in `pending_host_analysis`;
+  `reoffer=true` returns the stored payload, `expire=true` stamps them).
+- **Added** deep depth to the analyze flow: `depth="deep"` extends the
+  deferred payload with the per-shot schema and requires `confirm_deep=true`
+  after a token-cost estimate. Caps pre-call refusal applies on both paths.
+- **Added** panel affordances: `Deepen analysis` (clip view) and `Deepen this
+  shot` (shot view) copy ready-made chat prompts, per the chat-first UX.
+  Shots with no sampled frames on disk get 1–2 frames re-extracted via
+  ffmpeg, downscaled per caps (source media stays read-only).
+- **Fixed** a provenance bug in the analysis store: a source re-deriving an
+  unchanged value no longer re-attributes the row (a deep pass would
+  otherwise claim every untouched field as `vision_deep_v1`).
+- **Validation**: full offline suite (1081 tests; 15 new), and a real
+  end-to-end deep pass on the 2026-05-17 sample clip — estimate → confirm →
+  frames read by the host chat → commit → rows/blob/export parity → fields
+  visible in the panel shot view. Control-panel guide screenshots
+  regenerated from the live panel.
+
+## What's New in v2.41.0
+
+DB-canonical clip analysis (C1) — Phase A of the analysis + edit-engine
+program. The per-project SQLite DB is now the source of truth for clip
+analysis; `analysis.json` becomes a derived export written in lockstep.
+
+- **Added** schema v9 to the per-project timeline-brain DB: `clips`,
+  `clip_aliases`, `analysis_reports` (canonical full payload), `shots`,
+  `subjective_fields` + `field_changelog` (per-field provenance),
+  `transcript_segments`, `frames`, and `qc_observations`.
+- **Added** `src/utils/analysis_store.py`: transactional ingest, export with
+  human-correction overlay (human rows always win and survive re-analysis),
+  alias-based clip lookup, shot ids stable under one-second boundary jitter,
+  and a round-trip guard verified against a real sample analysis root.
+- **Added** `media_analysis` actions `db_status` (schema version + row
+  counts) and `db_ingest` (one-shot migration of existing JSON reports and
+  `corrections.json` sidecars into the DB).
+- **Changed** the analysis write path: `execute_plan` and `commit_vision`
+  write DB rows first, then export the JSON. Panel clip/shot endpoints read
+  DB-first with JSON fallback for pre-v9 reports and job-linked report dirs.
+- **Changed** `update_clip_field` / `update_shot_field` / `revert_field` to
+  mirror corrections into the DB as row-level provenance (the
+  `corrections.json` sidecar remains for compatibility).
+- **Fixed** eight V2 actions that were unreachable from MCP dispatch since
+  v2.24.0 (`get_panel_state`, `set_panel_state`, `session_start_context`,
+  `update_shot_field`, `update_clip_field`, `get_field_history`,
+  `revert_field`, `list_corrections`): they were checked inside the
+  project-root dispatch block but missing from its membership set. The
+  control panel proxied to the helpers directly, which masked it.
+- **Fixed** the action-list drift guard to inspect async tool functions
+  (media_analysis had drifted unchecked) and to fail on actions that are
+  unreachable inside membership blocks — the exact class above. Four
+  reachable-but-unadvertised actions (`coverage_report`,
+  `get_resolve_ai_usage`, `get_ai_governance`, `set_ai_governance`) are now
+  listed in the unknown-action error.
+- **Validation**: full offline suite (1066 tests; 12 new), round-trip guard
+  on the real 2026-05-17 sample root, and a live headless pipeline run on
+  synthetic media verifying rows-then-export parity, row-level corrections,
+  and DB-first panel reads.
+
 ## What's New in v2.40.0
 
 Control panel UX overhaul + docs refresh, from a full live audit of every

package/README.md

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

package/docs/SKILL.md

@@ -491,8 +491,45 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `publish_clip_metadata`, `commit_vision`, `summarize`, `get_report`,
 `build_index`, `index_status`, `query_index`, `start_batch_job`,
 `run_batch_job_slice`, `batch_job_status`, `list_batch_jobs`,
-`cancel_batch_job`, `resume_batch_job`, `review_timeline_markers`, and
-`cleanup_artifacts`.
+`cancel_batch_job`, `resume_batch_job`, `review_timeline_markers`,
+`cleanup_artifacts`, `db_status`, `db_ingest`, `get_panel_state`,
+`set_panel_state`, `session_start_context`, `update_clip_field`,
+`update_shot_field`, `get_field_history`, `revert_field`,
+`list_corrections`, `deepen`, `commit_shot_vision`, and
+`vision_pending_sweep`.
+
+**Deep shot-level vision tier (v2.42.0+).** Opt-in, estimate-first. Two
+entry points share one per-shot schema (Visual / Content / Production /
+Editorial / Cuttability / description / confidence):
+- `depth="deep"` on any analyze action extends the deferred host-vision
+  payload with `deep_shot_schema`; each `shot_descriptions` entry must carry
+  the field groups. The first deep run returns `confirmation_required` with
+  a token-cost estimate — re-call with `confirm_deep=true`. Caps still apply.
+- `deepen(clip_id|clip_dir, shot_index?|shot_indices?)` runs the pass
+  post-hoc on an already-analyzed clip. First call returns the estimate +
+  `confirm_token`; re-call with the token to get the deferred payload, read
+  its `frame_paths`, and commit via
+  `commit_shot_vision(clip_id, shots=[{shot_index, ...groups...}],
+  vision_token)`. Deep fields land as `vision_deep_v1` provenance rows;
+  human corrections always survive. Shots with no sampled frames on disk get
+  1–2 frames re-extracted via ffmpeg (read-only on source media).
+`vision_pending_sweep(expire?, max_age_days?, reoffer?)` lists clips stuck
+in `pending_host_analysis`; `reoffer=true` returns each clip's stored
+deferred payload to finish the run, `expire=true` stamps them
+`expired_host_analysis` so pendings never linger silently.
+
+**DB-canonical analysis store (v2.41.0+).** The per-project SQLite DB
+(`_soul/timeline_brain.sqlite`, schema v9+) is the source of truth for clip
+analysis; `analysis.json` is a derived export written in lockstep. Analysis
+runs write rows first (clips, shots, per-field subjective provenance,
+transcript segments, sampled frames, QC observations) and then export the
+JSON. Human corrections recorded via `update_clip_field` / `update_shot_field`
+live as row-level provenance and always survive re-analysis. Readers
+(panel API, exports) load DB-first and fall back to `analysis.json` for
+reports that predate v9. `db_status` reports schema version + row counts;
+`db_ingest` migrates an existing project's JSON reports (and
+`corrections.json` sidecars) into the DB — run it once on older analysis
+roots.
 The tool never installs
 dependencies and validates that outputs stay under
 `davinci-resolve-mcp-analysis` project roots rather than beside source media.

package/docs/guides/control-panel.md

@@ -86,7 +86,10 @@ transcripts once the search index is built.
 
 The clip view shows the full summary, tags, star rating, editorial notes, and
 a contact sheet of every detected shot. From here you can open the clip in
-Resolve, jump to the transcript, or click into any shot.
+Resolve, jump to the transcript, or click into any shot. `Deepen analysis`
+copies a ready-made chat prompt that asks your MCP session to run the opt-in
+deep shot pass (cost estimate first, then per-shot Visual / Content /
+Editorial / Cuttability fields).
 
 ### Transcript
 
@@ -107,7 +110,9 @@ start", "After cut", "Flash frame", "Motion peak"). Subjective fields are
 editable inline; edits are kept with the clip's analysis and merged on top of
 future re-analysis so human notes survive fresh vision runs. `Open in Resolve`
 jumps straight to the clip in the source viewer with the shot's mark in/out
-set.
+set. The field groups (Visual, Content, Production, Editorial, Cuttability)
+are filled by the opt-in deep vision pass — `Deepen this shot` copies a chat
+prompt that runs it for just this shot, estimate first.
 
 ### Media → History
 

package/install.py

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

package/src/analysis_dashboard.py

@@ -8390,7 +8390,7 @@ HTML = r"""<!doctype html>
         <span class="meta">${formatDuration(card.duration_seconds)} · ${shots.length} shots</span>
         ${cls.primary_use ? `<span class="review-chip">${escapeHtml(cls.primary_use)}</span>` : ''}
         ${cls.select_potential ? `<span class="review-chip ${selectChipClass(cls.select_potential)}">${escapeHtml(cls.select_potential)}</span>` : ''}
-        <div class="actions"><button class="secondary" id="reviewClipTranscriptBtn">Transcript</button><button class="secondary" id="reviewClipOpenInResolveBtn">Open in Resolve</button></div>
+        <div class="actions"><button class="secondary" id="reviewClipTranscriptBtn">Transcript</button><button class="secondary" id="reviewClipOpenInResolveBtn">Open in Resolve</button><button class="secondary" data-copy-chat-prompt="${escapeHtml(`Deepen the analysis of clip “${card.clip_name || state.review.currentClipId}”: call media_analysis(action="deepen", params={"clip_id": "${card.clip_id || state.review.currentClipId}"}), show me the cost estimate, and after I confirm, read the frames and commit the per-shot fields via commit_shot_vision.`)}">Deepen analysis</button></div>
       `;
       $('reviewClipSummary').textContent = data.clip_summary || data.clip_summary_oneliner || '';
       $('reviewClipTags').innerHTML = tags.map(t => `<span class="review-chip">${escapeHtml(t)}</span>`).join('');
@@ -9440,6 +9440,7 @@ HTML = r"""<!doctype html>
         <span class="meta">${escapeHtml(shot.description || '')}</span>
         <div class="actions">
           <button class="secondary" id="reviewShotOpenInResolveBtn">Open in Resolve</button>
+          <button class="secondary" data-copy-chat-prompt="${escapeHtml(`Deepen shot ${shotIndex} of clip “${(state.review.currentClipData && state.review.currentClipData.card && state.review.currentClipData.card.clip_name) || clipId}”: call media_analysis(action="deepen", params={"clip_id": "${clipId}", "shot_index": ${shotIndex}}), show me the cost estimate, and after I confirm, read the frames and commit the per-shot fields via commit_shot_vision.`)}">Deepen this shot</button>
           <button id="reviewShotEditToggleBtn" ${editing ? '' : 'class="secondary"'}>${editToggleLabel}</button>
         </div>
       `;
@@ -12450,6 +12451,25 @@ def _v2_load_analysis(clip_dir: str) -> Optional[Dict[str, Any]]:
         return None
 
 
+def _v2_load_analysis_db_first(project_root: str, clip_dir: str) -> Optional[Dict[str, Any]]:
+    """C1 — DB-canonical reader with JSON fallback.
+
+    Falls back to analysis.json for reports that predate schema v9 and for
+    job-linked report dirs whose rows live under another project's DB.
+    """
+    try:
+        from src.utils import analysis_store
+
+        report = analysis_store.load_db_report(
+            project_root, clip_dir=os.path.basename(clip_dir.rstrip("/\\"))
+        )
+        if report is not None:
+            return report
+    except Exception:
+        pass
+    return _v2_load_analysis(clip_dir)
+
+
 def _v2_clip_duration(report: Dict[str, Any]) -> Optional[float]:
     marker_plan = report.get("clip_analysis_markers") if isinstance(report.get("clip_analysis_markers"), dict) else {}
     duration = marker_plan.get("duration_seconds")
@@ -12530,7 +12550,7 @@ def list_analyzed_clips(project_root: str) -> Dict[str, Any]:
     """List analyzed clips for the bin grid. One row per analysis.json found."""
     rows: List[Dict[str, Any]] = []
     for slug, clip_dir in _v2_iter_analysis_dirs(project_root):
-        report = _v2_load_analysis(clip_dir)
+        report = _v2_load_analysis_db_first(project_root, clip_dir)
         if report is None:
             continue
         rows.append(_v2_clip_summary_card(slug, clip_dir, report))
@@ -12561,7 +12581,7 @@ def get_analyzed_clip(project_root: str, clip_id: str) -> Dict[str, Any]:
     clip_dir = _v2_find_clip_dir(project_root, clip_id)
     if not clip_dir:
         return {"success": False, "error": f"No analyzed clip found for id={clip_id}"}
-    report = _v2_load_analysis(clip_dir)
+    report = _v2_load_analysis_db_first(project_root, clip_dir)
     if report is None:
         return {"success": False, "error": "analysis.json unreadable"}
     visual = report.get("visual") if isinstance(report.get("visual"), dict) else {}
@@ -12598,7 +12618,7 @@ def get_analyzed_clip_shots(project_root: str, clip_id: str) -> Dict[str, Any]:
     clip_dir = _v2_find_clip_dir(project_root, clip_id)
     if not clip_dir:
         return {"success": False, "error": f"No analyzed clip found for id={clip_id}"}
-    report = _v2_load_analysis(clip_dir)
+    report = _v2_load_analysis_db_first(project_root, clip_dir)
     if report is None:
         return {"success": False, "error": "analysis.json unreadable"}
     visual = report.get("visual") if isinstance(report.get("visual"), dict) else {}
@@ -12615,7 +12635,7 @@ def get_analyzed_clip_shot(project_root: str, clip_id: str, shot_index: int) ->
     clip_dir = _v2_find_clip_dir(project_root, clip_id)
     if not clip_dir:
         return {"success": False, "error": f"No analyzed clip found for id={clip_id}"}
-    report = _v2_load_analysis(clip_dir)
+    report = _v2_load_analysis_db_first(project_root, clip_dir)
     if report is None:
         return {"success": False, "error": "analysis.json unreadable"}
     visual = report.get("visual") if isinstance(report.get("visual"), dict) else {}

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.40.0"
+VERSION = "2.42.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.40.0"
+VERSION = "2.42.0"
 
 import base64
 import os
@@ -11215,6 +11215,25 @@ def _v2_update_field(project_root: str, p: Dict[str, Any], *, entity_type: str)
     write_result = _v2_write_corrections(path, data)
     if not write_result.get("success"):
         return write_result
+    # C1 — mirror the correction into the DB-canonical store (row-level
+    # provenance). Best-effort: the sidecar remains authoritative for projects
+    # whose DB predates v9 or lacks ingested rows.
+    db_result: Dict[str, Any]
+    try:
+        from src.utils import analysis_store
+        db_result = analysis_store.record_human_correction(
+            project_root,
+            clip_ref=clip_id or os.path.basename(os.path.dirname(path)),
+            entity_type=entity_type,
+            entity_uuid=entity_uuid,
+            field_path=field_path,
+            value=new_value,
+            author=author,
+            reason=reason,
+            confidence=str(confidence) if confidence else None,
+        )
+    except Exception as exc:  # noqa: BLE001 — DB mirror must not break corrections
+        db_result = {"success": False, "error": f"{type(exc).__name__}: {exc}"}
     return {
         "success": True,
         "entity_type": entity_type,
@@ -11225,6 +11244,7 @@ def _v2_update_field(project_root: str, p: Dict[str, Any], *, entity_type: str)
         "author": author,
         "timestamp": now,
         "corrections_path": path,
+        "db": db_result,
     }
 
 
@@ -11307,6 +11327,35 @@ def _v2_revert_field(project_root: str, p: Dict[str, Any]) -> Dict[str, Any]:
     write_result = _v2_write_corrections(path, data)
     if not write_result.get("success"):
         return write_result
+    # C1 — mirror the revert into the DB-canonical store. A revert back to a
+    # human value re-records it; a revert to machine-derived clears the human
+    # row so the export overlay falls back to the blob value.
+    db_result: Dict[str, Any]
+    try:
+        from src.utils import analysis_store
+        clip_ref = clip_id or os.path.basename(os.path.dirname(path))
+        if action_taken == "removed (back to machine-derived)" or revert_source != "human":
+            db_result = analysis_store.clear_human_field(
+                project_root,
+                clip_ref=clip_ref,
+                entity_type=entity_type,
+                entity_uuid=entity_uuid,
+                field_path=field_path,
+                author=author,
+            )
+        else:
+            db_result = analysis_store.record_human_correction(
+                project_root,
+                clip_ref=clip_ref,
+                entity_type=entity_type,
+                entity_uuid=entity_uuid,
+                field_path=field_path,
+                value=revert_to,
+                author=author,
+                reason=f"revert by {author}",
+            )
+    except Exception as exc:  # noqa: BLE001 — DB mirror must not break corrections
+        db_result = {"success": False, "error": f"{type(exc).__name__}: {exc}"}
     return {
         "success": True,
         "action": action_taken,
@@ -11314,6 +11363,7 @@ def _v2_revert_field(project_root: str, p: Dict[str, Any]) -> Dict[str, Any]:
         "reverted_value": revert_to,
         "timestamp": now,
         "corrections_path": path,
+        "db": db_result,
     }
 
 
@@ -14955,6 +15005,25 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "cancel_batch_job",
         "resume_batch_job",
         "cleanup_artifacts",
+        # V2 session/panel state + C4 corrections. These checks lived inside
+        # this block since v2.24.0 but were missing from the membership set,
+        # making them unreachable from MCP dispatch (the panel proxied to the
+        # helpers directly, which masked it). Fixed as part of C1 (Phase A).
+        "get_panel_state",
+        "set_panel_state",
+        "session_start_context",
+        "update_shot_field",
+        "update_clip_field",
+        "get_field_history",
+        "revert_field",
+        "list_corrections",
+        # C1 — DB-canonical analysis store.
+        "db_status",
+        "db_ingest",
+        # Phase B — deep shot-level vision tier.
+        "deepen",
+        "commit_shot_vision",
+        "vision_pending_sweep",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -15007,6 +15076,49 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
             return _v2_revert_field(project_root, p)
         if action == "list_corrections":
             return _v2_list_corrections(project_root, p)
+        # C1 — DB-canonical analysis store (Phase A).
+        if action == "db_status":
+            from src.utils import analysis_store
+            return analysis_store.db_status(project_root)
+        if action == "db_ingest":
+            from src.utils import analysis_store
+            return analysis_store.ingest_project(project_root)
+        # Phase B — deep shot-level vision tier.
+        if action == "deepen":
+            from src.utils import deep_vision
+            clip_ref = p.get("clip_id") or p.get("clipId") or p.get("clip_dir") or p.get("clipDir") or p.get("file_path") or p.get("filePath")
+            if not clip_ref:
+                return _err("deepen requires clip_id, clip_dir, or file_path")
+            raw_indices = p.get("shot_indices") or p.get("shotIndices")
+            if raw_indices is None and p.get("shot_index") is not None:
+                raw_indices = [p.get("shot_index")]
+            return deep_vision.deepen_clip(
+                project_root,
+                clip_ref=clip_ref,
+                shot_indices=[int(i) for i in raw_indices] if raw_indices else None,
+                confirm_token=p.get("confirm_token") or p.get("confirmToken"),
+                job_id=p.get("job_id") or p.get("jobId"),
+            )
+        if action == "commit_shot_vision":
+            from src.utils import deep_vision
+            clip_ref = p.get("clip_id") or p.get("clipId") or p.get("clip_dir") or p.get("clipDir") or p.get("file_path") or p.get("filePath")
+            if not clip_ref:
+                return _err("commit_shot_vision requires clip_id, clip_dir, or file_path")
+            return deep_vision.commit_shot_vision(
+                project_root,
+                shots=p.get("shots"),
+                vision_token=p.get("vision_token") or p.get("visionToken"),
+                clip_ref=clip_ref,
+                author=p.get("author") or "host_chat",
+            )
+        if action == "vision_pending_sweep":
+            from src.utils import deep_vision
+            return deep_vision.vision_pending_sweep(
+                project_root,
+                expire=_media_analysis_bool(p.get("expire"), False),
+                max_age_days=p.get("max_age_days") or p.get("maxAgeDays"),
+                reoffer=_media_analysis_bool(p.get("reoffer"), False),
+            )
         if action in {"build_index", "rebuild_index"}:
             return build_analysis_index(project_root, index_path=p.get("index_path") or p.get("indexPath"))
         if action == "index_status":
@@ -15408,6 +15520,26 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "cancel_batch_job",
         "resume_batch_job",
         "cleanup_artifacts",
+        "get_panel_state",
+        "set_panel_state",
+        "session_start_context",
+        "update_shot_field",
+        "update_clip_field",
+        "get_field_history",
+        "revert_field",
+        "list_corrections",
+        "db_status",
+        "db_ingest",
+        "deepen",
+        "commit_shot_vision",
+        "vision_pending_sweep",
+        "get_caps",
+        "set_caps_preset",
+        "get_usage",
+        "coverage_report",
+        "get_resolve_ai_usage",
+        "get_ai_governance",
+        "set_ai_governance",
     ])