Brick MCP App

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+

命令

建筑

服务器是 单一事实来源 对于所有场景状态。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.com URL代替 http://localhost:3001` 在下面的配置中。

克劳德桌面版

Claude Desktop本身不支持通过配置流式传输HTTP服务器。您需要将服务器添加为 自定义连接器 （可在付费计划中使用）：

1. 打开克劳德桌面设置
2. 导航至 连接器 并添加新的自定义连接器
3. 将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工具

无论您使用何种客户端与应用程序交互，都可以访问以下工具。

交互式用户界面

3D视口支持七种交互模式，可通过工具栏或键盘快捷键切换：

其他快捷方式：

砖块类型

\[！注意\] 这个列表不是最终的——随着时间的推移，将添加更多的砖块类型。看 添加新砖类型 如何贡献新类型。

三类20种砖：

坐标系

\[！注意\] 我可能会在未来进一步扩大这一范围（或完全取消基板）。目前的设置是非常实验性的。

• 底板：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 字段决定哪个几何生成器创建三维模型：

添加新类别

要添加全新的几何图形样式，请执行以下操作：

1. 在中创建几何体生成器 src/bricks/geometry/ （例如。 cylinder.ts)
2. 在开关中添加一个案例 src/bricks/geometry/index.ts:

   case 'cylinder': geometry = createCylinderGeometry(bt); break;

1. 将类别添加到 BrickDefinition 类型联合 src/bricks/types.ts
2. 几何形状必须 角原点 --跨越 [0, w] x [0, h] x [0, d] 在本地空间中

单位参考

本地测试

测试线束

该项目包括一个内置的视觉测试线束，用于在没有主机的情况下测试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

许可证

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