内容
# openscad-wasm-mcp
一个在 Node.js/TypeScript 中使用 WebAssembly 运行 OpenSCAD 的模型上下文协议（MCP）服务器。无需在主机上安装原生 OpenSCAD。
## 快速入门
### 1. 使用 Docker Compose 运行
默认情况下，服务器在 Docker 中以受限权限运行：
```bash
docker compose up --build
```
MCP 服务器监听 `http://127.0.0.1:3333/mcp`。
### 2. 配置 MCP 客户端
将服务器添加到您的 MCP 客户端配置中（例如，`claude_desktop_config.json`）：
**使用 HTTP 传输（默认）：**
```json
{
"mcpServers": {
"openscad-wasm": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/client-cli", "http://127.0.0.1:3333/mcp"]
}
}
}
```
## 可用工具
### OpenSCAD 工具
- `openscad_validate`：验证 SCAD 代码并返回语法/逻辑诊断。
- `openscad_export_model`：将模型导出为 `stl`、`3mf`、`off`、`csg`、`dxf` 或 `svg`。
- `openscad_render_preview`：生成服务器端 WebP 渲染或交互式 3D 预览链接。
- `openscad_create_preview_link`：生成一个 URL 以打开基于浏览器的交互式 3D 查看器。
- `openscad_analyze_model`：计算模型的边界框和三角形数量。
### 工作区工具
- `workspace_list_files`：列出容器工作区中的文件。
- `workspace_read_file`：从工作区读取文件。
- `workspace_write_file`：将文件写入工作区。
- `workspace_delete_file`：从工作区删除文件。
## 工件
渲染和模型导出保存在主机上的 `./workspace/artifacts` 下。MCP 工具响应返回元数据：`path`、`filename`、`format`、`mimeType`、`sizeBytes` 和 `sha256`。
## 配置
通过复制 `.env.example` 到 `.env` 并编辑环境变量来自定义运行时限制（内存、超时、目录）。
## 已知限制
- **性能**：复杂模型在 WebAssembly 中可能较慢或内存密集。
- **视觉效果**：WebP 预览不保留 OpenSCAD 颜色、GUI 助手或 2D 相机视角。
- **资产和库**：字体和外部库未捆绑；您必须先将必要的文件上传到工作区。
- **格式支持**：构建特定的限制可能会影响导出（例如，`3mf` 目前不支持）。
## 许可证
MIT 许可证。有关详细信息，请参见 [LICENSE](LICENSE)。依赖项 (`openscad-wasm`、`sharp`) 具有其各自的许可证。
