RackArchitect MCP

---

🎯 为什么选择 RackArchitect MCP？（三条黄金法则）

过去，使用 AI Agent 规划紧凑型 10 英寸迷你机架（例如 DeskPi RackMate T1/T2、Digitus SOHO）或高密度 19 英寸家庭实验室，总会因为一个原因失败：**大模型会凭空编造物理几何信息。**它们会忽略后置 PDU 上的 55 mm Schuko 插头会与前置安装的 182 mm Lenovo ThinkCentre M920q 发生碰撞，也会忽略两台无风扇 PoE 交换机堆叠后会形成热斑。

RackArchitect MCP 通过三条不可妥协的工程法则解决这一问题：

1. **大模型绝不猜测几何信息：**所有空间坐标（1 U = 44.45 mm）、3D 轴对齐包围盒（B_chassis + 动态插头间隙 $\Delta Z_{\text{plug}}$）、Catmull-Rom 3D 线缆样条、PoE 预算有向无环图，以及对数 dB(A) 声学总和，均由 @rack-mcp/core-domain 以毫米为单位确定性计算。
2. **单一事实来源（rack.yaml）：**整个机架状态（设备、3D 打印的 sub-U 承载架插槽、子级迷你 PC、Keystone 耦合器、线缆、VLAN 和 IP CIDR）都存储在一个便于 Git 管理的 YAML 文件中。
3. **可操作的自我纠正反馈：**每当设备放置或线缆未通过 5 个验证阶段中的任何一项（26 种封闭的 DiagnosticCode 类型）时，引擎都会返回结构化的 remediation_suggestions，让 AI Agent 在下一轮中自主修复碰撞、PoE 过载或 Cat5e 瓶颈。

---

🖼️ 生成的 CAD 蓝图（100% 确定性 SVG 输出）

1. 双排工程立面图与 Z 深度侧剖图（elevation.svg）

包含设备清单、正面立面图（X, Y）、水平镜像的后部立面图（W_panel - X - width）、线缆标注区域，以及右侧 Z 深度剖图（Z_min 至 Z_max，并检查前玻璃门 -50 mm 和后墙 +300 mm 的间隙）：

2. 带 VLAN 与 IP CIDR 标记的 5 层逻辑引脚对引脚布线示意图（wiring-schematic.svg）

---

🚀 30 秒快速入门

选项 A：本地 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

在浏览器中打开 http://127.0.0.1:3100/，查看 3D 数字孪生，从目录抽屉中装载设备，布置 3D 样条线缆，并下载 .SCAD / .STL / .GLB / .SVG / BOM.md 交付文件！

选项 B：Docker（无需本地依赖）

# 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/

选项 C：CLI 验证和无头 CAD 导出

# 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

---

🤖 连接 Claude Desktop、Cursor 或 Antigravity

将 rack_architect_mcp 添加到 claude_desktop_config.json、.cursor/mcp.json 或 Antigravity MCP 设置中：

{
  "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"
      ]
    }
  }
}

每当你的 AI Agent 通过 stdio 启动 MCP 服务时，它都会自动在 http://127.0.0.1:3100 启动本地 WebSocket Sidecar。AI 执行的每次工具调用（mount_equipment、connect_cables、modify_equipment、undo_redo）都会实时更新 3D 浏览器视图！

🧠 官方开源 Agent Skill（skills/rack-architect/SKILL.md）

此仓库包含一个完全免费、采用 MIT 许可的 Agent Skill（skills/rack-architect/SKILL.md 和 .agents/skills/rack-architect/SKILL.md），可教会 Claude Code、Cursor、GitHub Copilot 和 Google Antigravity 掌握完整的6 阶段自主机架工程操作手册（sub-U 模块化载体配对、-angled 插头选择、全部 26 种诊断修复模式，以及 2 manifold .STL 导出）：

# 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!

---

🖨️ 参数化 3D 打印生成器（.scad 和 .stl）

对于每个模块化 3D 打印载体（category: 'modular-carrier'），@rack-mcp/exporters 会自动生成：

1. 参数化 OpenSCAD（.scad）： 可自定义壁厚、EIA-310 椭圆机架耳（9.5 × 6.5 mm）、sub-U 设备槽（适用于 Lenovo ThinkCentre M920q、Ubiquiti UCG-Max、JetKVM，公差为 +0.35 mm）、Keystone 卡扣、侧面支撑导轨，以及带魔术贴槽的后置 PSU 电源砖托架。
2. 可直接切片的水密 ASCII .stl： 通过 2D 网格细分直接在内存中计算生成，可直接导入 OrcaSlicer、Bambu Studio 或 PrusaSlicer！

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

---

🖥️ 实时 3D 数字孪生与 2D CAD Web 查看器（127.0.0.1:3100）

• 交互式目录与线缆配线构建器（+ Catalog & Cable Builder）：
  • 搜索全部 67 个硬件蓝图，按 10inch / 19inch / 6inch / sub-module 筛选，选择 Target U + FRONT/REAR，一键安装。
  • 在任意两个端口之间布设 3D Catmull-Rom 线缆，并可选择添加 VLAN ID（1..4094）和 IP CIDR（10.10.20.0/24）注释。
• 3D 工程 HUD：
  • 相机预设：Perspective、Front Ortho、Rear Ortho、Left Cutaway
  • 切换项：X-Ray Chassis（检查内部迷你 PC 和 PSU 电源适配器）、Clearance Boxes（$\Delta Z_{\text{plug}}$ 线框）、Cable Splines
  • Explode Z (0..140 mm) 滑块，用于分离前后组件
• 支持 W3C WebMCP： 在支持 WebMCP 的浏览器中打开时，自动在 document.modelContext 上注册全部 11 个工具。

---

🛡️ 5 阶段验证引擎（全部 26 个诊断代码）

阶段	诊断代码	确定性检查内容
1. 边界与插槽	CODE_DUPLICATE_INSTANCE_ID、CODE_UNKNOWN_BLUEPRINT、CODE_RACK_BOUNDS_EXCEEDED、CODE_SLOT_NOT_FOUND、CODE_SLOT_OCCUPIED、CODE_SLOT_BOUNDS_EXCEEDED	机架 U 高度、面板宽度（19"、10"、6"）、子 U 承载插槽尺寸（mm）和允许的类别。
2. 3D AABB 与门板	CODE_CHASSIS_COLLISION、CODE_CLEARANCE_COLLISION、CODE_FRONT_DOOR_VIOLATION、CODE_REAR_CLEARANCE_VIOLATION	前后设备间精确到毫米的 3D AABB 重叠检测，包括动态插头净空（schuko-cee7 = 55 mm、iec-c13 = 45 mm、sfp+ = 38 mm、rj45 = 35 mm）。
3. 电源与 PoE DAG	CODE_POE_BUDGET_EXCEEDED、CODE_MISSING_POWER_INPUT、CODE_EXTERNAL_PSU_UNPLUGGED、CODE_PDU_OVERLOAD	从 UPS/PDU 到交换机、外置电源适配器（Lenovo 135W Slim-Tip）以及 PoE PSE/PD 预算（196 W）的完整电气 DAG。
4. 线缆与速率	CODE_PORT_NOT_FOUND、CODE_PORT_ALREADY_OCCUPIED、CODE_PORT_INCOMPATIBLE、SPEED_MISMATCH、CODE_MISSING_CABLE_PORTAL、CODE_CABLE_BEND_RADIUS_VIOLATION	连接器兼容性、检测 $\ge 2.5\text{ GbE}$ 链路上的 Cat5e 瓶颈（SPEED_MISMATCH）、前后侧刷线孔检查，以及最小 3D 样条曲线弯曲半径。
5. 热与声学	THERMAL_AIRFLOW_CONFLICT、THERMAL_HOTSPOT_STACKING、CODE_THERMAL_DENSITY_HIGH、ACOUSTIC_NOISE_HIGH、CODE_WEIGHT_LIMIT_WARNING	气流方向相反（front-to-rear 与 rear-to-front）、高功率无风扇交换机堆叠、BTU/hr 热负荷，以及对数 dB(A) 噪声叠加（$L_{\text{total}} = 10 \log_{10}(\sum 10^{L_i/10})$）。

---

📦 Monorepo 架构（packages/*）

软件包	描述
@rack-mcp/core-domain	纯 TypeScript/Zod 模式、3D 坐标转换器、AABB 碰撞求解器、5 阶段验证器，以及带限幅的 Catmull-Rom 3D 样条路由器（不依赖 Node/DOM）。
@rack-mcp/hardware-catalog	67 个 YAML 硬件蓝图（10inch、19inch、6inch、carriers、sub-modules）、port_groups 矩阵展开器，以及目录搜索/验证器。
@rack-mcp/exporters	elevation.svg、wiring-schematic.svg、BOM.md、无头二进制 .glb，以及参数化 .scad 和 .stl 3D 打印生成器。
@rack-mcp/mcp-server	MCP 服务（stdio）、11 个工具、4 个资源、2 个提示词、50 步撤销/重做管理器，以及本地 HTTP/WebSocket 伴随服务（:3100）。
@rack-mcp/web-viewer	React 19 + Three.js（@react-three/fiber）实时 3D/2D CAD 工作室、目录/线缆构建器抽屉，以及 W3C WebMCP 集成。
@rack-mcp/cli	统一的 rack-mcp CLI（serve、validate、export）。

---

🤝 贡献与添加硬件蓝图

想添加你喜欢的 10 英寸交换机、迷你 PC 或 3D 打印载板？你可以在不到 2 分钟内添加新的 YAML 蓝图——请参阅 CONTRIBUTING.md！

📄 许可证

基于 MIT License 发布。