@shapeitup/mcp-server

Bootstrap a folder so `.shape.ts` files get correct types in editors. Writes node_modules/shapeitup and node_modules/replicad type stubs + a minimal tsconfig.json if missing. Idempotent — safe to call repeatedly. Does NOT run npm install; replicad and OCCT are bundled inside this MCP server at runtime. Typically you don

Create a new .shape.ts CAD script file and execute it. Fails if file already exists — use modify_shape to update existing files. Path resolution precedence: absolute `directory` used as-is; relative `directory` probed against each heartbeat-reported VSCode workspace root (first match wins), else `process.cwd()`; omitted `directory` defaults to the first active VSCode workspace root (or cwd if no extension is running). Refuses to create a file when the resolved path contains a duplicated segment (e.g. `examples/examples/...`) unless `allowPathDuplication: true` is passed.

Execute an existing .shape.ts file; when the ShapeItUp VSCode extension is open it will also reflect the file in its interactive viewer. Relative paths probe each open VSCode workspace (first match wins), else fall back to process.cwd(). Pass `capture: true` to also render a screenshot through the bundled SVG pipeline (runs standalone — no extension needed). A capture failure does not fail the whole call — it

Change an existing .shape.ts file and execute it. Three write modes plus a re-run mode: (1) `code` — full overwrite; (2) `edits` — apply one or more exact-string patches in place (token-cheap for a few-line change — no need to resend the whole file); (3) `params` only (no `code`/`edits`) — re-execute with ephemeral param overrides, no disk write; (4) all omitted — behaves like `open_shape` (re-executes from disk), useful after editing an imported dependency like `constants.ts`. Relative paths probe each open VSCode workspace (first match wins), else fall back to process.cwd(). Precedence when several are supplied: `code` > `edits` > `params`; the losers are reported as ignored.

Read the contents of a .shape.ts file. Relative paths probe each open VSCode workspace (first match wins), else fall back to process.cwd().

Delete a .shape.ts file. Relative paths probe each open VSCode workspace (first match wins), else fall back to process.cwd().

Export the last executed shape to STEP, STL, or 3MF. Optionally pass `filePath` to execute and export a specific file in one call. For multi-part assemblies, pass `partName` to export a single named part instead of the whole assembly, or `splitParts: true` to write EACH part to its own file in a folder (best for 3D printing — every part becomes an independent file the slicer can arrange). Pass `bom: true` to write a `*.bom.json` sidecar next to the exported file with per-part volume, mass, qty, material, and bounding box.

List 3D apps detected on the user

Find all .shape.ts files in a directory. Relative `directory` probes each open VSCode workspace (first existing match wins), else falls back to process.cwd(). Omitted `directory` defaults to the first active VSCode workspace root.

Validate TypeScript syntax and detect common CAD pitfalls (sketch mischain, missing sketchOnPlane, unclosed pen, non-uniform scale, oversized fillet, hand-rolled boolean loops including for/while/forEach/reduce with .cut/.fuse/.intersect, fillet-after-boolean). Does NOT verify imports, types, or runtime behavior — for that, call create_shape or modify_shape.

Execute a .shape.ts snippet WITHOUT writing it to the user

Re-execute an existing .shape.ts with ephemeral `params` overrides WITHOUT modifying the file — the file on disk is untouched. Returns the same stats as get_render_status (volume, surface area, bounding box, timings, warnings) so agents can binary-search a design constraint (target volume, bounding box, mass, fit tolerance) before committing the winning value with modify_shape. Pass `captureScreenshot: true` to also render a PNG of the tuned configuration through the bundled headless SVG pipeline (runs standalone; the ShapeItUp VSCode extension, when open, will also reflect the render in its interactive viewer). Pass `persist: true` to also write the override map to a `.shapeitup-params.json` sidecar next to the file so every later execution (render_preview, open_shape, export_shape, etc.) picks them up automatically; clear with `clear_params`.

Clear persisted param overrides written by `tune_params({ persist: true })`. Persistence model: `tune_params` with `persist: true` writes a `.shapeitup-params.json` sidecar alongside the shape file; subsequent executions (render_preview, open_shape, export_shape, modify_shape, preview_finder, check_collisions) merge those overrides on top of the script

Get Replicad API reference. Call without category to list available categories, pass `search` to find the most relevant sections across all categories, or pass `signaturesOnly: true` to get just the method signatures (token-efficient lookup).

Render a PNG screenshot of the current shape through the bundled headless SVG pipeline — a 4-pane (top/front/right/iso) shaded view produced from the in-memory tessellation. Runs standalone; the ShapeItUp VSCode extension, when open, will also reflect the same shape in its interactive viewer. PNGs are written to `{workspace}/shapeitup-previews/` — Read the returned absolute path to view the image. Pass `finder` to overlay pink dots at matched edges/faces (for a text-only match count, use `preview_finder`). Pass `meshQuality:

Return the latest (or a specified) ShapeItUp preview PNG as inline MCP image content — base64 bytes delivered directly in the tool response, no filesystem Read required. Use this when your sandbox ignores `shapeitup-previews/` (gitignored) or restricts filesystem reads. Does NOT trigger a render — call `render_preview` first if no preview exists yet.

Switch the interactive VSCode viewer between dark and AI mode. UI-only setting — when no VSCode viewer is attached the preference is recorded for the next viewer to pick up (the tool never fails on a missing viewer).

Show or hide dimension measurements on the VSCode viewer. UI-only setting — when no viewer is attached the preference is recorded for the next connection (the tool never fails on a missing viewer). Omit `show` to toggle the current state.

Get the result of the last shape render — whether it succeeded or failed, with stats, geometric properties (volume, area, center of mass, mass when material is exported), and bounding box. Reads the shared status file, which both MCP-driven and VSCode-driven renders write to. Includes currentParams — the resolved values of every exported param, so you don

Preview which edges/faces a Replicad EdgeFinder or FaceFinder matches on a shape — WITHOUT editing the user

Runs the Phase-1 kinematic MOTION simulation declared by a shape

Detects pairwise intersections between named parts in a multi-part assembly. AABB prefilter skips obviously-disjoint pairs; the rest run Replicad

Reports each part

Validates declared mate joints: executes the shape, reads the `joints` map on each rendered part (world coordinates — auto-populated by the stdlib `Part`/`entries()` API, or supplied directly via `{shape, name, joints}` returns), and measures each joint point

Single-call inspection bundle: executes the shape ONCE and runs any combination of geometry, collision, and joint checks against that single execution. Faster than calling describe_geometry → check_collisions → validate_joints separately (each of those re-executes the shape). Returns a structured JSON report with one section per requested check plus a top-level `ok` flag and `summary`. Pick `checks` to scope the work; per-check options are prefixed (geometryFormat, collisionTolerance, jointTolerance, etc.). Use the individual tools for one-off queries; use this when verifying an assembly comprehensively.

Rotate a single named part through a range of angles around a pivot+axis and report any collisions it would make with the other parts at each step. Useful for articulated mechanisms (hinges, arms, linkages) where static collision checks miss motion conflicts. The moving part is cloned at every step so the original assembly is never mutated. Also reports the swept-volume AABB — the union of the moving part

Enumerate the faces and/or edges of a rendered shape with per-entity geometry (normal, centroid, area, type; edges: start/end/length/type) plus a bounding box and a grouped-count `summary`. Use `format: