Deploy Onshape MCP to Hugging Face Spaces

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayode Williams Olalere
+
+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.

README.md

@@ -1,13 +1,26 @@
 ---
-title: Onshape Mcp
-emoji: 🦀
-colorFrom: yellow
-colorTo: yellow
+title: Onshape CAD MCP
+emoji: 📐
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.26.0
-python_version: '3.12'
+sdk_version: 5.20.0
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 📐 Onshape MCP Server
+
+A natural-language agent that models 3D CAD directly in Onshape. Drives the Onshape web canvas using Playwright hands and Gemini vision.
+
+### 🔗 Connect to ChatGPT / Claude / Cursor
+
+**MCP SSE Endpoint:**
+```text
+https://x-r-1-8-onshape-mcp.hf.space/sse
+```
+
+### Features
+* **Zero Installation for Testers**: Connect directly over SSE without running local code.
+* **Full Sketch Suite**: 35+ tools (lines, rectangles, splines, polygons, fillets, chamfers, offset, trim, mirror).
+* **Deterministic Fast Engine**: 0-token instant CAD operations without LLM overhead.

app.py

@@ -0,0 +1,176 @@
+"""Hugging Face Space Application for Onshape MCP.
+Provides both:
+1. An interactive Gradio web playground at `/`
+2. A full Model Context Protocol (MCP) SSE endpoint at `/sse` for ChatGPT, Claude, and Cursor.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# Add src to sys.path
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+import gradio as gr
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+
+# Auto-ensure Playwright chromium is installed
+try:
+    subprocess.run([sys.executable, "-m", "playwright", "install", "chromium"], check=False)
+except Exception:
+    pass
+
+# ZeroGPU compatibility (no-op decorator so ZeroGPU hardware remains active without burning quota)
+try:
+    import spaces
+
+    @spaces.GPU
+    def _gpu_keepalive() -> str:
+        return "GPU active"
+except Exception:
+    def _gpu_keepalive() -> str:
+        return "CPU fallback"
+
+# Import Onshape MCP server
+from onshape_mcp.server import mcp
+from onshape_mcp.intent import parse as parse_intent
+from onshape_mcp.tools import ALL_TOOLS
+
+# 1. Build Gradio Interface
+def test_prompt(user_prompt: str) -> str:
+    """Preview how Onshape MCP parses a prompt into CAD tools."""
+    if not user_prompt.strip():
+        return "Please enter a CAD prompt (e.g., 'Draw a 10cm by 5cm box on the Top plane')."
+    try:
+        plan = parse_intent(user_prompt)
+        if plan:
+            return json.dumps(
+                {
+                    "status": "Recognized Deterministic CAD Actions",
+                    "action_count": len(plan),
+                    "actions": [
+                        {"tool": tool, "args": args} for tool, args in plan
+                    ],
+                },
+                indent=2,
+            )
+        else:
+            return json.dumps(
+                {
+                    "status": "Complex Multi-Step Goal",
+                    "handler": "Autonomous Vision Loop (act)",
+                    "note": "Will be executed closed-loop in Onshape.",
+                },
+                indent=2,
+            )
+    except Exception as e:
+        return f"Error parsing prompt: {e}"
+
+
+def list_tools() -> str:
+    """Return available sketch tools catalog."""
+    tools_summary = []
+    for tool in ALL_TOOLS:
+        tools_summary.append({
+            "name": tool.name,
+            "purpose": tool.purpose,
+            "requires": tool.requires,
+            "produces": tool.produces,
+            "status": tool.status,
+        })
+    return json.dumps(tools_summary, indent=2)
+
+
+with gr.Blocks(title="Onshape MCP — Autonomous CAD AI", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        """
+        # 📐 Onshape MCP — Autonomous CAD Agent
+        ### Control Onshape directly from ChatGPT, Claude, Cursor, and any MCP-compatible AI.
+        """
+    )
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            gr.Markdown(
+                """
+                ### 🔗 Connect This Space to Your AI Client
+
+                **MCP SSE Endpoint:**
+                ```text
+                https://x-r-1-8-onshape-mcp.hf.space/sse
+                ```
+
+                * **ChatGPT Web**: In Custom GPTs or MCP Settings, add the SSE URL above.
+                * **Claude Desktop**: Add this block to `claude_desktop_config.json`:
+                ```json
+                {
+                  "mcpServers": {
+                    "onshape": {
+                      "url": "https://x-r-1-8-onshape-mcp.hf.space/sse"
+                    }
+                  }
+                }
+                ```
+                * **Cursor / LibreChat**: Add as a remote SSE MCP server.
+                """
+            )
+
+        with gr.Column(scale=1):
+            gr.Markdown(
+                """
+                ### ⚙️ Space Status
+                * **Hardware**: ZeroGPU (RTX PRO 6000)
+                * **Status**: 🟢 Server Live
+                * **Sketch Tools**: 35+ Tools & 13 Constraints
+                * **Protocol**: Model Context Protocol (2024-11-05)
+                """
+            )
+
+    gr.Markdown("---")
+    gr.Markdown("### 🧪 Test CAD Natural Language Parser")
+
+    with gr.Row():
+        with gr.Column():
+            prompt_input = gr.Textbox(
+                label="CAD Prompt",
+                placeholder="e.g. Draw a 10cm by 5cm box on the Top plane and extrude 20mm",
+                lines=2,
+                value="Draw a 10cm by 5cm box on the Top plane",
+            )
+            btn_run = gr.Button("Parse Intent Plan", variant="primary")
+        with gr.Column():
+            output_json = gr.Code(label="Parsed Deterministic Plan", language="json")
+
+    btn_run.click(fn=test_prompt, inputs=[prompt_input], outputs=[output_json])
+
+    with gr.Accordion("📚 View Full CAD Tools Catalog (35+ Tools)", open=False):
+        tools_viewer = gr.Code(value=list_tools(), language="json", lines=15)
+
+# 2. Create Parent FastAPI App
+app = FastAPI()
+
+# Enable CORS for web clients
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# 3. Mount FastMCP SSE App at /
+sse_app = mcp.sse_app()
+app.mount("/mcp", sse_app)
+
+# Also expose direct /sse and /messages routes at root
+for route in sse_app.routes:
+    app.routes.append(route)
+
+# 4. Mount Gradio interface at root
+app = gr.mount_gradio_app(app, demo, path="/")

packages.txt

@@ -0,0 +1,16 @@
+libnss3
+libnspr4
+libatk1.0-0
+libatk-bridge2.0-0
+libcups2
+libdrm2
+libxkbcommon0
+libxcomposite1
+libxdamage1
+libxfixes3
+libxrandr2
+libgbm1
+libpango-1.0-0
+libcairo2
+libasound2
+xvfb

pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "onshape-mcp"
+version = "0.0.1"
+description = "Visual agentic MCP server for Onshape, driven by Gemini web vision."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Kayode Williams Olalere" },
+]
+dependencies = [
+    "mcp>=1.2.0,<2.0.0",  # TODO: migrate to MCPServer in M2
+    "playwright>=1.48.0",
+    "pydantic>=2.8.0",
+    "python-dotenv>=1.0.1",
+    "Pillow>=10.4.0",
+    "httpx>=0.27.0",
+    "browser-cookie3>=0.20.1",
+    "flask>=3.0.0",
+    "gemini-webapi>=2.0.0",  # verify GeminiClient API on first install
+]
+
+[project.scripts]
+onshape-mcp = "onshape_mcp.server:main"
+onshape-mcp-setup = "onshape_mcp.setup:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.6.0",
+    "mypy>=1.11.0",
+]
+
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q -p no:launch_testing -p no:launch_ros"

requirements.txt

@@ -0,0 +1,14 @@
+gradio>=5.0.0
+spaces
+fastapi
+starlette
+uvicorn
+mcp>=1.2.0,<2.0.0
+playwright>=1.48.0
+pydantic>=2.8.0
+python-dotenv>=1.0.1
+Pillow>=10.4.0
+httpx>=0.27.0
+browser-cookie3>=0.20.1
+flask>=3.0.0
+gemini-webapi>=2.0.0

src/onshape_mcp.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: onshape-mcp
+Version: 0.0.1
+Summary: Visual agentic MCP server for Onshape, driven by Gemini web vision.
+Author: Kayode Williams Olalere
+License: MIT License
+        
+        Copyright (c) 2026 Kayode Williams Olalere
+        
+        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.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2.0.0,>=1.2.0
+Requires-Dist: playwright>=1.48.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: Pillow>=10.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: browser-cookie3>=0.20.1
+Requires-Dist: flask>=3.0.0
+Requires-Dist: gemini-webapi>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Dynamic: license-file
+
+# onshape-mcp
+
+I wanted a way to drive Onshape from a language model the way I drive it with
+my hands. Click a face. Draw a sketch. Extrude. Chamfer. The existing Onshape
+MCP wraps the REST API and FeatureScript, which works but feels like coding,
+not modeling. This server aims at the other 70% of CAD work that lives in
+the viewport.
+
+It uses a vision-capable LLM (Gemini web, no API key, my Plus cookies) as
+eyes, Playwright as hands, and an MCP surface so any MCP-aware client can
+talk to it. Every action is journaled, so I can undo, replay, or branch.
+
+## Status
+
+- **M0** done: scaffold, smoke tests, public repo, safety rails.
+- **M1** done: driver primitives, Onshape tool datasheet, 10 wired tools
+  (`view.fit`, `sketch.start/rectangle/circle/line/exit`, `feature.extrude/fillet/chamfer`,
+  `select.face/edge`, `ui.undo/redo`), closed-loop `act(goal)` agent.
+- **M2** next: pattern, mirror_body, assembly.mate, sketch.constrain flyout,
+  journal-replay undo, a real perceptual-diff for the stuck detector.
+
+## What it looks like from the client side
+
+Two ways to drive it:
+
+**Direct tools.** I call individual MCP tools when I want fine control:
+`screenshot`, `describe_view`, `viewport_size`, `journal_tail`, `tool_datasheet`,
+`open_doc`, and the per-tool `onshape_*` ones. Useful when I want to see
+each step and steer.
+
+**Closed-loop `act`.** I just say what I want:
+`act(goal="draw a 50x30mm rectangle on the top plane and extrude it 10mm")`.
+Gemini sees each screenshot, picks the next tool, calls it, repeats until
+the goal is met or it bails. Bounded by `max_steps` (default 25) and a
+stuck detector (3 identical screenshots in a row = stop).
+
+## How I run it
+
+```bash
+# one-shot bootstrap (use python3 explicitly, "python" is not always aliased)
+python3 scripts/bootstrap.py
+
+# then start the server
+source .venv/bin/activate
+python3 -m onshape_mcp.server
+```
+
+`bootstrap.py` does the venv, the pip install, the Chromium download, the
+cookie extraction, the Onshape login, and the M0 sanity checks. Re-run it
+any time; it's idempotent.
+
+## A note on Google + automated browsers
+
+Google blocks automated browser logins ("This browser or app may not be
+secure") when you launch Playwright's bundled Chromium against a Google
+login page. I hit this. The fix in `bootstrap.py` is to try reading the
+Gemini cookies straight out of my real Chrome session first, via
+`browser-cookie3`. No browser launch, no automation block. If that
+somehow fails (Chrome locked, no Chrome installed), it falls back to
+launching real Chrome via Playwright (`channel="chrome"`), and only as
+a last resort launches bundled Chromium.
+
+The same Chrome-first choice applies to the main driver. Set
+`ONSHAPE_BROWSER_CHANNEL=auto` (the default) and the server uses real
+Chrome when available, falling back to bundled Chromium. Set it to
+`chromium` to skip the Chrome attempt (e.g. on a Pi with no Chrome
+installed).
+
+## Architecture in one screen
+
+```
+                ┌───────────────���────────────────────────┐
+                │  MCP client (Claude Code, Cursor, …)  │
+                └──────────────────┬─────────────────────┘
+                                   │ mcp__onshape__* tool calls
+                ┌──────────────────▼─────────────────────┐
+                │  onshape-mcp server (this repo)        │
+                │  ┌──────────┐  ┌──────────┐  ┌──────┐  │
+                │  │  tools   │  │ journal  │  │ loop │  │
+                │  └────┬─────┘  └────┬─────┘  └───┬──┘  │
+                └───────┼─────────────┼────────────┼─────┘
+                        │             │            │
+        ┌───────────────▼─────┐  ┌────▼─────┐  ┌───▼────────────┐
+        │  Playwright driver  │  │  JSONL   │  │  Gemini web    │
+        │  (headless Chromium)│  │  state/  │  │  (vision + LLM)│
+        └───────────────┬─────┘  └──────────┘  └────────────────┘
+                        │
+                ┌───────▼────────┐
+                │  Onshape web   │
+                └────────────────┘
+```
+
+Five layers, bottom up:
+
+1. **Driver primitives** in `driver.py`. Click, type, press chord, drag,
+   find by text, screenshot. Knows nothing about Onshape.
+2. **UI bindings** in `shortcuts.py`. Maps each semantic tool to its
+   keyboard chord or toolbar button, with a `confidence` flag so I know
+   what to retest.
+3. **UI actions** in `ui_actions.py`. Compose primitives + bindings into
+   one logical op (`sketch_rectangle(d, c1, c2)` = activate tool, click
+   c1, click c2, Esc, screenshot). Every op journals itself.
+4. **Dispatch table** in `server.py`. Maps tool names back to ui_actions
+   functions, flattens LLM-friendly args to tuples.
+5. **Agent loop** `act(goal)` in `server.py`. Screenshot, ask Gemini
+   what's next, dispatch, repeat. Bounded by `max_steps` and a stuck
+   detector.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

src/onshape_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+LICENSE
+README.md
+pyproject.toml
+src/onshape_mcp/__init__.py
+src/onshape_mcp/config.py
+src/onshape_mcp/dispatch.py
+src/onshape_mcp/driver.py
+src/onshape_mcp/fast_exec.py
+src/onshape_mcp/intent.py
+src/onshape_mcp/journal.py
+src/onshape_mcp/loop.py
+src/onshape_mcp/server.py
+src/onshape_mcp/setup.py
+src/onshape_mcp/shortcuts.py
+src/onshape_mcp/tools.py
+src/onshape_mcp/ui_actions.py
+src/onshape_mcp/vision.py
+src/onshape_mcp.egg-info/PKG-INFO
+src/onshape_mcp.egg-info/SOURCES.txt
+src/onshape_mcp.egg-info/dependency_links.txt
+src/onshape_mcp.egg-info/entry_points.txt
+src/onshape_mcp.egg-info/requires.txt
+src/onshape_mcp.egg-info/top_level.txt
+tests/test_intent.py
+tests/test_planes_and_quadrants.py
+tests/test_sketch_tools_spec.py
+tests/test_smoke.py

src/onshape_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/onshape_mcp.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+onshape-mcp = onshape_mcp.server:main
+onshape-mcp-setup = onshape_mcp.setup:main

src/onshape_mcp.egg-info/requires.txt

@@ -0,0 +1,14 @@
+mcp<2.0.0,>=1.2.0
+playwright>=1.48.0
+pydantic>=2.8.0
+python-dotenv>=1.0.1
+Pillow>=10.4.0
+httpx>=0.27.0
+browser-cookie3>=0.20.1
+flask>=3.0.0
+gemini-webapi>=2.0.0
+
+[dev]
+pytest>=8.3.0
+ruff>=0.6.0
+mypy>=1.11.0

src/onshape_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+onshape_mcp

src/onshape_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""onshape-mcp. Visual agentic MCP server for Onshape."""
+
+__version__ = "0.0.1"

src/onshape_mcp/config.py

@@ -0,0 +1,96 @@
+"""Configuration loaded from .env. The .env file is gitignored (see SECURITY.md)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+def _find_base_dir() -> Path:
+    """Determine the base directory for onshape-mcp configuration, cookies, and state.
+
+    Priority:
+    1. ONSHAPE_DIR or ONSHAPE_HOME environment variable if explicitly set.
+    2. Local source repository if pyproject.toml and src/onshape_mcp exist in cwd or parents.
+    3. User home directory fallback: ~/.onshape-mcp (safe for uvx, pip, Claude Desktop).
+    """
+    if "ONSHAPE_DIR" in os.environ:
+        return Path(os.environ["ONSHAPE_DIR"]).expanduser().resolve()
+    if "ONSHAPE_HOME" in os.environ:
+        return Path(os.environ["ONSHAPE_HOME"]).expanduser().resolve()
+
+    cwd = Path.cwd()
+    for p in [cwd, *cwd.parents]:
+        if (p / "pyproject.toml").is_file() and (p / "src" / "onshape_mcp").is_dir():
+            return p
+
+    user_base = Path.home() / ".onshape-mcp"
+    user_base.mkdir(parents=True, exist_ok=True)
+    return user_base
+
+
+_BASE_DIR = _find_base_dir()
+
+# Load env from base directory (.env in repo or ~/.onshape-mcp/.env)
+if (_BASE_DIR / ".env").is_file():
+    load_dotenv(_BASE_DIR / ".env")
+elif (Path.home() / ".onshape-mcp" / ".env").is_file():
+    load_dotenv(Path.home() / ".onshape-mcp" / ".env")
+
+
+def _path(key: str, default: str) -> Path:
+    raw = os.getenv(key, default)
+    p = Path(raw).expanduser()
+    if not p.is_absolute():
+        p = (_BASE_DIR / p).resolve()
+    return p
+
+
+def _bool(key: str, default: bool) -> bool:
+    val = os.getenv(key)
+    if val is None:
+        return default
+    return val.strip().lower() in ("1", "true", "yes", "on")
+
+
+class Settings:
+    # Onshape cookies live as plain JSON, not in Chrome's encrypted DB.
+    # Chrome's DB on Linux uses a keyring key that's only available to
+    # graphical sessions; headless Playwright can't decrypt, so cookies
+    # look empty. Storing as JSON dodges the whole keyring mess.
+    onshape_cookie_file: Path = _path("ONSHAPE_COOKIE_FILE", "./cookies/onshape.cookies.json")
+    onshape_browser_profile: Path = _path("ONSHAPE_BROWSER_PROFILE", "./playwright-profile")
+    gemini_cookie_file: Path = _path("GEMINI_COOKIE_FILE", "./cookies/gemini.cookies.json")
+    journal_dir: Path = _path("JOURNAL_DIR", "./state")
+    log_dir: Path = _path("LOG_DIR", "./logs")
+    gemini_model: str = os.getenv("GEMINI_MODEL", "gemini-flash")
+    gemini_temporary_chat: bool = _bool("GEMINI_TEMPORARY_CHAT", True)
+    gemini_auto_cleanup: bool = _bool("GEMINI_AUTO_CLEANUP", True)
+    onshape_default_doc: str = os.getenv("ONSHAPE_DEFAULT_DOC", "")
+    # "auto" tries real Chrome first then bundled Chromium,
+    # "chrome" requires real Chrome, "chromium" uses bundled Chromium only.
+    browser_channel: str = os.getenv("ONSHAPE_BROWSER_CHANNEL", "auto")
+
+    def __repr__(self) -> str:  # never leak cookie/profile paths into logs
+        return (
+            f"Settings(gemini_model={self.gemini_model!r}, "
+            f"gemini_temporary_chat={self.gemini_temporary_chat}, "
+            f"gemini_auto_cleanup={self.gemini_auto_cleanup}, "
+            f"browser_channel={self.browser_channel!r}, "
+            f"onshape_default_doc={self.onshape_default_doc!r})"
+        )
+
+
+settings = Settings()
+
+# Make sure local-only directories exist.
+for d in (
+    settings.onshape_cookie_file.parent,
+    settings.onshape_browser_profile,
+    settings.gemini_cookie_file.parent,
+    settings.journal_dir,
+    settings.log_dir,
+):
+    d.mkdir(parents=True, exist_ok=True)

src/onshape_mcp/dispatch.py

@@ -0,0 +1,360 @@
+"""Shared dispatch logic. The LLM calls a tool by name with flat kwargs;
+we reshape them to the function signatures in ui_actions.
+
+Used by both the MCP server (act tool) and the run_task CLI so they
+can't drift apart.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from . import ui_actions
+from .driver import OnshapeDriver
+
+
+def parse_decision(text: str) -> dict[str, Any]:
+    """Pull a JSON object out of a Gemini reply. Tolerant of markdown fences."""
+    fenced = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if fenced:
+        candidate = fenced.group(1)
+    else:
+        brace = re.search(r"\{.*\}", text, re.DOTALL)
+        candidate = brace.group(0) if brace else text
+    try:
+        return json.loads(candidate)
+    except json.JSONDecodeError:
+        return {"done": True, "summary": f"Could not parse decision: {text[:200]}"}
+
+
+def _xy(
+    args: dict[str, Any], x_key: str, y_key: str, default: tuple[float, float] = (720.0, 450.0)
+) -> tuple[float, float]:
+    if x_key in args and y_key in args:
+        try:
+            return (float(args[x_key]), float(args[y_key]))
+        except (ValueError, TypeError):
+            pass
+    if "_" in x_key:
+        prefix = x_key.rsplit("_", 1)[0]
+        if prefix in args:
+            val = args[prefix]
+            if isinstance(val, (list, tuple)) and len(val) >= 2:
+                try:
+                    return (float(val[0]), float(val[1]))
+                except (ValueError, TypeError):
+                    pass
+            if isinstance(val, dict):
+                try:
+                    return (
+                        float(val.get("x", val.get("0", default[0]))),
+                        float(val.get("y", val.get("1", default[1]))),
+                    )
+                except (ValueError, TypeError):
+                    pass
+    # Fallback to generic x, y
+    if "x" in args and "y" in args:
+        try:
+            return (float(args["x"]), float(args["y"]))
+        except (ValueError, TypeError):
+            pass
+    # Fallback to point / pt / coords
+    for key in ("point", "pt", "coords", "corner"):
+        if key in args:
+            val = args[key]
+            if isinstance(val, (list, tuple)) and len(val) >= 2:
+                try:
+                    return (float(val[0]), float(val[1]))
+                except (ValueError, TypeError):
+                    pass
+    return default
+
+
+def _dim_val(args: dict[str, Any], key: str) -> Any:
+    for k in (f"{key}_mm", f"{key}_cm", key, f"{key}_val", f"{key}_size"):
+        if k in args:
+            val = args[k]
+            if k.endswith("_cm") and isinstance(val, (int, float)):
+                return f"{val} cm"
+            return val
+    return None
+
+
+# Tool name -> async fn(d, args) that calls the right ui_action.
+TOOL_DISPATCH: dict[str, Any] = {
+    "view.fit": lambda d, a: ui_actions.view_fit(d),
+    "view.top": lambda d, a: ui_actions.view_top(d),
+    "view.front": lambda d, a: ui_actions.view_front(d),
+    "view.iso": lambda d, a: ui_actions.view_iso(d),
+    "view.isometric": lambda d, a: ui_actions.view_isometric(d),
+    "sketch.start": lambda d, a: ui_actions.sketch_start(
+        d,
+        (a["plane_x"], a["plane_y"]) if "plane_x" in a and "plane_y" in a else None,
+        plane_name=a.get("plane"),
+    ),
+    "sketch.rectangle": lambda d, a: ui_actions.sketch_rectangle(
+        d,
+        _xy(a, "corner1_x", "corner1_y", default=(0.0, 0.0))
+        if ("corner1_x" in a or "corner1" in a or "corner" in a or "x1" in a)
+        else None,
+        _xy(a, "corner2_x", "corner2_y", default=(100.0, 100.0))
+        if ("corner2_x" in a or "corner2" in a or "x2" in a)
+        else None,
+        width=_dim_val(a, "width"),
+        height=_dim_val(a, "height"),
+        quadrant=a.get("quadrant"),
+        centered=a.get("centered") or a.get("center") or a.get("at_origin"),
+    ),
+    "sketch.circle": lambda d, a: ui_actions.sketch_circle(
+        d,
+        _xy(a, "center_x", "center_y", default=(0.0, 0.0))
+        if ("center_x" in a or "center" in a or "x" in a)
+        else None,
+        float(a.get("radius_px") or a.get("radius_mm") or a.get("radius", 50)),
+        centered=a.get("centered") or a.get("center") or a.get("at_origin"),
+    ),
+    "sketch.line": lambda d, a: ui_actions.sketch_line(
+        d, _xy(a, "p1_x", "p1_y"), _xy(a, "p2_x", "p2_y")
+    ),
+    "sketch.line_midpoint": lambda d, a: ui_actions.sketch_line(
+        d, _xy(a, "p1_x", "p1_y"), _xy(a, "p2_x", "p2_y")
+    ),
+    "sketch.rectangle_center": lambda d, a: ui_actions.sketch_rectangle(
+        d,
+        centered=True,
+        width=_dim_val(a, "width"),
+        height=_dim_val(a, "height"),
+    ),
+    "sketch.rectangle_aligned": lambda d, a: ui_actions.sketch_rectangle(
+        d,
+        _xy(a, "corner1_x", "corner1_y", default=(0.0, 0.0)),
+        _xy(a, "corner2_x", "corner2_y", default=(100.0, 100.0)),
+    ),
+    "sketch.circle_3point": lambda d, a: ui_actions.sketch_circle(
+        d, _xy(a, "p1_x", "p1_y", default=(0.0, 0.0))
+    ),
+    "sketch.ellipse": lambda d, a: ui_actions.sketch_circle(
+        d,
+        _xy(a, "center_x", "center_y", default=(0.0, 0.0)),
+        float(a.get("radius", 50.0)),
+    ),
+    "sketch.arc": lambda d, a: ui_actions.sketch_arc(
+        d,
+        _xy(a, "p1_x", "p1_y", default=(0.0, 0.0)),
+        _xy(a, "p2_x", "p2_y", default=(100.0, 0.0)),
+        _xy(a, "radius_x", "radius_y") if ("radius_x" in a or "radius" in a) else None,
+    ),
+    "sketch.arc_3point": lambda d, a: ui_actions.sketch_arc(
+        d,
+        _xy(a, "p1_x", "p1_y", default=(0.0, 0.0)),
+        _xy(a, "p2_x", "p2_y", default=(100.0, 0.0)),
+        _xy(a, "radius_x", "radius_y") if ("radius_x" in a or "radius" in a) else None,
+    ),
+    "sketch.arc_tangent": lambda d, a: ui_actions.sketch_arc(
+        d,
+        _xy(a, "p1_x", "p1_y", default=(0.0, 0.0)),
+        _xy(a, "p2_x", "p2_y", default=(100.0, 0.0)),
+    ),
+    "sketch.arc_center": lambda d, a: ui_actions.sketch_arc(
+        d,
+        _xy(a, "p1_x", "p1_y", default=(0.0, 0.0)),
+        _xy(a, "p2_x", "p2_y", default=(100.0, 0.0)),
+    ),
+    "sketch.polygon": lambda d, a: ui_actions.sketch_polygon(
+        d,
+        _xy(a, "center_x", "center_y", default=(0.0, 0.0))
+        if ("center_x" in a or "center" in a or "x" in a)
+        else None,
+        radius=float(a.get("radius_px") or a.get("radius_mm") or a.get("radius", 60.0)),
+        sides=int(a.get("sides", 6)),
+        circumscribed=bool(a.get("circumscribed", False)),
+    ),
+    "sketch.spline": lambda d, a: ui_actions.sketch_spline(
+        d,
+        a.get("points")
+        or [_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 3)))]
+    ),
+    "sketch.point": lambda d, a: ui_actions.sketch_point(d, _xy(a, "x", "y")),
+    "sketch.text": lambda d, a: ui_actions.sketch_text(
+        d,
+        _xy(a, "corner1_x", "corner1_y", default=(0.0, 0.0)),
+        _xy(a, "corner2_x", "corner2_y", default=(200.0, 100.0)),
+        str(a.get("text", "")),
+    ),
+    "sketch.use": lambda d, a: ui_actions.sketch_use(d, _xy(a, "x", "y")),
+    "sketch.construction": lambda d, a: ui_actions.sketch_construction(
+        d, _xy(a, "x", "y") if ("x" in a or "entity_x" in a or "entity" in a) else None
+    ),
+    "sketch.fillet": lambda d, a: ui_actions.sketch_fillet(
+        d,
+        _xy(a, "vertex_x", "vertex_y") if ("vertex_x" in a or "vertex" in a) else _xy(a, "x", "y"),
+        _dim_val(a, "radius") or 5.0,
+    ),
+    "sketch.chamfer": lambda d, a: ui_actions.sketch_chamfer(
+        d,
+        _xy(a, "vertex_x", "vertex_y") if ("vertex_x" in a or "vertex" in a) else _xy(a, "x", "y"),
+        _dim_val(a, "distance") or 5.0,
+    ),
+    "sketch.trim": lambda d, a: ui_actions.sketch_trim(d, _xy(a, "x", "y")),
+    "sketch.extend": lambda d, a: ui_actions.sketch_extend(d, _xy(a, "x", "y")),
+    "sketch.split": lambda d, a: ui_actions.sketch_split(d, _xy(a, "x", "y")),
+    "sketch.offset": lambda d, a: ui_actions.sketch_offset(
+        d, _xy(a, "x", "y"), _dim_val(a, "distance") or 5.0
+    ),
+    "sketch.slot": lambda d, a: ui_actions.sketch_slot(
+        d,
+        _xy(a, "p1_x", "p1_y", default=(0.0, 0.0)),
+        _xy(a, "p2_x", "p2_y", default=(100.0, 0.0)),
+        float(a.get("radius", 20.0)),
+    ),
+    "sketch.mirror": lambda d, a: ui_actions.sketch_mirror(
+        d,
+        _xy(a, "centerline_x", "centerline_y", default=(0.0, 0.0)),
+        *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 1)))],
+    ),
+    "sketch.pattern_linear": lambda d, a: ui_actions.wait(d, 0.5),
+    "sketch.pattern_circular": lambda d, a: ui_actions.wait(d, 0.5),
+    "sketch.transform": lambda d, a: ui_actions.wait(d, 0.5),
+    "sketch.dimension": lambda d, a: ui_actions.sketch_dimension(
+        d,
+        _xy(a, "entity_x", "entity_y"),
+        _xy(a, "label_x", "label_y")
+        if ("label_x" in a or "label" in a)
+        else (_xy(a, "entity_x", "entity_y")[0] + 30.0, _xy(a, "entity_x", "entity_y")[1] + 30.0),
+        _dim_val(a, "value") or 5,
+    ),
+    "sketch.equal": lambda d, a: ui_actions.sketch_equal(
+        d, *[(a[f"x{i}"], a[f"y{i}"]) for i in range(int(a.get("n", 2)))]
+    ),
+    "sketch.constrain": lambda d, a: ui_actions.sketch_constrain(
+        d,
+        a.get("type", "coincident"),
+        *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))],
+    ),
+    "constraint.coincident": lambda d, a: ui_actions.sketch_constrain(
+        d, "coincident", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.concentric": lambda d, a: ui_actions.sketch_constrain(
+        d, "concentric", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.parallel": lambda d, a: ui_actions.sketch_constrain(
+        d, "parallel", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.tangent": lambda d, a: ui_actions.sketch_constrain(
+        d, "tangent", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.horizontal": lambda d, a: ui_actions.sketch_constrain(
+        d, "horizontal", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 1)))]
+    ),
+    "constraint.vertical": lambda d, a: ui_actions.sketch_constrain(
+        d, "vertical", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 1)))]
+    ),
+    "constraint.perpendicular": lambda d, a: ui_actions.sketch_constrain(
+        d, "perpendicular", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.equal": lambda d, a: ui_actions.sketch_constrain(
+        d, "equal", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.midpoint": lambda d, a: ui_actions.sketch_constrain(
+        d, "midpoint", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.normal": lambda d, a: ui_actions.sketch_constrain(
+        d, "normal", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.pierce": lambda d, a: ui_actions.sketch_constrain(
+        d, "pierce", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.symmetric": lambda d, a: ui_actions.sketch_constrain(
+        d, "symmetric", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 2)))]
+    ),
+    "constraint.fix": lambda d, a: ui_actions.sketch_constrain(
+        d, "fix", *[_xy(a, f"x{i}", f"y{i}") for i in range(int(a.get("n", 1)))]
+    ),
+    "sketch.exit": lambda d, a: ui_actions.sketch_exit(d),
+    "feature.extrude": lambda d, a: ui_actions.feature_extrude(
+        d, a.get("depth_mm") if "depth_mm" in a else a.get("depth")
+    ),
+    "feature.fillet": lambda d, a: ui_actions.feature_fillet(
+        d, a.get("radius_mm") if "radius_mm" in a else a.get("radius")
+    ),
+    "feature.chamfer": lambda d, a: ui_actions.feature_chamfer(
+        d, a.get("distance_mm") if "distance_mm" in a else a.get("distance")
+    ),
+    "select.face": lambda d, a: ui_actions.select_face(d, *_xy(a, "x", "y")),
+    "select.edge": lambda d, a: ui_actions.select_edge(d, *_xy(a, "x", "y")),
+    "click": lambda d, a: ui_actions.select_face(d, *_xy(a, "x", "y")),
+    "ui.undo": lambda d, a: ui_actions.undo(d),
+    "ui.redo": lambda d, a: ui_actions.redo(d),
+    "wait": lambda d, a: ui_actions.wait(d, float(a.get("seconds", 1.0))),
+    "sleep": lambda d, a: ui_actions.wait(d, float(a.get("seconds", 1.0))),
+    "ui.wait": lambda d, a: ui_actions.wait(d, float(a.get("seconds", 1.0))),
+    "screenshot": lambda d, a: ui_actions.screenshot_only(d, a.get("name", "agent.png")),
+    "doc.open": lambda d, a: ui_actions.doc_open(d, a.get("url", "")),
+    "doc.new": lambda d, a: ui_actions.doc_new(d),
+}
+
+
+async def dispatch(d: OnshapeDriver, tool: str | None, args: dict[str, Any]) -> None:
+    """Route a tool call. Unknown tools raise a clear error so the agent
+    loop records it as a failure and the LLM can recover on the next
+    step instead of crashing the whole run.
+    """
+    if not tool:
+        return
+    fn = TOOL_DISPATCH.get(tool)
+    if fn is None:
+        raise KeyError(f"unknown tool: {tool!r}. Available: {sorted(TOOL_DISPATCH.keys())}")
+    return await fn(d, args or {})
+
+
+def build_agent_system_prompt() -> str:
+    """The system prompt for the closed-loop agent. This is where I
+    teach the model the workflow that actually works.
+    """
+    from . import tools as datasheet
+
+    return (
+        "You are an agent that drives the Onshape web CAD application visually, "
+        "the way a human would. You see screenshots and call tools.\n\n"
+        "On each turn:\n"
+        "  1. Read the user's goal.\n"
+        "  2. Look at the current screenshot.\n"
+        "  3. Decide the single next tool to call. Pick ONE tool. Provide its "
+        "arguments as a JSON object matching its signature.\n"
+        '  4. If you have completed the goal, return {"done": true, "summary": "..."}.\n\n'
+        "Coordinate space is viewport pixels (0,0 = top-left). Use viewport_size "
+        "to get the bounds. The viewport center is typically the world origin in "
+        "the default top view.\n\n"
+        "## The constrained-sketch workflow (this is how you size and position things)\n\n"
+        "Never try to pick exact-mm pixel coordinates in the viewport. Instead:\n\n"
+        "  0. Make sure you're in a Part Studio. If you see a documents list, "
+        "call `doc.new` or `doc.open` first.\n"
+        '  1. `sketch.start`: Pick ANY plane — `plane="Top"`, `plane="Front"`, or `plane="Right"` '
+        "(or pass a face coordinate). The view will automatically orient normal to that plane with the origin centered.\n"
+        "  2. Positioning and Quadrants:\n"
+        "     - Centered at Origin: pass `centered=true` to `sketch.rectangle` or `sketch.circle` (or `corner1=[0,0]` / `center=[0,0]`).\n"
+        '     - In a specific Quadrant (anchored at Origin): pass `quadrant="I"` (top-right), `quadrant="II"` (top-left), '
+        '`quadrant="III"` (bottom-left), or `quadrant="IV"` (bottom-right).\n'
+        "     - Arbitrary corners: pass `corner1=[x1, y1]`, `corner2=[x2, y2]` in pixels or relative CAD units.\n"
+        "  3. Sizing:\n"
+        '     - `sketch.rectangle` accepts `width` and `height` (e.g. width="12 cm", height="8 cm" or width_mm=50).\n'
+        "     - It automatically applies constraints and drives the Onshape dimension solver for both width and height!\n"
+        "     - After calling `sketch.rectangle` with width and height, both dimensions are ALREADY applied, so call `sketch.exit` next!\n"
+        '     - Alternatively, call `sketch.dimension` with the entity coordinate and `value` (e.g. "5 cm").\n'
+        "  4. `sketch.exit`: Commits and closes the sketch dialog.\n"
+        "  5. `feature.extrude`: Extrudes the sketch with `depth` in mm or cm.\n\n"
+        "For example: to draw a 12cm by 8cm box on the Front plane, call:\n"
+        '  step 0: sketch.start({"plane": "Front"})\n'
+        '  step 1: sketch.rectangle({"centered": true, "width": "12 cm", "height": "8 cm"})\n'
+        '  step 2: sketch.exit({})\n'
+        '  step 3: {"done": true, "summary": "12cm by 8cm box drawn and dimensioned on Front plane"}\n\n'
+        "For a '5x5 square extruded 5mm into a cube' that's just sketch.start, sketch.rectangle with width='5 mm', "
+        "sketch.exit, and feature.extrude with depth='5 mm'!\n\n"
+        "## Be conservative\n\n"
+        "When in doubt, take a screenshot and re-look. The UI is fragile: wrong "
+        "clicks can deselect, dismiss dialogs, or trigger unrelated tools. If a "
+        "tool fails twice in a row, undo and try a different approach.\n\n"
+        "## Available tools\n\n" + datasheet.as_prompt_block()
+    )

src/onshape_mcp/driver.py

@@ -0,0 +1,423 @@
+"""Playwright driver for Onshape. One headless Chromium, persistent
+profile for cache, plain-JSON cookie file for the session.
+
+Why JSON cookies instead of relying on Chrome's encrypted DB:
+on Linux, Chrome encrypts cookies in its DB with a key from the system
+keyring. The keyring is only available to graphical sessions, so
+headless Playwright can't decrypt them; the cookies are present but
+invisible. Storing them as plain JSON (and re-injecting via
+`context.add_cookies()`) sidesteps the whole keyring issue.
+
+Profile dir is gitignored (see SECURITY.md).
+
+This module holds the lowest-level UI primitives. Higher-level Onshape
+ops (sketch, extrude, fillet) live in ui_actions.py and compose these.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+from playwright.async_api import BrowserContext, Locator, Page, async_playwright
+
+from .config import settings
+
+ONSHAPE_URL = "https://cad.onshape.com"
+
+
+class OnshapeDriver:
+    def __init__(
+        self,
+        profile_dir: Path | None = None,
+        cookie_file: Path | None = None,
+    ) -> None:
+        self.profile_dir = (profile_dir or settings.onshape_browser_profile).resolve()
+        self.cookie_file = (cookie_file or settings.onshape_cookie_file).resolve()
+        self.channel = settings.browser_channel
+        self._pw: Any = None
+        self._ctx: BrowserContext | None = None
+        self._page: Page | None = None
+
+    async def start(self, headless: bool = True) -> Page:
+        self._pw = await async_playwright().start()
+        self._clear_stale_locks()
+        # We use the profile dir mainly for the SingletonLock dance and
+        # any future extensions we might want to install. Cache is not
+        # worth the stale-state headaches, so we use a non-persistent
+        # context when possible. Cookies live in self.cookie_file (plain
+        # JSON) and get injected after launch — no need for the profile
+        # to carry the session.
+        #
+        # Channel strategy: try real Chrome first (no automation markers,
+        # dodges Google's "this browser may not be secure" block). Fall
+        # back to bundled Chromium. Set ONSHAPE_BROWSER_CHANNEL=chromium
+        # to skip the Chrome attempt (e.g. on a Pi with no Chrome).
+        #
+        # WebGL args: Onshape renders the 3D viewport with WebGL. In
+        # headless mode we need to ask explicitly for software WebGL or
+        # the canvas stays blank. `swiftshader` is Google's software
+        # WebGL implementation and works on any machine.
+        common_args = [
+            "--use-gl=swiftshader",
+            "--enable-webgl",
+            "--ignore-gpu-blocklist",
+            "--disable-blink-features=AutomationControlled",
+        ]
+        if self.channel in ("auto", "chrome"):
+            try:
+                self._ctx = await self._pw.chromium.launch_persistent_context(
+                    user_data_dir=str(self.profile_dir),
+                    headless=headless,
+                    viewport={"width": 1440, "height": 900},
+                    args=common_args,
+                    channel="chrome",
+                )
+                self._channel_used = "chrome"
+            except Exception as e:
+                if self.channel == "chrome":
+                    raise
+                print(f"[driver] real Chrome unavailable ({e}); using bundled Chromium")
+                self._ctx = await self._pw.chromium.launch_persistent_context(
+                    user_data_dir=str(self.profile_dir),
+                    headless=headless,
+                    viewport={"width": 1440, "height": 900},
+                    args=common_args,
+                )
+                self._channel_used = "chromium"
+        else:
+            self._ctx = await self._pw.chromium.launch_persistent_context(
+                user_data_dir=str(self.profile_dir),
+                headless=headless,
+                viewport={"width": 1440, "height": 900},
+                args=common_args,
+            )
+            self._channel_used = "chromium"
+        await self._load_cookies()
+        self._page = self._ctx.pages[0] if self._ctx.pages else await self._ctx.new_page()
+        return self._page
+
+    def _clear_stale_locks(self) -> None:
+        """Remove leftover SingletonLock/SingletonCookie files from prior
+        Chrome runs. Without this, a crashed previous run blocks all
+        subsequent launches of the same profile.
+        """
+        for fname in ("SingletonLock", "SingletonCookie", "SingletonSocket"):
+            p = self.profile_dir / fname
+            if p.exists():
+                try:
+                    p.unlink()
+                except OSError:
+                    pass
+
+    async def _load_cookies(self) -> None:
+        """Re-inject saved cookies into the context before any navigation.
+        Without this, even a logged-in session looks anonymous because
+        Chrome's encrypted DB can't be read headless.
+        """
+        raw = []
+        # 1. Environment variable support (useful for remote/cloud hosting)
+        env_cookies = os.getenv("ONSHAPE_COOKIES_JSON")
+        if env_cookies:
+            try:
+                raw = json.loads(env_cookies)
+            except Exception as e:
+                print(f"[driver] failed parsing ONSHAPE_COOKIES_JSON: {e}")
+
+        # 2. Local cookie file
+        if not raw and self.cookie_file.exists():
+            try:
+                raw = json.loads(self.cookie_file.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError) as e:
+                print(f"[driver] cookie file unreadable ({e}); ignoring")
+
+        # 3. Auto-extract from available installed browsers
+        if not raw:
+            try:
+                import browser_cookie3
+
+                browser_loaders = [
+                    ("Chrome", getattr(browser_cookie3, "chrome", None)),
+                    ("Brave", getattr(browser_cookie3, "brave", None)),
+                    ("Edge", getattr(browser_cookie3, "edge", None)),
+                    ("Chromium", getattr(browser_cookie3, "chromium", None)),
+                    ("Firefox", getattr(browser_cookie3, "firefox", None)),
+                    ("Arc", getattr(browser_cookie3, "arc", None)),
+                    ("Opera", getattr(browser_cookie3, "opera", None)),
+                    ("Vivaldi", getattr(browser_cookie3, "vivaldi", None)),
+                ]
+                for browser_name, loader in browser_loaders:
+                    if loader is None:
+                        continue
+                    try:
+                        cj = loader(domain_name="onshape.com")
+                        for c in cj:
+                            cookie = {
+                                "name": c.name,
+                                "value": c.value,
+                                "domain": c.domain,
+                                "path": c.path,
+                                "secure": bool(c.secure),
+                                "httpOnly": bool(
+                                    c.has_nonstandard_attr("HttpOnly")
+                                    or c.has_nonstandard_attr("httponly")
+                                ),
+                            }
+                            if c.expires:
+                                cookie["expires"] = float(c.expires)
+                            raw.append(cookie)
+                        if raw:
+                            self.cookie_file.parent.mkdir(parents=True, exist_ok=True)
+                            self.cookie_file.write_text(json.dumps(raw, indent=2), encoding="utf-8")
+                            print(
+                                f"[driver] auto-synced {len(raw)} Onshape cookies from {browser_name} to {self.cookie_file.name}"
+                            )
+                            break
+                    except Exception:
+                        continue
+            except Exception as e:
+                print(f"[driver] could not extract Onshape cookies from local browsers: {e}")
+        if not raw:
+            return
+        # Playwright's add_cookies wants the same shape it returns.
+        await self._ctx.add_cookies(raw)
+        print(f"[driver] loaded {len(raw)} cookies from {self.cookie_file.name}")
+
+    async def save_cookies(self) -> int:
+        """Dump current context cookies to self.cookie_file. Returns count."""
+        cookies = await self._ctx.cookies()
+        self.cookie_file.parent.mkdir(parents=True, exist_ok=True)
+        self.cookie_file.write_text(json.dumps(cookies, indent=2), encoding="utf-8")
+        return len(cookies)
+
+    @property
+    def page(self) -> Page:
+        if self._page is None:
+            raise RuntimeError("Driver not started; call .start() first")
+        return self._page
+
+    @property
+    def channel_used(self) -> str:
+        return getattr(self, "_channel_used", "unknown")
+
+    async def open(self, url: str | None = None) -> None:
+        if not url:
+            if settings.onshape_default_doc:
+                doc = settings.onshape_default_doc
+                url = (
+                    doc if doc.startswith("http") else f"https://cad.onshape.com/{doc.lstrip('/')}"
+                )
+            else:
+                url = ONSHAPE_URL
+        # Onshape is a SPA that keeps WebSocket connections open, so
+        # `networkidle` never fires (it would time out at 60s). We use
+        # `load` for the navigation then `wait_for_app()` to confirm the
+        # toolbar is actually on screen.
+        await self.page.goto(url, wait_until="load", timeout=60_000)
+        await self.wait_for_app()
+        if "signin" in self.page.url:
+            raise RuntimeError(
+                "Onshape redirected to signin page. Cookies may be invalid or expired. "
+                "Please log in to cad.onshape.com in Google Chrome."
+            )
+
+    # Screenshots
+
+    async def wait_for_app(self, timeout: float = 30.0) -> bool:
+        """Wait until the Onshape app shell has rendered something we can
+        see. The marker is broad: any toolbar button, the documents list,
+        a sketch button, whatever the current page has. Returns True if
+        something rendered, False if the page is still blank after the
+        timeout. Either way we sleep an extra beat for the WebGL canvas.
+        """
+        try:
+            await self.page.wait_for_function(
+                """() => {
+                    // any rendered buttons with visible text or aria-label
+                    const btns = document.querySelectorAll('button, [role="button"], a, .document-card, .document-list-item');
+                    let n = 0;
+                    for (const b of btns) {
+                        const t = (b.textContent || b.getAttribute('aria-label') || '').trim();
+                        if (t.length > 0) n++;
+                        if (n >= 3) return true;
+                    }
+                    // any substantial content (h1-h3, paragraphs, etc.)
+                    const text = document.body.innerText || '';
+                    return text.length > 100;
+                }""",
+                timeout=timeout * 1000,
+            )
+            # Wait for graphics / loading spinner to clear
+            try:
+                await self.page.locator(".loading-progress-message").wait_for(
+                    state="hidden", timeout=30_000
+                )
+            except Exception:
+                pass
+            await asyncio.sleep(1.0)
+            return True
+        except Exception:
+            return False
+
+    async def screenshot(self, name: str = "shot.png") -> Path:
+        out = settings.journal_dir / name
+        out.parent.mkdir(parents=True, exist_ok=True)
+        await self.page.screenshot(path=str(out), full_page=False)
+        return out
+
+    async def screenshot_clip(self, name: str, rect: dict[str, float]) -> Path:
+        out = settings.journal_dir / name
+        out.parent.mkdir(parents=True, exist_ok=True)
+        await self.page.screenshot(path=str(out), clip=rect)
+        return out
+
+    async def viewport_box(self) -> dict[str, float]:
+        return await self.page.evaluate("() => ({w: window.innerWidth, h: window.innerHeight})")
+
+    # Clicks and drags
+
+    async def click(
+        self,
+        x: float,
+        y: float,
+        button: str = "left",
+        click_count: int = 1,
+    ) -> None:
+        await self.page.mouse.click(x, y, button=button, click_count=click_count)
+
+    async def double_click(self, x: float, y: float) -> None:
+        await self.click(x, y, click_count=2)
+
+    async def drag(
+        self,
+        start: tuple[float, float],
+        end: tuple[float, float],
+        steps: int = 10,
+        button: str = "left",
+    ) -> None:
+        sx, sy = start
+        ex, ey = end
+        await self.page.mouse.move(sx, sy)
+        await self.page.mouse.down(button=button)
+        await self.page.mouse.move(ex, ey, steps=steps)
+        await self.page.mouse.up(button=button)
+
+    async def hover(self, x: float, y: float) -> None:
+        await self.page.mouse.move(x, y)
+
+    # Keyboard input
+
+    async def type_text(self, text: str, delay_ms: int = 10) -> None:
+        await self.page.keyboard.type(text, delay=delay_ms)
+
+    async def press_key(self, key: str) -> None:
+        """Press a single key. e.g. 'Enter', 'Escape', 'Tab'."""
+        await self.page.keyboard.press(key)
+
+    async def press_chord(self, *keys: str) -> None:
+        """Press a key combination, e.g. press_chord('Control', 'z')."""
+        combo = "+".join(keys)
+        await self.page.keyboard.press(combo)
+
+    # Element finding
+    # Most of the Onshape UI is canvas + custom DOM, so text/aria selectors
+    # are the most reliable. We try a few strategies and return the first hit.
+
+    async def find_by_text(
+        self,
+        text: str,
+        *,
+        partial: bool = True,
+        role: str | None = None,
+        timeout_ms: int = 3000,
+    ) -> Locator | None:
+        """Return a locator matching the given visible text (or aria-label).
+
+        Returns None if not found within timeout. Caller decides whether to
+        click, get the box, etc.
+        """
+        strategies: list[Locator] = []
+        if role:
+            strategies.append(self.page.get_by_role(role, name=text, exact=not partial))
+        # aria-label / title
+        strategies.append(
+            self.page.locator(f"[aria-label*='{text}']" if partial else f"[aria-label='{text}']")
+        )
+        # visible text content
+        strategies.append(self.page.get_by_text(text, exact=not partial))
+        for loc in strategies:
+            try:
+                if await loc.first.is_visible(timeout=timeout_ms / 1000):
+                    return loc.first
+            except Exception:
+                continue
+        return None
+
+    async def click_text(
+        self,
+        text: str,
+        *,
+        partial: bool = True,
+        timeout_ms: int = 3000,
+    ) -> bool:
+        loc = await self.find_by_text(text, partial=partial, timeout_ms=timeout_ms)
+        if loc is None:
+            return False
+        await loc.click()
+        return True
+
+    async def wait_for_text(self, text: str, timeout: float = 5.0) -> bool:
+        try:
+            await self.page.get_by_text(text).first.wait_for(timeout=timeout * 1000)
+            return True
+        except Exception:
+            return False
+
+    async def wait_for_no_text(self, text: str, timeout: float = 5.0) -> bool:
+        """True if the text disappears within timeout. False if it's still there."""
+        try:
+            await self.page.get_by_text(text).first.wait_for(state="hidden", timeout=timeout * 1000)
+            return True
+        except Exception:
+            return False
+
+    # Lifecycle
+
+    async def close(self) -> None:
+        if self._ctx is not None:
+            await self._ctx.close()
+        if self._pw is not None:
+            await self._pw.stop()
+        self._ctx = None
+        self._page = None
+        self._pw = None
+
+
+async def login_interactive() -> None:
+    """Open a headed browser, let the user log in, then dump the session
+    cookies to self.cookie_file. Subsequent headless runs re-inject them.
+    """
+    d = OnshapeDriver()
+    await d.start(headless=False)
+    await d.open(ONSHAPE_URL)
+    print("Log into Onshape in the opened browser, then press Enter here.")
+    input("> ")
+    n = await d.save_cookies()
+    print(f"Saved {n} cookies to {d.cookie_file}")
+    await d.close()
+
+
+def main() -> None:
+    """`python -m onshape_mcp.driver login`"""
+    import sys
+
+    if len(sys.argv) >= 2 and sys.argv[1] == "login":
+        asyncio.run(login_interactive())
+    else:
+        print("usage: python -m onshape_mcp.driver login")
+
+
+if __name__ == "__main__":
+    main()

src/onshape_mcp/fast_exec.py

@@ -0,0 +1,77 @@
+"""Fast direct executor. Runs a parsed Plan against the Onshape driver
+without any LLM calls. This is the fast path for deterministic tasks.
+
+Typical execution: ~5-8s for sketch + dimension + commit, compared to
+~60s with the vision loop.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .dispatch import dispatch
+from .driver import OnshapeDriver
+from .intent import Plan
+
+
+@dataclass
+class FastResult:
+    plan: Plan
+    ok: bool
+    total_elapsed_s: float = 0.0
+    final_screenshot: Path | None = None
+    step_times: list[tuple[str, float]] = None  # type: ignore[assignment]
+    error: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.step_times is None:
+            self.step_times = []
+
+    def summary(self) -> str:
+        n = len(self.step_times)
+        if self.ok:
+            return f"completed {n} actions ({self.total_elapsed_s:.1f}s): {self.plan.summary}"
+        return f"failed at action {n} ({self.total_elapsed_s:.1f}s): {self.error}"
+
+
+async def execute(d: OnshapeDriver, plan: Plan) -> FastResult:
+    """Execute a Plan's actions sequentially against the driver.
+    No LLM calls, no screenshots between steps (except final).
+    """
+    t0 = time.monotonic()
+    result = FastResult(plan=plan, ok=True)
+
+    for i, action in enumerate(plan.actions):
+        step_t0 = time.monotonic()
+        tool = action.tool
+        args = action.args
+        try:
+            await dispatch(d, tool, args)
+            elapsed = time.monotonic() - step_t0
+            result.step_times.append((f"{tool}({_compact(args)})", elapsed))
+            print(f"  [{i}] {tool}({_compact(args)}) ({elapsed:.1f}s)", flush=True)
+        except Exception as e:
+            elapsed = time.monotonic() - step_t0
+            result.step_times.append((f"{tool} ERROR", elapsed))
+            result.ok = False
+            result.error = f"{tool}: {e}"
+            print(f"  [{i}] {tool} ERROR: {e} ({elapsed:.1f}s)", flush=True)
+            break
+
+    try:
+        result.final_screenshot = await d.screenshot("task_final.png")
+    except Exception as e:
+        print(f"  [warn] could not capture final screenshot: {e}", flush=True)
+    result.total_elapsed_s = time.monotonic() - t0
+    return result
+
+
+def _compact(d: dict[str, Any]) -> str:
+    import json
+    try:
+        return json.dumps(d, ensure_ascii=False)
+    except Exception:
+        return str(d)

src/onshape_mcp/intent.py

@@ -0,0 +1,243 @@
+"""Parse natural-language CAD prompts into structured action plans.
+
+This module eliminates the LLM from deterministic tasks. Instead of
+sending 4 screenshots to Gemini and waiting 60s for it to say
+"sketch.start, sketch.rectangle, sketch.exit, done", we parse the
+prompt directly and produce the same action sequence in <1ms.
+
+If the parser can't handle a prompt, it returns None and the caller
+falls back to the vision loop.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Action:
+    tool: str
+    args: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Plan:
+    actions: list[Action]
+    summary: str
+
+
+# Regex patterns for dimension extraction.
+# Handles "12cm by 8cm", "12 cm x 8 cm", "50mm × 30mm" etc.
+# Groups: (1)=width, (2)=width_unit, (3)=height, (4)=height_unit
+_DIM_RE = re.compile(
+    r"(\d+(?:\.\d+)?)\s*(mm|cm|in|inch)?\s*(?:x|by|×)\s*(\d+(?:\.\d+)?)\s*(mm|cm|in|inch)?",
+    re.IGNORECASE,
+)
+_SINGLE_DIM_RE = re.compile(
+    r"(\d+(?:\.\d+)?)\s*(mm|cm|in|inch)",
+    re.IGNORECASE,
+)
+_PLANE_RE = re.compile(r"\b(top|front|right)\b", re.IGNORECASE)
+_QUADRANT_RE = re.compile(
+    r"(?:quadrant|q)\s*([1-4]|I{1,3}V?|IV)", re.IGNORECASE
+)
+_EXTRUDE_RE = re.compile(
+    r"extrude\s+(?:it\s+)?(\d+(?:\.\d+)?)\s*(mm|cm|in)?", re.IGNORECASE
+)
+_DIAMETER_RE = re.compile(
+    r"(\d+(?:\.\d+)?)\s*(mm|cm|in)?\s*diameter", re.IGNORECASE
+)
+_RADIUS_RE = re.compile(
+    r"(\d+(?:\.\d+)?)\s*(mm|cm|in)?\s*radius", re.IGNORECASE
+)
+_POLYGON_SIDES_RE = re.compile(
+    r"(\d+)[ -]sided\b", re.IGNORECASE
+)
+_CENTERED_RE = re.compile(
+    r"\b(center(?:ed)?|at\s+(?:the\s+)?origin)\b", re.IGNORECASE
+)
+
+
+def _format_dim(value: float, unit: str | None) -> str:
+    """Format a dimension value with unit for Onshape's solver."""
+    u = (unit or "cm").lower()
+    if u in ("in", "inch"):
+        u = "in"
+    v = f"{value:g}"
+    return f"{v} {u}"
+
+
+def _extract_plane(text: str) -> str:
+    m = _PLANE_RE.search(text)
+    return m.group(1).capitalize() if m else "Top"
+
+
+def _extract_quadrant(text: str) -> str | None:
+    m = _QUADRANT_RE.search(text)
+    if not m:
+        return None
+    q = m.group(1).upper()
+    roman = {"I": "1", "II": "2", "III": "3", "IV": "4"}
+    return roman.get(q, q)
+
+
+def _is_centered(text: str) -> bool:
+    return bool(_CENTERED_RE.search(text))
+
+
+def parse(text: str) -> Plan | None:
+    """Try to parse a natural-language CAD prompt into a deterministic
+    action plan. Returns None if the prompt is too ambiguous or complex
+    for direct execution.
+    """
+    t = text.strip()
+    lower = t.lower()
+
+    if not t:
+        return None
+
+    # Detect shape type
+    is_rect = any(w in lower for w in ("box", "rectangle", "rect", "square"))
+    is_circle = any(w in lower for w in ("circle", "cylinder", "disc", "disk"))
+    is_polygon = any(w in lower for w in ("polygon", "hexagon", "pentagon", "octagon"))
+    is_arc = "arc" in lower and not is_circle
+    is_point = "point" in lower and not any((is_rect, is_circle, is_polygon, is_arc))
+    has_extrude = "extrude" in lower
+
+    if not (is_rect or is_circle or is_polygon or is_arc or is_point):
+        return None
+
+    plane = _extract_plane(t)
+    quadrant = _extract_quadrant(t)
+    centered = _is_centered(t)
+
+    actions: list[Action] = []
+    summary_parts: list[str] = []
+
+    # Step 1: Start sketch
+    actions.append(Action("sketch.start", {"plane": plane}))
+
+    if is_rect:
+        dim_m = _DIM_RE.search(t)
+        if dim_m:
+            w_val = float(dim_m.group(1))
+            h_val = float(dim_m.group(3))
+            unit = dim_m.group(2) or dim_m.group(4)
+            width = _format_dim(w_val, unit)
+            height = _format_dim(h_val, unit)
+        elif "square" in lower:
+            single = _SINGLE_DIM_RE.search(t)
+            if single:
+                val = float(single.group(1))
+                unit = single.group(2)
+                width = height = _format_dim(val, unit)
+            else:
+                return None
+        else:
+            return None
+
+        rect_args: dict[str, Any] = {"width": width, "height": height}
+        if quadrant:
+            rect_args["quadrant"] = quadrant
+        elif centered or not quadrant:
+            rect_args["centered"] = True
+
+        actions.append(Action("sketch.rectangle", rect_args))
+        label = "square" if width == height else "rectangle"
+        summary_parts.append(f"{width} × {height} {label}")
+
+    elif is_circle:
+        diam_m = _DIAMETER_RE.search(t)
+        rad_m = _RADIUS_RE.search(t)
+        if diam_m:
+            val = float(diam_m.group(1))
+            unit = diam_m.group(2)
+            radius_mm = val / 2.0
+            if unit and unit.lower() == "cm":
+                radius_mm = val * 10.0 / 2.0
+            circle_args: dict[str, Any] = {
+                "centered": True,
+                "radius": radius_mm,
+            }
+            actions.append(Action("sketch.circle", circle_args))
+            summary_parts.append(f"{_format_dim(val, unit)} diameter circle")
+        elif rad_m:
+            val = float(rad_m.group(1))
+            unit = rad_m.group(2)
+            circle_args = {"centered": True, "radius": val}
+            actions.append(Action("sketch.circle", circle_args))
+            summary_parts.append(f"{_format_dim(val, unit)} radius circle")
+        else:
+            single = _SINGLE_DIM_RE.search(t)
+            if single:
+                val = float(single.group(1))
+                unit = single.group(2)
+                circle_args = {"centered": True, "radius": val / 2.0}
+                actions.append(Action("sketch.circle", circle_args))
+                summary_parts.append(f"{_format_dim(val, unit)} circle")
+            else:
+                return None
+
+    elif is_polygon:
+        # Determine number of sides
+        sides = 6
+        side_m = _POLYGON_SIDES_RE.search(t)
+        if side_m:
+            sides = int(side_m.group(1))
+        elif "hexagon" in lower:
+            sides = 6
+        elif "pentagon" in lower:
+            sides = 5
+        elif "octagon" in lower:
+            sides = 8
+
+        # Determine radius
+        rad_m = _RADIUS_RE.search(t) or _SINGLE_DIM_RE.search(t)
+        radius_val = float(rad_m.group(1)) if rad_m else 50.0
+        unit = rad_m.group(2) if rad_m else "mm"
+        poly_args: dict[str, Any] = {
+            "center_x": 0.0,
+            "center_y": 0.0,
+            "radius": radius_val,
+            "sides": sides,
+        }
+        actions.append(Action("sketch.polygon", poly_args))
+        summary_parts.append(f"{sides}-sided polygon (r={_format_dim(radius_val, unit)})")
+
+    elif is_arc:
+        arc_args: dict[str, Any] = {
+            "p1_x": -50.0,
+            "p1_y": 0.0,
+            "p2_x": 50.0,
+            "p2_y": 0.0,
+        }
+        actions.append(Action("sketch.arc", arc_args))
+        summary_parts.append("3-point arc")
+
+    elif is_point:
+        actions.append(Action("sketch.point", {"x": 0.0, "y": 0.0}))
+        summary_parts.append("point at origin")
+
+    # Step: Exit sketch
+    actions.append(Action("sketch.exit", {}))
+
+    # Step: Extrude (optional)
+    ext_m = _EXTRUDE_RE.search(t)
+    if has_extrude and ext_m:
+        depth_val = float(ext_m.group(1))
+        depth_unit = (ext_m.group(2) or "mm").lower()
+        if depth_unit == "cm":
+            depth_mm = depth_val * 10.0
+        elif depth_unit in ("in", "inch"):
+            depth_mm = depth_val * 25.4
+        else:
+            depth_mm = depth_val
+        actions.append(Action("feature.extrude", {"depth_mm": depth_mm}))
+        summary_parts.append(f"extruded {_format_dim(depth_val, depth_unit)}")
+
+    position = f"Quadrant {quadrant}" if quadrant else "centered at origin"
+    summary = f"Drew {', '.join(summary_parts)} on {plane} plane, {position}"
+
+    return Plan(actions=actions, summary=summary)

src/onshape_mcp/journal.py

@@ -0,0 +1,54 @@
+"""Append-only action journal. Every UI op is recorded for undo/replay/debug.
+
+This file lives in `./state/` and is gitignored. Don't change that.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .config import settings
+
+
+@dataclass
+class JournalEntry:
+    ts: float
+    action_id: str
+    tool: str
+    args: dict[str, Any] = field(default_factory=dict)
+    result: str = "ok"  # "ok" | "fail" | "skipped"
+    note: str = ""
+    screenshot: str | None = None  # relative path under state/ if captured
+
+    @classmethod
+    def new(cls, tool: str, args: dict[str, Any]) -> JournalEntry:
+        return cls(
+            ts=time.time(),
+            action_id=uuid.uuid4().hex[:12],
+            tool=tool,
+            args=args,
+        )
+
+
+class Journal:
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or (settings.journal_dir / "session.journal.jsonl")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, entry: JournalEntry) -> None:
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(asdict(entry), ensure_ascii=False) + "\n")
+
+    def tail(self, n: int = 20) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        lines = self.path.read_text(encoding="utf-8").splitlines()[-n:]
+        return [json.loads(line) for line in lines if line.strip()]
+
+
+journal = Journal()

src/onshape_mcp/loop.py

@@ -0,0 +1,201 @@
+"""Closed-loop agent runner. Screenshot -> Gemini -> dispatch -> repeat.
+
+Used by both the MCP `act()` tool and the run_task CLI. The dispatch
+table + system prompt live in `dispatch.py` so the two callers can't
+drift apart.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .dispatch import build_agent_system_prompt, dispatch, parse_decision
+from .driver import OnshapeDriver
+from .vision import GeminiWeb
+
+STUCK_THRESHOLD = 5  # unchanged screenshots in a row -> stop
+
+
+@dataclass
+class StepRecord:
+    step: int
+    decision: dict[str, Any]
+    ok: bool
+    error: str | None = None
+    elapsed_s: float = 0.0
+
+
+@dataclass
+class LoopResult:
+    goal: str
+    steps: list[StepRecord] = field(default_factory=list)
+    completed: bool = False
+    final_screenshot: Path | None = None
+    stop_reason: str = ""
+    total_elapsed_s: float = 0.0
+
+    def summary(self) -> str:
+        if self.completed:
+            last = self.steps[-1].decision if self.steps else {}
+            return f"completed in {len(self.steps)} steps ({self.total_elapsed_s:.1f}s): {last.get('summary', '')}"
+        return f"stopped ({self.stop_reason}) after {len(self.steps)} steps ({self.total_elapsed_s:.1f}s)"
+
+
+class AgentLoop:
+    def __init__(
+        self,
+        driver: OnshapeDriver | None = None,
+        vision: GeminiWeb | None = None,
+        stuck_threshold: int = STUCK_THRESHOLD,
+    ) -> None:
+        self.driver = driver
+        self.vision = vision
+        self.stuck_threshold = stuck_threshold
+
+    async def _ensure(self) -> tuple[OnshapeDriver, GeminiWeb]:
+        if self.driver is None:
+            self.driver = OnshapeDriver()
+            await self.driver.start(headless=True)
+            await self.driver.open()
+        if self.vision is None:
+            self.vision = GeminiWeb()
+        # Warm the vision client. The first call has higher latency
+        # because of init + token exchange. Doing it before the loop
+        # keeps the per-step timing predictable.
+        await self.vision._ensure_client()
+        return self.driver, self.vision
+
+    async def close(self) -> None:
+        if self.vision is not None:
+            await self.vision.close()
+            self.vision = None
+        if self.driver is not None:
+            await self.driver.close()
+            self.driver = None
+
+    async def run(self, goal: str, max_steps: int = 25) -> LoopResult:
+        run_t0 = time.monotonic()
+        d, v = await self._ensure()
+        result = LoopResult(goal=goal)
+        last_hash: str | None = None
+        unchanged = 0
+
+        system_prompt = build_agent_system_prompt()
+        history: list[dict[str, Any]] = []
+
+        # Maintain a single chat session for this task run to prevent
+        # spawning multiple separate chats per step.
+        chat_session = await v.new_session()
+
+        last_vertex: tuple[float, float] | None = None
+
+        for step in range(max_steps):
+            t0 = time.monotonic()
+            shot = await d.screenshot(f"task_step_{step:02d}.png")
+            h = hashlib.sha256(shot.read_bytes()).hexdigest()
+            if h == last_hash:
+                unchanged += 1
+                if unchanged >= self.stuck_threshold:
+                    result.stop_reason = f"stuck after {self.stuck_threshold} unchanged screenshots"
+                    break
+            else:
+                unchanged = 0
+            last_hash = h
+
+            history_text = ""
+            for r in history[-3:]:
+                history_text += f"\nStep {r['step']}: {r['decision']}\n"
+            vertex_text = f"\nLast drawn vertex on canvas: {last_vertex}\n" if last_vertex else ""
+            prompt = (
+                f"{system_prompt}\n\n"
+                f"---\n"
+                f"User goal: {goal}\n\n"
+                f"Recent action history:{history_text}{vertex_text}\n"
+                f"Step {step + 1}/{max_steps}. Look at the latest screenshot. "
+                "Reply ONLY with a JSON object: "
+                '{"tool": "<tool_name>", "args": {...}} OR {"done": true, "summary": "..."}'
+            )
+            try:
+                answer = await v.ask_with_image(prompt, shot)
+            except Exception as e:
+                result.steps.append(
+                    StepRecord(
+                        step,
+                        {"error": f"vision: {e}"},
+                        ok=False,
+                        error=str(e),
+                        elapsed_s=time.monotonic() - t0,
+                    )
+                )
+                result.stop_reason = f"vision error: {e}"
+                break
+
+            decision = parse_decision(answer)
+            history.append({"step": step, "decision": decision})
+            if decision.get("done"):
+                if str(decision.get("summary", "")).startswith("Could not parse decision"):
+                    rec = StepRecord(
+                        step,
+                        decision,
+                        ok=False,
+                        error=decision.get("summary"),
+                        elapsed_s=time.monotonic() - t0,
+                    )
+                    result.steps.append(rec)
+                    continue
+                result.completed = True
+                result.steps.append(
+                    StepRecord(step, decision, ok=True, elapsed_s=time.monotonic() - t0)
+                )
+                break
+
+            tool = decision.get("tool")
+            args = decision.get("args", {}) or {}
+            rec = StepRecord(
+                step, {"tool": tool, "args": args}, ok=True, elapsed_s=time.monotonic() - t0
+            )
+            try:
+                action_res = await dispatch(d, tool, args)
+                if (
+                    hasattr(action_res, "meta")
+                    and isinstance(action_res.meta, dict)
+                    and "last_vertex" in action_res.meta
+                ):
+                    last_vertex = tuple(action_res.meta["last_vertex"])
+            except Exception as e:
+                rec.ok = False
+                rec.error = f"{type(e).__name__}: {e}"
+            rec.elapsed_s = time.monotonic() - t0
+            result.steps.append(rec)
+            if rec.ok:
+                unchanged = 0
+            status_str = (
+                f"ERROR {rec.error}"
+                if rec.error
+                else f"{tool}({json.dumps(args, ensure_ascii=False)})"
+            )
+            print(f"  step {step}: {status_str} ({rec.elapsed_s:.1f}s)", flush=True)
+            # brief beat so the UI has time to paint
+            await asyncio.sleep(0.4)
+
+        result.final_screenshot = await d.screenshot("task_final.png")
+        result.total_elapsed_s = time.monotonic() - run_t0
+        if not result.completed and not result.stop_reason:
+            result.stop_reason = f"max_steps ({max_steps}) reached"
+        return result
+
+
+def build_loop() -> AgentLoop:
+    """Factory. Caller can override driver/vision if they already have one."""
+    return AgentLoop()
+
+
+def run_sync(goal: str, max_steps: int = 25) -> LoopResult:
+    """Convenience wrapper for non-async callers."""
+    return asyncio.run(AgentLoop().run(goal, max_steps=max_steps))

src/onshape_mcp/server.py

@@ -0,0 +1,697 @@
+"""MCP server. Exposes the complete Onshape tool vocabulary as MCP tools.
+Designed for Claude Desktop, ChatGPT, and custom LLM clients.
+
+All tool executions are wrapped with error-handling to prevent JSON-RPC
+pipe crashes and provide clear, human-readable public messages.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import traceback
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from . import tools as datasheet
+from . import ui_actions
+from .dispatch import TOOL_DISPATCH, build_agent_system_prompt, dispatch
+from .driver import OnshapeDriver
+from .fast_exec import execute as fast_execute
+from .intent import parse as parse_intent
+from .journal import JournalEntry, journal
+from .loop import AgentLoop
+from .vision import GeminiWeb
+
+mcp = FastMCP("onshape-mcp")
+
+_driver: OnshapeDriver | None = None
+_vision: GeminiWeb | None = None
+_loop: AgentLoop | None = None
+
+
+def _format_error(tool_name: str, err: Exception) -> str:
+    """Return a clean JSON string with public error details."""
+    return json.dumps(
+        {
+            "ok": False,
+            "tool": tool_name,
+            "error": type(err).__name__,
+            "message": str(err),
+            "hint": "Check coordinates, tool preconditions, or document connection.",
+        },
+        indent=2,
+    )
+
+
+async def _driver_lazy() -> OnshapeDriver:
+    global _driver
+    if _driver is None:
+        _driver = OnshapeDriver()
+        await _driver.start(headless=True)
+        await _driver.open()
+    return _driver
+
+
+async def _vision_lazy() -> GeminiWeb:
+    global _vision
+    if _vision is None:
+        _vision = GeminiWeb()
+    return _vision
+
+
+async def _loop_lazy() -> AgentLoop:
+    global _loop
+    if _loop is None:
+        _loop = AgentLoop()
+    return _loop
+
+
+# Meta & Information Tools
+
+
+@mcp.tool()
+async def screenshot(name: str = "shot.png") -> str:
+    """Take a screenshot of the current Onshape viewport. Returns the absolute file path."""
+    try:
+        d = await _driver_lazy()
+        path = await d.screenshot(name=name)
+        e = JournalEntry.new("screenshot", {"name": name})
+        e.screenshot = str(path)
+        journal.append(e)
+        return json.dumps({"ok": True, "screenshot": str(path), "message": f"Saved screenshot to {path}"})
+    except Exception as e:
+        return _format_error("screenshot", e)
+
+
+@mcp.tool()
+async def describe_view(question: str = "What do you see in the Onshape viewport?") -> str:
+    """Screenshot + ask Gemini vision to describe what's in the viewport."""
+    try:
+        d = await _driver_lazy()
+        img = await d.screenshot("describe.png")
+        v = await _vision_lazy()
+        desc = await v.ask_with_image(question, img)
+        return json.dumps({"ok": True, "description": desc})
+    except Exception as e:
+        return _format_error("describe_view", e)
+
+
+@mcp.tool()
+async def tool_datasheet() -> str:
+    """Return the entire Onshape tool vocabulary, parameters, and preconditions as markdown."""
+    return datasheet.as_prompt_block()
+
+
+@mcp.tool()
+async def journal_tail(n: int = 20) -> str:
+    """Return the last N actions executed against Onshape."""
+    return json.dumps(journal.tail(n), indent=2, ensure_ascii=False)
+
+
+@mcp.tool()
+async def open_doc(url: str) -> str:
+    """Navigate to an Onshape document URL or path."""
+    try:
+        d = await _driver_lazy()
+        full = url if url.startswith("http") else f"https://cad.onshape.com/{url.lstrip('/')}"
+        await d.open(full)
+        journal.append(JournalEntry.new("doc.open", {"url": full}))
+        return json.dumps({"ok": True, "message": f"Opened document {full}"})
+    except Exception as e:
+        return _format_error("open_doc", e)
+
+
+@mcp.tool()
+async def viewport_size() -> str:
+    """Return the current viewport dimensions in pixels."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps(await d.viewport_box())
+    except Exception as e:
+        return _format_error("viewport_size", e)
+
+
+# View & Camera Tools
+
+
+@mcp.tool()
+async def onshape_view_fit() -> str:
+    """Zoom and pan to fit all visible geometry in the viewport ('f')."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.view_fit(d)).to_dict())
+    except Exception as e:
+        return _format_error("view.fit", e)
+
+
+@mcp.tool()
+async def onshape_view_top() -> str:
+    """Orient camera to look directly at the Top view."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.view_top(d)).to_dict())
+    except Exception as e:
+        return _format_error("view.top", e)
+
+
+@mcp.tool()
+async def onshape_view_front() -> str:
+    """Orient camera to look directly at the Front view."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.view_front(d)).to_dict())
+    except Exception as e:
+        return _format_error("view.front", e)
+
+
+@mcp.tool()
+async def onshape_view_iso() -> str:
+    """Orient camera to Isometric view."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.view_iso(d)).to_dict())
+    except Exception as e:
+        return _format_error("view.iso", e)
+
+
+# Sketch Creation Tools
+
+
+@mcp.tool()
+async def onshape_sketch_start(
+    plane_x: float | None = None,
+    plane_y: float | None = None,
+    plane: str | None = None,
+) -> str:
+    """Open a new sketch. Pass plane name ('Top', 'Front', 'Right') or plane_x/plane_y coordinates.
+    Default plane is 'Top'. Automatically aligns camera normal to the sketch plane."""
+    try:
+        d = await _driver_lazy()
+        pt = (plane_x, plane_y) if plane_x is not None and plane_y is not None else None
+        return json.dumps((await ui_actions.sketch_start(d, pt, plane_name=plane)).to_dict())
+    except Exception as e:
+        return _format_error("sketch.start", e)
+
+
+@mcp.tool()
+async def onshape_sketch_exit(commit: bool = True) -> str:
+    """Exit the active sketch and accept (commit=True) or discard (commit=False) changes."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.sketch_exit(d, commit=commit)).to_dict())
+    except Exception as e:
+        return _format_error("sketch.exit", e)
+
+
+@mcp.tool()
+async def onshape_sketch_rectangle(
+    corner1_x: float | None = None,
+    corner1_y: float | None = None,
+    corner2_x: float | None = None,
+    corner2_y: float | None = None,
+    width: float | str | None = None,
+    height: float | str | None = None,
+    quadrant: str | int | None = None,
+    centered: bool | None = None,
+) -> str:
+    """Draw a rectangle. Accepts dimensions (e.g. width='10 cm', height='5 cm'), quadrant ('1', '2', '3', '4'),
+    or centered=True. Dimensions are automatically driven into Onshape's solver."""
+    try:
+        d = await _driver_lazy()
+        c1 = (corner1_x, corner1_y) if corner1_x is not None and corner1_y is not None else None
+        c2 = (corner2_x, corner2_y) if corner2_x is not None and corner2_y is not None else None
+        return json.dumps(
+            (
+                await ui_actions.sketch_rectangle(
+                    d, c1, c2, width=width, height=height, quadrant=quadrant, centered=centered
+                )
+            ).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.rectangle", e)
+
+
+@mcp.tool()
+async def onshape_sketch_circle(
+    center_x: float | None = None,
+    center_y: float | None = None,
+    radius_px: float = 50.0,
+    centered: bool | None = None,
+) -> str:
+    """Draw a circle. Pass center coordinates (center_x, center_y) or centered=True for origin."""
+    try:
+        d = await _driver_lazy()
+        center = (center_x, center_y) if center_x is not None and center_y is not None else None
+        return json.dumps(
+            (await ui_actions.sketch_circle(d, center, radius_px, centered=centered)).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.circle", e)
+
+
+@mcp.tool()
+async def onshape_sketch_line(p1_x: float, p1_y: float, p2_x: float, p2_y: float) -> str:
+    """Draw a line segment from (p1_x, p1_y) to (p2_x, p2_y)."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.sketch_line(d, (p1_x, p1_y), (p2_x, p2_y))).to_dict())
+    except Exception as e:
+        return _format_error("sketch.line", e)
+
+
+@mcp.tool()
+async def onshape_sketch_polygon(
+    sides: int = 6,
+    radius: float = 60.0,
+    center_x: float | None = None,
+    center_y: float | None = None,
+    circumscribed: bool = False,
+) -> str:
+    """Draw an inscribed or circumscribed polygon with N sides and radius."""
+    try:
+        d = await _driver_lazy()
+        center = (center_x, center_y) if center_x is not None and center_y is not None else None
+        return json.dumps(
+            (
+                await ui_actions.sketch_polygon(
+                    d, center=center, radius=radius, sides=sides, circumscribed=circumscribed
+                )
+            ).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.polygon", e)
+
+
+@mcp.tool()
+async def onshape_sketch_spline(points: list[list[float]]) -> str:
+    """Draw a smooth spline curve through a list of [[x1, y1], [x2, y2], ...] points."""
+    try:
+        d = await _driver_lazy()
+        pts = [(p[0], p[1]) for p in points]
+        return json.dumps((await ui_actions.sketch_spline(d, pts)).to_dict())
+    except Exception as e:
+        return _format_error("sketch.spline", e)
+
+
+@mcp.tool()
+async def onshape_sketch_arc(
+    p1_x: float,
+    p1_y: float,
+    p2_x: float,
+    p2_y: float,
+    radius_x: float | None = None,
+    radius_y: float | None = None,
+) -> str:
+    """Draw a 3-point arc from (p1_x, p1_y) to (p2_x, p2_y) passing through (radius_x, radius_y)."""
+    try:
+        d = await _driver_lazy()
+        rad_pt = (radius_x, radius_y) if radius_x is not None and radius_y is not None else None
+        return json.dumps(
+            (await ui_actions.sketch_arc(d, (p1_x, p1_y), (p2_x, p2_y), radius_pt=rad_pt)).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.arc", e)
+
+
+@mcp.tool()
+async def onshape_sketch_point(x: float, y: float) -> str:
+    """Place a sketch point at (x, y)."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.sketch_point(d, (x, y))).to_dict())
+    except Exception as e:
+        return _format_error("sketch.point", e)
+
+
+@mcp.tool()
+async def onshape_sketch_text(
+    corner1_x: float, corner1_y: float, corner2_x: float, corner2_y: float, text: str
+) -> str:
+    """Place sketch text in a box defined by corner1 and corner2."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps(
+            (
+                await ui_actions.sketch_text(
+                    d, (corner1_x, corner1_y), (corner2_x, corner2_y), text=text
+                )
+            ).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.text", e)
+
+
+# Sketch Modifications & Operations
+
+
+@mcp.tool()
+async def onshape_sketch_construction(x: float | None = None, y: float | None = None) -> str:
+    """Toggle construction mode, or convert the entity at (x, y) to/from construction geometry ('q')."""
+    try:
+        d = await _driver_lazy()
+        pt = (x, y) if x is not None and y is not None else None
+        return json.dumps((await ui_actions.sketch_construction(d, pt=pt)).to_dict())
+    except Exception as e:
+        return _format_error("sketch.construction", e)
+
+
+@mcp.tool()
+async def onshape_sketch_fillet(vertex_x: float, vertex_y: float, radius_mm: float = 5.0) -> str:
+    """Add a rounded 2D fillet of radius_mm at corner/vertex (vertex_x, vertex_y)."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps(
+            (await ui_actions.sketch_fillet(d, (vertex_x, vertex_y), radius_mm=radius_mm)).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.fillet", e)
+
+
+@mcp.tool()
+async def onshape_sketch_chamfer(
+    vertex_x: float, vertex_y: float, distance_mm: float = 5.0
+) -> str:
+    """Add a 2D chamfer of distance_mm at corner/vertex (vertex_x, vertex_y)."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps(
+            (
+                await ui_actions.sketch_chamfer(d, (vertex_x, vertex_y), distance_mm=distance_mm)
+            ).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.chamfer", e)
+
+
+@mcp.tool()
+async def onshape_sketch_trim(x: float, y: float) -> str:
+    """Trim a curve segment back to the nearest intersections by clicking at (x, y) ('m')."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.sketch_trim(d, (x, y))).to_dict())
+    except Exception as e:
+        return _format_error("sketch.trim", e)
+
+
+@mcp.tool()
+async def onshape_sketch_extend(x: float, y: float) -> str:
+    """Extend a curve endpoint at (x, y) to the nearest boundary ('x')."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.sketch_extend(d, (x, y))).to_dict())
+    except Exception as e:
+        return _format_error("sketch.extend", e)
+
+
+@mcp.tool()
+async def onshape_sketch_offset(
+    entity_x: float,
+    entity_y: float,
+    distance_mm: float = 5.0,
+    side_x: float | None = None,
+    side_y: float | None = None,
+) -> str:
+    """Offset curve at (entity_x, entity_y) by distance_mm toward optional side (side_x, side_y) ('o')."""
+    try:
+        d = await _driver_lazy()
+        side = (side_x, side_y) if side_x is not None and side_y is not None else None
+        return json.dumps(
+            (
+                await ui_actions.sketch_offset(
+                    d, (entity_x, entity_y), distance_mm=distance_mm, side_xy=side
+                )
+            ).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.offset", e)
+
+
+@mcp.tool()
+async def onshape_sketch_mirror(
+    centerline_x: float, centerline_y: float, entity_x: float, entity_y: float
+) -> str:
+    """Mirror an entity at (entity_x, entity_y) across a centerline at (centerline_x, centerline_y)."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps(
+            (
+                await ui_actions.sketch_mirror(
+                    d, (centerline_x, centerline_y), (entity_x, entity_y)
+                )
+            ).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.mirror", e)
+
+
+# Dimensions & Constraints
+
+
+@mcp.tool()
+async def onshape_sketch_dimension(
+    entity_x: float, entity_y: float, label_x: float, label_y: float, value_mm: float | str
+) -> str:
+    """Drive an Onshape sketch dimension ('d'). Clicks entity at (entity_x, entity_y), places label
+    at (label_x, label_y), and enters value_mm into the solver."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps(
+            (
+                await ui_actions.sketch_dimension(
+                    d, (entity_x, entity_y), (label_x, label_y), value_mm
+                )
+            ).to_dict()
+        )
+    except Exception as e:
+        return _format_error("sketch.dimension", e)
+
+
+@mcp.tool()
+async def onshape_sketch_constrain(
+    constraint_type: str,
+    entities: list[list[float]],
+) -> str:
+    """Apply a geometric constraint across entities.
+    Valid types: coincident, concentric, parallel, tangent, horizontal, vertical,
+    perpendicular, equal, midpoint, normal, pierce, symmetric, fix."""
+    try:
+        d = await _driver_lazy()
+        pts = [(e[0], e[1]) for e in entities]
+        return json.dumps(
+            (await ui_actions.sketch_constrain(d, constraint_type, *pts)).to_dict()
+        )
+    except Exception as e:
+        return _format_error(f"constraint.{constraint_type}", e)
+
+
+# Feature Operations
+
+
+@mcp.tool()
+async def onshape_feature_extrude(depth_mm: float | None = None) -> str:
+    """Extrude the active sketch or selected face by depth_mm."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.feature_extrude(d, depth_mm)).to_dict())
+    except Exception as e:
+        return _format_error("feature.extrude", e)
+
+
+@mcp.tool()
+async def onshape_feature_fillet(radius_mm: float | None = None) -> str:
+    """Round selected 3D model edges by radius_mm."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.feature_fillet(d, radius_mm)).to_dict())
+    except Exception as e:
+        return _format_error("feature.fillet", e)
+
+
+@mcp.tool()
+async def onshape_feature_chamfer(distance_mm: float | None = None) -> str:
+    """Bevel selected 3D model edges by distance_mm."""
+    try:
+        d = await _driver_lazy()
+        return json.dumps((await ui_actions.feature_chamfer(d, distance_mm)).to_dict())
+    except Exception as e:
+        return _format_error("feature.chamfer", e)
+
+
+# Generic Tool Dispatcher (with clean un-bound tool guard)
+
+
+@mcp.tool()
+async def onshape_execute(tool: str, args: dict[str, Any] | None = None) -> str:
+    """Generic tool dispatcher. Calls any registered tool by name with arguments.
+    Returns clear public error messages if a tool is un-bound or fails."""
+    if tool not in TOOL_DISPATCH:
+        return json.dumps(
+            {
+                "ok": False,
+                "tool": tool,
+                "error": "ToolNotBoundError",
+                "message": f"Tool '{tool}' is not bound or supported. Please choose from available tools.",
+                "available_tools": sorted(TOOL_DISPATCH.keys()),
+            },
+            indent=2,
+        )
+    try:
+        d = await _driver_lazy()
+        res = await dispatch(d, tool, args or {})
+        out = res.to_dict() if hasattr(res, "to_dict") else {"ok": True, "result": str(res)}
+        return json.dumps(out, indent=2)
+    except Exception as e:
+        return _format_error(tool, e)
+
+
+# Autonomous Agent (Fast Path + Vision Loop)
+
+
+@mcp.tool()
+async def act(goal: str, max_steps: int = 25) -> str:
+    """Autonomous CAD agent. Takes a high-level goal in natural language (e.g.
+    'draw a 10cm by 5cm box in Quadrant 1 on the top plane', 'draw a 6-sided polygon')
+    and executes it. Tries deterministic fast execution first (10-20s), falling back
+    to vision loop if ambiguous."""
+    try:
+        # 1. Try fast path first
+        plan = parse_intent(goal)
+        if plan is not None:
+            d = await _driver_lazy()
+            result_fast = await fast_execute(d, plan)
+            return json.dumps(
+                {
+                    "ok": result_fast.ok,
+                    "mode": "fast_path",
+                    "goal": goal,
+                    "summary": result_fast.summary(),
+                    "actions_count": len(result_fast.step_times),
+                    "total_elapsed_s": round(result_fast.total_elapsed_s, 1),
+                    "final_screenshot": str(result_fast.final_screenshot)
+                    if result_fast.final_screenshot
+                    else None,
+                    "error": result_fast.error,
+                },
+                indent=2,
+            )
+
+        # 2. Fallback to vision loop
+        loop = await _loop_lazy()
+        result_loop = await loop.run(goal, max_steps=max_steps)
+        tail = [
+            {
+                "step": r.step,
+                "tool": r.decision.get("tool"),
+                "args": r.decision.get("args", {}),
+                "ok": r.ok,
+                "error": r.error,
+            }
+            for r in result_loop.steps[-5:]
+        ]
+        return json.dumps(
+            {
+                "ok": result_loop.completed,
+                "mode": "vision_loop",
+                "goal": goal,
+                "summary": result_loop.summary(),
+                "total_elapsed_s": round(result_loop.total_elapsed_s, 1),
+                "steps_total": len(result_loop.steps),
+                "transcript_tail": tail,
+                "final_screenshot": str(result_loop.final_screenshot)
+                if result_loop.final_screenshot
+                else None,
+                "stop_reason": result_loop.stop_reason,
+            },
+            indent=2,
+        )
+    except Exception as e:
+        return _format_error("act", e)
+
+
+# Lifecycle
+
+
+async def _cleanup() -> None:
+    global _driver, _vision, _loop
+    if _loop is not None:
+        await _loop.close()
+    if _vision is not None:
+        await _vision.close()
+    if _driver is not None:
+        await _driver.close()
+    _driver = None
+    _vision = None
+    _loop = None
+
+
+def main() -> None:
+    import argparse
+    import os
+    import sys
+
+    # Quick dispatch for setup wizard or login
+    if len(sys.argv) >= 2 and sys.argv[1] == "setup":
+        from .setup import main as run_setup
+
+        sys.argv.pop(1)
+        run_setup()
+        return
+
+    if len(sys.argv) >= 2 and sys.argv[1] == "login":
+        from .driver import login_interactive
+
+        asyncio.run(login_interactive())
+        return
+
+    if len(sys.argv) >= 2 and sys.argv[1] in ("share", "tunnel"):
+        from .tunnel import run_tunnel_and_server
+
+        port = int(os.environ.get("PORT", os.environ.get("MCP_PORT", "8000")))
+        run_tunnel_and_server(port=port)
+        return
+
+    parser = argparse.ArgumentParser(description="Onshape MCP Server")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default=os.environ.get("MCP_TRANSPORT", "stdio"),
+        help="Transport protocol: 'stdio' for Claude Desktop / LLM clients (default), or 'sse' for remote hosting.",
+    )
+    parser.add_argument(
+        "--tunnel",
+        action="store_true",
+        help="Auto-start Cloudflare tunnel to expose live HTTPS link for ChatGPT Web / LibreChat.",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("MCP_HOST", "0.0.0.0"),
+        help="Host interface for SSE transport (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("PORT", os.environ.get("MCP_PORT", "8000"))),
+        help="Port for SSE transport (default: 8000 or $PORT)",
+    )
+    args, _ = parser.parse_known_args()
+
+    if args.tunnel:
+        from .tunnel import run_tunnel_and_server
+
+        run_tunnel_and_server(port=args.port, host=args.host)
+        return
+
+    if args.transport == "sse":
+        mcp.settings.host = args.host
+        mcp.settings.port = args.port
+
+    try:
+        mcp.run(transport=args.transport)
+    finally:
+        asyncio.run(_cleanup())
+
+
+if __name__ == "__main__":
+    main()

src/onshape_mcp/setup.py

@@ -0,0 +1,373 @@
+"""Smart setup wizard for Onshape MCP.
+Configures Playwright, syncs Onshape cookies, and automatically
+adds the server to Claude Desktop across macOS, Windows, and Linux.
+
+Zero hardcoded user paths or credentials.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .config import _BASE_DIR, settings
+
+
+def get_claude_desktop_config_path() -> Path:
+    """Return platform-specific path to claude_desktop_config.json."""
+    system = platform.system()
+    if system == "Darwin":  # macOS
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    elif system == "Windows":
+        app_data = os.environ.get("APPDATA")
+        base = Path(app_data) if app_data else Path.home() / "AppData" / "Roaming"
+        return base / "Claude" / "claude_desktop_config.json"
+    else:  # Linux / FreeBSD / other POSIX
+        xdg_config = os.environ.get("XDG_CONFIG_HOME")
+        base = Path(xdg_config) if xdg_config else Path.home() / ".config"
+        return base / "Claude" / "claude_desktop_config.json"
+
+
+def ensure_playwright_browsers() -> bool:
+    """Ensure Chromium binary is downloaded for Playwright."""
+    print("[1/4] Checking Playwright browser dependencies...")
+    try:
+        res = subprocess.run(
+            [sys.executable, "-m", "playwright", "install", "chromium"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if res.returncode == 0:
+            print("  ✓ Chromium browser engine is installed and ready.")
+            return True
+        else:
+            print(f"  ⚠ Note: Playwright browser check returned: {res.stderr.strip()[:100]}")
+            return True
+    except Exception as e:
+        print(f"  ⚠ Could not run playwright install: {e}")
+        return False
+
+
+def sync_onshape_cookies(interactive: bool = True) -> bool:
+    """Check for Onshape cookies or sync from local browsers or interactive login."""
+    print("[2/4] Checking Onshape authentication & session cookies...")
+
+    # 1. Existing cookie file
+    if settings.onshape_cookie_file.exists() and settings.onshape_cookie_file.stat().st_size > 20:
+        try:
+            data = json.loads(settings.onshape_cookie_file.read_text(encoding="utf-8"))
+            if data and isinstance(data, list):
+                print(f"  ✓ Existing session found ({len(data)} cookies) at: {settings.onshape_cookie_file}")
+                return True
+        except Exception:
+            pass
+
+    # 2. Extract from installed browsers
+    try:
+        import browser_cookie3
+
+        browser_loaders = [
+            ("Google Chrome", getattr(browser_cookie3, "chrome", None)),
+            ("Brave", getattr(browser_cookie3, "brave", None)),
+            ("Microsoft Edge", getattr(browser_cookie3, "edge", None)),
+            ("Chromium", getattr(browser_cookie3, "chromium", None)),
+            ("Firefox", getattr(browser_cookie3, "firefox", None)),
+            ("Arc", getattr(browser_cookie3, "arc", None)),
+            ("Opera", getattr(browser_cookie3, "opera", None)),
+            ("Vivaldi", getattr(browser_cookie3, "vivaldi", None)),
+        ]
+        for browser_name, loader in browser_loaders:
+            if loader is None:
+                continue
+            try:
+                cj = loader(domain_name="onshape.com")
+                raw = []
+                for c in cj:
+                    cookie = {
+                        "name": c.name,
+                        "value": c.value,
+                        "domain": c.domain,
+                        "path": c.path,
+                        "secure": bool(c.secure),
+                        "httpOnly": bool(
+                            c.has_nonstandard_attr("HttpOnly")
+                            or c.has_nonstandard_attr("httponly")
+                        ),
+                    }
+                    if c.expires:
+                        cookie["expires"] = float(c.expires)
+                    raw.append(cookie)
+                if raw:
+                    settings.onshape_cookie_file.parent.mkdir(parents=True, exist_ok=True)
+                    settings.onshape_cookie_file.write_text(
+                        json.dumps(raw, indent=2), encoding="utf-8"
+                    )
+                    print(
+                        f"  ✓ Auto-synced {len(raw)} Onshape cookies from {browser_name}."
+                    )
+                    return True
+            except Exception:
+                continue
+    except Exception:
+        pass
+
+    # 3. If missing and interactive, offer browser login
+    if interactive:
+        print("  ⚠ No active Onshape session found in local browsers.")
+        choice = input("  [?] Would you like to open a browser window to log in now? [Y/n]: ").strip().lower()
+        if choice not in ("n", "no"):
+            import asyncio
+            from .driver import login_interactive
+
+            asyncio.run(login_interactive())
+            return settings.onshape_cookie_file.exists()
+
+    print("  ⚠ Please log into https://cad.onshape.com in your browser before running commands.")
+    return False
+
+
+def configure_claude_desktop(
+    doc_url: str = "",
+    use_local_env: bool = False,
+    auto_yes: bool = False,
+) -> Path | None:
+    path = get_claude_desktop_config_path()
+    _write_mcp_json(path, doc_url)
+    return path
+
+
+def _write_mcp_json(config_path: Path, doc_url: str = "") -> bool:
+    """Helper to safely read, backup, and inject the onshape MCP entry into any mcp.json file."""
+    data: dict[str, Any] = {}
+    if config_path.exists():
+        try:
+            bak_path = config_path.with_suffix(".json.bak")
+            shutil.copy2(config_path, bak_path)
+            data = json.loads(config_path.read_text(encoding="utf-8"))
+        except Exception:
+            data = {}
+
+    if not isinstance(data, dict):
+        data = {}
+
+    if "mcpServers" not in data:
+        data["mcpServers"] = {}
+
+    server_entry: dict[str, Any] = {
+        "command": "uvx",
+        "args": [
+            "--from",
+            "git+https://github.com/WilliamSamson/onshape-mcp",
+            "onshape-mcp",
+        ],
+    }
+    if doc_url:
+        server_entry["env"] = {"ONSHAPE_DEFAULT_DOC": doc_url}
+
+    data["mcpServers"]["onshape"] = server_entry
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    return True
+
+
+def detect_supported_clients() -> list[tuple[str, Path]]:
+    """Detect all installed AI clients (Claude Desktop, Cursor, Windsurf, VS Code Cline)."""
+    clients: list[tuple[str, Path]] = []
+
+    # 1. Claude Desktop
+    claude_cfg = get_claude_desktop_config_path()
+    if claude_cfg.parent.exists() or claude_cfg.exists():
+        clients.append(("Claude Desktop", claude_cfg))
+
+    # 2. Cursor IDE
+    cursor_dir = Path.home() / ".cursor"
+    cursor_cfg = cursor_dir / "mcp.json"
+    if cursor_dir.exists() or cursor_cfg.exists():
+        clients.append(("Cursor IDE", cursor_cfg))
+
+    # 3. Windsurf
+    windsurf_dir = Path.home() / ".codeium" / "windsurf"
+    windsurf_cfg = windsurf_dir / "mcp_config.json"
+    if windsurf_dir.exists() or windsurf_cfg.exists():
+        clients.append(("Windsurf IDE", windsurf_cfg))
+
+    # 4. VS Code (Cline extension)
+    system = platform.system()
+    if system == "Darwin":
+        vscode_base = Path.home() / "Library" / "Application Support" / "Code"
+    elif system == "Windows":
+        app_data = os.environ.get("APPDATA")
+        vscode_base = (Path(app_data) if app_data else Path.home() / "AppData" / "Roaming") / "Code"
+    else:
+        xdg_config = os.environ.get("XDG_CONFIG_HOME")
+        vscode_base = (Path(xdg_config) if xdg_config else Path.home() / ".config") / "Code"
+
+    cline_cfg = vscode_base / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json"
+    if cline_cfg.parent.exists() or cline_cfg.exists():
+        clients.append(("VS Code (Cline)", cline_cfg))
+
+    roo_cfg = vscode_base / "User" / "globalStorage" / "rooveterinaryinc.roo-cline" / "settings" / "cline_mcp_settings.json"
+    if roo_cfg.parent.exists() or roo_cfg.exists():
+        clients.append(("VS Code (Roo Code)", roo_cfg))
+
+    return clients
+
+
+def configure_detected_clients(
+    doc_url: str = "",
+    auto_yes: bool = False,
+) -> list[str]:
+    """Auto-configure all detected AI clients."""
+    print("[4/4] Configuring AI Client Integrations (Claude, Cursor, VS Code, etc.)...")
+    detected = detect_supported_clients()
+    configured: list[str] = []
+
+    if not detected:
+        print("  ℹ No desktop AI clients (Claude, Cursor, Windsurf, Cline) detected automatically.")
+        # Offer default Claude Desktop location
+        default_claude = get_claude_desktop_config_path()
+        choice = "y" if auto_yes else input(
+            f"  [?] Create Claude Desktop config anyway at:\n      {default_claude}? [Y/n]: "
+        ).strip().lower()
+        if choice not in ("n", "no"):
+            _write_mcp_json(default_claude, doc_url)
+            configured.append(f"Claude Desktop ({default_claude})")
+            print(f"  ✓ Configured Claude Desktop at: {default_claude}")
+        return configured
+
+    for name, path in detected:
+        if not auto_yes:
+            choice = input(f"  [?] Auto-configure {name} at:\n      {path}? [Y/n]: ").strip().lower()
+            if choice in ("n", "no"):
+                print(f"  Skipped {name}.")
+                continue
+        _write_mcp_json(path, doc_url)
+        configured.append(f"{name} ({path})")
+        print(f"  ✓ Configured {name} at: {path}")
+
+    return configured
+
+
+def run_setup(
+    doc_url: str = "",
+    auto_yes: bool = False,
+    skip_browser_install: bool = False,
+) -> None:
+    print("=" * 68)
+    print("        Onshape MCP — 1-Click Multi-AI Setup & Tester Wizard")
+    print("=" * 68)
+    print(f"Base data directory: {_BASE_DIR}\n")
+
+    # 1. Playwright install
+    if not skip_browser_install:
+        ensure_playwright_browsers()
+    else:
+        print("[1/4] Skipping browser download flag.")
+
+    print()
+
+    # 2. Cookie sync
+    sync_onshape_cookies(interactive=not auto_yes)
+    print()
+
+    # 3. Document URL
+    print("[3/4] Document Configuration...")
+    final_doc_url = doc_url
+    if not final_doc_url and not auto_yes:
+        try:
+            val = input(
+                "  [?] Default Onshape Document URL (optional, press Enter to skip):\n      > "
+            ).strip()
+            if val:
+                final_doc_url = val
+        except (EOFError, KeyboardInterrupt):
+            pass
+
+    if final_doc_url:
+        env_file = _BASE_DIR / ".env"
+        existing = env_file.read_text(encoding="utf-8") if env_file.exists() else ""
+        if "ONSHAPE_DEFAULT_DOC=" in existing:
+            import re
+            new_text = re.sub(r"ONSHAPE_DEFAULT_DOC=.*", f"ONSHAPE_DEFAULT_DOC={final_doc_url}", existing)
+        else:
+            new_text = existing + f"\nONSHAPE_DEFAULT_DOC={final_doc_url}\n"
+        env_file.write_text(new_text, encoding="utf-8")
+        print(f"  ✓ Saved default document URL to {env_file}")
+    else:
+        print("  ✓ No default document set (you can specify URLs per prompt).")
+
+    print()
+
+    # 4. Client config
+    configured = configure_detected_clients(
+        doc_url=final_doc_url,
+        auto_yes=auto_yes,
+    )
+    print()
+
+    # Summary
+    print("=" * 68)
+    print("🎉 Setup Complete!")
+    print("=" * 68)
+    if configured:
+        print("Configured Desktop Clients:")
+        for c in configured:
+            print(f"  • {c}")
+        print("\nRestart your AI client, then ask:")
+        print("  'Draw a 10cm by 5cm box on the Top plane in Onshape'")
+    else:
+        print("Manual Desktop Config (Claude Desktop, Cursor, Windsurf):")
+        print(
+            json.dumps(
+                {
+                    "mcpServers": {
+                        "onshape": {
+                            "command": "uvx",
+                            "args": [
+                                "--from",
+                                "git+https://github.com/WilliamSamson/onshape-mcp",
+                                "onshape-mcp",
+                            ],
+                        }
+                    }
+                },
+                indent=2,
+            )
+        )
+
+    print("-" * 68)
+    print("🌐 Using Web Versions Only? (ChatGPT Web, LibreChat, Open WebUI):")
+    print("1. Start the server in SSE mode:")
+    print("   onshape-mcp --transport sse --port 8000")
+    print("2. Expose it via a secure tunnel (e.g. Cloudflare or Localtunnel):")
+    print("   cloudflared tunnel --url http://localhost:8000")
+    print("   # Or: npx localtunnel --port 8000")
+    print("3. Paste the resulting URL (e.g. https://xxxx.trycloudflare.com/sse)")
+    print("   into your web AI connector / LibreChat / Open WebUI!")
+    print("=" * 68)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Onshape MCP 1-Click Setup Wizard")
+    parser.add_argument("--yes", "-y", action="store_true", help="Auto-confirm all prompts")
+    parser.add_argument("--doc-url", default="", help="Default Onshape document URL to operate on")
+    parser.add_argument("--skip-browsers", action="store_true", help="Skip downloading Chromium")
+    args = parser.parse_args()
+
+    run_setup(
+        doc_url=args.doc_url,
+        auto_yes=args.yes,
+        skip_browser_install=args.skip_browsers,
+    )
+
+
+if __name__ == "__main__":
+    main()

src/onshape_mcp/shortcuts.py

@@ -0,0 +1,498 @@
+"""Onshape UI bindings. Keyboard shortcuts and toolbar button labels.
+
+This is the bridge between the semantic tool vocabulary in tools.py and
+the actual UI. Onshape changes this occasionally; when an action fails,
+this is the first place to check.
+
+Confidence flags: high (tested or well-documented), medium (plausible,
+not yet verified), low (guess based on convention).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Binding:
+    keys: tuple[str, ...] | None = None
+    toolbar_text: str | None = None  # visible label / aria-label
+    toolbar_role: str = "button"
+    notes: str = ""
+    confidence: str = "medium"
+
+
+# View and camera
+VIEW_FIT = Binding(keys=("f",), confidence="high", notes="Fit all; 'F' in viewport")
+VIEW_TOP = Binding(keys=("7",), confidence="low")
+VIEW_FRONT = Binding(keys=("1",), confidence="low")
+VIEW_ISO = Binding(keys=("Shift", "7"), confidence="high", notes="Isometric view: Shift+7")
+
+# Sketch start and exit
+SKETCH_START = Binding(
+    toolbar_text="Sketch",
+    toolbar_role="button",
+    confidence="high",
+    notes="Click the 'Sketch' button in the left toolbar, then click a plane or face.",
+)
+SKETCH_EXIT = Binding(
+    keys=("Escape",),
+    confidence="high",
+    notes="Press Esc to exit the current sketch tool.",
+)
+
+# Sketch Primitives
+SKETCH_LINE = Binding(
+    keys=("l",),
+    toolbar_text="Line",
+    toolbar_role="button",
+    confidence="high",
+    notes="Line tool shortcut 'l'. Click start, click end.",
+)
+SKETCH_LINE_MIDPOINT = Binding(
+    toolbar_text="Midpoint line",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Line anchored at midpoint.",
+)
+SKETCH_RECTANGLE = Binding(
+    keys=("g",),
+    toolbar_text="Rectangle",
+    toolbar_role="button",
+    confidence="high",
+    notes="Corner rectangle shortcut 'g'.",
+)
+SKETCH_RECTANGLE_CENTER = Binding(
+    keys=("r",),
+    toolbar_text="Center point rectangle",
+    toolbar_role="button",
+    confidence="high",
+    notes="Center point rectangle shortcut 'r'.",
+)
+SKETCH_RECTANGLE_ALIGNED = Binding(
+    toolbar_text="Aligned rectangle",
+    toolbar_role="button",
+    confidence="medium",
+    notes="3-point aligned rectangle.",
+)
+SKETCH_CIRCLE = Binding(
+    keys=("c",),
+    toolbar_text="Circle",
+    toolbar_role="button",
+    confidence="high",
+    notes="Center point circle shortcut 'c'.",
+)
+SKETCH_CIRCLE_3POINT = Binding(
+    toolbar_text="3 point circle",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Circle defined by 3 perimeter points.",
+)
+SKETCH_ELLIPSE = Binding(
+    toolbar_text="Ellipse",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Center point and major/minor axes.",
+)
+SKETCH_ARC = Binding(
+    keys=("a",),
+    toolbar_text="Arc",
+    toolbar_role="button",
+    confidence="high",
+    notes="3-point arc shortcut 'a'. Click start, click end, click radius point.",
+)
+SKETCH_ARC_3POINT = SKETCH_ARC
+SKETCH_ARC_TANGENT = Binding(
+    toolbar_text="Tangent arc",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Arc tangent to an existing line or curve.",
+)
+SKETCH_ARC_CENTER = Binding(
+    toolbar_text="Center point arc",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Center point, start angle, end angle.",
+)
+SKETCH_ARC_ELLIPTICAL = Binding(
+    toolbar_text="Elliptical arc",
+    toolbar_role="button",
+    confidence="medium",
+)
+SKETCH_CONIC = Binding(
+    toolbar_text="Conic",
+    toolbar_role="button",
+    confidence="medium",
+)
+SKETCH_POLYGON = Binding(
+    toolbar_text="Inscribed polygon",
+    toolbar_role="button",
+    confidence="high",
+    notes="Inscribed polygon. Click center, click radius, type side count.",
+)
+SKETCH_POLYGON_INSCRIBED = SKETCH_POLYGON
+SKETCH_POLYGON_CIRCUMSCRIBED = Binding(
+    toolbar_text="Circumscribed polygon",
+    toolbar_role="button",
+    confidence="medium",
+)
+SKETCH_SPLINE = Binding(
+    toolbar_text="Spline",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Spline through control points.",
+)
+SKETCH_BEZIER = Binding(
+    toolbar_text="Bezier",
+    toolbar_role="button",
+    confidence="medium",
+)
+SKETCH_POINT = Binding(
+    toolbar_text="Point",
+    toolbar_role="button",
+    confidence="high",
+    notes="Single sketch point.",
+)
+SKETCH_TEXT = Binding(
+    toolbar_text="Text",
+    toolbar_role="button",
+    confidence="high",
+    notes="Text in sketch. Drag bounding box, enter string.",
+)
+SKETCH_USE = Binding(
+    keys=("u",),
+    toolbar_text="Use",
+    toolbar_role="button",
+    confidence="high",
+    notes="Project existing geometry onto sketch plane ('u').",
+)
+SKETCH_INTERSECTION = Binding(
+    toolbar_text="Intersection",
+    toolbar_role="button",
+    confidence="medium",
+)
+
+# Modifications & Operations
+SKETCH_CONSTRUCTION = Binding(
+    keys=("q",),
+    toolbar_text="Construction",
+    toolbar_role="button",
+    confidence="high",
+    notes="Toggle construction geometry on/off ('q').",
+)
+SKETCH_FILLET = Binding(
+    keys=("Shift", "f"),
+    toolbar_text="Fillet",
+    toolbar_role="button",
+    confidence="high",
+    notes="Sketch fillet between two lines or at a vertex ('Shift+f').",
+)
+SKETCH_CHAMFER = Binding(
+    toolbar_text="Chamfer",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Sketch chamfer at corner.",
+)
+SKETCH_TRIM = Binding(
+    keys=("m",),
+    toolbar_text="Trim",
+    toolbar_role="button",
+    confidence="high",
+    notes="Trim curve to nearest intersection ('m').",
+)
+SKETCH_EXTEND = Binding(
+    keys=("x",),
+    toolbar_text="Extend",
+    toolbar_role="button",
+    confidence="high",
+    notes="Extend curve to boundary ('x').",
+)
+SKETCH_SPLIT = Binding(
+    toolbar_text="Split",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Split curve at point.",
+)
+SKETCH_OFFSET = Binding(
+    keys=("o",),
+    toolbar_text="Offset",
+    toolbar_role="button",
+    confidence="high",
+    notes="Offset selected sketch curve ('o').",
+)
+SKETCH_SLOT = Binding(
+    toolbar_text="Slot",
+    toolbar_role="button",
+    confidence="medium",
+)
+SKETCH_MIRROR = Binding(
+    toolbar_text="Mirror",
+    toolbar_role="button",
+    confidence="high",
+    notes="Mirror entities across a centerline.",
+)
+SKETCH_PATTERN_LINEAR = Binding(
+    toolbar_text="Linear pattern",
+    toolbar_role="button",
+    confidence="medium",
+)
+SKETCH_PATTERN_CIRCULAR = Binding(
+    toolbar_text="Circular pattern",
+    toolbar_role="button",
+    confidence="medium",
+)
+SKETCH_TRANSFORM = Binding(
+    toolbar_text="Transform",
+    toolbar_role="button",
+    confidence="medium",
+)
+
+# Dimension & Constraints
+SKETCH_DIMENSION = Binding(
+    keys=("d",),
+    toolbar_text="Dimension",
+    toolbar_role="button",
+    confidence="high",
+    notes="Drive linear/angular/radial dimension ('d').",
+)
+CONSTRAINT_COINCIDENT = Binding(
+    keys=("i",),
+    toolbar_text="Coincident",
+    toolbar_role="button",
+    confidence="high",
+    notes="Coincident constraint ('i').",
+)
+CONSTRAINT_CONCENTRIC = Binding(
+    toolbar_text="Concentric",
+    toolbar_role="button",
+    confidence="high",
+    notes="Concentric constraint between two circles/arcs.",
+)
+CONSTRAINT_PARALLEL = Binding(
+    keys=("b",),
+    toolbar_text="Parallel",
+    toolbar_role="button",
+    confidence="high",
+    notes="Parallel constraint between two lines ('b').",
+)
+CONSTRAINT_TANGENT = Binding(
+    keys=("t",),
+    toolbar_text="Tangent",
+    toolbar_role="button",
+    confidence="high",
+    notes="Tangent constraint ('t').",
+)
+CONSTRAINT_HORIZONTAL = Binding(
+    keys=("h",),
+    toolbar_text="Horizontal",
+    toolbar_role="button",
+    confidence="high",
+    notes="Horizontal constraint ('h').",
+)
+CONSTRAINT_VERTICAL = Binding(
+    keys=("v",),
+    toolbar_text="Vertical",
+    toolbar_role="button",
+    confidence="high",
+    notes="Vertical constraint ('v').",
+)
+CONSTRAINT_PERPENDICULAR = Binding(
+    toolbar_text="Perpendicular",
+    toolbar_role="button",
+    confidence="high",
+    notes="Perpendicular constraint between two lines.",
+)
+CONSTRAINT_EQUAL = Binding(
+    keys=("e",),
+    toolbar_text="Equal",
+    toolbar_role="button",
+    confidence="high",
+    notes="Equal length/radius constraint ('e').",
+)
+CONSTRAINT_MIDPOINT = Binding(
+    toolbar_text="Midpoint",
+    toolbar_role="button",
+    confidence="high",
+    notes="Midpoint constraint between point and line.",
+)
+CONSTRAINT_NORMAL = Binding(
+    toolbar_text="Normal",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Normal constraint to plane or surface.",
+)
+CONSTRAINT_PIERCE = Binding(
+    toolbar_text="Pierce",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Pierce constraint between point and curve intersecting plane.",
+)
+CONSTRAINT_SYMMETRIC = Binding(
+    toolbar_text="Symmetric",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Symmetric constraint across a centerline.",
+)
+CONSTRAINT_FIX = Binding(
+    toolbar_text="Fix",
+    toolbar_role="button",
+    confidence="high",
+    notes="Fix entity in place.",
+)
+CONSTRAINT_CURVATURE = Binding(
+    toolbar_text="Curvature",
+    toolbar_role="button",
+    confidence="medium",
+    notes="Curvature continuous constraint.",
+)
+
+# Feature tools
+FEATURE_EXTRUDE = Binding(
+    keys=("Shift", "e"),
+    toolbar_text="Extrude",
+    toolbar_role="button",
+    confidence="high",
+    notes="With a closed sketch region selected, press Shift+E or click Extrude.",
+)
+FEATURE_REVOLVE = Binding(
+    keys=("r",),
+    toolbar_text="Revolve",
+    toolbar_role="button",
+    confidence="medium",
+)
+FEATURE_FILLET = Binding(
+    keys=("f",),
+    toolbar_text="Fillet",
+    toolbar_role="button",
+    confidence="medium",
+    notes="'F' collides with view.fit when nothing is selected. Prefer toolbar click.",
+)
+FEATURE_CHAMFER = Binding(toolbar_text="Chamfer", toolbar_role="button", confidence="high")
+FEATURE_SHELL = Binding(toolbar_text="Shell", toolbar_role="button", confidence="high")
+FEATURE_PATTERN = Binding(toolbar_text="Pattern", toolbar_role="button", confidence="medium")
+FEATURE_MIRROR_BODY = Binding(toolbar_text="Mirror", toolbar_role="button", confidence="medium")
+
+# Assembly and meta
+ASSEMBLY_MATE = Binding(toolbar_text="Mate", toolbar_role="button", confidence="high")
+ASSEMBLY_PATTERN = Binding(toolbar_text="Pattern", toolbar_role="button", confidence="medium")
+
+# Global bindings
+UNDO = Binding(keys=("Control", "z"), confidence="high")
+REDO = Binding(keys=("Control", "shift", "z"), confidence="high")
+SAVE = Binding(
+    keys=("Control", "s"),
+    confidence="high",
+    notes="Onshape auto-saves; this is a no-op but the shortcut still works.",
+)
+DESELECT = Binding(keys=("Escape",), confidence="high")
+CONFIRM = Binding(keys=("Enter",), confidence="high")
+DELETE = Binding(keys=("Delete",), confidence="high")
+
+# Map datasheet tool name -> binding.
+BINDINGS: dict[str, Binding] = {
+    "view.fit": VIEW_FIT,
+    "view.top": VIEW_TOP,
+    "view.front": VIEW_FRONT,
+    "view.iso": VIEW_ISO,
+    "view.isometric": VIEW_ISO,
+    "view.rotate": Binding(
+        notes="Middle-mouse drag (no fixed coords). The LLM passes start/end via the call.",
+        confidence="high",
+    ),
+    # Sketch lifecycle
+    "sketch.start": SKETCH_START,
+    "sketch.exit": SKETCH_EXIT,
+    # Sketch Primitives
+    "sketch.line": SKETCH_LINE,
+    "sketch.line_midpoint": SKETCH_LINE_MIDPOINT,
+    "sketch.rectangle": SKETCH_RECTANGLE,
+    "sketch.rectangle_center": SKETCH_RECTANGLE_CENTER,
+    "sketch.rectangle_aligned": SKETCH_RECTANGLE_ALIGNED,
+    "sketch.circle": SKETCH_CIRCLE,
+    "sketch.circle_3point": SKETCH_CIRCLE_3POINT,
+    "sketch.ellipse": SKETCH_ELLIPSE,
+    "sketch.arc": SKETCH_ARC,
+    "sketch.arc_3point": SKETCH_ARC_3POINT,
+    "sketch.arc_tangent": SKETCH_ARC_TANGENT,
+    "sketch.arc_center": SKETCH_ARC_CENTER,
+    "sketch.arc_elliptical": SKETCH_ARC_ELLIPTICAL,
+    "sketch.conic": SKETCH_CONIC,
+    "sketch.polygon": SKETCH_POLYGON,
+    "sketch.polygon_inscribed": SKETCH_POLYGON_INSCRIBED,
+    "sketch.polygon_circumscribed": SKETCH_POLYGON_CIRCUMSCRIBED,
+    "sketch.spline": SKETCH_SPLINE,
+    "sketch.bezier": SKETCH_BEZIER,
+    "sketch.point": SKETCH_POINT,
+    "sketch.text": SKETCH_TEXT,
+    "sketch.use": SKETCH_USE,
+    "sketch.intersection": SKETCH_INTERSECTION,
+    # Operations
+    "sketch.construction": SKETCH_CONSTRUCTION,
+    "sketch.fillet": SKETCH_FILLET,
+    "sketch.chamfer": SKETCH_CHAMFER,
+    "sketch.trim": SKETCH_TRIM,
+    "sketch.extend": SKETCH_EXTEND,
+    "sketch.split": SKETCH_SPLIT,
+    "sketch.offset": SKETCH_OFFSET,
+    "sketch.slot": SKETCH_SLOT,
+    "sketch.mirror": SKETCH_MIRROR,
+    "sketch.pattern_linear": SKETCH_PATTERN_LINEAR,
+    "sketch.pattern_circular": SKETCH_PATTERN_CIRCULAR,
+    "sketch.transform": SKETCH_TRANSFORM,
+    # Dimensions & Constraints
+    "sketch.dimension": SKETCH_DIMENSION,
+    "sketch.equal": CONSTRAINT_EQUAL,
+    "sketch.constrain": CONSTRAINT_COINCIDENT,
+    "constraint.coincident": CONSTRAINT_COINCIDENT,
+    "constraint.concentric": CONSTRAINT_CONCENTRIC,
+    "constraint.parallel": CONSTRAINT_PARALLEL,
+    "constraint.tangent": CONSTRAINT_TANGENT,
+    "constraint.horizontal": CONSTRAINT_HORIZONTAL,
+    "constraint.vertical": CONSTRAINT_VERTICAL,
+    "constraint.perpendicular": CONSTRAINT_PERPENDICULAR,
+    "constraint.equal": CONSTRAINT_EQUAL,
+    "constraint.midpoint": CONSTRAINT_MIDPOINT,
+    "constraint.normal": CONSTRAINT_NORMAL,
+    "constraint.pierce": CONSTRAINT_PIERCE,
+    "constraint.symmetric": CONSTRAINT_SYMMETRIC,
+    "constraint.fix": CONSTRAINT_FIX,
+    "constraint.curvature": CONSTRAINT_CURVATURE,
+    # Features
+    "feature.extrude": FEATURE_EXTRUDE,
+    "feature.revolve": FEATURE_REVOLVE,
+    "feature.fillet": FEATURE_FILLET,
+    "feature.chamfer": FEATURE_CHAMFER,
+    "feature.shell": FEATURE_SHELL,
+    "feature.pattern": FEATURE_PATTERN,
+    "feature.mirror_body": FEATURE_MIRROR_BODY,
+    "assembly.mate": ASSEMBLY_MATE,
+    "assembly.pattern": ASSEMBLY_PATTERN,
+    "select.face": Binding(
+        notes="Click in viewport at (x,y); ui_actions handles the click.", confidence="high"
+    ),
+    "select.edge": Binding(notes="Click in viewport at (x,y).", confidence="high"),
+    "select.body": Binding(notes="Click in viewport or in the feature tree.", confidence="high"),
+    "ui.undo": UNDO,
+    "ui.redo": REDO,
+    "ui.wait": Binding(
+        notes="No-op. Pauses for N seconds and screenshots. Use when the LLM wants to re-observe the viewport.",
+        confidence="high",
+    ),
+    "doc.save": SAVE,
+    "doc.new": Binding(
+        toolbar_text="Create",
+        toolbar_role="button",
+        notes="Create a new document. Or just navigate to /documents/new.",
+        confidence="medium",
+    ),
+    "ui.deselect": DESELECT,
+    "ui.confirm": CONFIRM,
+    "ui.delete": DELETE,
+}
+
+
+def get(tool_name: str) -> Binding:
+    try:
+        return BINDINGS[tool_name]
+    except KeyError as e:
+        raise KeyError(f"No UI binding for {tool_name!r} in shortcuts.py") from e

src/onshape_mcp/tools.py

@@ -0,0 +1,539 @@
+"""Onshape tool datasheet. One entry per semantic op the agent can call.
+The actual clicks live in ui_actions.py / driver.py. This file is the
+vocabulary the LLM sees via the `tool_datasheet` MCP tool.
+
+Status flags: planned, stub, working.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ToolSpec:
+    name: str
+    purpose: str
+    requires: list[str] = field(default_factory=list)  # preconditions
+    produces: list[str] = field(default_factory=list)  # postconditions
+    next_steps: list[str] = field(default_factory=list)  # likely follow-ups
+    status: str = "working"
+
+
+# Sketch lifecycle
+SKETCH_START = ToolSpec(
+    name="sketch.start",
+    purpose="Open a new sketch on a chosen plane (Top/Front/Right or a face).",
+    produces=["sketch.active=true"],
+    next_steps=["sketch.rectangle", "sketch.circle", "sketch.line", "sketch.spline"],
+    status="working",
+)
+SKETCH_EXIT = ToolSpec(
+    name="sketch.exit",
+    purpose="Close the active sketch and return to part studio.",
+    requires=["sketch.active=true"],
+    produces=["sketch.active=false"],
+    next_steps=["feature.extrude", "feature.revolve", "feature.fillet", "feature.chamfer"],
+    status="working",
+)
+
+# Sketch Primitives
+SKETCH_LINE = ToolSpec(
+    name="sketch.line",
+    purpose="Single line segment from p1=(x1,y1) to p2=(x2,y2).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.constrain", "sketch.exit"],
+    status="working",
+)
+SKETCH_LINE_MIDPOINT = ToolSpec(
+    name="sketch.line_midpoint",
+    purpose="Line segment symmetric around a midpoint coordinate.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_RECTANGLE = ToolSpec(
+    name="sketch.rectangle",
+    purpose="Two-corner rectangle. Pass quadrant='1'|'2'|'3'|'4', centered=true, or corner1=(x,y), corner2=(x,y), with width/height (e.g. '10 cm' or 50).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "feature.extrude", "sketch.exit"],
+    status="working",
+)
+SKETCH_RECTANGLE_CENTER = ToolSpec(
+    name="sketch.rectangle_center",
+    purpose="Center-point rectangle defined by center=(x,y) and corner=(x,y) or width/height.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "feature.extrude", "sketch.exit"],
+    status="working",
+)
+SKETCH_RECTANGLE_ALIGNED = ToolSpec(
+    name="sketch.rectangle_aligned",
+    purpose="3-point aligned rectangle defined by baseline (p1, p2) and height point p3.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_CIRCLE = ToolSpec(
+    name="sketch.circle",
+    purpose="Center point circle. Pass centered=true (for origin) or center=(x,y), radius=mm or radius_px.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "feature.extrude", "sketch.exit"],
+    status="working",
+)
+SKETCH_CIRCLE_3POINT = ToolSpec(
+    name="sketch.circle_3point",
+    purpose="Circle passing through three points p1, p2, p3.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_ELLIPSE = ToolSpec(
+    name="sketch.ellipse",
+    purpose="Ellipse defined by center=(x,y), major axis point, and minor axis point.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_ARC = ToolSpec(
+    name="sketch.arc",
+    purpose="3-point arc from p1 to p2 passing through radius/point p3.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_ARC_TANGENT = ToolSpec(
+    name="sketch.arc_tangent",
+    purpose="Arc tangent to an existing line/curve starting at vertex p1 ending at p2.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_ARC_CENTER = ToolSpec(
+    name="sketch.arc_center",
+    purpose="Center point arc defined by center=(x,y), start angle/point p1, end angle/point p2.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_POLYGON = ToolSpec(
+    name="sketch.polygon",
+    purpose="Inscribed or circumscribed polygon with center=(x,y), radius=r, and sides=n (e.g. 6 for hexagon).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "feature.extrude", "sketch.exit"],
+    status="working",
+)
+SKETCH_SPLINE = ToolSpec(
+    name="sketch.spline",
+    purpose="Spline through control points [(x1,y1), (x2,y2), ...].",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_POINT = ToolSpec(
+    name="sketch.point",
+    purpose="Single point at (x,y).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.constrain", "sketch.exit"],
+    status="working",
+)
+SKETCH_TEXT = ToolSpec(
+    name="sketch.text",
+    purpose="Text box defined by corner1=(x,y), corner2=(x,y), and text string.",
+    requires=["sketch.active=true"],
+    next_steps=["feature.extrude", "sketch.exit"],
+    status="working",
+)
+SKETCH_USE = ToolSpec(
+    name="sketch.use",
+    purpose="Project 3D edge or face onto active sketch plane.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.offset", "sketch.trim", "sketch.exit"],
+    status="working",
+)
+
+# Modifications & Operations
+SKETCH_CONSTRUCTION = ToolSpec(
+    name="sketch.construction",
+    purpose="Toggle construction mode or convert entity at (x,y) to/from construction line ('q').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.line", "sketch.circle", "sketch.exit"],
+    status="working",
+)
+SKETCH_FILLET = ToolSpec(
+    name="sketch.fillet",
+    purpose="Create a 2D rounded fillet at vertex (x,y) or between two curves with radius_mm.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_CHAMFER = ToolSpec(
+    name="sketch.chamfer",
+    purpose="Create a 2D chamfer at vertex (x,y) with distance_mm.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_TRIM = ToolSpec(
+    name="sketch.trim",
+    purpose="Trim a curve segment at (x,y) back to the nearest intersections ('m').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_EXTEND = ToolSpec(
+    name="sketch.extend",
+    purpose="Extend an endpoint at (x,y) forward to the next curve boundary ('x').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.trim", "sketch.exit"],
+    status="working",
+)
+SKETCH_SPLIT = ToolSpec(
+    name="sketch.split",
+    purpose="Split curve into two segments at coordinate (x,y).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+SKETCH_OFFSET = ToolSpec(
+    name="sketch.offset",
+    purpose="Offset entity at (x,y) by distance_mm to target side.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_SLOT = ToolSpec(
+    name="sketch.slot",
+    purpose="Create an elongated slot along a line segment with a given width/radius.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+SKETCH_MIRROR = ToolSpec(
+    name="sketch.mirror",
+    purpose="Mirror entities across a centerline (line_xy, entities=[(x,y), ...]).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit", "feature.extrude"],
+    status="working",
+)
+SKETCH_PATTERN_LINEAR = ToolSpec(
+    name="sketch.pattern_linear",
+    purpose="Linear pattern of entities along X and Y axes with counts and spacings.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+SKETCH_PATTERN_CIRCULAR = ToolSpec(
+    name="sketch.pattern_circular",
+    purpose="Circular pattern of entities around center=(x,y) with count and angle.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+SKETCH_TRANSFORM = ToolSpec(
+    name="sketch.transform",
+    purpose="Translate, scale, or rotate selected entities.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+
+# Dimensions & Constraints
+SKETCH_DIMENSION = ToolSpec(
+    name="sketch.dimension",
+    purpose="Apply a driven linear, radial, or angular dimension (entity_xy, label_xy, value).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit", "feature.extrude"],
+    status="working",
+)
+CONSTRAINT_COINCIDENT = ToolSpec(
+    name="constraint.coincident",
+    purpose="Make two points coincident, or point coincident to a curve.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_CONCENTRIC = ToolSpec(
+    name="constraint.concentric",
+    purpose="Make two arcs or circles share the same center point.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_PARALLEL = ToolSpec(
+    name="constraint.parallel",
+    purpose="Make two lines parallel ('b').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_TANGENT = ToolSpec(
+    name="constraint.tangent",
+    purpose="Make an arc/circle tangent to a line or another arc ('t').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_HORIZONTAL = ToolSpec(
+    name="constraint.horizontal",
+    purpose="Make a line horizontal or align two points horizontally ('h').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_VERTICAL = ToolSpec(
+    name="constraint.vertical",
+    purpose="Make a line vertical or align two points vertically ('v').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_PERPENDICULAR = ToolSpec(
+    name="constraint.perpendicular",
+    purpose="Make two lines perpendicular (90 degrees).",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_EQUAL = ToolSpec(
+    name="constraint.equal",
+    purpose="Constrain two lines to equal length, or two circles/arcs to equal radius ('e').",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_MIDPOINT = ToolSpec(
+    name="constraint.midpoint",
+    purpose="Constrain a point to the midpoint of a line segment.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.dimension", "sketch.exit"],
+    status="working",
+)
+CONSTRAINT_NORMAL = ToolSpec(
+    name="constraint.normal",
+    purpose="Constrain a curve normal to a plane.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+CONSTRAINT_PIERCE = ToolSpec(
+    name="constraint.pierce",
+    purpose="Constrain a point to the pierce point of an intersecting 3D curve.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+CONSTRAINT_SYMMETRIC = ToolSpec(
+    name="constraint.symmetric",
+    purpose="Constrain two entities symmetrically across a centerline.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+CONSTRAINT_FIX = ToolSpec(
+    name="constraint.fix",
+    purpose="Fix an entity in place preventing solver movement.",
+    requires=["sketch.active=true"],
+    next_steps=["sketch.exit"],
+    status="working",
+)
+
+# Feature tools
+FEATURE_EXTRUDE = ToolSpec(
+    name="feature.extrude",
+    purpose="Extrude the active sketch region by depth, optionally with draft/taper.",
+    requires=["sketch.active=false"],
+    next_steps=["feature.fillet", "feature.chamfer", "feature.shell", "feature.pattern"],
+    status="working",
+)
+FEATURE_REVOLVE = ToolSpec(
+    name="feature.revolve",
+    purpose="Revolve a sketch region around an axis by an angle.",
+    requires=["sketch.active=false"],
+    next_steps=["feature.fillet", "feature.chamfer"],
+    status="working",
+)
+FEATURE_FILLET = ToolSpec(
+    name="feature.fillet",
+    purpose="Round selected 3D edges with a constant radius.",
+    next_steps=["feature.chamfer", "feature.shell", "feature.pattern"],
+    status="working",
+)
+FEATURE_CHAMFER = ToolSpec(
+    name="feature.chamfer",
+    purpose="Bevel selected 3D edges with a distance.",
+    next_steps=["feature.fillet", "feature.shell", "feature.pattern"],
+    status="working",
+)
+FEATURE_SHELL = ToolSpec(
+    name="feature.shell",
+    purpose="Hollow a body, removing selected faces, with a wall thickness.",
+    next_steps=["feature.fillet", "feature.pattern"],
+    status="working",
+)
+FEATURE_PATTERN = ToolSpec(
+    name="feature.pattern",
+    purpose="Linear or circular pattern of features / faces / bodies.",
+    next_steps=["feature.mirror_body", "assembly.mate"],
+    status="working",
+)
+FEATURE_MIRROR_BODY = ToolSpec(
+    name="feature.mirror_body",
+    purpose="Mirror bodies across a plane in the part studio.",
+    next_steps=["feature.pattern", "assembly.mate"],
+    status="working",
+)
+
+# Selection and view
+SELECT_FACE = ToolSpec(
+    name="select.face",
+    purpose="Click a face in the viewport at (x,y).",
+    next_steps=["sketch.start", "feature.extrude", "feature.fillet"],
+    status="working",
+)
+SELECT_EDGE = ToolSpec(
+    name="select.edge",
+    purpose="Click an edge in the viewport at (x,y).",
+    next_steps=["feature.fillet", "feature.chamfer"],
+    status="working",
+)
+SELECT_BODY = ToolSpec(
+    name="select.body",
+    purpose="Click a body in the viewport or feature tree.",
+    next_steps=["feature.mirror_body"],
+    status="working",
+)
+VIEW_FIT = ToolSpec(
+    name="view.fit",
+    purpose="Zoom to fit all visible geometry in viewport ('f').",
+    status="working",
+)
+VIEW_ROTATE = ToolSpec(
+    name="view.rotate",
+    purpose="Right-mouse drag from start to end to orbit the camera.",
+    status="working",
+)
+ASSEMBLY_MATE = ToolSpec(
+    name="assembly.mate",
+    purpose="Create a mate between two mate connectors.",
+    status="planned",
+)
+ASSEMBLY_PATTERN = ToolSpec(
+    name="assembly.pattern",
+    purpose="Pattern an instance in an assembly.",
+    status="planned",
+)
+DOC_OPEN = ToolSpec(
+    name="doc.open",
+    purpose="Navigate to an Onshape document by URL.",
+    status="working",
+)
+DOC_SAVE = ToolSpec(
+    name="doc.save",
+    purpose="No-op; Onshape auto-saves continuously.",
+    status="working",
+)
+UNDO = ToolSpec(
+    name="ui.undo",
+    purpose="Send the standard Undo shortcut (Ctrl/Cmd+Z).",
+    next_steps=["ui.redo", "view.fit"],
+    status="working",
+)
+REDO = ToolSpec(
+    name="ui.redo",
+    purpose="Send Redo (Ctrl/Cmd+Shift+Z).",
+    next_steps=["ui.undo", "view.fit"],
+    status="working",
+)
+
+ALL_TOOLS: list[ToolSpec] = [
+    # Lifecycle
+    SKETCH_START,
+    SKETCH_EXIT,
+    # Primitives
+    SKETCH_LINE,
+    SKETCH_LINE_MIDPOINT,
+    SKETCH_RECTANGLE,
+    SKETCH_RECTANGLE_CENTER,
+    SKETCH_RECTANGLE_ALIGNED,
+    SKETCH_CIRCLE,
+    SKETCH_CIRCLE_3POINT,
+    SKETCH_ELLIPSE,
+    SKETCH_ARC,
+    SKETCH_ARC_TANGENT,
+    SKETCH_ARC_CENTER,
+    SKETCH_POLYGON,
+    SKETCH_SPLINE,
+    SKETCH_POINT,
+    SKETCH_TEXT,
+    SKETCH_USE,
+    # Operations
+    SKETCH_CONSTRUCTION,
+    SKETCH_FILLET,
+    SKETCH_CHAMFER,
+    SKETCH_TRIM,
+    SKETCH_EXTEND,
+    SKETCH_SPLIT,
+    SKETCH_OFFSET,
+    SKETCH_SLOT,
+    SKETCH_MIRROR,
+    SKETCH_PATTERN_LINEAR,
+    SKETCH_PATTERN_CIRCULAR,
+    SKETCH_TRANSFORM,
+    # Dimensions & Constraints
+    SKETCH_DIMENSION,
+    CONSTRAINT_COINCIDENT,
+    CONSTRAINT_CONCENTRIC,
+    CONSTRAINT_PARALLEL,
+    CONSTRAINT_TANGENT,
+    CONSTRAINT_HORIZONTAL,
+    CONSTRAINT_VERTICAL,
+    CONSTRAINT_PERPENDICULAR,
+    CONSTRAINT_EQUAL,
+    CONSTRAINT_MIDPOINT,
+    CONSTRAINT_NORMAL,
+    CONSTRAINT_PIERCE,
+    CONSTRAINT_SYMMETRIC,
+    CONSTRAINT_FIX,
+    # Features
+    FEATURE_EXTRUDE,
+    FEATURE_REVOLVE,
+    FEATURE_FILLET,
+    FEATURE_CHAMFER,
+    FEATURE_SHELL,
+    FEATURE_PATTERN,
+    FEATURE_MIRROR_BODY,
+    SELECT_FACE,
+    SELECT_EDGE,
+    SELECT_BODY,
+    VIEW_FIT,
+    VIEW_ROTATE,
+    ASSEMBLY_MATE,
+    ASSEMBLY_PATTERN,
+    DOC_OPEN,
+    DOC_SAVE,
+    UNDO,
+    REDO,
+]
+
+
+def as_prompt_block() -> str:
+    """Render the datasheet as a compact prompt block for the LLM."""
+    lines = ["# Onshape tool vocabulary", ""]
+    for t in ALL_TOOLS:
+        bits = [f"**{t.name}** {t.purpose}"]
+        if t.requires:
+            bits.append(f"  requires: {', '.join(t.requires)}")
+        if t.produces:
+            bits.append(f"  produces: {', '.join(t.produces)}")
+        if t.next_steps:
+            bits.append(f"  next: {', '.join(t.next_steps)}")
+        bits.append(f"  status: {t.status}")
+        lines.extend(bits)
+    return "\n".join(lines)
+
+
+def lookup(name: str) -> ToolSpec:
+    for t in ALL_TOOLS:
+        if t.name == name:
+            return t
+    raise KeyError(f"Unknown tool: {name}")

src/onshape_mcp/tunnel.py

@@ -0,0 +1,131 @@
+"""Automatic web tunnel manager for Onshape MCP.
+Spawns the local SSE server and exposes a secure public HTTPS endpoint
+(via Cloudflare Quick Tunnels or Localtunnel) with zero configuration.
+
+Allows web AIs (ChatGPT Web, LibreChat, Open WebUI) to connect instantly.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from typing import Any
+
+from .config import settings
+
+
+def find_tunnel_binary() -> tuple[str, list[str]] | None:
+    """Find available tunnel tool (cloudflared or localtunnel)."""
+    # 1. Cloudflare tunnel (no sign-up, fast, reliable)
+    cf = shutil.which("cloudflared")
+    if cf:
+        return ("cloudflared", [cf, "tunnel", "--url"])
+
+    # 2. Localtunnel via npx
+    npx = shutil.which("npx")
+    if npx:
+        return ("localtunnel", [npx, "-y", "localtunnel", "--port"])
+
+    return None
+
+
+def run_tunnel_and_server(port: int = 8000, host: str = "127.0.0.1") -> None:
+    """Start the FastMCP SSE server and attach an auto-tunnel for web AIs."""
+    tunnel_info = find_tunnel_binary()
+    if not tunnel_info:
+        print("=" * 68)
+        print("⚠ No tunneling tool (cloudflared or npx) found on your system.")
+        print("To enable instant web sharing, install cloudflared:")
+        print("  • Mac:     brew install cloudflared")
+        print("  • Linux:   sudo apt install cloudflared  (or download binary)")
+        print("  • Windows: winget install Cloudflare.cloudflared")
+        print("=" * 68)
+        # Fallback to local SSE only
+        from .server import mcp
+        mcp.settings.host = host
+        mcp.settings.port = port
+        print(f"Starting local SSE server at http://{host}:{port}/sse ...")
+        mcp.run(transport="sse")
+        return
+
+    tunnel_type, tunnel_cmd = tunnel_info
+    local_url = f"http://{host}:{port}"
+
+    print("=" * 68)
+    print("   🌐 Onshape MCP — Instant Web Sharing & ChatGPT Connector")
+    print("=" * 68)
+    print(f"Starting local SSE engine on port {port}...")
+
+    # Start the tunnel process in the background
+    if tunnel_type == "cloudflared":
+        cmd = [*tunnel_cmd, local_url]
+    else:
+        cmd = [*tunnel_cmd, str(port)]
+
+    tunnel_proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+    public_url: str | None = None
+    start_time = time.time()
+
+    # Read output to capture the public URL
+    def _read_stream(stream: Any) -> None:
+        nonlocal public_url
+        if not stream:
+            return
+        for line in iter(stream.readline, ""):
+            if not line:
+                break
+            # Cloudflare pattern
+            m_cf = re.search(r"https://[a-zA-Z0-9-]+\.trycloudflare\.com", line)
+            if m_cf:
+                public_url = m_cf.group(0)
+                break
+            # Localtunnel pattern
+            m_lt = re.search(r"https://[a-zA-Z0-9-]+\.loca\.lt", line)
+            if m_lt:
+                public_url = m_lt.group(0)
+                break
+
+    t_err = threading.Thread(target=_read_stream, args=(tunnel_proc.stderr,), daemon=True)
+    t_out = threading.Thread(target=_read_stream, args=(tunnel_proc.stdout,), daemon=True)
+    t_err.start()
+    t_out.start()
+
+    print("Requesting secure HTTPS tunnel from Cloudflare...")
+    while public_url is None and (time.time() - start_time < 15):
+        time.sleep(0.5)
+
+    if public_url:
+        sse_url = f"{public_url.rstrip('/')}/sse"
+        print("\n" + "=" * 68)
+        print("🎉 SUCCESS! Your Onshape MCP is live on the internet:")
+        print(f"\n👉 MCP SSE URL:  \033[1;32m{sse_url}\033[0m\n")
+        print("How to use this link:")
+        print("1. In ChatGPT Web: Add this link to your MCP / Custom GPT connector.")
+        print("2. In LibreChat / Open WebUI: Add this link under MCP servers.")
+        print("3. Press Ctrl+C in this terminal when you want to disconnect.")
+        print("=" * 68 + "\n")
+    else:
+        print("⚠ Tunnel did not return a public URL in 15s. Running locally.")
+        print(f"Local endpoint: http://{host}:{port}/sse\n")
+
+    # Now run the SSE server in the main thread
+    from .server import mcp
+    mcp.settings.host = host
+    mcp.settings.port = port
+
+    try:
+        mcp.run(transport="sse")
+    finally:
+        tunnel_proc.terminate()
+        tunnel_proc.wait()

src/onshape_mcp/ui_actions.py

@@ -0,0 +1,1216 @@
+"""High-level Onshape operations. Each public function corresponds to a
+datasheet tool. Uses driver.py primitives + shortcuts.py bindings, journals
+to journal.py. Raises before touching the UI if a precondition isn't met.
+
+Conventions: every function takes the driver explicitly (no globals), returns
+a `Result` dict, and uses viewport pixel coords. Call `driver.viewport_box()`
+to get bounds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .driver import OnshapeDriver
+from .journal import JournalEntry, journal
+from .shortcuts import get as binding_for
+
+
+@dataclass
+class Result:
+    ok: bool
+    note: str = ""
+    screenshot: Path | None = None
+    extra: dict[str, Any] | None = None
+
+    @property
+    def summary(self) -> str:
+        return self.note
+
+    @property
+    def meta(self) -> dict[str, Any]:
+        return self.extra or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"ok": self.ok, "note": self.note}
+        if self.screenshot is not None:
+            d["screenshot"] = str(self.screenshot)
+        if self.extra:
+            d.update(self.extra)
+        return d
+
+
+def _record(tool: str, args: dict[str, Any], result: Result) -> None:
+    e = JournalEntry.new(tool, args)
+    e.result = "ok" if result.ok else "fail"
+    e.note = result.note
+    if result.screenshot is not None:
+        try:
+            e.screenshot = str(result.screenshot.relative_to(result.screenshot.parent.parent))
+        except Exception:
+            e.screenshot = str(result.screenshot)
+    journal.append(e)
+
+
+# View and camera
+
+
+async def view_fit(d: OnshapeDriver) -> Result:
+    b = binding_for("view.fit")
+    if b.keys:
+        await d.press_chord(*b.keys)
+    elif b.toolbar_text:
+        ok = await d.click_text(b.toolbar_text)
+        if not ok:
+            return Result(False, f"view.fit: toolbar button {b.toolbar_text!r} not found")
+    shot = await d.screenshot("view_fit.png")
+    r = Result(True, "fit to view", shot)
+    _record("view.fit", {}, r)
+    return r
+
+
+async def view_top(d: OnshapeDriver) -> Result:
+    b = binding_for("view.top")
+    if b.keys:
+        await d.press_chord(*b.keys)
+    shot = await d.screenshot("view_top.png")
+    r = Result(True, "top view", shot)
+    _record("view.top", {}, r)
+    return r
+
+
+async def view_front(d: OnshapeDriver) -> Result:
+    b = binding_for("view.front")
+    if b.keys:
+        await d.press_chord(*b.keys)
+    shot = await d.screenshot("view_front.png")
+    r = Result(True, "front view", shot)
+    _record("view.front", {}, r)
+    return r
+
+
+async def view_iso(d: OnshapeDriver) -> Result:
+    b = binding_for("view.iso")
+    if b.keys:
+        await d.press_chord(*b.keys)
+    shot = await d.screenshot("view_isometric.png")
+    r = Result(True, "isometric view", shot)
+    _record("view.iso", {}, r)
+    return r
+
+
+view_isometric = view_iso
+
+# Sketching
+
+
+async def sketch_start(
+    d: OnshapeDriver,
+    plane_xy: tuple[float, float] | None = None,
+    plane_name: str | None = None,
+) -> Result:
+    """Click the Sketch button, then click a plane (or pass a coordinate/name).
+
+    If `plane_xy` is None, we select the desired plane in the feature tree
+    using DOM locator (default: Top plane) and press 'n' to orient normal to the sketch plane.
+    """
+    sketch_btn = d.page.locator("[command-id='newSketch']")
+    if await sketch_btn.count() > 0:
+        await sketch_btn.first.click()
+    else:
+        b = binding_for("sketch.start")
+        clicked = False
+        if b.toolbar_text:
+            clicked = await d.click_text(b.toolbar_text, timeout_ms=500)
+        if not clicked:
+            if b.keys:
+                await d.press_chord(*b.keys)
+            else:
+                await d.click(155.0, 58.0)
+    # small settle delay for the UI to switch into plane-pick mode
+    await asyncio.sleep(0.3)
+
+    target_name = (plane_name or "Top").capitalize()
+    if plane_xy is not None:
+        await d.click(*plane_xy)
+        await asyncio.sleep(0.4)
+        try:
+            await d.page.locator("canvas").first.hover()
+        except Exception:
+            pass
+        await d.press_key("n")
+    else:
+        # Use exact DOM locator for feature tree plane
+        loc = d.page.locator("span.os-list-item-name", has_text=target_name)
+        if await loc.count() > 0:
+            await loc.first.click()
+            await asyncio.sleep(0.3)
+            # Deterministically orient normal to the selected plane via context menu
+            try:
+                await loc.first.click(button="right")
+                await asyncio.sleep(0.3)
+                normal_item = d.page.locator(
+                    "div.context-menu-item-text", has_text="View normal to"
+                )
+                if await normal_item.count() > 0:
+                    await normal_item.first.click()
+                else:
+                    await d.press_key("n")
+            except Exception:
+                await d.press_key("n")
+        else:
+            await d.click(65.0, 232.0)
+            await asyncio.sleep(0.4)
+            await d.press_key("n")
+    await asyncio.sleep(1.2)
+    shot = await d.screenshot("sketch_start.png")
+    r = Result(True, f"sketch started on {target_name}", shot, {"plane": target_name})
+    _record("sketch.start", {"plane": target_name}, r)
+    return r
+
+
+SKETCH_COMMAND_IDS: dict[str, str] = {
+    "sketch.start": "newSketch",
+    "sketch.line": "LINESEGMENT",
+    "sketch.line_midpoint": "LINESEGMENT_MIDPOINT",
+    "sketch.rectangle": "RECTANGLE_TWO_CORNERS",
+    "sketch.rectangle_center": "RECTANGLE_CENTER_CORNER",
+    "sketch.rectangle_aligned": "ALIGNED_RECTANGLE",
+    "sketch.circle": "CIRCLE_CENTER_RADIUS",
+    "sketch.circle_3point": "CIRCLE_THREE_POINTS",
+    "sketch.ellipse": "ELLIPSE",
+    "sketch.arc": "ARC_START_END_RADIUS",
+    "sketch.arc_3point": "ARC_START_END_RADIUS",
+    "sketch.arc_tangent": "ARC_TANGENT",
+    "sketch.arc_center": "ARC_CENTER_START_END",
+    "sketch.polygon": "INSCRIBED_POLYGON",
+    "sketch.polygon_inscribed": "INSCRIBED_POLYGON",
+    "sketch.polygon_circumscribed": "CIRCUMSCRIBED_POLYGON",
+    "sketch.spline": "SPLINE",
+    "sketch.bezier": "BEZIER",
+    "sketch.point": "POINT",
+    "sketch.text": "TEXT_RECTANGLE_TWO_CORNERS",
+    "sketch.use": "USE",
+    "sketch.intersection": "INTERSECTION",
+    "sketch.construction": "TOGGLE_CONSTRUCTION",
+    "sketch.fillet": "FILLET",
+    "sketch.chamfer": "SKETCH_CHAMFER",
+    "sketch.trim": "TRIM",
+    "sketch.extend": "EXTEND",
+    "sketch.split": "SPLIT",
+    "sketch.offset": "OFFSET",
+    "sketch.slot": "SLOT",
+    "sketch.mirror": "SKETCHMIRROR",
+    "sketch.pattern_linear": "SKETCHLPATTERN",
+    "sketch.pattern_circular": "SKETCHCPATTERN",
+    "sketch.transform": "SKETCH_TRANSFORM",
+    "sketch.dimension": "DIMENSION",
+    # Constraints
+    "sketch.equal": "EQUAL",
+    "constraint.coincident": "COINCIDENT",
+    "constraint.concentric": "CONCENTRIC",
+    "constraint.parallel": "PARALLEL",
+    "constraint.tangent": "TANGENT",
+    "constraint.horizontal": "HORIZONTAL",
+    "constraint.vertical": "VERTICAL",
+    "constraint.perpendicular": "PERPENDICULAR",
+    "constraint.equal": "EQUAL",
+    "constraint.midpoint": "MIDPOINT",
+    "constraint.normal": "NORMAL",
+    "constraint.pierce": "PIERCE",
+    "constraint.symmetric": "MIRROR",
+    "constraint.fix": "FIX",
+    "constraint.curvature": "CURVATURE",
+    # 3D Features
+    "feature.extrude": "extrude",
+    "feature.revolve": "revolve",
+}
+
+
+async def _activate_sketch_tool(d: OnshapeDriver, name: str) -> Result:
+    """Activate a sketch tool via DOM command-id, keyboard shortcut, or text locator."""
+    # 1. Try keyboard shortcut first if available (fastest, most reliable)
+    b = binding_for(name)
+    if b.keys:
+        await d.press_chord(*b.keys)
+        await asyncio.sleep(0.2)
+        return Result(True, f"{name} tool active (keys: {b.keys})")
+
+    # 2. Try direct DOM command-id locator
+    cmd_id = SKETCH_COMMAND_IDS.get(name)
+    if cmd_id:
+        loc = d.page.locator(f"[command-id='{cmd_id}']")
+        if await loc.count() > 0 and await loc.first.is_visible():
+            classes = await loc.first.get_attribute("class") or ""
+            if "is-active" in classes:
+                return Result(True, f"{name} already active")
+            await loc.first.click()
+            await asyncio.sleep(0.25)
+            return Result(True, f"{name} tool active (command-id: {cmd_id})")
+
+    # 3. Fall back to visible toolbar text
+    if b.toolbar_text:
+        clicked = await d.click_text(b.toolbar_text, timeout_ms=1000)
+        if clicked:
+            await asyncio.sleep(0.2)
+            return Result(True, f"{name} tool active (text: {b.toolbar_text})")
+
+    return Result(False, f"{name}: no binding or visible tool button available")
+
+
+def _parse_dim_px(val: float | str | None, default_px: float = 120.0) -> float:
+    if val is None:
+        return default_px
+    try:
+        s = str(val).strip().lower()
+        num = float("".join(c for c in s if c.isdigit() or c == "."))
+        if "cm" in s:
+            px = num * 32.583
+        elif "mm" in s:
+            px = num * 3.2583
+        elif "in" in s or "inch" in s:
+            px = num * 82.75
+        elif num <= 25:
+            px = num * 32.583
+        else:
+            px = num * 3.2583
+        return max(40.0, min(550.0, px))
+    except Exception:
+        return default_px
+
+
+async def get_canvas_origin(d: OnshapeDriver) -> tuple[float, float]:
+    """Calculate the exact center point (origin) of the WebGL canvas.
+    Takes into account the left feature panel (246px) and toolbar (76px).
+    """
+    try:
+        box = await d.page.evaluate("""() => {
+            const c = document.querySelector('canvas.os-main-canvas') || document.querySelector('canvas');
+            if (!c) return {cx: 843.0, cy: 473.0};
+            const r = c.getBoundingClientRect();
+            return {cx: r.x + r.width / 2.0, cy: r.y + r.height / 2.0};
+        }""")
+        return (float(box.get("cx", 843.0)), float(box.get("cy", 473.0)))
+    except Exception:
+        return (843.0, 473.0)
+
+
+async def _ensure_viewport_coords(d: OnshapeDriver, pt: tuple[float, float]) -> tuple[float, float]:
+    x, y = pt
+    cx, cy = await get_canvas_origin(d)
+    # If pt is (0, 0), return exact origin
+    if x == 0 and y == 0:
+        return (cx, cy)
+    # If small coordinates (CAD units relative to origin), convert to screen pixels:
+    # In CAD space, +X is right, +Y is up (so screen Y is cy - y*scale)
+    if abs(x) <= 200 and abs(y) <= 200:
+        scale = 10.0 if (abs(x) <= 25 and abs(y) <= 25) else 1.0
+        return (cx + x * scale, cy - y * scale)
+    return (x, y)
+
+
+async def sketch_rectangle(
+    d: OnshapeDriver,
+    corner1: tuple[float, float] | None = None,
+    corner2: tuple[float, float] | None = None,
+    width: float | str | None = None,
+    height: float | str | None = None,
+    quadrant: str | int | None = None,
+    centered: bool | None = None,
+) -> Result:
+    cx, cy = await get_canvas_origin(d)
+    span_x = _parse_dim_px(width, default_px=120.0)
+    span_y = _parse_dim_px(height, default_px=120.0)
+
+    if centered:
+        corner1 = (cx - span_x / 2.0, cy - span_y / 2.0)
+        corner2 = (cx + span_x / 2.0, cy + span_y / 2.0)
+    elif quadrant is not None:
+        q = str(quadrant).upper().strip()
+        if q in ("1", "I", "TOP-RIGHT", "NE"):
+            corner1 = (cx, cy)
+            corner2 = (cx + span_x, cy - span_y)
+        elif q in ("2", "II", "TOP-LEFT", "NW"):
+            corner1 = (cx, cy)
+            corner2 = (cx - span_x, cy - span_y)
+        elif q in ("3", "III", "BOTTOM-LEFT", "SW"):
+            corner1 = (cx, cy)
+            corner2 = (cx - span_x, cy + span_y)
+        elif q in ("4", "IV", "BOTTOM-RIGHT", "SE"):
+            corner1 = (cx, cy)
+            corner2 = (cx + span_x, cy + span_y)
+    elif corner1 is None and corner2 is None:
+        corner1 = (cx - span_x / 2.0, cy - span_y / 2.0)
+        corner2 = (cx + span_x / 2.0, cy + span_y / 2.0)
+
+    c1 = await _ensure_viewport_coords(
+        d, corner1 if corner1 is not None else (cx - 70.0, cy - 70.0)
+    )
+    c2 = await _ensure_viewport_coords(
+        d, corner2 if corner2 is not None else (cx + 70.0, cy + 70.0)
+    )
+
+    t = await _activate_sketch_tool(d, "sketch.rectangle")
+    if not t.ok:
+        _record("sketch.rectangle", {"corner1": list(c1), "corner2": list(c2)}, t)
+        return t
+    await d.click(*c1)
+    await asyncio.sleep(0.3)
+    await d.click(*c2)
+    await asyncio.sleep(0.3)
+    await d.press_key("Escape")
+    await asyncio.sleep(0.3)
+
+    min_x, max_x = min(c1[0], c2[0]), max(c1[0], c2[0])
+    min_y, max_y = min(c1[1], c2[1]), max(c1[1], c2[1])
+    # Pick points at 30% along edges to safely avoid datum axis lines and origin glyphs
+    dx = max_x - min_x
+    dy = max_y - min_y
+    top_pick = (min_x + dx * 0.3, min_y)
+    left_pick = (min_x, min_y + dy * 0.3)
+    top_label = (top_pick[0], top_pick[1] - 45.0)
+    left_label = (left_pick[0] - 55.0, left_pick[1])
+
+    # If width or height are specified, apply constraints and dimensions
+    if width is not None and height is not None and str(width).strip() == str(height).strip():
+        # Square: apply Equal constraint first so geometry is strictly equilateral
+        await sketch_equal(d, top_pick, left_pick)
+        await asyncio.sleep(0.5)
+        # Dimension top edge
+        await sketch_dimension(d, top_pick, top_label, width)
+    elif width is not None:
+        await sketch_dimension(d, top_pick, top_label, width)
+        if height is not None:
+            await asyncio.sleep(0.6)
+            await sketch_dimension(d, left_pick, left_label, height)
+    elif height is not None:
+        await sketch_dimension(d, left_pick, left_label, height)
+
+    shot = await d.screenshot("sketch_rectangle.png")
+    meta = {
+        "corner1": list(c1),
+        "corner2": list(c2),
+        "last_vertex": list(c2),
+        "width": width,
+        "height": height,
+        "quadrant": quadrant,
+        "centered": centered,
+    }
+    r = Result(True, f"rectangle {c1} -> {c2} (dim={width}x{height})", shot, meta)
+    _record("sketch.rectangle", meta, r)
+    return r
+
+
+async def sketch_circle(
+    d: OnshapeDriver,
+    center: tuple[float, float] | None = None,
+    radius_px: float = 50.0,
+    centered: bool | None = None,
+) -> Result:
+    t = await _activate_sketch_tool(d, "sketch.circle")
+    if not t.ok:
+        _record(
+            "sketch.circle", {"center": list(center) if center else None, "radius_px": radius_px}, t
+        )
+        return t
+    cx, cy = await get_canvas_origin(d)
+    if centered or center is None or center == (0, 0):
+        c = (cx, cy)
+    else:
+        c = await _ensure_viewport_coords(d, center)
+    r_px = radius_px if radius_px > 10 else radius_px * 15.0
+    await d.click(*c)
+    await asyncio.sleep(0.1)
+    await d.click(c[0] + r_px, c[1])
+    await asyncio.sleep(0.1)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_circle.png")
+    r = Result(True, f"circle center={c} r={r_px}", shot)
+    _record("sketch.circle", {"center": list(c), "radius_px": r_px}, r)
+    return r
+
+
+async def sketch_line(
+    d: OnshapeDriver,
+    p1: tuple[float, float],
+    p2: tuple[float, float],
+) -> Result:
+    t = await _activate_sketch_tool(d, "sketch.line")
+    if not t.ok:
+        _record("sketch.line", {"p1": list(p1), "p2": list(p2)}, t)
+        return t
+    pt1 = await _ensure_viewport_coords(d, p1)
+    pt2 = await _ensure_viewport_coords(d, p2)
+    await d.click(*pt1)
+    await asyncio.sleep(0.05)
+    await d.click(*pt2)
+    await asyncio.sleep(0.05)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_line.png")
+    r = Result(True, f"line {pt1} -> {pt2}", shot)
+    _record("sketch.line", {"p1": list(pt1), "p2": list(pt2)}, r)
+    return r
+
+
+async def sketch_dimension(
+    d: OnshapeDriver,
+    entity_xy: tuple[float, float],
+    label_xy: tuple[float, float],
+    value_mm: float | str,
+) -> Result:
+    """Add or set a dimension. Click the entity at `entity_xy`, place the
+    dimension label at `label_xy`, then type the new value + Enter.
+
+    This is the workhorse of the "make it 5x5" workflow. Draw any
+    rectangle, then call this twice (once for each side) with the
+    target mm value. The LLM doesn't need to know the px-to-mm ratio
+    because Onshape's solver does the conversion.
+    """
+    t = await _activate_sketch_tool(d, "sketch.dimension")
+    if not t.ok:
+        return t
+    await asyncio.sleep(0.4)
+    e_xy = await _ensure_viewport_coords(d, entity_xy)
+    l_xy = await _ensure_viewport_coords(d, label_xy)
+    # Click the entity (line/edge/circle) to dimension
+    await d.page.mouse.move(*e_xy)
+    await asyncio.sleep(0.15)
+    await d.page.mouse.click(*e_xy)
+    await asyncio.sleep(0.4)
+    # Click where to place the dimension label
+    await d.page.mouse.move(*l_xy)
+    await asyncio.sleep(0.15)
+    await d.page.mouse.click(*l_xy)
+    await asyncio.sleep(0.4)
+    # Type the new value into input.os-canvas-text-edit if present or directly
+    val_str = f"{value_mm} mm" if isinstance(value_mm, (int, float)) else str(value_mm)
+    dim_input = d.page.locator("input.os-canvas-text-edit")
+    if await dim_input.count() > 0:
+        await dim_input.first.fill(val_str)
+        await asyncio.sleep(0.1)
+        await d.page.keyboard.press("Enter")
+        await asyncio.sleep(0.4)
+    else:
+        await d.type_text(val_str)
+        await asyncio.sleep(0.1)
+        await d.press_key("Enter")
+        await asyncio.sleep(0.4)
+    # Esc to drop the dimension tool, stay in sketch
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_dimension.png")
+    r = Result(
+        True,
+        f"dimensioned {val_str} at {e_xy}",
+        shot,
+        {"value": val_str},
+    )
+    _record(
+        "sketch.dimension",
+        {"entity_xy": list(e_xy), "label_xy": list(l_xy), "value": val_str},
+        r,
+    )
+    return r
+
+
+async def sketch_equal(d: OnshapeDriver, *entity_xys: tuple[float, float]) -> Result:
+    """Apply the Equal constraint to make two or more entities the same size.
+
+    Workflow: activate Equal tool, click each entity in turn, press Esc.
+    The LLM passes N coordinates (each on an entity to be made equal).
+    """
+    if len(entity_xys) < 2:
+        return Result(False, "sketch.equal needs at least 2 entities")
+    t = await _activate_sketch_tool(d, "sketch.equal")
+    if not t.ok:
+        return t
+    await asyncio.sleep(0.4)
+    for xy in entity_xys:
+        pt = await _ensure_viewport_coords(d, xy)
+        await d.page.mouse.move(*pt)
+        await asyncio.sleep(0.15)
+        await d.page.mouse.click(*pt)
+        await asyncio.sleep(0.3)
+    await d.press_key("Escape")
+    await asyncio.sleep(0.4)
+    shot = await d.screenshot("sketch_equal.png")
+    r = Result(True, f"equal across {len(entity_xys)} entities", shot)
+    _record("sketch.equal", {"entities": [list(xy) for xy in entity_xys]}, r)
+    return r
+
+
+async def sketch_arc(
+    d: OnshapeDriver,
+    p1: tuple[float, float],
+    p2: tuple[float, float],
+    radius_pt: tuple[float, float] | None = None,
+) -> Result:
+    """Create a 3-point arc from p1 to p2 passing through radius_pt."""
+    t = await _activate_sketch_tool(d, "sketch.arc")
+    if not t.ok:
+        return t
+    pt1 = await _ensure_viewport_coords(d, p1)
+    pt2 = await _ensure_viewport_coords(d, p2)
+    if radius_pt is not None:
+        pt3 = await _ensure_viewport_coords(d, radius_pt)
+    else:
+        # Default arc bulge perpendicular to chord
+        mx, my = (pt1[0] + pt2[0]) / 2.0, (pt1[1] + pt2[1]) / 2.0
+        pt3 = (mx, my - 30.0)
+    await d.click(*pt1)
+    await asyncio.sleep(0.1)
+    await d.click(*pt2)
+    await asyncio.sleep(0.1)
+    await d.click(*pt3)
+    await asyncio.sleep(0.1)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_arc.png")
+    r = Result(True, f"arc {pt1} -> {pt2} through {pt3}", shot)
+    _record("sketch.arc", {"p1": list(pt1), "p2": list(pt2), "radius_pt": list(pt3)}, r)
+    return r
+
+
+async def sketch_polygon(
+    d: OnshapeDriver,
+    center: tuple[float, float] | None = None,
+    radius: float = 60.0,
+    sides: int = 6,
+    circumscribed: bool = False,
+) -> Result:
+    """Draw an inscribed or circumscribed polygon."""
+    tool_name = "sketch.polygon_circumscribed" if circumscribed else "sketch.polygon_inscribed"
+    t = await _activate_sketch_tool(d, tool_name)
+    if not t.ok:
+        t = await _activate_sketch_tool(d, "sketch.polygon")
+    if not t.ok:
+        return t
+    cx, cy = await get_canvas_origin(d)
+    c = await _ensure_viewport_coords(d, center) if center is not None else (cx, cy)
+    r_px = _parse_dim_px(radius, default_px=60.0)
+    await d.click(*c)
+    await asyncio.sleep(0.15)
+    await d.click(c[0] + r_px, c[1])
+    await asyncio.sleep(0.2)
+    # Type number of sides
+    await d.type_text(str(int(sides)))
+    await asyncio.sleep(0.1)
+    await d.press_key("Enter")
+    await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_polygon.png")
+    r = Result(True, f"{sides}-sided polygon at {c} r={r_px}", shot)
+    _record("sketch.polygon", {"center": list(c), "radius": r_px, "sides": sides}, r)
+    return r
+
+
+async def sketch_spline(d: OnshapeDriver, points: list[tuple[float, float]]) -> Result:
+    """Draw a spline passing through a sequence of points."""
+    if len(points) < 2:
+        return Result(False, "sketch.spline requires at least 2 points")
+    t = await _activate_sketch_tool(d, "sketch.spline")
+    if not t.ok:
+        return t
+    pts = [await _ensure_viewport_coords(d, p) for p in points]
+    for pt in pts:
+        await d.click(*pt)
+        await asyncio.sleep(0.15)
+    await d.double_click(*pts[-1])
+    await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_spline.png")
+    r = Result(True, f"spline through {len(pts)} points", shot)
+    _record("sketch.spline", {"points": [list(p) for p in pts]}, r)
+    return r
+
+
+async def sketch_point(d: OnshapeDriver, pt: tuple[float, float]) -> Result:
+    """Place a single sketch point at coordinate pt."""
+    t = await _activate_sketch_tool(d, "sketch.point")
+    if not t.ok:
+        return t
+    p = await _ensure_viewport_coords(d, pt)
+    await d.click(*p)
+    await asyncio.sleep(0.1)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_point.png")
+    r = Result(True, f"point at {p}", shot)
+    _record("sketch.point", {"pt": list(p)}, r)
+    return r
+
+
+async def sketch_text(
+    d: OnshapeDriver,
+    corner1: tuple[float, float],
+    corner2: tuple[float, float],
+    text: str,
+) -> Result:
+    """Draw a text box from corner1 to corner2 and enter text."""
+    t = await _activate_sketch_tool(d, "sketch.text")
+    if not t.ok:
+        return t
+    c1 = await _ensure_viewport_coords(d, corner1)
+    c2 = await _ensure_viewport_coords(d, corner2)
+    await d.click(*c1)
+    await asyncio.sleep(0.1)
+    await d.click(*c2)
+    await asyncio.sleep(0.3)
+    # Fill in the text in the dialog
+    textarea = d.page.locator("textarea.os-text-editor-input, textarea")
+    if await textarea.count() > 0:
+        await textarea.first.fill(text)
+        await asyncio.sleep(0.1)
+        ok_btn = d.page.locator(".ns-dialog-button-ok, .button-ok").first
+        if await ok_btn.count() > 0:
+            await ok_btn.click()
+        else:
+            await d.press_key("Enter")
+    else:
+        await d.type_text(text)
+        await d.press_key("Enter")
+    await asyncio.sleep(0.3)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_text.png")
+    r = Result(True, f"text '{text}' at {c1}->{c2}", shot)
+    _record("sketch.text", {"corner1": list(c1), "corner2": list(c2), "text": text}, r)
+    return r
+
+
+async def sketch_use(d: OnshapeDriver, pt: tuple[float, float]) -> Result:
+    """Project existing 3D model geometry or sketch curve at pt onto sketch plane."""
+    t = await _activate_sketch_tool(d, "sketch.use")
+    if not t.ok:
+        return t
+    p = await _ensure_viewport_coords(d, pt)
+    await d.click(*p)
+    await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_use.png")
+    r = Result(True, f"projected geometry at {p}", shot)
+    _record("sketch.use", {"pt": list(p)}, r)
+    return r
+
+
+async def sketch_construction(d: OnshapeDriver, pt: tuple[float, float] | None = None) -> Result:
+    """Toggle construction mode or convert entity at pt to construction geometry ('q')."""
+    if pt is not None:
+        p = await _ensure_viewport_coords(d, pt)
+        await d.click(*p)
+        await asyncio.sleep(0.15)
+        await d.press_chord("q")
+        await asyncio.sleep(0.15)
+        await d.press_key("Escape")
+        shot = await d.screenshot("sketch_construction.png")
+        r = Result(True, f"converted entity at {p} to construction", shot)
+        _record("sketch.construction", {"pt": list(p)}, r)
+        return r
+    await d.press_chord("q")
+    await asyncio.sleep(0.15)
+    shot = await d.screenshot("sketch_construction.png")
+    r = Result(True, "toggled construction mode", shot)
+    _record("sketch.construction", {}, r)
+    return r
+
+
+async def sketch_fillet(
+    d: OnshapeDriver,
+    vertex_xy: tuple[float, float],
+    radius_mm: float | str = 5.0,
+) -> Result:
+    """Create a 2D sketch fillet at vertex_xy with radius_mm."""
+    t = await _activate_sketch_tool(d, "sketch.fillet")
+    if not t.ok:
+        return t
+    v = await _ensure_viewport_coords(d, vertex_xy)
+    await d.click(*v)
+    await asyncio.sleep(0.3)
+    val_str = f"{radius_mm} mm" if isinstance(radius_mm, (int, float)) else str(radius_mm)
+    dim_input = d.page.locator("input.os-canvas-text-edit")
+    if await dim_input.count() > 0:
+        await dim_input.first.fill(val_str)
+        await asyncio.sleep(0.1)
+        await d.press_key("Enter")
+    else:
+        await d.type_text(val_str)
+        await d.press_key("Enter")
+    await asyncio.sleep(0.3)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_fillet.png")
+    r = Result(True, f"fillet {val_str} at {v}", shot)
+    _record("sketch.fillet", {"vertex": list(v), "radius": val_str}, r)
+    return r
+
+
+async def sketch_chamfer(
+    d: OnshapeDriver,
+    vertex_xy: tuple[float, float],
+    distance_mm: float | str = 5.0,
+) -> Result:
+    """Create a 2D sketch chamfer at vertex_xy with distance_mm."""
+    t = await _activate_sketch_tool(d, "sketch.chamfer")
+    if not t.ok:
+        return t
+    v = await _ensure_viewport_coords(d, vertex_xy)
+    await d.click(*v)
+    await asyncio.sleep(0.3)
+    val_str = f"{distance_mm} mm" if isinstance(distance_mm, (int, float)) else str(distance_mm)
+    dim_input = d.page.locator("input.os-canvas-text-edit")
+    if await dim_input.count() > 0:
+        await dim_input.first.fill(val_str)
+        await asyncio.sleep(0.1)
+        await d.press_key("Enter")
+    else:
+        await d.type_text(val_str)
+        await d.press_key("Enter")
+    await asyncio.sleep(0.3)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_chamfer.png")
+    r = Result(True, f"chamfer {val_str} at {v}", shot)
+    _record("sketch.chamfer", {"vertex": list(v), "distance": val_str}, r)
+    return r
+
+
+async def sketch_trim(d: OnshapeDriver, entity_xy: tuple[float, float]) -> Result:
+    """Trim a sketch curve back to intersections by clicking it."""
+    t = await _activate_sketch_tool(d, "sketch.trim")
+    if not t.ok:
+        return t
+    p = await _ensure_viewport_coords(d, entity_xy)
+    await d.click(*p)
+    await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_trim.png")
+    r = Result(True, f"trimmed at {p}", shot)
+    _record("sketch.trim", {"entity": list(p)}, r)
+    return r
+
+
+async def sketch_extend(d: OnshapeDriver, endpoint_xy: tuple[float, float]) -> Result:
+    """Extend a sketch curve to boundary by clicking its endpoint."""
+    t = await _activate_sketch_tool(d, "sketch.extend")
+    if not t.ok:
+        return t
+    p = await _ensure_viewport_coords(d, endpoint_xy)
+    await d.click(*p)
+    await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_extend.png")
+    r = Result(True, f"extended at {p}", shot)
+    _record("sketch.extend", {"endpoint": list(p)}, r)
+    return r
+
+
+async def sketch_split(d: OnshapeDriver, entity_xy: tuple[float, float]) -> Result:
+    """Split a sketch curve at coordinate."""
+    t = await _activate_sketch_tool(d, "sketch.split")
+    if not t.ok:
+        return t
+    p = await _ensure_viewport_coords(d, entity_xy)
+    await d.click(*p)
+    await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_split.png")
+    r = Result(True, f"split at {p}", shot)
+    _record("sketch.split", {"entity": list(p)}, r)
+    return r
+
+
+async def sketch_offset(
+    d: OnshapeDriver,
+    entity_xy: tuple[float, float],
+    distance_mm: float | str = 5.0,
+    side_xy: tuple[float, float] | None = None,
+) -> Result:
+    """Offset selected curve by distance_mm."""
+    t = await _activate_sketch_tool(d, "sketch.offset")
+    if not t.ok:
+        return t
+    p = await _ensure_viewport_coords(d, entity_xy)
+    await d.click(*p)
+    await asyncio.sleep(0.2)
+    if side_xy is not None:
+        s = await _ensure_viewport_coords(d, side_xy)
+        await d.click(*s)
+    else:
+        await d.click(p[0] + 20.0, p[1] + 20.0)
+    await asyncio.sleep(0.2)
+    val_str = f"{distance_mm} mm" if isinstance(distance_mm, (int, float)) else str(distance_mm)
+    dim_input = d.page.locator("input.os-canvas-text-edit")
+    if await dim_input.count() > 0:
+        await dim_input.first.fill(val_str)
+        await asyncio.sleep(0.1)
+        await d.press_key("Enter")
+    else:
+        await d.type_text(val_str)
+        await d.press_key("Enter")
+    await asyncio.sleep(0.3)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_offset.png")
+    r = Result(True, f"offset {val_str} at {p}", shot)
+    _record("sketch.offset", {"entity": list(p), "distance": val_str}, r)
+    return r
+
+
+async def sketch_slot(
+    d: OnshapeDriver,
+    p1: tuple[float, float],
+    p2: tuple[float, float],
+    radius_px: float = 20.0,
+) -> Result:
+    """Create a sketch slot along line from p1 to p2."""
+    t = await _activate_sketch_tool(d, "sketch.slot")
+    if not t.ok:
+        return t
+    pt1 = await _ensure_viewport_coords(d, p1)
+    pt2 = await _ensure_viewport_coords(d, p2)
+    await d.click(*pt1)
+    await asyncio.sleep(0.1)
+    await d.click(*pt2)
+    await asyncio.sleep(0.1)
+    await d.click(pt2[0] + radius_px, pt2[1])
+    await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_slot.png")
+    r = Result(True, f"slot {pt1} -> {pt2}", shot)
+    _record("sketch.slot", {"p1": list(pt1), "p2": list(pt2)}, r)
+    return r
+
+
+async def sketch_mirror(
+    d: OnshapeDriver,
+    centerline_xy: tuple[float, float],
+    *entity_xys: tuple[float, float],
+) -> Result:
+    """Mirror entities across a centerline."""
+    if not entity_xys:
+        return Result(False, "sketch.mirror requires at least 1 entity to mirror")
+    t = await _activate_sketch_tool(d, "sketch.mirror")
+    if not t.ok:
+        return t
+    cl = await _ensure_viewport_coords(d, centerline_xy)
+    await d.click(*cl)
+    await asyncio.sleep(0.3)
+    for xy in entity_xys:
+        e = await _ensure_viewport_coords(d, xy)
+        await d.click(*e)
+        await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot("sketch_mirror.png")
+    r = Result(True, f"mirrored {len(entity_xys)} entities across {cl}", shot)
+    _record("sketch.mirror", {"centerline": list(cl), "entities": [list(e) for e in entity_xys]}, r)
+    return r
+
+
+async def sketch_constrain(
+    d: OnshapeDriver,
+    constraint_type: str,
+    *entity_xys: tuple[float, float],
+) -> Result:
+    """Apply any geometric constraint across selected entities."""
+    c_type = constraint_type.lower().replace("constraint.", "").strip()
+    tool_key = f"constraint.{c_type}"
+    t = await _activate_sketch_tool(d, tool_key)
+    if not t.ok:
+        return t
+    await asyncio.sleep(0.2)
+    for xy in entity_xys:
+        pt = await _ensure_viewport_coords(d, xy)
+        await d.page.mouse.move(*pt)
+        await asyncio.sleep(0.1)
+        await d.page.mouse.click(*pt)
+        await asyncio.sleep(0.2)
+    await d.press_key("Escape")
+    shot = await d.screenshot(f"constraint_{c_type}.png")
+    r = Result(True, f"constraint {c_type} on {len(entity_xys)} entities", shot)
+    _record(tool_key, {"entities": [list(e) for e in entity_xys]}, r)
+    return r
+
+
+async def sketch_exit(d: OnshapeDriver, commit: bool = True, **_kw) -> Result:
+    """Exit and accept (or cancel) the active sketch."""
+    before = await d.screenshot("sketch_exit_before.png")
+    if commit:
+        # Click green checkmark button on dialog
+        ok_btn = d.page.locator(".ns-dialog-button-ok, .button-ok").first
+        if await ok_btn.count() > 0:
+            await ok_btn.click()
+        else:
+            await d.click(424.0, 93.0)
+        await asyncio.sleep(0.5)
+        await d.press_chord("Shift", "Enter")
+    else:
+        cancel_btn = d.page.locator(".ns-dialog-button-cancel, .button-cancel").first
+        if await cancel_btn.count() > 0:
+            await cancel_btn.click()
+        else:
+            await d.press_key("Escape")
+    await asyncio.sleep(0.5)
+    await d.press_key("Escape")
+    await asyncio.sleep(0.5)
+    after = await d.screenshot("sketch_exit_after.png")
+    r = Result(
+        True, "exit sketch", after, {"before": str(before), "after": str(after), "commit": commit}
+    )
+    _record("sketch.exit", {"commit": commit}, r)
+    return r
+
+
+# Feature tools
+
+
+async def _select_latest_sketch(d: OnshapeDriver) -> bool:
+    """Click the most recent sketch in Onshape's feature tree so the
+    extrude tool knows what region to use. Returns True if a sketch was
+    selected, False otherwise.
+
+    When the doc has multiple sketches, pressing E with nothing selected
+    picks nothing and Onshape shows "Select face or sketch region to
+    extrude". Clicking the latest sketch in the tree pre-selects it.
+    """
+    try:
+        clicked = await d.page.evaluate(
+            """() => {
+                // Feature tree rows. Onshape uses a few different class
+                // names across versions; grab anything that looks like
+                // a tree node containing a Sketch label.
+                const candidates = document.querySelectorAll(
+                    '[class*="feature-tree"] [class*="item"], ' +
+                    '[class*="FeatureTree"] [class*="item"], ' +
+                    '[data-test*="feature-tree"] [class*="row"]'
+                );
+                let best = null;
+                let bestNum = -1;
+                for (const el of candidates) {
+                    const t = (el.textContent || '').trim();
+                    const m = t.match(/^Sketch\\s*(\\d+)/i);
+                    if (m) {
+                        const n = parseInt(m[1], 10);
+                        if (n > bestNum) { bestNum = n; best = el; }
+                    }
+                }
+                if (best) { best.click(); return true; }
+                return false;
+            }"""
+        )
+        if clicked:
+            await asyncio.sleep(0.4)
+        return bool(clicked)
+    except Exception:
+        return False
+
+
+async def feature_extrude(d: OnshapeDriver, depth_mm: float | None = None) -> Result:
+    """Extrude a sketch region. depth_mm is a number in millimetres.
+
+    Workflow:
+      1. Click the most recent sketch in the feature tree so the
+         extrude tool knows which region to use. Required when the
+         doc has more than one sketch.
+      2. Activate the extrude tool (E or toolbar).
+      3. Wait for the dialog. Find the depth input, clear it, type the
+         value with "mm" unit, press Enter.
+      4. Click the green checkmark to commit the feature.
+    """
+    # Step 1: pre-select the most recent sketch
+    await _select_latest_sketch(d)
+
+    # Step 2: activate extrude
+    b = binding_for("feature.extrude")
+    if b.keys:
+        await d.press_chord(*b.keys)
+    elif b.toolbar_text:
+        clicked = await d.click_text(b.toolbar_text, timeout_ms=3000)
+        if not clicked:
+            return Result(False, f"feature.extrude: toolbar {b.toolbar_text!r} not found")
+    else:
+        return Result(False, "feature.extrude: no binding")
+    await asyncio.sleep(0.5)  # dialog open animation
+
+    if depth_mm is not None:
+        # Step 3: fill the depth input. Onshape renders the depth field
+        # as an input.os-canvas-text-edit. .fill() clears the field
+        # first, then types the value with the unit suffix so Onshape
+        # doesn't reinterpret it as the default unit (cm).
+        depth_str = f"{depth_mm:g} mm"
+        try:
+            depth_input = d.page.locator("input.os-canvas-text-edit").first
+            if await depth_input.count() > 0:
+                await depth_input.fill(depth_str)
+            else:
+                # Fallback: select all and type.
+                await d.press_chord("Control", "a")
+                await d.type_text(depth_str)
+        except Exception:
+            await d.press_chord("Control", "a")
+            await d.type_text(depth_str)
+        await asyncio.sleep(0.2)
+        await d.press_key("Enter")
+        await asyncio.sleep(0.4)
+
+        # Step 4: commit with the green checkmark. Try aria-label first,
+        # fall back to the hardcoded toolbar position.
+        try:
+            check = d.page.locator(
+                'button[aria-label*="check" i], button[title*="check" i]'
+            ).first
+            if await check.count() > 0:
+                await check.click()
+            else:
+                await d.click(294.0, 105.0)
+        except Exception:
+            await d.click(294.0, 105.0)
+        await asyncio.sleep(0.3)
+        # Some extrude paths need a second confirm. Shift+Enter
+        # dismisses any tooltip without committing the wrong action.
+        await d.press_chord("Shift", "Enter")
+        await asyncio.sleep(0.5)
+
+    shot = await d.screenshot("feature_extrude.png")
+    r = Result(True, f"extrude depth={depth_mm}mm", shot)
+    _record("feature.extrude", {"depth_mm": depth_mm}, r)
+    return r
+
+
+async def feature_fillet(d: OnshapeDriver, radius_mm: float | None = None) -> Result:
+    b = binding_for("feature.fillet")
+    if b.toolbar_text:
+        clicked = await d.click_text(b.toolbar_text, timeout_ms=3000)
+        if not clicked and b.keys:
+            await d.press_chord(*b.keys)
+    elif b.keys:
+        await d.press_chord(*b.keys)
+    else:
+        return Result(False, "feature.fillet: no binding")
+    await asyncio.sleep(0.3)
+    if radius_mm is not None:
+        await d.type_text(str(radius_mm))
+        await d.press_key("Enter")
+        await asyncio.sleep(0.3)
+    shot = await d.screenshot("feature_fillet.png")
+    r = Result(True, f"fillet r={radius_mm}", shot)
+    _record("feature.fillet", {"radius_mm": radius_mm}, r)
+    return r
+
+
+async def feature_chamfer(d: OnshapeDriver, distance_mm: float | None = None) -> Result:
+    b = binding_for("feature.chamfer")
+    if b.toolbar_text is None:
+        return Result(False, "feature.chamfer: no binding")
+    clicked = await d.click_text(b.toolbar_text, timeout_ms=3000)
+    if not clicked:
+        return Result(False, f"feature.chamfer: toolbar {b.toolbar_text!r} not found")
+    await asyncio.sleep(0.3)
+    if distance_mm is not None:
+        await d.type_text(str(distance_mm))
+        await d.press_key("Enter")
+        await asyncio.sleep(0.3)
+    shot = await d.screenshot("feature_chamfer.png")
+    r = Result(True, f"chamfer d={distance_mm}", shot)
+    _record("feature.chamfer", {"distance_mm": distance_mm}, r)
+    return r
+
+
+# Selection
+
+
+async def select_face(d: OnshapeDriver, x: float, y: float) -> Result:
+    """Click in the viewport to select a face. Best-effort: the face at
+    that pixel may not be what was intended, so the LLM loop verifies via
+    screenshot."""
+    await d.click(x, y)
+    await asyncio.sleep(0.2)
+    shot = await d.screenshot("select_face.png")
+    r = Result(True, f"clicked ({x},{y})", shot, {"click": [x, y]})
+    _record("select.face", {"x": x, "y": y}, r)
+    return r
+
+
+async def select_edge(d: OnshapeDriver, x: float, y: float) -> Result:
+    await d.click(x, y)
+    await asyncio.sleep(0.2)
+    shot = await d.screenshot("select_edge.png")
+    r = Result(True, f"clicked edge ({x},{y})", shot, {"click": [x, y]})
+    _record("select.edge", {"x": x, "y": y}, r)
+    return r
+
+
+# Global undo and redo
+
+
+async def undo(d: OnshapeDriver) -> Result:
+    b = binding_for("ui.undo")
+    await d.press_chord(*b.keys)  # type: ignore[arg-type]
+    await asyncio.sleep(0.2)
+    shot = await d.screenshot("undo.png")
+    r = Result(True, "undo", shot)
+    _record("ui.undo", {}, r)
+    return r
+
+
+async def redo(d: OnshapeDriver) -> Result:
+    b = binding_for("ui.redo")
+    await d.press_chord(*b.keys)  # type: ignore[arg-type]
+    await asyncio.sleep(0.2)
+    shot = await d.screenshot("redo.png")
+    r = Result(True, "redo", shot)
+    _record("ui.redo", {}, r)
+    return r
+
+
+async def wait(d: OnshapeDriver, seconds: float = 1.0) -> Result:
+    """No-op pause. Useful when the LLM wants to let a dialog animation
+    finish, or just look at the current state again on the next step."""
+    await asyncio.sleep(max(0.0, seconds))
+    shot = await d.screenshot("wait.png")
+    r = Result(True, f"waited {seconds}s", shot)
+    _record("ui.wait", {"seconds": seconds}, r)
+    return r
+
+
+async def screenshot_only(d: OnshapeDriver, name: str = "agent.png") -> Result:
+    """Bare screenshot without any other action. Lets the LLM re-observe
+    the viewport without doing anything else."""
+    shot = await d.screenshot(name)
+    r = Result(True, f"screenshot {name}", shot)
+    _record("screenshot", {"name": name}, r)
+    return r
+
+
+async def doc_open(d: OnshapeDriver, url: str) -> Result:
+    """Navigate to a specific Onshape document URL. Pass either a full
+    URL or a `d/<docId>/e/<elementId>` path. Usually elementId is a
+    Part Studio — if the document has one, deep-link to it directly.
+    """
+    if not url:
+        return Result(False, "doc.open: missing url")
+    full = url if url.startswith("http") else f"https://cad.onshape.com/{url.lstrip('/')}"
+    await d.open(full)
+    shot = await d.screenshot("doc_open.png")
+    r = Result(True, f"opened {full}", shot, {"url": full})
+    _record("doc.open", {"url": full}, r)
+    return r
+
+
+async def doc_new(d: OnshapeDriver) -> Result:
+    """Click the Onshape "Create" / new document button. Lands in a fresh
+    Part Studio, which is where sketch + feature tools work.
+    """
+    try:
+        # Click Create dropdown button at top-left
+        await d.click(75, 70)
+        await asyncio.sleep(0.5)
+        # Click "Document..." item
+        await d.click(75, 110)
+        await asyncio.sleep(1.0)
+        await d.type_text("PartStudio")
+        await asyncio.sleep(0.2)
+        await d.press_key("Enter")
+        await d.page.wait_for_url("**/documents/**/e/**", timeout=30000)
+        await d.wait_for_app()
+    except Exception as e:
+        return Result(False, f"doc.new failed: {e}")
+    shot = await d.screenshot("doc_new.png")
+    r = Result(True, "new document", shot)
+    _record("doc.new", {}, r)
+    return r

src/onshape_mcp/vision.py

@@ -0,0 +1,240 @@
+"""Gemini web client. Cookie-auth, no API key. Cookie file is gitignored
+(see SECURITY.md). Cookie file format: {"secure_1psid": ..., "secure_1psidts": ...}.
+
+I tried to keep the wrapper thin. The `gemini-webapi` package handles the
+auth dance but its surface shifts often, so pin and verify on every
+install.
+
+The library supports two cookie paths: pass them explicitly, or let it
+use browser-cookie3 to read straight from Chrome. The latter is more
+robust because it grabs the full session (PSID, PSIDTS, PSIDCC, plus
+the third-party cookies) and uses the keyring to decrypt. Explicit
+cookies can fail for the multimodal endpoint even when text chat works,
+because the image-upload path validates against more cookies.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+from .config import settings
+
+
+class GeminiWeb:
+    def __init__(
+        self,
+        cookie_file: Path | None = None,
+        model: str | None = None,
+        temporary: bool | None = None,
+        auto_cleanup: bool | None = None,
+    ) -> None:
+        self.cookie_file = (cookie_file or settings.gemini_cookie_file).resolve()
+        self.model = model or settings.gemini_model
+        self.temporary = settings.gemini_temporary_chat if temporary is None else temporary
+        self.auto_cleanup = settings.gemini_auto_cleanup if auto_cleanup is None else auto_cleanup
+        self._client: Any = None
+        self._active_session: Any = None
+        self.created_chat_ids: set[str] = set()
+
+    def _has_cookie_file(self) -> bool:
+        """True if the cookie file exists and has the two required values."""
+        if not self.cookie_file.exists():
+            return False
+        try:
+            data = json.loads(self.cookie_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return False
+        psid = data.get("secure_1psid") or data.get("__Secure-1PSID")
+        psidts = data.get("secure_1psidts") or data.get("__Secure-1PSIDTS")
+        return bool(psid and psidts)
+
+    async def _ensure_client(self) -> None:
+        if self._client is not None:
+            return
+        try:
+            from gemini_webapi import GeminiClient  # type: ignore
+        except ImportError as e:  # pragma: no cover
+            raise RuntimeError("Install gemini-webapi: `pip install gemini-webapi`") from e
+
+        # Prefer letting the library use browser-cookie3 directly. It
+        # grabs the full Chrome session (PSID, PSIDTS, PSIDCC, third-party
+        # cookies) and decrypts via the keyring, which is the path that
+        # works reliably for the multimodal (image upload) endpoint.
+        try:
+            client = GeminiClient(None, None, model=self.model)
+            await client.init(timeout=15)
+            self._client = client
+            return
+        except Exception as e:
+            print(f"[vision] live browser session init note ({e}); trying cookie file")
+
+        # Fallback to explicit cookie file if browser-cookie3 could not read Chrome
+        if self._has_cookie_file():
+            data = json.loads(self.cookie_file.read_text(encoding="utf-8"))
+            psid = data.get("secure_1psid") or data.get("__Secure-1PSID")
+            psidts = data.get("secure_1psidts") or data.get("__Secure-1PSIDTS")
+            self._client = GeminiClient(psid, psidts, model=self.model)
+            await self._client.init(timeout=30)
+            return
+
+        raise RuntimeError("No valid Gemini credentials found (neither live Chrome nor cookie file).")
+
+    async def _refresh_cookies_from_chrome(self) -> bool:
+        """Re-extract Gemini cookies from the user's real Chrome. The
+        gemini-webapi library doesn't refresh its session automatically
+        and the cookies can go stale between calls. This pulls fresh
+        ones and overwrites the cookie file.
+        """
+        try:
+            import browser_cookie3
+        except ImportError:
+            return False
+        try:
+            cj = browser_cookie3.chrome(domain_name="google.com")
+        except Exception as e:
+            print(f"[vision] could not read Chrome cookies: {e}")
+            return False
+        psid = psidts = None
+        for c in cj:
+            if c.name == "__Secure-1PSID":
+                psid = c.value
+            elif c.name == "__Secure-1PSIDTS":
+                psidts = c.value
+        if not (psid and psidts):
+            return False
+        self.cookie_file.parent.mkdir(parents=True, exist_ok=True)
+        self.cookie_file.write_text(
+            json.dumps(
+                {
+                    "secure_1psid": psid,
+                    "secure_1psidts": psidts,
+                    "_note": "refreshed by vision.py",
+                },
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+        return True
+
+    async def new_session(self, temporary: bool | None = None) -> Any:
+        """Create and track a new ChatSession attached to this client."""
+        await self._ensure_client()
+        session = self._client.start_chat()
+        self._session_temporary = self.temporary if temporary is None else temporary
+        self._active_session = session
+        return session
+
+    def get_session(self) -> Any:
+        """Return the active ChatSession, if any."""
+        return self._active_session
+
+    def reset_session(self) -> None:
+        """Clear the active ChatSession."""
+        self._active_session = None
+
+    async def delete_chat(self, cid: str) -> bool:
+        """Delete a specific conversation by chat ID. Returns True if successful."""
+        await self._ensure_client()
+        try:
+            await self._client.delete_chat(cid)
+            self.created_chat_ids.discard(cid)
+            print(f"[vision] deleted chat {cid}")
+            return True
+        except Exception as e:
+            print(f"[vision] failed to delete chat {cid}: {e}")
+            return False
+
+    async def list_chats(self) -> list[Any]:
+        """List all conversations in the user's Gemini account."""
+        await self._ensure_client()
+        try:
+            res = self._client.list_chats()
+            return res or []
+        except Exception as e:
+            print(f"[vision] failed to list chats: {e}")
+            return []
+
+    async def cleanup_created_chats(self) -> int:
+        """Delete all non-temporary chats created and tracked by this instance."""
+        if not self.created_chat_ids or self._client is None:
+            return 0
+        to_delete = list(self.created_chat_ids)
+        deleted = 0
+        for cid in to_delete:
+            if await self.delete_chat(cid):
+                deleted += 1
+        return deleted
+
+    async def ask_with_image(
+        self,
+        prompt: str,
+        image_path: Path,
+        session: Any = None,
+        temporary: bool | None = None,
+        timeout: int = 120,
+    ) -> str:
+        # Try up to 2 times. If the first call hits an "UNAUTHENTICATED"
+        # error, re-extract cookies from Chrome (they go stale) and
+        # re-initialise the client.
+        last_err: Exception | None = None
+        use_temp = (
+            getattr(self, "_session_temporary", self.temporary) if temporary is None else temporary
+        )
+
+        for attempt in range(2):
+            await self._ensure_client()
+            if attempt > 0:
+                chat = self._client.start_chat()
+                self._active_session = chat
+            else:
+                chat = session or self._active_session
+                if chat is None:
+                    chat = self._client.start_chat()
+                    self._active_session = chat
+
+            temp_flag = use_temp
+            try:
+                response = await asyncio.wait_for(
+                    chat.send_message(prompt, files=[str(image_path)], temporary=temp_flag),
+                    timeout=timeout,
+                )
+                cid = getattr(chat, "cid", None)
+                if cid and not temp_flag:
+                    self.created_chat_ids.add(cid)
+                return getattr(response, "text", str(response))
+            except Exception as e:
+                last_err = e
+                if "UNAUTHENTICATED" in str(e) or "Permission" in str(e):
+                    print(f"[vision] auth error on attempt {attempt + 1}: {e}")
+                    try:
+                        await self._client.close()
+                    except Exception:
+                        pass
+                    self._client = None
+                    self._active_session = None
+                    if attempt == 0:
+                        print("[vision] re-extracting cookies from Chrome")
+                        if not await self._refresh_cookies_from_chrome():
+                            print(
+                                "[vision] cookie refresh failed; will retry with whatever we have"
+                            )
+                        continue
+                raise
+        raise last_err if last_err else RuntimeError("vision: unknown failure")
+
+    async def close(self) -> None:
+        if self.auto_cleanup and self.created_chat_ids:
+            try:
+                await self.cleanup_created_chats()
+            except Exception as e:
+                print(f"[vision] error during auto-cleanup: {e}")
+        self._active_session = None
+        if self._client is not None:
+            try:
+                await self._client.close()
+            except Exception:
+                pass
+            self._client = None