davinci-resolve-mcp 2.40.0 → 2.41.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 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.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.41.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,24 @@ 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`, and
+`list_corrections`.
+
+**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/install.py

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

package/src/analysis_dashboard.py

@@ -12450,6 +12450,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 +12549,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 +12580,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 +12617,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 +12634,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.41.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.41.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,21 @@ 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",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -15007,6 +15072,13 @@ 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)
         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 +15480,23 @@ 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",
+        "get_caps",
+        "set_caps_preset",
+        "get_usage",
+        "coverage_report",
+        "get_resolve_ai_usage",
+        "get_ai_governance",
+        "set_ai_governance",
     ])