build123d MCP

Recognise hole patterns on a session object (defaults to current shape): ≥3 identical-spec holes equally spaced on a circle → bolt_circle (center, diameter/BCD), collinear at constant pitch → linear_array (pitch, direction). Returns JSON: {count, patterns: [{type, holes: [HoleFeature records], center/diameter | pitch/direction}]}. Each hole belongs to at most one pattern; make_drawing already annotates these automatically.

Recognise drilled holes on a session object (defaults to current shape). Coaxial internal cylinders are grouped into one record per hole: drill + counterbore + spotface stacks, keyway-split bores, and bores interrupted by crossing holes all count once. Returns JSON: {count, holes: [{axis (drilling direction, unit vector), location (opening point), diameter, depth (bore top to deep end; drill-point cone excluded), bottom: through|flat|drill_point|unknown, cbore: {diameter, depth}|null, spotface: {diameter, depth}|null}]}. Countersinks read as openings (not steps); threads and non-cylindrical fe…

Verify that render and export dependencies are working. Tests PNG render (VTK), SVG render (build123d HLR), STEP export, and STL export with a trivial shape. Returns JSON with ok/error per capability. Run at session start if you suspect a missing dependency.

Import a STEP (.step/.stp), STL (.stl), or 3MF (.3mf) file as a named object in the session. path: absolute or relative path to the file. name: name to register the shape under (defaults to the filename stem). The shape becomes both the named object and the current_shape. A multi-object 3MF registers an aggregate under name plus each member as name_1, name_2, etc.; the result includes per-member topology summaries. After importing, use render_view() to visualise the shape, measure() for geometry queries, or compare(a='imported', b='model', kind='shape') to diff against a show() object. Note: S…

DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Structured bbox and annotation report for a 2D drawing. Two modes: 1. Session mode (default): inspects objects registered via annotate()/show(). Returns per-object bounding boxes, face/edge counts, annotation metadata (label string, measured length, Leader tip/elbow), and structural lint. 2. SVG mode (svg_path set): parses an SVG file from disk and reports page size, layer ids, text content + positions, and element counts. Decouples inspection from the build-…

Return one compact generation-checkpoint inventory: bbox, solid/topology counts, holes grouped by axis/diameter/depth/bottom, bosses grouped by axis/diameter/height, recognised patterns with member counts, and a cross-section area profile. expected is an optional JSON object derived from the drawing/spec; supported keys are bbox [x,y,z], solid_count, holes/bosses/patterns group lists, section_varying, and tolerance. Pattern groups can check type, diameter, pitch, direction, center, member_count, and member_diameter. A supplied feature category is an exact inventory: unexpected or ambiguously m…

Copy a b123d workflow skill into the current project. Writes the appropriate config file for the requested agent so the step-by-step workflow is available in future sessions. skill: which workflow to install (default "modeling") - drawing → DEPRECATED; still installs, but drawing generation has moved to draftwright, which publishes its own skill (#465) - modeling → build 3D parts/assemblies (incl. from technical drawings) - edit → modify existing build123d code and verify geometry deltas - repair → repair a solid that fails the validity gate target: one of …

Suggest planar mounting faces from recognised hole openings, with exact hole handles. These are geometric candidates, not a declaration of design intent. Pass chosen hole handles as protected_refs to edit_feature(); that edit also checks every other recognised hole and the outer envelope.

Return details of the last failed execute() call: exception type, message, and (for runtime and syntax errors) line number and a 5-line excerpt around the failing line. Security errors include a message but no line/excerpt. Returns {"error": null} if the last execute() succeeded or no execute() has failed yet. Call this immediately after an execute() error to get the exact failing line — much faster than re-reading the submitted code.

DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Run structural drawing-quality checks and return JSON {violations: [...]}. Session mode (default): reconstructs the session's annotations and delegates to build123d-drafting-helpers (lint_drawing + find_interferences) — single source of truth. Surfaces label-vs-measured divergence (axis swap), Leader line through its own label, annotation/label overlap, a witness/extension line piercing a neighbour's label, redundant collinear lines, and page-bounds overshoot. SVG mode (s…

Report how many CAD sessions this server process is holding, its configured limit, and how long each has been idle. Handles are secrets and are never returned. Operator/diagnostic tool for HTTP deployments — over stdio there is always exactly one session.

Load a named part from the library into the session. name: part name from search_library. params: optional JSON object of parameter overrides e.g. '{"od": 8.0, "length": 20.0}' — unspecified params use their defaults. The part is registered as a named object and becomes current_shape.

Report WHERE a solid fails the validity gate, with 3D coordinates — so you can fix the exact edge/face instead of guessing. validate()/export() tell you WHAT is wrong (e.g. "1 non-manifold edge", "BRepCheck failed") but not where; call this when validate() FAILs to get a per-defect list: brep_invalid_face (face index + center + BRepCheck status, e.g. an unorientable BSpline), open_edge / nonmanifold_edge (B-rep edge midpoint + faces_incident), the mesh self-touches strict CAD/mesh consumers reject — mesh_nonmanifold_edge (edge midpoint) and mesh_nonmanifold_vertex (corner-to-corner touch point…

Measure a shape and return a complete geometric summary: volume (mm³), surface area (mm²), topology (face/edge/vertex counts), bounding box with per-axis size and center, volumetric center of mass, 6-component inertia tensor (Ixx/Iyy/Izz/Ixy/Ixz/Iyz), and a face-type inventory classifying every face as Plane/Cylinder/Cone/Sphere/Torus/BSpline with area and type-specific params (e.g. cylinder diameter and axis); identical faces are collapsed with a count, non-analytic sliver faces folded into one summary line. Prefer measure over render_view for verifying geometry — numbers are unambiguous. top…

Find fastener holes in a MESH by slicing it on all three axes. Returns JSON {count, holes:[{axis, diameter, location, span, depth, through}]} where axis is the drilling direction and location is the hole centre in world coordinates. This is the mesh counterpart to find_holes(), which needs real topology and returns nothing for an imported STL - the usual case when remixing a downloaded model and you need its existing mounting features before designing a part that bolts on. Read `depth` and `through`: a blind pocket a few mm deep is a heat-set insert seat, not a screw hole, and coaxial pockets …

Loops on one cross-section plane of a mesh, largest first. Returns JSON {axis, position, loop_count, enclosed_passages, loops:[{points, center, size, min, max, enclosed}]}, all in the two axes that are not `axis`. enclosed_passages counts loops at odd nesting depth, representing passages through material at this height. An open groove reads 0. Works on imported STL shells and solids. axis: X, Y or Z (the plane normal). position: absolute world coordinate. tolerance: tessellation tolerance. weld: point-merge distance when chaining segments. object_name: named object from show()/import_cad_file …

Prepare a raster engineering drawing for efficient inspection. Detects substantial spatial regions, saves one labelled overview plus readable PNG crops, and returns their pixel bounding boxes and paths. Region ids are layout evidence only: this tool does NOT label views, recognise CAD features, interpret lines, infer dimensions, or trace geometry. Use it once near the start instead of repeatedly writing shell/PIL crop scripts; inspect the returned overview and only the relevant crops. Printed dimensions remain authoritative. image_path: PNG/JPEG/TIFF drawing under an allowed read root. output_…

Run the shared quiddity inventory once and return exact, run-local edit evidence. With families='' the response is a compact inventory and targetable-family count; pass comma-separated families such as 'holes,bosses,blends' for structured records and @feature handles. Returned handles are usable inside execute() as recognition_faces(handle), or recognition_faces(handle, role='defining'), and fail if their source geometry has been replaced. coordinate_frame='caller' (default) preserves the imported model coordinates used by edit instructions; 'part' uses a rigid-equivariant part-relative frame …

DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Rasterise an existing SVG file to PNG via resvg-py. Complements render_view (which takes build123d shapes from the live session) by accepting an SVG written outside the sandbox — typically by a short Python script that does the ExportSVG call directly. The PNG is returned inline so the LLM can see the drawing without you having to open the file in another tool. Args: svg_path: path to an SVG file on disk. width: output pixel width (default 1200); height set by SVG…

Render model. Auto-detects 3D vs 2D: solids use VTK; flat drawings use the 2D pipeline. Renders confirm appearance, not geometry. format: png, svg, dxf, or both. direction accepts top, bottom, front, rear, side, left, right, or iso. quality: preview, standard, or high; a timed-out standard/high PNG automatically retries once as a coarse preview. azimuth/elevation apply after the preset. objects selects comma-separated registered names. clip_plane: x/y/z. save_to writes the result. mode: auto/2d/3d. label_objects and highlights add PNG labels; colors controls object/layer colours.

Return structured, field-proven repair/edit recipes for an agent to implement explicitly in execute(). Unlike repair_hints(), which gives short error-specific tips, this emits a sequenced plan with code-pattern names, acceptance checks, and stop conditions. Provide the full validate()/export()/last_error() text as error_text, the intended edit as goal, and any extra notes from locate_gate_defects()/compare(a='before', b='after', kind='shape') as context. The tool is read-only and does not mutate geometry.

Given an error message or validity-gate reason, return targeted fix suggestions for common build123d mistakes and gate failures: wrong Location syntax, missing .part, CadQuery idioms, blocked imports, degenerate boolean results, fillet edge selection, B-rep defects, mesh non-manifold/open-edge failures, and more. Pass the full error string from execute(), last_error(), validate(), or export().

Clear the current session back to empty state, including all snapshots.

Evaluate a selector expression against a named object and return a geometry descriptor. selector is a Python expression suffix applied to the object, e.g. '.faces().filter_by(Axis.Z).last()'. If label is given, the descriptor is stored in session.geometry_refs[label] and appears in session_state(). Returns JSON: {label, ref, object, selector, type, geom_type, area/length, center}. center is the entity's true centre — the arc centre for a circular/elliptical edge, the area centroid otherwise — not the parametric midpoint, which for a circle or cylinder lies ON the entity a radius from its axis.…

Restore geometric state from a previously saved snapshot (current_shape and the show() registry). The Python variable namespace is NOT restored — execute() calls made after the snapshot are still in scope, but current_shape and all show() objects revert to what they were at snapshot time. Raises an error if the snapshot name does not exist.

DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Write a .dims.json sidecar file alongside an SVG with label metadata. build123d renders Text as filled glyph paths, not <text> SVG elements, so label strings are irrecoverable from a finished SVG. Call this tool after completing a drawing (annotate all dims/leaders with annotate()) and before or after exporting the SVG. The sidecar is read automatically by inspect_drawing(svg_path=...) to restore annotation content. Workflow: 1. Build your drawing with Dimension / Lea…

Save a named checkpoint of the current geometric state (current_shape and the show() object registry). The Python variable namespace is NOT saved — only geometry. Call this before risky experiments so you can restore known-good geometry without re-running all prior execute() calls.

Return a single Python script assembled from all successfully executed code blocks in this session. Prepends 'from build123d import *' if not already present. If save_to is given, writes the script to that path and returns {script_path, blocks}; otherwise returns {script, blocks}. Useful for exporting a reproducible script after an interactive session.

Search the part library. query: keywords matched against name, description, tags, category (empty returns all). Returns name, category, description, tags, and full parameter specs including types, defaults, and descriptions.

Return a structured JSON snapshot of the current session: current_shape metrics, all named objects (replaces list_objects) with geometry stats, snapshot names, and a variables summary of the Python namespace (type + volume for shapes, type + length for collections, type + value for scalars). Use this to orient after a reset, restore, or multi-step build to confirm what geometry and variables are active.

Draft a starter design-intent spec from the current (or named) shape, so you can edit detected values instead of authoring a verify_spec spec from scratch. Introspects the shape with the same primitives verify_spec checks against — bounding box (→ envelope_mm), the validity gate (→ solid), volume, feature recognition (→ hole/hole_pattern/boss features), and top-level numeric parameters — and returns JSON {spec, note}. The `spec` describes what was BUILT (envelope/volume use a ±2% band, parameters ±10% — editable defaults); review and edit each value against your intended drawing, then pass the…

DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Auto-calculate safe VIEW_X / VIEW_Y positions for a multi-view engineering drawing. Measures the named shape's bounding box and returns per-view page positions (VIEW_X, VIEW_Y), look_at values, and camera/up vectors for a standard third-angle layout: [plan ] [ ] [front] [ side ] [ iso ] [ title block (bottom-right) ] Returns JSON with: views: {name: {VIEW_X, VIEW_Y, half_w, half_h, look_at, camera, up}} free_space: {name: {above/b…

Check whether a shape would pass a CAD validity gate before exporting it. Returns a PASS/FAIL verdict plus JSON (passes_gate, n_solids, volume, is_manifold, brep_valid, reasons). The gate mirrors what strict CAD and mesh consumers require: a well-formed (BRepCheck), watertight, manifold solid with non-zero volume. A FAIL means a STEP/STL export would be rejected outright — common causes are a leftover 2D sketch or open shell as the current shape, an un-fused compound, or a degenerate boolean result. Run this immediately before export() on any part you intend to submit or hand off. object_name:…

Verify the built solid against a declared design-intent spec — did you build what was requested? Checks requested features/constraints against the actual geometry and returns an evidence-tiered conformance report; unlike validate() (is the solid valid?) this answers requested-vs-built. Provide the spec as inline JSON (spec=) or a .json file path (spec_path=). Supported spec keys: envelope_mm {x/y/z:[lo,hi]} (bbox size in range), solid {count, valid}, volume_mm3 {min,max}, features:[{kind:"hole_pattern",pattern:"bolt_circle"|"linear_array",holes,bcd_mm|pitch_mm,diameter_mm} | {kind:"hole",count…

Return the installed versions of the build123d-mcp server, its key dependencies (build123d, build123d-drafting-helpers), and the companion packages importable inside execute() (bd_warehouse for threads/fasteners/gears/bearings, augura for printability analysis). Use this to confirm which server build is running — e.g. to check whether a feature or fix is present, or whether the client is talking to a stale install.

DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Return the world→page axis mapping for a project_to_viewport call, computed analytically (no projection performed). Use this BEFORE rendering a projected view to confirm which world axis ends up on which page axis and with what sign — catches bottom-view/side-view axis swaps before they show up in the render. Returns JSON like {"world_X": ["page_X", -1.0], "world_Y": ["page_Y", 1.0], "world_Z": ["depth", 0.0]} — for a bottom-view origin (0,0,-100), world-X flips to negativ…

Return guidance on how to use these tools effectively. Call this at the start of a session or whenever unsure which tool to reach for.