OpenSCAD MCP Server for 3D Model Generation

Overview

The OpenSCAD MCP Server is a Model Context Protocol (MCP) server designed to generate 3D models from text descriptions or images. It focuses on creating parametric 3D models using multi-view reconstruction and OpenSCAD. The server integrates AI image generation, multi-view image processing, and 3D reconstruction to streamline the model creation process.

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: Offload computationally intensive tasks to 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 follows a modular architecture with the following structure:

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:
   bash git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git cd OpenSCAD-MCP-Server
2. Create a virtual environment:
   bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
3. Install dependencies:
   bash pip install -r requirements.txt
4. Install OpenSCAD:
5. Ubuntu/Debian: sudo apt-get install openscad
6. macOS: brew install openscad
7. Windows: Download from openscad.org
8. Install CUDA Multi-View Stereo:
   bash git clone https://github.com/fixstars/cuda-multi-view-stereo.git cd cuda-multi-view-stereo mkdir build && cd build cmake .. make
9. Set up API keys:
10. Create a .env file in the root directory.
11. 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

Server Setup (on the machine with CUDA GPU)

1. Install CUDA Multi-View Stereo on the server machine:
   bash 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:
   bash 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, 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:
   bash python src/main.py
2. The server will start on http://localhost:8000.
3. Use the MCP tools to interact with the server:
4. generate_image_gemini: Generate an image using Google Gemini API.
5. generate_multi_view_images: Generate multiple views of the same 3D object.
6. create_3d_model_from_images: Create a 3D model from approved multi-view images.
7. create_3d_model_from_text: Complete pipeline from text to 3D model.
8. export_model: Export a model to a specific format.
9. discover_remote_cuda_mvs_servers: Find CUDA MVS servers on your network.
10. get_remote_job_status: Check the status of a remote processing job.
11. download_remote_model_result: Download a completed model from a remote server.
12. discover_printers: Discover 3D printers on the network.
13. print_model: Print a model on a connected printer.

Image Generation Options

1. Google Gemini API (Default): Uses the Gemini 2.0 Flash Experimental model for high-quality image generation.
2. Venice.ai API (Optional): Alternative image generation service.
3. User-Provided Images: Skip image generation and use your own images.

Multi-View Workflow

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.
4. Model Refinement: Optionally refine the model using OpenSCAD.

Remote Processing Workflow

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

• OBJ: Wavefront OBJ format.
• STL: Standard Triangle Language.
• PLY: Polygon File Format.
• SCAD: OpenSCAD source code.
• CSG: OpenSCAD CSG format.
• AMF: Additive Manufacturing File Format.
• 3MF: 3D Manufacturing Format.

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.

About

Mirror of https://github.com/jhacksman/OpenSCAD-MCP-Server.