BDB Hardware & PCB

@hybridlabor-api/bdb-hardware-pcb — Electrical Engineering, PCB Design, and 3D Mechanical Enclosure tooling for AI coding agents: 6 skills plus two MCP servers (KiCad, OpenSCAD) exposing 55 tools over stdio JSON-RPC.

Supports KiCad 9 & 10 automation and OpenSCAD parametric enclosures across Anthropic Claude Code, OpenAI Codex, and Google Antigravity (Gemini).

Install

Option A — as part of AOS

If you already use @hybridlabor-api/bdb-dev-optimized-agent-skills (AOS), its installer offers this package as an optional module (same mechanism as bdb-synapse / bdb-dev-creator-extension): AOS downloads this package and runs its installer.js --auto for you. No separate step needed.

Option B — standalone

npx @hybridlabor-api/bdb-hardware-pcb

This runs installer.js directly, non-interactively, on macOS, Linux, or Windows. It will:

1. Set up the kicad-mcp-server and openscad-mcp-server Python virtual environments (via uv sync if uv is on PATH, otherwise python3/python -m venv + pip install -e .).
2. Detect which harnesses are present on this machine (~/.claude, ~/.codex, ~/.gemini, ~/.agents) and, for each one found:
   • copy the 5 skill directories into its skills folder,
   • merge the kicad and openscad MCP server entries into its real MCP config file (without touching any other entries already there).

Every step prints one line saying what it actually did, or why it was skipped. Nothing is silently a no-op.

Re-run the installer any time (e.g. after moving/reinstalling this package) to refresh the registered paths — it is idempotent and self-healing: it rewrites stale command paths in place rather than leaving them broken.

Verify

./scripts/test_mcp_connection.sh --all

Spawns both MCP servers over real stdio, performs the JSON-RPC initialize handshake, lists tools, and validates every tool's schema — 47 tools from KiCad + 8 from OpenSCAD = 55 tools, exit code 0 on success.

Read HANDOFF_REVIEW.md for the detailed verification dossier, and docs/adr/ADR-001-KICAD-OPENSCAD-MCP-STRATEGY.md for the architecture decision record behind the KiCad/OpenSCAD MCP choice.

The 6 skills

1. code-first-hardware-design — programmatic schematics via SKiDL, OpenSCAD parametric enclosures, text-based netlists.
2. pcb-constraint-definition — differential impedance, high-voltage creepage/clearance, return-path routing.
3. schematic-datasheet-analysis — automated PDF datasheet parsing, pinmux validation, decoupling networks.
4. pcb-layout-routing-automation — stackup configuration, placement heuristics, auto-routing via CLI, shared placement preamble with iterative render gate.
5. pcb-validation-dfm-signoff — automated ERC/DRC execution, SI/PI integrity audits, DFM manufacturing constraints.
6. schematic-reverse-engineering — rebuild a board photo or web schematic in KiCad in batches of 5–10 with render + vision diff + ERC per batch.

MCP servers

• KiCad MCP Server (mcp_servers/kicad-mcp-server, upstream: Seeed-Studio/kicad-mcp-server) — 47 tools: schematic capture, netlist generation, pinmux analysis, ERC, DRC, 3D rendering.
• OpenSCAD MCP Server (mcp_servers/openscad-mcp-server, upstream: jhacksman/OpenSCAD-MCP-Server) — 8 tools: parametric 3D enclosure modeling, STL export, multi-view PNG rendering.

Both are third-party Python MCP servers vendored under mcp_servers/; their .venv/ is created fresh at install time and is never shipped in the npm package.

Repository layout

bdb-hardware-pcb/
├── installer.js          # cross-platform installer (npx entry point / AOS module)
├── config/mcp/            # reference-only MCP config templates (placeholder paths;
│                           # installer.js generates the real, machine-specific config)
├── docs/adr/               # architectural decision records (ADR-001)
├── mcp_servers/
│   ├── kicad-mcp-server     # vendored Python MCP server (KiCad)
│   └── openscad-mcp-server  # vendored Python MCP server (OpenSCAD)
├── scripts/
│   ├── test_mcp_connection.py  # zero-dependency stdlib JSON-RPC tester
│   ├── test_mcp_connection.sh  # multi-harness test runner
│   ├── run_kicad_mcp.sh        # self-locating KiCad MCP launcher
│   ├── run_openscad_mcp.sh     # self-locating OpenSCAD MCP launcher
│   ├── openscad_wrapper.sh     # macOS / Linux OpenSCAD binary shim
│   ├── kicad-cli-path.sh       # kicad-cli locator (KICAD_CLI_PATH-aware)
│   ├── kicad-version.sh        # kicad-cli version probe
│   ├── kicad-project-find.sh   # KiCad project file finder (read-only)
│   ├── kicad-render.sh         # deterministic kicad-cli render wrapper
│   ├── kicad-drc-json.sh       # headless PCB DRC as JSON (exit code is the gate)
│   ├── kicad-erc-json.sh       # headless schematic ERC as JSON (exit code is the gate)
│   └── install_mcps.sh         # legacy bash-only venv setup (macOS/Linux only —
│                                 # installer.js is the cross-platform replacement)
├── skills/                # the 6 skills above
├── HANDOFF_REVIEW.md      # verification dossier
└── README.md

Notes on portability

config/mcp/*.json and config/mcp/codex.toml are reference templates only — they contain the placeholder __INSTALL_DIR__, never a real machine path, and are not read by installer.js at install time (it generates configs dynamically from os.homedir() and its own install directory). They are resolved to a real path only by scripts/test_mcp_connection.sh, for local verification.