davinci-resolve-mcp 3.2.2 → 3.3.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 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 v3.3.0 — ask the server what the native Resolve API contains
+
+Contributed by @legionsound (#229), the second of the two branches queued in #207.
+
+### Added
+
+- **`resolve_control`: `search_api`, `describe_api`, `api_surface`**, plus
+  granular twins `search_resolve_api`, `describe_resolve_api` and
+  `get_resolve_api_surface`. `resolve_control api_truth` already answered *what
+  is broken*; nothing answered *what exists*. #205 shipped Blackmagic's typed
+  `DaVinciResolveScript.pyi` and `scripts/audit_typed_api.py` could inventory
+  it, but only from a shell — an agent talking to this server had no way to ask.
+  This is the equivalent of Blackmagic's own `search_scripting_api`. Tool count
+  37/384 → 37/387.
+- **All three are read-only and none needs a Resolve connection.** They parse
+  the stub that already ships in `docs/reference/`, so they answer with Resolve
+  closed, and they describe the stub checked into this repository — currently
+  21.1.0.14 — not whatever build happens to be installed. A missing stub is
+  reported as missing rather than guessed around.
+- **Every result carries `referenced_in_this_server` and the files that
+  reference the method**, so a lookup doubles as a parity check: does the native
+  API have it, and do we wrap it? The flag counts executable syntax only —
+  attribute access, calls, `getattr(obj, "Name")` — never docstrings or
+  comments, built the same way `audit_typed_api.py` builds its source
+  references. A method named in prose is not coverage.
+- **Ambiguity is reported, not guessed.** A bare `GetName` lists its candidates
+  instead of picking one. An invalid regex is refused rather than raised.
+  Results are capped with an explicit `truncated` flag rather than silently cut.
+
+### Guards
+
+- The parser independently reports **410 methods, 46 TypedDicts, 513 fields**,
+  and `tests/test_typed_api_search.py` asserts that equality against the
+  inventory recorded in `resolve-211-typed-api.md`. A future stub refresh that
+  changes the surface now fails the suite instead of drifting quietly. The same
+  file checks both interfaces agree on surface, search and describe, and that
+  neither needs a connection.
+
 ## What's New in v3.2.2 — an analysis root that is deleted is actually let go of
 
 Contributed by @Dev-next-gen (#228), generalised to the second site and to the

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.2.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.3.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-37%20(384%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(387%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)
@@ -133,7 +133,7 @@ The command starts a loopback-only server and opens the control panel in your br
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 37 | 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` | 384 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 387 | 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.
 
@@ -365,7 +365,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **37** compound / **384** granular (live server) |
+| MCP Tools | **37** compound / **387** 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-3.2.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.3.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-37%20(384%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(387%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)
 
-> 本翻译对应 v3.2.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v3.3.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 37 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 384 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 387 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **37** 复合 / **384** 细粒度（实时服务器） |
+| MCP 工具 | **37** 复合 / **387** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -353,7 +353,7 @@ to the user as verified.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 37 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 384 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 387 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades

package/docs/install.md

@@ -144,7 +144,7 @@ The MCP server comes in two modes:
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
 | **Compound** (default) | `src/server.py` | 37 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 384 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 387 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 384-tool server
+python src/server.py --full    # Launch full 387-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -25,7 +25,7 @@ Every non-deprecated method in the bundled legacy README is represented. This
 does not claim complete coverage of the newer Resolve 21.1 typed API. The
 default compound server exposes **37 tools** that group related operations by
 action parameter, keeping LLM context windows lean. The full granular server
-provides **384 individual tools** for power users. The legacy coverage spans
+provides **387 individual tools** for power users. The legacy coverage spans
 13 API object classes. MCP-level kernel actions are tracked separately in
 [Kernel Action Coverage](../kernels/README.md).
 
@@ -39,6 +39,11 @@ Parity with Blackmagic's own MCP surfaced one more gap: it exposes
 node but never list, install or remove LUT files. The `lut` tool and its
 granular twins close that. See [LUT file controls](lut-file-controls.md).
 
+The typed stub shipped in #205 is now queryable from the server itself, the
+way Blackmagic's MCP exposes `search_scripting_api` — and each result also says
+whether this server wraps the method, so a lookup doubles as a parity check.
+See [Querying the typed API](typed-api-search.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
 version-on-mutate hook that auto-archives the working timeline before any

package/docs/reference/typed-api-search.md

@@ -0,0 +1,56 @@
+# Querying the typed API from inside the server
+
+`resolve_control api_truth` answers *what is broken*. Nothing answered *what
+exists*. PR #205 landed Blackmagic's `DaVinciResolveScript.pyi` in
+`docs/reference/`, and `scripts/audit_typed_api.py` can turn it into a full
+inventory — but only from a shell. An agent talking to this server had no way
+to ask what the native API contains.
+
+Blackmagic's own MCP exposes `search_scripting_api` for this. These are the
+equivalent, with one addition that matters more here.
+
+## The addition: coverage, not just existence
+
+Every result carries `referenced_in_this_server` and the source files that
+reference it. That turns a lookup into a parity check — *does the native API
+have it, and do we wrap it?* — which is the question the whole 21.1 audit was
+built to answer, and it was previously only answerable by grepping.
+
+The flag counts **executable syntax only**: attribute access, calls, and
+`getattr(obj, "Name")`. A method named in a docstring or a comment is not
+coverage. Treating prose as coverage is the specific mistake this repo's audits
+exist to avoid, so the flag is built the same way `scripts/audit_typed_api.py`
+builds its source references.
+
+## Actions and tools
+
+Compound `resolve_control`, none of which need a Resolve connection:
+
+- `search_api(pattern, kind?, limit?)` — case-insensitive regex over
+  class-qualified method names, signatures, TypedDict names, field names and
+  descriptions. `kind` is `all`, `methods` or `options`. Results are capped and
+  the response declares `truncated` rather than silently cutting.
+- `describe_api(symbol)` — one `Class.Method`, an unambiguous bare method name,
+  or a TypedDict name. An ambiguous bare name lists the candidates instead of
+  guessing.
+- `api_surface()` — counts and the object list.
+
+Granular twins: `search_resolve_api`, `describe_resolve_api`,
+`get_resolve_api_surface`. Tool count 384 → 387. The granular tools carry the read-only annotation, since
+for the granular server the MCP annotation is the signal a client reads.
+
+## Self-consistency
+
+The parser reports **410 methods, 46 TypedDicts, 513 fields**, independently
+matching the inventory published in `resolve-211-typed-api.md` and the
+disposition ledgers built during the 21.1 audit. That agreement is asserted in
+`tests/test_typed_api_search.py`, so a stub refresh that changes the surface
+will fail the suite rather than drift quietly.
+
+## Scope
+
+This reads the stub shipped in this repository; it does not query a running
+Resolve, and it will report a missing stub rather than guessing. It therefore
+describes the API of the Resolve version whose stub is checked in — 21.1.0.14 —
+not whatever build happens to be installed. Refreshing the stub is the existing
+documented process in `resolve-211-typed-api.md`.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "3.2.2"
+VERSION = "3.3.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -1543,7 +1543,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "37 compound · 384 full · 3 platforms"
+    subtitle = "37 compound · 387 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "3.2.2"
+VERSION = "3.3.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/resolve_control.py

@@ -1,6 +1,8 @@
 """Resolve control resources, inspection helpers, and app-level tools."""
 
 from src.granular.common import *  # noqa: F401,F403
+import os
+from src.utils import typed_api_search
 
 resolve = ResolveProxy()
 
@@ -719,3 +721,48 @@ def export_user_preferences_preset(preset_name: str, export_path: str) -> Dict[s
         return missing
     result = resolve.ExportUserPreferencesPreset(preset_name, export_path)
     return {"success": bool(result), "preset_name": preset_name, "export_path": export_path}
+
+
+_PROJECT_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def search_resolve_api(pattern: str, kind: str = "all", limit: int = 50) -> Dict[str, Any]:
+    """Search the shipped Resolve 21.1 typed API stub. Needs no connection.
+
+    `api_truth` answers what is broken; this answers what exists. Each hit also
+    reports whether THIS server references the method and in which files, so a
+    search doubles as a parity check.
+
+    Args:
+        pattern: Case-insensitive regular expression, e.g. "marker" or "(Get|Set)Setting".
+        kind: 'all' (default), 'methods', or 'options' for TypedDicts only.
+        limit: Maximum results per section (capped at 200).
+    """
+    try:
+        return typed_api_search.search(_PROJECT_DIR, pattern, kind=kind, limit=limit)
+    except typed_api_search.TypedApiError as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def describe_resolve_api(symbol: str) -> Dict[str, Any]:
+    """Full typed detail for one Resolve API symbol. Needs no connection.
+
+    Args:
+        symbol: 'Class.Method' (e.g. "Project.GetName"), a bare method name when
+            it is unambiguous, or a TypedDict name (e.g. "RenderSettings").
+    """
+    try:
+        return typed_api_search.describe(_PROJECT_DIR, symbol)
+    except typed_api_search.TypedApiError as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def get_resolve_api_surface() -> Dict[str, Any]:
+    """Counts and object list for the shipped typed stub. Needs no connection."""
+    try:
+        return typed_api_search.summary(_PROJECT_DIR)
+    except typed_api_search.TypedApiError as exc:
+        return {"error": str(exc)}

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (384 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (387 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "3.2.2"
+VERSION = "3.3.0"
 
 import base64
 import os
@@ -52,6 +52,7 @@ from src.utils.resolve211_edits import validate_edit_options, validate_transitio
 
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
+from src.utils import typed_api_search
 from src.utils import lut_files
 from src.utils import resolve_writes as _resolve_writes
 from src.utils.mcp_stdio import run_fastmcp_stdio
@@ -16652,6 +16653,15 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       set_keyframe_mode(mode) -> {success}
       quit() -> {success}
       get_fairlight_presets() -> {presets}
+      search_api(pattern, kind?, limit?) -> {methods, option_types, total_matches}
+        — regex over the shipped Resolve 21.1 typed stub. Each hit says whether
+          THIS server references the method, and where, so it doubles as a
+          parity check. kind: 'all' (default) | 'methods' | 'options'.
+          No connection needed.
+      describe_api(symbol) -> {signatures, stub_line, description, source_files}
+        — one 'Class.Method' or one TypedDict name. No connection needed.
+      api_surface() -> {methods, option_types, option_fields, objects}
+        — what the shipped stub contains. No connection needed.
       set_high_priority() -> {success}
       disable_background_tasks_for_current_session() -> {success}  — Resolve 21+
       list_user_preferences_presets() -> {presets}  — Resolve 21.0.4+
@@ -16706,7 +16716,24 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     # that property is worth keeping: it is the one call that still answers when
     # Resolve is down or unreachable. So the live build is used only if one is
     # ALREADY connected, or if the caller names it. Never connect for this.
-    if action == "api_truth":
+    if action == "search_api":
+        try:
+            return typed_api_search.search(
+                project_dir, p.get("pattern"),
+                kind=p.get("kind", "all"), limit=p.get("limit", 50))
+        except typed_api_search.TypedApiError as exc:
+            return _err(str(exc), code="TYPED_API_QUERY", category="invalid_input")
+    elif action == "describe_api":
+        try:
+            return typed_api_search.describe(project_dir, p.get("symbol"))
+        except typed_api_search.TypedApiError as exc:
+            return _err(str(exc), code="TYPED_API_QUERY", category="invalid_input")
+    elif action == "api_surface":
+        try:
+            return typed_api_search.summary(project_dir)
+        except typed_api_search.TypedApiError as exc:
+            return _err(str(exc), code="TYPED_API_QUERY", category="invalid_input")
+    elif action == "api_truth":
         facts = lookup_api_truth(p.get("query"))
         live_version = p.get("resolve_version")
         if not live_version and resolve is not None:
@@ -17139,7 +17166,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if err:
             return _err(err)
         return {"success": bool(r.ExportUserPreferencesPreset(clean["name"], clean["path"]))}
-    return _unknown(action, ["is_studio","get_keyboard_presets","get_current_keyboard_preset","launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","report_issue","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["is_studio","get_keyboard_presets","get_current_keyboard_preset","launch","runtime_mode","get_version","search_api","describe_api","api_surface","api_truth","check_version_support","verification_stats","report_issue","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────

package/src/utils/typed_api_search.py

@@ -0,0 +1,260 @@
+"""Query the shipped Resolve 21.1 typed stub from inside the server.
+
+PR #205 landed Blackmagic's `DaVinciResolveScript.pyi` in `docs/reference/`, and
+`scripts/audit_typed_api.py` can turn it into a full inventory — but only from a
+shell. An agent talking to this server had no way to ask what the native API
+contains. `resolve_control api_truth` answers "what is broken"; nothing answered
+"what exists".
+
+The official Blackmagic MCP exposes `search_scripting_api` for this. This is the
+equivalent, with one addition that matters more here: each result says whether
+**this server** references the method, and where. That turns a lookup into a
+parity check — "does the native API have it, and do we wrap it?" — which is the
+question that drove the whole 21.1 audit.
+
+Parsing is `ast`-based and reuses the same shapes as the audit script. Source
+references are executable syntax only: a method named in a docstring or comment
+is not counted as coverage.
+"""
+
+import ast
+import os
+import re
+from functools import lru_cache
+from typing import Any, Dict, List, Optional
+
+STUB_RELATIVE = os.path.join("docs", "reference", "DaVinciResolveScript.pyi")
+MAX_RESULTS = 200
+
+
+class TypedApiError(ValueError):
+    """The stub is missing, unparseable, or the query was unusable."""
+
+
+def stub_path(project_dir: str) -> str:
+    return os.path.join(project_dir, STUB_RELATIVE)
+
+
+@lru_cache(maxsize=4)
+def _inventory(path: str, mtime: float) -> Dict[str, Any]:
+    """Parse the stub into methods and TypedDicts. Cached on path plus mtime."""
+    with open(path, "r", encoding="utf-8") as handle:
+        text = handle.read()
+    methods: Dict[str, Any] = {}
+    option_types: Dict[str, Any] = {}
+    for cls in ast.parse(text).body:
+        if not isinstance(cls, ast.ClassDef):
+            continue
+        for node in cls.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and not node.name.startswith("_"):
+                signature = f"{node.name}({ast.unparse(node.args)})"
+                if node.returns is not None:
+                    signature += f" -> {ast.unparse(node.returns)}"
+                row = methods.setdefault(f"{cls.name}.{node.name}", {
+                    "object": cls.name,
+                    "method": node.name,
+                    "signatures": [],
+                    "stub_line": node.lineno,
+                    "description": ast.get_docstring(node),
+                })
+                row["signatures"].append(signature)
+        if any(ast.unparse(base).endswith("TypedDict") for base in cls.bases):
+            fields: Dict[str, Any] = {}
+            for index, node in enumerate(cls.body):
+                if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+                    doc = None
+                    if index + 1 < len(cls.body):
+                        following = cls.body[index + 1]
+                        if (isinstance(following, ast.Expr)
+                                and isinstance(following.value, ast.Constant)
+                                and isinstance(following.value.value, str)):
+                            doc = following.value.value
+                    fields[node.target.id] = {"type": ast.unparse(node.annotation),
+                                              "stub_line": node.lineno,
+                                              "description": doc}
+            option_types[cls.name] = fields
+    if not methods:
+        raise TypedApiError("The typed stub contains no public class methods; refusing an empty inventory")
+    return {"methods": methods, "option_types": option_types}
+
+
+def load(project_dir: str) -> Dict[str, Any]:
+    path = stub_path(project_dir)
+    if not os.path.isfile(path):
+        raise TypedApiError(
+            f"Typed API stub not found at {STUB_RELATIVE}. It ships with this "
+            "repository; a source checkout is required for API search."
+        )
+    return _inventory(path, os.path.getmtime(path))
+
+
+@lru_cache(maxsize=4)
+def _wrapped_names(project_dir: str, fingerprint: str) -> Dict[str, List[str]]:
+    """Map native method name -> source files that actually call or read it.
+
+    Executable syntax only. A name that appears solely in a docstring or comment
+    is not coverage, and counting it as such is exactly the mistake this whole
+    audit existed to avoid.
+    """
+    found: Dict[str, set] = {}
+    src_root = os.path.join(project_dir, "src")
+    for current, _dirs, files in os.walk(src_root):
+        for filename in files:
+            if not filename.endswith(".py"):
+                continue
+            absolute = os.path.join(current, filename)
+            try:
+                with open(absolute, "r", encoding="utf-8", errors="replace") as handle:
+                    tree = ast.parse(handle.read())
+            except (OSError, SyntaxError):
+                continue
+            relative = os.path.relpath(absolute, project_dir).replace(os.sep, "/")
+            for node in ast.walk(tree):
+                name = None
+                if isinstance(node, ast.Attribute):
+                    name = node.attr
+                elif (isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
+                      and node.func.id == "getattr" and len(node.args) > 1
+                      and isinstance(node.args[1], ast.Constant)
+                      and isinstance(node.args[1].value, str)):
+                    name = node.args[1].value
+                if name:
+                    found.setdefault(name, set()).add(relative)
+    return {name: sorted(paths) for name, paths in found.items()}
+
+
+def _source_fingerprint(project_dir: str) -> str:
+    """Cheap change detector for the source tree: newest mtime plus file count."""
+    newest = 0.0
+    count = 0
+    for current, _dirs, files in os.walk(os.path.join(project_dir, "src")):
+        for filename in files:
+            if filename.endswith(".py"):
+                count += 1
+                try:
+                    newest = max(newest, os.path.getmtime(os.path.join(current, filename)))
+                except OSError:
+                    pass
+    return f"{count}:{newest}"
+
+
+def search(project_dir: str, pattern: str, *, kind: str = "all",
+           limit: int = 50) -> Dict[str, Any]:
+    """Case-insensitive regex over method names, signatures, types and docs."""
+    if not isinstance(pattern, str) or not pattern.strip():
+        raise TypedApiError("pattern is required")
+    if kind not in ("all", "methods", "options"):
+        raise TypedApiError(f"kind must be all, methods or options, not {kind!r}")
+    try:
+        expression = re.compile(pattern, re.IGNORECASE)
+    except re.error as exc:
+        raise TypedApiError(f"pattern is not a valid regular expression: {exc}")
+    try:
+        limit = max(1, min(int(limit), MAX_RESULTS))
+    except (TypeError, ValueError):
+        raise TypedApiError("limit must be an integer")
+
+    inventory = load(project_dir)
+    wrapped = _wrapped_names(project_dir, _source_fingerprint(project_dir))
+
+    methods: List[Dict[str, Any]] = []
+    if kind in ("all", "methods"):
+        for key, row in sorted(inventory["methods"].items()):
+            haystack = " ".join([key] + row["signatures"] + [row["description"] or ""])
+            if not expression.search(haystack):
+                continue
+            references = wrapped.get(row["method"], [])
+            methods.append({
+                "symbol": key,
+                "object": row["object"],
+                "signatures": row["signatures"],
+                "stub_line": row["stub_line"],
+                "description": row["description"],
+                "referenced_in_this_server": bool(references),
+                "source_files": references[:5],
+            })
+
+    options: List[Dict[str, Any]] = []
+    if kind in ("all", "options"):
+        for type_name, fields in sorted(inventory["option_types"].items()):
+            matched = {
+                field: detail for field, detail in fields.items()
+                if expression.search(" ".join([type_name, field, detail["type"],
+                                               detail["description"] or ""]))
+            }
+            if expression.search(type_name):
+                matched = dict(fields)
+            if matched:
+                options.append({
+                    "type": type_name,
+                    "field_count": len(fields),
+                    "matched_fields": matched,
+                })
+
+    total = len(methods) + len(options)
+    return {
+        "pattern": pattern,
+        "kind": kind,
+        "total_matches": total,
+        "truncated": total > limit,
+        "methods": methods[:limit],
+        "option_types": options[:limit],
+        "stub": STUB_RELATIVE,
+        "note": ("referenced_in_this_server is executable syntax only — a name that "
+                 "appears solely in a docstring or comment is not counted."),
+    }
+
+
+def describe(project_dir: str, symbol: str) -> Dict[str, Any]:
+    """Full detail for one `Class.Method` or one TypedDict name."""
+    if not isinstance(symbol, str) or not symbol.strip():
+        raise TypedApiError("symbol is required")
+    inventory = load(project_dir)
+    key = symbol.strip()
+
+    if key in inventory["option_types"]:
+        fields = inventory["option_types"][key]
+        return {"symbol": key, "kind": "option_type", "field_count": len(fields),
+                "fields": fields, "stub": STUB_RELATIVE}
+
+    row = inventory["methods"].get(key)
+    if row is None:
+        candidates = sorted(k for k in inventory["methods"] if k.split(".", 1)[1] == key)
+        if len(candidates) == 1:
+            key, row = candidates[0], inventory["methods"][candidates[0]]
+        elif candidates:
+            raise TypedApiError(
+                f"{symbol!r} exists on more than one object: {', '.join(candidates)}. "
+                "Qualify it, e.g. 'Project.GetName'."
+            )
+        else:
+            raise TypedApiError(
+                f"{symbol!r} is not in the Resolve 21.1 typed stub. Use search to "
+                "find the right name."
+            )
+
+    wrapped = _wrapped_names(project_dir, _source_fingerprint(project_dir))
+    references = wrapped.get(row["method"], [])
+    return {
+        "symbol": key,
+        "kind": "method",
+        "object": row["object"],
+        "signatures": row["signatures"],
+        "stub_line": row["stub_line"],
+        "description": row["description"],
+        "referenced_in_this_server": bool(references),
+        "source_files": references,
+        "stub": STUB_RELATIVE,
+    }
+
+
+def summary(project_dir: str) -> Dict[str, Any]:
+    inventory = load(project_dir)
+    field_total = sum(len(fields) for fields in inventory["option_types"].values())
+    return {
+        "stub": STUB_RELATIVE,
+        "methods": len(inventory["methods"]),
+        "option_types": len(inventory["option_types"]),
+        "option_fields": field_total,
+        "objects": sorted({row["object"] for row in inventory["methods"].values()}),
+    }