Brick Builder MCP App

Quick Start

git clone https://github.com/<owner>/brick-mcp-app.git
cd brick-mcp-app
npm install
npm run build
npm run serve

The server starts at http://localhost:3001/mcp.

Prerequisites

• Node.js 20+

• npm 10+

Commands

Architecture

The server is the single source of truth for all scene state. Both the AI (LLM) and the interactive UI mutate state exclusively through MCP tools. The server validates every operation — collision detection, bounds checking, support verification — and returns authoritative results.

Key Design Decisions

• Shared module-level state: The host creates separate MCP sessions for the LLM and the app iframe. Scene state lives at module level so both sessions read/write the same scene.

• Polling for cross-session sync: The UI polls brick_get_scene every second to pick up LLM-initiated changes. User-initiated changes (via callServerTool) are reflected instantly.

• Single-brick placement: The LLM places one brick per brick_place call and receives the placed brick's footprint in the response, enabling precise positioning of subsequent bricks.

Connecting to Hosts

cloudflared tunnel --url http://localhost:3001

Claude Desktop

Claude Desktop does not natively support streamable HTTP servers through config. You need to add the server as a custom connector (available on paid plans):

1. Open Claude Desktop settings

2. Navigate to Connectors and add a new custom connector

3. Set the URL to the hosted URL of your MCP server (if you are using Cloudflare Tunnels, append /mcp)

Visual Studio Code

Visual Studio Code supports Streamable HTTP MCP servers natively. Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "brick-builder": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Or use the Command Palette: MCP: Add Server > HTTP > http://localhost:3001/mcp

MCP Tools

The following tools are accessible from whatever client you're using to interact with the app.

Interactive UI

The 3D viewport supports seven interaction modes, switchable via the toolbar or keyboard shortcuts:

Additional shortcuts:

Brick Types

20 brick types across three categories:

Coordinate System

• Baseplate: 48 x 48 studs (X and Z axes)

• Y axis: Height in plate units (1 standard brick = 3 Y units)

• Rotation: 0, 90, 180, or 270 degrees (swaps X/Z dimensions)

• All positions are integers snapped to the stud grid

Adding New Brick Types

Adding a new brick requires just two files. The catalog, server validation, geometry rendering, and UI selector all pick it up automatically.

Step 1: Create the definition

Create a file in src/bricks/definitions/. The BrickDefinition interface:

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)
}

Example — 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;

Example with blockout (slope) — the angled face blocks stud connections:

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 }],
};

Step 2: Export from the index

Add one line to src/bricks/definitions/index.ts:

export { default as brick_3x2 } from './brick_3x2.js';

Checklist

The brick is now:

• In BRICK_CATALOG (auto-populated from exports)

• Available to the LLM via brick_get_available and brick_place

• Shown in the UI brick selector panel

• Validated by server-side collision, bounds, and support checks

• Rendered with auto-generated geometry based on category

No changes to server.ts, BrickBuilder.tsx, or any other file are needed to make things happen.

How categories map to geometry

The category field determines which geometry builder creates the 3D model:

Adding a new category

To add an entirely new geometry style:

1. Create a geometry builder in src/bricks/geometry/ (e.g. cylinder.ts)

2. Add a case to the switch in src/bricks/geometry/index.ts:

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

3. Add the category to the BrickDefinition type union in src/bricks/types.ts

4. Geometries must be corner-origin — spanning [0, w] x [0, h] x [0, d] in local space

Unit reference

Local Testing

Test harness

The project includes a built-in visual test harness for testing MCP tools without a host. Start the server and navigate to:

http://localhost:3001/test

The harness connects directly to the MCP server and provides a sidebar with buttons for every tool — render the scene, place bricks, clear, export, etc. The 3D viewport is embedded alongside so you can see results immediately.

basic-host

You can also test using the MCP Apps SDK basic-host, which simulates the full host environment (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

License

MIT — see LICENSE.