onshape-jamcp 1.0.0__tar.gz

onshape_jamcp-1.0.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Secrets - never commit API keys
+.env
+.env.*
+!.env.example
+
+# Local-only tooling, kept out of the repository
+.claude/settings.json
+.claude/settings.local.json
+.github/hooks/
+ai-helper-*.ps1
+
+# Local output (screenshots / exports) and editor files
+output/
+.idea/
+.vscode/*
+!.vscode/tasks.json
+*.log

onshape_jamcp-1.0.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-14
+
+### Changed
+- Initial Version
+
+## [0.1.0] - 2026-11-14
+
+First release (alpha).
+
+### Added
+- 22 MCP tools: documents, Part Studio inspection, sketch / extrude / fillet / chamfer modeling,
+  feature editing, assembly inspection, screenshots, export and a raw API escape hatch.
+- **Metric by default**: all lengths are millimeters unless `ONSHAPE_UNITS=imperial` (inches).
+- **Screenshot review toggle**: `ONSHAPE_SCREENSHOT_REVIEW` / `--[no-]screenshot-review` and a
+  per-call `review` flag decide whether images are sent to the LLM (token cost) or only saved.
+- Read-only mode (`ONSHAPE_READ_ONLY`) that removes every write tool.
+- HMAC-signed API-key authentication (HTTP Basic available as a fallback).
+- Default-plane IDs are resolved at runtime via FeatureScript instead of being hard-coded.
+- `scripts/smoke_test.py` for verifying a build against a real Onshape account.
+- Generated tool reference (`docs/tools.md`), Dockerfile and `glama.json` for Glama.
+- Release automation: tag-triggered `release.yml` (verify, build, PyPI Trusted Publishing, GitHub
+  Release) and `scripts/release.py` (`check`, `notes`, `bump`, `build`, `verify`, `preflight`,
+  guarded `commit` / `tag` / `push` / `publish`).
+- One VS Code task, `Release` (`.vscode/tasks.json`), for the whole flow: it asks which version, an
+  optional note and Preview vs real, then bumps, verifies (restoring the files on failure), commits,
+  tags and pushes. Notes come from `## [Unreleased]` or a typed line.
+
+### Fixed during live verification
+- `whoami` no longer reports success for an anonymous session (Onshape returns `200 {}`).
+- `create_document` has a `public` option; free plans reject private documents (`409`).
+- FeatureScript evaluation: `queries` is an object, and flat `BTFSValue*` results are decoded.
+- STL export: the `units` query value must be lowercase (`millimeter` / `inch`).
+
+### Known limitations
+- Verified live on an Onshape free plan (31/31 smoke-test checks); not yet verified live: chamfer,
+  assemblies with mates, paid-plan behavior. See `docs/development.md`.
+- No revolve/pattern/hole helpers, variables or assembly mates yet (use `add_feature` or
+  `onshape_api_request`).

onshape_jamcp-1.0.0/Dockerfile

@@ -0,0 +1,26 @@
+# onshape-jamcp - MCP server speaking stdio.
+#
+#   docker build -t onshape-jamcp .
+#   docker run -i --rm -e ONSHAPE_ACCESS_KEY=... -e ONSHAPE_SECRET_KEY=... onshape-jamcp
+#
+# The server starts (and lists its tools) without credentials, so registries such as Glama can
+# introspect the image; tool calls report a clear error until the keys are provided.
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+WORKDIR /build
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install . && rm -rf /build
+
+# Run as an unprivileged user; screenshots/exports go to a writable directory.
+RUN useradd --create-home --uid 10001 jamcp
+USER jamcp
+WORKDIR /home/jamcp
+ENV ONSHAPE_OUTPUT_DIR=/home/jamcp/output
+
+ENTRYPOINT ["onshape-jamcp"]

onshape_jamcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onshape-jamcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

onshape_jamcp-1.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: onshape-jamcp
+Version: 1.0.0
+Summary: Just Another MCP server for Onshape CAD - metric by default, with optional screenshot review by the LLM.
+Author: onshape-jamcp contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d,cad,llm,mcp,model-context-protocol,onshape,parametric
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: mcp<3,>=2.3
+Description-Content-Type: text/markdown
+
+# onshape-jamcp
+
+**J**ust **A**nother **MCP** server for [Onshape](https://www.onshape.com) CAD. It lets an AI
+assistant (Claude, Cursor, VS Code, any [MCP](https://modelcontextprotocol.io) client) find your
+documents, model parts, measure them, look at them and export them - in **millimeters by default**,
+with a switch for **inches**, and a switch that decides whether the assistant gets to **see
+screenshots** (which costs tokens) or not.
+
+> **Status: alpha, verified live.** 140+ automated tests run against a simulated Onshape, and
+> [`scripts/smoke_test.py`](scripts/smoke_test.py) passed **31/31 checks against a real Onshape
+> account** (free plan, 2026-11-14): sketch → extrude → fillet → hole → edit → screenshot → STEP/STL
+> export, with orientation and dimensions measured. Chamfer, assemblies with mates and paid-plan
+> behavior are not yet verified live - see [what is verified](docs/development.md#verification-status-read-this-before-trusting-a-tool).
+> Re-run the smoke test on your own account (see [below](#verify-it-works-against-your-account)).
+
+## Highlights
+
+| | |
+|---|---|
+| 📏 **Metric by default** | Every length you send or receive is in **mm**. Set `ONSHAPE_UNITS=imperial` for inches. Angles are always degrees. |
+| 👁️ **Screenshot review toggle** | `ONSHAPE_SCREENSHOT_REVIEW=true` sends renders to the model so it can *see* its work (≈ 640 tokens per 800×600 image). `false` only saves them to disk - zero image tokens. Override per call with `review`. |
+| 🔒 **Read-only mode** | `ONSHAPE_READ_ONLY=true` removes every tool that can modify a document. |
+| 🧰 **22 focused tools** | Documents, sketch → extrude → fillet/chamfer, edit parameters, measure, faces/edges, assemblies, screenshots, STEP/STL export - plus escape hatches (raw feature JSON, FeatureScript, any REST endpoint). |
+| 🧪 **Honest feedback loop** | Every modeling tool reports the feature's health (`OK`/`WARNING`/`ERROR`) so the model notices failures instead of piling more features on top. |
+
+## Quick start
+
+**1. Create API keys** at <https://dev-portal.onshape.com/keys> (tick *Read* and *Write*; *Delete*
+only if you want `delete_feature`). Copy the secret immediately - Onshape shows it once.
+
+**2. Add the server to your MCP client.** Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "onshape": {
+      "command": "uvx",
+      "args": ["onshape-jamcp"],
+      "env": {
+        "ONSHAPE_ACCESS_KEY": "your-access-key",
+        "ONSHAPE_SECRET_KEY": "your-secret-key",
+        "ONSHAPE_UNITS": "metric",
+        "ONSHAPE_SCREENSHOT_REVIEW": "true"
+      }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add onshape -e ONSHAPE_ACCESS_KEY=... -e ONSHAPE_SECRET_KEY=... -- uvx onshape-jamcp`
+
+> Until the package is published to PyPI, run it from a checkout instead: replace the command with
+> `"command": "uv", "args": ["run", "--directory", "/path/to/onshape-jamcp", "onshape-jamcp"]`.
+> More clients and details: [docs/getting-started.md](docs/getting-started.md).
+
+**3. Ask for something:**
+
+> *"Create a document called 'Bracket'. In a new Part Studio model a 60 × 40 mm plate, 8 mm thick,
+> with four 5 mm holes 6 mm from the corners and 4 mm fillets on the vertical edges. Show me a
+> screenshot when you're done."*
+
+## Verify it works against your account
+
+```bash
+cp .env.example .env        # fill in the two keys
+uv run python scripts/smoke_test.py            # on a free plan add --public (see below)
+```
+
+It creates a throw-away document (private; on a free plan Onshape only allows public ones, so pass
+`--public`), models a plate, checks the dimensions/orientation/hole volume/fillets/edit/screenshot/
+STEP+STL export numerically, then moves the document to Onshape's trash.
+It prints `PASS`/`FAIL` per check. This is the step that confirms the assumptions a simulated
+Onshape cannot (plane orientation, face normals, extrude direction).
+
+## Settings
+
+Set as environment variables (the `env` block of your MCP client) or CLI flags. The important ones:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ONSHAPE_ACCESS_KEY` / `ONSHAPE_SECRET_KEY` | - | **Required.** API keys. |
+| `ONSHAPE_UNITS` | `metric` | `metric` = millimeters, `imperial` = inches. Flag: `--units`. |
+| `ONSHAPE_SCREENSHOT_REVIEW` | `true` | Send screenshots to the LLM (`true`) or only save them (`false`). Flag: `--[no-]screenshot-review`. |
+| `ONSHAPE_READ_ONLY` | `false` | Hide all write tools. Flag: `--read-only`. |
+| `ONSHAPE_BASE_URL` | `https://cad.onshape.com` | Enterprise: `https://yourcompany.onshape.com`. |
+
+Everything else (image size, output folder, timeout, auth mode, API version, log level) is in
+[docs/configuration.md](docs/configuration.md).
+
+## Tools
+
+| Group | Tools |
+|---|---|
+| Server | `get_settings`, `whoami` |
+| Documents | `list_documents`, `get_document`, `create_document`, `create_element` |
+| Inspect | `list_features`, `list_parts`, `get_part_properties`, `get_body_details`, `get_assembly`, `run_featurescript` |
+| Model | `create_sketch`, `extrude`, `fillet`, `chamfer`, `update_feature`, `delete_feature`, `add_feature` |
+| Look & export | `capture_screenshot`, `export_model` |
+| Escape hatch | `onshape_api_request` |
+
+Full parameter reference (generated from the code): [docs/tools.md](docs/tools.md).
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) - keys, installing in each client, first prompt
+- [Configuration](docs/configuration.md) - every setting, units, precedence
+- [How-to recipes](docs/how-to.md) - holes, fillets, edits, inches, export, read-only, advanced features
+- [Screenshots & token cost](docs/screenshots.md) - what the review toggle does and when to use it
+- [Tool reference](docs/tools.md) - all tools and parameters
+- [Troubleshooting](docs/troubleshooting.md)
+- [Development](docs/development.md) - architecture, tests, adding a tool
+- [Publishing](docs/publishing.md) - PyPI and Glama
+- [Comparison](docs/comparison.md) - how this relates to the other Onshape MCP servers
+
+## Security notes
+
+- API keys stay in your MCP client's config / environment. They are never returned by any tool,
+  never logged, and requests are HMAC-signed so the secret is not even sent over the wire.
+- **Onshape's free plan makes every document public.** Do not model confidential work there.
+- Write tools act as *you* on your real documents. Use `ONSHAPE_READ_ONLY=true` when you only want
+  the assistant to look around, and rely on Onshape's version history as your undo.
+- With screenshot review on, rendered images are sent to your LLM provider like any other message.
+
+## Acknowledgements
+
+Prior art that shaped this project: [hedless/onshape-mcp](https://github.com/hedless/onshape-mcp)
+(MIT; the Onshape feature JSON conventions were cross-checked against it) and
+[altendky/onshape-mcp](https://github.com/altendky/onshape-mcp). See
+[docs/comparison.md](docs/comparison.md).
+
+## License
+
+[MIT](LICENSE). Not affiliated with or endorsed by PTC / Onshape.

onshape_jamcp-1.0.0/README.md

@@ -0,0 +1,133 @@
+# onshape-jamcp
+
+**J**ust **A**nother **MCP** server for [Onshape](https://www.onshape.com) CAD. It lets an AI
+assistant (Claude, Cursor, VS Code, any [MCP](https://modelcontextprotocol.io) client) find your
+documents, model parts, measure them, look at them and export them - in **millimeters by default**,
+with a switch for **inches**, and a switch that decides whether the assistant gets to **see
+screenshots** (which costs tokens) or not.
+
+> **Status: alpha, verified live.** 140+ automated tests run against a simulated Onshape, and
+> [`scripts/smoke_test.py`](scripts/smoke_test.py) passed **31/31 checks against a real Onshape
+> account** (free plan, 2026-11-14): sketch → extrude → fillet → hole → edit → screenshot → STEP/STL
+> export, with orientation and dimensions measured. Chamfer, assemblies with mates and paid-plan
+> behavior are not yet verified live - see [what is verified](docs/development.md#verification-status-read-this-before-trusting-a-tool).
+> Re-run the smoke test on your own account (see [below](#verify-it-works-against-your-account)).
+
+## Highlights
+
+| | |
+|---|---|
+| 📏 **Metric by default** | Every length you send or receive is in **mm**. Set `ONSHAPE_UNITS=imperial` for inches. Angles are always degrees. |
+| 👁️ **Screenshot review toggle** | `ONSHAPE_SCREENSHOT_REVIEW=true` sends renders to the model so it can *see* its work (≈ 640 tokens per 800×600 image). `false` only saves them to disk - zero image tokens. Override per call with `review`. |
+| 🔒 **Read-only mode** | `ONSHAPE_READ_ONLY=true` removes every tool that can modify a document. |
+| 🧰 **22 focused tools** | Documents, sketch → extrude → fillet/chamfer, edit parameters, measure, faces/edges, assemblies, screenshots, STEP/STL export - plus escape hatches (raw feature JSON, FeatureScript, any REST endpoint). |
+| 🧪 **Honest feedback loop** | Every modeling tool reports the feature's health (`OK`/`WARNING`/`ERROR`) so the model notices failures instead of piling more features on top. |
+
+## Quick start
+
+**1. Create API keys** at <https://dev-portal.onshape.com/keys> (tick *Read* and *Write*; *Delete*
+only if you want `delete_feature`). Copy the secret immediately - Onshape shows it once.
+
+**2. Add the server to your MCP client.** Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "onshape": {
+      "command": "uvx",
+      "args": ["onshape-jamcp"],
+      "env": {
+        "ONSHAPE_ACCESS_KEY": "your-access-key",
+        "ONSHAPE_SECRET_KEY": "your-secret-key",
+        "ONSHAPE_UNITS": "metric",
+        "ONSHAPE_SCREENSHOT_REVIEW": "true"
+      }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add onshape -e ONSHAPE_ACCESS_KEY=... -e ONSHAPE_SECRET_KEY=... -- uvx onshape-jamcp`
+
+> Until the package is published to PyPI, run it from a checkout instead: replace the command with
+> `"command": "uv", "args": ["run", "--directory", "/path/to/onshape-jamcp", "onshape-jamcp"]`.
+> More clients and details: [docs/getting-started.md](docs/getting-started.md).
+
+**3. Ask for something:**
+
+> *"Create a document called 'Bracket'. In a new Part Studio model a 60 × 40 mm plate, 8 mm thick,
+> with four 5 mm holes 6 mm from the corners and 4 mm fillets on the vertical edges. Show me a
+> screenshot when you're done."*
+
+## Verify it works against your account
+
+```bash
+cp .env.example .env        # fill in the two keys
+uv run python scripts/smoke_test.py            # on a free plan add --public (see below)
+```
+
+It creates a throw-away document (private; on a free plan Onshape only allows public ones, so pass
+`--public`), models a plate, checks the dimensions/orientation/hole volume/fillets/edit/screenshot/
+STEP+STL export numerically, then moves the document to Onshape's trash.
+It prints `PASS`/`FAIL` per check. This is the step that confirms the assumptions a simulated
+Onshape cannot (plane orientation, face normals, extrude direction).
+
+## Settings
+
+Set as environment variables (the `env` block of your MCP client) or CLI flags. The important ones:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ONSHAPE_ACCESS_KEY` / `ONSHAPE_SECRET_KEY` | - | **Required.** API keys. |
+| `ONSHAPE_UNITS` | `metric` | `metric` = millimeters, `imperial` = inches. Flag: `--units`. |
+| `ONSHAPE_SCREENSHOT_REVIEW` | `true` | Send screenshots to the LLM (`true`) or only save them (`false`). Flag: `--[no-]screenshot-review`. |
+| `ONSHAPE_READ_ONLY` | `false` | Hide all write tools. Flag: `--read-only`. |
+| `ONSHAPE_BASE_URL` | `https://cad.onshape.com` | Enterprise: `https://yourcompany.onshape.com`. |
+
+Everything else (image size, output folder, timeout, auth mode, API version, log level) is in
+[docs/configuration.md](docs/configuration.md).
+
+## Tools
+
+| Group | Tools |
+|---|---|
+| Server | `get_settings`, `whoami` |
+| Documents | `list_documents`, `get_document`, `create_document`, `create_element` |
+| Inspect | `list_features`, `list_parts`, `get_part_properties`, `get_body_details`, `get_assembly`, `run_featurescript` |
+| Model | `create_sketch`, `extrude`, `fillet`, `chamfer`, `update_feature`, `delete_feature`, `add_feature` |
+| Look & export | `capture_screenshot`, `export_model` |
+| Escape hatch | `onshape_api_request` |
+
+Full parameter reference (generated from the code): [docs/tools.md](docs/tools.md).
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) - keys, installing in each client, first prompt
+- [Configuration](docs/configuration.md) - every setting, units, precedence
+- [How-to recipes](docs/how-to.md) - holes, fillets, edits, inches, export, read-only, advanced features
+- [Screenshots & token cost](docs/screenshots.md) - what the review toggle does and when to use it
+- [Tool reference](docs/tools.md) - all tools and parameters
+- [Troubleshooting](docs/troubleshooting.md)
+- [Development](docs/development.md) - architecture, tests, adding a tool
+- [Publishing](docs/publishing.md) - PyPI and Glama
+- [Comparison](docs/comparison.md) - how this relates to the other Onshape MCP servers
+
+## Security notes
+
+- API keys stay in your MCP client's config / environment. They are never returned by any tool,
+  never logged, and requests are HMAC-signed so the secret is not even sent over the wire.
+- **Onshape's free plan makes every document public.** Do not model confidential work there.
+- Write tools act as *you* on your real documents. Use `ONSHAPE_READ_ONLY=true` when you only want
+  the assistant to look around, and rely on Onshape's version history as your undo.
+- With screenshot review on, rendered images are sent to your LLM provider like any other message.
+
+## Acknowledgements
+
+Prior art that shaped this project: [hedless/onshape-mcp](https://github.com/hedless/onshape-mcp)
+(MIT; the Onshape feature JSON conventions were cross-checked against it) and
+[altendky/onshape-mcp](https://github.com/altendky/onshape-mcp). See
+[docs/comparison.md](docs/comparison.md).
+
+## License
+
+[MIT](LICENSE). Not affiliated with or endorsed by PTC / Onshape.

onshape_jamcp-1.0.0/docs/comparison.md

@@ -0,0 +1,47 @@
+# How this compares
+
+Several MCP servers touch Onshape. This table is based on each project's own README/listing as of
+November 2026; check them for current details.
+
+| | **onshape-jamcp** (this) | [hedless/onshape-mcp](https://github.com/hedless/onshape-mcp) | [altendky/onshape-mcp](https://github.com/altendky/onshape-mcp) | [Onshape Labs FeatureScript MCP](https://www.onshape.com/en/blog/featurescript-mcp-server-enables-text-code-cad) |
+|---|---|---|---|---|
+| Language / runs | Python, local stdio | Python, local stdio | Rust, local stdio (+ experimental HTTP) | Hosted by Onshape (HTTP) |
+| Install | `uvx` / `pip` / Docker | clone + venv | `npx` or binary | Onshape App Store subscription |
+| Auth | API keys (HMAC; Basic as fallback) | API keys (Basic) | OAuth (default) or API keys | Your Onshape sign-in |
+| Default units | **millimeters**, inches via setting | inches only | not stated | n/a |
+| Screenshots | yes, with a **token-saving review toggle** | no | yes | no |
+| Read-only mode | yes | no | - | - |
+| Scope | documents, sketch/extrude/fillet/chamfer, edit, measure, faces/edges, assembly view, export, raw API | very broad modeling + assemblies/mates (45+ tools) | broad, endpoints discovered dynamically; FeatureScript authoring | generate/debug FeatureScript custom features only |
+| Tool count | 22 | 45-48 | - | - |
+
+## Where jamcp is deliberately different
+
+- **Units are a first-class setting**, not an afterthought: millimeters by default, one switch to
+  inches, explicit units always honored, every output converted.
+- **Screenshot cost is under your control**: review on/off globally and per call, with token
+  estimates reported.
+- **Smaller tool surface.** Twenty-two well-described tools plus escape hatches, rather than 45+.
+  Fewer tools means less context spent on the tool list and fewer wrong choices by the model.
+  (Glama's quality scoring also penalizes very large tool counts.)
+- **Nothing hard-coded that Onshape can tell us.** Origin-plane IDs are looked up with FeatureScript
+  at runtime instead of being baked in as constants. (One existing server hard-codes
+  Front/Top/Right as three-letter IDs; that mapping could not be confirmed independently, and a
+  wrong constant would silently put sketches on the wrong plane.)
+- **Safe to explore**: read-only mode removes write tools entirely.
+
+## Where others are ahead (today)
+
+- **hedless/onshape-mcp** has assembly mates, positioning, interference checks, patterns, revolve,
+  thicken, variables and a much larger test and example base. If you need to build assemblies with
+  an AI right now, it covers more. jamcp's `add_feature` and `onshape_api_request` can reach those
+  features but without the ergonomic helpers.
+- **altendky/onshape-mcp** supports OAuth (no long-lived secret keys) and a hosted HTTP mode, and
+  it discovers API endpoints dynamically rather than shipping a fixed tool list.
+- **Onshape's FeatureScript MCP** is the right tool for *authoring custom features*; it is
+  complementary to this server, not a replacement.
+
+## Acknowledgement
+
+The Onshape feature JSON conventions (BTM types, sketch entity layout, sketch-region queries) were
+cross-checked against hedless/onshape-mcp (MIT) and Onshape's public OpenAPI specification. No code
+was copied.

onshape_jamcp-1.0.0/docs/configuration.md

@@ -0,0 +1,98 @@
+# Configuration
+
+onshape-jamcp is configured with **environment variables**. In an MCP client these go in the
+server's `env` block. A few have **command-line flags** (set in the client's `args`), which
+override the environment.
+
+```json
+{
+  "command": "uvx",
+  "args": ["onshape-jamcp", "--units", "imperial", "--no-screenshot-review"],
+  "env": { "ONSHAPE_ACCESS_KEY": "...", "ONSHAPE_SECRET_KEY": "..." }
+}
+```
+
+Invalid values stop the server at startup with a message naming the variable (exit code 2). Missing
+API keys do **not** stop it: the server starts and lists its tools, and each tool call that needs
+Onshape reports what to set.
+
+## All settings
+
+| Variable | Flag | Default | Description |
+|---|---|---|---|
+| `ONSHAPE_ACCESS_KEY` | | - | API access key (required for any tool that calls Onshape). |
+| `ONSHAPE_SECRET_KEY` | | - | API secret key. |
+| `ONSHAPE_UNITS` | `--units` | `metric` | `metric` (millimeters) or `imperial` (inches). Aliases: `mm`, `inch`, `inches`, `in`. |
+| `ONSHAPE_SCREENSHOT_REVIEW` | `--screenshot-review` / `--no-screenshot-review` | `true` | Send screenshots to the LLM for review. See [screenshots](screenshots.md). |
+| `ONSHAPE_SCREENSHOT_WIDTH` | | `800` | Default screenshot width in px (64-2000). |
+| `ONSHAPE_SCREENSHOT_HEIGHT` | | `600` | Default screenshot height in px (64-2000). |
+| `ONSHAPE_OUTPUT_DIR` | | system temp `/onshape-jamcp` | Where screenshots (`screenshots/`) and exports (`exports/`) are saved. |
+| `ONSHAPE_READ_ONLY` | `--read-only` | `false` | Do not register any tool that modifies documents; block non-GET `onshape_api_request`. |
+| `ONSHAPE_BASE_URL` | | `https://cad.onshape.com` | Onshape origin. Enterprise accounts: `https://yourcompany.onshape.com`. Must be `https` (plain `http` only for localhost). |
+| `ONSHAPE_API_VERSION` | | `v17` | REST API version, `v` + number. The tools were written against v17. |
+| `ONSHAPE_AUTH_MODE` | | `hmac` | `hmac` signs each request (the secret is never transmitted). `basic` sends `access:secret` as HTTP Basic over HTTPS; Onshape documents it as lowest-security, "for local testing only", so use it only as a fallback if signing misbehaves. |
+| `ONSHAPE_TIMEOUT` | | `60` | Per-request timeout in seconds (1-600). Raise it for very large models. |
+| `ONSHAPE_LOG_LEVEL` | | `WARNING` | `DEBUG`, `INFO`, `WARNING`, `ERROR`. Logs go to **stderr** (stdout is the MCP channel). `DEBUG` also logs HTTP requests (never credentials or bodies). |
+
+Booleans accept `true/false`, `1/0`, `yes/no`, `on/off`.
+
+## Units
+
+The unit system is a single global setting.
+
+| | `metric` (default) | `imperial` |
+|---|---|---|
+| Lengths in and out | millimeters (`mm`) | inches (`in`) |
+| Areas | `mm^2` | `in^2` |
+| Volumes | `mm^3` | `in^3` |
+| Angles | degrees | degrees |
+| Mass | kilograms (always) | kilograms (always) |
+
+How it works:
+
+- **Plain numbers are in the configured unit.** With metric, `depth: 10` means 10 mm; with imperial
+  it means 10 in.
+- **Explicit units always win.** Any length also accepts a string such as `"0.5 in"` or `"25 mm"`
+  (units: `mm`, `cm`, `m`, `in`, `ft`, `yd`), so you can mix systems in one request.
+- **Onshape expressions** are accepted where Onshape evaluates them (`extrude.depth`, `fillet.radius`,
+  `chamfer.distance`, `update_feature` values): `"#width"`, `"#width / 2"`. Sketch geometry needs
+  concrete numbers because the API stores it in meters.
+- **Everything the server returns is converted** to the configured unit: bounding boxes, volumes,
+  centroids, face origins, edge end points, assembly positions. `get_settings` tells the model which
+  unit is active.
+- Two things stay in raw SI because they are pass-through: results of `run_featurescript` (meters)
+  and `onshape_api_request` (meters). Their tool descriptions say so.
+
+Switching units never changes existing models - Onshape stores geometry in SI internally and only
+the *input and output of this server* change.
+
+## Screenshots
+
+- `ONSHAPE_SCREENSHOT_REVIEW=true` (default): `capture_screenshot` saves the PNG **and** returns it
+  to the model.
+- `ONSHAPE_SCREENSHOT_REVIEW=false`: it saves the PNG and returns only the file path and metadata -
+  **no image tokens**.
+- Per call: `capture_screenshot(review=true|false)` overrides the setting for that call.
+
+Details, token numbers and strategy: [screenshots.md](screenshots.md).
+
+## Read-only mode
+
+With `ONSHAPE_READ_ONLY=true` the modeling and document-creating tools (`create_document`,
+`create_element`, `create_sketch`, `extrude`, `fillet`, `chamfer`, `update_feature`,
+`delete_feature`, `add_feature`) are **not registered at all**, so the model cannot even try. Reading,
+measuring, screenshots, export and `GET` requests through `onshape_api_request` keep working.
+Note that export creates a temporary translation job on Onshape's side but does not change your
+document.
+
+## Precedence
+
+command-line flag → environment variable → built-in default.
+
+## Per-client notes
+
+- **Claude Desktop** passes only the variables in `env` to the server - it does not inherit your
+  shell environment. Put the keys in `env`.
+- **Windows paths** in JSON need escaped backslashes (`"D:\\source\\repos\\..."`) or forward slashes.
+- For local development a `.env` file is read by `scripts/smoke_test.py` only; the server itself
+  reads the real process environment.