内容
# 雕刻
**一个MCP服务器，允许AI代理构建、编辑、渲染和导出真正的3D模型** —
从几何基元和布尔CSG。无需扩散，无需GPU，无需浏览器。代理
调用建模工具，返回多视图渲染以查看其工作，迭代并
导出干净的`.glb`/`.obj`。
> 每个模型都是真实的可编辑几何体 — 盒子、球体、圆柱体、圆锥体组合并使用
> `union` / `subtract` / `intersect`并镜像以实现对称。上面的渲染（一个由9个工具调用构建的椅子）
> 是由**纯CPU软件光栅化器**生成的 — 与代理看到的相同
> 东西。
## 为什么
图像/网格扩散模型绘制表面 — 您得到一个无法干净编辑或
布尔运算的blob。Chisel采用相反的方法：给代理一个**离散的、可检查的
建模API**和一个**查看和修订循环**，它构建您可以打开的真实实体
在Blender中，切片打印，或放入游戏引擎。
3D-by-agent的难点不是几何体，而是**遮挡** — 任何单个视图都会隐藏
模型的一半。因此，Chisel每次渲染四个规范视图（前/侧/上/
iso）并将它们作为图像返回，以便代理推理整个表单，而不是一个
面。
## 快速开始
运行服务器（stdio）：
```bash
# 零安装，直接从GitHub（首次运行后构建）
npx -y github:EYamanS/chisel
# … 或从克隆
git clone https://github.com/EYamanS/chisel && cd chisel
npm install
npm run mcp
```
将其连接到任何MCP客户端（`claude_desktop_config.json`, `.mcp.json`, 等）：
```json
{
"mcpServers": {
"chisel": {
"command": "npx",
"args": ["-y", "github:EYamanS/chisel"],
"env": { "CSG_OUTPUT_DIR": "/absolute/path/to/exports" }
}
}
}
```
或指向本地克隆以加速：
```json
{
"mcpServers": {
"chisel": {
"command": "node",
"args": ["/absolute/path/to/chisel/dist/server.js"],
"env": { "CSG_OUTPUT_DIR": "/absolute/path/to/exports" }
}
}
}
```
然后只需询问您的代理： *"建模一个咖啡杯并将其导出为glb。"*
## 工具
| 工具 | 功能 |
|------|--------------|
| `add_box` `add_sphere` `add_cylinder` `add_cone` | 添加基本体（大小/半径/高度，位置，旋转，颜色）。 |
| `transform` | 移动 / 旋转 / 缩放对象（绝对或相对）。 |
| `union` `subtract` `intersect` | 布尔CSG — 融合，挖孔，或剪裁到重叠部分。 |
| `mirror` | 将对象反射到X/Y/Z。 与布尔运算组合 — 构建一侧，镜像它。 |
| `set_color` `delete` `select` | 重新着色，删除，突出显示。 |
| `get_scene` | 返回场景图为文本（每个对象，形状，变换）。 |
| `render` | 返回2×2多视图PNG（前/侧/上/iso）以便代理可以**查看**模型。 |
| `export_model` | 将`.glb`或`.obj`写入磁盘; 返回路径。 `inline:true`用于base64。 |
| `reset` | 清除会话到空场景。 |
模型在每个`session` id（默认为`main`）的生命周期内持续存在，因此代理
跨调用逐步构建。渲染是**无GPU**（评估的CSG三角形的软件光栅化器），
因此它在Node运行的任何地方运行 — 笔记本电脑，CI，容器。
## 典型代理循环
```
add_cylinder { radius: 0.6, height: 1.2, position: [0, 0.6, 0], color: "steel" } -> obj1
add_cylinder { radius: 0.46, height: 1.1, position: [0, 0.74, 0] } -> obj2
subtract { a: "obj1", b: "obj2" } # hollow it out -> obj3
render # look at all four views, notice it needs a handle
add_box { size: [0.16, 0.62, 0.16], position: [0.66, 0.62, 0], color: "steel" }
union { a: "obj3", b: "obj4", name: "mug" }
render # looks right
export_model { format: "glb" } # -> ./exports/main-<ts>.glb
```
## 网络游乐场（可选）
仓库还附带了一个交互式Next.js游乐场，其中OpenAI模型驱动
同一个引擎在您的浏览器中，具有实时3D视口和glTF/OBJ导出：
```bash
cp .env.local.example .env.local # add OPENAI_API_KEY
npm run dev # http://localhost:3000
```
**Demo**按钮（Mug / Table / Rocket）使用完整的引擎，无需API密钥。
## 工作原理
```
src/lib/scene/ types.ts 场景图：CSG表达式树的扁平列表
operations.ts 确定性约简器 — 应用一个工具调用
tools.ts 建模工具模式（MCP + web代理共享）
src/lib/three/ build.ts 场景图 -> Three.js网格（评估CSG）
src/lib/render/ raster.ts 无头软件渲染器（无GPU）-> 2x2 PNG
export.ts glTF/OBJ导出 | png.ts编码器 | font.ts标签
src/mcp/ server.ts MCP服务器（stdio）| engine.ts会话存储
src/lib/agent/ loop.ts 网络游乐场的渲染->查看->修订代理循环
src/components/ Viewport.tsx 浏览器视口（WebGL）+ 捕获 + 导出
src/app/ page.tsx 游乐场UI | api/agent/route.ts OpenAI代理
```
MCP服务器和网络游乐场是**一个引擎**的两个前端 — 相同的场景
图，相同的CSG，相同的工具模式。MCP路径是完全无头的（软件渲染）;
网络路径为交互式视口使用WebGL。
## 开发
```bash
npm run mcp # 从源代码运行MCP服务器（tsx）
npm run build:mcp # 打包自包含的二进制文件 -> dist/server.js
npm run dev # 网络游乐场
npm run build # 生产环境构建网络应用
```
## 许可证
MIT © Emir Yaman Sivrikaya
