Metadata-Version: 2.4
Name: b123d-print
Version: 0.3.1
Summary: Design, check and export 3D-printable parts with build123d, from any LLM via MCP
Keywords: cad,3d-printing,build123d,mcp,llm
Author: KD5RYN, b123d-print contributors
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY.md
Requires-Dist: build123d==0.13.0
Requires-Dist: matplotlib==3.11.2
Requires-Dist: mcp==2.3.0
Requires-Dist: numpy==2.5.4
Requires-Dist: scipy==1.18.1
Requires-Python: ==3.12.*
Project-URL: Documentation, https://kd5ryn.github.io/b123d-print/
Project-URL: Source, https://github.com/KD5RYN/b123d-print
Project-URL: Issues, https://github.com/KD5RYN/b123d-print/issues
Project-URL: Changelog, https://github.com/KD5RYN/b123d-print/blob/main/CHANGELOG.md
Project-URL: Releases, https://github.com/KD5RYN/b123d-print/releases
Description-Content-Type: text/markdown

# b123d-print

[![PyPI](https://img.shields.io/pypi/v/b123d-print.svg)](https://pypi.org/project/b123d-print/)
[![CI](https://github.com/KD5RYN/b123d-print/actions/workflows/ci.yml/badge.svg)](https://github.com/KD5RYN/b123d-print/actions/workflows/ci.yml)
[![Docs](https://github.com/KD5RYN/b123d-print/actions/workflows/docs.yml/badge.svg)](https://kd5ryn.github.io/b123d-print/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Vibe CAD for 3D printing.** Tell your AI assistant what you need, in plain words, with a
photo and a few caliper readings. It designs the part, looks at it from every side, checks it
for printing problems and hands you a file for your slicer. No CAD skills needed, and it works
with any assistant that supports MCP: Claude, Gemini CLI, Cursor, VS Code Copilot, Codex and
more.

## What you can make

Ask the way you would ask a friend who owns calipers and a CAD program. These were designed
this way, and printed:

- *"A box for this IR blaster board: the LED pointing out the top, a screw-on lid, two tabs to
  mount it on the wall."* A two-part case, checked against a stand-in of the board so it fits.
- *"An outdoor case for this motion sensor. It should slide off a wall plate and keep the rain
  out."* Dovetail rails, a click-in detent, a drain slot, and a cover that prints without
  supports.
- *"An adapter plate: 2-gang box behind, 1-gang smart switch in front."* Counterbored screw
  holes, and a wall check added after the first print broke through a 0.05 mm skin no render
  showed.

Or [remix](https://kd5ryn.github.io/b123d-print/using/remix/) a model you downloaded (STL, 3MF or STEP) and change it:

- *"Here's an L bracket STL I downloaded: turn its two mounting holes into slots and add
  gussets."* The original is loaded as a solid and changed, the checks tell the original's
  flaws from new ones, and a before/after view shows exactly what moved. (A demo for the docs,
  not printed yet.)

And the everyday things: a spacer, a knob, a bracket, a cable clip, a replacement for a broken
part you can measure. Then keep talking to it: *"make it 5 mm taller"*, *"add a hole for an M4
screw"*, *"the lid is too tight"*. Every dimension stays a named number in a short
[build123d](https://github.com/gumyr/build123d) script, so each change is exact, and you get
STEP files to keep editing in other CAD if you want.

| | |
| --- | --- |
| ![ESP IR blaster box, assembly with board stand-ins](docs/images/esp_ir_blaster_assembly.png) | ![Section through the LED: base, lid, board and LED stand-ins](docs/images/esp_ir_blaster_xz0.6.png) |
| *Two-part box for an IR transceiver board, with the board stand-ins* | *Section through the LED: lid cone, board, clearances* |
| ![Outdoor motion sensor case, arch cover](docs/images/tuya_motion_sensor_outdoor_case_arch_assembly.png) | ![Wall plate section through the counterbores](docs/images/plate_2gang_to_1gang_xy2.45.png) |
| *Outdoor sensor case: dovetail back plate + support-free cover* | *Wall plate: section just past the face, where the wall check looks* |
| ![Remix: the downloaded L bracket and the version with slots and gussets](docs/images/remix_bracket_before_after.png) | ![Remix: the original colored where the remix differs](docs/images/remix_bracket_vs_original.png) |
| *Remix: a downloaded bracket, before and after* | *Where the remix differs: red cut, grey added* |

**Documentation: https://kd5ryn.github.io/b123d-print/**

## Get started in 2 minutes

b123d-print's MCP server is a plug-in that gives your AI assistant CAD tools. It runs on your
own computer.

**The easy way:** paste this into your AI assistant (Claude Code, Claude Desktop, Cursor,
Gemini CLI, Codex, …):

```text
Install the b123d-print MCP server for me. It runs with
`uvx --from b123d-print b123d-print-mcp --workspace <folder>`
where <folder> is a folder for my parts, such as ~/parts.
Install uv first if it is missing (https://docs.astral.sh/uv/).
Add the server to your MCP settings, tell me when to restart you,
and after the restart check that its tools (list_parts, new_part,
build_part, ...) are available.
```

It will probably ask to run a few commands (to install uv and add the server): that is expected.

**By hand:**

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), which fetches Python
   and everything else b123d-print needs.
2. Add the server. Claude Code:

   ```bash
   claude mcp add b123d-print -- uvx --from b123d-print b123d-print-mcp --workspace ~/parts
   ```

   Claude Desktop (Settings → Developer → Edit Config):

   ```json
   {
     "mcpServers": {
       "b123d-print": {
         "command": "uvx",
         "args": ["--from", "b123d-print", "b123d-print-mcp", "--workspace", "/Users/you/parts"]
       }
     }
   }
   ```

   Cursor, VS Code, Gemini CLI, Codex and others: [Connect your MCP client](https://kd5ryn.github.io/b123d-print/getting-started/mcp-clients/).
3. Restart the assistant.

**Then ask:** *"Design a 40 mm round spacer, 10 mm tall, with an M3 hole."* The files land in
your parts folder under `parts/<name>/out/`, ready for your slicer. The first start downloads a
few hundred MB and can take a few minutes ([Troubleshooting](https://kd5ryn.github.io/b123d-print/troubleshooting/)).
The assistant checks its work by looking at its renders, so use a client that passes tool
images to the model (Claude Desktop and Claude Code do).

**Scope: parts for FDM 3D printing, nothing else.** Everything is built around a printed part:
print orientation with the bed at Z=0, hole compensation, mating clearance, calibration coupons,
and print checks built on [sourced FDM design rules](https://kd5ryn.github.io/b123d-print/BEST_PRACTICES/).
It is not a general CAD framework.

## What's in it

- **`b123d-print` package + CLI** — export, 6-view renders, colored multi-part cross-sections,
  and print checks: **overlap** between mating parts, **overhang** and **bridges** in print
  orientation, **thin features** and **wall thickness** around cuts, **holes** (round tops that
  sag), **bed-edge** fillets, **gaps** between moving parts, **probes** ("is the roof closed?").
- **`b123d-print-mcp`** — an [MCP](https://modelcontextprotocol.io) server, so it works from
  Claude Desktop, Claude Code, Gemini CLI, Cursor, VS Code, Codex and other MCP clients. Part
  scripts are model-written code: they run in a sandbox with a timeout and no network.
- **`compare`** — measure a part against a reference STL, 3MF or STEP: size, volume and surface
  differences, a 0–100 score, pass/fail, and a deviation view
  ([comparing parts](https://kd5ryn.github.io/b123d-print/using/compare/)).
- **Remix** — start from someone else's STL, 3MF or STEP: `import_model` makes a mesh a solid
  (coplanar triangles merged), the checks tell the original's problems from the ones the remix
  added, and a before/after view shows the change
  ([remixing a part](https://kd5ryn.github.io/b123d-print/using/remix/)).
- **Design review** — after the print checks pass, the assistant reviews the part for a style
  you pick (functional, modern, least cost, rugged/outdoor, soft/handheld): rough filament and
  time estimates, supports, edge treatment, layer steps, water traps, and concrete suggestions
  from [sourced design rules](https://kd5ryn.github.io/b123d-print/DESIGN_GUIDE/). It changes
  nothing without your OK ([design review](https://kd5ryn.github.io/b123d-print/using/design-review/)).
- **The workflow, model-neutral** — MCP prompts plus an [`AGENTS.md`](AGENTS.md) any agent can
  read. The rules come from real prints; one exists because a part broke through a 0.05 mm skin
  that no render showed.
- **Examples** — four parts designed this way and printed, plus calibration coupons for holes,
  fits, and overhangs and bridges, in
  [`src/b123d_print/examples/`](src/b123d_print/examples/).

## Advanced: run it on another machine

Not needed for most people. To keep the parts on a home server and design from a laptop, use
[SSH](https://kd5ryn.github.io/b123d-print/getting-started/ssh/); for many agents sharing one server (eval runs, a team),
[HTTP](https://kd5ryn.github.io/b123d-print/getting-started/http/) with a named token per tool; for the strongest isolation
(also on Windows), [Docker](https://kd5ryn.github.io/b123d-print/getting-started/docker/).
[Which mode?](https://kd5ryn.github.io/b123d-print/advanced/) compares them.

## Documentation

| | |
| --- | --- |
| **Getting started** | [Quick start](https://kd5ryn.github.io/b123d-print/getting-started/quick-start/) · [MCP clients](https://kd5ryn.github.io/b123d-print/getting-started/mcp-clients/) (Claude Desktop, Claude Code, Gemini CLI, Cursor, VS Code, Codex) · [CLI and Python](https://kd5ryn.github.io/b123d-print/getting-started/cli/) |
| **Advanced** | [Which mode?](https://kd5ryn.github.io/b123d-print/advanced/) · [Remote over SSH](https://kd5ryn.github.io/b123d-print/getting-started/ssh/) · [Over the network (HTTP)](https://kd5ryn.github.io/b123d-print/getting-started/http/) · [Docker](https://kd5ryn.github.io/b123d-print/getting-started/docker/) |
| **Using it** | [How a session goes](https://kd5ryn.github.io/b123d-print/using/workflow/) · [MCP tools and prompts](https://kd5ryn.github.io/b123d-print/using/tools/) · [Output formats](https://kd5ryn.github.io/b123d-print/using/formats/) · [Settings](https://kd5ryn.github.io/b123d-print/using/settings/) · [Hole compensation](https://kd5ryn.github.io/b123d-print/using/hole-compensation/) · [Printer profiles](https://kd5ryn.github.io/b123d-print/using/printer-profiles/) · [The checks](https://kd5ryn.github.io/b123d-print/using/checks/) · [Sandbox](https://kd5ryn.github.io/b123d-print/using/sandbox/) · [Comparing parts](https://kd5ryn.github.io/b123d-print/using/compare/) · [Remixing a part](https://kd5ryn.github.io/b123d-print/using/remix/) |
| **Part scripts** | [The part script](https://kd5ryn.github.io/b123d-print/scripts/convention/) · [Checks API](https://kd5ryn.github.io/b123d-print/scripts/checks-api/) · [Examples](https://kd5ryn.github.io/b123d-print/scripts/examples/) · [Workflow rules](https://kd5ryn.github.io/b123d-print/scripts/rules/) · [Design rules (sourced)](https://kd5ryn.github.io/b123d-print/BEST_PRACTICES/) |
| **More** | [Reference](https://kd5ryn.github.io/b123d-print/reference/) · [Updating](https://kd5ryn.github.io/b123d-print/updating/) · [Troubleshooting](https://kd5ryn.github.io/b123d-print/troubleshooting/) · [Contributing](CONTRIBUTING.md) · [Agent evals](https://kd5ryn.github.io/b123d-print/contributing/evals/) · [Credits and licenses](https://kd5ryn.github.io/b123d-print/credits/) |

## Status

**0.x — early.** The part-script convention may still change. CI tests macOS, Ubuntu and
Windows, the built package via `uvx`, and the Docker image on every push. On Windows the server
runs natively for local use, but without an OS sandbox (process isolation and an audit hook
only); use WSL2 or Docker for isolation. SSH mode's server side is macOS and Linux only; Windows
works as an SSH or HTTP client. [Platforms and status](https://kd5ryn.github.io/b123d-print/#platforms-and-status).

## Credits and license

b123d-print is a thin layer over [build123d](https://github.com/gumyr/build123d),
[Open CASCADE Technology](https://dev.opencascade.org) (via [OCP](https://github.com/CadQuery/OCP)),
[lib3mf](https://github.com/3MFConsortium/lib3mf), [OrcaSlicer](https://github.com/SoftFever/OrcaSlicer)'s
printer data, [matplotlib](https://matplotlib.org), [NumPy](https://numpy.org), the
[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) and [uv](https://github.com/astral-sh/uv).
Details and redistribution notes: [THIRD_PARTY.md](THIRD_PARTY.md).

[MIT](LICENSE) © KD5RYN and contributors.
