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
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.
- Build with
add_shape, then set_hole, move_bodies, resize_shape, group_bodies.
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.
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.
- 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
add_shape {"kind": "box", "size": {"w": 40, "d": 30, "h": 20}, "name": "Block"} returns the block's id, say "b1".
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.
group_bodies {"ids": ["b1", "b2"], "name": "Block with hole"} returns the group's id, say "b3".
wait_ready, then list_bodies: one body, volume about 22994.7 mm3 (24000 minus the hole).
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:
new_design with mode: "advanced" (only when the user wants a fresh design, never on their open tab unasked).
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.
list_faces and list_edges to look: positions, normals, sizes, in world mm. Indices are valid only until the next edit.
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:
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.
1---2name: jumpstart-3d3description: "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."4metadata:5 source: https://skillmd.com/skills/maxsikorski/jumpstart-3d6---78# Driving JumpStart 3D910JumpStart 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`...).1112Before risky steps, use `checkpoint`; review with `diff_checkpoint` and use `rollback` on failure (one undo step).1314## Facts to keep straight1516- `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.17- Lengths are millimetres, angles degrees, positions `[x, y, z]` with z up.18- `add_shape` puts the middle of the shape's footprint at `at` `[x, y]` and its base at `at` z. Default `[0, 0, 0]`.19- 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.20- Never guess an id. Every tool that takes ids needs ones returned by `add_shape`, `group_bodies` or `list_bodies`.21- 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.22- 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.23- A group's own position stays `[0, 0, 0]`; read `bbox` to see where it is.24- `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.25- `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.26- `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.27- `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.28- `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.29- `add_hardware` adds any Fasteners-library part (screws, nuts, washers, heat-set inserts, dowels); `add_spring` a compression spring.30- `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.31- `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.32- `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.3334## The loop35361. `status` first. It never starts a browser. `page` says where you are:37 - `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).38 - `headless`: your own invisible browser with a blank design.39 - `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.402. Build with `add_shape`, then `set_hole`, `move_bodies`, `resize_shape`, `group_bodies`.413. `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`.424. `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.435. 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).4445If 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.4647## Worked example: a 40 x 30 x 20 mm block with an 8 mm hole straight through48491. `add_shape` `{"kind": "box", "size": {"w": 40, "d": 30, "h": 20}, "name": "Block"}` returns the block's id, say `"b1"`.502. `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.513. `group_bodies` `{"ids": ["b1", "b2"], "name": "Block with hole"}` returns the group's id, say `"b3"`.524. `wait_ready`, then `list_bodies`: one body, volume about 22994.7 mm3 (24000 minus the hole).535. `screenshot` to look. `export_file` `{"kind": "stl", "path": "/Users/me/block.stl"}` returns the path and byte count.5455To cut one existing solid out of another instead: `group_bodies` with `"op": "cut"` subtracts every later id from the first.5657## Advanced parts: sketches, features, selectors5859For 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:60611. `new_design` with `mode: "advanced"` (only when the user wants a fresh design, never on their open tab unasked).622. `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.633. `list_faces` and `list_edges` to look: positions, normals, sizes, in world mm. Indices are valid only until the next edit.644. `shell_body`, `fillet_edges`, `chamfer_edges`, `add_holes`, `pattern_features`, then `wait_ready`, `list_bodies` (error? volume?) and `screenshot`.6566Faces 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.6768## What the tools cannot do6970Sweeps, 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:7172```js73JS3D.add("box", { size: [40, 30, 20], at: [0, 0, 0], hole: false }) // returns an id74JS3D.group([a, b], { name: "Part", op: "cut" }) // join, or cut/intersect75JS3D.scale(id, [1, 1, 2]); JS3D.rotate(id, "z", 45) // about the box middle: after `await JS3D.ready()`, or pass `{ about }`76JS3D.setParam("w", "40"); JS3D.bind(id, "w", "w/2") // a size that follows a parameter77await JS3D.ready(); JS3D.list(); JS3D.get(id).volume // wait, then read78await JS3D.screenshot({ fit: true, width: 800 }) // PNG bytes79await JS3D.export("step") // bytes; also stl, obj, 3mf, glb, json80await JS3D.load(jsonText) // open a project file you wrote81```8283To get something no tool makes in, write a project file by hand (format in BRIDGE.md Part 2) and open it with `load_project`.8485## Mistakes to avoid8687- Calling a part ready to print without `check_print`.88- Reading `volume` before `wait_ready`.89- Rotating or scaling before `wait_ready` (the tools throw while a body is still being built unless you pass `about`).90- Calling `group_bodies` with a hole alone: a hole needs a solid to cut.91- Forgetting that `at` z is the base of the shape, not its middle.92- Using `new_design` on a user's open tab without being asked.93- Telling the user a file exists without the path from `export_file`.