|
2 | 2 |
|
3 | 3 | 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. |
4 | 4 |
|
| 5 | +## What's New in v2.25.0 |
| 6 | + |
| 7 | +**Agentic flow improvements** — A second-pass review against the Claude |
| 8 | +Certified Architect study material drove a sweep of correctness gains. Every |
| 9 | +tool error now returns a structured envelope (`code` / `category` / |
| 10 | +`retryable` / `reason` / `remediation` / `message`); `retryable` defaults are |
| 11 | +locked per category so a host can make a one-shot retry decision without |
| 12 | +inference. Compound-tool descriptions for `media_analysis` and |
| 13 | +`timeline_item_color` adopt XML semantic tags (`<when_to_use>`, `<actions>`, |
| 14 | +`<returns>`) for cheaper per-turn parsing. Repeated failures on the same |
| 15 | +`(scope, action)` pair attach an `escalation` block on the 3rd response — |
| 16 | +halts auto-retry loops with a `suggested_action` for the host. Batch |
| 17 | +manifests now always carry `partial_success`, `completed_clip_ids`, and |
| 18 | +`failed_clip_ids` for safe targeted retry. |
| 19 | + |
| 20 | +**MCP resources surface** — 8 read-only resource URIs the host can poll |
| 21 | +without paying a tool-turn cost: `status://mcp_version`, |
| 22 | +`status://resolve_connection`, `status://current_project`, |
| 23 | +`status://current_timeline`, `status://caps_preset`, |
| 24 | +`analysis://recent_reports`, `capabilities://installed_tools`, |
| 25 | +`capabilities://install_guidance`. Paired tools still work for hosts that |
| 26 | +don't consume resources. |
| 27 | + |
| 28 | +**MCP prompts surface** — 5 slash-command workflow templates: |
| 29 | +`/davinci-resolve:analyze_and_propose_grade`, |
| 30 | +`/davinci-resolve:match_bin_to_hero`, |
| 31 | +`/davinci-resolve:verify_timeline_coverage`, |
| 32 | +`/davinci-resolve:open_and_analyze_selection`, |
| 33 | +`/davinci-resolve:prep_color_handoff`. First-class agentic intent, no |
| 34 | +re-derivation from SKILL.md prose. |
| 35 | + |
| 36 | +**Color-grading evidence base** — `timeline_item_color.grade_evidence_base` |
| 37 | +composes `version_snapshot` + `node_graph` + `color_group` + coverage report |
| 38 | +into a single `evidence_base` summary string; the SKILL guide now teaches |
| 39 | +agents to lead any color recommendation with that line. |
| 40 | +`timeline_item_color.propose_grade` formalizes a recommendation as a |
| 41 | +validated structured plan (returns `plan_id` + `preview_path`; requires |
| 42 | +explicit `execute=true` re-call). `bulk_match_to_hero` drives CDL-delta or |
| 43 | +copy-grade across many targets with a `confirm_token` gate and dry-run |
| 44 | +preview. |
| 45 | + |
| 46 | +**Analysis caps layer** — Token-budget governance for analysis. 7 cap |
| 47 | +dimensions across vision/transcription/job/clip/day scopes, 4 named presets |
| 48 | +(`minimal` / `standard` / `generous` / `unlimited`), pre-call refusal with |
| 49 | +`CAPS_REFUSAL` / `budget_exhausted` / `retryable: false`. New |
| 50 | +`media_analysis` actions: `get_caps`, `set_caps_preset`. Token usage table |
| 51 | +in the analysis DB plus a control-panel widget with gauges + override |
| 52 | +inputs. Wall-clock timeout helper wraps vision/transcription call sites. |
| 53 | + |
| 54 | +**Timeline versioning + analysis↔timeline marriage** — New |
| 55 | +`timeline_versioning` MCP tool: every destructive timeline edit |
| 56 | +auto-archives the current timeline into an Archive bin (compound, captions, |
| 57 | +ripple, gap close, etc.), so versions can be diffed and rolled back. Run |
| 58 | +scoping, schema v4 migrations, concurrency safety, structural snapshots, |
| 59 | +action filtering, strict mode, auto-save preference, media-pool destructive |
| 60 | +coverage, thumbnails. Backed by new modules `timeline_versioning.py`, |
| 61 | +`timeline_brain_db.py`, `brain_edits.py`, `analysis_runs.py`, |
| 62 | +`media_pool_changes.py`, `destructive_hook.py`. Surfaced in the control |
| 63 | +panel's Review → History view. |
| 64 | + |
| 65 | +**Async opt-in for long-running ops** — `analyze_clip` / `analyze_file` / |
| 66 | +`commit_vision` accept `prefer_handle: true`. When set (and the estimated |
| 67 | +runtime exceeds the configured threshold), the response is a fast handoff |
| 68 | +with `job_id` + `status: "queued"`; poll `batch_job_status({job_id})`. |
| 69 | +Default behavior unchanged. |
| 70 | + |
| 71 | +**Aggregated provenance** — `summarize`, |
| 72 | +`review_timeline_markers`, and `grade_evidence_base` now return a |
| 73 | +`provenance` block: `source_reports[]` (clip_id, signature, report_path, |
| 74 | +analyzed_at), `missing_reports[]` (per reason: `no_report` / `stale_report` |
| 75 | +/ `caps_refused`), and inline `[ref:<clip_id>]` citations in the human |
| 76 | +summary text. Multi-clip claims are now traceable. |
| 77 | + |
| 78 | +**Confirm-token gates on destructive batches** — `propose_grade`, |
| 79 | +`bulk_match_to_hero`, and other multi-target writes now require an explicit |
| 80 | +`confirm_token` on first execute (returned on the dry-run), with a |
| 81 | +`pending_user_decision` error if missing. |
| 82 | + |
| 83 | +**Action-help indirection** — `action_help(name=...)` returns the long-form |
| 84 | +guidance for a single action, keeping the top-level tool descriptions |
| 85 | +compact while preserving full per-action documentation. |
| 86 | + |
| 87 | +**Tool-choice hint emission** — Analyze responses include a |
| 88 | +`host_tool_choice_hint` block. Hosts that respect it pass |
| 89 | +`tool_choice={type:"tool", name:"media_analysis"}` on the next API turn, |
| 90 | +hard-locking the agent into the correct next call. |
| 91 | + |
| 92 | +**Update process hardening** — Five improvements layered onto the |
| 93 | +update-check path: active-job lock prevents updates mid-analysis, auto-stash |
| 94 | +strategy preserves uncommitted work across updates, restart-needed marker |
| 95 | +surfaces to the host, channels (`stable` / `beta` / `dev`), pre-update |
| 96 | +breaking-change scan, integrity SHA verification of downloaded artifacts, |
| 97 | +update history table, eager DB migration on update, and rollback to the |
| 98 | +previous build. New `analysis_caps.py` + `update_check.py` revisions. |
| 99 | + |
| 100 | +**Source-safe guardrails** — `destructive_hook.py` + decorator coverage |
| 101 | +tests ensure every destructive surface goes through the auto-archive path |
| 102 | +and never modifies, transcodes, or creates derivatives of source media. |
| 103 | + |
| 104 | +**Test surface** — 30+ new test modules covering error envelopes, |
| 105 | +failure tracking, partial-success manifests, `prefer_handle`, MCP resources, |
| 106 | +MCP prompts, provenance, XML description shape, `action_help`, |
| 107 | +`grade_evidence_base`, `propose_grade`, `bulk_match_to_hero`, |
| 108 | +`confirm_token`, the analysis caps layer, caps integration / events / |
| 109 | +history, timeline versioning, the timeline-brain DB, destructive decorator |
| 110 | +coverage, the destructive hook, update hardening, and update history. |
| 111 | + |
| 112 | +**Validation** — `tests/test_import.py`, `scripts/audit_api_parity.py`, |
| 113 | +`node bin/davinci-resolve-mcp.mjs --version`, `npm pack --dry-run`, and |
| 114 | +`git diff --check` all pass. 375 focused unit tests pass. Live Resolve |
| 115 | +validation covered the D1–F2 surface end-to-end against project CKY / |
| 116 | +Timeline 7 (D1 `retryable`, D2 XML descriptions, D3 partial-success on |
| 117 | +plans + CAPS_REFUSAL manifests, E1 8 MCP resource URIs, E2 escalation on |
| 118 | +3× repeated failure, E3 `prefer_handle` job handoff with |
| 119 | +`batch_job_status` polling, F1 provenance block) — 6/6 PASS on the |
| 120 | +fourteenth-attempt smoke test. No source media was modified. |
| 121 | + |
5 | 122 | ## What's New in v2.24.1 |
6 | 123 |
|
7 | 124 | **`npx davinci-resolve-mcp` no longer breaks MCP clients when invoked without a |
|
0 commit comments