jhacksman_OpenSCAD-MCP-Server

# OpenSCAD MCP Server A Model Context Protocol (MCP) server that enables users to generate 3D models from text descriptions or images, with a focus on creating parametric 3D models using multi-view reconstruction and OpenSCAD. ## Features - **AI Image Generation**: Generate images from text descriptions using Google Gemini or Venice.ai APIs - **Multi-View Image Generation**: Create multiple views of the same 3D object for reconstruction - **Image Approval Workflow**: Review and approve/deny generated images before reconstruction - **3D Reconstruction**: Convert approved multi-view images into 3D models using CUDA Multi-View Stereo - **Remote Processing**: Process computationally intensive tasks on remote servers within your LAN - **OpenSCAD Integration**: Generate parametric 3D models using OpenSCAD - **Parametric Export**: Export models in formats that preserve parametric properties (CSG, AMF, 3MF, SCAD) - **3D Printer Discovery**: Optional network printer discovery and direct printing ## Architecture The server is built using the Python MCP SDK and follows a modular architecture: ``` openscad-mcp-server/ ├── src/ │ ├── main.py # Main application │ ├── main_remote.py # Remote CUDA MVS server │ ├── ai/ # AI integrations │ │ ├── gemini_api.py # Google Gemini API for image generation │ │ └── venice_api.py # Venice.ai API for image generation (optional) │ ├── models/ # 3D model generation │ │ ├── cuda_mvs.py # CUDA Multi-View Stereo integration │ │ └── code_generator.py # OpenSCAD code generation │ ├── workflow/ # Workflow components │ │ ├── image_approval.py # Image approval mechanism │ │ └── multi_view_to_model_pipeline.py # Complete pipeline │ ├── remote/ # Remote processing │ │ ├── cuda_mvs_client.py # Client for remote CUDA MVS processing │ │ ├── cuda_mvs_server.py # Server for remote CUDA MVS processing │ │ ├── connection_manager.py # Remote connection management │ │ └── error_handling.py # Error handling for remote processing │ ├── openscad_wrapper/ # OpenSCAD CLI wrapper │ ├── visualization/ # Preview generation and web interface │ ├── utils/ # Utility functions │ └── printer_discovery/ # 3D printer discovery ├── scad/ # Generated OpenSCAD files ├── output/ # Output files (models, previews) │ ├── images/ # Generated images │ ├── multi_view/ # Multi-view images │ ├── approved_images/ # Approved images for reconstruction │ └── models/ # Generated 3D models ├── templates/ # Web interface templates └── static/ # Static files for web interface ``` ## Installation 1. Clone the repository: ``` git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git cd OpenSCAD-MCP-Server ``` 2. Create a virtual environment: ``` python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install dependencies: ``` pip install -r requirements.txt ``` 4. Install OpenSCAD: - Ubuntu/Debian: `sudo apt-get install openscad` - macOS: `brew install openscad` - Windows: Download from [openscad.org](https://openscad.org/downloads.html) 5. Install CUDA Multi-View Stereo: ``` git clone https://github.com/fixstars/cuda-multi-view-stereo.git cd cuda-multi-view-stereo mkdir build && cd build cmake .. make ``` 6. Set up API keys: - Create a `.env` file in the root directory - Add your API keys: ``` GEMINI_API_KEY=your-gemini-api-key VENICE_API_KEY=your-venice-api-key # Optional REMOTE_CUDA_MVS_API_KEY=your-remote-api-key # For remote processing ``` ## Remote Processing Setup The server supports remote processing of computationally intensive tasks, particularly CUDA Multi-View Stereo reconstruction. This allows you to offload processing to more powerful machines within your LAN. ### Server Setup (on the machine with CUDA GPU) 1. Install CUDA Multi-View Stereo on the server machine: ``` git clone https://github.com/fixstars/cuda-multi-view-stereo.git cd cuda-multi-view-stereo mkdir build && cd build cmake .. make ``` 2. Start the remote CUDA MVS server: ``` python src/main_remote.py ``` 3. The server will automatically advertise itself on the local network using Zeroconf. ### Client Configuration 1. Configure remote processing in your `.env` file: ``` REMOTE_CUDA_MVS_ENABLED=True REMOTE_CUDA_MVS_USE_LAN_DISCOVERY=True REMOTE_CUDA_MVS_API_KEY=your-shared-secret-key ``` 2. Alternatively, you can specify a server URL directly: ``` REMOTE_CUDA_MVS_ENABLED=True REMOTE_CUDA_MVS_USE_LAN_DISCOVERY=False REMOTE_CUDA_MVS_SERVER_URL=http://server-ip:8765 REMOTE_CUDA_MVS_API_KEY=your-shared-secret-key ``` ### Remote Processing Features - **Automatic Server Discovery**: Find CUDA MVS servers on your local network - **Job Management**: Upload images, track job status, and download results - **Fault Tolerance**: Automatic retries, circuit breaker pattern, and error tracking - **Authentication**: Secure API key authentication for all remote operations - **Health Monitoring**: Continuous server health checks and status reporting ## Usage 1. Start the server: ``` python src/main.py ``` 2. The server will start on http://localhost:8000 3. Use the MCP tools to interact with the server: - **generate_image_gemini**: Generate an image using Google Gemini API ```json { "prompt": "A low-poly rabbit with black background", "model": "gemini-2.0-flash-exp-image-generation" } ``` - **generate_multi_view_images**: Generate multiple views of the same 3D object ```json { "prompt": "A low-poly rabbit", "num_views": 4 } ``` - **create_3d_model_from_images**: Create a 3D model from approved multi-view images ```json { "image_ids": ["view_1", "view_2", "view_3", "view_4"], "output_name": "rabbit_model" } ``` - **create_3d_model_from_text**: Complete pipeline from text to 3D model ```json { "prompt": "A low-poly rabbit", "num_views": 4 } ``` - **export_model**: Export a model to a specific format ```json { "model_id": "your-model-id", "format": "obj" // or "stl", "ply", "scad", etc. } ``` - **discover_remote_cuda_mvs_servers**: Find CUDA MVS servers on your network ```json { "timeout": 5 } ``` - **get_remote_job_status**: Check the status of a remote processing job ```json { "server_id": "server-id", "job_id": "job-id" } ``` - **download_remote_model_result**: Download a completed model from a remote server ```json { "server_id": "server-id", "job_id": "job-id", "output_name": "model-name" } ``` - **discover_printers**: Discover 3D printers on the network ```json {} ``` - **print_model**: Print a model on a connected printer ```json { "model_id": "your-model-id", "printer_id": "your-printer-id" } ``` ## Image Generation Options The server supports multiple image generation options: 1. **Google Gemini API** (Default): Uses the Gemini 2.0 Flash Experimental model for high-quality image generation - Supports multi-view generation with consistent style - Requires a Google Gemini API key 2. **Venice.ai API** (Optional): Alternative image generation service - Supports various models including flux-dev and fluently-xl - Requires a Venice.ai API key 3. **User-Provided Images**: Skip image generation and use your own images - Upload images directly to the server - Useful for working with existing photographs or renders ## Multi-View Workflow The server implements a multi-view workflow for 3D reconstruction: 1. **Image Generation**: Generate multiple views of the same 3D object 2. **Image Approval**: Review and approve/deny each generated image 3. **3D Reconstruction**: Convert approved images into a 3D model using CUDA MVS - Can be processed locally or on a remote server within your LAN 4. **Model Refinement**: Optionally refine the model using OpenSCAD ## Remote Processing Workflow The remote processing workflow allows you to offload computationally intensive tasks to more powerful machines: 1. **Server Discovery**: Automatically discover CUDA MVS servers on your network 2. **Image Upload**: Upload approved multi-view images to the remote server 3. **Job Processing**: Process the images on the remote server using CUDA MVS 4. **Status Tracking**: Monitor the job status and progress 5. **Result Download**: Download the completed 3D model when processing is finished ## Supported Export Formats The server supports exporting models in various formats: - **OBJ**: Wavefront OBJ format (standard 3D model format) - **STL**: Standard Triangle Language (for 3D printing) - **PLY**: Polygon File Format (for point clouds and meshes) - **SCAD**: OpenSCAD source code (for parametric models) - **CSG**: OpenSCAD CSG format (preserves all parametric properties) - **AMF**: Additive Manufacturing File Format (preserves some metadata) - **3MF**: 3D Manufacturing Format (modern replacement for STL with metadata) ## Web Interface The server provides a web interface for: - Generating and approving multi-view images - Previewing 3D models from different angles - Downloading models in various formats Access the interface at http://localhost:8000/ui/ ## License MIT ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.