RenderDoc MCP

Позволяет AI-клиентам с поддержкой Model Context Protocol (MCP) напрямую анализировать файлы захвата RenderDoc: просматривать события Draw/Dispatch, проверять состояние конвейера и шейдеры, а также читать постранично данные вершин и константных буферов.

Репозиторий содержит работающий MCP stdio-сервис, границы безопасности для сессий и путей, Mock-бэкенд для разработки и тестирования, а также реальный мостовой Replay-бэкенд, подключающийся к qrenderdoc 1.44.

[!IMPORTANT] Сейчас для подключения к реальным захватам рекомендуется использовать бэкенд qrenderdoc; бэкенды renderdoc / native остаются зарезервированными реализациями.

Реальный мост состоит из двух процессов: современного Python 3.11 MCP Gateway и UI-расширения, работающего во встроенном Python 3.6 qrenderdoc. Они обмениваются данными через локальную файловую очередь по JSON-протоколу со случайным токеном; это исключает зависимость от модуля _socket, отсутствующего в урезанном Python RenderDoc.

MCP Client  <-- stdio -->  Python 3.11 Gateway
                                  |
                         authenticated JSON spool
                                  |
                           qrenderdoc extension
                                  |
                         RenderDoc ReplayController

Доступные возможности

• MCP stdio-сервис со структурированными ответами инструментов.

• Белый список путей для .rdc, ограничения по типу файла, размеру и числу сессий.

• Запуск отдельных .exe из белого списка через инъекцию RenderDoc; аргументы передаются массивом, без shell.

• Стабильный capture_id, явный event_id, без зависимости от скрытого текущего выбранного события.

• Последовательный доступ к бэкенду для каждого capture, соблюдающий границы потоковой модели RenderDoc ReplayController.

• Фильтрация Action и постраничная навигация через курсор.

• Композитный вызов inspect_event, чтобы избежать множества мелких MCP-запросов при одной проверке.

• Чтение топологии, viewport/scissor, шейдеров, привязки ресурсов, целей рендеринга и сообщений валидации текущего события.

• Единая структура ошибок и пассивный capture summary Resource.

Первые инструменты:

• health

• launch_program

• open_capture

• close_capture

• get_capture_summary

• list_actions

• get_event

• inspect_event

• get_pipeline_state

• get_shader

• get_vertex_data

• list_constant_buffers

• get_constant_buffer

Данные Pipeline, Shader и Buffer

• get_pipeline_state без передачи section возвращает общий снимок для всех API и api_specific_sections; повторный вызов с именем любой из этих секций в качестве section читает полные группы состояния верхнего уровня для D3D11, D3D12, Vulkan или OpenGL.

• get_shader читает по стадиям reflection, disassembly, source или raw. Для последних трёх типов объёмного содержимого используется постраничная выдача через cursor / next_cursor; source_file_index позволяет перебирать каждый встроенный файл исходного кода.

• get_vertex_data раскладывает инстансы и вершины draw в стабильные записи и возвращает декодированные значения всех атрибутов, точный raw_hex, фактическое смещение в буфере и метаданные формата; uv_attributes явно помечает UV / TEXCOORD. Постоянно следуя за next_cursor, можно охватить все инстансы и вершины.

• list_constant_buffers перечисляет каждую шейдерную стадию, блок отражения и элемент массива; затем get_constant_buffer читает все декодированные переменные этой группы. Лежащие в основе сырые байты разбиваются на страницы через raw_offset / next_offset, поэтому данные не теряются даже при превышении лимита одного чтения.

Related MCP server: RenderDoc MCP Server

Окружение

• Python 3.11+

• Стабильная линия MCP Python SDK >=1.27,<2

• RenderDoc/qrenderdoc 1.44 (реальный мостовой бэкенд)

SDK v2 всё ещё находится на стадии предварительного релиза, поэтому проект временно зафиксирован на v1.x, чтобы код фреймворка не менялся вместе с предрелизными интерфейсами.

Быстрый старт (Mock-бэкенд)

В PowerShell:

python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
$env:RENDERDOC_MCP_BACKEND = "mock"
$env:RENDERDOC_MCP_ALLOWED_ROOTS = (Get-Location).Path
.venv\Scripts\python -m renderdoc_mcp

stdio — это протокольный канал, обычные логи не должны записываться в stdout.

С MCP Inspector:

.venv\Scripts\mcp dev src\renderdoc_mcp\server.py

Mock-бэкенд по-прежнему требует передать реально существующий путь .rdc, находящийся в белом списке, но не разбирает содержимое файла.

Установка моста qrenderdoc

Предположим, RenderDoc установлен в C:\Tools\RenderDoc. В каталоге проекта выполните:

powershell -ExecutionPolicy Bypass -File .\scripts\install_qrenderdoc_bridge.ps1 `
  -RenderDocRoot C:\Tools\RenderDoc

Скрипт:

• установит расширение в %APPDATA%\qrenderdoc\extensions\renderdoc_mcp_bridge;

• сгенерирует случайный токен и запишет его в bridge_config.json на стороне расширения;

• создаст в корне проекта .renderdoc-mcp-bridge.json для использования Gateway.

Затем откройте C:\Tools\RenderDoc\qrenderdoc.exe, перейдите в Tools → Manage Extensions, выберите RenderDoc MCP Bridge, нажмите Load и после успешной загрузки отметьте Always Load. При использовании реального бэкенда qrenderdoc должен оставаться запущенным; каталог очереди по умолчанию — .renderdoc-mcp-spool внутри проекта, игнорируемый Git.

Для разработки можно также попросить qrenderdoc автоматически выполнить скрипт загрузки один раз после открытия UI:

C:\Tools\RenderDoc\qrenderdoc.exe --ui-python .\scripts\load_qrenderdoc_bridge.py

Эта команда отвечает только за однократную загрузку; для повседневной работы по-прежнему рекомендуется отмечать Always Load в менеджере расширений.

Пример конфигурации MCP-клиента

Замените пути на фактические расположения:

{
  "mcpServers": {
    "renderdoc": {
      "command": "C:\\path\\to\\RenderDoc_MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "renderdoc_mcp"],
      "env": {
        "RENDERDOC_MCP_BACKEND": "qrenderdoc",
        "RENDERDOC_MCP_ALLOWED_ROOTS": "C:\\captures",
        "RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS": "C:\\projects\\my-renderer",
        "RENDERDOC_MCP_ARTIFACT_ROOT": "C:\\path\\to\\RenderDoc_MCP\\artifacts",
        "RENDERDOC_MCP_RENDERDOC_ROOT": "C:\\Tools\\RenderDoc"
      },
      "cwd": "C:\\path\\to\\RenderDoc_MCP"
    }
  }
}

На странице графической конфигурации Codex аргументы нужно разбить на две строки: -m и renderdoc_mcp. Передача переменных окружения остаётся пустой; в поле Working directory укажите корень проекта. Так как в рабочем каталоге уже есть .renderdoc-mcp-bridge.json, вручную вставлять токен в конфигурацию MCP не нужно.

Параметры конфигурации

Запуск программы из RenderDoc

Сначала добавьте корень проекта вашей программы в RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS, перезапустите MCP-сервис, затем вызовите:

{
  "executable": "C:\\projects\\my-renderer\\bin\\renderer.exe",
  "arguments": ["--scene", "C:\\projects\\my-renderer\\scenes\\demo.json"],
  "working_directory": "C:\\projects\\my-renderer",
  "hook_into_children": false,
  "api_validation": false
}

В случае успеха результат содержит ident target-control RenderDoc и шаблон файла capture. Программа уже внедрена через RenderDoc, и в её окне можно нажать клавишу F12 (по умолчанию) для захвата кадра. Инструмент не принимает shell-команды и не допускает изменения переменных окружения; включайте hook_into_children, только если требуется внедрение также в дочерние процессы, а api_validation — только если нужен слой проверки API.

Тестирование

После установки зависимостей для разработки:

.venv\Scripts\python -m pytest
.venv\Scripts\ruff check .

Основные тесты сервиса можно запустить и без установки сторонних тестовых зависимостей:

$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v

Границы безопасности

• Можно открывать только файлы .rdc из RENDERDOC_MCP_ALLOWED_ROOTS.

• launch_program по умолчанию отключён; разрешён запуск только .exe из RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS.

• Аргументы запуска передаются массивом, минуя shell; Gateway не позволяет изменять переменные окружения целевой программы через инструменты.

• Локальные сообщения между Gateway и расширением qrenderdoc аутентифицируются случайным токеном, сгенерированным при установке.

• Для данных Action, Shader, вершин и Buffer действуют ограничения постраничной выдачи или лимита одного чтения.

Статус проекта и дальнейшие шаги

Основной путь моста, Pipeline state, Shader, вершинные входы и чтение константных буферов уже реализованы. В дальнейшем по задачам целесообразно добавить экспорт Texture, универсальный readback Buffer, Pixel History и управление артефактами.

Подробные границы см. в описании архитектуры.

License

MIT