resolve-mcp: Instructions file for Claude Code

resolve-mcp

MCP server exposing ~296 tools for the DaVinci Resolve scripting API (v20.3), plus AI bridge tools powered by Google Gemini.

Quick Start

pip install -e ".[dev]"         # install package + ruff/pytest/pyright
cp .env.example .env            # optional — only needed for AI bridge tools
resolve-mcp                     # run the MCP server (needs Resolve open)
pytest tests/ -v                # run tests (no Resolve needed)

Architecture

• Package: resolve_mcp/ — all modules use relative imports (from .config import mcp)
• Entry point: resolve_mcp/__init__.py → main() → mcp.run()
• Tool registration: Every tool module is imported in __init__.py. The @mcp.tool decorator on each function auto-registers it with the FastMCP server.
• MCP resources: resources.py exposes read-only resolve:// URIs (project, timelines, bins, render-queue, version)

Key Patterns

Adding a new tool

1. Create or edit a *_tools.py module
2. Import from .config import mcp and from .resolve import get_resolve, _boilerplate
3. Decorate with @mcp.tool
4. If the module is new, add from . import my_new_tools in __init__.py

Gotcha — cascading imports: 18 modules are loaded indirectly through import chains rather than __init__.py. For example, edit_tools.py imports clip_edit_tools, which imports clip_query_tools. If you add tools to one of these indirect modules, they'll register correctly without touching __init__.py — but only because the parent module already imports them. See tests/test_conventions.py::INDIRECT_IMPORT_MODULES for the full list.

Resolve connection

• get_resolve() returns the Resolve scripting object (or None if not running)
• _boilerplate() returns (resolve, project, media_pool) — a 3-tuple, no timeline. Get timeline separately: project.GetCurrentTimeline()
• All Resolve API calls go through the network scripting interface

Error handling

• @safe_resolve_call decorator in errors.py wraps tools to catch exceptions and return MCP-friendly error strings — including your own bugs (NameError, KeyError, etc.), which become silent string returns instead of tracebacks
• Custom exception classes: ResolveNotRunning, ProjectNotOpen, TimelineNotFound, BinNotFound, ClipNotFound, ItemNotFound, StudioRequired