dend/brick-mcp-app

Brick Builder running in Claude, building a structure through natural language

Quick Start

git clone https://github.com//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

[!TIP] You can use Cloudflare Tunnels to expose your locally-hosted server to the internet. This lets you connect from claude.ai or any remote MCP host without port forwarding or VPNs: