Codex용 Fusion MCP

이 프로젝트는 Codex용 로컬 플러그인과 Fusion 360용 애드인을 포함합니다. 핵심 아이디어는 Codex가 MCP를 통해 Autodesk Fusion 360을 검사하고 자동화할 수 있게 하는 것입니다.

아키텍처

• server/main.py: Codex가 stdio로 시작하는 로컬 MCP 서버

• fusion_addin/FusionCodexBridge/: 127.0.0.1:19851에 로컬 HTTP 브리지를 노출하는 Fusion 360 애드인

• .mcp.json: Codex에 로컬 MCP 서버 시작 방법을 알려줌

MCP 서버는 인증된 HTTP를 통해 Fusion 애드인과 통신합니다. 설치 프로그램이 로컬 개인 토큰을 생성하고 두 프로세스 모두 %LOCALAPPDATA%\FusionMCP\credentials.json에서 이를 읽습니다. 애드인은 토큰을 제시하지 않는 요청을 거부합니다. 애드인은 사용자 정의 이벤트를 사용하여 Fusion의 메인 스레드에서 승인된 작업을 실행합니다. 매니페스트는 runOnStartup=true로 FusionCodexBridge를 설치하여 Fusion이 열릴 때 브리지가 자동으로 시작되도록 합니다. POST 요청의 JSON 본문은 기본 1MiB 제한이 있으며, fusion_run_script는 명시적 옵트인 없이는 비활성화된 상태로 유지됩니다.

/health 엔드포인트는 브리지 버전과 protocolVersion을 반환합니다. MCP 클라이언트는 일반 도구를 실행하기 전에 호환성 검사를 수행하며, Fusion이 여전히 오래된 애드인을 실행 중인 경우 안내 오류를 반환합니다. fusion_ping과 fusion_reload_bridge는 진단 및 재로드에 사용할 수 있습니다.

Related MCP server: fusion360-mcp-server

MCP가 노출하는 도구

• fusion_ping

• fusion_status

• fusion_reload_bridge

• fusion_list_documents

• fusion_active_design_summary

• fusion_list_user_parameters

• fusion_list_all_parameters

• fusion_find_entities

• fusion_resolve_entity_token

• fusion_list_bodies

• fusion_list_surface_bodies

• fusion_list_mesh_bodies

• fusion_printability_report

• fusion_list_sketches

• fusion_list_sketch_curves

• fusion_list_sketch_profiles

• fusion_inspect_sketch

• fusion_list_components

• fusion_list_construction_planes

• fusion_list_construction_geometry

• fusion_list_available_appearances

• fusion_list_available_materials

• fusion_list_body_topology

• fusion_inspect_body_physical_properties

• fusion_upsert_user_parameter

• fusion_delete_user_parameter

• fusion_create_rectangle_sketch

• fusion_create_circle_sketch

• fusion_create_line_sketch

• fusion_create_arc_sketch

• fusion_create_ellipse_sketch

• fusion_create_fitted_spline_sketch

• fusion_create_text_sketch

• fusion_create_conic_sketch

• fusion_create_polyline_sketch

• fusion_create_polygon_sketch

• fusion_create_slot_sketch

• fusion_offset_sketch_curves

• fusion_trim_sketch_curve

• fusion_extend_sketch_curve

• fusion_fillet_sketch_curves

• fusion_chamfer_sketch_lines

• fusion_project_entities_to_sketch

• fusion_intersect_entities_with_sketch_plane

• fusion_project_curves_to_surface

• fusion_move_sketch_entities

• fusion_copy_sketch_entities

• fusion_mirror_sketch_entities

• fusion_rectangular_pattern_sketch_entities

• fusion_circular_pattern_sketch_entities

• fusion_add_sketch_constraint

• fusion_add_sketch_dimension

• fusion_set_sketch_dimension_expression

• fusion_delete_sketch_constraint

• fusion_delete_sketch_dimension

• fusion_create_offset_construction_plane

• fusion_create_midplane

• fusion_create_angled_construction_plane

• fusion_create_construction_point_from_sketch_point

• fusion_create_construction_axis_by_two_points

• fusion_create_construction_plane_by_three_points

• fusion_rename_construction_entity

• fusion_delete_construction_entity

• fusion_revolve_profile

• fusion_sweep_profile

• fusion_loft_profiles

• fusion_scale_bodies

• fusion_split_body

• fusion_preview_boundary_fill_cells

• fusion_create_boundary_fill

• fusion_create_silhouette_split

• fusion_merge_faces

• fusion_create_emboss

• fusion_create_derive

• fusion_split_faces

• fusion_delete_faces

• fusion_draft_faces

• fusion_thread_faces

• fusion_thicken_faces

• fusion_replace_faces

• fusion_patch_profile

• fusion_stitch_surface_bodies

• fusion_unstitch_faces

• fusion_extend_surface_edges

• fusion_create_ruled_surface

• fusion_untrim_surface_faces

• fusion_trim_surfaces

• fusion_rename_mesh_body

• fusion_set_mesh_body_visibility

• fusion_set_mesh_body_appearance

• fusion_delete_mesh_body

• fusion_import_mesh

• fusion_convert_mesh_to_brep

• fusion_reduce_mesh

• fusion_repair_mesh

• fusion_combine_mesh_bodies

• fusion_list_sheet_metal_rules

• fusion_create_sheet_metal_rule

• fusion_activate_sheet_metal_rule

• fusion_create_open_hem

• fusion_create_sheet_metal_rip

• fusion_create_box

• fusion_create_plate_with_holes

• fusion_create_printable_svg_plate

• fusion_create_cylinder

• fusion_extrude_profile

• fusion_create_hole

• fusion_fillet_edges

• fusion_chamfer_edges

• fusion_combine_bodies

• fusion_shell_body

• fusion_mirror_bodies

• fusion_rectangular_pattern_bodies

• fusion_circular_pattern_bodies

• fusion_translate_bodies

• fusion_rotate_bodies

• fusion_rename_sketch

• fusion_set_sketch_visibility

• fusion_delete_sketch

• fusion_delete_body

• fusion_set_body_appearance

• fusion_set_face_appearance

• fusion_set_body_material

• fusion_rename_body

• fusion_set_body_visibility

• fusion_rename_construction_plane

• fusion_delete_construction_plane

• fusion_create_component

• fusion_list_component_entities

• fusion_rename_component

• fusion_set_component_visibility

• fusion_activate_component

• fusion_delete_component

• fusion_translate_component

• fusion_create_box_in_component

• fusion_create_cylinder_in_component

• fusion_extrude_component_profile

• fusion_list_assembly_tree

• fusion_list_occurrence_entities

• fusion_list_occurrence_topology

• fusion_create_nested_component

• fusion_move_occurrence_to_component

• fusion_copy_paste_bodies

• fusion_cut_paste_bodies

• fusion_translate_occurrence

• fusion_set_occurrence_grounded

• fusion_create_rigid_group

• fusion_analyze_assembly_interference

• fusion_create_joint

• fusion_create_joint_origin

• fusion_list_joint_origins

• fusion_activate_manufacture_workspace

• fusion_manufacture_status

• fusion_list_cam_setups

• fusion_create_milling_setup

• fusion_list_cam_strategies

• fusion_generate_toolpaths

• fusion_list_cam_parameters

• fusion_set_cam_parameter

• fusion_rename_cam_setup

• fusion_delete_cam_setup

• fusion_rename_cam_operation

• fusion_set_cam_operation_suppression

• fusion_delete_cam_operation

• fusion_list_document_cam_tools

• fusion_list_cam_tool_library

• fusion_create_cam_operation

• fusion_list_cam_post_processors

• fusion_list_nc_programs

• fusion_create_nc_program

• fusion_postprocess_nc_program

• fusion_list_cam_machines

• fusion_assign_cam_machine

• fusion_drawing_status

• fusion_export_drawing_pdf

• fusion_list_workspaces

• fusion_activate_workspace

• fusion_viewport_status

• fusion_set_camera

• fusion_set_viewport_visual_style

• fusion_toggle_mesh_face_groups

• fusion_capture_viewport

• fusion_start_local_render

• fusion_list_render_jobs

• fusion_capture_parameter_animation

• fusion_create_document

• fusion_list_cloud_projects

• fusion_save_document_as

• fusion_activate_document

• fusion_save_document

• fusion_close_document

• fusion_list_timeline

• fusion_rename_timeline_object

• fusion_set_timeline_suppression

• fusion_delete_timeline_object

• fusion_inspect_timeline_dependencies

• fusion_export_step

• fusion_export_stl

• fusion_export_printable_stl

• fusion_import_step

• fusion_export_sketch_dxf

• fusion_import_dxf

• fusion_import_svg

• fusion_export_cad

• fusion_import_cad

• fusion_run_script

스케치 생성 도구는 원점 평면(xy, xz, yz) 또는 construction_plane_index를 사용한 사용자 정의 구성 평면에서 작업할 수 있습니다.

fusion_find_entities는 이름으로 바디, 스케치, 컴포넌트 및 사용자 정의 평면을 검색합니다. exact, contains, fuzzy를 지원하며, 다른 도구가 기대하는 인덱스가 포함된 선택기를 반환합니다.

검사 응답에는 Fusion이 지원하는 경우 entityToken이 포함됩니다. fusion_resolve_entity_token을 사용하면 타임라인 변경 후 현재 엔티티와 해당 인덱스를 복구할 수 있습니다.

제약 조건이나 치수를 추가하려면 먼저 fusion_list_sketch_curves와 fusion_inspect_sketch를 사용하세요. 해당 인덱스는 편집 후 변경될 수 있습니다. fusion_list_sketch_profiles는 면적, 중심, 경계 상자 및 루프가 포함된 돌출 가능한 프로파일을 나열합니다. 복잡한 SVG나 로고가 많은 영역을 생성할 때 profile_indices를 선택하는 데 사용하세요. fusion_add_sketch_constraint는 horizontal, vertical, parallel, perpendicular, equal, tangent, concentric, collinear, coincident, midpoint, symmetry, smooth, fix 및 unfix를 다룹니다. fusion_add_sketch_dimension은 Fusion 표현식을 사용하여 길이, 수평, 수직, 정렬, 각도, 지름 및 반지름 치수를 다룹니다. 선형 치수는 선 하나 또는 두 점을 허용하며, 각도 치수는 두 개의 선이 필요합니다. fusion_set_sketch_dimension_expression을 사용하여 치수를 편집하고, fusion_delete_sketch_* 도구를 사용하여 선택한 치수 또는 제약 조건을 삭제하세요.

fusion_save_document는 이전에 저장된 문서의 새 버전을 저장합니다. 첫 저장 또는 복사본 생성을 위해서는 fusion_list_cloud_projects를 사용한 다음 project_id와 Fusion Team의 기존 폴더 경로를 사용하여 fusion_save_document_as를 호출하세요.

타임라인 도구는 종속 피처와 지오메트리에 영향을 줄 수 있습니다. 요소를 억제하거나 삭제하기 전에 fusion_list_timeline을 실행하는 것이 좋습니다.

fusion_inspect_body_physical_properties는 루트 바디의 질량, 밀도, 질량 중심 및 관성 모멘트를 반환합니다. 정밀도는 low(±1%), medium(±0.5%), high(±0.1%) 또는 very_high(±0.01%)일 수 있습니다. 정밀도가 높을수록 더 오래 걸립니다. fusion_inspect_timeline_dependencies는 연결된 피처와 요소와 연관된 매개변수 간의 관계를 반환합니다.

HTTP 오류는 이제 Fusion 내부에서 생성된 상세 메시지를 유지합니다. 브리지가 활성화되지 않은 경우 Codex는 FusionCodexBridge를 시작하는 방법을 직접 안내합니다. 애드인 변경 사항을 재설치한 후 fusion_reload_bridge는 설치된 버전을 로드하기 위해 Fusion 내부에서 브리지 재시작을 예약합니다. Codex에 새 도구가 아직 표시되지 않으면 Codex를 다시 시작하거나 플러그인 선택기를 다시 열어 MCP 카탈로그를 새로 고치세요.

fusion_thread_faces, fusion_thicken_faces 및 fusion_replace_faces는 fusion_list_body_topology에서 얻은 인덱스로 작업합니다. Fusion은 현재 Rib/Web 생성을 위한 공개 API를 제공하지 않습니다. RibFeatures는 기존 피처 검사만 허용합니다.

fusion_export_cad와 fusion_import_cad는 iges, sat 및 smt를 지원합니다. DXF의 경우 형식이 스케치와 2D 평면에 적용되므로 별도의 도구가 사용됩니다. fusion_export_printable_stl은 루트 컴포넌트 또는 특정 바디의 STL을 내보내기 전에 기본 인쇄 가능성 검사를 실행하고 생성된 파일과 함께 보고서를 반환합니다. fusion_import_svg는 원점 또는 구성 평면의 새 스케치에 SVG를 오프셋 및 배율과 함께 가져옵니다. 직접 인쇄 가능한 플레이트의 경우 fusion_create_printable_svg_plate는 직사각형 솔리드 베이스를 만들고, 상단 면에 SVG를 가져오고, 해당 프로파일을 결합 릴리프, 분리 릴리프 또는 컷으로 돌출시킵니다. 복잡한 SVG에서는 profile_selection(all, largest, area_desc, outer_only)과 min_profile_area_cm2를 사용하여 노이즈를 제거할 수 있습니다. profile_indices는 정확한 수동 선택을 위해 계속 사용할 수 있습니다.

비루트 컴포넌트 내 작업은 상자, 원통, 프로파일 돌출을 포함합니다. 중첩 어셈블리의 경우 fusion_list_assembly_tree를 사용하세요. 이 함수는 fullPathName을 반환하며, 이는 중첩된 occurrence의 검사, 생성, 이동, 변환 도구가 사용하는 안정적인 선택자입니다. fusion_copy_paste_bodies와 fusion_cut_paste_bodies는 원본 컴포넌트의 로컬 인덱스를 사용합니다. 루트 컴포넌트의 경우 경로를 비워 두세요. 잘라내기/붙여넣기는 본체를 이동하며 allow_move_bodies=true가 필요합니다. occurrence는 컴포넌트 정의를 나타냅니다. 해당 정의에 여러 인스턴스가 있는 경우 본체를 복사하거나 이동하면 모든 인스턴스에 영향을 줄 수 있습니다. 도구는 이를 수행하기 전에 추가 확인을 요구합니다. 조인트를 만들기 전에 fusion_list_occurrence_topology를 사용하여 각 occurrence의 컨텍스트 내에서 면 인덱스를 가져오세요. fusion_create_joint의 MVP는 평면과 rigid 또는 revolute 조인트를 지원합니다. 두 번째 occurrence는 조인트를 만들 때 재배치할 수 있습니다. fusion_set_occurrence_grounded, fusion_create_rigid_group, fusion_analyze_assembly_interference는 occurrence 경로에서 작동하며, 마지막 함수는 설계를 수정하지 않습니다.

Surface는 표면 나열, 패치, 스티치, 언스티치, 확장, 룰드 서피스, 트림, 언트림 및 fusion_thicken_faces 재사용을 허용합니다. fusion_trim_surfaces에서는 먼저 selected_cell_indices=[]를 사용하여 인덱스 미리보기를 얻은 다음, 삭제할 셀로 호출을 반복하세요.

Mesh는 STL/OBJ/3MF 가져오기, 본체 검사 및 관리, 외관 지정, 변환, 축소, 복구 및 결합을 허용합니다. fusion_printability_report는 루트 가시 본체의 3D 인쇄를 위한 기본 기하학적 조건을 검사합니다: B-Rep 솔리드 또는 닫힌/방향이 지정된 메시로 양의 부피를 가져야 합니다. 이는 volumeCm3이 0인 열린 메시와 같은 시각적 사례를 감지하는 데 유용하지만, 최종 검증은 슬라이서의 몫입니다. fusion_create_printable_svg_plate는 플레이트를 만든 후 해당 보고서를 반환하여 시각적 기하학만 남는 것을 방지합니다. 네 가지 수정 작업은 Autodesk의 미리보기 API를 사용하며 일부 설치에서는 사용하지 못할 수 있습니다. 이 경우 도구는 안내 지침을 반환합니다.

Sheet Metal의 초기 매핑은 규칙, 규칙 활성화, 열린 헴, 기존 시트 메탈 본체에 대한 립을 다룹니다. Autodesk는 현재 공개 API에서 베이스 플랜지/플랜지 생성을 노출하지 않습니다.

Manufacture는 워크스페이스 활성화, 셋업/작업/매개변수 검사, 밀링 셋업 생성, CAM 표현식 편집, 요소 이름 변경/억제/삭제, 호환 전략 발견 및 툴패스 생성을 허용합니다. 또한 문서 또는 URL의 라이브러리에서 도구를 쿼리하고, 도구 및 표현식과 호환되는 모든 strategy를 생성하고, 머신을 쿼리/할당하고, 포스트를 검색하고, NCProgram을 생성하고 포스트프로세싱할 수 있습니다.

권장 CAM 흐름: 셋업을 생성하거나 검사하고, fusion_list_cam_strategies를 쿼리하고, fusion_list_document_cam_tools 또는 fusion_list_cam_tool_library로 도구를 선택하고, fusion_create_cam_operation으로 작업을 생성하고 툴패스를 생성합니다. NC 코드의 경우 머신/포스트를 발견하고, 프로그램을 생성하고, confirm_postprocess=true로 fusion_postprocess_nc_program을 실행하기 전에 인덱스를 검토하세요. 출력 디렉터리는 존재해야 하며 머신, 도구, 원점 및 충돌에 대한 최종 검증은 여전히 운영자의 책임입니다.

Drawing은 문서/활성 시트를 검사하고 모든 시트 또는 범위를 PDF로 내보낼 수 있습니다. Drawing 공개 API는 아직 모든 시트, 뷰 및 주석을 프로그래밍 방식으로 생성하고 편집할 수 있는 완전한 컬렉션을 노출하지 않습니다.

Render/Animation에는 카메라 읽기 및 제어, 뷰포트 시각적 스타일 제어, 뷰포트 캡처, 비동기 로컬 렌더링 및 작업 추적이 포함됩니다. fusion_capture_viewport는 output_path 없이 최대 20MiB의 인라인 PNG를 반환하고 종료 전에 임시 파일을 삭제합니다. 이는 시각적 검사에 권장되는 모드입니다. 캡처를 보존하거나 더 큰 이미지를 생성하려면 명시적 output_path와 persist=true를 전달하세요. 호환성을 위해 이미 경로를 제공하는 이전 호출은 계속 유지됩니다. 비동기 렌더링과 애니메이션은 여전히 사용자가 지정한 명시적 경로에 씁니다. fusion_toggle_mesh_face_groups는 Fusion이 재질을 숨기고 면 그룹 색상을 표시할 때 메시 면 그룹의 표시를 끄거나 켤 수 있습니다. fusion_capture_parameter_animation은 매개변수의 표현식을 보간하고, 카메라를 궤도 회전시킬 수 있으며, PNG 시퀀스를 쓰고 원래 매개변수/카메라를 복원합니다. 최종 비디오 어셈블리는 Fusion 외부에서 수행됩니다.

fusion_list_workspaces와 fusion_activate_workspace는 ID로 워크스페이스를 발견하고 활성화할 수 있습니다. Simulation에서는 탐색만 다룹니다. Autodesk는 현재 adsk.cam과 동등한 연구를 생성하고 해결하기 위한 API 모델을 공개하지 않습니다.

fusion_split_body는 현재 절단 도구로 원점 평면 또는 기존 구성 평면을 사용합니다. 나중에 프로파일, 면 또는 본체를 분할 도구로 확장할 수 있습니다.

Boundary Fill의 경우 먼저 body 및/또는 construction_plane 선택자로 fusion_preview_boundary_fill_cells를 사용하세요. 각 임시 셀의 부피, 면적, 면 및 경계 상자를 반환합니다. 그런 다음 동일한 선택자를 동일한 순서로 fusion_create_boundary_fill과 보존하려는 selected_cell_indices로 즉시 반복하세요. 해당 인덱스는 임시적이며 모델을 편집한 후에는 재사용해서는 안 됩니다. operation은 new_body, join, cut 또는 intersect를 허용합니다. remove_tool_bodies는 도구로 사용된 본체를 삭제하므로 allow_remove_tools=true도 필요합니다.

fusion_create_silhouette_split은 루트 솔리드 본체에 실루엣 분할선을 계산합니다. 방향은 construction_axis, construction_plane, 선형 모서리 또는 평면을 허용합니다. faces_only는 기본 비파괴 모드이고, shelled_body와 solid_body는 본체를 분할합니다. Fusion은 이 기능을 호환 가능한 본체로 제한합니다. 구는 흐름을 확인하는 간단한 사례입니다.

fusion_merge_faces는 동일한 솔리드 또는 표면 본체의 연결된 면을 결합하지만 Direct Modeling 설계에서만 가능합니다. 직접 B-Rep 편집이므로 피처나 타임라인 항목을 만들지 않으며 allow_direct_modification=true가 필요합니다. is_chain_selection=true를 사용하여 시드 면을 호환 가능한 연결 체인으로 확장하세요.

fusion_create_emboss는 스케치 프로파일을 루트 본체의 면에 매핑합니다. 양의 깊이는 릴리프, 음의 깊이는 각인에 사용합니다. 표현식은 단위 또는 Fusion 매개변수를 허용합니다. MVP는 호출당 하나의 프로파일과 하나의 면을 노출하며 선택적 오프셋과 회전이 있습니다. Fusion이 2025년 9월에 도입한 Emboss API가 필요합니다. 사용할 수 없으면 안내 표시를 반환합니다.

fusion_create_derive는 Fusion에서 이미 열려 있고 저장된 다른 설계 문서에서 파생 링크를 만듭니다. fusion_list_documents를 사용하여 source_document_index를 식별하세요. 소스 엔터티로 root_component, body, mesh_body, sketch, construction_plane 또는 occurrence를 허용합니다. 활성 문서는 항상 대상이며 자체적으로 파생될 수 없습니다. 이 도구는 2026년 1월에 도입된 Derive API가 필요합니다.

fusion_split_faces는 도구로 body, face, sketch_curve 또는 construction_plane 선택자를 허용합니다. surface_intersection, closest_point, along_vector 모드를 지원합니다. fusion_delete_faces는 기본적으로 heal을 사용하여 Fusion이 본체를 복구하도록 시도합니다. surface 모드는 복구 없이 삭제하며 열린 표면 본체를 남길 수 있으므로 allow_make_surface=true가 필요합니다. 모든 fusion_delete_* 도구는 이제 대상 선택자와 confirm_delete=true를 요구합니다. 확인 직전에 대상을 나열하거나 검사하세요. 저장하지 않고 닫으려면 save_changes=false와 confirm_discard_changes=true가 필요합니다.

fusion_draft_faces는 중립 평면을 사용하여 본체의 면에 드래프트를 적용합니다. 일반적으로 먼저 fusion_list_body_topology를 사용하여 face_indices를 얻습니다.

로컬 테스트

Fusion을 열지 않고 사용 가능한 단위 및 계약 테스트를 실행하려면:

python -m unittest discover -s tests

이 세트는 README의 도구 목록, ROADMAP의 개수, 브리지/플러그인/매니페스트 버전 및 MCP 프로토콜이 동기화되었는지도 확인합니다.

두 주요 Python 진입점의 구문을 빠르게 확인하려면:

python -m py_compile server/main.py fusion_addin/FusionCodexBridge/FusionCodexBridge.py

브리지가 활성화된 Fusion을 대상으로 실제 3D 인쇄 스모크 테스트를 실행하려면:

python .\scripts\smoke_printable_svg.py

이 스모크 테스트는 임시 문서를 만들고, SVG에서 플레이트를 생성하고, fusion_export_printable_stl로 STL을 내보내고, 파일이 존재하는지 확인하고, 저장하지 않고 문서를 닫습니다. 아티팩트는 scratch/fusion-smoke에 남습니다.

브리지가 활성화된 Fusion을 대상으로 기본 스케치의 실제 스모크 테스트를 실행하려면:

python .\scripts\smoke_sketch_basics.py

이 스모크 테스트는 임시 문서를 만들고, 사각형, 원, 선, 호, 폴리라인, 다각형 및 슬롯 스케치를 생성하고, 오프셋, 제약 조건, 치수 및 검사를 테스트하고, 저장하지 않고 문서를 닫습니다.

요구 사항

• Windows에서 Python 3.10 이상이 PATH에 python으로 사용 가능해야 함

• Autodesk Fusion 360

보안 설정

• fusion_run_script는 기본적으로 비활성화되어 있습니다. 의도적으로 활성화하려면 MCP 프로세스와 Fusion 360 모두에 FUSION_MCP_ENABLE_RUN_SCRIPT=1을 설정하고 둘 다 다시 시작하세요. 스크립트는 사용자의 전체 권한으로 실행되므로 전용 도구를 선호해야 합니다.

• FUSION_MCP_MAX_REQUEST_BODY_BYTES는 브리지의 JSON 페이로드 한도를 조정합니다. 기본값은 1MiB이고 허용되는 최대값은 16MiB입니다.

• 삭제, 변경 사항 폐기 및 포스트프로세싱 작업에는 명시적 확인 플래그가 필요합니다. 해당 플래그는 대상 사전 검사를 대체하지 않습니다.

Windows 권장 설치

이 저장소가 이미 로컬에 있다면 가장 빠른 설치 방법은 다음과 같습니다:

powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1

이 설치 프로그램은 다음을 수행합니다:

• MCP와 Fusion을 인증하기 위한 임의의 개인 자격 증명을 생성하거나 유지합니다.

• 자격 증명 파일을 보호하고, 전용 폴더를 만들 때 해당 폴더의 권한도 현재 사용자로 제한합니다. 기존 상위 폴더의 ACL은 변경하지 않습니다.

• 허용된 파일 목록에서 플러그인을 빌드하고 ~/plugins/fusion-mcp에 복사합니다. 캡처, 백업, CAD 또는 기타 워크스페이스 아티팩트는 포함하지 않습니다.

• 매니페스트로 플러그인 및 애드인 대상을 검증합니다. 저장소와의 겹침, 인식되지 않는 폴더, 정션 및 관리 대상 내 상태 파일을 거부합니다.

• 후보 + 백업으로 런타임을 게시하고 마켓플레이스가 실패하면 이전 버전을 복원합니다.

• 런타임을 게시한 후 ~/.agents/plugins/marketplace.json을 원자적 교체로 업데이트합니다.

• requirements.txt의 종속성을 설치합니다.

• Fusion 애드인을 %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\FusionCodexBridge에 복사합니다. 해당 폴더가 없으면 %APPDATA%\Autodesk\Autodesk Fusion\API\AddIns\FusionCodexBridge를 사용합니다.

• 해당 설치 폴더를 동기화하고 이전 버전의 오래된 파일을 제거합니다.

• Autodesk의 대체 경로에서 FusionCodexBridge의 다른 복사본을 찾으면 경고합니다. Fusion이 이전 복사본을 로드할 수 있기 때문입니다.

Codex 부분만 설치하고 Fusion 애드인을 아직 복사하지 않으려면 다음을 사용할 수 있습니다:

powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1 -SkipFusionAddIn

작동시키기 위한 단계별 가이드

1. 리포지토리 루트에서 터미널을 엽니다.

2. 설치 프로그램을 실행합니다:

   powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1

3. Fusion 360을 엽니다.

4. Fusion에서 Utilities > Add-Ins > Scripts and Add-Ins로 이동합니다.

5. Add-Ins 탭으로 이동합니다.

6. 목록이 비어 보이면, 애드인이 없다고 가정하기 전에 먼저 필터를 정리합니다.

7. FusionCodexBridge를 찾아 Run으로 실행합니다.

8. FusionCodexBridge가 목록에 나타나지 않으면 + 버튼을 사용하여 다음 폴더 중 하나를 수동으로 지정합니다:

   • %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\FusionCodexBridge

   • %APPDATA%\Autodesk\Autodesk Fusion\API\AddIns\FusionCodexBridge

9. Fusion 로컬 브리지가 실행 중인지 확인합니다:

   $credential = Get-Content "$env:LOCALAPPDATA\FusionMCP\credentials.json" -Raw | ConvertFrom-Json
   Invoke-RestMethod http://127.0.0.1:19851/health -Headers @{ Authorization = "Bearer $($credential.token)" }

   "ok": true가 포함된 JSON 응답을 받아야 합니다.

10. 필요한 경우 Codex를 재시작하거나 VS Code 창을 새로고침합니다.

11. Codex CLI 또는 Codex 앱을 사용하는 경우 MCP 서버를 한 번만 등록합니다:

codex mcp add fusion-local -- python "$HOME\plugins\fusion-mcp\server\main.py"

12. 서버가 등록되었는지 확인합니다:

codex mcp list

13. Codex로 돌아가 간단한 지시문으로 테스트합니다. 예:

• Fusion에서 활성 설계 검토

• fusion_status 실행

• 10x6x3 cm 상자 만들기

수동 설치

수동 설치도 MCP와 Fusion이 FUSION_MCP_TOKEN 또는 FUSION_MCP_CREDENTIALS_FILE이 가리키는 JSON 파일을 통해 최소 32자 토큰을 공유해야 합니다. 권한 및 구성 오류를 방지하려면 설치 프로그램을 최소 한 번 실행하는 것이 좋습니다.

설치 프로그램을 사용하지 않으려면 수동으로 진행할 수 있습니다:

1. Python 종속성을 설치합니다:

   pip install -r requirements.txt

2. fusion_addin/FusionCodexBridge/를 Fusion의 Add-Ins 폴더로 복사합니다:

   • %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\

   • 또는 %APPDATA%\Autodesk\Autodesk Fusion\API\AddIns\

3. Codex에 MCP 서버를 등록합니다:

   codex mcp add fusion-local -- python "$PWD\server\main.py"

4. Fusion 360을 열고 Utilities > Add-Ins > Scripts and Add-Ins에서 FusionCodexBridge를 실행합니다.

문제 해결

• Fusion에 애드인 목록이 비어 표시되면 먼저 Scripts and Add-Ins 창의 필터를 정리합니다.

• VS Code에 No MCP Servers found가 표시되면 Developer: Reload Window를 실행한 다음 MCP: List Servers를 다시 사용합니다.

• VS Code 확장 Marketplace에서 fusion-local을 검색하지 마세요. 이는 로컬 MCP 서버이지 Marketplace 확장이 아닙니다.

• Codex가 서버는 인식하지만 Fusion에 대한 작업이 실패하면 위의 /health 확인 명령을 사용하거나 fusion_ping을 실행하세요. 모든 엔드포인트는 로컬 Bearer 토큰이 필요합니다.

• Codex가 브리지가 호환되지 않거나 protocolVersion이 없다고 보고하면 powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1을 실행한 다음 fusion_reload_bridge를 실행하거나 Fusion을 재시작합니다.

• 설치 프로그램이 FusionCodexBridge의 다른 복사본이 존재한다고 경고하면 Scripts and Add-Ins를 열고 설치 프로그램이 출력한 업데이트된 폴더를 실행 중인지 확인합니다.

• Unauthorized Fusion MCP request를 받으면 설치 프로그램을 다시 실행하고 Codex와 애드인을 재시작하여 둘 다 동일한 자격 증명을 사용하도록 합니다.

• 설치 프로그램이 기존 자격 증명 파일을 거부하면 CredentialPath가 올바른지 확인합니다. 실제로 손상된 자격 증명을 다시 생성하려면 해당 파일을 명시적으로 이동하거나 삭제한 후 설치 프로그램을 다시 실행하세요. 설치 프로그램은 알 수 없는 파일을 덮어쓰지 않습니다.

• %LOCALAPPDATA%\FusionMCP\credentials.json을 복사하거나 게시하지 마세요. 설치 프로그램은 토큰을 표시하지 않습니다.

참고 사항

• fusion_run_script는 Fusion 내부에서 Python을 실행하며 API에 대한 전체 액세스 권한을 가지며 기본적으로 비활성화되어 있습니다. 신뢰할 수 있는 코드에서만 명시적 옵트인을 통해 사용하세요.

• /health를 포함한 모든 엔드포인트는 설치 중 생성된 Bearer 토큰이 필요합니다.

• 스크립트 도구는 result 변수에 할당된 값을 반환합니다.

• 브리지가 실행 중이 아니면 애드인을 시작한 후 fusion_ping 또는 fusion_status로 먼저 테스트해 보세요.