{ "schemaVersion": 1, "scope": "local", "tools": [ { "name": "evaluate_script", "description": "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 + diagnostics + sceneSummary (BREP validity, volume in mm³, face count, bounding size in mm). When the scene is assembly-built (assembly().part(...) → .model()/.solvedModel()), also returns a parts summary { count, names } AND runs the mechanism-truth gate by default: the `mechanism` field reports real/broken/unverified and a broken mechanism (disconnected components / mechanism.orphan-part, self-collision, fastened drift, dof-mismatch) makes ok:false with the failures in diagnostics, as does a mate connector more than 6 mm outside its part bounding box (assembly.mechanical.connector-not-in-solid, the same error review_cad reports) — a mechanism (any mate or joint) needs every part linked by connectors + mates/joints (axis+revolute for shafts/hinges/gears; frame+fastened for rigid; or arm.revolute/.prismatic/.ball/.fixed). A plain multi-part assembly with no mates (base + lid, print layout) is independent bodies and passes. Pass { skipMechanismCheck: true } to opt out (e.g. a deliberately free part next to a mechanism). An animation or drive on a fastened joint (mechanism.motion-on-fixed-joint) is broken: animate a revolute/prismatic mate pose. For a model with moving joints or motion intent, `mechanismSummary.statement` is one plain line: \"Motion checked: ...\" names what ran; \"Motion not checked: ...\" is NOT a pass — never call that mechanism working. Every union() is checked too (no opt-out): union.disconnected (the union is several separate solids — a floating operand) and union.member-overlap (two operands that each carry their own .finish()/.material(), the same one, share > 1 mm³ — cut members to fit, e.g. a cross tube between rails is span minus two rail widths) make ok:false. Pass either { file: \"\" } or { code: \"\" }. Set { dryRun: true } for fast validation while iterating: transpile + capture + capture-light checks without building solids, DFM gates, or meshing — milliseconds instead of seconds (100x+ on boolean/fillet-heavy scripts). A dry run catches script throws, capture-time API misuse, and assembly validity-gate failures, but NOT lowering failures or dfmSpec diagnostics; it leaves the active session untouched, so finish with a full (non-dry) evaluate_script before using session-dependent tools. To show a measurement in the 3D viewer (e.g. hole spacing), declare it in the script with shape.dimension({ kind: \"linear\", from, to, label }); a full evaluate lists them as dimensions: [{ text, kind, source }], and a shared /p link with ?dims=1 forces them on. A full evaluation updates the active MCP session and viewer state and keeps temporary step evidence; { dryRun: true } leaves the active session unchanged.", "inputSchema": { "type": "object", "properties": { "file": { "type": "string", "description": "Path to a .kcad.ts script file." }, "code": { "type": "string", "description": "Inline kernelCAD script source." }, "dryRun": { "type": "boolean", "description": "Fast validation only: skip solid build, DFM gates, and meshing. Does not set or clear the active session." }, "kernel": { "type": "string", "enum": [ "occt", "smlib" ], "description": "Solid-modeling kernel. Default 'occt' (OpenCascade); opt-in 'smlib' uses guarded candidates with explicit OCCT fallback diagnostics." }, "skipMechanismCheck": { "type": "boolean", "description": "Opt out of the default mechanism-truth gate. By default a full evaluation of an assembly-built scene runs checkMechanismTruth and returns a `mechanism` verdict (real/broken/unverified); a broken mechanism makes ok:false. Set true to skip the sweep entirely (no `mechanism` field, no cost). Ignored for dryRun and non-assembly scripts." }, "baseline": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The `selections` of an earlier evaluation of this model. A selector that now binds to a different face or edge is reported as selector.binding-changed (warning), one whose entity only moved or resized as selector.binding-moved (info). Defaults to the previous evaluation of the same `file`." }, "requirements": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Call-time external requirements ([{ name, predicate }]) measured in the same `requirements` ledger, tagged source: 'external' and never persisted. The predicate is the serializable form of require(): { metric: clearance | distance | mass | volume | bbox | centerOfMass | count | innerLoops | angle | concentric | coplanar, a?, b?, op: gte | lte | eq | between | within, limit, tolerance?, density? }. Operands are { kind: body | faces | edges | part, ref: , query? }." } } }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": true }, "outputSchema": { "type": "object", "properties": { "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "ok": { "type": "boolean", "description": "Whether the script compiled and lowered cleanly." }, "viewerUrl": { "type": "string", "description": "Live loopback Studio URL; reused on later full builds in the same local MCP process." }, "viewerError": { "type": "string", "description": "Viewer provisioning error; separate from the CAD build result." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "featureCount": { "type": "number", "description": "Number of features captured by the script." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "dryRun": { "type": "boolean", "description": "True when the result came from a fast dry run." }, "parts": { "type": "object", "additionalProperties": true, "description": "Assembly parts summary { count, names } when the scene is assembly-built." }, "featureHealth": { "type": "array", "items": { "type": "object", "properties": { "featureId": { "type": "string" }, "status": { "type": "string", "enum": [ "warning", "error" ] } }, "required": [ "featureId", "status" ], "additionalProperties": false }, "description": "Per-feature health degradations — ONLY features that fell back to a passthrough (warning) or failed to lower (error). Empty when every feature is healthy. Surfaces which feature degraded even when ok is true." }, "selections": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "What each feature's selectors bound to: { consumerFeatureId, selectorText, syntax: lineage | topoRef | query, fingerprints[] (entity kind, surface type, producing feature, direction, radius, size, centroid), partDiagonal }. Pass back as `baseline` to learn which selectors an edit re-bound. Omitted when no feature used a selector." }, "requirements": { "type": "object", "additionalProperties": true, "description": "One requirements ledger: { ok, summary: { pass, fail, notEvaluated }, entries: [{ name, source: script | external | dfm | fea | mechanical, status: pass | fail | not-evaluated, measured, limit, margin, selections[] with S1 fingerprints, message? }] }. The ledger is the repair signal: it names the requirement, the measured value, the limit and the exact selections. ok is true only when every entry passed; a not-evaluated entry is never green." }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "linear", "diameter", "radius", "angular" ] }, "source": { "type": "string", "enum": [ "declared", "auto" ] } }, "required": [ "text", "kind", "source" ], "additionalProperties": false }, "description": "Dimensions declared with shape.dimension(), as the viewer labels them (e.g. \"hole spacing 30\"). Omitted when the script declares none." }, "tubes": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "object", "properties": { "tube": { "type": "string", "description": "Name of the other tube of the joint." }, "at": { "type": "number", "description": "Station of the tee: mm along the trunk centreline from the trunk's from end." } }, "required": [ "tube", "at" ], "additionalProperties": false, "description": "Set when the from end branches off another tube: the trunk and the station of the tee on it. The cut length and bend table of this tube then start on the trunk wall. Omitted for any other end." }, "to": { "type": "object", "properties": { "tube": { "type": "string", "description": "Name of the other tube of the joint." }, "at": { "type": "number", "description": "Station of the tee: mm along the trunk centreline from the trunk's from end." } }, "required": [ "tube", "at" ], "additionalProperties": false, "description": "Set when the to end branches off another tube: the trunk and the station of the tee on it. Omitted for any other end." }, "branches": { "type": "array", "items": { "type": "object", "properties": { "tube": { "type": "string", "description": "Name of the other tube of the joint." }, "at": { "type": "number", "description": "Station of the tee: mm along the trunk centreline from the trunk's from end." } }, "required": [ "tube", "at" ], "additionalProperties": false, "description": "One tube that branches off this one." }, "description": "The tubes that branch off this one, by station. Omitted when there are none." } }, "additionalProperties": true }, "description": "One entry per tube: name, system, od, wall, bendRadius, material, cutLength (mm), bends, xyz (bend-table corner points), lra (length/rotation/angle rows), lastStraight, minStraight, minClearance { mm, to, at } (exact nearest part or tube), massKg (null without a known material or density), volumeInternalMl, pressureDropKPa (null without a declared flow)." }, "systems": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "One entry per named system: { system, lines, cutLength, massKg }." } }, "required": [ "lines", "systems" ], "additionalProperties": false, "description": "Tube line report. Present only when the model has tubes; the gate diagnostics are in diagnostics." }, "ports": { "type": "array", "items": { "type": "object", "properties": { "part": { "type": "string", "description": "The assembly part that owns the port." }, "name": { "type": "string", "description": "The connector name; part.port(name) gives this port to tube()." }, "system": { "type": "string" }, "od": { "type": "number", "description": "Tube outer diameter the port takes, mm." }, "minStraight": { "type": "number", "description": "Straight a tube must keep leaving the port, mm. Omitted when the port declares none." }, "origin": { "type": "array", "items": { "type": "number" }, "description": "Port position [x, y, z] in assembly space, mm, with params and mates resolved. Omitted when unresolved is set." }, "axis": { "type": "array", "items": { "type": "number" }, "description": "Unit axis [x, y, z] pointing out of the part, assembly space. Omitted when unresolved is set." }, "placedBy": { "type": "string", "enum": [ "at", "connect", "mate" ], "description": "'at': the part is where its at puts it. 'connect': the part is where its connect puts it. For both, part.port(name) gives this position. 'mate': a mate or joint moved or turned the part after that; origin and axis are the solved ones, and part.port(name) still gives the position before the solve. Omitted when unresolved is set." }, "usedBy": { "type": "array", "items": { "type": "string" }, "description": "Names of the tubes that end on the port; empty when the port is free." }, "unresolved": { "type": "string", "description": "Why the position is missing: the script does not build the assembly, the part failed to build, another part failed so the solve did not run and this part is positioned by a mate, a joint or connect, the part is not in the built assembly, or the connector origin is a topology reference or not numeric. Omitted when origin is given." } }, "required": [ "part", "name", "system", "od", "usedBy" ], "additionalProperties": false }, "description": "Every fluid port (a connector with port data) of the assembly the script returns. Present, possibly empty, whenever the script declares an assembly and builds a model, with or without tubes; omitted otherwise and for dryRun." }, "mechanism": { "type": "string", "enum": [ "real", "broken", "unverified" ], "description": "Mechanism-truth verdict for an assembly-built scene (default-on; omitted for dryRun, non-assembly, or skipMechanismCheck:true). 'broken' makes ok:false; 'unverified' keeps ok and surfaces a loud budget diagnostic." }, "mechanismSummary": { "type": "object", "additionalProperties": false, "required": [ "verdict", "maxLevel", "statement", "checked", "skipped", "failures" ], "description": "Plain verdict for a model with moving joints or motion intent (animation, drive, transmission); absent for a static model. Read `statement`: 'Motion checked' names what ran, 'Motion not checked' names what was skipped (NOT a pass), 'Mechanism broken' names the joint.", "properties": { "verdict": { "type": "string", "enum": [ "real", "broken", "unverified" ] }, "maxLevel": { "type": "string", "enum": [ "ok", "warning", "error" ], "description": "One status level: 'error' when broken, 'warning' when not checked, 'ok' when checked." }, "statement": { "type": "string", "description": "One line. Quote it instead of calling the mechanism working." }, "checked": { "type": "array", "items": { "type": "string" }, "description": "What ran and held (verdict 'real')." }, "skipped": { "type": "array", "items": { "type": "string" }, "description": "What did not run and why. On 'real', the moving joint DOFs with no limits (range not checked)." }, "failures": { "type": "array", "description": "Error failures (verdict 'broken'); `joint` names the mate and `part` the part when known.", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "reason" ], "properties": { "code": { "type": "string" }, "reason": { "type": "string" }, "joint": { "type": "string" }, "part": { "type": "string" } } } }, "loads": { "type": "object", "additionalProperties": false, "required": [ "maxLevel", "statement" ], "description": "Motion-load line, present when a mechanicalJoint declares torqueNm. Full table: verify({ check: 'motion-load' }).", "properties": { "maxLevel": { "type": "string", "enum": [ "ok", "warning", "error" ] }, "statement": { "type": "string" }, "joints": { "type": "array", "description": "Compact per-joint loads for the Studio Loads panel: peaks, support radial loads, and [tMs, torqueNm] pairs.", "items": { "type": "object", "additionalProperties": true, "required": [ "joint", "peakTorqueNm" ] } } } } } }, "reviewHint": { "type": "string", "description": "Present only when a captured assembly declares articulated (non-fastened) mates: the default mechanism check is shallow (no joint-support intents, pose-envelope overlap at declared limits, or gravity drop) — run review_cad for pose-envelope + gravity checks." } }, "required": [ "ok", "featureCount", "diagnostics", "sceneSummary" ], "additionalProperties": true } }, { "name": "diff_scripts", "description": "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)\" pseudo-part; a `return [a, b]` multi-body script diffs per body as \"body[0]\", \"body[1]\". An error that still leaves geometry (e.g. a skipped fillet) is listed under base/revised.errors beside the diff. Use after editing a script to verify exactly what changed physically before re-rendering. On a hosted server pass both versions inline: { baseCode: 'return box(10, 10, 10);', code: 'return box(10, 10, 12);' } (base_code/old_code/before and revised_code/new_code/after are accepted as aliases). Read-only — never touches the active session.", "inputSchema": { "type": "object", "properties": { "baseFile": { "type": "string", "description": "Baseline (before) script — path to a .kcad.ts file. Local servers only." }, "baseCode": { "type": "string", "description": "Baseline (before) script — inline source. One of baseFile / baseCode is required." }, "file": { "type": "string", "description": "Revised (after) script — path to a .kcad.ts file. Local servers only." }, "code": { "type": "string", "description": "Revised (after) script — inline source. One of file / code is required." } } }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "base": { "type": "object", "additionalProperties": true, "description": "Baseline summary { featureCount, partCount, isAssembly, errors? } (success); errors lists error diagnostics that still left geometry to diff." }, "revised": { "type": "object", "additionalProperties": true, "description": "Revision summary { featureCount, partCount, isAssembly, errors? } (success)." }, "parts": { "type": "object", "additionalProperties": true, "description": "Per-part added/removed/renamed/changed/unchanged (success)." }, "interference": { "type": "object", "additionalProperties": true, "description": "Total interference-volume delta + per-pair detail (success)." }, "mates": { "type": "object", "additionalProperties": true, "description": "Mate-graph changes (success)." }, "params": { "type": "object", "additionalProperties": true, "description": "Param value/min/max changes (success)." }, "deeperDiffAvailable": { "type": "object", "additionalProperties": true, "description": "Present when the diff touched geometry-affecting ops: { tool: 'diff_geometry', reason, bodies } — the same two scripts can be compared at material level (added/removed/common volume + per-body verdict)." }, "side": { "type": "string", "description": "Which side failed ('base' | 'revised') (failure)." }, "error": { "type": "string", "description": "Failure message (failure)." }, "errorCode": { "type": "string" }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "inspect", "description": "Use this when you need to read facts about a model. One reader, selected by `of`:\n- 'assembly' — physical assembly inventory (parts, bboxes, connectors, mates, disconnected solids).\n- 'robot' — URDF/SDFormat export preview (links, joints, planning groups, end-effectors, issues).\n- 'step' — inspect an imported STEP file: solid tree, exact bbox/volume, cylindrical holes (breached bores flagged partial; holeDetection: 'exact' | 'heuristic').\n- 'shape' — volume / surfaceArea / bbox for one feature ({ feature_id? }).\n- 'mass' — mass, centre of mass, centroidal inertia tensor (inertia6 + 3x3 inertiaMatrix), principalMoments/principalAxes, symmetry flags, and optionally the radius of gyration about an arbitrary axis ({ feature_id?, density?, gyration_axis? }); density in kg/m^3, defaults to 1000 (water).\n- 'features' — features captured by the script (kind, id, params, transforms, suppression).\n- 'assemblies' — assembly intent (assemblies, parts, connectors, joints).\n- 'topology' — canonical face names + edge count for a feature ({ feature_id? }).\n- 'edges' — edges of a shape with optional EdgeQuery ({ feature_id?, query? }); returns @kc[...] refs.\n- 'face-edges' — boundary edges of a named canonical face ({ feature_id?, face_name }).\n- 'faces' — faces of a shape with optional FaceQuery ({ feature_id?, query? }); returns @kc[...] refs.\n- 'face-labels' — user-applied labels visible in the script.\n- 'mates' — mates captured by the script.\n- 'constraints' — sketch constraints captured by the script.\n- 'part-stats' — bundled parts-catalog statistics.\n- 'bend-table' — sheet-metal bend table for a flattened pattern.\n- 'params' — declared model parameters.\n- 'part-categories' — top-level part-catalog categories available in the bundled (and configured remote) catalog.\n- 'part-families' — part families within a category ({ category? }); count + exemplar ids per family.\n- 'bom' — bill of materials ({ assembly? }): one row per distinct part (grouped by geometry/catalog identity, not name) with real instance quantity, kind ('fabricated'|'purchased'), material, density, per-unit and total mass, bbox, a fabrication process (`process` + `processSource`), catalog provenance for purchased parts, and totals; `bom.*` diagnostics flag rows with no density source or missing catalog vendor info instead of guessing.\n- 'section' — numeric cross-section probe of a shape: area, perimeter, loop/hole counts, 2D bbox at a plane ({ feature_id?, plane | at+axis, stack?: { from, to, count, axis? } }). `stack` scans evenly spaced slices and returns `minAreaIndex`/`minAreaPosition` — use it to find the neck/thinnest cross-section along an axis.\n- 'continuity' — G0/G1/G2 classification of shared edges ({ feature_id?, edges? }); position gap, normal jump, curvature difference, worst-sample XYZ.\n- 'curvature' — per-face Gaussian and mean curvature min/max/mean, inflections, spikes ({ feature_id?, faces?, spike_factor? }).\n- 'multi-material' — explicit material leaves shadowed by later attributed boolean descendants, with assembly-part rewrite templates; analyzes capture records and does not change mesh attribution.\nAll params except `of` are subject-specific and forwarded verbatim. Most subjects accept { file | code }.", "inputSchema": { "type": "object", "properties": { "of": { "type": "string", "enum": [ "assembly", "robot", "step", "shape", "mass", "features", "assemblies", "topology", "edges", "face-edges", "faces", "face-labels", "mates", "constraints", "part-stats", "bend-table", "params", "part-categories", "part-families", "bom", "section", "continuity", "curvature", "multi-material" ], "description": "Which facts to read." }, "file": { "type": "string", "description": "Path to a .kcad.ts script file." }, "code": { "type": "string", "description": "Inline kernelCAD script source." }, "assembly": { "type": "string", "description": "of:'assembly'|'robot'|'bom' — assembly name; defaults to the first captured assembly." }, "feature_id": { "type": "string", "description": "of:'shape'|'mass'|'topology'|'edges'|'faces'|'face-edges'|'face-labels' — FeatureId; defaults to the last returned shape." }, "density": { "type": "number", "description": "of:'mass' — material density in kg/m^3 (steel 7850, aluminium 2700, ABS 1050). Defaults to 1000 (water); the response echoes the value used and flags when it was defaulted." }, "gyration_axis": { "type": "object", "description": "of:'mass' — optional axis in shape-local mm to report the radius of gyration about. Omit for centroidal quantities only; the result is density-independent and returned in mm.", "properties": { "origin": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "A point on the axis, shape-local mm." }, "direction": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Axis direction; normalised internally, so it need not be a unit vector." } }, "required": [ "origin", "direction" ] }, "face_name": { "type": "string", "enum": [ "top", "bottom", "left", "right", "front", "back" ], "description": "of:'face-edges' — canonical face name (required for that subject)." }, "query": { "type": "object", "description": "of:'edges'|'faces' — optional EdgeQuery/FaceQuery filter." }, "category": { "type": "string", "description": "of:'part-families' — optional top-level category to filter families by." }, "plane": { "type": [ "string", "object" ], "description": "of:'section' — section plane. Either a cardinal name string 'xy'|'xz'|'yz', { plane: 'xy'|'xz'|'yz', offset? }, or { origin: [x,y,z], normal: [nx,ny,nz] }. Omit to use `at`+`axis`." }, "at": { "type": "number", "description": "of:'section' — single slice position along `axis` (mm)." }, "axis": { "type": "string", "enum": [ "x", "y", "z" ], "description": "of:'section' — normal axis for `at` / `stack` (default 'z')." }, "stack": { "type": "object", "description": "of:'section' — dense scan: `count` slices evenly spaced from `from` to `to` along `axis`; response reports minAreaIndex/minAreaPosition.", "properties": { "from": { "type": "number", "description": "Start position along the axis (mm)." }, "to": { "type": "number", "description": "End position along the axis (mm)." }, "count": { "type": "integer", "description": "Number of evenly spaced slices (>= 1)." }, "axis": { "type": "string", "enum": [ "x", "y", "z" ], "description": "Scan axis (default 'z')." } }, "required": [ "from", "to", "count" ] }, "edges": { "type": [ "object", "array", "string" ], "description": "of:'continuity' — optional EdgeQuery or @kc[...] ref(s) limiting which shared edges are sampled." }, "faces": { "type": [ "object", "array", "string" ], "description": "of:'curvature' — optional FaceQuery or @kc[...] ref(s) limiting which faces are sampled." }, "spike_factor": { "type": "number", "description": "of:'curvature' — spike sensitivity as a multiple of the face's Gaussian stddev (default 6)." } }, "required": [ "of" ] }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": true }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the read succeeded." }, "error": { "type": "string", "description": "Failure message (present on failure)." }, "errorCode": { "type": "string" } }, "required": [], "additionalProperties": true } }, { "name": "verify", "description": "Use this when you need to check a design against a rule set. One verifier, selected by `check`:\n- '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.\n- 'urdf' — structural validity of a .urdf file ({ urdf_path }).\n- 'dfm' — print-readiness gates declared by dfmSpec() ({ file | code }).\n- 'dfm-preflight' — sheet-metal flat pattern vs a job-shop's ordering rules ({ vendor, material, thicknessIn|thicknessMm, ... }). Returns the vendor's catalog source pages as `sources`; when `disclosure` is present, show it with those links.\n- 'assembly-path' — continuous straight-line removal of each assembly part along ±X/±Y/±Z and optional world-space directions. Returns valid directions, blocking parts and one of three states (removable / blocked / unknown); sequence peels the directional blocking graph and reverses it into a build sequence with a model stamp. Fastened-mate and fixed-connect clusters become subassemblies: each is planned recursively inside and installed as one unit at the top level (`Step.subassembly`). Remaining valid orders use deterministic heuristics (subassemblies first, outside-in, fewest reorientations, fewest tool changes); stuck sets get a budgeted blocking-reduction partition and a sampling fallback whose paths are labelled found-by-search, never proven. A fastener with a fastened-mate `fastener` declaration (axis, pitch, optional tool envelope) is tested along its helical path and reported `motion: helical`; a press/snap `fit` declaration becomes a `requires-force` step, never simulated. A modelled driver/socket/hex-key envelope swept along the approach axis adds `toolBlocked` { fastener, blockers } and a failing S2 ledger entry; unmodelled tools add nothing. Threaded fasteners without metadata stay unknown: non-straight-path. `stability: true` adds an approximate P3 support check at each build step: each part's mesh centre of mass must project inside the support polygon of its contacts with already-stable parts (declared or inferred base/fixture under `gravity`, default [0,0,-1]); unsupported parts become `needsHold` { part, reason, supports } and their steps carry `stability: 'needs-hold'`, while stable steps may carry `heldBy`. This is a projection, not gravity simulation, friction, tipping or fixture analysis. disassemblyOrder runs a deterministic greedy removal pass. Watertight mesh approximation, conservative contact, no rotation/mate/hardware certification.\n- 'swept-collision' — sweep declared joint range(s) and report colliding poses.\n- 'reachable' — inverse-kinematics reachability for an end-effector ({ tip_link, target_position, ... }).\n- 'geometry-quality' — one solid body's BREP tiny faces and short edges (ids, locations, mm²/mm), plus sampled mirror symmetry about centroid XY/YZ/XZ and principal inertia planes ({ file | code, feature_id?, tiny_face_area_mm2?, tiny_face_relative?, short_edge_length_mm?, symmetry_tolerance_mm?, mesh_deflection_mm?, asserted_plane?: { origin, normal } }). Relative area is a fraction of total surface area; thresholds are ORed. Candidate planes are discovery; only an asserted plane gates symmetry. Approximate sampled tessellation, not exact BREP proof.\n- 'fastener-installation' — measured explicit catalog-screw installation stations on lowered assembly BREP ({ file | code, fasteners:[{ part, against, engagementPart?, minEngagementMm?, maxProtrusionMm? }], toleranceMm?, angleToleranceDeg? }). Reports annular bearing gap, bore axis/diameter/overlap and receiver geometric engagement/protrusion. Unknown or zero coverage cannot pass. Simplified threads do not certify torque, preload or strength.\n- 'mounting-holes' — fastened mates: hole pairs one screw can use (equal, or clearance over a tap drill / hole({ thread }) of the same metric size; hole-free faces are a rigid bond) and fastener holes meeting at the contact face are coaxial. Sides it cannot resolve are info, never mismatches.\n- 'load-capacity' — will it hold? Closed-form Euler-Bernoulli beam check ({ loads, materials, ... }), or mode:'fea' to solve the script's feaStudy (quadratic-tet FEA, CalculiX) — both return { ok, safetyFactor, elements[{ partName, stressPa, yieldPa, safetyFactor }], failures[], diagnostics }; fea adds the threshold, the stress regions as @kc[...] faces with their location, and fea { peakStressPa, maxDisplacementMm, meshTrusted, peakAtSupportPa, refinement }; it refines the mesh automatically until the stress is trusted (refine: false for one solve).\n- 'static-hold' — gravitational holding torque/force at a sampled pose grid vs each actuated joint's declared actuator capacity ({ joint?, pose?, gravity?, min_torque_margin_pct?, range_samples? }).\n- 'motion-load' — loads on each driven joint (mechanicalJoint on a revolute mate) while the model moves: gravity, inertia from the animationView tracks (finite differences), optional external forces. Mass and inertia come from the solids and density/material, or a part's massKg. Returns per joint peak torque vs the mechanicalJoint torqueNm (margin; < 1x error, < 2x warning), axial / radial force and bending moment on the actuator shaft (checked only against radialLimitN / axialLimitN; without them 'no rating, not checked'), the radial load on each of up to two coaxial supports (each at its station on the shaft: the actuator at the joint origin, else the support's connector on the axis, else the middle of its material nearest the shaft; an ambiguous station is a mechanism.load.not-resolved warning, not a number), the worst pose, a torque-vs-time series, and `partLoads` (the worst wrench per part and side in that part's own frame, which `feaStudy({ loadsFrom })` consumes) ({ file | code, motion_mode?: 'tracks'|'range'|'poses', motion_poses?: [{ joint: value }], sample_ms?, range_samples?, quasi_static?, gravity?, motion_loads?: [{ part, point, force, fromMs?, toMs? }], supports?: { joint: [parts] }, series_points? }). Pass supports to compare with and without a bushing. Rigid bodies, tree mate graphs, no friction.\n- 'physics' — full mechanism truth with physics engine: kinematic disconnect / interference / DOF checks plus static equilibrium and drop-on-release under gravity ({ file | code, assembly?, physics? }). Returns { ok, mechanism: 'real'|'broken'|'unverified', failures[], coverage }.\n- 'edge-radius' — general edge-break specification on final BREP ({ file | code, min_radius_mm?, max_radius_mm?, require_edge_break?: 'external'|'internal'|'all', feature_id?, assembly?, parts?, edges?, faces? }). Reports sharp convex/concave edges, analytic cylindrical/toroidal fillet radii and spherical junctions, and heuristic planar chamfer strips. Radius bounds apply only to fillets; selectors/points are part-local. Unknown/empty coverage cannot pass.\nAll params except `check` are check-specific and forwarded verbatim; each check fails closed on its own missing required params.", "inputSchema": { "type": "object", "properties": { "check": { "type": "string", "description": "Which verification to run. Omit only when passing call-time `requirements`; then the requirements ledger is the verification.", "enum": [ "assembly", "urdf", "dfm", "dfm-preflight", "swept-collision", "reachable", "mounting-holes", "load-capacity", "static-hold", "motion-load", "fastener-installation", "geometry-quality", "assembly-path", "edge-radius", "physics", "requirements" ] }, "requirements": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Call-time external requirements ([{ name, predicate }]) measured in the same ledger as script require(), dfmSpec and feaStudy, tagged source: 'external' and never persisted. The predicate is the serializable form of require(): { metric: clearance | distance | mass | volume | bbox | centerOfMass | count | innerLoops | angle | concentric | coplanar, a?, b?, op: gte | lte | eq | between | within, limit, tolerance?, density? }. Operands are { kind: body | faces | edges | part, ref: , query? }. With `check` omitted the ledger is the whole verification; check 'requirements' is the explicit form." }, "file": { "type": "string", "description": "Path to a .kcad.ts script (assembly/dfm/dfm-preflight/swept-collision/reachable/mounting-holes/load-capacity/static-hold/geometry-quality/edge-radius/requirements)." }, "code": { "type": "string", "description": "Inline kernelCAD script source (same checks as `file`)." }, "feature_id": { "type": "string", "description": "check:'geometry-quality' — body feature to measure; defaults to script return. check:'edge-radius' — lowered feature; default the returned model." }, "tiny_face_area_mm2": { "type": "number", "minimum": 0, "default": 0.01, "description": "check:'geometry-quality' — flag faces strictly below this absolute area; zero disables." }, "tiny_face_relative": { "type": "number", "minimum": 0, "maximum": 1, "default": 0, "description": "check:'geometry-quality' — fraction of total BREP surface area, ORed with absolute threshold." }, "short_edge_length_mm": { "type": "number", "minimum": 0, "default": 0.1, "description": "check:'geometry-quality' — flag edges strictly below this length; zero disables." }, "symmetry_tolerance_mm": { "type": "number", "minimum": 0.000001, "default": 0.05, "description": "check:'geometry-quality' — maximum sampled mirror-to-mesh distance, mm." }, "mesh_deflection_mm": { "type": "number", "minimum": 1e-7, "description": "check:'geometry-quality' — absolute mesh deflection, defaults to tolerance/4; must be <= tolerance/2." }, "asserted_plane": { "type": "object", "additionalProperties": false, "required": [ "origin", "normal" ], "description": "check:'geometry-quality' — optional required mirror plane in model coordinates; normal is normalized and must be nonzero.", "properties": { "origin": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "normal": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } } }, "assembly": { "type": "string", "description": "Assembly name; defaults to the first captured assembly." }, "min_radius_mm": { "type": "number", "minimum": 0, "description": "check:'edge-radius' — minimum fillet radius in mm (does not imply sharp-edge prohibition)." }, "max_radius_mm": { "type": "number", "minimum": 0, "description": "check:'edge-radius' — maximum fillet radius in mm; must be >= min_radius_mm." }, "require_edge_break": { "type": "string", "enum": [ "external", "internal", "all" ], "description": "check:'edge-radius' — prohibit sharp convex/external, concave/internal, or all edges." }, "parts": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "check:'edge-radius' — explicit assembly part names (default all)." }, "edges": { "type": [ "object", "array", "string" ], "description": "check:'edge-radius' — EdgeQuery or @kc[...] edge ref(s); intersected with faces. Query near sorts, it does not filter." }, "faces": { "type": [ "object", "array", "string" ], "description": "check:'edge-radius' — FaceQuery or @kc[...] face ref(s); includes incident edges and fillets on selected faces." }, "fasteners": { "type": "array", "description": "check:'fastener-installation' — explicit named stations; empty means no coverage.", "items": { "type": "object", "additionalProperties": false, "properties": { "part": { "type": "string", "minLength": 1 }, "against": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }, "engagementPart": { "type": "string", "minLength": 1 }, "minEngagementMm": { "type": "number", "minimum": 0, "description": "Declared geometric axial overlap minimum; no thread-strength claim." }, "maxProtrusionMm": { "type": "number", "minimum": 0 } }, "required": [ "part", "against" ] } }, "toleranceMm": { "type": "number", "minimum": 0, "description": "check:'fastener-installation' — linear tolerance, default .05 mm." }, "angleToleranceDeg": { "type": "number", "minimum": 0, "maximum": 90, "description": "check:'fastener-installation' — axis tilt tolerance, default 1 degree." }, "urdf_path": { "type": "string", "description": "check:'urdf' — path to the .urdf file." }, "dxf": { "type": "string", "description": "check:'dfm-preflight' — path to a DXF file." }, "featureId": { "type": "string", "description": "check:'dfm-preflight' — FeatureId to scope to." }, "vendor": { "type": "string", "description": "check:'dfm-preflight' — vendor SKU (required for that check)." }, "material": { "type": "string", "description": "check:'dfm-preflight' — material SKU (required for that check)." }, "thicknessIn": { "type": "number", "description": "check:'dfm-preflight' — material thickness in inches." }, "thicknessMm": { "type": "number", "description": "check:'dfm-preflight' — material thickness in millimeters." }, "service": { "type": "string", "enum": [ "laser", "cnc-router", "waterjet", "bending" ], "description": "check:'dfm-preflight' — service." }, "refreshCatalog": { "type": "boolean", "description": "check:'dfm-preflight' — force vendor catalog refresh." }, "directions": { "type": "array", "maxItems": 64, "items": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "description": "check:'assembly-path' — additional nonzero world-space removal vectors; normalized and deduplicated." }, "disassemblyOrder": { "type": "boolean", "description": "check:'assembly-path' — iteratively remove freed parts and return removalOrder or stuckParts." }, "sequence": { "type": "boolean", "description": "check:'assembly-path' — plan a build sequence { steps, model, unknown, search?, requiresForce?, toolBlocked?, needsHold? }. Fastened/fixed clusters become subassemblies planned inside and installed as one unit; steps carry the insertion direction (reverse removal), and may be motion: helical (declared fastener), requires-force (press/snap, not proven) or search. Stuck sets use a budgeted partition; non-straight paths found by sampling are labelled found-by-search and are not proven. Blocked and unknown parts are not reported as impossible." }, "threadedFasteners": { "type": "array", "items": { "type": "string" }, "description": "check:'assembly-path' — part names that need a helical removal. Catalog screw/bolt/nut families are detected automatically; without a fastened-mate fastener declaration (axis/pitch) they remain unknown: non-straight-path. Declare the motion on arm.mate(..., 'fastened', { fastener: { part, axis, pitchMm, tool? }, fit?: { kind, part? } })." }, "stability": { "type": "boolean", "description": "check:'assembly-path' — run the approximate P3 static-stability pass on the sequence. Each part's closed-mesh volume centroid (uniform density) must project inside the convex hull of its contacts with already-stable parts. Unsupported parts become needsHold { part, reason, supports } and ok:false; a stable step may carry heldBy. Not a physics simulation." }, "fixtures": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "check:'assembly-path' with stability:true — declared base/fixture part names, stable from step 1. Default: the lowest part(s) along gravity." }, "contactToleranceMm": { "type": "number", "minimum": 0, "description": "check:'assembly-path' with stability:true — surface distance at or below which parts count as touching (default 0.05 mm)." }, "joint": { "type": "string", "description": "check:'swept-collision' — joint to sweep; omit to sweep every declared joint. check:'static-hold' — joint to evaluate; omit to evaluate every joint with a declared actuator." }, "range": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "check:'swept-collision' — [lower, upper, step] in joint-native units." }, "collision_tolerance_mm3": { "type": "number", "description": "check:'swept-collision' — BREP intersection volume tolerance (mm^3)." }, "tip_link": { "type": "string", "description": "check:'reachable' — end-effector part name (required for that check)." }, "target_position": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "check:'reachable' — target [x, y, z] mm (world frame)." }, "target_orientation": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "check:'reachable' — target XYZ Euler angles in radians." }, "position_tolerance_mm": { "type": "number", "description": "check:'reachable' — position tolerance in mm." }, "orientation_tolerance_rad": { "type": "number", "description": "check:'reachable' — orientation tolerance in radians." }, "prefer_solver": { "type": "string", "enum": [ "analytical", "numeric", "auto" ], "description": "check:'reachable' — force the IK path ('auto' default)." }, "max_iterations": { "type": "number", "description": "check:'reachable' — numeric-path iteration cap." }, "seed": { "type": "object", "description": "check:'reachable' — numeric IK seed pose (joint name -> deg/mm)." }, "loads": { "type": "object", "description": "check:'load-capacity' — partName -> { force?: [Fx,Fy,Fz] N, torque?: [Tx,Ty,Tz] N*m }." }, "materials": { "type": "object", "description": "check:'load-capacity' — partName -> material declaration." }, "mode": { "type": "string", "enum": [ "stub", "beam", "fea" ], "description": "check:'load-capacity' — 'beam' (default), 'stub', or 'fea' (solve the script's feaStudy: CalculiX + gmsh when installed, else the in-process voxel estimate)." }, "safety_factor_threshold": { "type": "number", "description": "check:'load-capacity' — pass/fail safety-factor floor (default 1.5; mode 'fea': the study's minSafetyFactor when declared)." }, "study": { "type": "string", "description": "check:'load-capacity' mode:'fea' — feaStudy name (default: the last declared one)." }, "mesh_size": { "type": "number", "description": "check:'load-capacity' mode:'fea' — element size override, mm." }, "heatmaps": { "type": "boolean", "description": "check:'load-capacity' mode:'fea' — also render stress heatmap PNGs (default false)." }, "refine": { "type": "boolean", "description": "check:'load-capacity' mode:'fea' — one automatic finer pass (0.75x element size) when the stress is untrusted, inside the element budget (default true); false solves once at the study's meshSize." }, "pose": { "type": [ "object", "array" ], "description": "check:'static-hold' — explicit pose (joint name -> deg/mm) or array of poses; omit to sample a grid across the evaluated joint's range." }, "gravity": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "check:'static-hold' — gravity vector, m/s^2, world frame (default [0, 0, -9.81]). check:'assembly-path' with stability:true — gravity direction, world frame, magnitude ignored (default [0, 0, -1])." }, "min_torque_margin_pct": { "type": "number", "description": "check:'static-hold' — safety-margin floor as a percent of actuator capacity (default 20)." }, "range_samples": { "type": "number", "description": "check:'static-hold' — grid density per evaluated joint when `pose` is omitted (default 9). check:'motion-load' motion_mode:'range' — grid points per joint (default 5)." }, "motion_mode": { "type": "string", "enum": [ "tracks", "range", "poses" ], "description": "check:'motion-load' — 'tracks' (default): along the animationView timeline with inertia; 'range': quasi-static grid over each driven joint's limits; 'poses': exactly motion_poses (a user-named pose is one entry)." }, "motion_poses": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } }, "description": "check:'motion-load' motion_mode:'poses' — explicit mate poses, each an object of joint name -> value in degrees." }, "sample_ms": { "type": "number", "description": "check:'motion-load' — timeline sample step, ms (default 20). Inertia peaks depend on it at keyframe velocity steps." }, "quasi_static": { "type": "boolean", "description": "check:'motion-load' — drop velocity/acceleration terms (gravity and external loads only)." }, "motion_loads": { "type": "array", "description": "check:'motion-load' — external forces: [{ part, point: [x,y,z] mm in the part's modeled frame, force: [Fx,Fy,Fz] N world, fromMs?, toMs? }].", "items": { "type": "object", "required": [ "part", "point", "force" ], "properties": { "part": { "type": "string" }, "point": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "force": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "fromMs": { "type": "number" }, "toMs": { "type": "number" } } } }, "supports": { "type": "object", "description": "check:'motion-load' — mechanicalJoint name -> support part names to use instead of the declared supports (compare with / without a bushing)." }, "series_points": { "type": "number", "description": "check:'motion-load' — max torque-vs-time points per joint in the result (default 120; 0 omits the series)." } }, "required": [ "check" ] }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "checkedEdges": { "type": "integer", "minimum": 0, "description": "edge-radius: selected nondegenerate, nonseam edges." }, "checkedFillets": { "type": "integer", "minimum": 0, "description": "edge-radius: analytic fillet face patches, including spherical junctions." }, "bodies": { "type": "array", "description": "edge-radius: one local BREP report per solid of each selected part, plus retained unsupported topology.", "items": { "type": "object", "additionalProperties": false, "properties": { "part": { "type": "string" }, "bodyIndex": { "type": "integer", "minimum": 0 }, "edges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "ref": { "type": "string" }, "edgeIndex": { "type": "integer", "minimum": 0 }, "faceIndices": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "faceRefs": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "sharp", "smooth", "filleted", "chamfered", "unknown", "seam", "degenerate" ] }, "side": { "type": "string", "enum": [ "external", "internal", "unknown" ] }, "point": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } }, "required": [ "ref", "edgeIndex", "faceIndices", "faceRefs", "kind", "side", "point" ] } }, "breaks": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "ref": { "type": "string" }, "faceIndex": { "type": "integer", "minimum": 0 }, "edgeIndices": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "edgeRefs": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "fillet", "chamfer" ] }, "surfaceType": { "type": "string" }, "radiusMm": { "type": [ "number", "null" ], "description": "Fillet radius in mm; null for planar chamfer strips." } }, "required": [ "ref", "faceIndex", "edgeIndices", "edgeRefs", "kind", "surfaceType", "radiusMm" ] } }, "violations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "rule": { "type": "string", "enum": [ "min-radius", "max-radius", "required-edge-break" ] }, "ref": { "type": "string" }, "measuredMm": { "type": "number" }, "limitMm": { "type": [ "number", "null" ] } }, "required": [ "rule", "ref", "measuredMm", "limitMm" ] } }, "unknownRefs": { "type": "array", "items": { "type": "string" } } }, "required": [ "part", "bodyIndex", "edges", "breaks", "violations", "unknownRefs" ] } }, "ok": { "type": "boolean", "description": "Whether the verification ran and passed its gate." }, "source": { "type": "string", "description": "fastener-installation/geometry-quality/assembly-path/edge-radius: local geometry evidence." }, "featureId": { "type": "string", "description": "geometry-quality: measured body feature." }, "frame": { "type": "string", "description": "geometry-quality: model coordinate frame for all locations." }, "thresholds": { "type": "object", "additionalProperties": true, "description": "geometry-quality: effective area/length thresholds and total surface area." }, "tinyFaces": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "geometry-quality: rebuild-scoped face id/index, areaMm2, location." }, "shortEdges": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "geometry-quality: rebuild-scoped edge id/index, lengthMm, parametric midpoint location." }, "degenerateEdges": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "geometry-quality: explicit BREP degenerated pole/parameterization edges, ids and locations; excluded from the physical short-edge gate." }, "symmetry": { "type": "object", "additionalProperties": true, "description": "geometry-quality: sampled-mesh-reflection; planes with passed, maxDeviationMm, rmsDeviationMm, sampleCount and worst-point witnesses, matchingPlanes, toleranceMm and meshDeflectionMm." }, "basis": { "type": "string", "description": "assembly-path: continuous-triangle-mesh." }, "parts": { "type": "array", "description": "assembly-path: initial per-part removable, validDirections, directions with distanceMm, clear and blockingParts, and the state (removable / blocked / unknown / requires-force). A helical fastener also carries fastener { axis, pitchMm, handedness, threadLengthMm, turns }; a modelled tool carries toolReach.", "items": { "type": "object", "additionalProperties": true } }, "model": { "type": "object", "additionalProperties": true, "description": "assembly-path: model stamp — rigid parts, motionModels (straight-line-translation plus helical-screw / requires-force / sampling-search when used), tested directions, toolReach (not-modelled / swept-envelope), gravity (not-modelled / approximate-support-projection) and stability { gravity, contactToleranceMm, seed, seedSource, massBasis } when P3 ran, mesh tessellation and clearance tolerance." }, "blockingGraph": { "type": "object", "additionalProperties": true, "description": "assembly-path: union of the per-direction blocker sets as part -> blocker -> direction edges." }, "sequence": { "type": "object", "additionalProperties": true, "description": "assembly-path: { steps, model, unknown, search?, requiresForce?, toolBlocked?, needsHold? }. Steps are the reverse of the removal peel with insertion direction; a step may be motion: helical (declared fastener), requires-force (press/snap, never simulated) or search, and with stability:true may be stability: stable / needs-hold plus heldBy. Subassembly steps name the unit and its internal build. search lists sampling paths labelled found-by-search (never proven); unknown lists parts that could not be proven (never \"impossible\")." }, "needsHold": { "type": "array", "description": "assembly-path: P3 approximate stability findings. Each entry has part, status: needs-hold, reason, supports, centre of mass and the support polygon when one existed. Not a physics proof.", "items": { "type": "object", "additionalProperties": true } }, "removalOrder": { "type": "array", "description": "assembly-path: deterministic part removal steps, each with part and direction.", "items": { "type": "object", "additionalProperties": true } }, "search": { "type": "array", "description": "assembly-path: non-straight paths found by the sampling fallback. Each entry has part, status: found-by-search and waypoints; it is evidence inside a finite budget, not a proof.", "items": { "type": "object", "additionalProperties": true } }, "toolReach": { "type": "array", "description": "assembly-path: swept tool-envelope results. Each entry has fastener, status clear/tool-blocked, blockers, tool and basis. Only modelled tools appear.", "items": { "type": "object", "additionalProperties": true } }, "toolBlocked": { "type": "array", "description": "assembly-path: fasteners whose modelled tool envelope is obstructed, with the blockers named.", "items": { "type": "object", "additionalProperties": true } }, "requiresForce": { "type": "array", "description": "assembly-path: declared press/snap fits ordered as requires-force steps. Declared, never simulated or proven.", "items": { "type": "object", "additionalProperties": true } }, "requirements": { "type": "object", "additionalProperties": true, "description": "assembly-path: S2 ledger entries for modelled tool reach (pass/fail) and declared forced fits (not-evaluated). Unmodelled tools add nothing." }, "stuckParts": { "type": "array", "items": { "type": "string" }, "description": "assembly-path: remaining parts when no straight removal is available." }, "assembly": { "type": [ "string", "null" ], "description": "Audited lowered assembly." }, "status": { "type": "string", "description": "fastener-installation/edge-radius: pass, fail, partial, or no-coverage; partial/zero coverage cannot pass." }, "counts": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "integer", "minimum": 0 }, "measured": { "type": "integer", "minimum": 0 }, "passed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 } }, "required": [ "requested", "measured", "passed", "failed", "unknown" ], "additionalProperties": false }, { "type": "object", "properties": { "faces": { "type": "integer", "minimum": 0 }, "edges": { "type": "integer", "minimum": 0 } }, "required": [ "faces", "edges" ], "additionalProperties": false } ] }, "stations": { "type": "array", "description": "Explicit fastener-installation stations only; no whole-assembly certification.", "items": { "type": "object", "properties": { "part": { "type": "string" }, "against": { "type": "array", "items": { "type": "string" } }, "engagementPart": { "type": [ "string", "null" ] }, "catalogId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pass", "fail", "partial" ] }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "part": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "not-applicable" ] }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "enum": [ "mm", "deg" ] }, "limit": { "type": [ "number", "null" ] }, "basis": { "type": "string" }, "repairHint": { "type": [ "string", "null" ] } }, "required": [ "name", "part", "status", "value", "unit", "limit", "basis", "repairHint" ], "additionalProperties": false } } }, "required": [ "part", "against", "engagementPart", "catalogId", "status", "metrics" ], "additionalProperties": false } }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "Coverage and physical limitations of the geometry audit." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Verifier diagnostics (most checks)." }, "error": { "type": "string", "description": "Failure message (present on failure)." }, "errorCode": { "type": "string" } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "why_did_this_fail", "description": "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? }.", "inputSchema": { "type": "object", "properties": { "file": { "type": "string" }, "code": { "type": "string" }, "feature_id": { "type": "string" } } }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "feature_id": { "type": "string" }, "chain": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Upstream feature diagnostics in topological order; requested feature last." }, "trace": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every captured feature joined to its call site, AST node range, diagnostics, inputs and dependents." }, "repairRegion": { "type": "object", "additionalProperties": true, "description": "Minimal editable line ranges for the failure: { file, ranges: [{ startLine, endLine, role, featureId?, paramName? }] }." }, "candidates": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Ordered concrete fixes, each with an AST-anchored patch, a predicted effect, and the geometry it was derived from." }, "candidateStatus": { "type": "string", "enum": [ "candidates", "no-automatic-candidate" ], "description": "'no-automatic-candidate' means the region is the whole answer — no mechanical fix exists for that diagnostic kind." }, "candidateReason": { "type": "string", "description": "Why no candidate was derivable." }, "targetDiagnosticId": { "type": "string", "description": "Id of the diagnostic the repair plan targets; pass it to repair_script." }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "set_param", "description": "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). With preview: true it builds the edit in a scratch session instead and returns the diff_geometry summary plus the requirements-ledger and S1 binding diffs (which requirements flip, which margins shrink, which selectors moved or re-bound), without touching the active session, source, revision or caches. A preview whose revised build fails returns ok:false and no diff. Inspect after.requirementsOk to see whether the edit preserves declared intent; preview.ok only says the preview could be computed.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "The .kcad.ts source code." }, "param_name": { "type": "string", "description": "The string literal name of the param (first arg to param())." }, "new_value": { "type": [ "number", "boolean", "string" ], "description": "The new default value: number for numeric params, boolean for boolean params, or string for choice/string/color params (must be one of the declared choices for a choice param; a color param — one whose default is a hex literal — takes '#rrggbb', '#rgb' or a basic CSS colour name and is written back as '#rrggbb')." }, "preview": { "type": "boolean", "description": "S6 edit preview: evaluate the edit in a scratch session and return geometry + requirements-ledger + S1 binding diffs. Writes nothing. Default false (the normal source-edit result)." } }, "required": [ "code", "param_name", "new_value" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." }, "preview": { "type": "boolean", "description": "True when the result came from preview: true (scratch build, nothing written)." }, "geometry": { "type": "object", "additionalProperties": true, "description": "The diff_geometry result for baseline -> revised: { base, revised, bodies, unmatched, summary, diagnostics }. summary carries identical / moved / resized / topologyChanged / unmatched / totalAddedMm3 / totalRemovedMm3 / maxDeviationMm. Absent on a failed preview." }, "requirementsDiff": { "type": "object", "additionalProperties": true, "description": "S2 ledger diff: { ok, changed, summary: { before, after, flipped, marginsShrunk, added, removed }, entries[], flipped[], marginsShrunk[], added[], removed[] }. Each entry has name/source/featureId, optional before/after snapshots (status, measured, limit, margin, message) and { flipped, changed, margin: { before, after, delta, direction: shrink | grow | same | unknown } }." }, "bindings": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "S1 selectors whose bound entity moved or changed: { consumerFeatureId, selectorText, syntax, occurrence, verdict: moved | changed, pairs[{ verdict, reasons, deltas, before?, after? }] }." }, "before": { "type": "object", "additionalProperties": true, "description": "Baseline evaluation summary: { buildOk, exitCode, featureCount, requirementsOk, requirements, diagnostics }." }, "after": { "type": "object", "additionalProperties": true, "description": "Revised evaluation summary: { buildOk, exitCode, featureCount, requirementsOk, requirements, diagnostics }. Check requirementsOk to see whether the edit preserves declared intent." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "add_feature", "description": "Use this when you need to insert a new feature line into a script. Insert a new feature line into a kernelCAD script before the last top-level return statement. Returns the modified code as text plus diagnostics from re-evaluating the result. Side-effect-free. Primitives that accept faceLabels (box, cylinder, extrudeRect, extrudeCircle, extrudePolygon, extrudeRoundedRect) can receive `opts.faceLabels` in the inserted code — use `lookup_api` to see `featureKindFaceLabels` for the full value schema.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "The .kcad.ts source code." }, "feature_code": { "type": "string", "description": "Single-statement source line to insert (e.g. `const hole = cylinder(5, 2).translate(10, 10, -1);`)." } }, "required": [ "code", "feature_code" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "add_surface", "description": "Use this when you need an organic, freeform, or swept shape — a body shell, panel, fairing, ergonomic curve, lens, or sculpted form — authored as a NURBS Surface into the user's .kcad.ts, OR when you need to finish surfaces into a watertight solid or taper faces for moldability. One authoring/finishing path, selected by `kind`:\n- 'nurbs' — insert a nurbsSurface(...) / surfaceFromCurves(...) call. Pass either { controls, degree, weights?, knots?, periodic? } for direct construction, OR { section_sketch_ids } for skinning. Weights are honored: supply rational weights to build exact circles/cylinders/spheres/conics (the surface becomes rational); omit weights for a non-rational surface.\n- 'boundary' — insert a surfaceFromBoundary([c1,c2,c3,c4], opts?) call: one NURBS face through 4 boundary Curve3D refs (bottom, right, top, left in loop order; adjacent endpoints must coincide within 1e-6 mm).\n- 'trim' — insert a `.trimTo()` or `.split()` call. Pass `surface_binding` (the Surface variable name), `by_binding` (the cutter Surface variable name; Shape/Curve3D cutters are deferred to a later slice), and `op: 'trim'` (keep the largest imprinted piece) or `op: 'split'` (return both halves as a `[Surface, Surface]` tuple).\n- 'sew' — insert a `sew([s0, s1, ...], opts?)` call to stitch N surfaces into a closed watertight solid. Pass `surface_bindings` (array of Surface variable names). Use after trim/boundary to close patches into a solid: trim → sew → solid pipeline. Optional `tolerance` (mm, default 1e-6) and `require_closed` (emits feature.surface-sew.open-shell if result is not watertight).\n- 'draft' — insert a `.draft(angleDeg, { face, neutralPlane?, pullDir? })` call to taper the selected face(s) for mold release. Pass `shape_binding`, `angle_deg` (0–90), and `face` (canonical name, label, or FaceQuery descriptor). Lowering emits feature.draft.failed on invalid geometry.\nThe returned Surface produces no Shape until you chain .thicken(t) or .toShape() (do that via add_feature on the binding name). Returns the modified code + diagnostics. Each kind fails closed on its own missing required params.", "inputSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nurbs", "boundary", "trim", "sew", "draft" ], "description": "Which surface-construction or surface-finishing path to use: 'nurbs' | 'boundary' | 'trim' | 'sew' | 'draft'." }, "code": { "type": "string", "description": "Current .kcad.ts source." }, "controls": { "type": "array", "description": "kind:'nurbs' — control-point grid for direct construction (controls[u][v] = [x, y, z], mm).", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } }, "weights": { "type": "array", "description": "kind:'nurbs' — optional rational weights, same grid shape as controls. Ignored in slice-1.", "items": { "type": "array", "items": { "type": "number" } } }, "degree": { "type": "object", "description": "kind:'nurbs' — degrees in U and V; each in [1, nU-1] / [1, nV-1].", "properties": { "u": { "type": "integer", "minimum": 1 }, "v": { "type": "integer", "minimum": 1 } }, "required": [ "u", "v" ] }, "knots": { "type": "object", "description": "kind:'nurbs' — optional explicit knot vectors; missing => clamped uniform inferred.", "properties": { "u": { "type": "array", "items": { "type": "number" } }, "v": { "type": "array", "items": { "type": "number" } } } }, "periodic": { "type": "object", "description": "kind:'nurbs' — optional periodic flags per parametric direction.", "properties": { "u": { "type": "boolean" }, "v": { "type": "boolean" } } }, "section_sketch_ids": { "type": "array", "description": "kind:'nurbs' — existing sketch FeatureIds (2 or more) to skin a surface through, in order.", "items": { "type": "string" } }, "curve_bindings": { "type": "array", "description": "kind:'boundary' — tuple of 4 existing Curve3D variable names (bottom, right, top, left) declared earlier in the source.", "items": { "type": "string" }, "minItems": 4, "maxItems": 4 }, "continuity": { "description": "kind:'boundary' — continuity grade applied to every edge ('C0' | 'C1' | 'C2'), or an array of 4 grades (one per edge, bottom/right/top/left order). Default 'C0'.", "oneOf": [ { "type": "string", "enum": [ "C0", "C1", "C2" ] }, { "type": "array", "items": { "type": "string", "enum": [ "C0", "C1", "C2" ] }, "minItems": 4, "maxItems": 4 } ] }, "sampling": { "type": "integer", "minimum": 1, "description": "kind:'boundary' — points sampled along each boundary (default 15)." }, "binding_name": { "type": "string", "description": "JS const name for the new binding (kind:'nurbs' default surface_; kind:'boundary' default _surface_; kind:'trim' default _trimmed_; kind:'sew' default _sewn_; kind:'draft' default _drafted_)." }, "surface_binding": { "type": "string", "description": "kind:'trim' — JS variable name of the Surface to trim/split (must be declared in source)." }, "by_binding": { "type": "string", "description": "kind:'trim' — JS variable name of the cutter Surface (must be declared in source). Shape/Curve3D cutters are deferred." }, "op": { "type": "string", "enum": [ "trim", "split" ], "description": "kind:'trim' — 'trim' discards the smaller half (calls .trimTo()); 'split' retains both halves (calls .split())." }, "surface_bindings": { "type": "array", "description": "kind:'sew' — JS variable names of the surfaces to stitch into a solid (each must be declared in source).", "items": { "type": "string" }, "minItems": 1 }, "tolerance": { "type": "number", "description": "kind:'sew' — edge-merging tolerance in mm (default 1e-6). Edges within this distance are merged." }, "require_closed": { "type": "boolean", "description": "kind:'sew' — when true the lowerer emits feature.surface-sew.open-shell if the stitched result is not a watertight solid." }, "shape_binding": { "type": "string", "description": "kind:'draft' — JS variable name of the Shape to taper (must be declared in source)." }, "angle_deg": { "type": "number", "minimum": 0, "maximum": 90, "description": "kind:'draft' — draft angle in degrees [0, 90]. The face is tapered outward by this angle relative to the pull direction." }, "face": { "type": "string", "description": "kind:'draft' — face selector for the face(s) to taper. Accepts a canonical name (top/bottom/front/back/left/right), a user label declared via faceLabels, or a FaceQuery descriptor string." }, "neutral_plane": { "type": "string", "description": "kind:'draft' — parting-line face (the plane where drafted faces remain fixed). Defaults to `face` if omitted." }, "pull_dir": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "kind:'draft' — demoulding direction as [x, y, z]. Defaults to the face normal at lower time." } }, "required": [ "kind", "code" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "add_curve", "description": "Use this when you need a freeform/organic 3D curve — a body feature line, brow, spine rail, or G2 blend between panels — authored as a Curve3D into the user's .kcad.ts immediately before the last top-level return. One authoring path, selected by `kind`:\n- 'nurbs' — insert a `nurbsCurve(controlPoints, opts?)` declaration. Pass `controlPoints` as a Vec3[] (mm, at least 2 points). Optional NURBS knobs: `degree` (default 3), rational `weights`, explicit `knots`, `closed`.\n- 'hermite' — insert a `hermiteG2(a, b)` declaration: a quintic Hermite curve interpolating two endpoints with matching positions, tangents, and (optional) curvatures — bridges two curves with G2 continuity. Each endpoint is `{ point: Vec3, tangent: Vec3, curvature?: Vec3 }` in mm; tangent magnitude ~ chord length; curvature defaults to [0,0,0] (G1-only).\nThe returned binding has type Curve3D (peer to Shape / Surface) — consume it via `add_variable_sweep` (spine input), `add_surface({ kind: 'boundary' })` (boundary curve), or downstream Curve3D-accepting features. Returns the modified code + diagnostics from re-evaluating. Side-effect-free. Each kind fails closed on its own missing required params.", "inputSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nurbs", "hermite" ], "description": "Which curve-construction path to use." }, "code": { "type": "string", "description": "The .kcad.ts source code." }, "controlPoints": { "type": "array", "description": "kind:'nurbs' — control points as Vec3 triples in mm; at least 2 entries.", "items": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } }, "degree": { "type": "integer", "minimum": 1, "description": "kind:'nurbs' — curve degree; default 3 (cubic)." }, "weights": { "type": "array", "description": "kind:'nurbs' — optional rational weights, one per control point (same length as controlPoints).", "items": { "type": "number" } }, "knots": { "type": "array", "description": "kind:'nurbs' — optional explicit knot vector; missing => clamped-uniform inferred.", "items": { "type": "number" } }, "closed": { "type": "boolean", "description": "kind:'nurbs' — optional periodic/closed-curve flag." }, "a": { "type": "object", "description": "kind:'hermite' — start endpoint.", "properties": { "point": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Endpoint position in mm." }, "tangent": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "First derivative of the curve at this endpoint." }, "curvature": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Optional second derivative; defaults to [0, 0, 0] (G1-only)." } }, "required": [ "point", "tangent" ] }, "b": { "type": "object", "description": "kind:'hermite' — end endpoint.", "properties": { "point": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "tangent": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "curvature": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } }, "required": [ "point", "tangent" ] }, "binding_name": { "type": "string", "description": "JS const name for the new Curve3D binding (default: _curve_)." } }, "required": [ "kind", "code" ], "allOf": [ { "if": { "properties": { "kind": { "const": "nurbs" } } }, "then": { "required": [ "controlPoints" ] } }, { "if": { "properties": { "kind": { "const": "hermite" } } }, "then": { "required": [ "a", "b" ] } } ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "add_path_segment", "description": "Use this when you need a freeform/organic 2D outline — an eyewear brow, ergonomic grip, sneaker midsole, or body silhouette — by appending a curved segment to an existing PathBuilder chain on the named `chain_anchor` variable. The call is injected at the END of the chain, immediately before any `.close()`. One segment kind, selected by `kind`:\n- 'spline' — `.spline(points, opts?)`: interpolates through every `points` waypoint (Vec2[] mm, >= 2 entries; points[0] must match current pen position). Optional `tension`, and `startTangent`/`endTangent` 2D direction vectors that constrain the first-derivative direction at the endpoints (magnitude normalised internally). Use for organic 2D outlines (eyewear brow, ergonomic handle, sneaker midsole).\n- 'nurbs' — `.nurbsSegment(controlPoints, opts?)`: explicit B-spline net (Vec2[] mm, >= degree+1 entries; controlPoints[0] must match pen; pen ends at controlPoints[N-1]). Optional `degree` (default 3), rational `weights` (strictly positive), explicit `knots` (length = controlPoints.length + degree + 1).\n- 'hermite' — `.hermiteG2(a, b)`: each endpoint `{ point: Vec2, tangent: Vec2, curvature?: Vec2 }` in mm (a.point must match pen; pen ends at b.point). `curvature` defaults to [0,0] (G1); pass matching curvatures for G2 blends. Tangent magnitude is the first derivative (~ chord length), NOT unit length.\nReturns the modified code + diagnostics from re-evaluating. Side-effect-free. Each kind fails closed on its own missing required params.", "inputSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "spline", "nurbs", "hermite" ], "description": "Which path-segment kind to append." }, "code": { "type": "string", "description": "The .kcad.ts source code." }, "chain_anchor": { "type": "string", "description": "JS identifier of an existing PathBuilder binding (e.g. `const brow = path().moveTo(0,0)`)." }, "points": { "type": "array", "description": "kind:'spline' — waypoints as Vec2 pairs in mm; at least 2 entries; first must match current pen position.", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "minItems": 2 }, "tension": { "type": "number", "description": "kind:'spline' — optional Catmull-Rom-style stiffness; forwarded to the underlying B-spline approximation." }, "startTangent": { "type": "array", "description": "kind:'spline' — optional [x, y] direction vector at points[0]. Magnitude is normalised internally; direction matters.", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "endTangent": { "type": "array", "description": "kind:'spline' — optional [x, y] direction vector at points[N-1]. Magnitude is normalised internally; direction matters.", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "controlPoints": { "type": "array", "description": "kind:'nurbs' — control-net vertices as Vec2 pairs in mm; at least degree+1 entries.", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "degree": { "type": "integer", "minimum": 1, "description": "kind:'nurbs' — B-spline degree (default 3)." }, "weights": { "type": "array", "description": "kind:'nurbs' — optional rational weights (one per control point; strictly positive).", "items": { "type": "number" } }, "knots": { "type": "array", "description": "kind:'nurbs' — optional explicit knot vector; length must equal controlPoints.length + degree + 1.", "items": { "type": "number" } }, "a": { "type": "object", "description": "kind:'hermite' — start endpoint; point must match current pen position within 1e-6 mm.", "properties": { "point": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "tangent": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "curvature": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "point", "tangent" ] }, "b": { "type": "object", "description": "kind:'hermite' — end endpoint.", "properties": { "point": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "tangent": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "curvature": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "point", "tangent" ] }, "binding_name": { "type": "string", "description": "Reserved for future use; the segment injection mutates the chain anchor in place." } }, "required": [ "kind", "code", "chain_anchor" ], "allOf": [ { "if": { "properties": { "kind": { "const": "spline" } } }, "then": { "required": [ "points" ] } }, { "if": { "properties": { "kind": { "const": "nurbs" } } }, "then": { "required": [ "controlPoints" ] } }, { "if": { "properties": { "kind": { "const": "hermite" } } }, "then": { "required": [ "a", "b" ] } } ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "trace_from_image", "description": "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 `kernelcad-trace-from-image` skill for the conversion-to-mm pipeline.", "inputSchema": { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "URL or path to the reference image. Supports file://, http(s)://, data:image/...;base64,..., or a bare filesystem path." }, "hint": { "type": "string", "description": "Optional free-text hint forwarded to vision-LLM backends (e.g. \"a pair of eyewear; trace the upper brow only\")." }, "features": { "type": "array", "description": "Features to trace. Defaults to a single { label: \"silhouette\", kind: \"silhouette\" } when omitted.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Caller-chosen identifier (echoed in the response)." }, "kind": { "type": "string", "enum": [ "silhouette", "curve", "point", "bbox" ], "description": "Geometric shape of the requested feature." }, "region": { "type": "string", "description": "Optional free-text region hint forwarded to vision-LLM backends; ignored by opencv." } }, "required": [ "label", "kind" ] } }, "maxWaypointsPerFeature": { "type": "integer", "description": "Cap on waypoints per feature. Defaults to 12 (suitable for medium-inflection outlines).", "minimum": 2 }, "backend": { "type": "string", "enum": [ "opencv", "vision-llm", "hybrid", "auto" ], "description": "Force a specific backend; default `auto` routes by corner-color stddev." }, "scaleAnchor": { "type": "object", "description": "Pixel-to-real-world scale anchor: two measured points on the image. Absent -> the returned ledger's `scale` fact is `missing`.", "properties": { "pixelDistance": { "type": "number", "description": "Distance in pixels between the two measured points." }, "realDistance": { "type": "number", "description": "The same distance in real-world units." }, "unit": { "type": "string", "enum": [ "mm", "cm", "in" ] } }, "required": [ "pixelDistance", "realDistance", "unit" ] }, "priors": { "type": "array", "description": "Caller-supplied category-norm defaults (e.g. wall thickness) recorded verbatim as `assumed` ledger facts.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "statement": { "type": "string" }, "value": { "type": [ "string", "number", "boolean", "array", "object" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "id", "statement", "value", "confidence" ] } }, "validate": { "type": "string", "enum": [ "warn", "error" ], "description": "Assumption-ledger strictness. `warn` (default) never blocks. `error` fails the call when any `missing` ledger fact (e.g. scale) is still open." } }, "required": [ "imageUrl" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": true }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "features": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Traced features with normalized [0..1] waypoints + confidence." }, "imageDims": { "type": "array", "items": { "type": "number" }, "description": "Pixel dimensions [width, height] of the source image." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "ledger": { "type": "object", "additionalProperties": true, "description": "Assumption ledger: { facts, scale?, unresolvedCount } classifying every fact as visible/inferred/assumed/missing." } }, "required": [ "ok", "features", "imageDims", "diagnostics", "ledger" ], "additionalProperties": true } }, { "name": "add_variable_sweep", "description": "Use this when you need an organic swept solid whose cross-section changes along its length — a tapering body, horn, bottle, handle, ring band, fairing, or duct — authored as a variable-section sweep along a spine. Inserts `variableSweep(spine, sections, opts?)` into the .kcad.ts `code` immediately before the last top-level return (an empty `code` starts a new script that returns the sweep). Spine: EITHER `spine_points` ([[x,y,z], ...] in mm, interpolated with spline3d; `spine_closed: true` closes the loop for a ring) OR `spine_binding` (an existing Curve3D / Sketch / Vec3[] variable). Each section: `t` in [0, 1] plus a profile — inline `radius` (circle) or `width` + `height` (rectangle), or `profile_binding` (an existing Sketch); profiles are centred on the spine and turned to face along it. Sections are strictly increasing in t, first t=0, last t=1 (omit t on every section to space them evenly). On a closed spine t=1 is the seam and reuses the t=0 profile. Example: { code, spine_points: [[0,0,0],[0,10,30],[0,0,60]], sections: [{ t: 0, radius: 8 }, { t: 0.5, radius: 10 }, { t: 1, radius: 4 }] }. Returns the modified code, diagnostics from re-evaluating it, and `sweep` { volumeMm3, bbox } measured from the built solid (ok:false when the sweep built nothing). The result is a Shape binding: return it, or chain `.union(...)` etc. via add_feature. Orientation is not exposed by this MCP tool until runtime orientation support is wired. Side-effect-free.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "The .kcad.ts source code (\"\" for a new script)." }, "spine_points": { "type": "array", "description": "Inline spine: at least 2 [x, y, z] points in mm, interpolated with spline3d. Use this OR spine_binding.", "items": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } }, "spine_closed": { "type": "boolean", "description": "With spine_points: close the spline into a loop (ring band, loop handle)." }, "spine_binding": { "type": "string", "description": "Existing variable name for a Curve3D / Sketch / Vec3[] declared earlier in the source. Use this OR spine_points." }, "sections": { "type": "array", "description": "Varying cross-sections along the spine; at least 2 entries, strictly increasing in `t`, first t=0, last t=1.", "items": { "type": "object", "properties": { "t": { "type": "number", "description": "Spine parameter in [0, 1]." }, "radius": { "type": "number", "description": "Inline circular profile radius, mm." }, "width": { "type": "number", "description": "Inline rectangular profile width, mm (with height)." }, "height": { "type": "number", "description": "Inline rectangular profile height, mm (with width)." }, "profile_binding": { "type": "string", "description": "Existing Sketch variable name for this section (instead of radius / width+height)." } } } }, "closed": { "type": "boolean", "description": "Optional closed-sweep flag." }, "continuity": { "type": "string", "enum": [ "C0", "C1", "C2" ], "description": "Inter-section continuity; default 'C1'." }, "binding_name": { "type": "string", "description": "JS const name for the new Shape binding (default: _sweep_)." } }, "required": [ "code", "sections" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "add_text", "description": "Use this when you need to author text into a kernelCAD script before the last top-level return. One authoring path, selected by `mode`:\n- 'sketch' — insert a sketch.text(...) call. The emitted sketch is chainable: pair with subsequent .extrude(...) / cut(...) edits to land an engraved or raised text feature.\n- 'emboss' — insert a `.embossText({...})` chained call onto an existing Shape `target`. Use for engraved brand text on faces (Ray-Ban temple, CE mark, model number). `depth > 0` raises text out of the face; `depth < 0` engraves text into the face. Lowers via replicad drawText → sketchOnFace → extrude → fuse|cut.\nDefault font is the runtime-bundled Liberation Sans. Side-effect-free; returns the modified code plus diagnostics from re-evaluating. Each mode fails closed on its own missing required params.", "inputSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sketch", "emboss" ], "description": "Which text-authoring path to use." }, "code": { "type": "string", "description": "The .kcad.ts source code." }, "content": { "type": "string", "description": "mode:'sketch' — text content (UTF-8, non-empty, non-whitespace)." }, "size": { "type": "number", "description": "mode:'sketch'|'emboss' — glyph cap height in mm (positive finite)." }, "font": { "type": "string", "description": "mode:'sketch' — optional logical font name or .ttf file path; defaults to bundled Liberation Sans." }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "mode:'sketch' — horizontal alignment relative to position (default left); mode:'emboss' — relative to the UV anchor (default center)." }, "position": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "mode:'sketch' — [x, y] anchor in mm. Default [0, 0]." }, "rotation": { "type": "number", "description": "mode:'sketch' — CCW rotation in degrees around position (default 0); mode:'emboss' — CCW rotation in the face tangent plane (default 0)." }, "bindAs": { "type": "string", "description": "mode:'sketch' — emits `const = sketch.text(...)`; mode:'emboss' — emits `const = .embossText(...);`." }, "target": { "type": "string", "description": "mode:'emboss' — variable name of the Shape to chain onto (inserted verbatim)." }, "textContent": { "type": "string", "description": "mode:'emboss' — text content (UTF-8, non-empty, non-whitespace)." }, "depth": { "type": "number", "description": "mode:'emboss' — signed extrusion depth in mm: positive emboss out, negative engrave in. Must be non-zero." }, "face": { "type": "string", "description": "mode:'emboss' — target face — canonical name ('top'/'bottom'/'left'/'right'/'front'/'back') or label." }, "fontFamily": { "type": "string", "description": "mode:'emboss' — optional logical font name or .ttf file path; defaults to bundled Liberation Sans." }, "anchorU": { "type": "number", "description": "mode:'emboss' — U anchor in [0, 1] face-local (0=umin, 0.5=centre, 1=umax). Default 0.5." }, "anchorV": { "type": "number", "description": "mode:'emboss' — V anchor in [0, 1] face-local. Default 0.5." }, "scaleMode": { "type": "string", "enum": [ "original", "native", "bounds" ], "description": "mode:'emboss' — Drawing.sketchOnFace scaling mode. Default original." } }, "required": [ "mode", "code" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "project_curve", "description": "Use this when you need to wrap a 2D closed curve onto a 3D face. Insert a `.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.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "The .kcad.ts source code." }, "target": { "type": "string", "description": "Variable name of the Shape to chain onto." }, "commands": { "type": "array", "description": "Closed 2D path to wrap onto the face, as plain-number commands. Must start with a `moveTo` and end with a `close` (e.g. [{kind:\"moveTo\",x:0,y:0},{kind:\"lineTo\",x:2,y:0},{kind:\"lineTo\",x:2,y:2},{kind:\"close\"}]).", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "moveTo", "lineTo", "close" ] }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "kind" ] } }, "face": { "type": "string", "description": "Target face — canonical name or label." }, "scaleMode": { "type": "string", "enum": [ "original", "native", "bounds" ], "description": "Drawing.sketchOnFace scaling mode. Default original." }, "asEdge": { "type": "boolean", "description": "Open-wire (edge) projection. NOT IMPLEMENTED — rejected at edit time. Use a closed-curve projection (omit asEdge)." }, "bindAs": { "type": "string", "description": "Optional local variable name; emits `const = .projectCurve(...);`." } }, "required": [ "code", "target", "commands", "face" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "add_pattern_feature", "description": "Use this when you need to repeat a feature in a pattern. Insert a Shape.patternLinear / .patternCircular / .patternGrid call into a kernelCAD script before the last top-level return. Pass structured args (kind + the matching spec object). Returns the modified code plus diagnostics from re-evaluating. Side-effect-free. The pattern feature is a single editable unit; pattern-instance face refs resolve via `_pattern_` on the pattern feature's lineage. Geometric note: pattern is implemented as cumulative boolean union of transformed source copies — additive features (boxes, ribs, fins, spokes) pattern cleanly; patterning a subtractive feature (hole, cutout) only preserves the per-instance void when adjacent bodies are disjoint.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "The .kcad.ts source code." }, "target": { "type": "string", "description": "Variable name of the Shape to pattern (inserted verbatim as the LHS receiver)." }, "kind": { "type": "string", "enum": [ "linear", "circular", "grid" ] }, "linear": { "type": "object", "description": "Required when kind=linear.", "properties": { "count": { "type": "integer", "minimum": 2 }, "direction": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "spacing": { "type": "number" } }, "required": [ "count", "direction", "spacing" ] }, "circular": { "type": "object", "description": "Required when kind=circular.", "properties": { "count": { "type": "integer", "minimum": 2 }, "axis": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "angleDeg": { "type": "number", "description": "Optional; defaults to 360." } }, "required": [ "count", "axis" ] }, "grid": { "type": "object", "description": "Required when kind=grid.", "properties": { "x": { "type": "object", "description": "First grid axis.", "properties": { "count": { "type": "integer", "minimum": 2 }, "direction": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "spacing": { "type": "number" } }, "required": [ "count", "direction", "spacing" ] }, "y": { "type": "object", "description": "Second grid axis.", "properties": { "count": { "type": "integer", "minimum": 2 }, "direction": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "spacing": { "type": "number" } }, "required": [ "count", "direction", "spacing" ] } }, "required": [ "x", "y" ] }, "assign_to": { "type": "string", "description": "Optional const-binding name; emits `const = .patternX(...);`. Omit for statement form." } }, "required": [ "code", "target", "kind" ], "allOf": [ { "if": { "properties": { "kind": { "const": "linear" } } }, "then": { "required": [ "linear" ] } }, { "if": { "properties": { "kind": { "const": "circular" } } }, "then": { "required": [ "circular" ] } }, { "if": { "properties": { "kind": { "const": "grid" } } }, "then": { "required": [ "grid" ] } } ] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "remove_feature", "description": "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.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "The .kcad.ts source code." }, "match": { "type": "string", "description": "A substring that uniquely identifies the line to remove (e.g. `const hole = cylinder(5,`)." } }, "required": [ "code", "match" ] }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false }, "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the edit applied and re-evaluated cleanly." }, "viewerUrl": { "type": "string", "description": "Same live Studio link when this edit built a replacement model." }, "viewerError": { "type": "string", "description": "Viewer provisioning error, independent of edit diagnostics." }, "viewerMode": { "type": "string", "enum": [ "hosted" ], "description": "Hosted mode uses open_in_studio instead of a process-local viewer." }, "viewerHint": { "type": "string", "description": "How to view the built model in hosted Studio." }, "step": { "type": "object", "additionalProperties": true, "description": "Per-step build validity, volume and paired local PNG paths with a shared iso frame; unavailable snapshots report an error. Not a topology certificate. Omitted on dry runs." }, "sceneSummary": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "BREP validity, independent of DFM/mechanism/tool success; null if unchecked." }, "volume": { "type": [ "number", "null" ], "description": "Volume in mm³; assembly parts summed, including overlaps." }, "faceCount": { "type": [ "integer", "null" ], "description": "BREP faces, summed per assembly part; not mesh triangles." }, "size": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3, "description": "Conservative world AABB size [x,y,z] in mm." } }, "required": [ "valid", "volume", "faceCount", "size" ], "additionalProperties": false }, "new_code": { "type": "string", "description": "Modified .kcad.ts source (present on success). Caller persists it." }, "binding_name": { "type": "string", "description": "JS const name bound to the new construct (when one was created)." }, "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Diagnostics from re-evaluating the modified source." }, "error": { "type": "string", "description": "Failure message (present when ok is false)." } }, "required": [ "ok" ], "additionalProperties": true } }, { "name": "query", "description": "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'):\n- 'evaluate' — list the faces a Query matches ({ query }). Pass expect:'unique' to assert exactly-one.\n- 'resolve' — resolve one ref to one face ({ ref }).\n- 'lineage' — the creating/modifying history of a face ({ ref }; feature_id defaults to the last feature).\nQuery forms (faces only; edge/vertex kinds return query.unsupported-entity-type):\n- a bare face label: 'top', 'bottom', 'left', 'right', 'front', 'back', or a hole/cutout slot like 'wall'.\n- @kc[/face/