ultron-onshape-mcp

# Ultron Onshape MCP A performance- and reliability-focused fork of [jarvis-onshape-mcp](https://github.com/ReshefElisha/jarvis-onshape-mcp) by Reshef Elisha (MIT). All credit for the architecture, the vision workflow, and the original tool surface goes upstream — this fork keeps that intact and tunes it for faster, cheaper, real-world iteration. ## What this fork changes Measured on a 90-face lofted impeller (the part this fork was tuned against): - **3.2× faster verification loop.** `describe_part_studio` went 9.3s → 2.9s: the per-face tangent-plane FeatureScript probe is skipped during verification (`list_entities` gained `include_frames`), and the bbox + face-area probes merged into a single eval so the part regenerates once, not three times. - **~46% fewer tokens per verification call** (~6,300 → ~3,370): body topology is summarized (largest planar faces by real area + representatives per curved type, `verboseTopology=true` for the full dump), default renders are 3 views @ 1024x680 instead of 4 @ 1200x800, and all tool responses use compact JSON. - **`create_circular_pattern` actually works.** The native axis query (`qCreatedBy(makeId("FRONT"), EntityType.EDGE)`) can never resolve — datum planes have no edges. World-axis patterns (axis=X/Y/Z) now auto-generate a FeatureScript `opPattern` + `rotationAround` feature; a new `axisEdgeId` parameter uses the native pattern when a real model edge is available. - **Feature-parameter compatibility fixes** against Onshape's current API (e.g. `libraryRelationType: "NONE"` rejection) and a `create_revolve` deterministic-edge axis option. Claude Code plugin that lets Claude drive real Onshape CAD: sketches, extrudes, fillets, mates, parametric iteration via Variable Studios, custom FeatureScript features. Every mutating tool returns a structured truth: what changed, what warnings the regenerator raised, and hints for the next move. Multi-view PNG renders come back as image content so Claude can actually see the part. Includes a vision-decomposition skill that walks Claude through reading an engineering reference image *before* building. See `RESEARCH.md` for the benchmark data behind that workflow. > "felt dramatically more like writing code than anything I've tried with an LLM CAD tool." ## What you get - **Truth-telling on every mutation.** Every tool returns `{ok, status, feature_id, feature_name, error_message, changes?, hints?}`. Silent regen failures are surfaced, warnings are enriched with actionable fixes. - **Vision.** `render_part_studio_views` and `render_assembly_views` return shaded PNGs (front/top/right/iso). `crop_image` zooms in on regions. `load_local_image` caches a reference image (drawing, photo, sketch) the user shares so you can crop into it the same way. `compare_to_reference` renders your in-progress part and composites it directly under the reference for side-by-side visual diff in a single image. - **Vision-decomposition skill.** `/skill vision-decompose` — when the user gives you a reference image and asks you to build it, this skill walks you through a structured zoom-and-describe pass *before* you start building. Produces a feature tree the user can sanity-check. We measured this turns "agent skims image and builds the wrong shape" into "agent reads image carefully, asks the user to confirm, then builds." See the research writeup below. - **Drawing OCR.** `extract_drawing_dimensions` runs Tesseract on an engineering drawing and returns every numeric callout (length / radius / diameter / thread / angle / count) grouped by kind, with pixel positions. Use it on hard-to-read drawing PNGs where small dim text gets clobbered by Claude's vision downsampling. - **Entity discovery with outward normals.** `list_entities` returns deterministic face IDs, surface types, and normals so follow-up features can target geometry without guessing. - **Per-feature geometric diffs.** After each feature, you get a `changes:` block with bbox delta, part count delta, mass delta — you see the effect before rendering. - **Parametric iteration.** First-class Variable Studios. `set_variable` is upsert-by-name, so reparametrizing NEMA 17 → NEMA 23 is a few values away. - **FeatureScript escape hatch.** `write_featurescript_feature` lets Claude write a custom feature directly (helices, swept threads, shells with parameters) when the tool-per-primitive surface isn't enough. Regen errors surface FS notice text. - **Hints rotation.** When a feature fails with a known pattern, hints point at the fix (`BOOLEAN_SUBTRACT_NO_OP → oppositeDirection`, `SKETCH_DIMENSION_MISSING_PARAMETER → add missing variable`, …). - **Assembly.** Fastened, slider, revolute, cylindrical mates; face-coordinate systems; instance alignment; bounding-box interference checks. ## Install ``` /plugin install github:ReshefElisha/jarvis-onshape-mcp ``` Claude Code will prompt you for: - `ONSHAPE_API_KEY` — the "Access Key" from the Onshape developer portal. - `ONSHAPE_API_SECRET` — the "Secret Key" shown once when you create the key pair. Get a key pair at [dev-portal.onshape.com](https://dev-portal.onshape.com/). Both values are stored in the OS keychain and never written to disk in plaintext. ### Requirements - [uv](https://docs.astral.sh/uv/) on your PATH (`brew install uv` or the official installer). The plugin launches its MCP server via `uv run`. - Claude Code desktop or CLI with plugin support. - An Onshape account. ## Quick start Once installed, restart Claude Code and try: > "Create a new Onshape document, add a Part Studio, and build me a > 60×40×8 mm mounting plate with four ø4 mm holes 6 mm in from the corners." Claude will render the result, show you the bbox delta, and surface any regen warnings. If it takes a wrong direction on an extrude, the `BOOLEAN_SUBTRACT_NO_OP` hint will kick in and it'll self-correct. ## Protocol guide Two plugin skills auto-discovered by Claude Code: - `skills/onshape/SKILL.md` — **CAD build skill**. Loaded into every Onshape session. Covers units (bare numbers in mm), coordinate frames (Front is XZ with a Y-normal sign flip), render-first and entity-first workflows, iteration discipline, when to reach for `write_featurescript_feature`, and the gotchas (REMOVE-on-face auto-flip, Variable Studios as separate elements, deterministic ID remapping). - `skills/vision-decompose/SKILL.md` — **Vision decomposition**. Use this *before* building when the user shares a reference image. Walks the agent through overview → cache → zoom-into-each-feature → structured spec. Output is a feature tree (type, role, size, position, face) the user can review before committing turns to the build. See "Recommended workflow" below. You can load either into any Claude session as a system prompt to get the same behavior outside the plugin context. ## Recommended workflow The plugin works best as a copilot, not an autocomplete. Two modes: **Mode A — text-first design.** Describe the part in plain text ("a 100×60×30 mm aluminum heat sink with 1mm fins on 3mm pitch and 4 corner Ø3.5 mounting holes") and let Claude build. This works well — the bottleneck is not CAD execution, it's image interpretation. **Mode B — image reference.** Drop in a drawing, photo, sketch, or competition prompt and ask Claude to build it. 1. Invoke the vision-decomposition skill: `/skill vision-decompose`. 2. Claude produces a structured feature tree from the image. 3. Review it — fix mis-reads, fill in things the image didn't make obvious. 4. Tell Claude "build to that spec." It runs the CAD pipeline against the confirmed tree. Mode B with a careful human review beats letting Claude attempt the whole thing autonomously. See `RESEARCH.md` for the experimental data behind that recommendation. ## Tool surface Roughly 60 tools across these groups: | Group | Highlights | |-------|-----------| | Document | `create_document`, `find_part_studios`, `get_elements` | | Sketch | `create_sketch` (multi-entity), plus rectangle / circle / line / arc / rounded rect primitives | | Feature | `create_extrude`, `create_revolve`, `create_thicken`, `create_fillet`, `create_chamfer`, `create_boolean`, `create_linear_pattern`, `create_circular_pattern` | | Assembly | `add_assembly_instance`, `create_fastened_mate`, `create_slider_mate`, `create_revolute_mate`, `create_cylindrical_mate`, `align_instance_to_face`, `check_assembly_interference` | | Introspection | `describe_part_studio`, `list_entities`, `get_body_details`, `get_bounding_box`, `get_mass_properties`, `measure`, `get_face_coordinate_system` | | Variables | `create_variable_studio`, `set_variable`, `get_variables` | | FeatureScript | `eval_featurescript`, `write_featurescript_feature` | | Rendering | `render_part_studio_views`, `render_assembly_views`, `crop_image`, `load_local_image`, `compare_to_reference`, `extract_drawing_dimensions` | | Export | `export_part_studio`, `export_assembly` (STL / STEP / GLTF / …) | Full schemas are discoverable from Claude via `ToolSearch` — no separate docs to read. ## Known limitations - **Section views are blocked** at the Onshape platform level. The REST API has no section-view endpoint; only the UI `Shift+X` works. - `create_fillet` with `variableCenter` currently hits a phantom-reference bug on Onshape's side. Bare radius works. - `opHelix` standard-library call is flaky in some contexts; cookbook uses `opFitSpline` as a workaround. ## Development ``` git clone https://github.com/ReshefElisha/jarvis-onshape-mcp cd jarvis-onshape-mcp uv sync export ONSHAPE_API_KEY=... export ONSHAPE_API_SECRET=... uv run onshape-mcp # launch the MCP server on stdio uv run pytest # unit tests ``` ## Attribution Scaffolding (Onshape REST client + HMAC auth, BTMFeature-134 / BTMParameterQuantity-147 / BTMIndividualQuery-138 payload builders, and the first-pass tool-per-primitive MCP surface) was forked from [hedless/onshape-mcp](https://github.com/hedless/onshape-mcp) — thanks to hedless for getting that off the ground. Everything built on top of that (truth-telling, vision, entity discovery, parametric Variable Studios, FeatureScript orchestration, per-feature geometric diffs, the hints rotation, iterative agent harness via Claude Agent SDK, and most of the current tool surface) was built here. See `NOTICE` and `git log` for the full trail. ## License MIT. See `LICENSE`.