🛠️ MCP-FreeCAD 통합
참고: 이 저장소는 현재 활발하게 개발 중입니다. 매일 커밋이 있을 수 있으며, 잠재적인 변경 사항이 있을 수 있습니다.
이 프로젝트는 모델 컨텍스트 프로토콜(MCP)을 사용하여 AI 어시스턴트와 FreeCAD CAD 소프트웨어 간의 강력한 통합을 제공합니다. 외부 애플리케이션이 표준화된 인터페이스를 통해 FreeCAD와 상호 작용할 수 있도록 지원하며, 다양한 연결 방식과 특수 도구를 제공합니다.
빠른 시작(권장: AppImage + Launcher)
가장 안정적인 설정을 위해 다음 단계를 따르세요.
- 환경 설정(일회성) : 설정 스크립트를 실행합니다. 이 스크립트는 저장소를
~/.mcp-freecad 에 복제하고, Python 가상 환경을 생성하고, 최신 FreeCAD AppImage를 다운로드하고 압축을 푼 후, 서버에서 해당 파일을 사용하도록 설정합니다.지엑스피1또는 리포를 복제하고 ./scripts/bin/setup_freecad_env.sh 수동으로 실행합니다. - 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로 실행
- 컨테이너를 시작합니다 .
- 처음부터 빌드하기 (변경 사항이 있는 경우):
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 연결( src/mcp_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())
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 프로젝트는 다음과 같은 디렉토리 구조로 구성됩니다.
mcp-freecad/
├── assets/ # 3D model assets (STL, STEP files)
├── backups/ # Backup files
├── config.json # Main configuration file
├── config.template.json # Template for configuration
├── docs/ # Documentation files
│ ├── FLOWCHART.md # Detailed flow diagrams
│ ├── FREECAD_INTEGRATION.md # FreeCAD integration guide
│ ├── FREECAD_SERVER_SETUP.md # Server setup instructions
│ ├── OPTIMIZATION_FEATURES.md # Performance optimization guide
│ └── PYTHON_INTERPRETER_SETUP.md # Python interpreter configuration
├── examples/ # Example scripts showing API usage
├── freecad_connection_bridge.py # Bridge for CLI interaction with FreeCAD
├── freecad_client.py # Command-line client
├── freecad_connection_manager.py # Unified connection interface
├── freecad_mcp.py # Entry point script
├── freecad_mcp_server.py # MCP server implementation
├── freecad_socket_server.py # Socket-based server for FreeCAD
├── scripts/ # Shell scripts for installation and execution
│ ├── README.md # Scripts documentation
│ └── bin/ # Executable scripts
│ ├── install-global.sh # Global installation script
│ ├── mcp-freecad-installer.sh # Installer/Runner script
│ ├── mcp-freecad # Link target for global install
│ └── setup_freecad_env.sh # Environment setup script (AppImage download/extract)
├── src/ # Source code (contains mcp_freecad package)
│ └── mcp_freecad/
│ ├── __init__.py
│ ├── server/
│ │ ├── __init__.py
│ │ └── freecad_mcp_server.py # The main MCP server implementation
│ ├── freecad_connection_manager.py # Unified connection interface
│ └── ... # Other source files
├── tests/ # Test files
│ └── e2e/ # End-to-end tests
├── .gitignore # Git ignore patterns
├── pyproject.toml # Project metadata and dependencies (PEP 621)
├── LICENSE # Project License
├── README.md # This file
├── Dockerfile # Docker build definition
├── docker-compose.yml # Docker Compose configuration
└── ... # Other config files (.dockerignore, .editorconfig, etc.)
스크립트에 대한 자세한 내용은 scripts/README.md를 참조하세요.
⚙️ 설치 및 설정 세부 정보
이 섹션에서는 다양한 설치 및 설정 옵션에 대한 자세한 내용을 제공합니다.
권장 설정: AppImage + Launcher(자세한 단계)
여기에는 두 가지 주요 스크립트가 포함됩니다.
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
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 사용하여 환경을 설정해야 합니다 .
# Navigate to the repository (e.g., ~/.mcp-freecad)
cd ~/.mcp-freecad
# Run the setup script first
./scripts/bin/setup_freecad_env.sh
# Then run the global installation script
sudo ./scripts/bin/install-global.sh # Needs sudo for /usr/local/bin
# Now you can run the server from anywhere
mcp-freecad
수동 설치
- 저장소를 복제합니다.
- venv를 생성하고 요구 사항을 설치합니다.
- AppImage를 수동으로 다운로드하고 추출합니다 .
python download_appimage.py 와 python extract_appimage.py /path/to/downloaded.AppImage 직접 실행합니다. - 서버를 실행합니다:
python freecad_mcp_server.py .
🚀 MCP 서버 사용
이는 Claude와 같은 AI 보조 도구를 사용하여 FreeCAD와 상호 작용하는 기본 방법입니다.
MCP 서버 시작
# Start the server using the default config.json
python src/mcp_freecad/server/freecad_mcp_server.py
# Start with a specific configuration file
python src/mcp_freecad/server/freecad_mcp_server.py --config /path/to/your/config.json
# Enable debug logging
python src/mcp_freecad/server/freecad_mcp_server.py --debug
서버가 실행되어 MCP 클라이언트의 연결을 수신합니다.
MCP 클라이언트 연결
MCP 호환 클라이언트를 사용하세요. 참조 mcp client 사용 예:
# Replace 'mcp client' with the actual client command if different
mcp client connect stdio --command "python src/mcp_freecad/server/freecad_mcp_server.py"
또는 MCP 문서에 있는 것과 같은 클라이언트 스크립트가 있는 경우 uv 사용합니다.
uv run path/to/your/mcp_client.py python src/mcp_freecad/server/freecad_mcp_server.py
대안: 통합 서버로 FreeCAD 시작
다음을 사용하여 통합 서버로 FreeCAD를 시작할 수도 있습니다.
./scripts/start_freecad_with_server.sh
그러면 FreeCAD가 실행되고 자동으로 그 안의 서버가 시작됩니다.
MCP 서버 구성( config.json )
config.json 파일은 서버의 다양한 기능을 제어합니다. extract_appimage.py 실행한 후 권장되는 런처 설정을 보여주는 예시는 다음과 같습니다.
{
"auth": { // Optional authentication settings
"api_key": "development",
"enabled": false
},
"server": { // MCP server settings
"host": "0.0.0.0",
"port": 8000,
"debug": true,
"workers": 1,
"name": "mcp-freecad",
"version": "0.7.11",
"mcp": {
"transport": "stdio", // Use stdio for Cursor/local clients
"protocol_version": "0.1.0"
// ... other MCP settings
}
},
"freecad": { // FreeCAD connection settings
// Paths are set automatically by extract_appimage.py for launcher mode
"path": "/home/user/mcp-freecad/squashfs-root/usr/bin/freecad", // Example path
"python_path": "/home/user/mcp-freecad/squashfs-root/usr/bin/python", // Example path
"module_path": "/home/user/mcp-freecad/squashfs-root/usr/lib/", // Example path
"host": "localhost", // Not used by launcher
"port": 12345, // Not used by launcher
"auto_connect": false, // Connection handled internally
"reconnect_on_failure": true,
"use_mock": false,
"connection_method": "launcher", // *** KEY: Use the launcher method ***
"script_path": "/home/user/mcp-freecad/freecad_launcher_script.py", // Script run inside FreeCAD
"launcher_path": "/home/user/mcp-freecad/freecad_connection_launcher.py", // Script that starts AppRun
"use_apprun": true, // *** KEY: Tells launcher to use AppRun ***
"apprun_path": "/home/user/mcp-freecad/squashfs-root/AppRun" // Path to AppRun executable
},
"logging": { // Logging configuration
"level": "INFO",
"file": "mcp_freecad.log",
"max_size": 10485760,
"backup_count": 3
},
"tools": { // Optional: control which tool groups are enabled
"enable_smithery": true,
"enable_primitives": true,
"enable_model_manipulation": true,
"enable_export_import": true,
"enable_measurement": true,
"enable_code_generator": true
// ... other tool settings
}
// ... other sections like cache, recovery, cors, performance ...
}
참고: 예시 경로를 실제 절대 경로로 바꾸세요.
통합 옵션에 대한 자세한 내용은 FREECAD_INTEGRATION.md를 참조하세요.
🛠️ 사용 가능한 MCP 도구
MCP 서버는 현재 다음과 같은 핵심 도구를 제공합니다. 추가 도구 세트가 계획되어 있습니다.
freecad.create_document : 새 문서를 만듭니다.freecad.list_documents : 열려 있는 모든 문서를 나열합니다.freecad.list_objects : 특정 문서(또는 활성 문서)의 객체를 나열합니다.freecad.create_box : 기본 상자를 만듭니다.freecad.create_cylinder : 원통 기본형을 만듭니다.freecad.create_sphere : 구 기본형을 생성합니다.freecad.create_cone : 원뿔 기본형을 만듭니다.freecad.boolean_union : 두 객체 간의 부울 합집합(융합)을 수행합니다.freecad.boolean_cut : 두 객체 간의 부울 절단(차이)을 수행합니다.freecad.boolean_intersection : 두 객체 사이의 부울 교집합(공통)을 수행합니다.freecad.move_object : 객체를 새로운 절대 위치로 이동합니다.freecad.rotate_object : 지정된 각도로 객체를 회전합니다.freecad.export_stl : 지정된 객체(또는 전체 객체)를 STL 파일로 내보냅니다.
(참고: MCP 요청에 사용되는 도구 이름은 클라이언트와 서버 구현 세부 정보에 따라 약간 다를 수 있습니다(예: 마침표 대신 밑줄 사용). 정확한 이름은 서버의 mcp/listTools 출력을 참조하세요.)
📝 MCP 상호 작용 예시
다음은 AI 어시스턴트와 함께 MCP 서버를 사용하는 개념적 예입니다.
상자 만들기 및 내보내기
User: Create a box 50mm long, 30mm wide, and 20mm high.
Assistant: Okay, I can create that box.
[Tool Call: primitives.create_box (arguments: {"length": 50.0, "width": 30.0, "height": 20.0})]
[Tool Result: {"object_name": "Box", "message": "Created box...", "success": true}]
User: Now export it as box.stl
Assistant: Sure, exporting the model to box.stl.
[Tool Call: export_import.export_stl (arguments: {"file_path": "box.stl", "object_names": ["Box"]})]
[Tool Result: {"file_path": "box.stl", "message": "Exported successfully...", "success": true}]
Assistant: I've exported the box model to `box.stl`.
🔍 문제 해결
- 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와 같은 도구와의 통합을 위해 설계되었습니다.
- 커서 구성 : 커서 설정(설정 > 기능 > 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" // Corrected script path
],
"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 구조와 일치하는지 확인하세요. - 커서 재시작 : 구성 변경 사항을 적용하려면 커서를 완전히 재시작하세요.
- 서버 통신 : 서버는 기본적으로
stdio 전송을 사용합니다( config.json 파일의 server.mcp.transport 에서 설정). 이는 Cursor의 통신 프로토콜과 호환됩니다. 오류는 MCP 오류 응답을 통해 Cursor에 보고되어야 합니다.
커서별 고려 사항
freecad_mcp_server.py 스크립트는 기본적으로 config.json 로드합니다. 이 파일에 올바른 설정, 특히 extract_appimage.py 에 의해 업데이트된 freecad 섹션이 포함되어 있는지 확인하세요..cursor/mcp.json 에 설정된 환경 변수는 Cursor가 제공하는 환경 내에서 launcher 메서드가 올바르게 작동하는 데 필수적입니다.
📋 사용 가능한 옵션 및 사용 사례
🔧 연결 방법
- 런처 연결(권장)
- 추출된 AppImage에서
AppRun 사용합니다. 가장 안정적입니다. extract_appimage.py 에 의해 자동으로 구성됩니다.- 구성(
config.json ): GXP19
- 래퍼 연결
- 별도의 Python 하위 프로세스에서 FreeCAD 로직을 실행합니다. AppImage/AppRun이 문제를 일으키는 경우 좋은 대안입니다.
- 구성(
config.json ): GXP20
- 소켓 서버 연결
- FreeCAD 내에서
freecad_socket_server.py 실행해야 합니다. - FreeCAD를 지속적인 백그라운드 서버로 실행할 때 사용합니다.
- 구성(
config.json ): GXP21
- CLI 브리지 연결
freecad 명령줄 도구를 사용합니다. 속도가 느리거나 안정성이 떨어질 수 있습니다.- 구성(
config.json ): GXP22
- 모의 연결
- FreeCAD 없이 테스트하는 경우.
- 구성(
config.json ): GXP23
- 자동 연결
- 자동으로 가장 적합한 방법을 선택합니다(런처 > 래퍼 > 서버 > 브리지 > 모의).
connection_method 없거나 "auto" 로 설정된 경우 기본값입니다.
🛠️ 도구 범주 및 사용 사례
- 기본 FreeCAD 작업
- 필수 문서 관리
- 사용 사례:
- 새 문서 만들기
- 프로젝트 저장 및 로드
- 다양한 형식으로 내보내기
- 문서 구조 관리
- 모델 조작
- 객체 변환 및 수정
- 사용 사례:
- 객체를 정확하게 회전
- 3D 공간에서 움직이는 객체
- 모델 확장
- 미러와 복사본 만들기
- 부울 연산(합집합, 절단, 교집합)
- 측정 도구
- 분석 및 검증
- 사용 사례:
- 거리 측정
- 각도 계산
- 표면적 분석
- 볼륨 계산
- 질량 속성
- 원시 창조
- 기본 모양 생성
- 사용 사례:
- 상자와 원통 만들기
- 구 생성
- 콘과 토리 만들기
- 정다각형 만들기
- 타원 그리기
- 수출/수입 작업
- 파일 형식 변환
- 사용 사례:
- STEP 파일 내보내기/가져오기
- IGES 형식 처리
- DXF 파일 처리
- 3D 프린팅을 위한 STL 내보내기
- 코드 생성
- 자동화된 코드 생성
- 사용 사례:
- 파이썬 스크립트 생성
- OpenSCAD 코드 내보내기
- CNC용 G 코드 생성
- 3D 프린터 설정 최적화
💻 통합 시나리오
- 커서 IDE 통합
- 개발 환경 통합
- 사용 사례:
- IDE에서 직접 모델 조작
- 실시간 피드백
- 디버그 로깅
- 오류 추적
- AI 어시스턴트 통합
- AI 기반 설계 자동화
- 사용 사례:
- 자연어 모델 생성
- 자동화된 설계 수정
- 매개변수 최적화
- 설계 검증
- 명령줄 사용법
- 스크립팅 및 자동화
- 사용 사례:
- 일괄 처리
- 자동화된 테스트
- CI/CD 통합
- 명령줄 도구
🎯 일반적인 사용 사례 예시
- 신속한 프로토타입 제작
# Create a new document
freecad.create_document("Prototype")
# Add basic shapes
primitives.create_box(length=100, width=50, height=20)
# Export for 3D printing
export_import.export_stl("prototype.stl")
- 자동 처리
# Import and modify multiple files
for file in files:
import_step(file)
model_manipulation.scale(1.5)
export_stl(f"{file}_scaled.stl")
⚙️ 구성 옵션
- 서버 구성
{
"server": {
"name": "custom-server-name",
"version": "1.0.0",
"description": "Custom description"
}
}
- 도구 활성화
{
"tools": {
"enable_smithery": true,
"enable_primitives": true,
"enable_model_manipulation": true,
"enable_export_import": true,
"enable_measurement": true,
"enable_code_generator": true
}
}
- 디버그 구성
{
"cursor": {
"debug": true,
"log_level": "DEBUG",
"stdio_transport": true
}
}
특징
- MCP 프로토콜을 통해 AI 어시스턴트를 FreeCAD에 연결합니다.
- 프로그래밍 방식으로 3D 모델을 생성하고 조작합니다.
- 기본 모양(상자, 원통, 구, 원뿔) 지원
- 부울 연산(합집합, 교집합, 절단)
- 객체 변환(이동, 회전)
- 모델을 STL 형식으로 내보내기
- 문서 및 객체 관리
필수 조건
- Python 3.8 이상
- 권장 사항 : 안정적인
launcher 연결 방법을 위한 FreeCAD AppImage( scripts/bin/setup_freecad_env.sh 사용하여 다운로드 및 추출) - 또는 : FreeCAD 0.20+의 시스템 설치(
bridge 또는 server 방법의 경우 안정성이 떨어질 수 있음). - Git(저장소 복제용).
종속성은 pyproject.toml 통해 관리되며 설치 중에 가상 환경에 설치됩니다.
사용 가능한 도구
(이 섹션은 위의 목록을 중복합니다. 명확성을 위해 통합했습니다.)
현재 MCP를 통해 사용할 수 있는 도구는 다음과 같습니다.
문서 관리
freecad.create_documentfreecad.list_documentsfreecad.list_objects
3D 기본 요소
freecad.create_boxfreecad.create_cylinderfreecad.create_spherefreecad.create_cone
부울 연산
freecad.boolean_unionfreecad.boolean_cutfreecad.boolean_intersection
변형
freecad.move_objectfreecad.rotate_object
내보내다
측정, 기타 가져오기/내보내기 형식, 코드 생성을 다루는 추가 도구가 향후 릴리스에 포함될 예정입니다.
테스트
이 프로젝트에는 시스템 기능을 검증하기 위한 종단간(E2E) 테스트가 포함되어 있습니다.
종단간 테스트
이러한 테스트는 MCP 프로토콜을 사용하여 클라이언트 관점에서 상호작용을 검증합니다.
모든 E2E 테스트를 실행하려면:
# Run with mock FreeCAD (default, doesn't require actual FreeCAD installation)
./tests/e2e/run_tests.py
# Run with verbose output
./tests/e2e/run_tests.py --verbose
# Run with real FreeCAD connection (requires FreeCAD to be installed and configured)
./tests/e2e/run_tests.py --real
# Run a specific test file (e.g., test_primitives.py)
./tests/e2e/run_tests.py --single test_primitives.py
E2E 테스트는 tests/e2e/ 디렉토리에 있으며 기능별로 구성되어 있습니다.
새로운 E2E 테스트 작성
새로운 E2E 테스트를 추가하려면:
tests/e2e/ 디렉토리에 새 테스트 파일을 만듭니다.- 적절한 기본 테스트 클래스(
MCPClientTestBase )를 확장합니다. - MCP 클라이언트를 사용하여 도구와 상호 작용하는 테스트 방법을 추가합니다.
- 테스트 러너로 테스트를 실행하세요
예를 보려면 기존 테스트 파일을 참조하세요.
선적 서류 비치
이 프로젝트에는 다양한 측면에 대한 여러 문서 파일이 포함되어 있습니다.
AI 어시스턴트의 경우 자세한 사용 지침과 예시는 AI_ASSISTANT_GUIDE.md 를 참조하세요.
기여하다
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
감사의 말
- 놀라운 CAD 소프트웨어를 위한 FreeCAD 개발팀
- 모델 컨텍스트 프로토콜(MCP) SDK를 위한 Anthropic 및 Claude