samuelgursky/davinci-resolve-mcp

v2.25.0

Agentic flow improvements, MCP resources + prompts surfaces, color-grading evidence base, analysis caps layer, timeline versioning, async opt-in, aggregated provenance, update-process hardening.

Added

• Agentic flow improvements — structured error envelope (code / category / retryable / reason / remediation / message) with locked per-category retryable defaults; XML semantic tags (<when_to_use>, <actions>, <returns>) on compound-tool descriptions; repeated-failure escalation block on the 3rd failure of the same (scope, action); batch manifests always carry partial_success, completed_clip_ids, failed_clip_ids.
• MCP resources surface — 8 read-only URIs the host can poll without paying a tool-turn cost: status://mcp_version, status://resolve_connection, status://current_project, status://current_timeline, status://caps_preset, analysis://recent_reports, capabilities://installed_tools, capabilities://install_guidance.
• MCP prompts surface — 5 slash-command workflow templates: analyze_and_propose_grade, match_bin_to_hero, verify_timeline_coverage, open_and_analyze_selection, prep_color_handoff.
• Color-grading evidence base — timeline_item_color.grade_evidence_base composes version_snapshot + node_graph + color_group + coverage report into a single evidence_base summary string. propose_grade formalizes a recommendation as a validated structured plan (plan_id + preview_path; requires execute=true re-call). bulk_match_to_hero drives CDL-delta or copy-grade across many targets with a confirm_token gate and dry-run preview.
• Analysis caps layer — 7 cap dimensions across vision/transcription/job/clip/day scopes, 4 named presets (minimal / standard / generous / unlimited), pre-call refusal with CAPS_REFUSAL. New media_analysis.get_caps and set_caps_preset actions. Token usage table + control-panel widget with gauges. Wall-clock timeout wraps vision/transcription call sites.
• Timeline versioning + analysis↔timeline marriage — new timeline_versioning MCP tool. Every destructive timeline edit auto-archives into an Archive bin so versions can be diffed and rolled back. Run scoping, schema v4 migrations, concurrency safety, structural snapshots, action filtering, strict mode, media-pool destructive coverage. Backed by new modules timeline_versioning.py, timeline_brain_db.py, brain_edits.py, analysis_runs.py, media_pool_changes.py, destructive_hook.py.
• Async opt-in (prefer_handle) — analyze_clip / analyze_file / commit_vision accept prefer_handle: true. When set and the estimated runtime exceeds the configured threshold, the response is a fast handoff with job_id + status: "queued"; poll batch_job_status({job_id}).
• Aggregated provenance — summarize, review_timeline_markers, and grade_evidence_base return a provenance block: source_reports[], missing_reports[] (per reason), and inline [ref:<clip_id>] citations in the human summary.
• Confirm-token gates — propose_grade, bulk_match_to_hero, and other multi-target writes require an explicit confirm_token on first execute (returned on dry-run), with a pending_user_decision error if missing.
• Action-help indirection — action_help(name=...) returns long-form per-action guidance, keeping top-level descriptions compact.
• Tool-choice hint emission — analyze responses include a host_tool_choice_hint block hosts can pass as tool_choice to hard-lock the next call.
• Update-process hardening — active-job lock prevents mid-analysis updates, auto-stash preserves uncommitted work, restart-needed marker, channels (stable / beta / dev), pre-update breaking-change scan, integrity SHA verification, update history table, eager DB migration on update, rollback to previous build.

Fixed

• Compact analyze response by default (verbose: true for full manifest).
• commit_vision auto-publish reflects per-row status correctly (no silent-lie pending).
• Frame sampler reserves per-shot budget so shot starts aren't starved by flash candidates.
• Machine markers no longer written to Resolve (V2 architecture).
• resolve_output_root skips slug append when the configured base already terminates in the slug.

Documentation

• docs/SKILL.md updated to teach the host the host_tool_choice_hint block, the control-panel Review → History surface, and the coverage_report pre-flight contract.
• docs/guides/color-decision-guide.md and docs/guides/editorial-decision-guide.md reframed around evidence_base-first responses.
• docs/reference/api-coverage.md refreshed.

Validation

• venv/bin/python tests/test_import.py — ok
• venv/bin/python scripts/audit_api_parity.py — PASS — all checks clean
• node bin/davinci-resolve-mcp.mjs --version — 2.25.0
• npm pack --dry-run — davinci-resolve-mcp-2.25.0.tgz
• git diff --check — clean
• 375 focused unit tests pass (error envelope, failure tracker, partial-success manifest, prefer_handle, MCP resources, MCP prompts, provenance, XML description shape, action_help, grade_evidence_base, propose_grade, bulk_match_to_hero, confirm_token, analysis caps, caps integration / events / history, timeline versioning, timeline-brain DB, destructive decorator coverage, destructive hook, update hardening, update history, plus existing media-analysis / marker / v232 / v233 / append_clip_infos suites).
• Live Resolve validation: D1–F2 surface verified end-to-end against CKY / Timeline 7 (D1 retryable, D2 XML descriptions, D3 partial-success on plans + CAPS_REFUSAL manifests, E1 8 MCP resource URIs, E2 escalation on 3× repeated failure, E3 prefer_handle job handoff with batch_job_status polling, F1 provenance) — 6/6 PASS. No source media was modified.