Fusion Studio MCP

FusionのスクリプティングAPIを介して、スタンドアロンのBlackmagic Fusion Studioを検査・制御するためのローカルMCPサーバー。

このプロジェクトは慎重に進めます。まずFusionへの接続を実証し、次に読み取り専用の検査ツールを公開し、その後、ドライランとアンドゥ動作を備えた保護付き編集ツールを追加します。

現在のステータス

• プロジェクトの雛形作成日: 2026-07-13

• 対象アプリ特定: Blackmagic Fusion 21.0.2

• Fusionに同梱されている fusionscript.so のPythonインポートパスを確認

• ライブのコンポジション検査を Composition1 に対して検証

• pytest、ruff、Python MCP SDKを備えたローカル .venv を作成

• ステータス、ノード一覧、単一ノード参照、選択ノードの読み取り、コンパクトなコンポ概要のための読み取り専用MCPツールを実装

• 選択、入力の読み書き、リネーム、FlowView配置のための保護付き編集MCPツールを実装

• 制御されたノード作成、画像コネクション編集、入力の切断、コネクション検査、確認付き単一ノード削除を実装

• 設定可能なノード作成に加え、ネイティブのキーフレームツールとエクスプレッションツールを実装

• コンポジションコントロールに加え、トランザクショナルなグラフ・バッチツールを実装

• レンダー検証、Saver設定、診断、ツールカタログ/スキーマ、グラフエクスポートツールを実装

• 使い捨ての Composition1 に対するライブ編集検証に合格

Related MCP server: nuke-mcp

要件

• macOS

• Blackmagic Fusion Studio 21.0.2 または互換バージョン

• Python 3.11+ が必要 (requires-python = ">=3.11")。macOS標準のPython 3.9は古すぎる

• Fusionに同梱されたスクリプティングライブラリのパスが利用可能: /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

• サーバーモード用のPython MCP SDK

Claude Desktop on macOS でのインストール

アーティストや非開発者におすすめ: Fusion Studio MCP のインストール - Claude Desktop (macOS)。

これは、macOS上のスタンドアロンFusion StudioとClaude Desktopのための公開されたコピーペースト2回のセットアップ手順です。公開GitHubリポジトリからインストールします: https://github.com/bigsbypuglise/fusion-studio-mcp

Claude DesktopにFusionコンポの検査、ノード一覧取得、保護付きノードツリーの構築をさせたい場合で、開発者向けセットアップを避けたい場合はこの手順を使用してください。

クイックバージョン:

1. Fusion Studio 21を開き、コンポを開くか作成します。

2. Claude Desktop macOSガイドのインストール用ペーストを実行します。

3. ガイドのClaude設定用ペーストを実行します。

4. Command-QでClaude Desktopを完全に終了し、再度開いて、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

必要に応じてHomebrewでPythonをインストール:

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 はstdio MCPサーバーのエントリポイントです。これはMCPクライアントから起動されることを想定しています。クライアントを接続せずに通常のターミナルで直接実行した場合、stdinが閉じた後に正常終了する場合があります。単体の接続スモークテストには scripts/test_fusion_connection.py を使用してください。

macOS MCPクライアントの例:

{
  "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 にFusionの Contents/Libraries パスが含まれていることを確認してください。

• 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

https://www.python.org/downloads/windows/ からPythonをインストールし、「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と同様に、サーバーコマンドはstdio経由でMCPクライアントから起動されることを想定しています。クライアントを接続せずにシェルで手動実行した場合、stdinが閉じると終了する場合があります。

Windows MCPクライアントの例:

{
  "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 を使用するか、PATH統合を有効にしてPythonを再インストールしてください。

• fusionscript をインポートできない場合は、Fusionのインストールパスを確認し、そのスクリプティングディレクトリを PYTHONPATH に追加してください。

• PowerShellとJSONではスペースを含むパスを引用符で囲み、JSON文字列ではバックスラッシュを2重にしてください。

• 接続に失敗する場合は、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が閉じている場合は、FUSION_NOT_RUNNING とともに success: false を返すはずです。

読み取り専用検査プローブ

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ツールタイプ

• Fusionが公開している場合の、comp.CurrentFrame.FlowView.GetPosTable(tool) によるフローポジション

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

安全な編集ツール

編集操作は、何かを変更する前にアクティブなコンポジション、ノード、入力を検証します。書き込みは、防御的なクリーンアップラッパーを介してFusionの Lock()、StartUndo(...)、EndUndo(True)、Unlock() を使用するため、失敗した操作でアンドゥグループが開いたままになることはありません。

実装済みの編集ツール:

• 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値タイプをサポートしています:

• 有限スカラー数値

• ブール値（数値系のFusion入力では 1 または 0 に変換）

• Text 入力用の文字列

• FuID 入力用の文字列（Fusionが入力を公開している場合は入力ごとの選択肢に対して検証）

• ポイント（[x, y] または {"x": x, "y": y} として）

• 色（[r, g, b]、[r, g, b, a]、またはFusionが真の Color 入力を公開している場合の対応するdictキーとして）

サポートされていない値や曖昧な値は構造化された失敗を返し、書き込みを試みません。画像入力はスカラー値ではなくコネクションとして編集する必要があるため、値設定ツールでは拒否されます。

Fusion Studio 21.0.2の内蔵Backgroundカラーコントロールは、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 は settings={"Clip": "/path/to/output.exr"} でClipパスを受け取ることができ、その設定が指定された場合はプレースホルダーが不要になります。

コネクション編集は現在、画像フローリンクに限定されています。ツールレイヤーは、修飾子、エクスプレッション、マスク、スカラーリンクを通常の画像パイプであるかのように扱わず、明示的なソケットメタデータ付きで拒否します。

安全性の動作:

• ツールIDは作成前にFusionのローカルレジストリと照合されます

• MediaOut は、レジストリクラスがスタンドアロンFusionでは作成できないため拒否されます

• Saver は、Fusionがファイルダイアログを開かないように、明示的なプレースホルダーClipパス付きで作成可能です

• replace=true でない限り、ターゲット入力は置き換えられません

• 自己コネクションと明らかな画像フローの循環は拒否されます

• 削除には confirm=true が必要で、1回の呼び出しにつき1つのノード名のみ受け付けます

• すべての作成/接続/切断/削除操作は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 Studio 21.0.2 における fusion_set_comp_range_tool(1, 48)、fusion_set_current_frame_tool(24)、fusion_save_comp_tool("/tmp/fusionmcp_batch_*.comp") が確認されました。

fusion_create_graph_tool は以下を受け付けます:

• nodes: id、tool_id または tool_type、任意の name、任意の x/y、任意の settings を持つオブジェクト

• connections: source/target にグラフノード ID を持ち、さらに source_output と target_input を持つオブジェクト

• comp_settings: 現在は start_frame/end_frame または global_start/global_end をサポート

グラフ作成は、トランザクションの前または最中に、重複した名前、欠落したグラフ参照、無効なツール ID、明らかなサイクル、およびサポートされていない値を検証します。まずノードを作成し、設定を適用してから、Image ソケットを接続します。後続のステップが失敗した場合、そのリクエストによって作成されたリンクの切断と、そのリクエストによって作成されたノードのみの削除を試み、項目ごとのロールバック結果とともに status: "rolled_back" を返します。

バッチ入力/キーフレーム/削除ツールは、バッチごとに 1 つの Fusion アンドゥグループを使用します。バッチ削除には confirm=true が必要で、明示的にリストされたノードのみを削除します。

レンダリング、診断、エクスポート

レンダリングの実行には confirm=true が必要です。fusion_validate_render_tool は、レンダリングを意図的に実行することなく、アクティブな comp の状態、Saver の存在/タイプ、絶対出力パス、サポートされているファイル拡張子、出力ディレクトリの欠落、上書きリスク、有効なフレーム範囲、接続された Saver のイメージ入力をチェックします。既存の出力は、allow_overwrite=true が明示的に指定されない限り、OUTPUT_ALREADY_EXISTS を返します。

特定の saver_node を指定した fusion_render_tool は、ライブ確認済みの正規の Saver トランザクションを使用します。元の Saver オブジェクトを保持し、Clip を書き換えず、レンダリング前にレンダリングステータスをポーリングせず、Start、End、Wait、Tool を指定して comp.Render を 1 回呼び出し、ディスク上の Saver の Clip パスから出力ファイルを確認します。Fusion が完了を報告したにもかかわらず、期待される出力ファイルが現れない場合、ツールはレンダートレースの詳細とともに RENDER_OUTPUT_MISSING を返します。

診断には、comp の範囲チェック、切断された必須イメージ入力、欠落した Loader パス、無効な Saver パス、None と評価される式、未解決のツール ID、検出可能な場合の重複名が含まれます。

fusion_export_graph_tool は、正確なツール ID、入力 ID、安全な設定、FlowView の位置、イメージフロー接続、および安全に読み取れる場合のネイティブキーフレームを含む fusionmcp.graph.v1 を出力します。

アニメーションと式

ネイティブキーフレームは 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 と評価される場合、不正な式は拒否されます。

テスト

ユニットテストと lint を実行:

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

安全性

書き込みツールは、アクティブなコンポジションを意図的に変更します。より広範な本番環境の保護策が追加されるまで、使い捨てまたは明示的に承認された comp でのみ使用してください。

読み取り専用の検査は、上流のレンダリングをトリガーする可能性があるため、意図的に Output.GetValue() を呼び出しません。出力検査は、出力属性と接続メタデータのみを読み取ります。

本番コンポジションを統合テストに使用しないでください。

スタンドアロンの Fusion Studio 21.0.2 は、このプロジェクトでは MediaOut を Resolve 固有として扱います。スタンドアロンの Fusion はターミナルノードを必要としません。Saver は、AddTool の defsettings なしで作成され、作成後に Clip が割り当てられた場合、通常のスタンドアロンツールとしてサポートされます。作成や検査によってレンダリングがトリガーされることはありません。

レンダリングリリースノート: 2026-07-14 のライブ分離テストで、Saver の Clip 書き込みが有効な文字列として読み戻される一方、保存された .comp にはゼロスパンの内部 Clip オブジェクト (Length = 0、GlobalStart/GlobalEnd = -2000000000) が含まれることが判明しました。その状態では、comp.Render(...) は成功を返し、フレームがレンダリングされたと報告しますが、ファイルは書き込まれません。fusion_render_tool は、レンダリングの直前に Saver の Clip を書き換えなくなりました。検証は副作用なしのままです。

ライブの Saver 初期化プローブには scripts/diagnose_saver_initialization.py を使用してください。現在の生の動作手順は、ロックされていない新しい comp を作成し、Background/Saver を追加している間にロックし、作成後に Saver の Clip を設定し、ロックしたまま接続し、ロックを解除して Tool=saver でレンダリングするというものです。ハーネスと公開 fusion_render_tool は現在そのトランザクションを共有しています。5 回連続の公開 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 です。保護付き編集、グラフ構築、診断、グラフエクスポート、Saver を対象とした確認済みレンダリング、および macOS クリーンマシンでの受け入れノートを備えたローカル Fusion Studio MCP 制御です。より多くの Fusion/Resolve バージョンとより大規模な実世界の comp にわたる、より広範な本番環境での信頼性のために 1.0.0 を予約してください。