# Jumpstart 3d

> Build and edit 3D parts in JumpStart 3D through its MCP tools: Beginner shapes, Advanced sketches and features (extrude, fillet, shell, holes), groups, parameters, screenshots, STL/STEP/OBJ/3MF export. Use when the user asks for a part, bracket, box, enclosure or any 3D model, or for an edit to the design they have open in JumpStart 3D.

- Skill: `maxsikorski/jumpstart-3d` (Agent Skill)
- Install (CLI): `npx get-skill add maxsikorski/jumpstart-3d`
- Raw SKILL.md: https://api.skillmd.com/api/skills/maxsikorski/jumpstart-3d/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MaxSikorski (https://skillmd.com/u/maxsikorski)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/maxsikorski/jumpstart-3d

---


# Driving JumpStart 3D

JumpStart 3D is a CAD app that runs in a browser. These tools edit a design in it. The tool names start with a prefix your client adds; this text uses the short names (`status`, `add_shape`...).

Before risky steps, use `checkpoint`; review with `diff_checkpoint` and use `rollback` on failure (one undo step).

## Facts to keep straight

- `inspect_bodies` gives size, volume, area and weight (default PLA); `measure` gives distances (two flat faces picked with `a_near`/`b_near` give a wall's thickness); `check_print` says whether the design prints as it sits (on the plate, fits the printer, overhangs); `check_collisions` finds parts that overlap or touch; `section_view` cuts the design and gives the outline areas.
- Lengths are millimetres, angles degrees, positions `[x, y, z]` with z up.
- `add_shape` puts the middle of the shape's footprint at `at` `[x, y]` and its base at `at` z. Default `[0, 0, 0]`.
- Sizes are `{w, d, h}` (width x, depth y, height z) or `[w, d, h]`. `list_kinds` shows the 20 kinds and their size keys.
- Never guess an id. Every tool that takes ids needs ones returned by `add_shape`, `group_bodies` or `list_bodies`.
- Shapes are built in the background. `volume` and `bbox` in `list_bodies` are null until you call `wait_ready`. `screenshot` and `export_file` wait by themselves.
- A hole is a cutter, not a part. It is see-through, is left out of exports, and does nothing until `group_bodies` combines it with a solid.
- A group's own position stays `[0, 0, 0]`; read `bbox` to see where it is.
- `add_fastener` makes a whole bolt, nut, threaded rod or tap cutter with a real thread (metric M2.5 to M12, inch #6 to 1/2). A bolt's `length` is under the head. A tap cutter is a hole: put it inside a solid and `group_bodies` both, and it cuts a threaded hole. Threads take a few seconds to build, so call `wait_ready`. More than 150 thread turns is refused.
- `add_hole_pattern` drills a grid, a staggered grid or a circle of round holes into one flat face of a body, as one Hole feature. `face` is the direction the face looks (`+z` is the top). Columns run along the face's longest straight edge (on a box top, the longer side), rows across it; `angle` and `start` are measured from that edge. Leave `pitch` out to spread the holes over the face; holes that would not fit inside the face and its `margin` are left out and counted in `dropped`. Plain, counterbore (`cbore`), countersink (`csink`) or `tapped`, with a `size` such as `M3`. `shape` `square`, `hex` or `slot` cuts that outline instead (`width`: the side, the width across flats or the slot's width; `length`: the slot's overall length) as one sketch and one Extrude cut, with the same layouts; stagger with a row pitch of 0.866 x the column pitch for a honeycomb. More than 200 plain holes or shapes (130 counterbores or countersinks, 8 tapped) is refused. Call `wait_ready` after.
- `add_gear` makes a spur gear, a helical gear (`angle` 5 to 30, `hand`; it meshes with one of the opposite hand on a parallel axis), a straight bevel gear or a rack from `module` (mm) and `teeth`. Two spur gears of one module mesh at centres `module × (teeth1 + teeth2) / 2` apart; when `teeth2` is even, turn the second by `180 / teeth2` degrees about its own centre with rotate_bodies. Call wait_ready after.
- `add_gear_set` places gears that already mesh: a pair, rack and pinion, ring, planetary set (with motion-study joints), a 90 degree bevel pair or a helical pair.
- `add_box_maker` makes a Box Maker set: open bins with compartments, or cases with drawers, tilt bins or doors, stacked and side by side.
- `add_hardware` adds any Fasteners-library part (screws, nuts, washers, heat-set inserts, dowels); `add_spring` a compression spring.
- `add_texture` (keys from `list_textures`) textures a body or some faces; mesh only, so STEP has no texture. `export_drawing` writes a DXF of Top, Front and Right.
- `add_name_plate` makes a tag or name plate sized to one line of text: raised letters are a second body in their own colour (do not group_bodies them with the plate, that fuses them into one colour); cut letters are part of the plate. Call wait_ready after.
- `add_knurl` makes a knurled knob or grip: a cylinder with straight V grooves and an optional round, hex or D bore. For a diamond pattern use the app's Texture. Call wait_ready after.

## The loop

1. `status` first. It never starts a browser. `page` says where you are:
   - `tab`: the user's open browser tab. You are editing their real design. Add to it; call `new_design` only if they ask (it replaces what is on screen).
   - `headless`: your own invisible browser with a blank design.
   - `none`: nothing yet. Any other tool starts headless. If the user wants their open tab, tell them: Customize (the sliders button in the top bar), turn on "Connect to AI agent". Chrome may ask to allow "local network access" for the website; they must allow it.
2. Build with `add_shape`, then `set_hole`, `move_bodies`, `resize_shape`, `group_bodies`.
3. `wait_ready`, then `inspect_bodies` (or `list_bodies`) to check sizes and volumes, and `check_print` before you call a part printable. A body with an `error` did not build; read the message, fix it, or `undo`.
4. `screenshot` after every few edits and look at it. Do not trust the numbers alone. If your model cannot see images, pass `path` (a file name): the PNG is saved there and you get `{path, bytes, width}` as text, so the user can look at the file.
5. At the end `export_file` and tell the user the full path. Use an absolute path; a relative one is relative to the folder the server was started in. Kinds: `stl`, `obj`, `3mf`, `glb`, `step`, `json` (the project file).

If a tool fails with "could not start the headless browser", tell the user to run `npx playwright@1.62.1 install chromium` once and then try again. Headless opens the public site (https://maxsikorski.github.io/jumpstart-3d/) unless the server runs from a checkout that has a built `docs/` folder, or `JS3D_APP` says otherwise, so it needs internet when the server runs from the installed plugin.

## Worked example: a 40 x 30 x 20 mm block with an 8 mm hole straight through

1. `add_shape` `{"kind": "box", "size": {"w": 40, "d": 30, "h": 20}, "name": "Block"}` returns the block's id, say `"b1"`.
2. `add_shape` `{"kind": "cylinder", "size": {"w": 8, "d": 8, "h": 30}, "at": [0, 0, -5], "hole": true, "name": "Hole"}` returns `"b2"`. It is taller than the block and starts 5 mm below it, so it cuts all the way through.
3. `group_bodies` `{"ids": ["b1", "b2"], "name": "Block with hole"}` returns the group's id, say `"b3"`.
4. `wait_ready`, then `list_bodies`: one body, volume about 22994.7 mm3 (24000 minus the hole).
5. `screenshot` to look. `export_file` `{"kind": "stl", "path": "/Users/me/block.stl"}` returns the path and byte count.

To cut one existing solid out of another instead: `group_bodies` with `"op": "cut"` subtracts every later id from the first.

## Advanced parts: sketches, features, selectors

For a part that is more than basic shapes (an enclosure, a bracket with fillets and holes), work in Advanced mode and build it like a person does:

1. `new_design` with `mode: "advanced"` (only when the user wants a fresh design, never on their open tab unasked).
2. `add_sketch` with shapes (`rect`, `roundrect`, `circle`, `slot`, `polygon`, `polyline`, `line`; sizes may be expressions such as `"W/2"`), then `extrude` (or `revolve`). Cut or join with `op`; `through: true` cuts right through.
3. `list_faces` and `list_edges` to look: positions, normals, sizes, in world mm. Indices are valid only until the next edit.
4. `shell_body`, `fillet_edges`, `chamfer_edges`, `add_holes`, `pattern_features`, then `wait_ready`, `list_bodies` (error? volume?) and `screenshot`.

Faces and edges are picked with a selector, not an index: `top`, `bottom`, `front` (-y), `>z` (the highest), `|z` (parallel to z), `#z`, `hole`, `circle`, `edges of top`, joined with `and`, `or`, `not` and brackets. The outer rim of an open box: `edges of top and (>x or <x or >y or <y)`. A selector is resolved when you call; after a parameter change, look again with `list_faces` or `list_edges`. A fillet too large for the walls shows as the body's `error` in `list_bodies`: undo and use a smaller radius.

## What the tools cannot do

Sweeps, lofts, mirrors, split, emboss, threads and construction planes have no tool. Use `run_script` for those and anything else: it runs JavaScript in the page with `JS3D` in scope and returns the value as JSON. Top-level `await` works; end with `return` to give a value back. It has the full power of the page, so use it for the design only. Full reference: BRIDGE.md in the JumpStart 3D repository (https://github.com/MaxSikorski/jumpstart-3d/blob/main/BRIDGE.md). The calls you will use most:

```js
JS3D.add("box", { size: [40, 30, 20], at: [0, 0, 0], hole: false })   // returns an id
JS3D.group([a, b], { name: "Part", op: "cut" })                       // join, or cut/intersect
JS3D.scale(id, [1, 1, 2]); JS3D.rotate(id, "z", 45)                   // about the box middle: after `await JS3D.ready()`, or pass `{ about }`
JS3D.setParam("w", "40"); JS3D.bind(id, "w", "w/2")                   // a size that follows a parameter
await JS3D.ready();  JS3D.list();  JS3D.get(id).volume                // wait, then read
await JS3D.screenshot({ fit: true, width: 800 })                      // PNG bytes
await JS3D.export("step")                                             // bytes; also stl, obj, 3mf, glb, json
await JS3D.load(jsonText)                                             // open a project file you wrote
```

To get something no tool makes in, write a project file by hand (format in BRIDGE.md Part 2) and open it with `load_project`.

## Mistakes to avoid

- Calling a part ready to print without `check_print`.
- Reading `volume` before `wait_ready`.
- Rotating or scaling before `wait_ready` (the tools throw while a body is still being built unless you pass `about`).
- Calling `group_bodies` with a hole alone: a hole needs a solid to cut.
- Forgetting that `at` z is the base of the shape, not its middle.
- Using `new_design` on a user's open tab without being asked.
- Telling the user a file exists without the path from `export_file`.

