RackArchitect

---

🎯 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: Zero-Install Hosted Remote MCP + Live 3D Studio (Recommended — 0 Setup!)

Use the live, multi-tenant Hosted Remote MCP server right away without installing Node.js, pnpm, or Docker:

{
  "mcpServers": {
    "rack_architect_mcp": {
      "url": "https://mcp.rackarchitect.dev/mcp"
    }
  }
}

# Or add in 1 second via Claude Code CLI:
claude mcp add --transport http rack_architect_mcp https://mcp.rackarchitect.dev/mcp

# Or explore the Hosted Live 3D/2D Studio directly in your browser:
# https://mcp.rackarchitect.dev/

Option B: 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 all 52 Vitest 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 C: Self-Hosted Docker (Zero Local Node Dependencies)

# Build & run directly from GitHub in one step (bound to localhost):
docker build -t rack-architect-mcp https://github.com/itAlex240/rack-architect-mcp.git
docker run --rm -p 127.0.0.1:3100:3100 rack-architect-mcp
# Open http://127.0.0.1:3100/

Option D: 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, Claude Code, Cursor, VS Code, Windsurf, or Antigravity

Option 1: Zero-Install Hosted Remote MCP (Streamable HTTP & SSE — Instant 1-URL Setup)

Connect any MCP client directly over HTTPS — zero local dependencies, strict multi-session isolation, and an automatic real-time 3D browser twin for every AI session:

Live Hosted Endpoint	URL	Purpose
Streamable HTTP MCP (Recommended)	https://mcp.rackarchitect.dev/mcp	Modern MCP transport (POST / GET / DELETE /mcp) for Claude, Cursor, VS Code, Windsurf, Antigravity & MCP Inspector
Legacy HTTP+SSE MCP	https://mcp.rackarchitect.dev/sse	Backwards-compatible GET /sse + POST /messages transport
Live Hosted 3D Studio & Session Twin	https://mcp.rackarchitect.dev/	Interactive 3D/2D CAD Studio & live /?session=<uuid> WebSocket (wss://) viewer returned by every MCP tool call
MCP Discovery & Health Probe	https://mcp.rackarchitect.dev/.well-known/mcp.json	Machine-readable MCP discovery manifest & /health status endpoint

Standard mcp.json / Client Configuration (Streamable HTTP):

{
  "mcpServers": {
    "rack_architect_mcp": {
      "url": "https://mcp.rackarchitect.dev/mcp"
    }
  }
}

1-Line CLI & Inspector Commands:

# Claude Code CLI:
claude mcp add --transport http rack_architect_mcp https://mcp.rackarchitect.dev/mcp

# Test immediately in MCP Inspector:
npx @modelcontextprotocol/inspector https://mcp.rackarchitect.dev/mcp

Legacy HTTP+SSE Configuration (for older SSE-only MCP clients):

{
  "mcpServers": {
    "rack_architect_mcp": {
      "type": "sse",
      "url": "https://mcp.rackarchitect.dev/sse"
    }
  }
}

• Strict Multi-Session Isolation & Zero-Disk Exports: Every connecting MCP client receives its own isolated in-memory workspace (Mcp-Session-Id), a dedicated Live 3D Digital Twin URL (https://mcp.rackarchitect.dev/?session=<uuid>) streaming every AI tool mutation live over wss://, and direct HTTPS download URLs from export_deliverables (.svg, .md, .glb, .scad, .stl, .yaml).

Option 2: Local stdio + Local WebSocket Sidecar (127.0.0.1:3100)

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
• 3dprint-10inch-cover-panel-lines-1u.scad & .stl
• 3dprint-10inch-cover-panel-hex-1u.scad & .stl
• 3dprint-10inch-cover-panel-lines-2u.scad & .stl
• 3dprint-10inch-cover-panel-ribs-2u.scad & .stl

---

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

• Interactive Catalog & Cable Patch Builder (+ Catalog & Cable Builder):
  • Search all 67 hardware blueprints, filter by 10inch / 19inch / 6inch / 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 12 tools on document.modelContext when opened in a WebMCP-capable browser.

---

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

Stage	Diagnostic Codes	What Is Checked Deterministically?
1. Bounds & Slots	CODE_DUPLICATE_INSTANCE_ID, CODE_UNKNOWN_BLUEPRINT, CODE_RACK_BOUNDS_EXCEEDED, CODE_SLOT_NOT_FOUND, CODE_SLOT_OCCUPIED, CODE_SLOT_BOUNDS_EXCEEDED	Rack U height, panel width (19", 10", 6"), sub-U carrier slot dimensions (mm) and allowed categories.
2. 3D AABB & Doors	CODE_CHASSIS_COLLISION, CODE_CLEARANCE_COLLISION, CODE_FRONT_DOOR_VIOLATION, CODE_REAR_CLEARANCE_VIOLATION	Millimeter-exact 3D AABB overlap between front and rear equipment including dynamic plug clearances (schuko-cee7 = 55 mm, iec-c13 = 45 mm, sfp+ = 38 mm, rj45 = 35 mm).
3. Power & PoE DAG	CODE_POE_BUDGET_EXCEEDED, CODE_MISSING_POWER_INPUT, CODE_EXTERNAL_PSU_UNPLUGGED, CODE_PDU_OVERLOAD	Full electrical DAG from UPS/PDU to switches, external power bricks (Lenovo 135W Slim-Tip), and PoE PSE/PD budgets (196 W).
4. Cables & Speed	CODE_PORT_NOT_FOUND, CODE_PORT_ALREADY_OCCUPIED, CODE_PORT_INCOMPATIBLE, SPEED_MISMATCH, CODE_MISSING_CABLE_PORTAL, CODE_CABLE_BEND_RADIUS_VIOLATION	Connector compatibility, Cat5e bottleneck detection on $\ge 2.5\text{ GbE}$ links (SPEED_MISMATCH), front-to-rear brush portal checks, and minimum 3D spline bend radius.
5. Thermal & Acoustic	THERMAL_AIRFLOW_CONFLICT, THERMAL_HOTSPOT_STACKING, CODE_THERMAL_DENSITY_HIGH, ACOUSTIC_NOISE_HIGH, CODE_WEIGHT_LIMIT_WARNING	Opposing airflow (front-to-rear vs rear-to-front), stacked high-power fanless switches, BTU/hr heat load, and logarithmic dB(A) noise addition ($L_{\text{total}} = 10 \log_{10}(\sum 10^{L_i/10})$).

---

📦 Monorepo Architecture (packages/*)

Package	Description
@rack-mcp/core-domain	Pure TypeScript/Zod schemas, 3D coordinate transformer, AABB collision solver, 5-stage validator, and clamped Catmull-Rom 3D spline router (zero Node/DOM dependencies).
@rack-mcp/hardware-catalog	67 YAML hardware blueprints (10inch, 19inch, 6inch, carriers, sub-modules), port_groups matrix expander, and catalog search/validator.
@rack-mcp/exporters	elevation.svg, wiring-schematic.svg, BOM.md, headless binary .glb, and parametric .scad & .stl 3D-print generators.
@rack-mcp/mcp-server	Multi-tenant Remote MCP server (Streamable HTTP /mcp & SSE /sse) + local stdio MCP server, 12 tools, 4 resources, 2 prompts, 50-step Undo/Redo manager, and HTTP/WebSocket 3D sidecar (:3100).
@rack-mcp/web-viewer	React 19 + Three.js (@react-three/fiber) live 3D/2D CAD studio, Catalog/Cable Builder Drawer, and W3C WebMCP integration.
@rack-mcp/cli	Unified rack-mcp CLI (serve, validate, export).

---

🤝 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.