fusion-reconstruct-mcp

MCP 서버로, LLM이 STL/3MF 메시(또는 참조 사진)를 파라메트릭 Fusion 360 모델로 변환할 수 있게 해줍니다 — 스케치, 돌출, 필렛, 패턴 등 기능별로 하나씩 재구성하며, 단순 메시 바디로 가져오지 않습니다.

왜 필요한가

슬라이서(Bambu Studio, PrusaSlicer 등)는 STL/3MF만 이해합니다: 구워진 삼각형 메시입니다. Fusion 360은 파라메트릭 피처 트리만 이해합니다. STL을 Fusion에 가져오면 볼 수는 있지만 의미 있게 편집할 수 없는 솔리드가 됩니다 — 파라메트릭 치수도, 편집 가능한 스케치도, 슬라이더를 움직일 수 있는 것도 없습니다. 이 프로젝트는 LLM이 메시를 보고 그것이 무엇으로 이루어졌는지(플레이트, 구멍, 보스, 리브 등) 파악한 다음 실제 Fusion 피처로 재구성하여, 직접 손으로 만든 모델처럼 크기를 조절하거나 구멍을 추가하거나 수정할 수 있는 모델을 얻을 수 있게 함으로써 그 격차를 메웁니다.

Related MCP server: Fusion360 LLM Assistant

범위 (먼저 읽어주세요)

이 프로젝트는 기계적/기능적 부품을 대상으로 합니다 — 브래킷, 인클로저, 마운트, 볼트 구멍이 있는 플레이트, 보스 — 프리미티브(돌출, 회전, 필렛, 모따기, 패턴, 미러, 불리언 연산)로부터 재구성합니다. 자유 형상/유기적 표면 재구성은 시도하지 않습니다. 그것은 훨씬 더 어렵고 신뢰성도 낮은 문제로, 이 프로젝트가 해결하려는 범위가 아닙니다. 의도된 워크플로는 docs/RECONSTRUCTION_STRATEGY.md를 참조하세요.

작동 방식

flowchart LR
    LLM["LLM client"] -- MCP --> Server["MCP server<br/>(mesh analysis + Fusion bridge client)"]
    Server -- HTTP, localhost --> Addin["Fusion 360 add-in<br/>(runs inside Fusion)"]
    Addin --> Fusion[("Your live Fusion design")]

MCP 서버는 두 가지 도구 패밀리를 노출합니다:

• mesh_summary, find_circular_holes, find_circular_faces, list_planar_facets, get_cross_section, render_orthographic_views, compare_meshes — 순수 메시 분석(trimesh)으로, Fusion이 필요 없습니다. 입력 파일을 이해하고 이후 재구성의 정확도를 검증하는 데 사용됩니다.

• fusion_* (스케치 생성, 선/원/사각형/호 추가, 돌출, 회전, 필렛, 모따기, 패턴, 미러, 결합, 매개변수 설정/조회, 내보내기, 스크린샷 등) — http://127.0.0.1:6172를 통해 동반 Fusion 360 애드인과 통신하며, 실행 중인 Fusion 세션 내부의 실제 adsk.fusion API에 대해 명령을 실행합니다.

왜 이런 식으로 분할했는지는 docs/ARCHITECTURE.md를 참조하세요 (요약: Fusion의 API는 Fusion 자체 프로세스 내부, 메인 스레드에서만 실행되며 pip 액세스가 없습니다 — 따라서 애드인은 표준 라이브러리 전용의 작은 HTTP 브리지여야 합니다).

설정

전체 지침은 docs/SETUP.md를 참조하세요. 요약:

git clone https://github.com/<your-username>/fusion-reconstruct-mcp.git
cd fusion-reconstruct-mcp
python -m venv .venv && source .venv/bin/activate  # .venv\Scripts\activate on Windows
pip install -r requirements.txt

그런 다음 fusion_addin/FusionReconstructBridge/를 Fusion의 AddIns 폴더에 복사하고 유틸리티 > 애드인 > 스크립트 및 애드인에서 시작한 다음, MCP 클라이언트(claude mcp add ... 또는 mcp.json)가 이 저장소의 python -m server.mcp_server를 가리키게 하세요.

사용 방법

Fusion이 실행 중이고 애드인이 시작된 상태에서 LLM 클라이언트에 다음과 같이 요청하세요:

~/Downloads/bracket.stl을 파라메트릭 Fusion 360 모델로 재구성한 다음 내보내고 원본과 얼마나 가까운지 확인해줘.

그러면 메시를 검사하고, 렌더링된 뷰를 살펴보고, 구멍/보스를 찾아내고, Fusion에서 피처별로 부품을 재구성한 다음, 내보내기와 소스 메시와의 비교를 통해 결과를 검증합니다. 메시 대신 사진을 사용하는 경우, 설명/이미지로부터 첫 번째 패스를 만들고 사용자와 대화형으로 다듬습니다 — 단일 사진에는 실측 치수 데이터가 없으므로 이 경로는 "스캔 투 CAD"가 아닌 "보조 모델링"으로 취급하세요.

상태 / 제한 사항

• 원/구멍 감지는 메시 테셀레이션 휴리스틱(패싯 외곽선 원 피팅)입니다 * 일반적인 프린터용 부품에서는 잘 작동하지만 범용 피처 인식 엔진은 아닙니다.

  • 사진 기반 재구성은 비율을 추정합니다. 단일 이미지에서 실제 세계 치수를 측정하지 않습니다.

• render_orthographic_views는 일반 matplotlib 와이어프레임/솔리드 렌더러(GPU 의존성 없음)를 사용합니다 — 전체 형상을 보기에는 충분하며, 포토리얼리스틱은 아니고 복잡한 부품에서 약간의 z-순서 아티팩트가 나타날 수 있습니다.

• 한 번에 하나의 Fusion 문서/브리지 연결만 지원합니다.

• fusion_create_sketch의 명명된 기본 평면 경로(plane="XY"/"XZ"/"YZ", 선택적으로 offset_mm)는 철저히 실시간 검증되었습니다. 임의 평면 경로(origin+normal)는 실제 버그가 수정되었지만(setByThreePoints는 원시 Point3D가 아닌 점 엔티티가 필요합니다 — git 히스토리 참조) 이후에 작동이 확인되지는 않았습니다: 다음 시도에서 두 번째로 다른 오류(ConstructionPoints.add의 "Environment is not supported")가 나타났다가 애드인을 다시 시작하니 사라졌는데, 이는 코드 버그라기보다 일시적인 Fusion 상태로 보이지만 해당 경로는 재테스트 대신 우회되었습니다. 누군가 실시간으로 확인할 때까지 검증되지 않은 것으로 취급하세요.

• mcp>=2.0.0의 MCPServer API에 대해 빌드 및 스모크 테스트되었습니다. Fusion 측 작업은 모두 실제 실행 중인 Fusion 360 세션에서 테스트되었습니다(문서만 보고 작성된 것이 아님) — tests/smoke_test_fusion_live.py(스케치 → 돌출 → 절단/결합 → 내보내기, 원본 메시에 대해 0.01mm 이내로 검증) 및 tests/smoke_test_fusion_live_features.py(필렛, 모따기, 미러, 원형 패턴, 회전, 명시적 결합)를 참조하세요. sketch_add_line, sketch_add_arc_three_point 및 pattern_rectangular는 테스트된 형제 기능과 코드 경로를 공유하지만 자체 전용 라이브 테스트는 아직 없습니다. 이 중 어떤 것도 CI에서 실행되지 않습니다(헤드리스 Fusion이 없음) — fusion_addin/에 대한 이슈/PR은 언제든 환영합니다.

라이선스

MIT — LICENSE를 참조하세요.