# Flamingo

Prompt-first PCB CAD for Claude Code. No schematic step: describe the board in plain language and Claude Code drives a custom TypeScript engine over MCP — picking real LCSC parts, placing footprints, wiring connectivity, autorouting with Freerouting, running DRC, and exporting a JLCPCB-ready fab package (gerbers.zip + bom.csv + cpl.csv). A live browser view shows the board update as it's built.

Features

• Prompt-first workflow over MCP — 39 tools cover the whole flow: parts → placement → nets → routing → DRC → fab export. No schematic step.
• Real parts — LCSC keyword search plus EasyEDA footprint fetch/parse with real pad numbers and geometry, cached locally under ~/.flamingo/parts/.
• Live browser editor — WebSocket-synced canvas view with selection and drag editing, a via tool (hover copper to inherit its net), silk text/line editing, board search, zone & label layer toggles, copper island tints, a nets panel showing each net's track width, a one-click Lock & Route button, and Run DRC with red canvas markers.
• 3D view + STEP export — interactive 3D board with real vendor component models, 3D silkscreen, and STEP export in two flavours: light courtyard blocks or full detail (copper, silk, drilled barrels).
• Autorouting — Freerouting integration with per-net routing, automatic thin-escape retry for fat nets that can't exit fine-pitch pads, a widen pass that necks down only at obstructions, and automatic GND stitching vias for orphaned pour islands.
• Copper features — zone pours with filled-copper connectivity, keepouts, mounting holes/slots, and per-net-class track width / clearance / via rules.
• DRC against JLCPCB capabilities — rulesets picked by layer count: clearance, track width, drill/annular/via minimums, copper-to-edge, keepouts, hole-to-hole, courtyard overlap, silk-over-pad, unconnected nets, and outline checks.
• Live stock check in DRC — every placed part is checked against JLCPCB's assembly parts library; out-of-stock parts gate export (waivable), low or unknown stock is reported as a non-gating advisory.
• Board-aware silkscreen — refdes labels are auto-placed on-board, pad-safe, and non-overlapping by a whole-board solver.
• Fab-ready export — Gerber X2 + Excellon drills, JLCPCB BOM/CPL, a reference render SVG, and a browser download zip shaped for direct upload to JLCPCB's order page.
• Op-log editing — every change is an operation with full undo/redo; boards are plain JSON files that diff cleanly in git.
• Agent-friendly feedback — PNG screenshots (with ratsnest and DRC overlays), text board summaries, and connection listings on demand.

Quick start

npm install
npm run build

# Serve a board (creates board.flamingo if it doesn't exist):
node packages/server/dist/cli.js serve board.flamingo
#   … or, once the server package is linked, `npx flamingo serve board.flamingo`

# Open the live view:
open http://localhost:4242

Point Claude Code at the running server by dropping this .mcp.json in your project (it's already at the repo root):

{
  "mcpServers": {
    "flamingo": { "type": "http", "url": "http://localhost:4242/mcp" }
  }
}

Now ask Claude Code to build a board — e.g. "make me a 2-layer ESP32-S3 breakout with USB-C power and a 3.3V LDO" — and watch the browser view fill in.

Requirements

• Node.js 22+
• A Java runtime (for the Freerouting autorouter). On macOS: brew install openjdk (keg-only — either add /opt/homebrew/opt/openjdk/bin to PATH or set JAVA_HOME). freerouting.jar is downloaded to ~/.flamingo/ on first autoroute.
• Network on first use, to fetch part footprints from the EasyEDA/LCSC API (cached under ~/.flamingo/parts/ afterward).

The workflow

prompt → parts → place → connect → route → drc → export

1. parts — parts_search (keyword) then parts_get (pad list) to choose real LCSC parts and learn their pin numbers.
2. place — new_board, set_board_outline, then place_component / move_component to lay out footprints (mm, y-up).
3. connect — connect_pins builds nets from REFDES.PAD pin refs; create_net_class / assign_net_class set track/via/clearance rules.
4. features — add_zone (copper pours), add_mounting_hole, add_silk_text, add_keepout.
5. route — autoroute runs Freerouting for bulk routing; add_track / add_via place surgical fixes by hand; get_ratsnest / unroute help iterate.
6. drc — run_drc reports violations against the JLCPCB ruleset for the board's layer count, and checks live JLCPCB assembly stock for every placed part: a part with less stock than one board needs is a gating stock-out violation; low stock (fewer than 100 boards buildable) and parts missing from the JLC library are non-gating advisories. Set FLAMINGO_STOCK_CHECK=off to skip the stock half (e.g. offline).
7. export — export_fab runs DRC (fills zones first, including the stock check) and writes the JLCPCB fileset — refusing on any violation unless waiveDrc is set.

screenshot renders the board to a PNG at any point so Claude can see what it's doing.

MCP tools

39 tools are served at http://localhost:4242/mcp:

Group	Tools
Board / project	new_board, open_board, import_board, save_board, get_board_state, describe_connections
Parts	parts_search, parts_get, datasheet_get
Placement	place_component, move_component, remove_component, set_component_label, set_component_silk, set_cpl_rotation, set_pad_paste
Connectivity	connect_pins, disconnect_pins, create_net_class, assign_net_class
Board features	set_board_outline, add_zone, add_keepout, add_mounting_hole, add_silk_text, add_silk_line, remove_item
Routing / analysis	add_track, add_via, get_ratsnest, autoroute, unroute, widen_tracks, run_drc
History	undo, redo
Output	export_fab, export_step, screenshot

Architecture

npm workspaces monorepo — all packages are ESM, strict TypeScript, tested with Vitest (packages/*/test/*.test.ts):

packages/
  engine/   pure library: data model, geometry, netlist/ratsnest, zone fill, DRC, ops
  parts/    LCSC search + EasyEDA footprint fetch/parse/cache
  fab/      Gerber X2 + Excellon writers, BOM/CPL writers, DSN export / SES import
  server/   Node: document host, op-log + undo/redo, HTTP + WebSocket, MCP endpoint, CLI, autoroute runner
  ui/       browser PCB view (Canvas 2D) with mouse editing tools

The server is the hub: it owns the live Doc (board + undo/redo), serves the ui at /, streams changes over /ws, and exposes every editing operation as an MCP tool at /mcp. Claude Code and the browser both act on the same board.

Development

npm run build   # tsc -p . in every package (+ vite build for the ui)
npm test        # vitest run in every package

The full prompt→fab pipeline is exercised for real (live LCSC parts, real Freerouting) by:

npx tsx packages/server/scripts/e2e-esp32.ts

which builds the reference board above, asserts a DRC-clean export, and tracespace-validates every Gerber.

License

MIT — see LICENSE.