# DaVinci Resolve MCP Server — Agent Instructions This is the canonical short operating brief for AI coding agents working in this repository. Keep it durable: do not duplicate version numbers, tool counts, kernel-action counts, release notes, or long reference tables here. ## Non-Negotiable Source Media Safety Never modify, transcode, convert, proxy, relink, replace, or create derivatives of source media unless the user explicitly asks for that exact operation. Analysis workflows may read source media, but file outputs must go to sidecar files, session scratch space, or the configured `davinci-resolve-mcp-analysis` project root. Resolve-target analysis should run visual analysis, transcription, metadata writeback, and Media Pool marker writeback by default unless the user opts out; those writes are Resolve project database changes, not source-media changes. Preserve the chain from camera original to final delivery. See `docs/guides/media-analysis-guide.md` for the full source-safe workflow. ## Media Analysis Defaults Are Mandatory Do not translate source-safe into underpowered, read-only, no-writeback analysis. When the user asks to analyze Resolve media, run the requested analysis directly with visual analysis, transcription, persisted artifacts, metadata writeback, and Media Pool marker writeback enabled by default. Do not add `include_visuals=false`, `include_transcription=false`, `publish_metadata=false`, `timed_markers=no`, `session_only=true`, or `dry_run=true` unless the user explicitly asks for that opt-out, the target is a raw file path that cannot receive Resolve project writeback. Vision uses `host_chat_paths` by default — analyze actions return a deferred payload with absolute `frame_paths` and a JSON schema; the host chat must read those frames as local images, produce JSON per the schema, and call `media_analysis(action="commit_vision", params={clip_id, visual, vision_token})` to merge the result and trigger metadata + Media Pool clip-marker writeback. Not completing `commit_vision` leaves the analysis in `pending_host_vision_analysis` — that is a failure mode, not a success. Users must explicitly opt out with `include_visuals=false` for a technical-only run. ## Frame-Referenced Color Work Before applying a grade, look, shot match, LUT, CDL, DRX, or copied grade to an existing Resolve timeline, inspect representative Resolve-rendered frames for the target shot or shots. Use thumbnails, contact sheets, Gallery stills, marker frames, or visual analysis reports written only to scratch/analysis locations. When the API can safely provide them, compare matched untreated/bypass, current, and after frames at the same timecodes; restore the previous active version or node-enabled state after any temporary bypass capture. Do not grade only from clip metadata, graph availability, or a requested style label unless the user explicitly asks for a blind/global pass. Preserve or create a recoverable grade version, and report which frame references informed the change. Do not describe Resolve's default one-node graph as an existing creative grade unless active grade tools, LUTs, or other grade state are present. When the user asks to build on or adjust an existing grade, treat the current grade as creative work to preserve. Inspect the active grade version and node graph first, create or switch to a recoverable adjustment version, and make incremental changes only through supported controls. Do not reset grades, replace graphs, or apply whole-grade artifacts unless the user explicitly asks for that semantics. ## Source Of Truth - Public overview, current stats, and docs map: `README.md` - Historical release notes: `CHANGELOG.md` - AI assistant operating reference: `docs/SKILL.md` - Craft guidance for remote clients: the `knowledge` tool serves `.agents/skills/`, `docs/guides/`, and `docs/kernels/` as resolved prose over MCP. When you add a skill, guide, or kernel it is indexed automatically — a drift guard fails the suite if anything in those directories is unreachable - Release checklist and validation rules: `docs/process/release-process.md` - Kernel workflow support maps: `docs/kernels/` - API coverage and live-test status: `docs/reference/api-coverage.md` - Blackmagic-facing API gaps/bugs (generated from `api_truth`): `docs/reference/api-limitations.md` — when you document a new Resolve API limitation, add a `submit`-tagged entry to `src/utils/api_truth.py` and regenerate with `scripts/gen_api_limitations.py` (a drift guard enforces it) - Bundled Resolve API text: `docs/reference/resolve_scripting_api.txt` — refresh it by copying the shipped `Developer/Scripting/README.txt` over it wholesale, never by hand-adding the lines you already know about. The file's only value is that a diff against it is trustworthy; a hand-patch carries a newer `Last Updated:` header while still hiding everything you did not know to look for. That is exactly how it sat eight weeks stale at 26 May 2026 while ten documented 21.0.4 methods went unwired (PR #139) ## Key Paths - Compound server: `src/server.py` - Granular server entrypoint: `src/resolve_mcp_server.py` - Local control panel launcher: `src/control_panel.py` - Granular implementation: `src/granular/` - Utilities: `src/utils/` - Installer: `install.py` - Tests: `tests/` - Examples: `examples/` - Portable agent assets: `.agents/skills/`, `.agents/roles/`, `.agents/hooks/` - Client adapters: `.claude/` and `.codex/`. Skills are byte-identical in `.claude/skills/` (edit either copy, then run `scripts/agent-rules/sync_portable_assets.py`); hooks are canonical in `.agents/hooks/` with thin shims; `.claude/agents/*` keep their frontmatter (tools/model pins) over the shared `.agents/roles/*` bodies ## Common Commands ```bash python src/server.py python src/server.py --full venv/bin/python -m src.control_panel python install.py venv/bin/python tests/test_import.py venv/bin/python scripts/audit_api_parity.py ``` Python 3.10+ is required (the MCP SDK floor). 3.10-3.12 is the lowest-risk range for Resolve scripting; 3.13/3.14 are accepted and verified on Resolve Studio 20.3.2, but older Resolve builds may fail to connect on 3.13+. ## Development Notes - Prefer the compound server unless a task specifically needs granular tools. - Use existing action-dispatch patterns and helper functions before adding new abstractions. - All Resolve-facing temp or export paths should use the repo's safe path helpers; do not invent ad hoc temp paths for files Resolve writes. - For changes touching Resolve behavior, update focused tests and follow the live-validation guidance in `docs/process/release-process.md`. - For docs changes, keep the README concise and move durable detail into dedicated files under `docs/`. ## Domain Routing Per-domain routers pair the live tools with their offline (advanced-server) counterparts. Every domain is available on demand in ANY MCP client as a slash prompt (`/color_grade_workflow`, `/timeline_edit_workflow`, `/conform_workflow`, `/delivery_workflow`, `/analyze_media`) and as canonical skills in `.agents/skills/` (Claude Code loads content-complete `.claude/skills/` copies kept byte-identical by `scripts/agent-rules/sync_portable_assets.py` and its parity guard). Full per-action depth lives in `docs/kernels/`. - **Color / Grade** (`/color_grade_workflow`, skill `resolve-color`) — grading, correcting, shot matching, developing looks, or applying/modifying LUTs, CDLs, DRX grades, or copied grades. Live: timeline_item_color. Offline: drx. Depth: docs/kernels/color-grade-kernel.md + docs/guides/color-decision-guide.md. - **Timeline Edit** (`/timeline_edit_workflow`, skill `resolve-edit`) — cutting, trimming, pacing, duplicating/moving clips, copying ranges, building variants, tightening a cut, or generating an editorial changelist. Live: timeline. Offline: editorial. Depth: docs/kernels/timeline-edit-kernel.md + docs/guides/editorial-decision-guide.md. - **Conform / Interchange** (`/conform_workflow`, skill `resolve-conform`) — importing/relinking editorial, checking a conform against a reference, repairing reversed/retimed subclips, tracing grades across a re-conform, or QCing a conformed timeline. Live: timeline. Offline: conform. Depth: docs/kernels/timeline-conform-interchange-kernel.md. - **Delivery / Deliverable QC** (`/delivery_workflow`, skill `resolve-delivery`) — preparing render jobs, validating render settings, QCing a finished render vs spec, building render manifests, expanding texted/textless/stems deliverables, verifying media ingest, or producing a provenance/episode report. Live: render. Offline: deliverable. Depth: docs/kernels/render-deliver-kernel.md. - **Fusion Composition** (`/fusion_workflow`, skill `resolve-fusion`) — building or editing Fusion comps — titles, motion graphics, VFX, merges, masks, trackers. Live: fusion_comp. Offline: fusion. Depth: docs/kernels/fusion-composition-kernel.md. - **Audio / Fairlight** (`/audio_workflow`, skill `resolve-audio`) — setting audio properties, syncing audio, isolating voice, generating subtitles, planning Fairlight tracks/buses, checking loudness, routing buses, or splitting/trimming/converting audio. Live: timeline. Offline: audio_plan. Depth: docs/kernels/audio-fairlight-kernel.md. - **Media Pool / Ingest** (`/media_pool_workflow`, skill `resolve-media-pool`) — importing media, building multicam timelines, organizing/relinking clips, normalizing metadata, or verifying/inventorying a card before ingest. Live: media_pool. Offline: media. Depth: docs/kernels/media-pool-ingest-kernel.md + docs/guides/multicam-setup-guide.md. - **Media Analysis** (`/analyze_media`, skill `resolve-media-analysis`) — reading or analyzing source media (technical, visual, or transcription) to inform Resolve actions. Live: media_analysis. Offline: media. Depth: docs/kernels/README.md + docs/guides/media-analysis-guide.md.