gerberize

Overview

gerberize is a Python package for agents that work on circuit boards. It has three entry points: a dependency-free command line tool, a stdio MCP server, and an optional FastAPI service with a web workspace. The local commands wrap KiCad for design rule checks, electrical rule checks, footprint and BOM checks, and Gerber, drill, position and BOM export. They also wrap ngspice for operating point, transient and AC analysis against explicit limits. AI coding agents wrote the code under my direction over five days, and the test suite is the main record of what it does.

The core design decision is one result contract. Every action command, including help and argument failures, prints a single JSON envelope with an ok flag, errors, warnings and data. An error carries a code, the component reference, a fix hint and a board position, so an agent can act on a failed check without parsing prose. Exit status is 0 or 1 to match. The MCP server exposes each command as a tool with the same schema, plus 13 optional PCB guide resources and 7 documentation resources that work offline.

The server side stores users, hashed API keys, uploads, jobs, quotes, orders and approvals through SQLAlchemy, with PostgreSQL in production and SQLite for local work. Uploaded CAD runs in an unprivileged worker container with a read-only root filesystem, an internal network and bounded temporary storage. Ordering is the most heavily guarded path. An order accepts only a stored quote ID, never a price from the client. Amounts are integer cents. A per-order cap and a monthly budget are required, retries reuse an idempotency key, and approvals are short-lived single-use tokens that an agent key cannot issue for itself.

The website is plain semantic HTML, CSS and JavaScript with no frontend framework and no build step. An earlier homepage used a procedural Three.js board that assembles itself: bare-board manufacturing, then staggered placement of the processor, connector and passives. A later version animates a real open hardware board converted from its published CAD, with attribution on the tool's own site. A separate outbound-only render worker takes a validated board model, runs a fixed Blender template and returns a 3840 x 2160 image, and never accepts a user script.

The goal is an agent taking a KiCad project to a paid, submitted fabrication order in under five minutes, and that has not been demonstrated against a real fabricator. What has run is a no-card test on a simple LED board: one simulated order, mock payment, and ten fabrication-email scenarios delivered over real mail and handled by the mailbox triage lane. Payment collection is implemented and fixture-tested only, and the package is not yet published to PyPI.

Specifications

• The command schema file defines 37 commands, each exposed as an MCP tool named gerberize_<command>.
• The full test suite recorded 1,231 passed and 9 skipped on 2 November 2026.
• The isolated acceptance harness covers 11 requirement groups, 23 application checks and 10 scenarios, with source hashes in its receipt.
• The repository has 128 commits between 29 October and 2 November 2026.
• In the no-card LED board test, all ten external-mail scenarios passed through a 90-second poller, with nine model responses and one forced fallback.
• The Linux worker image bundles KiCad 9.0.2 and ngspice 44.2; on the deployed stack a queued simulation completed in 2.02 seconds and a project validation in 4.06 seconds.
• The render worker produced a 3840 x 2160 board image end to end in 64.39 seconds in its acceptance run, with 68 component models resolved.
• The payment layer rejects live keys outright: only test-mode keys are accepted and every returned object must be marked as test mode.