Kernelcad

Use this when the goal is complex / production / enclosure / gearbox / robot-arm / multi-body, or when you need evaluate→review/verify→revise until green. PREFERRED over one-shot evaluate_script+open_in_studio for Adam-level parts. Runs a CAD design loop over attempt scripts: review_cad each attempt, continue past functional attempts with unresolved warnings, return repair prompts (nextActionPrompt) plus structured revisionAssist (suggestedPatches / autoApplied.suggestedCode for repairable feature failures; cookbook steers for stacked-primitive toys). Stop on ok or convergence.escalate. To pic…

Use this when you need a manufacturability (DFM) report before printing or machining a part: returns a pass/fail checklist, no dfmSpec(...) needed. Pass { file | code } and optional processes (default ['fdm', 'cnc']). FDM 3D printing checks: fdm.overhangs (unsupported overhang steeper than max_overhang_deg, default 45° from vertical), fdm.bridging (bridges over max_bridge_mm, default 10), fdm.min-wall (walls under 2 × nozzle_mm, default 0.4 mm nozzle), fdm.min-hole (holes under 5 × nozzle), fdm.min-pin (warn), fdm.bed-fit (printer profile bed, default generic-fdm), fdm.bed-contact (warn). CNC …

Use this when you need to know WHAT MATERIAL changed between two versions of a model, not just how much. The deeper sibling of diff_scripts: a volume delta alone is ambiguous (a boss that grew and a pocket that deepened report the same magnitude, and a part that only moved reports zero), so this tool answers it with geometry instead of pixels. Baseline is { baseFile } or { baseCode }; the revised side is either another script ({ file } or { code }) or the SAME script re-lowered with { params } overrides — a bag of declared param() name -> new value, which is the one-script form a parameter swe…

Use this when you need to see exactly what changed between two script versions. Structured geometric delta between two versions of a kernelCAD script — a baseline ({ baseFile } or { baseCode }) and a revision ({ file } or { code }). Returns agent-readable JSON: per-part added/removed/renamed/changed (volume mm³ + exact bbox deltas, numbers matching inspect({ of: 'part-stats' })), total interference-volume delta with per-pair detail, mate-graph changes (added/removed/changed mates incl. type, connectors, pose, limits), and param changes (value/min/max). Single-shape scripts diff as one "(root)"…

Use this when the reference for a part is a 2D engineering drawing PDF (orthographic views with dimensions), not a photo. Deterministic, no vision model: reads the vector linework (stroke width, dash) and positioned text; classifies visible / hidden / center / dimension / extension lines; reads the title block scale, units and projection symbol; identifies front / top / side views by projection alignment (third- or first-angle); ties dimension text to its lines (⌀, R, 4×, ±, THRU, depth). Dimension values win over measured lengths. Rebuilds the part as the view silhouette extruded by the depth…

Use this when you need to run a script and check it compiles. Full local builds return viewerUrl: a live Studio link reused and updated on later full builds in the same MCP process. Hosted builds return viewerMode: hosted and viewerHint pointing to open_in_studio; they do not start a loopback viewer. Full evaluations return step evidence: build validity, volume and before/after local PNG paths in one shared iso frame. Snapshots require PW_CDP_URL for an existing browser; unavailable captures report an explicit error. Run a kernelCAD .kcad.ts script and report pass/fail + feature count + diagno…

Use this when you need to sample a signed-distance field at a point. Sample the signed distance from an in-script sdf.* field at a 3D point. Returns { distance, inside, aabb, kind }. Distance is in mm; negative = inside the surface, 0 = exactly on the surface, positive = outside. Use this to verify SDF composition before calling sdf.materialize (which is the expensive step). The script must bind the SdfField via sdf.bind('<name>', field) and pass that name as fieldName. Hint: pass either { file } or { code }, plus { fieldName, point: [x,y,z] }.

Use this when you need evaluate_script (and optionally open_in_studio) for an industry / cookbook demo in ONE step — after lookup_cookbook for industry demos, prefer execute_cookbook when you need evaluate+Studio together; empty lookup is not a stop (freehand-author instead). Resolves a cookbook snippet by `id` or BM25 `query` (same ranking as lookup_cookbook), evaluates its body via evaluate_script with bounded vendor timeouts, and returns explicit status with stage resolve|evaluate|open_in_studio. Pass openInStudio:true to publish the same script via open_in_studio after a green full evaluat…

Use this when you need an ordered exploded-view plan for an assembly. Supply parts as {name,center:[x,y,z],size:[x,y,z]} in mm. Optional assembly_order sets the sequence; missing order falls back to input part order, and unlisted/unknown order refs are reported. Choose mode axis (default) or radial; axis follows the requested direction, radial moves parts away from the assembly centroid. The result includes ready-to-paste param_declarations, animation_tracks and reverse_animation_tracks for animationView(), part_transforms for existing shapes, and script_fragment. cameraPlan gives framing guid…

Use this when you need to export geometry to a file. One exporter, selected by `target`: - target:'model' — export the script geometry to one file. Pass { file | code }, a required { output_path }, and { format }. Supported formats: stl (binary STL mesh), step (BREP CAD interchange), dxf (2D cut file for laser / waterjet / CNC: a flat part — plate, panel, extruded profile, in any orientation — exports its outline and holes in its own plane with exact arcs and circles; a sheet-metal part or a returned Region exports its flat pattern; a flat or sheet-metal part also returns sheet { thickness_mm,…

Use this when the user wants to get a part made: packages the fabrication files into one directory plus a zip, and returns links to public instant-quote pages. Pass { file | code } and output_dir; optional scope ('part', default — one script's files; 'bom' — the whole assembly's BOM: per-part single-body files, per-part drawings, bom.csv/json and vendor handoff texts), name (default 'part'), formats (default step, stl, 3mf, pdf-drawing, bom-csv; add 'dxf' for flat or sheet parts), and processes ('3d-print' | 'cnc' | 'sheet-cut') to filter the links (bom: also narrows which fabricated rows are …

Use this when you need a structural check's context without paying for a solve. Read-only: returns the stored summary of a previous run_fea (pass the same `output_dir`), whether the CalculiX + gmsh toolchain is available on this machine (with the install command when it is not; run_fea then uses its in-process voxel solver — toolchain.default_solver says which), and the FEA material table with real E / Poisson / yield numbers so a grade is chosen against data rather than from memory. Never meshes, solves, or writes.

Fetch one bundled catalog part. Prefer `await lib.standard.nema17()` and `await lib.standard.bearing608()` — they are offline and do not download remote STEP. A lookup that cannot finish fails within 45s with errorCode parts.lookup.timeout. Do not retry in parallel.

Search the bundled parts catalog (offline). For a NEMA-17 motor write `await lib.standard.nema17()`; for a 608 bearing write `await lib.standard.bearing608()`. Do not fan out parallel lookups and do not pass partsBaseUrl unless you set source:"remote". Remote lookups fail within 45s with errorCode parts.lookup.timeout instead of hanging.

Use this when you need to fit an orthogonal least-squares plane to XYZ point-cloud data. Returns centroid, deterministic unit normal, signed point residuals, RMS residual and maximum absolute residual. Accepts points already parsed by the caller from scan data or mesh vertices. Computes parameters only; it does not create a surface body. Requires at least three non-collinear finite points.

Use this when you need the unfolded flat pattern of a bent sheet-metal part. Return the unfolded 2D flat-pattern of a bent sheet-metal Shape as a Region (outer polyline + holes + bend lines + sketch plane). Any number of parallel bends; crossing bends need corner relief. Pass { file } or { code }; optional { featureId } to pick a specific Shape.

Render a project's current model server-side and return it as an inline image so you can SEE what you built. Prefer open_in_studio for the happy path — it already includes an iso PNG preview in the same publish result when previewDelivered is true. Use this tool for a different `view`, a contact sheet (`view:"all"`), or when you only have a slug and are not publishing. Call with that `slug` to inspect whether the build looks right. CRITICAL — the image is rendered from the MODEL on the server; it does NOT reflect the user's Studio camera, zoom, or screen. NEVER ask the user to rotate, zoom, pa…

Return the raw per-feature triangle mesh (positions/indices/normals) of a project's current model, by slug. For the in-chat 3D viewer widget to render geometry; delivered over the MCP Apps bridge. The slug is the capability: public/unlisted need no OAuth; private requires the owner signed in.

Use this when you need to reopen a saved project or browse what the user has saved — it fetches a kernelCAD Studio project, or lists the signed-in user's saved projects. Pass `slug` (from a /p/<slug> link or a prior listing) to fetch that project's full .kcad source and metadata — then edit and open_in_studio with the same slug so the user's open tab updates live. Private projects require their owner's OAuth connection. OMIT `slug` to list the signed-in user's saved projects (most recently updated first); that listing mode requires the OAuth connection and does NOT paint — prefer list_my_proje…

Fetch the exact immutable .kcad source and parameters captured at a prior `open_in_studio` version. Use this to read-after-write verify a release: pass the returned `slug` and `version`, then hash or inspect the returned source. Public/unlisted projects use the slug as capability; private projects require the owner's OAuth connection.

Use this when you need to read the human/agent selection in a local Studio session. Returns one clicked face or edge (or null), with current-generation mesh-local shapeIndex/kind/id and creating featureId. During a rebuild selection is null with “selection pending rebuild” until Studio uniquely verifies the face; ambiguous or deleted faces are cleared. Inspect the current shape before authoring a fillet. Requires a running local Studio opened on the same script; hosted sessions are not supported.

Use this when the user wants to start from their own STEP or STL file (a part they designed elsewhere, a vendor model). Give exactly one source: url (a public https direct-download link), upload (a file the user attached in ChatGPT), or content_base64 (raw bytes, small files only). Max 50 MB. The format is detected from the bytes (or pass format: 'step' | 'stl'). Writes the file and a starter <name>.kcad.ts whose base body is lib.fromSTEP / lib.fromSTL into output_dir (default: a fresh temp dir), evaluates it, and returns { ok, format, model_path, script_path, code, bbox }. Pass script_path as…

Use this when you need to read facts about a model. One reader, selected by `of`: - 'assembly' — physical assembly inventory (parts, bboxes, connectors, mates, disconnected solids). - 'robot' — URDF/SDFormat export preview (links, joints, planning groups, end-effectors, issues). - 'step' — inspect an imported STEP file: solid tree, exact bbox/volume, cylindrical holes (breached bores flagged partial; holeDetection: 'exact' | 'heuristic'). - 'shape' — volume / surfaceArea / bbox for one feature ({ feature_id? }). - 'mass' — mass, centre of mass, centroidal inertia tensor (inertia6 + 3x3 inertia…

Use this when you need the captured NURBS definition for a kernelCAD nurbsCurve/spline3d feature. Returns degree, distinct knots and multiplicities, poles, weights, rational and uniformWeights flags, hasNonUnitWeights, and parameter range. Defaults to the last captured curve; pass feature_id to choose one. Reports authored data, not exact geometry-derived B-rep edge/face NURBS. Surface extraction and blending are not supported.

Use this when you need to list the kernelCAD script-runtime surface: global functions (box, path, selectEdges, helix, etc), Shape methods (fillet, sweep, lower, etc), Sketch methods (extrude, revolve, sweep), PathBuilder methods, EdgeQuery/FaceQuery key sets, and featureKindFaceLabels (which globals accept opts.faceLabels and valid value shapes). Use this to discover what is callable from a .kcad.ts script. Call this BEFORE concluding kernelCAD lacks a capability — its NURBS freeform surfacing (loft, sweep, boundary-fill, G2 blend) is easy to miss from tool names alone.

Return the kernelcad-authoring skill — conventions for writing .kcad.ts scripts (API surface, parameters, evaluation contract, common pitfalls) — in sections. Call with NO arguments first: you get the quick-start (units, axes, the return rule, the rules that prevent most failures, the intent → API routing table, the "Before you finish" checklist) and an index of every section with a one-line summary (under 16k chars). Then pull what you need: `{ section: "<id>" }` returns one section (e.g. "top-level-functions", "materials", "dfm-gates-print-readiness"); `{ query: "fillet after subtract" }` r…

Use this when you need a canonical pattern snippet for a CAD task. Search the kernelCAD cookbook for canonical pattern snippets. Returns top-k snippets matching the natural-language query, ranked by BM25 over title/tags/keywords/trigger. Use when you need a canonical pattern for fillet-after-subtract, non-overlapping booleans, sketch-to-extrude flows, etc. Returns empty if no snippet scores above the relevance floor — proceed without cookbook help in that case.

Use this when you need the kernelCAD 26-code diagnostic catalogue with hint templates. Tiny one-shot call; useful for an agent that wants to pre-populate retry strategies. Hints are also inline on every emitted diagnostic — this tool just gives you the canonical list up front.

Use this when the user wants to union, subtract, or intersect two imported triangle mesh solids (STL, OBJ, or 3MF). Supports union, subtract (A minus B) and intersect. Pass each operand as { file } on the MCP server or { data } with base64 mesh bytes; formats are detected or may be specified. Returns volume in mm³, triangle count and a binary STL as data_base64; pass that payload to import_step to continue modeling. Inputs must be closed, consistently oriented 2-manifold meshes. Open, non-manifold, or invalid meshes return an error. This computes mesh geometry and does not create an editable B…

Mesh a kernelCAD .kcad.ts source server-side and return a COMPACT geometry summary — overall bounds plus, per feature, its id, kind, triangle count, and bounding box. Use this to INSPECT a model's geometry without a viewer: confirm a part is the size/shape you expect, see how many triangles each feature contributes, or check that every feature produced geometry. This runs the full server-side OCCT pipeline (the same one the Studio renderer uses), so it evaluates modern sources (assembly, path, .material, …) that the legacy client worker cannot. INPUT: `source` (required) the .kcad.ts script …

Use this when you are handed an STL, OBJ or 3MF of a mostly prismatic mechanical part (plate, bracket, spacer, flange, housing block) and need an EDITABLE kernelCAD model of it rather than a faceted lib.fromSTL import. Deterministic, measured, self-verifying: it welds and checks the mesh, segments planes and cylinders, picks the extrusion axis, slices each band and fits exact lines / arcs / circles, snaps near-round values (each snap recorded), then emits a readable .kcad.ts with named param()s — a revolve for concentric round stacks, extruded profiles otherwise, .hole()/.holes() for through, …

Save the model as a kernelCAD project AND show it: persists a project revision, returns the interactive Studio viewer (MCP Apps / ChatGPT outputTemplate), and includes a PNG preview in the SAME tool result (image content + previewUrl when available). ONE VIEWER PER PROJECT PER RESPONSE: every call renders a new viewer card. Do all validation with evaluate_script first, then call open_in_studio exactly once, after validation succeeds; reuse the returned URL, revision and preview, and never call it again after a successful result in the same response. Re-calling with unchanged code for the same …

Order the part made: creates the production request and returns a pay_url for the user. Propose the manufacturing method from the user's words and the part, pass it as method with a one-line reason. The price is the real maker price; never invent or send one. Tell the user the card is only held, and a person confirms the final price before charging. If the result is status "pricing", the price is still being worked out: call again in a few seconds.

Start or read the real price for making the part. Cheap. Returns status "ready" with estimate_cents and summary, or "pricing" while the makers are asked (call again in a few seconds). Creates nothing and charges nothing.

Use this when you need to wrap a 2D closed curve onto a 3D face. Insert a `<shape>.projectCurve({ source, face, scaleMode? })` chained call into a kernelCAD script. The `source` is the structured `{ kind: "sketchCommands", commands: [...] }` wire format the runtime API accepts. Wraps the curve onto the face along the face normal; pair with `.extrude(d)` / `.cut(...)` for raised or engraved logos on curved bodies. Open-wire projection (`asEdge: true`) is not implemented and is rejected at edit time. Side-effect-free; returns modified code plus diagnostics.

Use this when you need to resolve or inspect topology against a script's lowered geometry. Pass the script as `code` (inline; works on a hosted server) or `file`. Selected by `mode` (default 'evaluate'): - 'evaluate' — list the faces a Query matches ({ query }). Pass expect:'unique' to assert exactly-one. - 'resolve' — resolve one ref to one face ({ ref }). - 'lineage' — the creating/modifying history of a face ({ ref }; feature_id defaults to the last feature). Query forms (faces only; edge/vertex kinds return query.unsupported-entity-type): - a bare face label: 'top', 'bottom', 'left', 'righ…

Use this when you need the faces a ray hits in a local Studio model, nearest first, with points, distances, and normals. Inputs are model units (mm); direction is normalized. Requires the local Studio URL and session token for the same script, reads the current model generation, and returns a set_selection argument object with every hit. feature_id must identify a displayed terminal shape; intermediates have no current viewer shapeIndex. Intersections use the viewer per-face tessellation, so curved-surface points and normals are mesh approximations.

Use this when you need to remove a feature line from a script. Remove a single line from a kernelCAD script identified by a substring match. Returns the modified code plus diagnostics from re-evaluating. Refuses to remove the line containing the return statement. Side-effect-free.

Use this when you need to LOOK at a kernelCAD model — render its script to deterministic PNG views for visual self-check (the visual half of the evaluate → render → inspect → fix loop), with NO studio or dev server required. Pass { code } (inline source) or { file } (a .kcad.ts path), exactly one. Renders the canonical engineering views (front, right, top, iso — pass { views } for a subset, e.g. ["iso"] for fastest iteration) plus an optional { pose: "<az>,<el>" } arbitrary camera angle (degrees; az=0,el=0 is front, +az rotates CCW around +Z, +el lifts the camera). NO STUDIO / DEV-SERVER REQUI…

Use this when evaluate_script reported an error and you want the fix applied rather than described. Takes the candidates why_did_this_fail derives for a diagnostic, applies them one at a time, re-evaluates after each, and keeps the first that clears the diagnostic without introducing new errors. Never edits outside the repair region (failing feature statement + its input statements + the param() lines it reads) — an out-of-region patch is refused with tool.repair.out-of-region. Returns the repaired source in `new_code` (the caller persists it), a unified `diff`, and before/after health maps. P…

Use this when the user has a photo, PDF drawing, STEP, STL, DXF, SVG or 3MF file on their device and you need it in a kernelCAD tool (trace_from_image, drawing_to_cad, mesh_to_features, inspect of:"step", or lib.fromSTEP / fromSTL / fromDXF / fromSVG / referenceImage in a script). Do not ask the user to paste the file as text or base64, and do not type coordinates from an image by hand. Returns a one-time `uploadUrl` (valid 30 minutes) and an `asset` reference. Give the user the link; after they say the upload is done, pass the `asset` value ("asset:<id>") as the file argument, for example tra…

Use this when you need to confirm or override the open facts in an assumption ledger from trace_from_image (missing scale, inferred/assumed values) before committing geometry built from a reference photo. Reads the persisted `<model>.ledger.json` at `ledgerPath`, applies each resolution — `{ id, confirm: true }` to accept a fact as-is, or `{ id, value }` to override it — rewrites the ledger file, and returns the updated ledger plus `paramOverrides` (factId -> value) to feed straight into `set_param`. Pair with the `kernelcad-from-reference` skill.

Use this when you need to review a mechanism for fitness and repair mode. Run the deterministic CAD review loop: evaluate the script, validate the assembly/mate graph, check mate connectors touch modeled material, sample declared mate limits, optionally check interferences at sampled poses, report connector workspace bounds, and return a mechanism fitness verdict for agent self-review. Fitness includes repairMode: none, local-fix, parameter-tune, or topology-redesign. Runs within timeBudgetMs (default 90 s): stages that did not fit are listed in skippedStages (their checks did not run; mechani…

Return the newest brush-painted review packet from a Studio session. After sharing a /p/<slug> link, the user can open it in the browser and paint marks over the 3D viewport to give visual feedback. Call this tool with the `slug` from that link to see the strokes — screenshot + mask + struck part names plus an optional one-line note and intent tags (e.g. "too thick", "missing", "wrong angle") describing WHAT is wrong — and act on the feedback. The slug is the capability: no OAuth required when passing `slug`; private projects require the owner to be signed in. Omit `slug` to fetch your own lat…

Use this when you need to know whether a part will hold a load. Runs a linear-static structural study and returns evidence — peak von Mises stress (MPa), peak displacement (mm), the minimum safety factor against the material yield (taken away from the clamp-singular edges of the fixed faces; the raw clamp-edge peak is reported separately as peakAtSupportMPa), per-region hot spots named by @kc[...] face ref, mesh trust flags, an equilibrium residual, and (CalculiX only) stress-heatmap PNG paths. The study is EITHER declared in the script with `shape.feaStudy({ material, fixed, loads, meshSize?,…

Use this when you need to upload a .gcode file (e.g. written by export with target: "model", format: "gcode") to a real network printer and, by default, start the print. protocol: 'octoprint' (POST /api/files/local with an X-Api-Key), 'moonraker' (Klipper's POST /server/files/upload), or 'bambu-lan' (Bambu Lab LAN-mode: FTPS implicit-TLS upload on port 990 as user 'bblp' with the printer's LAN access code, then an MQTT print-start command on port 8883 — requires access_code and, unless start_print is false, serial). bambu-lan uploads a .gcode.3mf print project (the printer prints 3MF projects,…

Use this when you need to edit a param() default value in a kernelCAD script. Returns the modified code as text plus diagnostics from re-evaluating the result. Caller persists the new code via standard file-write tools (this tool has no side effects).

Use this when you need to set how the script returns its assembly. Replace the final top-level return statement with `return <assembly>.model();` or `return <assembly>.solvedModel(poses, options?);`. Use solvedModel for mate-authored mechanisms so FK and validation run. Returns modified source plus diagnostics from re-evaluation.

Use this when you need to replace the shared local Studio face/edge selection, or clear it with selection:null. The viewer highlights the pick on its next sync (300 ms). Does not edit geometry. Pass model_generation from get_selection; writes from an older generation are rejected. Use only current shape indices. Requires a local Studio session.

Use this when you need to solve the mate graph and get part poses. Run the v0.6 mate-graph solver on the active assembly. Returns { status, poses, iterations? } where each pose is a serialized Transform ({ translation, rotateAxis, rotateDeg }). Optional poses overrides mate pose values by mate name.

Use this when you need to solve a 2D sketch constraint set. Solve a 2D sketch constraint set. Side-effect-free: pass { entities, constraints } and receive solved entities plus the original constraints. Entities are POINT, LINE, and CIRCLE records; constraints use the kernelCAD constraint vocabulary.

Use this when you need to check whether a mechanism stays buildable across a tolerance/dimension range, not just at one nominal value. Declares one or more param() names with a { values: [...] } list or a { min, max, steps } range, re-evaluates the script once per cartesian-product combination (capped at 64 combos — exceeding it truncates to the first 64 and emits kinematic.sweep-tolerance.combo-cap-exceeded), and runs the standard gates on each combo: interference, mounting-hole diameter agreement, and joint-axis binding (all three, default on); reachability only when gates.reachable names a …

Use this when you need to trace a reference image into normalized waypoints. Trace pixel-space features from a reference photo into normalized [0..1] waypoints the agent can map to mm via a known scale anchor and feed to path().spline / path().nurbsSegment. Three backends are dispatched behind the scenes: `opencv` (deterministic; uniform-bg silhouette only), `vision-llm` (vision model; named points/cluttered backgrounds; needs a configured vision endpoint), and `hybrid` (opencv silhouette + LLM-labeled named points). Default backend is `auto`. Per-feature confidence is reported. Pair with the …

Use this when you need to check a design against a rule set. One verifier, selected by `check`: - 'assembly' — static assembly review ({ file | code }, or the session evaluate_script left): mate validator, default-pose interference, joint topology, mechanical plausibility. ok:false with `blocking[]` exactly when review_cad's blocking rules fire on these findings; review_cad also sweeps joint ranges and runs physics. - 'urdf' — structural validity of a .urdf file ({ urdf_path }). - 'dfm' — print-readiness gates declared by dfmSpec() ({ file | code }). - 'dfm-preflight' — sheet-metal flat patter…

Use this when you need to trace why a feature failed. Walk the upstream chain of a failing feature. Returns the diagnostics of the requested feature plus the diagnostics of every upstream feature in topological order (the requested feature is the last entry). Per-code hints are inline on every diagnostic — call lookup_diagnostics for the full catalogue. Pass { file?, code?, feature_id? }.

Use this when you need to merge a LabWired handoff BOM with optional KernelCAD catalog parts, MPNs and pricing, then write CSV or retrieve Sheets-ready rows. Pass exactly one of handoff, handoff_json or handoff_path. This tool only writes a CSV locally; it makes no Google API calls. Returns headers, tabular rows, CSV contents and the CSV path.