Fusion Studio MCP

Локальный MCP-сервер для просмотра и управления автономным Blackmagic Fusion Studio через скриптовый API Fusion.

Проект начинается консервативно: сначала проверить подключение к Fusion, затем добавить инструменты только для чтения, а затем добавить защищённые инструменты редактирования с поведением dry-run и отмены.

Текущий статус

• Каркас проекта создан: 2026-07-13

• Целевое приложение найдено: Blackmagic Fusion 21.0.2

• Путь импорта Python подтверждён для встроенного fusionscript.so Fusion

• Проверка живого композита подтверждена для Composition1

• Локальный .venv создан с pytest, ruff и Python MCP SDK

• Инструменты MCP только для чтения реализованы для статуса, списка узлов, поиска одного узла, чтения выбранных узлов и компактных сводок композиции

• Защищённые инструменты редактирования MCP реализованы для выбора, чтения/записи входов, переименования и позиционирования FlowView

• Контролируемое создание узлов, редактирование подключений изображений, отключение входов, проверка подключений и подтверждённое удаление одного узла реализованы

• Настраиваемое создание узлов, а также нативные инструменты для ключевых кадров и выражений реализованы

• Управление композицией, а также транзакционные графовые и пакетные инструменты реализованы

• Проверка рендера, настройки Saver, диагностика, каталог инструментов/схемы и инструменты экспорта графа реализованы

• Проверка живого редактирования пройдена на одноразовом Composition1

Related MCP server: nuke-mcp

Требования

• macOS

• Blackmagic Fusion Studio 21.0.2 или совместимая версия

• Требуется Python 3.11+ (requires-python = ">=3.11"); встроенный Python 3.9 в macOS слишком старый

• Доступен путь к встроенной библиотеке скриптов Fusion: /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

• Python MCP SDK для серверного режима

Установка с Claude Desktop на macOS

Рекомендуется для художников и не-разработчиков: Установка Fusion Studio MCP - Claude Desktop (macOS).

Это публичный путь установки в два шага с копированием и вставкой для автономного Fusion Studio и Claude Desktop на macOS. Он устанавливает из публичного репозитория GitHub: https://github.com/bigsbypuglise/fusion-studio-mcp

Используйте этот путь, если вы хотите, чтобы Claude Desktop проверял композицию Fusion, перечислял узлы и строил защищённые деревья узлов без настройки для разработчика.

Краткая версия:

1. Откройте Fusion Studio 21 и откройте или создайте композицию.

2. Выполните вставку установки из руководства по Claude Desktop для macOS.

3. Выполните вставку конфигурации Claude из руководства.

4. Полностью завершите Claude Desktop с помощью Command-Q, снова откройте его и попросите Claude проверить подключение к Fusion.

Примечания:

• Рекомендуется Fusion Studio 21; Fusion Studio 20 может работать.

• В настоящее время это нацелено на автономный Fusion Studio, а не на DaVinci Resolve.

• Fusion Studio должен быть запущен с открытой активной композицией.

• Первый вызов инструмента Claude может запросить разрешение.

• Установщик по умолчанию для новичков отслеживает последнюю публичную ветку main, поэтому повторный запуск вставки №1 обновляет локальную установку. Пользователи, предпочитающие закреплённый стабильный релиз, могут использовать опцию тегированного релиза в руководстве.

Расширенная установка

Рабочий процесс macOS ниже был протестирован вживую с Fusion Studio 21.0.2. Рабочий процесс Windows документирован для эквивалентных установок Fusion Studio, но всё ещё требует проверки на чистой машине Windows.

Настройка для разработчика на macOS

Поддерживаемая протестированная среда:

• Blackmagic Fusion Studio 21.0.2

• Python 3.11+

• Подтверждённый путь приложения: /Applications/Blackmagic Fusion 21/Fusion.app

• Подтверждённый путь библиотеки скриптов: /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

Установите Python с помощью Homebrew, если необходимо:

brew install python@3.11

Создайте и установите локальную среду:

cd /path/to/fusion-studio-mcp
PYTHON_BIN=/opt/homebrew/bin/python3.11 scripts/setup_local.sh

Или сделайте это вручную:

cd /path/to/fusion-studio-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

Запустите Fusion Studio, создайте или откройте одноразовую композицию, затем выполните:

export PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src"
python scripts/test_fusion_connection.py
python -m fusion_mcp.server

python -m fusion_mcp.server — это точка входа MCP-сервера stdio. Он предназначен для запуска MCP-клиентом; при прямом запуске в обычном терминале без подключённого клиента он может корректно завершиться после закрытия stdin. Используйте scripts/test_fusion_connection.py для автономного смоук-теста подключения.

Пример MCP-клиента на macOS:

{
  "mcpServers": {
    "fusion-studio": {
      "command": "/path/to/fusion-studio-mcp/.venv/bin/python",
      "args": ["-m", "fusion_mcp.server"],
      "env": {
        "PYTHONPATH": "/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:/path/to/fusion-studio-mcp/src"
      }
    }
  }
}

Устранение неполадок на macOS:

• Если Fusion закрыт или нет активной композиции, инструменты подключения возвращают FUSION_NOT_RUNNING или NO_ACTIVE_COMP.

• Если fusionscript не импортируется, убедитесь, что PYTHONPATH включает путь Contents/Libraries Fusion.

• macOS может показывать запросы безопасности при первом взаимодействии инструментов с другим приложением. Разрешите Fusion и терминалу/MCP-клиенту обмениваться данными локально.

• Используйте уникальные абсолютные выходные папки для рендеров Saver, чтобы избежать защиты от перезаписи и проблем с именами файлов Fusion.

Настройка для разработчика на Windows

Документированная целевая среда:

• Blackmagic Fusion Studio 21.0.2 или совместимая версия

• Python 3.11+

• Обычный путь приложения: C:\Program Files\Blackmagic Design\Fusion 21\Fusion.exe

• Обычный путь библиотеки скриптов: C:\Program Files\Blackmagic Design\Fusion 21

Установите Python с https://www.python.org/downloads/windows/ и включите "Add python.exe to PATH", или установите с помощью winget:

winget install Python.Python.3.11
python --version
py -3.11 --version

Создайте и установите локальную среду из PowerShell:

cd C:\path\to\fusion-studio-mcp
.\scripts\setup_local.ps1 -Python py -PythonArgs "-3.11"
.\.venv\Scripts\Activate.ps1

Если PowerShell блокирует скрипт, запустите его только для текущего процесса:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\setup_local.ps1 -Python py -PythonArgs "-3.11"

Ручная настройка в командной строке:

cd C:\path\to\fusion-studio-mcp
py -3.11 -m venv .venv
.venv\Scripts\activate.bat
python -m pip install --upgrade pip
python -m pip install -e .[dev]

Запустите Fusion Studio, создайте или откройте одноразовую композицию, затем выполните из PowerShell:

.\.venv\Scripts\Activate.ps1
$env:PYTHONPATH = "C:\Program Files\Blackmagic Design\Fusion 21;C:\path\to\fusion-studio-mcp\src"
.\.venv\Scripts\python.exe .\scripts\test_fusion_connection.py
.\.venv\Scripts\python.exe -m fusion_mcp.server

Как и на macOS, команда сервера предназначена для запуска MCP-клиентом через stdio. Если она запущена вручную в оболочке без подключённого клиента, она может завершиться при закрытии stdin.

Пример MCP-клиента на Windows:

{
  "mcpServers": {
    "fusion-studio": {
      "command": "C:\\path\\to\\fusion-studio-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "fusion_mcp.server"],
      "env": {
        "PYTHONPATH": "C:\\Program Files\\Blackmagic Design\\Fusion 21;C:\\path\\to\\fusion-studio-mcp\\src"
      }
    }
  }
}

Устранение неполадок на Windows:

• Эти шаги для Windows документированы, но ещё не проверены вживую на чистой машине Windows.

• Если python не найден, используйте py -3.11 или переустановите Python с включённой интеграцией PATH.

• Если fusionscript не импортируется, проверьте путь установки Fusion и добавьте его каталог скриптов в PYTHONPATH.

• Заключайте пути с пробелами в кавычки в PowerShell и JSON; используйте удвоенные обратные слэши в строках JSON.

• Если подключение не удаётся, убедитесь, что Fusion Studio открыт, не заблокирован запросами безопасности Windows и имеет активную композицию.

• Используйте абсолютные пути вывода Saver в доступных для записи папках и предпочитайте уникальные выходные папки для каждого рендера.

Быстрая проверка подключения

1. Откройте автономный Fusion Studio.

2. Откройте или создайте одноразовую композицию.

3. Выполните:

cd /path/to/fusion-studio-mcp
PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python scripts/test_fusion_connection.py

Скрипт выводит структурированный JSON. Если Fusion закрыт, он должен вернуть success: false с FUSION_NOT_RUNNING.

Зонд проверки только для чтения

Запустите все функции инструментов только для чтения без запуска MCP-клиента:

cd /path/to/fusion-studio-mcp
PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python scripts/inspect_read_only.py

Текущие инструменты только для чтения:

• fusion_get_status_tool

• fusion_list_nodes_tool

• fusion_get_node_tool(node_name)

• fusion_get_selected_nodes_tool

• fusion_summarize_comp_tool

• fusion_get_node_input_tool(node_name, input_name)

Записи списка узлов включают:

• Имя узла и тип инструмента Fusion

• Позицию во Flow из comp.CurrentFrame.FlowView.GetPosTable(tool), когда Fusion её предоставляет

• Входы с ID, именем, типом данных, текущим не-изображением значением, подключённым выходом и атрибутами входа

• Выходы с ID, именем, типом данных, подключёнными входами и атрибутами выхода

• Сводку ключевых настроек для не-изображений контролов

Запуск MCP-сервера

После настройки выполните:

cd /path/to/fusion-studio-mcp
PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python -m fusion_mcp.server

Пример операций в стиле MCP:

fusion_get_status_tool()
fusion_list_nodes_tool()
fusion_get_node_tool(node_name="Blur1")
fusion_get_selected_nodes_tool()
fusion_summarize_comp_tool()
fusion_select_nodes_tool(node_names=["Background1", "Transform1"])
fusion_get_node_input_tool(node_name="Transform1", input_name="Blend")
fusion_set_node_input_tool(node_name="Transform1", input_name="Blend", value=0.5)
fusion_set_node_name_tool(node_name="Transform1", new_name="Transform_Main")
fusion_set_node_position_tool(node_name="Transform_Main", x=0, y=0)
fusion_create_node_tool(tool_id="Blur", name="Blur_Main", x=1, y=0)
fusion_create_node_tool(
  tool_id="Saver",
  name="Saver_Main",
  x=2,
  y=0,
  settings={"Clip": "/tmp/example.exr"}
)
fusion_connect_nodes_tool(
  source_node="Transform_Main",
  source_output="Output",
  target_node="Blur_Main",
  target_input="Input",
  replace=false
)
fusion_get_connections_tool(node_name="Blur_Main")
fusion_disconnect_input_tool(node_name="Blur_Main", input_name="Input")
fusion_delete_node_tool(node_name="Blur_Main", confirm=true)
fusion_set_keyframe_tool(node_name="Transform_Main", input_name="Size", frame=0, value=1.0, replace=false)
fusion_get_keyframes_tool(node_name="Transform_Main", input_name="Size")
fusion_delete_keyframe_tool(node_name="Transform_Main", input_name="Size", frame=10, confirm=true)
fusion_clear_keyframes_tool(node_name="Transform_Main", input_name="Center", confirm=true)
fusion_set_expression_tool(node_name="Transform_Main", input_name="Angle", expression="time/10", replace=false)
fusion_get_expression_tool(node_name="Transform_Main", input_name="Angle")
fusion_remove_expression_tool(node_name="Transform_Main", input_name="Angle", confirm=true)
fusion_get_comp_settings_tool()
fusion_set_comp_range_tool(start_frame=1, end_frame=48)
fusion_set_current_frame_tool(frame=24)
fusion_get_current_frame_tool()
fusion_save_comp_tool(path="/tmp/example.comp")
fusion_get_comp_path_tool()
fusion_create_graph_tool(
  nodes=[
    {"id": "bg", "tool_id": "Background", "name": "BG", "x": -4, "y": 0,
     "settings": {"TopLeftRed": 0.2, "TopLeftGreen": 0.4, "TopLeftBlue": 0.8}},
    {"id": "tx", "tool_id": "Transform", "name": "TX", "x": -2, "y": 0},
    {"id": "blur", "tool_id": "Blur", "name": "Blur", "x": 0, "y": 0,
     "settings": {"XBlurSize": 3.0}},
    {"id": "saver", "tool_id": "Saver", "name": "Saver", "x": 2, "y": 0,
     "settings": {"Clip": "/tmp/example.exr"}}
  ],
  connections=[
    {"source": "bg", "target": "tx", "source_output": "Output", "target_input": "Input"},
    {"source": "tx", "target": "blur", "source_output": "Output", "target_input": "Input"},
    {"source": "blur", "target": "saver", "source_output": "Output", "target_input": "Input"}
  ],
  comp_settings={"start_frame": 1, "end_frame": 48}
)
fusion_batch_set_inputs_tool(changes=[{"node_name": "BG", "input_name": "TopLeftRed", "value": 0.5}])
fusion_batch_set_keyframes_tool(keyframes=[{"node_name": "TX", "input_name": "Size", "frame": 1, "value": 1.0}])
fusion_batch_delete_nodes_tool(node_names=["Blur"], confirm=true)
fusion_get_saver_settings_tool(node_name="Saver")
fusion_set_saver_settings_tool(node_name="Saver", settings={"Clip": "/tmp/render.exr"})
fusion_validate_render_tool(saver_node="Saver", allow_overwrite=false)
fusion_render_tool(start_frame=1, end_frame=1, saver_node="Saver", confirm=true, allow_overwrite=false)
fusion_get_render_status_tool()
fusion_abort_render_tool(confirm=true)
fusion_validate_comp_tool()
fusion_find_broken_connections_tool()
fusion_find_missing_media_tool()
fusion_get_tool_catalog_tool(search="blur")
fusion_get_tool_schema_tool(tool_id="Blur")
fusion_export_graph_tool(node_names=["BG", "TX", "Saver"])
fusion_validate_graph_request_tool(nodes=[...], connections=[...], comp_settings={...})

Пример компактного сводного ответа от живого пустого Composition1:

{
  "success": true,
  "operation": "fusion_summarize_comp",
  "agent_summary": {
    "composition_name": "Composition1",
    "node_count": 0,
    "selected_nodes": [],
    "tool_type_counts": {},
    "plain_english": "Composition Composition1 has 0 node(s); 0 selected."
  }
}

Безопасные инструменты редактирования

Операции редактирования проверяют активную композицию, узел и вход перед изменением чего-либо. Записи используют Lock(), StartUndo(...), EndUndo(True) и Unlock() Fusion через защищённую обёртку очистки, чтобы неудачные операции не оставляли открытую группу отмены.

Реализованные инструменты редактирования:

• fusion_select_nodes_tool(node_names)

• fusion_get_node_input_tool(node_name, input_name)

• fusion_set_node_input_tool(node_name, input_name, value)

• fusion_set_node_name_tool(node_name, new_name)

• fusion_set_node_position_tool(node_name, x, y)

• fusion_create_node_tool(tool_id, name=None, x=None, y=None)

• fusion_connect_nodes_tool(source_node, source_output, target_node, target_input, replace=False)

• fusion_disconnect_input_tool(node_name, input_name)

• fusion_get_connections_tool(node_name=None)

• fusion_delete_node_tool(node_name, confirm=False)

• fusion_set_keyframe_tool(node_name, input_name, frame, value, replace=False)

• fusion_get_keyframes_tool(node_name, input_name)

• fusion_delete_keyframe_tool(node_name, input_name, frame, confirm=False)

• fusion_clear_keyframes_tool(node_name, input_name, confirm=False)

• fusion_set_expression_tool(node_name, input_name, expression, replace=False)

• fusion_get_expression_tool(node_name, input_name)

• fusion_remove_expression_tool(node_name, input_name, confirm=False)

• fusion_get_comp_settings_tool()

• fusion_set_comp_range_tool(start_frame, end_frame)

• fusion_set_current_frame_tool(frame)

• fusion_get_current_frame_tool()

• fusion_save_comp_tool(path=None)

• fusion_get_comp_path_tool()

• fusion_create_graph_tool(nodes, connections, comp_settings=None)

• fusion_batch_set_inputs_tool(changes)

• fusion_batch_set_keyframes_tool(keyframes)

• fusion_batch_delete_nodes_tool(node_names, confirm=False)

• fusion_get_saver_settings_tool(node_name)

• fusion_set_saver_settings_tool(node_name, settings)

• fusion_validate_render_tool(saver_node=None, allow_overwrite=False)

• fusion_render_tool(start_frame=None, end_frame=None, saver_node=None, confirm=False, allow_overwrite=False)

• fusion_get_render_status_tool()

• fusion_abort_render_tool(confirm=False)

• fusion_validate_comp_tool()

• fusion_find_broken_connections_tool()

• fusion_find_missing_media_tool()

• fusion_get_tool_catalog_tool(search=None)

• fusion_get_tool_schema_tool(tool_id)

• fusion_export_graph_tool(node_names=None)

• fusion_validate_graph_request_tool(nodes, connections, comp_settings=None)

fusion_set_node_input_tool поддерживает распространённые типы значений Fusion:

• конечные скалярные числа

• логические значения, преобразуемые в 1 или 0 для числовых входов Fusion

• строки для входов Text

• строки для входов FuID, проверяемые по доступным вариантам входа, когда Fusion их предоставляет

• точки как [x, y] или {"x": x, "y": y}

• цвета как [r, g, b], [r, g, b, a] или соответствующие ключи словаря, когда Fusion предоставляет настоящий вход Color

Неподдерживаемые или неоднозначные значения возвращают структурированную ошибку и не пытаются выполнить запись. Входы изображений отклоняются инструментами установки значений, поскольку их нужно редактировать как подключения, а не как скалярные значения.

Встроенные контроли цвета Background в Fusion Studio 21.0.2 представлены как отдельные числовые каналы входов, такие как TopLeftRed, TopLeftGreen, TopLeftBlue и TopLeftAlpha, каждый с INPID_InputControl == "ColorControl" и INPS_DataType == "Number". Живая проверка подтвердила установку этих каналов скалярными числами с плавающей точкой, например TopLeftRed = 0.25.

Пример успешного ответа:

{
  "success": true,
  "operation": "fusion_set_node_input",
  "node_name": "FMC_Test_Transform",
  "input_id": "Size",
  "previous_value": 1.0,
  "requested_value": 0.8,
  "confirmed_value": 0.8,
  "summary": "Set FMC_Test_Transform.Size."
}

Пример ошибки проверки:

{
  "success": false,
  "operation": "fusion_set_node_input",
  "error_code": "UNSUPPORTED_INPUT_VALUE",
  "error_message": "Image inputs are connections, not scalar values.",
  "node_name": "FMC_Test_Transform",
  "input_id": "Input",
  "requested_value": 1
}

Инструменты подключения и узлов

fusion_create_node_tool принимает необязательный параметр settings, применяемый после создания и проверки узла. Сбои настройки дают частичный результат: созданный узел остаётся в композиции, успешные настройки сообщаются, а неудачные настройки включают коды ошибок для каждого входа. Saver может получить путь Clip через settings={"Clip": "/path/to/output.exr"} и больше не требует заполнителя, когда эта настройка указана.

Редактирование подключений в настоящее время ограничено связями потока изображений. Слой инструментов отклоняет модификатор, выражение, маску и скалярные связи с явными метаданными сокета, а не притворяется, что они обычные каналы изображений.

Поведение безопасности:

• ID инструментов проверяются по локальному реестру Fusion перед созданием

• MediaOut отклоняется в автономном Fusion, потому что его класс реестра там не создаётся

• Saver можно создать с явным путём Clip-заполнителя, чтобы избежать открытия диалога выбора файла Fusion

• целевые входы не заменяются, если только replace=true

• самоподключения и очевидные циклы потока изображений отклоняются

• удаление требует confirm=true и принимает только одно имя узла за вызов

• все операции создания/подключения/отключения/удаления используют группы отмены Fusion

Пример успешного подключения:

{
  "success": true,
  "operation": "fusion_connect_nodes",
  "previous_state": null,
  "requested_state": {
    "source_node": "Background1",
    "source_output": "Output",
    "target_node": "Transform1",
    "target_input": "Input",
    "replace": false
  },
  "confirmed_state": {
    "node": "Background1",
    "output": "Output",
    "data_type": "Image"
  }
}

Пример защиты удаления:

{
  "success": false,
  "operation": "fusion_delete_node",
  "error_code": "DELETE_CONFIRMATION_REQUIRED",
  "error_message": "Deletion requires confirm=true."
}

Композиция и пакетные инструменты

Элементы управления композицией предоставляют диапазон кадров, текущий кадр, путь сохранения и явные сохранения .comp. Живая проверка подтвердила, что fusion_set_comp_range_tool(1, 48), fusion_set_current_frame_tool(24) и fusion_save_comp_tool("/tmp/fusionmcp_batch_*.comp") работают в автономном Fusion Studio 21.0.2.

fusion_create_graph_tool принимает:

• nodes: объекты с id, tool_id или tool_type, необязательными name, x/y и settings

• connections: объекты с идентификаторами узлов графа в source/target, плюс source_output и target_input

• comp_settings: в настоящее время поддерживает start_frame/end_frame или global_start/global_end

Создание графа проверяет дубликаты имён, отсутствующие ссылки на граф, недопустимые идентификаторы инструментов, очевидные циклы и неподдерживаемые значения до или во время транзакции. Сначала создаются узлы, затем применяются настройки, а после этого соединяются сокеты изображений. Если последующий шаг завершается с ошибкой, предпринимается попытка отключить связи, созданные этим запросом, и удалить только узлы, созданные этим запросом, возвращая status: "rolled_back" с результатами отката по каждому элементу.

Пакетные инструменты для ввода/ключевых кадров/удаления используют одну группу отмены Fusion на пакет. Пакетное удаление требует confirm=true и удаляет только явно перечисленные узлы.

Рендеринг, диагностика и экспорт

Выполнение рендеринга требует confirm=true. fusion_validate_render_tool проверяет активное состояние композиции, наличие/тип Saver, абсолютный путь вывода, поддерживаемое расширение файла, отсутствие выходного каталога, риск перезаписи, допустимый диапазон кадров и подключённый вход изображения Saver без намеренного рендеринга. Существующие выходные данные возвращают OUTPUT_ALREADY_EXISTS, если явно не указано allow_overwrite=true.

fusion_render_tool с конкретным saver_node использует каноническую подтверждённую вживую транзакцию Saver: он сохраняет исходный объект Saver, не перезаписывает Clip, не опрашивает статус рендеринга перед рендерингом, вызывает comp.Render один раз с Start, End, Wait и Tool, а затем подтверждает выходные файлы по пути Clip Saver на диске. Если Fusion сообщает о завершении, но ожидаемый выходной файл не появляется, инструмент возвращает RENDER_OUTPUT_MISSING с деталями трассировки рендеринга.

Диагностика включает проверки диапазона композиции, отключённые обязательные входы изображений, отсутствующие пути Loader, недопустимые пути Saver, выражения, вычисляемые в None, неразрешённые идентификаторы инструментов и дубликаты имён, если их можно обнаружить.

fusion_export_graph_tool выдаёт fusionmcp.graph.v1 с точными идентификаторами инструментов, идентификаторами входов, безопасными настройками, позициями FlowView, соединениями потоков изображений и нативными ключевыми кадрами, где их можно безопасно прочитать.

Анимация и выражения

Нативные ключевые кадры используют собственные модификаторы Fusion:

• скалярные входы используют BezierSpline

• точечные входы используют Path

• выражения используют input.SetExpression(...)

Инструменты различают состояния static, keyframed, expression и другие modifier. Они отклоняют молчаливые перезаписи: установка ключевого кадра на выраженческий вход, установка выражения на вход с ключевыми кадрами или установка дублирующего ключевого кадра возвращает структурированную ошибку. Удаление данных анимации/выражений требует confirm=true.

Подтверждённые вживую примеры:

{
  "success": true,
  "operation": "fusion_get_keyframes",
  "keyframes": [
    { "frame": 0.0, "value": 1.0 },
    { "frame": 20.0, "value": 3.0 }
  ],
  "state": {
    "state_type": "keyframed",
    "modifier_type": "BezierSpline"
  }
}

Плохие выражения отклоняются, когда Fusion принимает строку выражения, но оно вычисляется в None на текущем кадре.

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

Запустите модульные тесты и линтер:

cd /path/to/fusion-studio-mcp
.venv/bin/python -m pytest
.venv/bin/python -m ruff check src tests scripts

Запускайте опциональные живые тесты только на одноразовой активной композиции Fusion:

RUN_FUSION_LIVE_TESTS=1 PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python -m pytest tests/test_live_editing.py tests/test_live_connections.py tests/test_live_animation.py -q

Безопасность

Инструменты записи намеренно изменяют активную композицию. Используйте их только на одноразовых или явно одобренных композициях, пока не будут добавлены более широкие производственные меры защиты.

Read-only инспекция намеренно не вызывает Output.GetValue(), потому что это может запустить вышестоящий рендеринг. Инспекция вывода только читает атрибуты вывода и метаданные соединений.

Производственные композиции не следует использовать для интеграционного тестирования.

Автономный Fusion Studio 21.0.2 рассматривает MediaOut как специфичный для Resolve в этом проекте. Автономный Fusion не требует конечного узла. Saver поддерживается как обычный автономный инструмент при создании без дефолтных настроек AddTool, а затем ему назначается Clip после создания; ни создание, ни инспекция не запускают рендеринг.

Примечание к релизу рендеринга: живая изоляция 2026-07-14 показала, что записи Clip Saver могут считываться как допустимая строка, в то время как сохранённый .comp содержит внутренний объект Clip с нулевым диапазоном (Length = 0, GlobalStart/GlobalEnd = -2000000000). В этом состоянии comp.Render(...) возвращает успех и сообщает о рендеринге кадра, но файл не записывается. fusion_render_tool больше не перезаписывает Clip Saver непосредственно перед рендерингом; проверка остаётся свободной от побочных эффектов.

Используйте scripts/diagnose_saver_initialization.py для живых проб инициализации Saver. Текущая рабочая последовательность: создайте разблокированную свежую композицию, заблокируйте её при добавлении Background/Saver, установите Clip Saver после создания, соедините под блокировкой, разблокируйте и выполните рендеринг с Tool=saver. Тестовый стенд и публичный fusion_render_tool теперь используют эту транзакцию; пять последовательных циклов публичного graph/validate/render успешно записали файлы EXR.

Устранение неполадок

• Подключение Fusion: убедитесь, что автономный Fusion Studio открыт и имеет активную композицию.

• Пути Python: включите путь к встроенной библиотеке Fusion в PYTHONPATH, а затем src этого репозитория.

• Пути Saver: используйте абсолютные пути, поддерживаемые расширения, существующие выходные папки и предпочтительно уникальные папки для каждого рендеринга.

• Права: выходные каталоги рендеринга должны быть доступны для записи текущему пользователю macOS.

• Заблокированные рендеринг: сначала проверьте с помощью fusion_validate_render_tool; распространённые ошибки: OUTPUT_DIRECTORY_MISSING, OUTPUT_ALREADY_EXISTS, SAVER_INPUT_DISCONNECTED и INVALID_RENDER_RANGE.

• MediaOut: автономный Fusion Studio рассматривает MediaOut как специфичный для Resolve в этом проекте; используйте Saver для автономного рендеринга.

Версионирование

Проект использует семантическое версионирование. Текущий патч-релиз — 0.1.1: локальное управление Fusion Studio MCP с защищённым редактированием, построением графов, диагностикой, экспортом графов, подтверждённым рендерингом с целевым Saver и примечаниями о приёмке для чистых macOS-машин. Резервируйте 1.0.0 для более широкой производственной уверенности в большем числе версий Fusion/Resolve и более крупных реальных композиций.