Brick Builder MCP App
A Three.js MCP App for designing 3D brick constructions inside MCP-enabled hosts like Claude Desktop and Visual Studio Code. Build interactively or let the AI build structures for you through natural language.
Quick Start · Connecting · Tools · Extensibility
Brick Builder running in Claude, building a structure through natural language
快速开始
git clone https://github.com//brick-mcp-app.git
cd brick-mcp-app
npm install
npm run build
npm run serve服务器启动于 http://localhost:3001/mcp.
先决条件
- Node.js 20+
- npm 10+
命令
| 命令 | 描述 |
|---|---|
npm install | 安装依赖项 |
npm run build | 构建客户端（Vite）+服务器（esbuild） |
npm run serve | 在开发模式下启动服务器（tsx，自动重新加载） |
npm run dev | 观看客户端+并发服务 |
npm start | 先构建后服务（一个命令） |
建筑
服务器是 单一事实来源 对于所有场景状态。AI（LLM）和交互式UI都只能通过MCP工具改变状态。服务器验证每个操作——冲突检测、边界检查、支持验证——并返回权威结果。
关键设计决策
- 共享模块级状态：主机为LLM和应用程序iframe创建单独的MCP会话。场景状态存在于模块级别，因此两个会话读取/写入相同的场景。
- 轮询跨会话同步：UI民意调查
brick_get_scene每秒都有LLM发起的更改。用户发起的更改（通过callServerTool)立即反映出来。 - 单层砖砌筑：LLM每人放置一块砖
brick_place调用并在响应中接收放置的砖块的足迹，从而能够精确定位后续砖块。
连接到主机
\[！提示\] 您可以使用 Cloudflare隧道 将本地托管的服务器暴露给互联网。这使您可以从claude.ai或任何远程MCP主机连接，而无需端口转发或VPN： ``sh cloudflared tunnel --url http://localhost:3001`然后使用生成的*.trycloudflare.comURL代替http://localhost:3001` 在下面的配置中。
克劳德桌面版
Claude Desktop本身不支持通过配置流式传输HTTP服务器。您需要将服务器添加为 自定义连接器 （可在付费计划中使用）：
- 打开克劳德桌面设置
- 导航至 连接器 并添加新的自定义连接器
- 将URL设置为MCP服务器的托管URL（如果您使用的是Cloudflare隧道，请附加
/mcp)
Visual Studio Code
Visual Studio Code本机支持流式HTTP MCP服务器。创建 .vscode/mcp.json 在您的工作空间中：
{
"servers": {
"brick-builder": {
"type": "http",
"url": "http://localhost:3001/mcp"
}
}
}或者使用命令选项板： MCP：添加服务器 > 超文本传输协议 > http://localhost:3001/mcp
MCP工具
无论您使用何种客户端与应用程序交互，都可以访问以下工具。
| 工具 | 说明 |
|---|---|
brick_read_me | 返回建筑指南、坐标系和示例 |
brick_get_available | 返回所有具有ID、尺寸和类别的砖类型 |
brick_render_scene | 打开3D查看器iframe（放置砖块前必须调用） |
brick_place | 放一块砖。返回带有足迹的放置砖块，以实现精确的相邻定位 |
brick_get_scene | 读取所有砖块及其足迹的当前场景状态 |
brick_remove_brick | 按ID移除单个砖块。级联以移除其上方的无支撑砖块 |
brick_clear_scene | 从场景中删除所有砖块 |
brick_export_scene | 导出为JSON或人类可读的摘要 |
交互式用户界面
3D视口支持七种交互模式，可通过工具栏或键盘快捷键切换：
| # | 模式 | 快捷方式 | 操作 |
|---|---|---|---|
| 1 | 看 | 1 | 动态观察、平移和缩放相机。没有砖块互动。 |
| 2 | 地点 | 2 | 单击网格以放置砖块。重影预览显示有效（绿色）或无效（红色）位置。 |
| 3 | 选择 | 3 | 单击一块砖以将其选中（突出显示）。 |
| 4 | 移动 | 4 | 将砖块拖动到新位置。 |
| 5 | 旋转 | 5 | 单击一块砖将其旋转90度。 |
| 6 | 删除 | 6 | 单击一块砖将其删除 |
| 7 | 油漆 | 7 | 单击砖块以更改其颜色。 |
其他快捷方式：
| 关键 | 行动 |
|---|---|
R | 原地模式下的循环旋转（0/90/180/270） |
Delete | 移除所选砖块 |
Escape | 取消选择/取消拖动 |
砖块类型
\[！注意\] 这个列表不是最终的——随着时间的推移，将添加更多的砖块类型。看 添加新砖类型 如何贡献新类型。
三类20种砖：
| 类别 | 类型 |
|---|---|
| 砖块 （标准高度，3个板单元） | 1x1、1x2、1x3、1x4、1x6、1x8、2x2、2x3、2x4、2x6、2x8 |
| 盘子 （1/3高度，1个板单元） | 1x1、1x2、1x4、2x2、2x4、2x6、4x4 |
| 斜坡 （斜顶） | 1x2、2x2、2x3 |
坐标系
\[！注意\] 我可能会在未来进一步扩大这一范围（或完全取消基板）。目前的设置是非常实验性的。
- 底板：48 x 48螺柱（x和Z轴）
- Y轴：板单位高度（1块标准砖=3个Y单位）
- 旋转：0、90、180或270度（交换X/Z维度）
- 所有位置都是捕捉到螺柱网格的整数
添加新砖类型
添加新砖只需要两个文件。目录、服务器验证、几何体渲染和UI选择器都会自动拾取它。
步骤1：创建定义
在中创建文件 src/bricks/definitions/The BrickDefinition 接口：
interface BrickDefinition {
id: string; // Unique ID used in tool calls (e.g. 'brick_3x2')
name: string; // Display name (e.g. '3×2 Brick')
category: 'brick' | 'plate' | 'slope' | 'technic' | 'corner';
studsX: number; // Width in studs (X axis)
studsZ: number; // Depth in studs (Z axis)
heightUnits: number; // Height in plate units (standard brick = 3, plate = 1)
blockout?: BlockoutZone[]; // Optional zones where bricks can't sit on top (slopes)
}示例 — src/bricks/definitions/brick_3x2.ts:
import type { BrickDefinition } from '../types.js';
const brick_3x2: BrickDefinition = {
id: 'brick_3x2',
name: '3×2 Brick',
category: 'brick',
studsX: 3,
studsZ: 2,
heightUnits: 3,
};
export default brick_3x2;带屏蔽的示例 （坡度）——斜面块螺柱连接：
const slope_2x3: BrickDefinition = {
id: 'slope_2x3',
name: '2×3 Slope 45°',
category: 'slope',
studsX: 2,
studsZ: 3,
heightUnits: 3,
blockout: [{ minX: 0, maxX: 2, minZ: 1, maxZ: 3, height: 3 }],
};步骤2：从索引导出
添加一行 src/bricks/definitions/index.ts:
export { default as brick_3x2 } from './brick_3x2.js';清单
砖块现在是：
- 在
BRICK_CATALOG（由出口自动填充） - LLM可通过以下方式获得
brick_get_available和brick_place - 显示在UI砖选择器面板中
- 通过服务器端冲突、边界和支持检查进行验证
- 基于自动生成的几何体渲染
category
没有更改 server.ts, BrickBuilder.tsx，或任何其他文件都需要使事情发生。
类别如何映射到几何图形
这 category 字段决定哪个几何生成器创建三维模型：
| 类别 | 高度约定 | 几何形状 |
|---|---|---|
brick | heightUnits: 3 （标准） | 顶部带螺柱的矩形，底部中空 |
plate | heightUnits: 1 （薄） | 与砖相同，1/3高 |
slope | heightUnits: 3 | 倾斜的顶面，仅在平坦部分有螺柱 |
technic | heightUnits: 3 | 墙上用于轴连接的销孔 |
corner | heightUnits: 1 | L形车身，带部分螺柱格栅 |
添加新类别
要添加全新的几何图形样式，请执行以下操作：
- 在中创建几何体生成器
src/bricks/geometry/（例如。cylinder.ts) - 在开关中添加一个案例
src/bricks/geometry/index.ts:
case 'cylinder': geometry = createCylinderGeometry(bt); break;- 将类别添加到
BrickDefinition类型联合src/bricks/types.ts - 几何形状必须 角原点 --跨越
[0, w] x [0, h] x [0, d]在本地空间中
单位参考
| 单位 | 世界大小 | 现实世界 |
|---|---|---|
| 1个螺柱（X/Z） | 1.0 | 8毫米 |
| 1个板单元（Y） | 0.4 | 3.2mm |
| 1块标准砖（Y） | 1.2（3块板） | 9.6mm |
本地测试
测试线束
该项目包括一个内置的视觉测试线束，用于在没有主机的情况下测试MCP工具。启动服务器并导航到：
http://localhost:3001/test该线束直接连接到MCP服务器，并为每个工具提供了一个带有按钮的侧边栏——渲染场景、放置砖块、清除、导出等。3D视口嵌入在旁边，因此您可以立即看到结果。
基本主机
您还可以使用MCP Apps SDK基本主机进行测试，该主机模拟了完整的主机环境（iframe、postMessage、， callServerTool):
# Terminal 1: start the server
npm run build && npm run serve
# Terminal 2: run basic-host
git clone --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps
cd /tmp/mcp-ext-apps/examples/basic-host
npm install
SERVERS='["http://localhost:3001/mcp"]' npm run start
# Open http://localhost:8080许可证
麻省理工学院——见 许可证.