Fusion Studio MCP

독립형 Blackmagic Fusion Studio를 Fusion의 스크립팅 API를 통해 검사하고 제어하기 위한 로컬 MCP 서버입니다.

이 프로젝트는 보수적으로 시작합니다. 먼저 Fusion 연결을 검증하고, 그다음 읽기 전용 검사 도구를 노출하며, 그다음 드라이런(dry-run) 및 실행 취소(undo) 동작이 있는 보호된 편집 도구를 추가합니다.

현재 상태

• 프로젝트 스캐폴드 생성: 2026-07-13

• 대상 앱 확인: Blackmagic Fusion 21.0.2

• Fusion 번들 fusionscript.so의 Python import 경로 확인됨

• 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

macOS에서 Claude Desktop으로 설치

아티스트와 비개발자에게 권장: Fusion Studio MCP - Claude Desktop (macOS) 설치.

이것은 macOS에서 독립형 Fusion Studio와 Claude Desktop을 위한 공개된 두 번의 복사-붙여넣기 설정 경로입니다. 공개 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를 import할 수 없으면 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를 import할 수 없으면 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 도구 유형

• 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 경로를 받을 수 있으며, 해당 설정이 제공되면 더 이상 플레이스홀더가 필요하지 않습니다.

연결 편집은 현재 Image 흐름 링크로 범위가 제한됩니다. 도구 계층은 일반 이미지 파이프인 것처럼 가장하는 대신 명시적 소켓 메타데이터로 수정자, 표현식, 마스크, 스칼라 링크를 거부합니다.

안전 동작:

• 도구 ID는 생성 전에 Fusion의 로컬 레지스트리에서 확인됩니다.

• MediaOut은 독립형 Fusion에서 해당 레지스트리 클래스를 만들 수 없으므로 거부됩니다.

• Saver는 Fusion이 파일 대화 상자를 열지 않도록 명시적 플레이스홀더 Clip 경로로 생성할 수 있습니다.

• 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 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"을 반환합니다.

배치 입력/키프레임/삭제 도구는 배치당 하나의 Fusion 실행 취소 그룹을 사용합니다. 배치 삭제는 confirm=true가 필요하며 명시적으로 나열된 노드만 삭제합니다.

렌더, 진단 및 내보내기

렌더 실행에는 confirm=true가 필요합니다. fusion_validate_render_tool은 의도적인 렌더링 없이 활성 컴포지션 상태, Saver 존재/유형, 절대 출력 경로, 지원되는 파일 확장자, 누락된 출력 디렉터리, 덮어쓰기 위험, 유효한 프레임 범위, 연결된 Saver 이미지 입력을 확인합니다. 기존 출력은 allow_overwrite=true가 명시적으로 제공되지 않는 한 OUTPUT_ALREADY_EXISTS를 반환합니다.

특정 saver_node를 사용하는 fusion_render_tool은 표준 라이브 확인 Saver 트랜잭션을 사용합니다. 원래 Saver 객체를 유지하고, Clip을 다시 쓰지 않으며, 렌더링 전에 렌더 상태를 폴링하지 않고, Start, End, Wait, Tool로 comp.Render를 한 번 호출한 다음 디스크의 Saver Clip 경로에서 출력 파일을 확인합니다. Fusion이 완료를 보고했지만 예상 출력 파일이 나타나지 않으면 도구는 렌더 추적 세부 정보와 함께 RENDER_OUTPUT_MISSING을 반환합니다.

진단에는 컴포지션 범위 확인, 연결이 끊긴 필수 이미지 입력, 누락된 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으로 평가되면 잘못된 표현식으로 간주되어 거부됩니다.

테스트

단위 테스트와 린트를 실행합니다:

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

안전

쓰기 도구는 의도적으로 활성 컴포지션을 수정합니다. 더 광범위한 프로덕션 보호 장치가 추가될 때까지 일회용 또는 명시적으로 승인된 컴포지션에서만 사용하세요.

읽기 전용 검사는 의도적으로 Output.GetValue()를 호출하지 않습니다. 업스트림 렌더링을 트리거할 수 있기 때문입니다. 출력 검사는 출력 속성과 연결 메타데이터만 읽습니다.

프로덕션 컴포지션은 통합 테스트에 사용해서는 안 됩니다.

독립 실행형 Fusion Studio 21.0.2는 이 프로젝트에서 MediaOut을 Resolve 전용으로 취급합니다. 독립 실행형 Fusion은 터미널 노드가 필요하지 않습니다. Saver는 AddTool defsettings 없이 생성된 후 Clip이 할당되면 일반 독립 실행형 도구로 지원됩니다. 생성이나 검사로 렌더가 트리거되지 않습니다.

렌더 릴리스 노트: 2026-07-14 라이브 격리 테스트에서 Saver Clip 쓰기가 유효한 문자열로 다시 읽히는 반면 저장된 .comp에는 길이가 0인 내부 Clip 객체(Length = 0, GlobalStart/GlobalEnd = -2000000000)가 포함되어 있음을 발견했습니다. 이 상태에서 comp.Render(...)는 성공을 반환하고 프레임이 렌더링되었다고 보고하지만 파일은 기록되지 않습니다. fusion_render_tool은 더 이상 렌더 직전에 Saver Clip을 다시 쓰지 않습니다. 검증은 부작용이 없는 상태로 유지됩니다.

라이브 Saver 초기화 프로브에는 scripts/diagnose_saver_initialization.py를 사용하세요. 현재 원시 작업 순서는 잠금 해제된 새 컴포지션을 만들고, Background/Saver를 추가하는 동안 잠그고, 생성 후 Saver Clip을 설정하고, 잠긴 상태에서 연결하고, 잠금을 해제한 다음 Tool=saver로 렌더링하는 것입니다. 하네스와 공개 fusion_render_tool은 이제 이 트랜잭션을 공유합니다. 연속 5회의 공개 그래프/검증/렌더 사이클이 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 버전과 더 큰 실제 컴포지션에서 광범위한 프로덕션 신뢰도를 확보하려면 1.0.0을 유보하세요.