RackArchitect MCP

🏗️ RackArchitect MCP (@rack-mcp/*)

The Open-Source, Agent-First "Rack-as-Code" Planning, 5-Stage Validation, Parametric 3D-Print (.scad/.stl) & Live 2D/3D CAD Platform for 19-Inch Enterprise Racks, 10-Inch Mini-Racks & 6-Inch Micro-Homelabs

-EC4899.svg)

**🌐 Launch Live 3D/2D Browser Demo** · **Quickstart** · **MCP Client & Agent Skill** · **3D-Print (.SCAD / .STL)** · **Add Hardware Blueprint** · **Complete Handbook (DE)**

🎯 Why RackArchitect MCP? (The Three Golden Laws)

Planning a compact 10-inch mini-rack (e.g., DeskPi RackMate T1/T2, Digitus SOHO) or a dense 19-inch homelab with AI agents used to fail for one reason: LLMs hallucinate physical geometry. They forget that a 55 mm Schuko plug on a rear PDU collides with a 182 mm Lenovo ThinkCentre M920q mounted in front, or that two fanless PoE switches stacked together create a thermal hotspot.

RackArchitect MCP solves this with three non-negotiable engineering laws:

1. LLMs Never Guess Geometry: Every spatial coordinate (1 U = 44.45 mm), 3D Axis-Aligned Bounding Box (B_chassis + dynamic plug clearance $\Delta Z_{\text{plug}}$), Catmull-Rom 3D cable spline, PoE budget DAG, and logarithmic dB(A) acoustic sum is computed deterministically in millimeters by @rack-mcp/core-domain.
2. Single Source of Truth (rack.yaml): Your entire rack state (devices, 3D-printed sub-U carrier slots, child mini-PCs, keystone couplers, cables, VLANs, and IP CIDRs) lives in a single, Git-friendly YAML file.
3. Actionable Self-Correction Feedback: Whenever a placement or cable fails any of the 5 validation stages (26 closed DiagnosticCode types), the engine returns structured remediation_suggestions so your AI agent fixes the collision, PoE overload, or Cat5e bottleneck autonomously in the very next turn.

🖼️ Generated CAD Blueprints (100% Deterministic SVG Output)

1. Dual-Row Engineering Elevation & Z-Depth Side Cutaway (elevation.svg)

Includes Equipment Schedule, Front Elevation (X, Y), Horizontally Mirrored Rear Elevation (W_panel - X - width), Cable Callout Lanes, and Right-Hand Z-Depth Cutaway (Z_min to Z_max with Front Glass Door -50 mm and Rear Wall +300 mm clearance checks):

2. 5-Layer Logical Pin-to-Pin Wiring Schematic with VLAN & IP CIDR Badges (wiring-schematic.svg)

🚀 30-Second Quickstart

Option A: Local Node.js (>= 20) & pnpm

# 1. Clone & install
git clone https://github.com/itAlex240/rack-architect-mcp.git
cd rack-architect-mcp
pnpm install

# 2. Build all 6 packages & run the 34 test suites
pnpm build
pnpm test

# 3. Launch the Live 3D/2D Web-Viewer & Sidecar on the 8U 10-Inch Reference Homelab
pnpm start

Open http://127.0.0.1:3100/ in your browser to inspect the 3D Digital Twin, mount devices from the Catalog Drawer, route 3D spline cables, and download .SCAD / .STL / .GLB / .SVG / BOM.md deliverables!

Option B: Docker (Zero Local Dependencies)

# Run the pre-built image from GitHub Container Registry:
docker run --rm -p 3100:3100 ghcr.io/italex240/rack-architect-mcp:latest

# Or build locally:
docker build -t rack-architect-mcp .
docker run --rm -p 3100:3100 rack-architect-mcp
# Open http://127.0.0.1:3100/

Option C: CLI Validation & Headless CAD Export

# Validate any rack.yaml and print the ASCII Elevation Plan + Diagnostics
pnpm validate:demo

# Export elevation.svg, wiring-schematic.svg, BOM.md, rack-scene.glb, and all .scad + .stl 3D-print carriers
pnpm export:demo

🤖 Connect Claude Desktop, Cursor, or Antigravity

Add rack_architect_mcp to your claude_desktop_config.json, .cursor/mcp.json, or Antigravity MCP settings:

{
  "mcpServers": {
    "rack_architect_mcp": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/rack-architect-mcp/packages/cli/dist/bin.js",
        "--stdio",
        "--port",
        "3100",
        "--project",
        "/ABSOLUTE/PATH/TO/rack-architect-mcp/examples/10inch-homelab/rack.yaml"
      ]
    }
  }
}

Whenever your AI agent starts the MCP server over stdio, it automatically launches the local WebSocket Sidecar at http://127.0.0.1:3100. Every tool call the AI executes (mount_equipment, connect_cables, modify_equipment, undo_redo) updates your 3D browser view in real time!

🧠 Official Open-Source Agent Skill (skills/rack-architect/SKILL.md)

This repository includes a 100% free, MIT-licensed Agent Skill (skills/rack-architect/SKILL.md & .agents/skills/rack-architect/SKILL.md) that teaches Claude Code, Cursor, GitHub Copilot, and Google Antigravity the complete 6-Phase Autonomous Rack Engineering Runbook (sub-U modular carrier pairing, -angled plug selection, all 26 diagnostic remediation patterns, and 2-manifold .STL export):

# Install the skill into Claude Code, Cursor, Copilot, or Windsurf via skills CLI:
npx skills add itAlex240/rack-architect-mcp

# Or in Google Antigravity: automatically discovered from .agents/skills/rack-architect/SKILL.md!

🖨️ Parametric 3D-Print Generator (.scad & .stl)

For every modular 3D-printed carrier (category: 'modular-carrier'), @rack-mcp/exporters automatically generates:

1. Parametric OpenSCAD (.scad): Customizable wall thickness, EIA-310 oval rack ears (9.5 × 6.5 mm), sub-U device bays (+0.35 mm tolerance for Lenovo ThinkCentre M920q, Ubiquiti UCG-Max, JetKVM), Keystone snap-in clips, side support rails, and rear PSU brick cradles with Velcro slots.
2. Ready-to-Slice Watertight ASCII .stl: Computed directly in memory via 2D grid subdivision—drop straight into OrcaSlicer, Bambu Studio, or PrusaSlicer!

Pre-generated reference files in examples/10inch-homelab/:

• 3dprint-10inch-lenovo-tiny-plus-2keystone.scad & .stl
• 3dprint-10inch-ucg-ultra-plus-3keystone.scad & .stl

🖥️ Live 3D Digital Twin & 2D CAD Web-Viewer (127.0.0.1:3100)

• Interactive Catalog & Cable Patch Builder (+ Catalog & Cable Builder):
  • Search all 30 hardware blueprints, filter by 10inch / 19inch / sub-module, select Target U + FRONT/REAR, and mount with 1 click.
  • Patch 3D Catmull-Rom cables between any two ports with optional VLAN ID (1..4094) and IP CIDR (10.10.20.0/24) annotations.
• 3D Engineering HUD:
  • Camera Presets: Perspective, Front Ortho, Rear Ortho, Left Cutaway
  • Toggles: X-Ray Chassis (inspect internal mini-PCs & PSU bricks), Clearance Boxes ($\Delta Z_{\text{plug}}$ wireframes), Cable Splines
  • Explode Z (0..140 mm) slider to separate front and rear assemblies
• W3C WebMCP Ready: Automatically registers all 11 tools on document.modelContext when opened in a WebMCP-capable browser.

🛡️ 5-Stage Validation Engine (All 26 Diagnostic Codes)

📦 Monorepo Architecture (packages/*)

🤝 Contributing & Adding Hardware Blueprints

Want to add your favorite 10-inch switch, mini-PC, or 3D-printed carrier? You can add a new YAML blueprint in under 2 minutes—see **CONTRIBUTING.md**!

📄 License

Released under the **MIT License**.