🛠️ MCP-FreeCAD 통합

참고: 이 저장소는 현재 활발하게 개발 중입니다. 매일 커밋이 있을 수 있으며, 잠재적인 변경 사항이 있을 수 있습니다.

이 프로젝트는 모델 컨텍스트 프로토콜(MCP)을 사용하여 AI 어시스턴트와 FreeCAD CAD 소프트웨어 간의 강력한 통합을 제공합니다. 외부 애플리케이션이 표준화된 인터페이스를 통해 FreeCAD와 상호 작용할 수 있도록 지원하며, 다양한 연결 방식과 특수 도구를 제공합니다.

빠른 시작(권장: AppImage + Launcher)

가장 안정적인 설정을 위해 다음 단계를 따르세요.

1. 환경 설정(일회성) : 설정 스크립트를 실행합니다. 이 스크립트는 저장소를 ~/.mcp-freecad 에 복제하고, Python 가상 환경을 생성하고, 최신 FreeCAD AppImage를 다운로드하고 압축을 푼 후, 서버에서 해당 파일을 사용하도록 설정합니다.지엑스피1또는 리포를 복제하고 ./scripts/bin/setup_freecad_env.sh 수동으로 실행합니다.
2. MCP 서버 실행 : 설치 스크립트를 사용하세요(이제는 venv가 활성화되어 있고 서버가 실행 중인지 확인하는 역할만 합니다) 또는 설치된 경우 글로벌 명령을 사용하세요.
   # Option A: Run via the installer script in the default location ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh # Option B: Run the global command (if installed via install-global.sh) mcp-freecad

이렇게 하면 다운로드 및 추출된 AppImage를 사용하여 권장되는 launcher 방법을 사용하여 MCP 서버가 시작됩니다.

도커 지원

더 쉬운 배포와 격리를 위해 Docker 컨테이너에서 MCP-FreeCAD를 실행할 수도 있습니다.

Docker Compose로 실행

1. 컨테이너 시작 :
   docker compose up
2. 처음부터 빌드하기 (변경 사항이 있는 경우):
   docker compose build --no-cache docker compose up

Docker 컨테이너는 다음 포트를 노출합니다.

• 8080: MCP 서버
• 12345: FreeCAD 서버

Docker 구성

Docker 설정은 다음으로 구성됩니다.

• Dockerfile : Python 3.12로 컨테이너를 정의하고, 종속성을 설치하고, 환경을 설정합니다.
• docker-compose.yml : 서비스, 포트, 볼륨 및 재시작 정책을 구성합니다.
• .dockerignore : 컨테이너에서 불필요한 파일을 제외합니다.

이러한 접근 방식은 CI/CD 파이프라인이나 MCP-FreeCAD 환경을 시스템에서 분리해야 할 때 특히 유용합니다.

🔄 MCP 흐름도

이 흐름도는 주요 구성 요소를 보여주고 freecad_connection_manager.py 에서 선택한 다양한 연결 방법이 FreeCAD 내에서 다양한 명령 실행 방식으로 이어지는 방식을 보여줍니다. AppRun 통해 추출된 AppImage와 함께 자주 사용되는 launcher 방식은 안정성을 위해 권장되는 방식입니다.

더 자세한 흐름도는 FLOWCHART.md를 참조하세요.

🔄 핵심 구성 요소

1. FreeCAD MCP 서버( freecad_mcp_server.py )

• 설명 : 모델 컨텍스트 프로토콜(Model Context Protocol)을 구현하는 메인 서버입니다. AI 어시스턴트 또는 기타 클라이언트가 MCP를 통해 FreeCAD와 통신할 수 있는 중앙 허브 역할을 합니다.
• 특징 :
  • 표준 MCP 요청( mcp/listTools , mcp/executeTool )을 처리합니다.
  • 구성된 방법을 사용하여 FreeCADConnection 활용하여 FreeCAD와 상호 작용합니다.
  • 구성에 따라 다양한 툴셋(기본, 조작, 내보내기 등)을 노출합니다.
  • config.json 통해 구성 가능합니다.
• 용법 :
  # Start the server (uses config.json by default) python src/mcp_freecad/server/freecad_mcp_server.py # Start with a specific config python src/mcp_freecad/server/freecad_mcp_server.py --config my_config.json

2. FreeCAD 연결( freecad_connection_manager.py )

• 설명 : FreeCAD 연결 로직을 캡슐화한 통합 Python 인터페이스입니다. MCP 서버에서 내부적으로 사용되며 직접 스크립팅에 사용할 수 있습니다.
• 특징 :
  • 구성과 가용성에 따라 가장 적합한 연결 방법을 지능적으로 선택합니다.
• 방법 :
  • 런처 : (권장) freecad_connection_launcher.py 및 AppRun 사용합니다.
  • 래퍼 : freecad_connection_wrapper.py 와 freecad_subprocess.py 사용합니다.
  • 서버 : 소켓을 통해 실행 중인 freecad_socket_server.py 에 연결합니다.
  • Bridge : freecad_connection_bridge.py 를 통해 FreeCAD CLI를 사용합니다.
  • Mock : 테스트를 위해 FreeCAD를 시뮬레이션합니다.
  • 자동 : 권장 순서대로 메서드를 시도합니다(런처 > 래퍼 > 서버 > 브리지 > 모의).
• 사용법(직접 스크립팅 예) :
  from freecad_connection_manager import FreeCADConnection # Auto-connect using settings potentially from config.json # (Ensure config.json is present or provide args) fc = FreeCADConnection(auto_connect=True) if fc.is_connected(): print(f"Connected via: {fc.get_connection_type()}") version_info = fc.get_version() print(f"FreeCAD Version: {version_info}") fc.create_document("TestDocFromScript") else: print("Failed to connect to FreeCAD.")

3. FreeCAD 런처( freecad_connection_launcher.py )

• 설명 : 일반적으로 추출된 AppImage에서 AppRun 사용하여 FreeCAD 환경을 실행합니다. 실행된 환경 내에서 freecad_launcher_script.py 실행합니다.
• 특징 :
  • FreeCAD/AppRun의 하위 프로세스 실행을 관리합니다.
  • 명령과 매개변수를 내부 FreeCAD 스크립트에 전달합니다.
  • 스크립트의 출력에서 JSON 결과를 구문 분석합니다.
• 사용법 : 주로 launcher 메서드가 선택되었을 때( config.json 에서 설정됨) FreeCADConnection 에서 내부적으로 사용됩니다. 일반적으로 사용자가 직접 실행하지 않습니다.

4. FreeCAD Wrapper( freecad_connection_wrapper.py ) 및 하위 프로세스( freecad_subprocess.py )

• 설명 : freecad_connection_wrapper.py 는 별도의 Python 프로세스에서 freecad_subprocess.py 시작합니다. freecad_subprocess.py FreeCAD 모듈을 가져오고 stdio 파이프를 통해 래퍼와 통신합니다.
• 특징 :
  • FreeCAD 모듈 가져오기를 전용 프로세스로 분리합니다.
  • 직접 모듈 가져오기가 가능하지만 AppRun/launcher에 문제가 있는 경우 대체 연결 방법을 제공합니다.
• 사용법 : wrapper 메서드가 선택되었을 때( config.json 에서 구성됨) FreeCADConnection 에서 내부적으로 사용됩니다. 하위 프로세스가 import FreeCAD 수 있는 Python 환경이 필요합니다.

5. FreeCAD 서버( freecad_socket_server.py )

• 설명 : FreeCAD 인스턴스 내부에서 실행되도록 설계된 독립형 소켓 서버입니다. FreeCADConnection 에서 연결을 수신합니다.
• 특징 :
  • 영구적인 FreeCAD 인스턴스에 연결할 수 있습니다.
  • --connect 모드로 실행하면 GUI와 상호작용할 수 있습니다.
• 사용법(FreeCAD 내 수동 시작) :
  # Inside FreeCAD Python Console: exec(open("/path/to/mcp-freecad/freecad_socket_server.py").read())
  MCP 서버 연결을 위해서는 config.json 에 connection_method: server 필요합니다. ( docs/FREECAD_SERVER_SETUP.md 참조)

6. FreeCAD Bridge( freecad_connection_bridge.py )

• 설명 : FreeCAD 실행 파일과의 명령줄 상호 작용을 활성화합니다. 직접 모듈 가져오기 문제를 우회하지만 속도가 느려질 수 있습니다.
• 특징 :
  • freecad 실행 파일에 대한 하위 프로세스 호출을 통해 FreeCAD 명령을 실행합니다.
• 사용법 : bridge 방식이 선택되었을 때( config.json 에서 설정) FreeCADConnection 에서 내부적으로 사용됩니다. freecad 시스템 PATH에 있거나 config.json 파일에서 path 가 올바르게 설정되어 있어야 합니다.

7. FreeCAD 클라이언트( freecad_client.py )

• 설명 : FreeCADConnection 인터페이스와 직접 상호 작용하기 위한 명령줄 유틸리티(MCP 서버가 아닌 연결 방법을 테스트/디버깅하기 위한 것)입니다.
• 특징 :
  • 터미널에서 특정 FreeCADConnection 명령(예: 기본 생성, 버전 가져오기)을 테스트할 수 있습니다.
  • config.json 사용하여 연결 설정을 결정합니다.
• 사용 예 :
  # Test connection and get version python freecad_client.py version # Create a box using the configured connection method python freecad_client.py create-box --length 20 --width 10

🔄 프로젝트 구조

MCP-FreeCAD 프로젝트는 다음과 같은 디렉토리 구조로 구성되어 있습니다.

스크립트에 대한 자세한 내용은 scripts/README.md를 참조하세요.

⚙️ 설치 및 설정 세부 정보

이 섹션에서는 다양한 설치 및 설정 옵션에 대한 자세한 내용을 제공합니다.

권장 설정: AppImage + Launcher(자세한 단계)

여기에는 두 가지 주요 스크립트가 포함됩니다.

1. scripts/bin/setup_freecad_env.sh : 환경을 준비합니다.
   • ~/.mcp-freecad 에 저장소를 복제하거나 업데이트합니다.
   • Python 가상 환경( .venv )을 생성/업데이트하고 요구 사항을 설치합니다.
   • download_appimage.py 실행하여 최신 안정된 FreeCAD Linux AppImage를 ~/.mcp-freecad 로 가져옵니다.
   • extract_appimage.py 실행합니다.
     • 다운로드한 AppImage를 ~/.mcp-freecad/squashfs-root 로 추출합니다.
     • ~/.mcp-freecad/config.json 업데이트하여 connection_method: launcher 및 use_apprun: true 올바른 절대 경로와 함께 사용합니다.
   • 실행 방법 : curl -sSL <URL>/setup_freecad_env.sh | bash 또는 ./scripts/bin/setup_freecad_env.sh
2. scripts/bin/mcp-freecad-installer.sh : 서버를 실행합니다.
   • 참고 : 이름과 달리 이 스크립트는 더 이상 전체 설치를 수행하지 않습니다 . 이 스크립트는 주로 저장소를 최신 상태로 유지하고, 가상 환경을 활성화하고, freecad_mcp_server.py 시작합니다.
   • 이는 환경(AppImage 다운로드/추출)이 setup_freecad_env.sh 또는 수동으로 준비되었다고 가정합니다.
   • 실행 방법 : ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh 또는 mcp-freecad (전역 명령).

기타 설치 방법

글로벌 설치( install-global.sh )

• /usr/local/bin 에 mcp-freecad 심볼릭 링크를 생성하여 repo에 있는 mcp-freecad-installer.sh 를 가리킵니다.
• 어디서나 mcp-freecad 실행할 수 있습니다.
• 권장되는 런처 방법을 사용하려면 먼저 setup_freecad_env.sh 사용하여 환경을 설정해야 합니다 .

수동 설치

• 저장소를 복제합니다.
• venv를 생성하고 요구 사항을 설치합니다.
• AppImage를 수동으로 다운로드하고 추출합니다 . python download_appimage.py 와 python extract_appimage.py /path/to/downloaded.AppImage 직접 실행합니다.
• 서버를 실행합니다: python freecad_mcp_server.py .

🚀 MCP 서버 사용

이는 Claude와 같은 AI 보조 도구를 사용하여 FreeCAD와 상호 작용하는 기본 방법입니다.

MCP 서버 시작

서버가 실행되어 MCP 클라이언트의 연결을 수신합니다.

MCP 클라이언트 연결

MCP 호환 클라이언트를 사용하세요. 참조 mcp client 사용 예:

또는 MCP 문서에 있는 것과 같은 클라이언트 스크립트가 있는 경우 uv 사용합니다.

대안: 통합 서버로 FreeCAD 시작

다음을 사용하여 통합 서버로 FreeCAD를 시작할 수도 있습니다.

그러면 FreeCAD가 실행되고 자동으로 그 안의 서버가 시작됩니다.

MCP 서버 구성( config.json )

config.json 파일은 서버의 다양한 기능을 제어합니다. extract_appimage.py 실행한 후 권장되는 런처 설정을 보여주는 예시는 다음과 같습니다.

참고: 예시 경로를 실제 절대 경로로 바꾸세요.

통합 옵션에 대한 자세한 내용은 FREECAD_INTEGRATION.md를 참조하세요.

🛠️ 사용 가능한 MCP 도구

MCP 서버는 다양한 도구 그룹을 제공합니다. 사용 가능한 모든 도구는 다음과 같습니다.

📐 기본 FreeCAD 도구 ( freecad.* )

• freecad.create_document : 새 문서를 만듭니다
• freecad.export_stl : 모델이나 특정 객체를 STL로 내보냅니다.
• freecad.import_stl : STL 파일을 현재 문서로 가져옵니다.
• freecad.save_document : 현재 문서를 저장합니다
• freecad.load_document : 기존 문서 로드

🔧 모델 조작 도구( model_manipulation.* )

• model_manipulation.rotate : 지정된 축을 중심으로 객체를 회전합니다.
• model_manipulation.translate : 3D 공간에서 객체 이동
• model_manipulation.scale : 객체를 균일하게 또는 비균일하게 크기 조정합니다.
• model_manipulation.mirror : 지정된 평면에 걸쳐 객체를 미러링합니다.
• model_manipulation.union : 부울 합집합을 사용하여 여러 객체를 결합합니다.
• model_manipulation.cut : 부울 차이를 사용하여 객체를 잘라냅니다.
• model_manipulation.intersect : 여러 객체의 교집합을 만듭니다.

📏 측정 도구 ( measurement.* )

• measurement.distance : 두 지점 사이의 거리를 측정합니다.
• measurement.angle : 세 점 사이의 각도를 측정합니다.
• measurement.area : 물체의 표면적을 계산합니다.
• measurement.volume : 고체 물체의 부피를 계산합니다.
• measurement.mass : 물체의 질량을 계산합니다(재료 속성 필요)

📦 기본 도구( primitives.* )

• primitives.create_box : 직사각형 상자를 만듭니다.
• primitives.create_cylinder : 실린더를 생성합니다.
• primitives.create_sphere : 구를 생성합니다.
• primitives.create_cone : 원뿔을 생성합니다.
• primitives.create_torus : 토러스를 생성합니다
• primitives.create_polygon : 정다각형을 생성합니다.
• primitives.create_ellipse : 타원을 생성합니다.

🔄 내보내기/가져오기 도구( export_import.* )

• export_import.export_step : STEP 형식으로 내보내기
• export_import.import_step : STEP 형식에서 가져오기
• export_import.export_iges : IGES 형식으로 내보내기
• export_import.import_iges : IGES 형식에서 가져오기
• export_import.export_dxf : DXF 형식으로 내보내기
• export_import.import_dxf : DXF 형식에서 가져오기

💻 코드 생성 도구( code_generator.* )

• code_generator.generate_python : 현재 모델에 대한 Python 코드 생성
• code_generator.generate_openscad : 현재 모델에 대한 OpenSCAD 코드 생성
• code_generator.generate_gcode : CNC 가공을 위한 G 코드 생성
• code_generator.generate_3d_print : 최적화된 3D 프린팅 설정 생성

📝 MCP 상호 작용 예시

다음은 AI 어시스턴트와 함께 MCP 서버를 사용하는 개념적 예입니다.

상자 만들기 및 내보내기

🔍 문제 해결

• MCP 서버 연결 문제 :
  • python src/mcp_freecad/server/freecad_mcp_server.py 즉시 오류 없이 실행될 수 있는지 확인하세요. 터미널 출력을 확인하세요.
  • 해당되는 경우 방화벽 설정을 확인하세요( stdio 의 경우 가능성이 낮음).
  • config.json 이 유효한 JSON인지 확인하세요.
• FreeCAD 연결 문제(특히 launcher 방법 사용 시) :
  • extract_appimage.py 실행합니다 . AppImage가 올바르게 추출되었고 config.json 업데이트되었는지 확인합니다.
  • config.json 경로 확인 : freecad 섹션의 모든 절대 경로가 시스템에 맞는지 확인하세요.
  • 권한 확인 : squashfs-root/AppRun 에 실행 권한이 있는지 확인하세요( chmod +x ).
  • 로그 확인 : 로깅이 시작되면 프로젝트 루트에 생성되는 mcp_freecad.log , freecad_server_stdout.log , freecad_server_stderr.log 를 조사하여 freecad_connection_launcher.py , AppRun 또는 FreeCAD 프로세스 자체의 오류가 있는지 확인합니다.
  • 환경 변수 : AppRun 라이브러리를 찾지 못하는 경우, LD_LIBRARY_PATH 와 PYTHONPATH 올바르게 설정되어 있는지 확인하세요. Cursor를 사용하는 경우 .cursor/mcp.json 에, 터미널에서 테스트하는 경우 수동으로 내보내야 할 수 있습니다. extract_appimage.py 스크립트는 이 부분을 덜 필요하게 만들지만, 문제가 될 수 있습니다.
  • 헤드리스 문제 : FreeCAD가 완전히 헤드리스로 실행되는 경우( QT_QPA_PLATFORM=offscreen ) 문제가 발생할 수 있습니다. GUI 관련 오류는 로그를 확인하세요.
• server 방법 : freecad_socket_server.py``config.json 에 구성된 올바른 호스트/포트에서 수신 대기하는 활성 FreeCAD 인스턴스 내부에서 실행 중인지 확인합니다.
• bridge 방법 : FreeCAD가 시스템 전체에 설치되어 있고 터미널에서 freecad 명령이 제대로 작동하는지 확인하세요. config.json 에서 freecad_path 확인하세요.
• MCP SDK가 없습니다 . pip install modelcontextprotocol 통해 설치하세요.
• Python 경로 문제 : 권장되는 AppImage 설정을 사용 하지 않을 때 FreeCAD 모듈을 찾을 수 없는 경우 PYTHON_INTERPRETER_SETUP.md 를 참조하세요.

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

🖥️ 커서 통합

MCP 서버는 Cursor IDE와 같은 도구와의 통합을 위해 설계되었습니다.

1. 커서 구성 : 커서 설정(설정 > 기능 > MCP 서버 > 새 MCP 서버 추가)에 MCP 서버를 추가합니다. 필요한 환경 변수와 작업 디렉터리를 설정하여 Python 스크립트를 직접 실행하도록 구성합니다. .cursor/mcp.json 의 구성 예시는 다음과 같습니다.
   { "mcpServers": { "mcp-freecad": { "command": "python3", // Command to run python "args": [ "src/mcp_freecad/server/freecad_mcp_server.py" // Script to run ], "env": { // Environment variables needed for headless AppRun "QT_QPA_PLATFORM": "offscreen", "DISPLAY": "", "FREECAD_CONSOLE": "1", "PYTHONNOUSERSITE": "1", // These might be needed if AppRun doesn't set them automatically "LD_LIBRARY_PATH": "/path/to/mcp-freecad/squashfs-root/usr/lib:/path/to/mcp-freecad/squashfs-root/usr/Ext:...", "PYTHONPATH": "/path/to/mcp-freecad/squashfs-root/usr/lib/python3.11/site-packages:..." }, "cwd": "/path/to/mcp-freecad" // Set working directory to project root } // ... other servers like memory ... } }
   /path/to/mcp-freecad 프로젝트의 실제 절대 경로로 바꾸세요. 필요한 경우 LD_LIBRARY_PATH 와 PYTHONPATH AppImage 구조와 일치하는지 확인하세요.
2. 커서 재시작 : 구성 변경 사항을 적용하려면 커서를 완전히 재시작하세요.
3. 서버 통신 : 서버는 기본적으로 stdio 전송을 사용합니다( config.json 파일의 server.mcp.transport 에서 설정). 이는 Cursor의 통신 프로토콜과 호환됩니다. 오류는 MCP 오류 응답을 통해 Cursor에 보고되어야 합니다.

커서별 고려 사항

• freecad_mcp_server.py 스크립트는 기본적으로 config.json 로드합니다. 이 파일에 올바른 설정, 특히 extract_appimage.py 에 의해 업데이트된 freecad 섹션이 포함되어 있는지 확인하세요.
• .cursor/mcp.json 에 설정된 환경 변수는 Cursor가 제공하는 환경 내에서 launcher 메서드가 올바르게 작동하는 데 필수적입니다.

📋 사용 가능한 옵션 및 사용 사례

🔧 연결 방법

1. 런처 연결(권장)
   • 추출된 AppImage에서 AppRun 사용합니다. 가장 안정적입니다.
   • extract_appimage.py 에 의해 자동으로 구성됩니다.
   • 구성( config.json ): GXP19
2. 래퍼 연결
   • 별도의 Python 하위 프로세스에서 FreeCAD 로직을 실행합니다. AppImage/AppRun이 문제를 일으키는 경우 좋은 대안입니다.
   • 구성( config.json ): GXP20
3. 소켓 서버 연결
   • FreeCAD 내에서 freecad_socket_server.py 실행해야 합니다.
   • FreeCAD를 지속적인 백그라운드 서버로 실행할 때 사용합니다.
   • 구성( config.json ): GXP21
4. CLI 브리지 연결
   • freecad 명령줄 도구를 사용합니다. 속도가 느리거나 안정성이 떨어질 수 있습니다.
   • 구성( config.json ): GXP22
5. 모의 연결
   • FreeCAD 없이 테스트하는 경우.
   • 구성( config.json ): GXP23
6. 자동 연결
   • 자동으로 가장 적합한 방법을 선택합니다(런처 > 래퍼 > 서버 > 브리지 > 모의).
   • connection_method 없거나 "auto" 로 설정된 경우 기본값입니다.

🛠️ 도구 범주 및 사용 사례

1. 기본 FreeCAD 작업
   • 필수 문서 관리
   • 사용 사례:
     • 새 문서 만들기
     • 프로젝트 저장 및 로드
     • 다양한 형식으로 내보내기
     • 문서 구조 관리
2. 모델 조작
   • 객체 변환 및 수정
   • 사용 사례:
     • 객체를 정확하게 회전
     • 3D 공간에서 움직이는 객체
     • 모델 확장
     • 미러와 복사본 만들기
     • 부울 연산(합집합, 절단, 교집합)
3. 측정 도구
   • 분석 및 검증
   • 사용 사례:
     • 거리 측정
     • 각도 계산
     • 표면적 분석
     • 볼륨 계산
     • 질량 속성
4. 원시 창조
   • 기본 모양 생성
   • 사용 사례:
     • 상자와 원통 만들기
     • 구 생성
     • 콘과 토리 만들기
     • 정다각형 만들기
     • 타원 그리기
5. 수출/수입 작업
   • 파일 형식 변환
   • 사용 사례:
     • STEP 파일 내보내기/가져오기
     • IGES 형식 처리
     • DXF 파일 처리
     • 3D 프린팅을 위한 STL 내보내기
6. 코드 생성
   • 자동화된 코드 생성
   • 사용 사례:
     • 파이썬 스크립트 생성
     • OpenSCAD 코드 내보내기
     • CNC용 G 코드 생성
     • 3D 프린터 설정 최적화

💻 통합 시나리오

1. 커서 IDE 통합
   • 개발 환경 통합
   • 사용 사례:
     • IDE에서 직접 모델 조작
     • 실시간 피드백
     • 디버그 로깅
     • 오류 추적
2. AI 어시스턴트 통합
   • AI 기반 설계 자동화
   • 사용 사례:
     • 자연어 모델 생성
     • 자동화된 설계 수정
     • 매개변수 최적화
     • 설계 검증
3. 명령줄 사용법
   • 스크립팅 및 자동화
   • 사용 사례:
     • 일괄 처리
     • 자동화된 테스트
     • CI/CD 통합
     • 명령줄 도구

🎯 일반적인 사용 사례 예시

1. 신속한 프로토타입 제작

2. 자동 처리

⚙️ 구성 옵션

1. 서버 구성

2. 도구 활성화

3. 디버그 구성

특징

• MCP 프로토콜을 통해 AI 어시스턴트를 FreeCAD에 연결합니다.
• 프로그래밍 방식으로 3D 모델을 생성하고 조작합니다.
• 기본 모양(상자, 원통, 구, 원뿔) 지원
• 부울 연산(합집합, 교집합, 절단)
• 객체 변환(이동, 회전)
• 모델을 STL 형식으로 내보내기
• 문서 및 객체 관리

필수 조건

• Python 3.8 이상
• MCP SDK( pip install modelcontextprotocol )
• 권장 사항 : 안정적인 launcher 연결 방법을 위해 FreeCAD AppImage( extract_appimage.py 를 사용하여 다운로드 및 추출)를 사용합니다.
• 또는 : FreeCAD 0.20+의 시스템 설치( bridge 또는 server 방법의 경우 안정성이 떨어질 수 있음).

사용 가능한 도구

문서 관리

1. freecad.create_document - 새 FreeCAD 문서 만들기
2. freecad.list_documents - 열려 있는 모든 문서 나열
3. freecad.list_objects - 문서의 모든 객체 나열

3D 기본 요소

1. freecad.create_box - 상자 기본형 만들기
2. freecad.create_cylinder - 원통 기본형을 만듭니다.
3. freecad.create_sphere - 구 기본형을 생성합니다
4. freecad.create_cone - 원뿔 기본형 만들기

부울 연산

1. freecad.boolean_union - 두 객체의 합집합을 만듭니다(추가)
2. freecad.boolean_cut - 첫 번째 객체에서 두 번째 객체를 잘라냅니다(빼기)
3. freecad.boolean_intersection - 두 객체의 교차점(공통 볼륨)을 만듭니다.

변형

1. freecad.move_object - 객체를 새 위치로 이동합니다.
2. freecad.rotate_object - 객체 회전

내보내다

1. freecad.export_stl - 모델을 STL 파일로 내보내기

테스트

이 프로젝트에는 품질과 안정성을 보장하기 위해 단위 테스트와 종단간(E2E) 테스트가 모두 포함됩니다.

단위 테스트

기본 단위 테스트를 실행하려면:

종단간 테스트

엔드투엔드 테스트는 클라이언트 관점에서 전체 시스템이 정상적으로 작동하는지 검증합니다. 실제 시나리오와 다양한 구성 요소 간의 상호 작용을 테스트합니다.

모든 E2E 테스트를 실행하려면:

E2E 테스트는 기능별로 구성됩니다.

• test_primitives.py - 기본 모양 생성 및 조작을 위한 테스트
• test_smithery.py - 대장간 도구 작동 테스트

새로운 E2E 테스트 작성

새로운 E2E 테스트를 추가하려면:

1. tests/e2e/ 디렉토리에 새 테스트 파일을 만듭니다.
2. 적절한 기본 테스트 클래스( MCPClientTestBase )를 확장합니다.
3. MCP 클라이언트를 사용하여 도구와 상호 작용하는 테스트 방법을 추가합니다.
4. 테스트 러너로 테스트를 실행하세요

예를 보려면 기존 테스트 파일을 참조하세요.

선적 서류 비치

이 프로젝트에는 다양한 측면에 대한 여러 문서 파일이 포함되어 있습니다.

• PYTHON_INTERPRETER_SETUP.md - Python 인터프리터를 구성하는 방법
• FREECAD_SERVER_SETUP.md - 서버 설정 가이드
• FREECAD_INTEGRATION.md - FreeCAD 통합 방법
• FLOWCHART.md - 자세한 흐름도
• OPTIMIZATION_FEATURES.md - 성능 최적화 가이드
• scripts/README.md - 스크립트 설명서

AI 어시스턴트의 경우 자세한 사용 지침과 예시는 AI_ASSISTANT_GUIDE.md 를 참조하세요.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

감사의 말

• 놀라운 CAD 소프트웨어를 위한 FreeCAD 개발팀
• 모델 컨텍스트 프로토콜(MCP) SDK를 위한 Anthropic 및 Claude