davinci-resolve-mcp 2.95.3 → 2.96.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 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.96.0
+
+New tool **`timeline_frame`** — the assistant can look at what Resolve is
+rendering instead of inferring it from metadata. Closes
+[#146](https://github.com/samuelgursky/davinci-resolve-mcp/issues/146).
+
+### `timeline_frame(action="capture")`
+
+Returns the timeline frame as MCP image content — grade, Fusion, titles,
+transitions, as composited. (For the raw camera file, `media_analysis(action=
+"extract_frames")` is still the right call.)
+
+- `timecode` / `frame` — capture anywhere, not just the playhead. Accepts
+  absolute (`01:00:15:12`) or elapsed (`00:00:15:12`) timecode, matching the
+  marker-parameter contract.
+- `quality` — `preview` (Resolve's thumbnail; fast, writes nothing) or `full`
+  (full resolution via a Gallery still, removed again afterwards).
+- `max_width` — bound the context cost. Preview downscales in-process with an
+  area average; `full` rescales with ffmpeg, and **fails rather than silently
+  returning a full-size frame** when ffmpeg is missing.
+- `format` — `png` (default), `jpg`, or `tif` on the `full` path.
+- `timeline_name` — capture from another timeline; it is made current for the
+  read and the original restored after.
+
+A capture is a read: the Color page, playhead, current timeline, and Gallery all
+come back as the caller left them.
+
+### Why a separate tool rather than an action on `timeline`
+
+FastMCP derives an output schema from a tool's return annotation and validates
+returns against it, so a `-> Dict[str, Any]` tool cannot return image content.
+`timeline_frame` is annotated `-> Any` for that reason — the same reason
+`timeline_markers` already was. The issue asked for a top-level tool, and the
+schema constraint independently forces one.
+
+### Fixed — thumbnail reads no longer misreport a page problem as a missing frame
+
+`GetCurrentClipThumbnailImage` returns `None` on every page except Color, with
+nothing to distinguish that from "no frame here."
+`timeline_markers(action="get_thumbnail")` and `get_thumbnail_image` called it
+bare, so off the Color page they reported a missing thumbnail. Both now hold the
+Color page for the read and restore the previous page — the mitigation
+`thumbnail_contact_sheet` already used. When the switch genuinely cannot happen
+(headless, page locked), the error names the Color-page requirement instead.
+
+`get_thumbnail_image` now shares the `timeline_frame` capture path, so it picks
+up the fix; its contract is unchanged.
+
+### Fixed — the installer configures Codex CLI
+
+The installer claimed Codex support but never wrote its config, so a successful
+install left no `davinci-resolve` entry in `~/.codex/config.toml` — everything
+else (venv, Resolve paths, bridge, server) was in place and only the
+registration was missing. Codex keys MCP servers under a TOML
+`[mcp_servers.<name>]` table, and the installer only knew how to write JSON.
+Closes [#39](https://github.com/samuelgursky/davinci-resolve-mcp/issues/39).
+
+`codex` is now a selectable client (included in `--clients all`), writing
+`$CODEX_HOME/config.toml` (default `~/.codex/config.toml`), and `--manual`
+prints a ready-to-paste TOML block.
+
+The merge is a text splice, not a parse-and-rewrite, so comments and hand
+formatting survive; an existing `[mcp_servers.davinci-resolve]` table has its
+`command`/`args`/`env` replaced in place. Sub-tables of that entry are kept:
+hand-written Codex configs put per-tool approval modes in
+`[mcp_servers.davinci-resolve.tools.<tool>]`, and an installer that dropped them
+would quietly widen what the agent may do without asking. An
+`[mcp_servers.davinci-resolve.env]` sub-table is regenerated in that same shape
+rather than replaced with an inline `env` — TOML rejects a file that spells one
+key both ways.
+
+Paths are escaped as TOML basic strings (Windows backslashes would otherwise
+corrupt the file). The installer refuses to touch a config that is already
+invalid TOML, one that defines the server as an inline key it cannot safely
+rewrite, or a merge result that would not parse — the same
+never-wipe-a-user-config policy the JSON clients follow. Writes are backed up to
+`config.toml.backup` first.
+
 ## What's New in v2.95.3
 
 Closes the retime entry's explicit `UNTESTED` warning: **reverse and

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.95.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.96.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-34%20(353%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-35%20(353%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -24,7 +24,7 @@ A local browser control panel ships with the server for inspecting Resolve state
 npx davinci-resolve-mcp setup
 ```
 
-Before connecting, open DaVinci Resolve Studio and set **Preferences > General > External scripting using** to **Local**. (On the **free edition** that preference does not help — see [Free edition](#free-edition-in-app-bridge) below.) The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, and JetBrains IDEs.
+Before connecting, open DaVinci Resolve Studio and set **Preferences > General > External scripting using** to **Local**. (On the **free edition** that preference does not help — see [Free edition](#free-edition-in-app-bridge) below.) The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, Codex CLI, and JetBrains IDEs.
 
 For source installs:
 
@@ -109,7 +109,7 @@ The command starts a localhost server and opens the control panel in your browse
 
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
-| Compound | `src/server.py` | 34 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
+| Compound | `src/server.py` | 35 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
 | Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 353 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
@@ -272,7 +272,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **34** compound / **353** granular (live server) |
+| MCP Tools | **35** compound / **353** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.95.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.96.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-34%20(353%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-35%20(353%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.95.3 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.96.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -26,7 +26,7 @@
 npx davinci-resolve-mcp setup
 ```
 
-连接之前，先打开 DaVinci Resolve Studio，把 **Preferences > General > External scripting using** 设为 **Local**。（**免费版**上这个偏好设置不起作用——见下文 [免费版](#免费版应用内桥接)。）npm 启动器会在你的用户应用数据目录下安装一份托管副本，然后运行通用 Python 安装器。安装器会创建虚拟环境、检测 Resolve 路径，并可自动配置 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Zed、Continue、Cline、Roo Code、OpenCode 和 JetBrains 系列 IDE。
+连接之前，先打开 DaVinci Resolve Studio，把 **Preferences > General > External scripting using** 设为 **Local**。（**免费版**上这个偏好设置不起作用——见下文 [免费版](#免费版应用内桥接)。）npm 启动器会在你的用户应用数据目录下安装一份托管副本，然后运行通用 Python 安装器。安装器会创建虚拟环境、检测 Resolve 路径，并可自动配置 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Zed、Continue、Cline、Roo Code、OpenCode、Codex CLI 和 JetBrains 系列 IDE。
 
 从源码安装：
 
@@ -81,7 +81,7 @@ venv/bin/python -m src.control_panel
 
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
-| Compound（复合） | `src/server.py` | 34 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
+| Compound（复合） | `src/server.py` | 35 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
 | Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 353 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
@@ -196,7 +196,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **34** 复合 / **353** 细粒度（实时服务器） |
+| MCP 工具 | **35** 复合 / **353** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -162,7 +162,7 @@ before mutating Resolve state.
 
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
-| Compound (default) | `src/server.py` | 34 tools | Most workflows — keeps context lean |
+| Compound (default) | `src/server.py` | 35 tools | Most workflows — keeps context lean |
 | Granular (full) | `src/server.py --full` | 353 tools | Power users needing one tool per API method |
 
 This skill document covers the **compound server** (the default). Each compound
@@ -393,7 +393,7 @@ the work done:
 
 - `timeline(action="detect_gaps_overlaps")`
 - `timeline(action="source_range_report")`
-- `timeline_markers(action="get_thumbnail_image")` at important markers and cuts
+- `timeline_frame(action="capture")` at important markers and cuts
 - Compare each marker name against the Resolve-rendered frame; revise the marker
   or edit if the image contradicts the plan.
 
@@ -1492,7 +1492,39 @@ applied — which is different from reading the source file directly.
 
 Use `get_thumbnail_image` when the MCP client can display image content directly.
 It converts the same Resolve thumbnail payload to PNG bytes without writing a
-file to disk.
+file to disk. Both actions hold the Color page for the read and restore the
+previous page. Prefer `timeline_frame(action="capture")` for new work — it is the
+same capture plus a timecode target, `max_width`, and a full-resolution mode.
+
+**`timeline_frame`** — Capture a timeline frame as viewable image content.
+
+Key actions: `capture(timecode?|frame?, quality?, max_width?, format?, timeline_name?)`,
+`capabilities`
+
+Returns MCP image content, so a multimodal assistant can look at what Resolve is
+rendering — grade, Fusion, titles, transitions — rather than inferring it from
+metadata. (For the raw camera file instead, use
+`media_analysis(action="extract_frames")`.)
+
+- `quality="preview"` (default) is Resolve's thumbnail: fast, small, writes
+  nothing.
+- `quality="full"` grabs a Gallery still for a full-resolution frame, then
+  removes it again. `format` is `png` (default), `jpg`, or `tif`.
+- `max_width` caps the width to conserve context. On `full` this needs ffmpeg;
+  without it the call fails rather than quietly returning a full-size frame.
+- `timecode` accepts absolute (`01:00:15:12`) or elapsed (`00:00:15:12`) time;
+  `frame` is the absolute timeline frame. Omit both to capture the playhead.
+
+A capture is a read: the Color page, the playhead, the current timeline, and the
+Gallery are all restored afterwards.
+
+```
+timeline_frame(action="capture", params={"timecode": "01:00:15:12", "max_width": 1280})
+```
+
+This tool is separate from `timeline` because a tool that returns image content
+cannot declare a `Dict[str, Any]` output schema — FastMCP validates returns
+against it, and image content fails that validation.
 
 **`timeline_ai`** — AI/ML analysis on the current timeline.
 
@@ -2046,15 +2078,33 @@ clip's comp, always pass `clip_id`, `timeline_item_id`, or `timeline_item`.
 
 ## Seeing What Resolve Sees (Visual Context)
 
-The server provides two mechanisms to inspect a frame as Resolve has processed it,
-including color grading, effects, and compositing — not just the raw source file.
+The server provides several mechanisms to inspect a frame as Resolve has processed
+it, including color grading, effects, and compositing — not just the raw source
+file.
+
+**Start here: `timeline_frame(action="capture")`** — Returns the frame at the
+playhead (or at any `timecode`/`frame` you name) as MCP image content, so a
+multimodal assistant can simply look at it. `quality="preview"` is fast and
+writes nothing; `quality="full"` is full resolution; `max_width` bounds the
+context cost. The Color page, playhead, current timeline, and Gallery are all
+restored afterwards.
+
+```
+timeline_frame(action="capture", params={"timecode": "01:00:15:12", "max_width": 1280})
+```
 
 **`timeline_markers(action="get_thumbnail")`** — Returns raw thumbnail data at
 the current playhead position. The response is a dictionary with keys `data`,
-`format`, `width`, `height`, `noOfComponents`, and `depth`.
+`format`, `width`, `height`, `noOfComponents`, and `depth`. Use it when you need
+pixel data for tooling rather than an image to look at.
+
+**`timeline_markers(action="get_thumbnail_image")`** — The original image-content
+action, equivalent to `timeline_frame(action="capture")` at default quality with
+no positional arguments. Kept for existing callers.
 
-**`timeline_markers(action="get_thumbnail_image")`** — Converts the same current
-frame thumbnail to PNG bytes and returns MCP image content without writing a file.
+**`timeline(action="thumbnail_contact_sheet")`** — Many frames at once as a single
+labeled PNG written to the analysis root. Use it to review a stretch of cut rather
+than one moment.
 
 **`gallery_stills(action="grab_and_export", params={...})`** — Grabs a still from
 the current frame on the Color page and returns the image encoded as base64 in the

package/docs/contributing.md

@@ -63,7 +63,7 @@ This MCP server controls DaVinci Resolve via its Scripting API. Some tools perfo
 davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
-│   ├── server.py                # Compound MCP server — 34 tools (default)
+│   ├── server.py                # Compound MCP server — 35 tools (default)
 │   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 353 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers

package/docs/install.md

@@ -88,6 +88,7 @@ The installer can automatically configure any of these clients:
 | Zed | `~/.config/zed/settings.json` |
 | Continue | `~/.continue/config.json` |
 | OpenCode | `~/.config/opencode/opencode.json` (or project-root `opencode.json`) |
+| Codex CLI | `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) — TOML `[mcp_servers.davinci-resolve]` |
 | JetBrains IDEs | Manual (Settings > Tools > AI Assistant > MCP) |
 
 You can configure multiple clients at once, or use `--clients manual` to get copy-paste config snippets.
@@ -132,7 +133,7 @@ The MCP server comes in two modes:
 
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
-| **Compound** (default) | `src/server.py` | 34 | Most users — fast, clean, low context usage |
+| **Compound** (default) | `src/server.py` | 35 | Most users — fast, clean, low context usage |
 | **Full** | `src/resolve_mcp_server.py` | 353 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
@@ -196,6 +197,21 @@ If you prefer to set things up yourself, add to your MCP client config:
 }
 ```
 
+Codex CLI uses TOML instead. Add to `~/.codex/config.toml` (or
+`$CODEX_HOME/config.toml`):
+
+```toml
+[mcp_servers.davinci-resolve]
+command = "/path/to/venv/bin/python"
+args = ["/path/to/davinci-resolve-mcp/src/server.py"]
+env = { RESOLVE_SCRIPT_API = "/path/to/DaVinci Resolve/Developer/Scripting", RESOLVE_SCRIPT_LIB = "/path/to/fusionscript.so-or-dll", PYTHONPATH = "/path/to/DaVinci Resolve/Developer/Scripting/Modules" }
+```
+
+Paths must be absolute — Codex does not expand `~`. Run
+`python install.py --clients codex` to have the installer write this block for
+you (it merges into an existing config and leaves your other servers and
+comments alone).
+
 On Windows, installer-generated configs also include `PYTHONHOME`. That scopes Resolve's Python binding to the selected interpreter and avoids the Resolve 20.3 multi-Python crash reported in [Issue #26](https://github.com/samuelgursky/davinci-resolve-mcp/issues/26).
 
 For Resolve's **Network** scripting mode, add

package/docs/reference/api-coverage.md

@@ -6,7 +6,7 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **34** compound (default) / **353** granular |
+| MCP Tools | **35** compound (default) / **353** granular |
 | Kernel Actions | **136** guarded MCP workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |
 | Methods Live Tested | **338/361** (93.6%) |
@@ -17,7 +17,7 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 ## API Coverage
 
-Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **34 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **353 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
+Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **35 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **353 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
 
 The 34th compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the