build123d-mcp

# build123d-mcp

[![PyPI version](https://img.shields.io/pypi/v/build123d-mcp)](https://pypi.org/project/build123d-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/build123d-mcp)](https://pypi.org/project/build123d-mcp/)
[![CI](https://github.com/pzfreo/build123d-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pzfreo/build123d-mcp/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![build123d-mcp MCP server](https://glama.ai/mcp/servers/pzfreo/build123d-mcp/badges/score.svg)](https://glama.ai/mcp/servers/pzfreo/build123d-mcp)

An MCP (Model Context Protocol) server that exposes build123d CAD operations as tools, enabling AI assistants to build, inspect, and iterate on 3D geometry interactively.

## Why

When using an AI to write build123d scripts, the AI writes blind — it cannot see the geometry it produces. This server closes the feedback loop: the AI can create geometry, render views, query dimensions, and catch errors incrementally rather than writing complete scripts and hoping they are correct.

## Tools

**Core**
- `execute` — run build123d Python code in a persistent session; use `show(shape, name)` to register named parts
- `reset` — clear session back to empty state (namespace, shapes, snapshots)

**Geometry inspection**
- `measure` — full geometric summary: volume, area, topology, bounding box, centre of mass, inertia tensor, face-type inventory
- `clearance` — minimum distance (mm) between two named shapes
- `cross_sections` — cross-sectional areas at evenly spaced planes along X/Y/Z; useful for detecting voids and wall-thickness variation
- `resolve` — evaluate a selector expression (e.g. `.faces().filter_by(Axis.Z).last()`) against a named object and return a geometry descriptor
- `find_holes` / `find_bosses` / `find_hole_patterns` — feature recognition: coaxial drill + counterbore + spotface stacks as one hole record (axis, location, diameter, depth, bottom: through/flat/drill_point/unknown), external bosses with height, bolt-circle and linear-array patterns
- `analyze_printability` — BREP-exact FDM printability analysis: overhangs, thin walls, minimum features, bed fit, tip-over risk
- `session_state` — full JSON snapshot of active shapes, named objects, snapshot names, and Python namespace variables
- `last_error` — details of the last failed `execute()`: type, message, line number, and code excerpt

**Viewing**
- `render_view` — render one or more shapes as PNG / SVG / DXF; auto-detects 3D vs 2D inputs (composed dimensioned drawings via `build123d.drafting` rasterise via ezdxf+matplotlib); supports assembly compositing, high-quality tessellation, cross-section clip planes, and optional labels for named shapes or specific faces/edges

**Engineering drawings**
- `suggest_view_layout` — auto-calculate safe page positions for a standard multi-view drawing layout
- `view_axes` — world-to-page axis mapping for a projected view, computed analytically before rendering
- `render_drawing` — rasterise an SVG file from disk to PNG
- `inspect_drawing` — structured bbox/annotation report for a 2D drawing (session objects or an SVG on disk)
- `lint_drawing` — structural drawing-quality checks: label/geometry divergence, overlapping annotations, page overshoot
- `save_drawing_annotations` — write a `.dims.json` sidecar capturing label metadata alongside an exported SVG

**Import / export**
- `export` — export as STEP / STL / DXF / SVG (or comma-separated like `step,stl`); auto-detects 2D vs 3D shape and routes to the appropriate format; targets a named object, the current shape, or `*` for all objects as an assembly
- `import_cad_file` — load a STEP or STL file as a named object for comparison

**Comparison**
- `shape_compare` — compare two named shapes by volume, bbox, topology, and centre offset
- `align_check` — check alignment between two named objects along an axis (flush / center / clearance modes)

**Session checkpoints**
- `save_snapshot` / `restore_snapshot` / `diff_snapshot` — checkpoint, recover, and compare geometric state

**Part library** *(requires `--library` flag)*
- `search_library` — search the part library by keyword; returns full parameter specs
- `load_part` — load a named part with optional parameter overrides

**Utility**
- `version` — return the server version
- `health_check` — verify VTK/SVG/STEP/STL dependencies work end-to-end
- `repair_hints` — get targeted fix suggestions for a given `execute()` error message
- `workflow_hints` — guidance on using the tools effectively
- `script` — assemble a reproducible Python script from the session's executed code blocks
- `install_skill` — copy a b123d workflow skill (modeling or drawing) into the current project

## Resources

Read-only MCP resources available to LLM clients:

- `build123d://quickref` — build123d API quick reference (primitives, booleans, positioning, selectors, fillets)
- `build123d://selectors` — task-indexed selector cookbook (get the top face, find circular edges, filter by area/length/radius, `Select.LAST` in builder context, fillet detection)
- `build123d://drafting` — code-first 2D engineering drawings cookbook (project a 3D part, dimension with ExtensionLine/DimensionLine, tolerances, hole-table pattern, multi-view sheet, title block, export to DXF)
- `build123d://drafting-api` — API reference for build123d-drafting-helpers, generated from the installed library (exact signatures for Dimension, Leader, TitleBlock, Drawing, and every other public symbol)
- `build123d://session` — live session state as JSON (current shape, named objects, snapshots, variables)
- `build123d://bd_warehouse` — catalogue of pre-built parametric parts from bd_warehouse (bearings, fasteners, gears, pipes, threads, and more)

> **build123d version**: examples in `quickref` and `selectors` are tested against build123d 0.10.x (soft-pinned in `pyproject.toml` as `>=0.10,<0.11`). The exact installed version is reported at the top of each resource. If you need a different build123d version, override the dependency and verify the examples still match the API.

## Prompts

- `start-cad-session` — primes a new CAD design session with the task description and step-by-step workflow reminders

See [llms.md](llms.md) for full tool reference and usage patterns.

## Recommended workflow

Build complexity falls into two tiers and the right approach differs between them.

**Simple shapes** (a few primitives, up to ~5 booleans): build entirely in `execute()`.

**Complex shapes** (IsoThread, multi-body fillets, high face counts): the `execute()` timeout (default 120 s) is a hard ceiling. The efficient pattern is:

1. **Probe** in the MCP — small `execute()` calls to discover API signatures, size strings, and face counts. Use `dir()` and `import inspect; inspect.signature(ClassName)` freely.
2. **Build** in a Python script — run it with Bash (or your shell). No timeout, full Python.
3. **Import and verify** in the MCP:
   ```
   import_cad_file("/path/to/part.step", "part")
   measure("part")          # verify volume, topology, bounding box
   render_view(objects="part")  # visualise
   ```

> **Timeout note:** the default is 120 s. Raise it with `--exec-timeout N` or `BUILD123D_EXEC_TIMEOUT=N`. When a timeout fires, all session state is lost (worker is restarted) — you must re-run any setup code.

> **Sandboxed-host note:** if every `execute()` fails with "Worker process failed to start", your MCP host is likely blocking subprocess creation (seen with sandboxed hosts on Windows). Relaunch with `--in-process` or `BUILD123D_IN_PROCESS=1` — a degraded mode that runs the CAD session inside the server process: no crash containment, no operation timeouts.

> **Import note:** after `import_cad_file()` the shape is a named session object. Always render it by name (`objects="part"`) when other shapes from the same build are also in session — two co-located shapes cause Z-fighting (striped colour artifacts). STL imports produce a shell (volume = 0); `render_view` and `measure` work, but `clearance()` and boolean operations require a solid.

## bd_warehouse fasteners

bd_warehouse is a full fastener system, not just a thread library. Always:

1. **Probe sizes first** (correct string format is `"M6-1"` not `"M6-1.0"`):
   ```python
   from bd_warehouse.fastener import CounterSunkScrew
   print(CounterSunkScrew.sizes("iso10642"))
   ```
2. **Instantiate the fastener object**, then pass it to the hole operation — never compute head geometry or tap-drill diameters manually:
   ```python
   from bd_warehouse.fastener import CounterSunkScrew, CounterSinkHole, TapHole
   screw = CounterSunkScrew(size="M6-1", fastener_type="iso10642", length=10)

   with BuildPart() as wheel:
       Cylinder(radius=20, height=10)
       CounterSinkHole(fastener=screw, depth=10)   # countersunk through-hole
       TapHole(fastener=screw, depth=8)             # tapped bore
   ```

See `build123d://bd_warehouse` (MCP resource) for the full catalogue and usage patterns.

## Security

Unlike CAD MCP servers that simply `exec()` user code, build123d-mcp ships with **defence-in-depth sandboxing** so the server is reasonable to expose to LLM-generated and untrusted prompts. Three layers, all applied before user code runs:

1. **AST inspection** — rejects imports of anything outside the allowlist (`build123d`, `bd_warehouse`, `math`, `numpy`, `inspect`, plus the rest of the safe stdlib subset and a curated set of geometric OCP submodules), blocks `eval`/`exec`/`compile`/`open`, and refuses dunder attribute access (the most common Python sandbox-escape route).
2. **Restricted builtins** — the `__builtins__` exposed to user code has the dangerous functions removed and `__import__` rewrapped to enforce the same allowlist at runtime, so a payload that bypasses the AST check still hits the wall on import.
3. **Execution timeout** — wall-clock limit (default 120 s, `--exec-timeout N` to override) enforced via SIGALRM, wit