Fusion Studio MCP

Servidor MCP local para inspeccionar y controlar Blackmagic Fusion Studio independiente a través de la API de scripting de Fusion.

Este proyecto comienza de forma conservadora: primero se comprueba la conexión con Fusion, luego se exponen herramientas de inspección de solo lectura y, por último, se añaden herramientas de edición protegidas con comportamiento de ejecución simulada (dry-run) y deshacer.

Estado actual

• Estructura inicial del proyecto creada: 2026-07-13

• Aplicación objetivo encontrada: Blackmagic Fusion 21.0.2

• Ruta de importación de Python confirmada para el fusionscript.so incluido con Fusion

• Inspección de composición en vivo verificada contra Composition1

• .venv local creado con pytest, ruff y el SDK de Python para MCP

• Herramientas MCP de solo lectura implementadas para el estado, el listado de nodos, la consulta de un solo nodo, la lectura de nodos seleccionados y los resúmenes compactos de composición

• Herramientas MCP de edición protegidas implementadas para la selección, la lectura/escritura de entradas, el renombrado y el posicionamiento en FlowView

• Creación controlada de nodos, edición de conexiones de imagen, desconexión de entradas, inspección de conexiones y eliminación confirmada de un solo nodo implementadas

• Creación configurable de nodos y herramientas nativas de fotogramas clave y expresiones implementadas

• Controles de composición, además de herramientas transaccionales de grafos y de lote, implementados

• Validación de render, ajustes de Saver, diagnósticos, catálogo/esquema de herramientas y herramientas de exportación de grafos implementados

• Validación de edición en vivo superada contra la composición desechable Composition1

Related MCP server: nuke-mcp

Requisitos

• macOS

• Blackmagic Fusion Studio 21.0.2 o compatible

• Python 3.11+ requerido (requires-python = ">=3.11"); el Python 3.9 integrado en macOS es demasiado antiguo

• Ruta de la biblioteca de scripting incluida con Fusion disponible: /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

• SDK de Python para MCP para el modo servidor

Instalación con Claude Desktop en macOS

Recomendado para artistas y no desarrolladores: Instalar Fusion Studio MCP - Claude Desktop (macOS).

Esta es la vía de instalación pública de dos copias y pegado para Fusion Studio independiente y Claude Desktop en macOS. Instala desde el repositorio público de GitHub: https://github.com/bigsbypuglise/fusion-studio-mcp

Usa esta vía si quieres que Claude Desktop inspeccione una composición de Fusion, liste los nodos y construya árboles de nodos protegidos sin necesidad de hacer una configuración de desarrollo.

Versión rápida:

1. Abre Fusion Studio 21 y abre o crea una composición.

2. Ejecuta el bloque de instalación de la guía de Claude Desktop para macOS.

3. Ejecuta el bloque de configuración de Claude de la guía.

4. Cierra completamente Claude Desktop con Command-Q, vuelve a abrirlo y pídele a Claude que compruebe la conexión con Fusion.

Notas:

• Fusion Studio 21 es la versión recomendada; Fusion Studio 20 puede funcionar.

• Actualmente está dirigido a Fusion Studio independiente, no a DaVinci Resolve.

• Fusion Studio debe estar en ejecución con una composición activa abierta.

• La primera llamada a herramienta de Claude puede pedir permiso.

• El instalador predeterminado para principiantes sigue la última rama pública main, de modo que volver a ejecutar el pegado n.º 1 actualiza la instalación local. Quienes prefieran una versión estable fijada pueden usar la opción de versión etiquetada de la guía.

Instalación avanzada

El flujo de trabajo de macOS que se muestra a continuación se ha probado en vivo con Fusion Studio 21.0.2. El flujo de trabajo de Windows está documentado para instalaciones equivalentes de Fusion Studio, pero aún necesita validación en una máquina limpia con Windows.

Configuración de desarrollo en macOS

Entorno compatible probado en vivo:

• Blackmagic Fusion Studio 21.0.2

• Python 3.11+

• Ruta de aplicación confirmada: /Applications/Blackmagic Fusion 21/Fusion.app

• Ruta de biblioteca de scripting confirmada: /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

Instala Python con Homebrew si es necesario:

brew install python@3.11

Crea e instala el entorno local:

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

O hazlo manualmente:

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]'

Inicia Fusion Studio, crea o abre una composición desechable y luego ejecuta:

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 es un punto de entrada de servidor MCP por stdio. Está pensado para ser lanzado por un cliente MCP; cuando se ejecuta directamente en una terminal simple sin un cliente conectado, puede salir limpiamente después de que se cierre stdin. Usa scripts/test_fusion_connection.py para una prueba de humo de conexión independiente.

Ejemplo de cliente MCP en 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"
      }
    }
  }
}

Solución de problemas en macOS:

• Si Fusion está cerrado o no hay ninguna composición activa, las herramientas de conexión devuelven FUSION_NOT_RUNNING o NO_ACTIVE_COMP.

• Si fusionscript no se puede importar, confirma que PYTHONPATH incluye la ruta Contents/Libraries de Fusion.

• macOS puede mostrar avisos de seguridad la primera vez que las herramientas se comunican con otra aplicación. Permite que Fusion y el cliente de terminal/MCP se comuniquen localmente.

• Usa carpetas de salida absolutas y únicas para los renders de Saver a fin de evitar la protección contra sobrescritura y los casos límite de nombres de archivo de Fusion.

Configuración de desarrollo en Windows

Entorno objetivo documentado:

• Blackmagic Fusion Studio 21.0.2 o compatible

• Python 3.11+

• Ruta de aplicación habitual: C:\Program Files\Blackmagic Design\Fusion 21\Fusion.exe

• Ruta de biblioteca de scripting habitual: C:\Program Files\Blackmagic Design\Fusion 21

Instala Python desde https://www.python.org/downloads/windows/ y habilita "Add python.exe to PATH", o instálalo con winget:

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

Crea e instala el entorno local desde PowerShell:

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

Si PowerShell bloquea el script, ejecútalo solo para el proceso actual:

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

Configuración manual con Command Prompt:

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]

Inicia Fusion Studio, crea o abre una composición desechable y, a continuación, ejecuta desde 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

Al igual que en macOS, el comando del servidor está pensado para ser lanzado por un cliente MCP a través de stdio. Si se ejecuta manualmente en una shell sin un cliente conectado, puede salir cuando se cierre stdin.

Ejemplo de cliente MCP en 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"
      }
    }
  }
}

Solución de problemas en Windows:

• Estos pasos para Windows están documentados pero aún no se han validado en vivo en una máquina Windows limpia.

• Si no se encuentra python, usa py -3.11 o reinstala Python con la integración de PATH habilitada.

• Si fusionscript no se puede importar, verifica la ruta de instalación de Fusion y añade su directorio de scripting a PYTHONPATH.

• Pon entre comillas las rutas con espacios en PowerShell y JSON; usa barras invertidas dobles en las cadenas JSON.

• Si la conexión falla, confirma que Fusion Studio está abierto, que no está bloqueado por avisos de seguridad de Windows y que tiene una composición activa.

• Usa rutas de salida absolutas de Saver en carpetas con permisos de escritura y prefiere carpetas de salida únicas por render.

Prueba rápida de conexión

1. Abre Fusion Studio independiente.

2. Abre o crea una composición desechable.

3. Ejecuta:

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

El script imprime JSON estructurado. Si Fusion está cerrado, debería devolver success: false con FUSION_NOT_RUNNING.

Sonda de inspección de solo lectura

Ejecuta todas las funciones de herramientas de solo lectura sin iniciar un cliente 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

Herramientas de solo lectura actuales:

• 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)

Las entradas de la lista de nodos incluyen:

• Nombre del nodo y tipo de herramienta de Fusion

• Posición en el Flow a partir de comp.CurrentFrame.FlowView.GetPosTable(tool) cuando Fusion la expone

• Entradas con ID, nombre, tipo de datos, valor actual no relacionado con imágenes, salida conectada y atributos de entrada

• Salidas con ID, nombre, tipo de datos, entradas conectadas y atributos de salida

• Resumen de ajustes de fotogramas clave para controles que no son de imagen

Ejecutar el servidor MCP

Después de la configuración, ejecuta:

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

Ejemplos de operaciones de estilo 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={...})

Ejemplo de respuesta de resumen compacto de la composición vacía en vivo 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."
  }
}

Herramientas de edición seguras

Las operaciones de edición validan la composición activa, el nodo y la entrada antes de modificar nada. Las escrituras usan Lock(), StartUndo(...), EndUndo(True) y Unlock() de Fusion a través de un envoltorio de limpieza defensivo, de modo que las operaciones fallidas no dejen un grupo de deshacer abierto.

Herramientas de edición implementadas:

• 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 admite tipos de valor comunes de Fusion:

• números escalares finitos

• booleanos, convertidos a 1 o 0 para entradas numéricas de Fusion

• cadenas para entradas Text

• cadenas para entradas FuID, validadas contra las opciones de cada entrada cuando Fusion las expone

• puntos como [x, y] o {"x": x, "y": y}

• colores como [r, g, b], [r, g, b, a] o claves de diccionario coincidentes cuando Fusion expone una entrada Color real

Los valores no admitidos o ambiguos devuelven un fallo estructurado y no intentan realizar una escritura. Las entradas de imagen son rechazadas por las herramientas de establecimiento de valores porque deben editarse como conexiones, no como valores escalares.

Los controles de color de Background integrados en Fusion Studio 21.0.2 se exponen como entradas de canal numéricas separadas, como TopLeftRed, TopLeftGreen, TopLeftBlue y TopLeftAlpha, cada una usando INPID_InputControl == "ColorControl" e INPS_DataType == "Number". La validación en vivo confirmó que se pueden ajustar estos canales con flotantes escalares, por ejemplo TopLeftRed = 0.25.

Ejemplo de respuesta de éxito:

{
  "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."
}

Ejemplo de fallo de validación:

{
  "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
}

Herramientas de conexión y nodos

fusion_create_node_tool acepta settings opcionales, que se aplican después de que el nodo exista y sea validado. Los fallos en los ajustes producen un resultado parcial: el nodo creado permanece en la composición, los ajustes correctos se notifican y los ajustes fallidos incluyen códigos de error por entrada. Saver puede recibir su ruta de Clip a través de settings={"Clip": "/path/to/output.exr"} y ya no necesita el marcador cuando se proporciona ese ajuste.

La edición de conexiones está actualmente limitada a enlaces de flujo de imagen. La capa de herramientas rechaza los enlaces de modificadores, expresiones, máscaras y escalares con metadatos de socket explícitos, en lugar de tratarlos como si fueran conexiones de imagen ordinarias.

Comportamiento de seguridad:

• los IDs de herramienta se comprueban contra el registro local de Fusion antes de la creación

• MediaOut se rechaza en Fusion independiente porque su clase de registro no se puede crear allí

• Saver se puede crear con una ruta de Clip provisional explícita para evitar que Fusion abra un diálogo de archivo

• las entradas de destino no se reemplazan a menos que replace=true

• se rechazan las autoconexiones y los ciclos evidentes de flujo de imagen

• la eliminación requiere confirm=true y solo acepta un nombre de nodo por llamada

• todas las operaciones de crear/conectar/desconectar/eliminar usan grupos de deshacer de Fusion

Ejemplo de conexión con éxito:

{
  "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"
  }
}

Ejemplo de protección de eliminación:

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

Herramientas de composición y lote

Los controles de composición exponen el rango de fotogramas, el fotograma actual, la ruta de guardado y los guardados explícitos de .comp. La validación en vivo confirmó fusion_set_comp_range_tool(1, 48), fusion_set_current_frame_tool(24) y fusion_save_comp_tool("/tmp/fusionmcp_batch_*.comp") en Fusion Studio 21.0.2 independiente.

fusion_create_graph_tool acepta:

• nodes: objetos con id, tool_id o tool_type, name opcional, x/y opcionales y settings opcionales

• connections: objetos con ids de nodos de grafo en source/target, más source_output y target_input

• comp_settings: actualmente soporta start_frame/end_frame o global_start/global_end

La creación de grafos valida nombres duplicados, referencias de grafo faltantes, ids de herramientas inválidos, ciclos obvios y valores no soportados antes o durante la transacción. Crea primero los nodos, aplica la configuración y luego conecta los sockets de imagen. Si un paso posterior falla, intenta desconectar los enlaces creados por esa solicitud y elimina solo los nodos creados por esa solicitud, devolviendo status: "rolled_back" con resultados de reversión por elemento.

Las herramientas de entrada/fotograma clave/eliminación en lote usan un grupo de deshacer de Fusion por lote. La eliminación en lote requiere confirm=true y solo elimina los nodos explícitamente listados.

Render, diagnóstico y exportación

La ejecución del render requiere confirm=true. fusion_validate_render_tool comprueba el estado activo del comp, la existencia/tipo de Saver, la ruta de salida absoluta, la extensión de archivo soportada, el directorio de salida faltante, el riesgo de sobrescritura, el rango de fotogramas válido y la entrada de imagen conectada del Saver sin renderizar intencionalmente. Las salidas existentes devuelven OUTPUT_ALREADY_EXISTS a menos que se proporcione explícitamente allow_overwrite=true.

fusion_render_tool con un saver_node específico usa la transacción Saver canónica confirmada en vivo: mantiene el objeto Saver original, no reescribe Clip, no consulta el estado del render antes de renderizar, llama a comp.Render una vez con Start, End, Wait y Tool, y luego confirma los archivos de salida desde la ruta Clip del Saver en disco. Si Fusion informa completado pero no aparece el archivo de salida esperado, la herramienta devuelve RENDER_OUTPUT_MISSING con detalles del seguimiento del render.

Los diagnósticos incluyen comprobaciones de rango del comp, entradas de imagen requeridas desconectadas, rutas de Loader faltantes, rutas de Saver inválidas, expresiones que evalúan a None, IDs de herramientas no resueltos y nombres duplicados cuando son detectables.

fusion_export_graph_tool emite fusionmcp.graph.v1 con IDs de herramientas exactos, IDs de entrada, configuración segura, posiciones de FlowView, conexiones de flujo de imagen y fotogramas clave nativos cuando se pueden leer de forma segura.

Animación y expresiones

Los fotogramas clave nativos usan los propios modificadores de Fusion:

• las entradas escalares usan BezierSpline

• las entradas de punto usan Path

• las expresiones usan input.SetExpression(...)

Las herramientas distinguen los estados static, keyframed, expression y otros modifier. Rechazan sobrescrituras silenciosas: establecer un fotograma clave en una entrada de expresión, establecer una expresión en una entrada con fotogramas clave o establecer un fotograma clave duplicado devuelve un error estructurado. Eliminar datos de animación/expresión requiere confirm=true.

Ejemplos confirmados en vivo:

{
  "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"
  }
}

Las expresiones malas se rechazan cuando Fusion acepta la cadena de expresión pero evalúa a None en el fotograma actual.

Pruebas

Ejecutar pruebas unitarias y lint:

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

Ejecutar las pruebas en vivo opcionales solo contra una composición Fusion activa desechable:

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

Seguridad

Las herramientas de escritura modifican intencionalmente la composición activa. Úselas solo en composiciones desechables o explícitamente aprobadas hasta que se añadan salvaguardas de producción más amplias.

La inspección de solo lectura no llama intencionalmente a Output.GetValue() porque puede desencadenar renderizado ascendente. La inspección de salida solo lee los atributos de salida y los metadatos de conexión.

Las composiciones de producción no deben usarse para pruebas de integración.

Fusion Studio 21.0.2 independiente trata MediaOut como específico de Resolve para este proyecto. Fusion independiente no requiere un nodo terminal. Saver se soporta como una herramienta independiente normal cuando se crea sin defsettings de AddTool y luego se asigna Clip después de la creación; no se desencadena ningún render por creación o inspección.

Nota de liberación de render: el aislamiento en vivo del 2026-07-14 encontró que las escrituras de Clip en Saver pueden leerse como una cadena válida mientras que el .comp guardado contiene un objeto interno Clip de intervalo cero (Length = 0, GlobalStart/GlobalEnd = -2000000000). En ese estado, comp.Render(...) devuelve éxito e informa que el fotograma se renderizó, pero no se escribe ningún archivo. fusion_render_tool ya no reescribe Clip de Saver inmediatamente antes del render; la validación permanece libre de efectos secundarios.

Use scripts/diagnose_saver_initialization.py para sondeos de inicialización de Saver en vivo. La secuencia de trabajo en bruto actual es crear un comp nuevo desbloqueado, bloquear mientras se añaden Background/Saver, establecer Clip de Saver después de la creación, conectar mientras está bloqueado, desbloquear y renderizar con Tool=saver. El arnés y fusion_render_tool público ahora comparten esa transacción; cinco ciclos consecutivos de grafo/validación/render públicos escribieron archivos EXR con éxito.

Solución de problemas

• Conexión de Fusion: asegúrese de que Fusion Studio independiente esté abierto y tenga una composición activa.

• Rutas de Python: incluya la ruta de la biblioteca incluida de Fusion en PYTHONPATH, seguida de src de este repositorio.

• Rutas de Saver: use rutas absolutas, extensiones soportadas, carpetas de salida existentes y preferiblemente carpetas únicas por render.

• Permisos: los directorios de salida del render deben ser escribibles por el usuario actual de macOS.

• Renders bloqueados: valide primero con fusion_validate_render_tool; los errores comunes son OUTPUT_DIRECTORY_MISSING, OUTPUT_ALREADY_EXISTS, SAVER_INPUT_DISCONNECTED e INVALID_RENDER_RANGE.

• MediaOut: Fusion Studio independiente trata MediaOut como específico de Resolve en este proyecto; use Saver para renders independientes.

Versionado

El proyecto usa versionado semántico. El release de parche actual es 0.1.1: control local de Fusion Studio MCP con edición protegida, construcción de grafos, diagnóstico, exportación de grafos, renderizado confirmado dirigido a Saver y notas de aceptación en máquina limpia de macOS. Reserve 1.0.0 para mayor confianza en producción entre más versiones de Fusion/Resolve y comps del mundo real más grandes.