# SolidWorks MCP — run, test & auto-fix VBA macros

An MCP server that connects to a running **SolidWorks 2022** over COM (pywin32),
runs your VBA macros (or inline VBA), inspects the resulting model, and returns
**structured diagnostics** so Claude can fix errors and re-run until the model
builds clean. It also ships an **API-documentation pipeline** that renders the
JavaScript-only `help.solidworks.com/2022` pages headlessly and extracts the
method/enum facts that keep generated code correct.

Built to pair with the `solidworks-vba` skill: the skill *writes* verified-style
macros; this server *runs, tests and repairs* them.

## How it works

```
Claude (+ solidworks-vba skill)
        │  writes / fixes VBA
        ▼
  run_and_verify ──► COM worker thread (STA) ──► SolidWorks 2022
        │                                              │
        │   ◄── verdict: ran? rebuild errors?  ◄───────┘
        ▼        errored features? VBA error?
   if not success: read errors, regenerate, call again   (Claude-driven loop)
```

- **Inline VBA** is written to a temporary `.swb` and executed with `RunMacro2`
  (SolidWorks compiles `.swb` text on the fly — no `.swp` authoring, no VBA
  trust-access setting needed).
- All COM access runs on **one STA worker thread** (COM objects are
  apartment-bound).
- Generated/automated macros use a **silent log** (`SWMCP_Log`) instead of
  `MsgBox`, and a **dialog watchdog** auto-dismisses stray modal dialogs so a
  macro can never deadlock the server.
- The server never edits your VBA. It returns rich errors; Claude fixes them.

## Session-first fast workflow

Every modeling request should begin with `prepare_modeling_context(request)`.
It performs the complete preflight in one round trip:

1. Detect running SOLIDWORKS processes through their exact ROT monikers.
2. Auto-select the only session, or return the process list when a choice is required.
3. Stop with `action=start_solidworks` when no session is running—nothing is launched silently.
4. Return matching skills, professional design guidance, bundled Cosmon references,
   and local SOLIDWORKS CHM results before any code is generated.
5. Bind every subsequent modeling tool to the selected process.

`sw_list_sessions`, `sw_select_session(process_id)`, and `sw_disconnect_session`
provide explicit control. Execution suppresses graphics/tree churn reversibly,
generated macros rebuild once, verification scans the feature tree once, and
repeated Cosmon searches are served from memory.

## Requirements

- Windows + **SolidWorks 2022** (COM ProgID `SldWorks.Application`).
- **Python 3.10+**.
- A **default part/assembly/drawing template** configured in SolidWorks
  (Tools ▸ Options ▸ Default Templates) — macros abort cleanly if none is set.

## Install

```bash
pip install -e .
python -m playwright install chromium   # one-time, for the docs pipeline
```

## Register with Claude Code

Already registered at user scope during setup:

```bash
claude mcp add solidworks -s user -- C:/Python313/python.exe -m sw_mcp.server
```

Or, for a project-scoped, shareable config, drop a `.mcp.json` in the project
root (see [install/register-mcp.md](install/register-mcp.md)). Confirm with
`claude mcp list` (look for `solidworks: ... ✓ Connected`).

## Tools

**Session and preflight** — `prepare_modeling_context`, `sw_status`,
`sw_list_sessions`, `sw_select_session`, `sw_disconnect_session`

**Professional design knowledge (proactive)**
- `get_design_guidance(query)` — **call this BEFORE modeling.** Returns the
  matching professional *archetype recipe* (ordered feature sequence,
  design-intent practices, key dimensions), the relevant universal design
  principles, and — for tolerancing queries — a GD&T reference. Distilled from
  real SolidWorks tutorials (`transcripts.txt`) so the build tools produce a real
  engineered component instead of a bare block or cylinder.
- `list_design_recipes()` — the available archetypes (bearing, engine, bottle,
  manifold, revolved housing, mounting plate).
  See [`DESIGN_PLAYBOOK.md`](src/sw_mcp/resources/knowledge/DESIGN_PLAYBOOK.md).

**Execute & verify**
- `run_macro(path, module, procedure)` — run an existing `.swp`/`.swb`.
- `run_vba(code, procedure, module)` — run an inline VBA string.
- `run_and_verify(code | macro_path, …)` — run → rebuild → scan → one verdict.
  **The auto-fix-loop primitive.**

**Diagnostics** — `rebuild_model`, `get_build_errors`, `get_feature_tree`,
`get_mass_properties`, `get_bounding_box`, `capture_screenshot`

**Documents** — `new_document`, `open_model`, `save_model`, `close_model`,
`export_file` (STEP/IGES/STL/X_T/PDF/PNG by extension)

**Feature generators** — single-feature *primitives* (verified-style VBA, each
built → run → rebuilt → error-scanned). These are building blocks and smoke
tests, **not** finished parts; a professional component is composed from them
(plus inline `run_vba`) following the recipe from `get_design_guidance`:
`create_extrusion`, `create_cylinder`, `create_fillet`, `create_chamfer`,
`create_shell`, `create_draft`, `create_rib` (L-bracket + gusset),
`create_revolve` (tube), `create_sweep` (swept groove), `create_loft` (lofted cut),
`create_hole_wizard` (metric counterbore), `create_thread` (real cut thread),
`create_spring` (helix + sweep), `create_linear_pattern`, `create_mirror`,
`create_circular_pattern`, `create_assembly` (2 components fully mated).
**Surface modeling:** `create_surface_extrude`, `create_surface_planar`,
`create_surface_revolve`, `create_surface_thicken` (surface→solid).
**Sheet metal:** `create_sheet_base_flange` (flat plate), `create_sheet_lbracket`
(bent, real bend). Extend by adding builders to `feature_tools.py` (see below).
Pattern variants not yet given a one-call tool (curve/sketch/table/fill), sheet-metal
edge flange/hem/miter, and any other feature are fully buildable via `run_vba` + the
`solidworks-vba` skill + the auto-fix loop.

**Self-improving knowledge base** — `learn_rule`, `list_rules`. Every fixed error
becomes a persistent rule (`resources/knowledge/rules.json`, human-readable
`LESSONS.md`). On failure, `run_and_verify` returns `suggested_fixes` matched from
past rules, so the same mistake is never solved twice.

**API docs** — `docs_lookup_method(interface, method)`,
`docs_lookup_enum(enum_name)`, `docs_get(url)`. Read the `remarks` field — it
holds the selection-mark/precondition details that separate working from
crashing code.

**Cosmon-compatible resources and skills** —
`engineering_resources_status`, `list_engineering_resources`,
`search_engineering_resources`, `get_engineering_resource`, `list_skills`,
`get_skill`, `create_skill`, `update_skill`, `delete_skill`, `import_skill`.
The server bundles Cosmon's complete SOLIDWORKS documentation payload—including
the large feature/function databases—plus C# templates, persistent-service
source, and all 12 packaged skills. The installed Cosmon resources remain a
fallback source. Set `COSMON_RESOURCES_DIR` for a non-default Cosmon location
and `SW_MCP_SKILLS_DIR` for editable skill overrides.

## The auto-fix loop

1. Claude writes a macro (via the `solidworks-vba` skill) and calls
   `run_and_verify`.
2. The verdict comes back: `{success, ran, run_error, log[], log_errors[],
   errors[], errored_features[], suppressed_features[], feature_count}`.
3. If `success == false`, Claude reads `log_errors`/`errors` (and looks up the
   exact API via `docs_lookup_method`), regenerates the corrected VBA, and calls
   `run_and_verify` again — until `success == true`.

## Designing professional parts (not bare blocks)

The build loop only checks that geometry *rebuilds* — left alone, the simplest
shape that builds clean is a block or a cylinder. To get a real engineered
component, design intent has to come from somewhere. That is the
`get_design_guidance` layer (`design_library.py`, surfaced from the tutorial
transcripts):

1. Call `get_design_guidance("<part description>")` (e.g. `"deep-groove ball
   bearing"`, `"mounting base plate with bolt circle"`, `"hollow exhaust
   manifold"`, `"shaft tolerance / GD&T"`).
2. Follow the returned **feature sequence** and **design-intent** notes — revolve
   about a centerline, fully-define sketches, locate holes on a construction PCD
   and circular-pattern them, break every edge, surface-then-thicken for
   thin-wall parts, combine-then-shell for hollow ones, fix-first then
   fully-constrain for assemblies, apply GD&T to functional features.
3. Emit the VBA (the feature primitives below, or inline `run_vba`) and drive it
   through `run_and_verify` until `success == true`.

The recipes are an *index of archetypes*; the **principles** apply to every part.
The same knowledge is mirrored as reactive rules in `rules.json`, so a related
build error also surfaces the relevant professional practice as a
`suggested_fix`.

## Writing more feature generators

Generators emit VBA in the verified `solidworks-vba` style and run through
`run_and_verify`. Two **non-negotiable rules** for inline `.swb` code (learned
the hard way — see `src/sw_mcp/vba/helpers.vba`):

1. **Never test an API boolean with bitwise `If Not x`.** In an on-the-fly
   `.swb`, API `VARIANT_BOOL` returns arrive as `+1`, and VBA's `Not` is
   bitwise (`Not 1 = -2`, truthy). Always write `If x = False Then`. Object
   checks (`Is Nothing`) are fine.
2. **`Create*Rectangle` returns a Variant array, not an object.** Capture with
   `Dim v As Variant: v = ...` and check `IsArray(v)` — never `Set seg = …`
   (raises run-time error 424).

Add a `build_<feature>()` to `feature_tools.py` (reuse `assemble_part_macro`)
and a thin `@mcp.tool()` wrapper in `server.py`.

## Diagnostic scripts

`scripts/` contains the standalone spikes used to validate each layer
(`spike_connect`, `spike_runmacro`, `spike_build`, `spike_autofix`, …). They are
handy for debugging the COM link without going through the MCP transport.