kernelcad-mcp

kernelCAD — MCP companion

When to load this skill

Load when kernelcad mcp is available and you need to inspect or edit a live model without re-running the full CLI on every change. The MCP server exposes dynamic introspection tools that operate on evaluated in-memory state.

MCP tool surface

When you have kernelcad mcp available, use the MCP tools for dynamic introspection rather than re-running the CLI. The MCP server exposes the current tool registry, including:

Point-cloud analysis

• fit_plane({ points }) — fit an orthogonal least-squares plane to at least three non-collinear XYZ triples (up to 100,000). Returns the centroid, deterministic unit normal, signed orthogonal residual per point, RMS residual and maximum absolute residual. Pass points parsed by the caller from a scan or mesh; this tool estimates parameters only and does not parse files or create a surface body.

Evaluation and introspection

• write_bom({ handoff | handoff_json | handoff_path, catalog_parts?, output_path?, overwrite? }) — merge a LabWired handoff BOM with optional KernelCAD catalog MPNs/prices; writes CSV and returns headers, formula-neutralized Sheets-ready sheets_rows, and CSV contents/path. Existing CSV destinations are preserved unless overwrite: true. The tool makes no Google API calls.

• evaluate_script({ file? code?, dryRun? }) — pass/fail + featureCount + diagnostics + sceneSummary (valid, volume in mm³, BREP faceCount, conservative world bounding size: [x,y,z] in mm); plus a parts summary { count, names } when the scene is assembly-built (absent for single-shape / non-assembly scripts). dryRun: true is the fast iteration mode: transpile + capture + capture-light checks without building solids, DFM gates, or meshing — milliseconds instead of seconds. A dry run catches script throws, capture-time API misuse, and assembly validity-gate failures, but NOT lowering failures (failed booleans, oversized fillets) or dfmSpec diagnostics, and it leaves the active session untouched — finish with a full evaluate_script before using session-dependent tools. A model with moving joints or motion intent (an animation track, mechanicalJoint, transmission) also gets mechanismSummary — { verdict, maxLevel, statement, checked, skipped, failures } (maxLevel: error broken, warning not checked, ok checked). The verdict also fails an animation key that drives a joint past its limits (kinematic.pose.out-of-limits), a closed loop that does not close (assembly.mate.over-constrained / assembly.solver.did-not-converge, naming the mate) and a loop mate that comes apart at a swept pose (mechanism.mate-unsatisfied); a moving DOF with no limits is listed in skipped (range not checked), not failed. Quote statement: Motion checked says what ran, Motion not checked is not a pass (say it was not checked), Mechanism broken names the joint. An animated param or drive on a fastened joint fails as mechanism.motion-on-fixed-joint: make that joint revolute/prismatic and pass the param as its pose; never turn a fastened part by rotating its geometry. Studio shows the same verdict as a badge; saving is never blocked by it.

• diff_scripts({ baseFile? baseCode?, file? code? }) — structured geometric delta between a baseline script and a revision. Returns per-part added/removed/renamed/changed (volume mm³ + exact bbox deltas; numbers match inspect({ of: 'part-stats' })), interference totals per side + deltaMm3 with per-pair detail, mate-graph changes (type, connectors, pose, limits), and param changes (value/min/max). Single-shape scripts diff as one (root) pseudo-part. Use after editing a script to verify exactly what changed physically before re-rendering; read-only, never touches the active session.

• diff_geometry({ baseFile? baseCode?, file? code?, params?, render? }) — the deeper sibling of diff_scripts, for when a volume/bbox delta is ambiguous: a boss that grew and a pocket that deepened report the same |ΔV|, and a part that only moved reports ΔV = 0. The revised side is either another script (file/code) or the SAME script re-lowered with params overrides (declared param() name → new value — the one-script form a parameter sweep asks for). Bodies pair by name, falling back to declaration-order positional pairing; leftovers land in unmatched and raise diff.body.unmatched. Per matched body: addedMm3 = volume(revised − base), removedMm3 = volume(base − revised), commonMm3 = volume(base ∩ revised), exact bbox with min/max/extent deltas, face/edge/hole count deltas, maxDeviationMm (two-sided discrete Hausdorff distance), and a verdict — identical | moved | resized | topology-changed (precedence: topology-changed > resized > moved > identical). Branch on the verdict; cite the numbers. { render: true } also writes an overlay PNG — added green, removed red, unchanged material as a translucent ghost — through the render_preview pipeline; the scene itself is a re-runnable diff-overlay.kcad.ts over lossless BREP sidecars in render.out_dir. It fails open: the numeric diff is returned either way, with render.error naming what the render pipeline needs. Read-only. diff_scripts sets deeperDiffAvailable when its own numbers are not enough to say what physically changed; follow that pointer here instead of reaching for a render.

• inspect({ of: 'features', file? code? }) — array of feature summaries (kind/id/params/inputs)

• inspect({ of: 'assemblies', file? code? }) — captured assembly intent: assemblies, parts, named connectors, fixed connections, joints, and aggregate models

• inspect({ of: 'assembly', file? | code?, assembly? }) — physical assembly inventory for agents: named parts, bboxes, explicitly assigned engineering material (from assembly.part(..., { material })), connectors, mates, mechanical review facts, disconnected solids, unexplainedGeometry, and a next-action prompt. componentCount is a disconnected-mesh diagnostic only; it is not a stable cell/region identity and cannot be assigned an independent material. Assign separate materials by modeling separate named assembly parts. Run this before accepting visually suspicious mechanisms; random/floating geometry must be repaired or explicitly justified by the original prompt.

• inspect({ of: 'step', file }) — inspect a STEP file directly, without evaluating a script ({ file } is required; no { code } mode): solid tree (index + best-effort name), per-solid exact bounding box + volume + face count, and detected cylindrical holes (axis origin + direction, diameter, depth, blind/through; co-axial seam-split faces merge into one bore). A bore whose wall is breached (a slot, pocket, or nearby fillet/chamfer runs into it) is still reported, flagged partial: true with angularCoverageDeg; the report then says holeDetection: 'heuristic' (also when an ambiguous concave cylinder was left out) — treat those holes as candidates to confirm with a render or section. 'exact' means every concave cylinder was a full bore or clearly a fillet/slot end. depthMm is the cylindrical wall length: a mouth chamfer/fillet shortens it. Run this before placing an imported vendor part — find mounting-hole positions and verify the part-local frame from exact geometry instead of measuring renders. CLI equivalent: kernelcad inspect step <file.step>.

• inspect({ of: 'shape', file? code?, feature_id? }) — volume/surfaceArea/bbox of a feature (default: last)

• inspect({ of: 'topology', file? code?, feature_id? }) — canonical face names + edge count

• inspect({ of: 'face-edges', file? code?, feature_id?, face_name }) — boundary edges of a face (centroid, length, isClosed)

• inspect({ of: 'edges', file? code?, feature_id? }) — enumerate all edges (index, centroid, length, isClosed)

• inspect({ of: 'faces', file? code?, feature_id? }) — enumerate all faces with area and centroid

• inspect_nurbs({ file? code?, feature_id? }) — read captured NURBS data from a nurbsCurve/spline3d feature: degree, knots and multiplicities, poles, weights, parameter range, rational (weights not all equal), uniformWeights (all equal), and hasNonUnitWeights (any differs from 1). This reports authored curve data, not post-operation B-rep edge/face extraction; surfaces and blends are not supported.

• apply_surface_blend({ code, shape_binding, operation?, radius?, distance?, selector?, continuity? }) — insert a Shape.fillet(...) or Shape.chamfer(...) line before the script return, evaluate the patched code, and return new_code plus diagnostics and scene summary. selector uses the existing EdgeSelector conventions (@kc[...] edge ref/query or { face: canonical name | face label | FaceQuery descriptor }); omit it to affect all sharp edges. Fillets accept continuity: 'G1' | 'G2' through the existing public API; chamfers use distance. This authors a fillet/chamfer operation only. It does not extract blend-surface NURBS poles; that still requires kernel surface extraction.

• inspect({ of: 'face-labels', file? code?, feature_id? }) — canonical face names resolvable on a feature

• query({ mode: 'lineage', file? code?, feature_id, ref }) — walk the HistoryMap chain that produced a named face/edge ref; returns { chain, usedFallback }.