Fusion Studio MCP

Lokaler MCP-Server zum Untersuchen und Steuern der eigenständigen Blackmagic Fusion Studio über die Scripting-API von Fusion.

Dieses Projekt startet konservativ: zuerst die Fusion-Verbindung nachweisen, dann schreibgeschützte Inspektionstools bereitstellen, dann abgesicherte Bearbeitungswerkzeuge mit Dry-Run- und Undo-Verhalten hinzufügen.

Aktueller Stand

• Projektscaffold erstellt: 2026-07-13

• Ziel-App gefunden: Blackmagic Fusion 21.0.2

• Python-Importpfad für Fusions gebündelte fusionscript.so bestätigt

• Live-Composition-Inspektion gegen Composition1 verifiziert

• Lokales .venv mit pytest, ruff und dem Python-MCP-SDK erstellt

• Schreibgeschützte MCP-Tools implementiert für Status, Knotenliste, Einzelknotenabfrage, Auswahl-Lesezugriffe und kompakte Comp-Zusammenfassungen

• Abgesicherte Bearbeitungs-MCP-Tools implementiert für Auswahl, Eingabe-Lesen/Schreiben, Umbenennen und FlowView-Positionierung

• Kontrollierte Knotenerstellung, Bildverbindungsbearbeitung, Eingabetrennung, Verbindungsinspektion und bestätigtes Einzelknotenlöschen implementiert

• Konfigurierbare Knotenerstellung sowie native Keyframe- und Ausdrucks-Tools implementiert

• Zusammensetzungssteuerungen sowie transaktionale Graph- und Batch-Tools implementiert

• Rendervalidierung, Saver-Einstellungen, Diagnose, Tool-Katalog/Schema und Graph-Export-Tools implementiert

• Live-Bearbeitungsvalidierung gegen eine wegwerfbare Composition1 bestanden

Related MCP server: nuke-mcp

Anforderungen

• macOS

• Blackmagic Fusion Studio 21.0.2 oder kompatibel

• Python 3.11+ erforderlich (requires-python = ">=3.11"); das in macOS integrierte Python 3.9 ist zu alt

• Der gebündelte Scripting-Bibliothekspfad von Fusion muss verfügbar sein: /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

• Python-MCP-SDK für den Servermodus

Installation mit Claude Desktop auf macOS

Empfohlen für Künstler:innen und Nicht-Entwickler:innen: Install Fusion Studio MCP - Claude Desktop (macOS).

Dies ist der öffentliche Weg mit zwei Copy-Paste-Schritten für eigenständiges Fusion Studio und Claude Desktop auf macOS. Es installiert aus dem öffentlichen GitHub-Repository: https://github.com/bigsbypuglise/fusion-studio-mcp

Nutzen Sie diesen Weg, wenn Claude Desktop ein Fusion-Comp inspizieren, Knoten auflisten und abgesicherte Knotenbäume erstellen soll, ohne ein Entwickler-Setup durchzuführen.

Kurzversion:

1. Öffnen Sie Fusion Studio 21 und erstellen oder öffnen Sie ein Comp.

2. Fügen Sie den Installations-Copy-Paste aus dem Claude-Desktop-macOS-Leitfaden ein.

3. Fügen Sie den Claude-Konfigurations-Copy-Paste aus dem Leitfaden ein.

4. Beenden Sie Claude Desktop vollständig mit Command-Q, öffnen Sie es erneut und bitten Sie Claude, die Fusion-Verbindung zu prüfen.

Hinweise:

• Fusion Studio 21 wird empfohlen; Fusion Studio 20 könnte funktionieren.

• Dies zielt derzeit auf eigenständiges Fusion Studio ab, nicht auf DaVinci Resolve.

• Fusion Studio muss mit einem aktiven Comp geöffnet sein.

• Der erste Claude-Toolaufruf kann um Erlaubnis bitten.

• Der Standard-Installateur für Einsteiger folgt dem neuesten öffentlichen main-Zweig, sodass das erneute Ausführen von Copy-Paste #1 die lokale Installation aktualisiert. Wer eine festgelegte stabile Version bevorzugt, kann die Option für getaggte Releases im Leitfaden nutzen.

Erweiterte Installation

Der macOS-Workflow unten wurde live mit Fusion Studio 21.0.2 getestet. Der Windows-Workflow ist für äquivalente Fusion-Studio-Installationen dokumentiert, muss aber noch auf einem sauberen Windows-Rechner validiert werden.

macOS-Entwickler-Setup

Unterstützte live getestete Umgebung:

• Blackmagic Fusion Studio 21.0.2

• Python 3.11+

• Bestätigter App-Pfad: /Applications/Blackmagic Fusion 21/Fusion.app

• Bestätigter Scripting-Bibliothekspfad: /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

Installieren Sie Python bei Bedarf mit Homebrew:

brew install python@3.11

Lokale Umgebung erstellen und installieren:

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

Oder manuell:

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

Starten Sie Fusion Studio, erstellen oder öffnen Sie eine wegwerfbare Komposition und führen Sie dann aus:

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 ist ein Stdio-MCP-Server-Einstiegspunkt. Er soll von einem MCP-Client gestartet werden; wenn er direkt in einem einfachen Terminal ohne angeschlossenen Client ausgeführt wird, kann er nach dem Schließen von stdin sauber beenden. Verwenden Sie scripts/test_fusion_connection.py für einen eigenständigen Verbindungs-Smoke-Test.

macOS-MCP-Client-Beispiel:

{
  "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-Fehlerbehebung:

• Wenn Fusion geschlossen ist oder kein Comp aktiv ist, geben Verbindungstools FUSION_NOT_RUNNING oder NO_ACTIVE_COMP zurück.

• Wenn fusionscript nicht importiert werden kann, überprüfen Sie, ob PYTHONPATH den Pfad zu Contents/Libraries von Fusion enthält.

• macOS zeigt möglicherweise beim ersten Mal Sicherheitsaufforderungen an, wenn Tools mit einer anderen App kommunizieren. Erlauben Sie Fusion und dem Terminal/MCP-Client die lokale Kommunikation.

• Verwenden Sie für Saver-Render eindeutige absolute Ausgabeordner, um Überschreibschutz und Fusion-Dateinamen-Sonderfälle zu vermeiden.

Windows-Entwickler-Setup

Dokumentierte Zielumgebung:

• Blackmagic Fusion Studio 21.0.2 oder kompatibel

• Python 3.11+

• Üblicher App-Pfad: C:\Program Files\Blackmagic Design\Fusion 21\Fusion.exe

• Üblicher Scripting-Bibliothekspfad: C:\Program Files\Blackmagic Design\Fusion 21

Installieren Sie Python von https://www.python.org/downloads/windows/ und aktivieren Sie "Add python.exe to PATH", oder installieren Sie mit winget:

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

Lokale Umgebung aus PowerShell erstellen und installieren:

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

Wenn PowerShell das Skript blockiert, führen Sie es nur für den aktuellen Prozess aus:

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

Manuelles Einrichten in der Eingabeaufforderung:

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]

Starten Sie Fusion Studio, erstellen oder öffnen Sie eine wegwerfbare Komposition und führen Sie dann aus PowerShell aus:

.\.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

Wie unter macOS ist der Serverbefehl dazu gedacht, von einem MCP-Client über stdio gestartet zu werden. Wenn er manuell in einer Shell ohne angeschlossenen Client ausgeführt wird, kann er beenden, wenn stdin geschlossen wird.

Windows-MCP-Client-Beispiel:

{
  "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-Fehlerbehebung:

• Diese Windows-Schritte sind dokumentiert, aber noch nicht live auf einem sauberen Windows-Rechner validiert.

• Wenn python nicht gefunden wird, verwenden Sie py -3.11 oder installieren Sie Python mit aktivierter PATH-Integration neu.

• Wenn fusionscript nicht importiert werden kann, überprüfen Sie den Fusion-Installationspfad und fügen Sie sein Scripting-Verzeichnis zu PYTHONPATH hinzu.

• Setzen Sie Pfade mit Leerzeichen in PowerShell und JSON in Anführungszeichen; verwenden Sie in JSON-Zeichenfolgen doppelte Backslashes.

• Wenn die Verbindung fehlschlägt, stellen Sie sicher, dass Fusion Studio geöffnet ist, nicht durch Windows-Sicherheitsaufforderungen blockiert wird und ein aktives Comp hat.

• Verwenden Sie absolute Saver-Ausgabepfade in beschreibbaren Ordnern und bevorzugen Sie für jeden Render eindeutige Ausgabeordner.

Schneller Verbindungstest

1. Öffnen Sie eigenständiges Fusion Studio.

2. Öffnen oder erstellen Sie eine wegwerfbare Komposition.

3. Führen Sie aus:

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

Das Skript gibt strukturiertes JSON aus. Wenn Fusion geschlossen ist, sollte es success: false mit FUSION_NOT_RUNNING zurückgeben.

Schreibgeschützter Inspektions-Test

Führen Sie alle schreibgeschützten Tool-Funktionen ohne einen MCP-Client aus:

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

Aktuelle schreibgeschützte Tools:

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

Knotenlisteneinträge enthalten:

• Knotenname und Fusion-Tooltyp

• Flow-Position aus comp.CurrentFrame.FlowView.GetPosTable(tool), wenn Fusion sie bereitstellt

• Eingaben mit ID, Name, Datentyp, aktuellem Nicht-Bild-Wert, verbundenem Ausgang und Eingabeattributen

• Ausgänge mit ID, Name, Datentyp, verbundenen Eingängen und Ausgangsattributen

• Schlüsseleinstellungszusammenfassung für Nicht-Bild-Steuerelemente

MCP-Server ausführen

Nach dem Setup ausführen:

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

Beispiel für MCP-ähnliche Operationen:

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={...})

Beispiel-Antwort mit kompakter Zusammenfassung von leerem live 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."
  }
}

Sichere Bearbeitungswerkzeuge

Bearbeitungsoperationen validieren die aktive Komposition, den Knoten und die Eingabe, bevor etwas geändert wird. Schreibvorgänge verwenden Fusion Lock(), StartUndo(...), EndUndo(True) und Unlock() über einen defensiven Bereinigungs-Wrapper, sodass fehlgeschlagene Operationen keine offene Undo-Gruppe hinterlassen.

Implementierte Bearbeitungswerkzeuge:

• 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 unterstützt gängige Fusion-Werttypen:

• endliche skalare Zahlen

• boolesche Werte, umgewandelt in 1 oder 0 für numerische Fusion-Eingaben

• Zeichenfolgen für Text-Eingaben

• Zeichenfolgen für FuID-Eingaben, validiert gegen die pro Eingabe verfügbaren Optionen, wenn Fusion sie bereitstellt

• Punkte als [x, y] oder {"x": x, "y": y}

• Farben als [r, g, b], [r, g, b, a] oder passende Dict-Schlüssel, wenn Fusion eine echte Color-Eingabe bereitstellt

Nicht unterstützte oder mehrdeutige Werte geben einen strukturierten Fehler zurück und versuchen keinen Schreibvorgang. Bildeingaben werden von Wert-Einstelltools abgelehnt, da sie als Verbindungen und nicht als skalare Werte bearbeitet werden müssen.

Integrierte Background-Farbsteuerelemente in Fusion Studio 21.0.2 werden als separate numerische Kanaleingaben wie TopLeftRed, TopLeftGreen, TopLeftBlue und TopLeftAlpha bereitgestellt, jeweils mit INPID_InputControl == "ColorControl" und INPS_DataType == "Number". Live-Validierung bestätigte das Setzen dieser Kanäle mit skalaren Gleitkommazahlen, zum Beispiel TopLeftRed = 0.25.

Beispiel für erfolgreiche Antwort:

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

Beispiel für Validierungsfehler:

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

Verbindungs- und Knotenwerkzeuge

fusion_create_node_tool akzeptiert optionale settings, die angewendet werden, nachdem der Knoten erstellt und validiert wurde. Fehler bei Einstellungen erzeugen ein Teilergebnis: Der erstellte Knoten bleibt im Comp, erfolgreiche Einstellungen werden gemeldet und fehlgeschlagene Einstellungen enthalten pro Eingabe Fehlercodes. Saver kann seinen Clip-Pfad über settings={"Clip": "/path/to/output.exr"} erhalten und benötigt keinen Platzhalter mehr, wenn diese Einstellung angegeben wird.

Die Verbindungsbearbeitung ist derzeit auf Bild-Flow-Verbindungen beschränkt. Die Tool-Ebene lehnt Modifier-, Ausdrucks-, Masken- und Skalar-Verbindungen mit expliziten Socket-Metadaten ab, anstatt sie als gewöhnliche Bildrohre zu behandeln.

Sicherheitsverhalten:

• Tool-IDs werden vor der Erstellung gegen Fusions lokale Registry geprüft

• MediaOut wird im eigenständigen Fusion abgelehnt, da seine Registry-Klasse dort nicht erstellbar ist

• Saver ist mit einem expliziten Platzhalter-Clip-Pfad erstellbar, um zu vermeiden, dass Fusion einen Dateidialog öffnet

• Zieleingänge werden nur ersetzt, wenn replace=true

• Selbstverbindungen und offensichtliche Bildfluss-Zyklen werden abgelehnt

• Löschen erfordert confirm=true und akzeptiert nur einen Knotennamen pro Aufruf

• alle Erstell-, Verbindungs-, Trenn- und Löschoperationen verwenden Fusion-Undo-Gruppen

Beispiel für erfolgreiche Verbindung:

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

Beispiel für Löschschutz:

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

Komposition und Batch-Tools

Kompositionssteuerungen legen Frame-Bereich, aktuelles Frame, Speicherpfad und explizite .comp-Speicherungen offen. Die Live-Validierung bestätigte fusion_set_comp_range_tool(1, 48), fusion_set_current_frame_tool(24) und fusion_save_comp_tool("/tmp/fusionmcp_batch_*.comp") in der eigenständigen Fusion Studio 21.0.2.

fusion_create_graph_tool akzeptiert:

• nodes: Objekte mit id, tool_id oder tool_type, optionalem name, optionalem x/y und optionalen settings

• connections: Objekte mit Graph-Knoten-IDs in source/target, plus source_output und target_input

• comp_settings: unterstützt derzeit start_frame/end_frame oder global_start/global_end

Die Grapherstellung validiert doppelte Namen, fehlende Graph-Referenzen, ungültige Tool-IDs, offensichtliche Zyklen und nicht unterstützte Werte vor oder während der Transaktion. Sie erstellt zuerst Knoten, wendet Einstellungen an und verbindet dann Image-Sockets. Wenn ein späterer Schritt fehlschlägt, versucht sie, die von dieser Anfrage erstellten Verbindungen zu trennen und nur die von dieser Anfrage erstellten Knoten zu löschen, und gibt status: "rolled_back" mit Rollback-Ergebnissen pro Element zurück.

Batch-Eingabe-/Keyframe-/Lösch-Tools verwenden eine Fusion-Undo-Gruppe pro Batch. Batch-Löschung erfordert confirm=true und löscht nur explizit aufgeführte Knoten.

Rendern, Diagnose und Export

Die Render-Ausführung erfordert confirm=true. fusion_validate_render_tool prüft den aktiven Kompositionsstatus, die Existenz/den Typ des Savers, den absoluten Ausgabepfad, die unterstützte Dateierweiterung, das fehlende Ausgabeverzeichnis, das Überschreibungsrisiko, den gültigen Frame-Bereich und den verbundenen Saver-Bildeingang, ohne absichtlich zu rendern. Vorhandene Ausgaben geben OUTPUT_ALREADY_EXISTS zurück, es sei denn, allow_overwrite=true wird explizit angegeben.

fusion_render_tool mit einem bestimmten saver_node verwendet die kanonische, live bestätigte Saver-Transaktion: Es behält das ursprüngliche Saver-Objekt bei, schreibt Clip nicht neu, fragt den Renderstatus vor dem Rendern nicht ab, ruft comp.Render einmal mit Start, End, Wait und Tool auf und bestätigt dann die Ausgabedateien vom Saver-Clip-Pfad auf der Festplatte. Wenn Fusion den Abschluss meldet, aber keine erwartete Ausgabedatei erscheint, gibt das Tool RENDER_OUTPUT_MISSING mit Details zur Render-Trace zurück.

Die Diagnose umfasst Kompositionsbereichsprüfungen, nicht verbundene erforderliche Bildeingänge, fehlende Loader-Pfade, ungültige Saver-Pfade, Ausdrücke, die zu None ausgewertet werden, unaufgelöste Tool-IDs und doppelte Namen, wo erkennbar.

fusion_export_graph_tool gibt fusionmcp.graph.v1 aus mit exakten Tool-IDs, Eingabe-IDs, sicheren Einstellungen, FlowView-Positionen, Bildfluss-Verbindungen und nativen Keyframes, wo sicher lesbar.

Animation und Ausdrücke

Native Keyframes verwenden Fusions eigene Modifikatoren:

• Skalare Eingaben verwenden BezierSpline

• Punkt-Eingaben verwenden Path

• Ausdrücke verwenden input.SetExpression(...)

Die Tools unterscheiden static, keyframed, expression und andere modifier-Zustände. Sie lehnen stilles Überschreiben ab: Das Setzen eines Keyframes auf einen Ausdruckseingang, das Setzen eines Ausdrucks auf einen keyframed Eingang oder das Setzen eines doppelten Keyframes gibt einen strukturierten Fehler zurück. Das Entfernen von Animations-/Ausdrucksdaten erfordert confirm=true.

Live-bestätigte Beispiele:

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

Schlechte Ausdrücke werden abgelehnt, wenn Fusion die Ausdruckszeichenfolge akzeptiert, sie aber am aktuellen Frame zu None ausgewertet wird.

Testen

Führen Sie Unit-Tests und Lint aus:

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

Führen Sie die optionalen Live-Tests nur gegen eine wegwerfbare aktive Fusion-Komposition aus:

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

Sicherheit

Schreib-Tools modifizieren absichtlich die aktive Komposition. Verwenden Sie sie nur auf wegwerfbaren oder ausdrücklich genehmigten Kompositionen, bis umfassendere Produktionssicherungen hinzugefügt werden.

Die schreibgeschützte Inspektion ruft absichtlich nicht Output.GetValue() auf, da dies ein vorgelagertes Rendern auslösen kann. Die Ausgabeinspektion liest nur Ausgabeattribute und Verbindungsmetadaten.

Produktionskompositionen sollten nicht für Integrationstests verwendet werden.

Die eigenständige Fusion Studio 21.0.2 behandelt MediaOut als Resolve-spezifisch für dieses Projekt. Die eigenständige Fusion erfordert keinen Endknoten. Saver wird als normales eigenständiges Tool unterstützt, wenn es ohne AddTool-Defsettings erstellt und nach der Erstellung Clip zugewiesen wird; durch Erstellung oder Inspektion wird kein Rendern ausgelöst.

Render-Versionshinweis: Die Live-Isolation am 2026-07-14 ergab, dass Saver-Clip-Schreibvorgänge als gültige Zeichenfolge zurückgelesen werden können, während die gespeicherte .comp ein internes Clip-Objekt mit Null-Spanne enthält (Length = 0, GlobalStart/GlobalEnd = -2000000000). In diesem Zustand gibt comp.Render(...) Erfolg zurück und meldet das gerenderte Frame, aber es wird keine Datei geschrieben. fusion_render_tool schreibt Saver-Clip nicht mehr unmittelbar vor dem Rendern neu; die Validierung bleibt nebenwirkungsfrei.

Verwenden Sie scripts/diagnose_saver_initialization.py für Live-Saver-Initialisierungsproben. Die aktuelle rohe Arbeitssequenz besteht darin, eine entsperrte frische Komposition zu erstellen, während des Hinzufügens von Background/Saver zu sperren, Saver-Clip nach der Erstellung zu setzen, während gesperrt zu verbinden, zu entsperren und mit Tool=saver zu rendern. Die Testumgebung und das öffentliche fusion_render_tool teilen sich jetzt diese Transaktion; fünf aufeinanderfolgende öffentliche Graph-/Validierungs-/Render-Zyklen schrieben EXR-Dateien erfolgreich.

Fehlerbehebung

• Fusion-Verbindung: Stellen Sie sicher, dass die eigenständige Fusion Studio geöffnet ist und eine aktive Komposition hat.

• Python-Pfade: Fügen Sie den gebündelten Bibliothekspfad von Fusion in PYTHONPATH ein, gefolgt vom src-Verzeichnis dieses Repos.

• Saver-Pfade: Verwenden Sie absolute Pfade, unterstützte Erweiterungen, vorhandene Ausgabeordner und vorzugsweise eindeutige Ordner pro Render.

• Berechtigungen: Render-Ausgabeverzeichnisse müssen für den aktuellen macOS-Benutzer beschreibbar sein.

• Blockierte Render: Validieren Sie zuerst mit fusion_validate_render_tool; häufige Fehler sind OUTPUT_DIRECTORY_MISSING, OUTPUT_ALREADY_EXISTS, SAVER_INPUT_DISCONNECTED und INVALID_RENDER_RANGE.

• MediaOut: Die eigenständige Fusion Studio behandelt MediaOut in diesem Projekt als Resolve-spezifisch; verwenden Sie Saver für eigenständige Render.

Versionierung

Das Projekt verwendet semantische Versionierung. Die aktuelle Patch-Version ist 0.1.1: lokale Fusion-Studio-MCP-Steuerung mit geschützter Bearbeitung, Grapherstellung, Diagnose, Graph-Export, bestätigtem Saver-gerichtetem Rendern und macOS-Clean-Machine-Abnahmehinweisen. Reservieren Sie 1.0.0 für breiteres Produktionsvertrauen über mehr Fusion/Resolve-Versionen und größere reale Kompositionen.