使用说明

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

快速开始

git clone https://github.com/<owner>/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：
cloudflared tunnel --url http://localhost:3001
然后使用生成的 *.trycloudflare.com URL代替 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

许可证

麻省理工学院——见许可证.