docs: agent skills for modeling and editing through MCP (#728)
Two agent skills for modeling and editing through the MCP server, with a command reference and model-only screenshot examples.
This commit is contained in:
1 parent
293d660d6c
commit
be55a49b04
6 files changed
+464
No files matched your search
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: solidcraft-modeling
|
||||
description: Use when building a new part, enclosure, bracket, plate, flange or any other 3D solid in SolidCraft through its MCP server (tools such as batch, execute, measure, screenshot), or when a SolidCraft session is using many tool calls or tokens.
|
||||
---
|
||||
|
||||
# SolidCraft modeling
|
||||
|
||||
## Overview
|
||||
Work the part out as numbers first. Then build it in a few large `batch` calls, and check each stage with `measure` against values you computed yourself. A clean build takes 3-4 build batches, about 10-13 calls with the checks. Command shapes, plane axes, ids, reply sizes and known traps are in `reference.md` next to this file, so you do not need to explore the command catalog.
|
||||
|
||||
## Before the first call
|
||||
1. Read `reference.md`.
|
||||
2. Run `inspect_design {"measure":false,"sketches":false}`, even when you think the session is empty.
|
||||
- The SolidCraft server's instructions end with `Backend: connected to the SolidCraft app` when it drives the user's open app, and with `Backend: headless` otherwise.
|
||||
- If the design has timeline features, ask before calling `new_design` or `open`, because both discard unsaved work. You can also build into the open design.
|
||||
3. Write a plan:
|
||||
- the parameters
|
||||
- the placement: centre the part on the origin so patterns and mirrors can work from the planes
|
||||
- every feature, with the world point you will use for each edge or face pick
|
||||
- the expected volume and bounding box
|
||||
|
||||
## Build
|
||||
- **Stages:** use one batch per stage:
|
||||
1. parameters, sketch, dimensions, finish and the first feature
|
||||
2. fillets and shell
|
||||
3. holes, cuts and patterns
|
||||
- **Failures:** a batch is all-or-nothing. On failure, read `failed.index` and `failed.error`, fix that step only, and send the batch again.
|
||||
- **Risky steps:** put a risky step in a batch of its own, so a failure does not roll back the work around it. This covers booleans between curved faces that touch, and anything you have not done before.
|
||||
- **Reply size:** in large designs, pass `"verbose": false` to `batch` and `execute`.
|
||||
- **Sketch ids are predictable,** so later steps in the same batch can use them:
|
||||
- Each sketch counts each kind from 1 (`l1`, `c1`, `a1`, `p1`).
|
||||
- Count what the earlier steps of that sketch created. For example, `rectangle.center` makes `l1`-`l6` and `p1`-`p5`.
|
||||
- Do not split a batch just to read ids back.
|
||||
- **Positions that must follow a parameter** come from:
|
||||
- sketch dimensions to `"origin"` with expression values (`"w/2 - wall - 6"`)
|
||||
- expression fields such as `solid.cylinder base:["w/2-6","d/2-6","wall"]`
|
||||
|
||||
A plain number never follows a parameter.
|
||||
- **Repeats:** `solid.pattern.rectangular` takes expression spacing; `solid.mirror` takes `XY`/`XZ`/`YZ`, a construction plane or `{origin, normal}`. A mirror or pattern feature cannot be mirrored or patterned again.
|
||||
- **Edge and face picks** snap to the nearest edge or face. There is no distance limit and no error, so compute the exact midpoint from your geometry (the vertical corner edge of a centred box is `[w/2, d/2, h/2]`).
|
||||
- Picks must be plain numbers.
|
||||
- A pick is resolved once and then follows its edge when parameters change.
|
||||
- **Profiles:** extrude takes every region by default. For a ring or a boss with a hole, pass `profiles`.
|
||||
- **Order:** fillet the outside edges before you shell, so the shell follows the fillets.
|
||||
|
||||
## Verify
|
||||
- **Each stage:** run `measure {}` (about 1 KB) and compare the volume, bbox and face count with your numbers. A cut or hole that leaves the volume unchanged has missed, even though it reported success.
|
||||
- **Timeline health:** `inspect_design {"measure":false,"sketches":false}` shows each feature's `error` and `warning`.
|
||||
- **Parameter test:** run `set_parameter`. Expect `errors: []`, then `measure` again; the COM and bbox should move by the amounts you computed.
|
||||
- **Positions:** `measure` does not say where a feature sits.
|
||||
- On an asymmetric part, check the COM shift you computed.
|
||||
- On a symmetric part (a mirrored or patterned layout) the COM does not move, so take a top-view screenshot and compare distances in pixels against a known size.
|
||||
- `body_topology` is a last resort: it costs 25-45 KB and splits cylinders into half faces.
|
||||
- **Final look:** one `screenshot {"source":"model","view":"iso","width":480,"height":320}`. Use `"view":"top"` for features inside walls, which the iso view hides.
|
||||
- `width` and `height` apply only to model renders.
|
||||
- When the server is bridged, `source` defaults to the whole app window and `view` also turns the user's camera, so pass `"source":"model"` and leave out `view` unless the user wants the camera moved.
|
||||
|
||||
## Finish
|
||||
`export {path}` writes `.step` for CAD or `.3mf`/`.stl` for printing. `save {path}` writes `.solidcraft`.
|
||||
|
||||
## Red flags
|
||||
|
||||
| Thought | Do instead |
|
||||
|---|---|
|
||||
| "List all commands first" | `reference.md`, or `list_commands {"filter":"<distinctive word>"}`. The unfiltered list is over 100 KB. |
|
||||
| "Check positions with body_topology" | `measure` COM and bbox against your numbers. |
|
||||
| "Inspect the sketch" | `sketch.solve` returns dof and the profile count in under 100 bytes. Run `sketch.inspect` on its own, never inside a big batch. |
|
||||
| "new_design for a clean start" | When the server is bridged, ask first. |
|
||||
| "It reported ok, so it worked" | Only a `measure` that matches the computed values counts. |
|
||||
@@ -0,0 +1,155 @@
|
||||
# SolidCraft command reference for agents
|
||||
|
||||
These are the shapes of the commands a part build needs, so an agent rarely has to call `list_commands`. The worked example at the end runs in CI (`skill_reference_example_builds_as_documented` in `crates/mcp/src/tests.rs`).
|
||||
|
||||
- Lengths are in mm.
|
||||
- Angles inside expressions take units: `"30 deg"`.
|
||||
- Any numeric field can be an expression that names parameters: `"w/2 - wall - 6"`.
|
||||
|
||||
## Sketch planes: where sketch (x, y) lands in the world
|
||||
|
||||
| `plane` | sketch x | sketch y | normal (+distance) |
|
||||
|---|---|---|---|
|
||||
| `"XY"` | +X | +Y | +Z |
|
||||
| `"XZ"` | +X | **-Z** | +Y |
|
||||
| `"YZ"` | +Y | +Z | +X |
|
||||
| `{origin, x_dir, y_dir}` | x_dir | y_dir | x_dir x y_dir |
|
||||
|
||||
- `offset: "expr"` on `sketch.create` moves the plane along its normal and follows parameters.
|
||||
- **Front wall (-Y) of a part centred on the origin:**
|
||||
- Sketch on `{"plane":"XZ","offset":"-d/2"}`.
|
||||
- Draw a feature at height z at sketch y = **-z**.
|
||||
- A cut with a positive distance goes into the wall.
|
||||
- **Top face:** sketch on `{"plane":"XY","offset":"h"}`.
|
||||
- **Hole direction:** `solid.hole {sketch}` drills from the sketch plane along -normal. A hole sketch at z=0 under a part drills into empty space and still reports success, so put the sketch on the top face.
|
||||
|
||||
## Ids
|
||||
|
||||
- **Numbering:** every creator returns `created: {points, curves, constraints, dimensions}`. Ids are stable and numbered per sketch.
|
||||
- **Curves:** `l1`, `c1`, `a1`.
|
||||
- **Points:** `p1`, `l1.start`, `l1.end`, `c1.center`, `a1.center`, and the sketch origin `"origin"`.
|
||||
- **Rectangles:** `sketch.rectangle.*` also returns `sides {bottom,right,top,left}` and `corners {bottom_left,...}`.
|
||||
- `rectangle.center` adds 2 construction diagonals, so each corner joins 3 lines.
|
||||
- `sketch.fillet {point}` therefore fails on its corners. Use `{a:"l1", b:"l4", radius}` or the 3D `solid.fillet`.
|
||||
- **Slots:** `sketch.slot.overall` and `sketch.slot.center_to_center` create curves `l1, a1, l2, a2` and points `p1`-`p4`, `a1.center`, `a2.center`.
|
||||
- The `length` role of `slot.overall` is the overall length. The arc centres are at ±(length/2 - width/2).
|
||||
- After `length` and `width`, 3 dof remain. To remove them, dimension `origin` to `a1.center` horizontally and vertically, and `origin` to `a2.center` vertically.
|
||||
- `sketch.slot.center_point` creates no centre point. Dimension an arc centre instead.
|
||||
- **Circles:** `sketch.circle.center` creates `c1` and `c1.center`, and no `p` point.
|
||||
- **Dimensions** share the `k` counter with constraints.
|
||||
- **Constraints can add curves:** a constraint about an axis, such as `sketch.constraint.symmetry` with `line:"y"`, adds a construction line and so takes the next `l` id. Read `created` before you count further.
|
||||
- **Over-constraining** is refused with `that conflicts with the sketch: neither entity can move to satisfy it`. For example, symmetry already makes two circles equal.
|
||||
|
||||
## Dimensions
|
||||
|
||||
```json
|
||||
{"command":"sketch.dimension","params":{"entities":["origin","c1.center"],"type":"horizontal","value":"w/2 - wall - 6"}}
|
||||
{"command":"sketch.dimension","params":{"entities":["c1"],"type":"diameter","value":"6"}}
|
||||
{"command":"sketch.dimension","params":{"entities":["l1"],"value":"w"}}
|
||||
```
|
||||
|
||||
Distances are unsigned. Draw the geometry on the correct side first, and the dimension keeps it there.
|
||||
|
||||
`sketch.draw.dimensioned` creates a shape and its dimensions in one undo step. The dimension roles depend on the creator:
|
||||
|
||||
| Creator | Roles |
|
||||
|---|---|
|
||||
| `line` (exactly 2 points) | `length`, `angle` |
|
||||
| `rectangle.*` | `width`, `height` |
|
||||
| `circle.*` | `radius` or `diameter` |
|
||||
| `arc.center_point` | `radius`, `sweep` |
|
||||
| `slot.center_to_center`, `slot.overall` | `length`, `width` |
|
||||
| `polygon.*` | `radius` |
|
||||
|
||||
```json
|
||||
{"command":"sketch.draw.dimensioned","params":{"command":"sketch.rectangle.center","params":{"center":[0,0],"corner":[35,25]},"dimensions":{"width":"w","height":"d"}}}
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
| Command | Minimal params | Traps |
|
||||
|---|---|---|
|
||||
| `solid.extrude` | `distance` | `profiles` defaults to **every region**, so two concentric circles give a solid disc. Pick regions with `[{"point":[x,y]}]` or `[index]`. Other options: `operation` (new/join/cut/intersect/auto), `direction` (positive/negative/symmetric), `through_all: true`, `start_offset`. A cut that misses reports success. |
|
||||
| `solid.box` | `length`, `width`, `height` | `center:[x,y,z]` or `corner`. The quickest way to block out a part. |
|
||||
| `solid.cylinder` | `radius` or `diameter`, `height` | `base` is the centre of the bottom (default origin), `axis` defaults to `Z`. Expressions work in `base`. Always pass `operation`. |
|
||||
| `sketch.slot.overall` / `sketch.slot.center_to_center` | `p0`, `p1` (overall ends / arc centres), `width` | Ids and dof are in the "Ids" section above. |
|
||||
| `solid.fillet` / `solid.chamfer` | `edges:[[x,y,z]]`, `radius` / `distance` | The pick snaps to the **nearest** edge, with no distance limit and no error, so check that the face count changed. One pick takes the whole tangent chain: a rounded rim needs 1 point, not 8. |
|
||||
| `solid.shell` | `faces:[[x,y,z]]`, `thickness` | A point on each face to remove. Fillet first. |
|
||||
| `solid.hole` | `position:[x,y,z]` on a face + `diameter`, or `sketch` (+ `points`) | `clearance:"M3"`. `depth` defaults to through all. `type` is one of simple/drilled/counterbore/countersink. A `countersink` needs `cs_diameter` and `cs_angle`; a `counterbore` needs `cb_diameter` and `cb_depth`. `position` is a fixed point. |
|
||||
| `solid.pattern.rectangular` | `features`, `dir1`, `count1`, `spacing1` (+ `dir2`, `count2`, `spacing2`) | Spacing takes expressions and follows parameters. |
|
||||
| `solid.pattern.circular` | `features`, `axis` (`"Z"` or `{origin, dir}`), `count` | `angle` defaults to 360 deg. A full pattern keeps the COM on the axis, so check its radius with a top-view screenshot. |
|
||||
| `solid.mirror` | `features:[names]`, `plane` (`XY`/`XZ`/`YZ`, a construction plane, or `{origin, normal}`) | Follows parameters. Mirror and pattern features cannot be mirrored or patterned again. |
|
||||
|
||||
- **Names:** name every feature (`"name":"Standoff"`) and keep names unique across sketches and features. `timeline.roll_to {"feature":"Plate"}` picks the first match, which can be the sketch.
|
||||
- **Counts as parameters:** `parameters.add {"name":"n","expression":"6","unit":""}` creates a unitless parameter, and `"count":"n"` uses it in a pattern.
|
||||
- **Holes on a parametric bolt circle:**
|
||||
1. Cut one hole with `solid.cylinder {"diameter":6.6,"height":"T + 2","base":["bcd/2",0,-1],"operation":"cut","name":"BoltHole"}`.
|
||||
2. Repeat it with `solid.pattern.circular {"features":["BoltHole"],"axis":"Z","count":"n"}`.
|
||||
|
||||
Both the radius and the count follow their parameters.
|
||||
- **Several parameter changes:** use one `batch` of `parameters.change` steps instead of one `set_parameter` call each.
|
||||
- **Primitive booleans:** a `solid.box` or `solid.cylinder` cut that touches curved faces of the target can fail with `the exact fallback ... takes planar faces only`. Use a sketch profile and an extrude cut instead, for example a slot sketch rather than a box plus 2 cylinders.
|
||||
|
||||
## Worked example: parametric plate with 4 counterbored holes (1 batch)
|
||||
|
||||
```json
|
||||
{"commands":[
|
||||
{"command":"parameters.add","params":{"name":"L","expression":"80 mm"}},
|
||||
{"command":"parameters.add","params":{"name":"W","expression":"50 mm"}},
|
||||
{"command":"parameters.add","params":{"name":"T","expression":"6 mm"}},
|
||||
{"command":"parameters.add","params":{"name":"inset","expression":"8 mm"}},
|
||||
{"command":"sketch.create","params":{"plane":"XY","name":"PlateSketch"}},
|
||||
{"command":"sketch.draw.dimensioned","params":{"command":"sketch.rectangle.center","params":{"center":[0,0],"corner":[40,25]},"dimensions":{"width":"L","height":"W"}}},
|
||||
{"command":"sketch.finish","params":{}},
|
||||
{"command":"solid.extrude","params":{"distance":"T","name":"Plate"}},
|
||||
{"command":"solid.fillet","params":{"edges":[[40,25,3],[-40,25,3],[40,-25,3],[-40,-25,3]],"radius":5,"name":"Corners"}},
|
||||
{"command":"sketch.create","params":{"plane":"XY","name":"HolePts","offset":"T"}},
|
||||
{"command":"sketch.point","params":{"point":[32,17]}},
|
||||
{"command":"sketch.dimension","params":{"entities":["origin","p1"],"type":"horizontal","value":"L/2 - inset"}},
|
||||
{"command":"sketch.dimension","params":{"entities":["origin","p1"],"type":"vertical","value":"W/2 - inset"}},
|
||||
{"command":"sketch.finish","params":{}},
|
||||
{"command":"solid.hole","params":{"sketch":"HolePts","diameter":3.4,"type":"counterbore","cb_diameter":6.5,"cb_depth":3.3,"name":"Hole"}},
|
||||
{"command":"solid.pattern.rectangular","params":{"features":["Hole"],"dir1":[-1,0,0],"count1":2,"spacing1":"L - 2*inset","dir2":[0,-1,0],"count2":2,"spacing2":"W - 2*inset","name":"Holes"}}
|
||||
]}
|
||||
```
|
||||
|
||||
**Expected volume:**
|
||||
- Plate: `L*W*T - 4*r²(1-π/4)*T`
|
||||
- Each hole: `π*1.7²*(T-3.3) + π*3.25²*3.3`
|
||||
- Total: 23335.2 mm³, with 22 faces.
|
||||
|
||||
After `set_parameter L=120` the volume is 35335.2 mm³, and the holes stay in the corners.
|
||||
|
||||
## Reading `measure`
|
||||
|
||||
- **Tolerance:** analytic and measured volumes agree to about 0.001-0.01%, so treat a gap that small as a match.
|
||||
- **Face counts:** compare the logical `faces`, not the larger `kernel.faces`.
|
||||
- **Reply types:** `set_parameter` returns `recomputed` as a number. A batch reply echoes every step.
|
||||
- **Boolean warning:** a feature `warning` such as `Boolean retry: temporary coincident-face separation up to 2.050000e0 mm per face` means the kernel nudged faces that coincide. Examples are a hole floor on another floor, or a join flush on a face. When the volume still matches your number the warning is harmless.
|
||||
|
||||
## Reply cost (0.8, plate example)
|
||||
|
||||
| Call | Size |
|
||||
|---|---|
|
||||
| `list_commands {}` | **Over 100 KB.** Never call it unfiltered; filter on a distinctive word such as `"hole"` or `"slot"`. |
|
||||
| `body_topology` | 25-45 KB |
|
||||
| `inspect_design {}` | 12 KB, and it grows with the sketches |
|
||||
| `inspect_design {"measure":false,"sketches":false}` | 4 KB: parameters, timeline errors, bodies |
|
||||
| `sketch.inspect` | 5 KB per small sketch |
|
||||
| `parameters.list {"filter":"feature"}` | 3 KB |
|
||||
| `measure {}` | 1 KB: volume, bbox, COM, face/edge/vertex counts |
|
||||
| `sketch.solve` | under 100 B: dof, status, profile count |
|
||||
| `screenshot {"source":"model","width":480,"height":320}` | one small image. Without `source`, a bridged server returns the whole app window and ignores the size. |
|
||||
|
||||
## Errors
|
||||
|
||||
| Error text | Fix |
|
||||
|---|---|
|
||||
| `... is not available right now: no sketch is being edited` | Run `sketch.create` or `sketch.edit {sketch}` first. |
|
||||
| `unknown sketch entity 'p1'` | Use the ids from `created`. A circle's centre is `c1.center`. |
|
||||
| `the corner must join exactly two lines` | It is a `rectangle.center` corner. Use the `{a, b}` form. |
|
||||
| `` `cs_diameter` must be a number or an expression `` | Countersinks need `cs_diameter` and `cs_angle`, even with `clearance`. |
|
||||
| `unsupported dimension role for this creator` | Check the roles table above. |
|
||||
| `<Feature> cannot be patterned or mirrored yet` | Pattern the original feature, for example one 2x2 rectangular pattern. |
|
||||
| `an edge is a point [x,y,z], {point} or {body, index}` | An edge pick contained an expression. Use plain numbers. |
|
||||
| `boolean Cut: the operation failed ... planar faces only` | See "Primitive booleans" above. |
|
||||
Reference in new issue
Block a user