OpenSCAD MCP 服务器

一个模型上下文协议 (MCP) 服务器，使用户能够从文本描述或图像生成 3D 模型，重点是使用多视图重建和 OpenSCAD 创建参数化 3D 模型。

特性

• AI 图像生成: 使用 Google Gemini 或 Venice.ai API 从文本描述生成图像
• 多视图图像生成: 为同一个 3D 对象创建多个视图以进行重建
• 图像审批工作流程: 在重建之前审查和批准/拒绝生成的图像
• 3D 重建: 使用 CUDA 多视图立体将批准的多视图图像转换为 3D 模型
• 远程处理: 在局域网内的远程服务器上处理计算密集型任务
• OpenSCAD 集成: 使用 OpenSCAD 生成参数化 3D 模型
• 参数化导出: 以保留参数化属性的格式导出模型 (CSG, AMF, 3MF, SCAD)
• 3D 打印机发现: 可选的网络打印机发现和直接打印

架构

该服务器使用 Python MCP SDK 构建，并遵循模块化架构：

openscad-mcp-server/
├── src/
│   ├── main.py                  # 主应用程序
│   ├── main_remote.py           # 远程 CUDA MVS 服务器
│   ├── ai/                      # AI 集成
│   │   ├── gemini_api.py        # 用于图像生成的 Google Gemini API
│   │   └── venice_api.py        # 用于图像生成的 Venice.ai API (可选)
│   ├── models/                  # 3D 模型生成
│   │   ├── cuda_mvs.py          # CUDA 多视图立体集成
│   │   └── code_generator.py    # OpenSCAD 代码生成
│   ├── workflow/                # 工作流程组件
│   │   ├── image_approval.py    # 图像审批机制
│   │   └── multi_view_to_model_pipeline.py  # 完整流程
│   ├── remote/                  # 远程处理
│   │   ├── cuda_mvs_client.py   # 远程 CUDA MVS 处理的客户端
│   │   ├── cuda_mvs_server.py   # 远程 CUDA MVS 处理的服务器
│   │   ├── connection_manager.py # 远程连接管理
│   │   └── error_handling.py    # 远程处理的错误处理
│   ├── openscad_wrapper/        # OpenSCAD CLI 包装器
│   ├── visualization/           # 预览生成和 Web 界面
│   ├── utils/                   # 实用函数
│   └── printer_discovery/       # 3D 打印机发现
├── scad/                        # 生成的 OpenSCAD 文件
├── output/                      # 输出文件 (模型, 预览)
│   ├── images/                  # 生成的图像
│   ├── multi_view/              # 多视图图像
│   ├── approved_images/         # 用于重建的已批准图像
│   └── models/                  # 生成的 3D 模型
├── templates/                   # Web 界面模板
└── static/                      # Web 界面的静态文件

安装

1. 克隆存储库:

   git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git
   cd OpenSCAD-MCP-Server
   

2. 创建一个虚拟环境:

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上: venv\Scripts\activate
   

3. 安装依赖项:

   pip install -r requirements.txt
   

4. 安装 OpenSCAD:

   • Ubuntu/Debian: sudo apt-get install openscad
   • macOS: brew install openscad
   • Windows: 从 openscad.org 下载

5. 安装 CUDA 多视图立体:

   git clone https://github.com/fixstars/cuda-multi-view-stereo.git
   cd cuda-multi-view-stereo
   mkdir build && cd build
   cmake ..
   make
   

6. 设置 API 密钥:

   • 在根目录中创建一个 .env 文件
   • 添加您的 API 密钥:

     GEMINI_API_KEY=your-gemini-api-key
     VENICE_API_KEY=your-venice-api-key  # 可选
     REMOTE_CUDA_MVS_API_KEY=your-remote-api-key  # 用于远程处理
     

远程处理设置

该服务器支持计算密集型任务的远程处理，特别是 CUDA 多视图立体重建。 这允许您将处理卸载到局域网内更强大的机器上。

服务器设置 (在具有 CUDA GPU 的机器上)

1. 在服务器机器上安装 CUDA 多视图立体:

   git clone https://github.com/fixstars/cuda-multi-view-stereo.git
   cd cuda-multi-view-stereo
   mkdir build && cd build
   cmake ..
   make
   

2. 启动远程 CUDA MVS 服务器:

   python src/main_remote.py
   

3. 服务器将使用 Zeroconf 在本地网络上自动广播自身。

客户端配置

1. 在您的 .env 文件中配置远程处理:

   REMOTE_CUDA_MVS_ENABLED=True
   REMOTE_CUDA_MVS_USE_LAN_DISCOVERY=True
   REMOTE_CUDA_MVS_API_KEY=your-shared-secret-key
   

2. 或者，您可以直接指定服务器 URL:

   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
   

远程处理特性

• 自动服务器发现: 在您的本地网络上查找 CUDA MVS 服务器
• 作业管理: 上传图像，跟踪作业状态，并下载结果
• 容错: 自动重试，断路器模式和错误跟踪
• 身份验证: 所有远程操作的安全 API 密钥身份验证
• 健康监控: 持续的服务器健康检查和状态报告

用法

1. 启动服务器:

   python src/main.py
   

2. 服务器将在 http://localhost:8000 上启动

3. 使用 MCP 工具与服务器交互:

   • generate_image_gemini: 使用 Google Gemini API 生成图像

     {
       "prompt": "一个带有黑色背景的低多边形兔子",
       "model": "gemini-2.0-flash-exp-image-generation"
     }
     

   • generate_multi_view_images: 生成同一 3D 对象的多个视图

     {
       "prompt": "一个低多边形兔子",
       "num_views": 4
     }
     

   • create_3d_model_from_images: 从批准的多视图图像创建 3D 模型

     {
       "image_ids": ["view_1", "view_2", "view_3", "view_4"],
       "output_name": "rabbit_model"
     }
     

   • create_3d_model_from_text: 从文本到 3D 模型的完整流程

     {
       "prompt": "一个低多边形兔子",
       "num_views": 4
     }
     

   • export_model: 将模型导出为特定格式

     {
       "model_id": "your-model-id",
       "format": "obj"  // 或 "stl", "ply", "scad", 等.
     }
     

   • discover_remote_cuda_mvs_servers: 在您的网络上查找 CUDA MVS 服务器

     {
       "timeout": 5
     }
     

   • get_remote_job_status: 检查远程处理作业的状态

     {
       "server_id": "server-id",
       "job_id": "job-id"
     }
     

   • download_remote_model_result: 从远程服务器下载已完成的模型

     {
       "server_id": "server-id",
       "job_id": "job-id",
       "output_name": "model-name"
     }
     

   • discover_printers: 发现网络上的 3D 打印机

     {}
     

   • print_model: 在连接的打印机上打印模型

     {
       "model_id": "your-model-id",
       "printer_id": "your-printer-id"
     }
     

图像生成选项

该服务器支持多种图像生成选项：

1. Google Gemini API (默认): 使用 Gemini 2.0 Flash Experimental 模型进行高质量图像生成

   • 支持具有一致风格的多视图生成
   • 需要 Google Gemini API 密钥

2. Venice.ai API (可选): 替代图像生成服务

   • 支持各种模型，包括 flux-dev 和 fluently-xl
   • 需要 Venice.ai API 密钥

3. 用户提供的图像: 跳过图像生成并使用您自己的图像

   • 将图像直接上传到服务器
   • 适用于处理现有照片或渲染图

多视图工作流程

该服务器实现了用于 3D 重建的多视图工作流程：

1. 图像生成: 生成同一 3D 对象的多个视图
2. 图像审批: 审查和批准/拒绝每个生成的图像
3. 3D 重建: 使用 CUDA MVS 将批准的图像转换为 3D 模型
   • 可以在本地或局域网内的远程服务器上处理
4. 模型细化: 可选择使用 OpenSCAD 细化模型

远程处理工作流程

远程处理工作流程允许您将计算密集型任务卸载到更强大的机器：

1. 服务器发现: 自动发现您网络上的 CUDA MVS 服务器
2. 图像上传: 将批准的多视图图像上传到远程服务器
3. 作业处理: 使用 CUDA MVS 在远程服务器上处理图像
4. 状态跟踪: 监控作业状态和进度
5. 结果下载: 处理完成后下载已完成的 3D 模型

支持的导出格式

该服务器支持以各种格式导出模型：

• OBJ: Wavefront OBJ 格式 (标准 3D 模型格式)
• STL: 标准三角形语言 (用于 3D 打印)
• PLY: 多边形文件格式 (用于点云和网格)
• SCAD: OpenSCAD 源代码 (用于参数化模型)
• CSG: OpenSCAD CSG 格式 (保留所有参数化属性)
• AMF: 增材制造文件格式 (保留一些元数据)
• 3MF: 3D 制造格式 (具有元数据的 STL 的现代替代品)

Web 界面

该服务器提供了一个 Web 界面，用于：

• 生成和批准多视图图像
• 从不同角度预览 3D 模型
• 以各种格式下载模型

在 http://localhost:8000/ui/ 访问该界面

许可证

MIT

贡献

欢迎贡献！ 请随时提交 Pull Request。