Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
height edited later. Give exactly one of `plane` and `face_point`; a point
in the air or on a curved face fails with `invalid_input`.

- **A `deprecated` support level** (#174). A deprecated tool still works;
its description and successful results open "Deprecated: use `<tool>`.",
it is tagged `level:deprecated`, and it is removed at the next major
release. The progress image leaves deprecated tools out of its count.
- **A verb list for tool names**, in the tool description standard: new
tools start with `create_`, `add_`, `get_`, `list_`, `set_` and the rest;
the names registered before it are listed as exceptions.
- **`get_model_info` reports the file's details**: `size_bytes`, `created`
and `modified`, read from the file on disk (null for a document never
saved).
- **`save_file` takes `overwrite`**, and checks a new `file_path` before
SolidWorks is asked: the folder exists and is writable, the extension
matches the document (.sldprt, .sldasm, .slddrw), and no file is there.

### Fixed

Found building the monitor stand demo (#206):
Expand All @@ -45,6 +59,54 @@ Found building the monitor stand demo (#206):
with no reference plane, and its camera turns to an isometric view after
each feature (`--look` in the script).

- **`save_file` keeps a file already at `file_path`** unless `overwrite`
is on, and refuses a path with another document type's extension. Before,
it replaced the file. Saving in place (no `file_path`) is unchanged.

### Deprecated

Each still works until 3.0.0; use the tool named instead (#174):

- `load_part`, `load_assembly`: use `open_model`.
- `save_part`, `save_assembly`: use `save_file` (`pack_and_go_assembly` to
copy an assembly with its referenced parts).
- `calculate_mass_properties`: use `get_mass_properties`.
- `get_file_properties`: use `get_model_info`.
- `add_drawing_view`: use `create_drawing_view`.
- `sketch_tutorial_simple_hole`: no replacement; build the hole with the
sketching and feature tools.

### Removed

33 tools that were registered but never implemented: every call returned
`not_supported` (#174). Clients that listed them only ever got an error.
Why each one went, and what does its job now, is in `openspec/queue.md`
("Removed tools").

- Analysis: `analyze_geometry`, `get_material_properties`.
- Automation: `automation_start_macro_recording`,
`automation_stop_macro_recording`, `batch_process_files`,
`create_template`, `execute_workflow`, `manage_design_table`,
`optimize_performance`. `manage_design_table` was checked live first: on
SolidWorks 2026 the design table is inserted, but SolidWorks can't open it
in Excel to read it and makes no configurations from it.
- Drawing: `add_annotation`.
- Drawing analysis: `analyze_drawing_annotations`,
`analyze_drawing_comprehensive`, `analyze_drawing_dimensions`,
`analyze_drawing_views`, `check_drawing_compliance`,
`generate_drawing_report`, `validate_drawing_completeness`.
- Export: `batch_export`.
- File management: `batch_file_operations`, `convert_file_format`,
`manage_file_properties`.
- Macros: `analyze_macro`, `batch_execute_macros`, `create_macro_library`,
`optimize_macro`, `start_macro_recording`, `stop_macro_recording`.
- Sketching: `tutorial_simple_hole`.
- Templates: `apply_template`, `batch_apply_template`, `extract_template`,
`list_template_library`, `save_to_template_library`.

The seven planned tools left are drawing tools; each names the queue item
that builds them (the drawing pack).

## [2.0.0] - 2026-11-12

### Added
Expand Down
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ When needed (credentials/SolidWorks environment available):

## Adding or Changing a Tool

- Name it with a verb from the [verb list](docs/agents/tool-description-standard.md#tool-names) (`create_`, `add_`, `get_`, `list_`, `set_`, ...).
- Write its docstring to the [tool description standard](docs/agents/tool-description-standard.md): what it does, when to use it, what it needs, what it changes (or "Read-only."), and what it returns.
- Describe `input_data` specifically in `Args:`, and give every input field a `Field(description=...)`.
- Add its title and behaviour hints to `src/solidworks_mcp/tools/tool_hints.py`; registration fails without them.
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@
[![SolidWorks](https://img.shields.io/badge/tested%20on-SolidWorks%202026-red)](https://www.solidworks.com/)
[![Coverage](https://codecov.io/gh/andrewbartels1/SolidworksMCP-python/branch/main/graph/badge.svg)](https://codecov.io/gh/andrewbartels1/SolidworksMCP-python)

Python MCP server for SolidWorks automation with 156 tools, plus an optional agent/prompt-testing layer for AI-assisted workflows.
Python MCP server for SolidWorks automation with 123 tools, plus an optional agent/prompt-testing layer for AI-assisted workflows.

[![155 MCP tools by support level, and how much of the core SolidWorks COM API they reach](docs/assets/progress/progress.svg)](https://andrewbartels1.github.io/SolidworksMCP-python/progress/)
[![115 MCP tools by support level (the 8 deprecated ones not counted), and how much of the core SolidWorks COM API they reach](docs/assets/progress/progress.svg)](https://andrewbartels1.github.io/SolidworksMCP-python/progress/)

<sub>Generated from the code; click it for every tool, its level and why, filterable by level and family.</sub>

Expand All @@ -33,7 +33,7 @@ Python MCP server for SolidWorks automation with 156 tools, plus an optional age
await adapter.create_extrusion(ExtrusionParameters(depth=10))
```

- **An MCP tool server on top of it.** The same calls, exposed as 156 MCP tools, so an agent such as Claude Code can build parts, assemblies and drawings from a description. Each tool carries a support level (stable, beta, experimental or planned), so the agent knows how far to trust it.
- **An MCP tool server on top of it.** The same calls, exposed as 123 MCP tools, so an agent such as Claude Code can build parts, assemblies and drawings from a description. Each tool carries a support level (stable, beta, experimental, planned or deprecated), so the agent knows how far to trust it.

## See it work

Expand Down Expand Up @@ -197,7 +197,7 @@ Each GIF is a live test driving SolidWorks 2026 through the MCP tools, with the

- Windows + SolidWorks COM automation for the main CAD lifecycle.
- Tested on SolidWorks 2026. Earlier versions may work but are untested. To check yours, run `uvx solidworks-mcp-python selftest` with SolidWorks open, then send the result with the [compatibility report form](https://github.com/andrewbartels1/SolidworksMCP-python/issues/new?template=compatibility.yml). The [compatibility page](https://andrewbartels1.github.io/SolidworksMCP-python/compatibility/) lists the releases checked so far.
- Modeling, sketching, drawing, analysis, export, automation, templates, and macro tools.
- Modeling, sketching, drawing, analysis, export, file and engineering-data tools, plus VBA generation and running macros.
- Every tool's support level, and the reason a tool isn't stable yet, is on the [progress page](https://andrewbartels1.github.io/SolidworksMCP-python/progress/).

## Not Yet / Simulated
Expand Down Expand Up @@ -302,7 +302,7 @@ Add this to `%APPDATA%\Code\User\mcp.json`:
}
```

Run **MCP: List Servers** from the Command Palette and start `solidworks`. Its output should end with `Discovered 156 tools` (the count grows as tools are added).
Run **MCP: List Servers** from the Command Palette and start `solidworks`. Its output should end with `Discovered 123 tools` (the count grows as tools are added).

</details>

Expand Down
2 changes: 1 addition & 1 deletion docs/agents/com-api-pitfalls.md
Original file line number Diff line number Diff line change
Expand Up @@ -1095,7 +1095,7 @@ time to release memory and finish background work between documents. Heavy parts
**What to do in a batch loop:**

- **Throttle.** Put a real pause (~10 s worked here) between parts — after `close_model`,
before the next `load_part`. Small parts don't need it; you won't know which are heavy
before the next `open_model`. Small parts don't need it; you won't know which are heavy
up front, so pace the whole loop.
- **Do the heavy files last** and don't retry-storm — if a big part fails its export,
record it and move on rather than reopening it immediately.
Expand Down
6 changes: 3 additions & 3 deletions docs/agents/prompting-tutorials.md
Original file line number Diff line number Diff line change
Expand Up @@ -400,8 +400,8 @@ Check the mass, volume, and centre of gravity for the currently open model.

```json
[
{"tool": "calculate_mass_properties", "args": {}},
{"tool": "get_material_properties", "args": {}}
{"tool": "get_mass_properties", "args": {}},
{"tool": "get_material", "args": {}}
]
```

Expand Down Expand Up @@ -444,4 +444,4 @@ You are an expert SolidWorks drafter operating a SolidWorks MCP server.
| Revolve fails | No axis / wrong axis name | Add centerline in same sketch, name = `"Line1"` |
| Dimension not found | Name mismatch | Check `"D1@FeatureName"` format |
| Export writes 0-byte file | No active document | Open or create a part first |
| Mass = 0 | No material assigned | Call `get_material_properties` to check |
| Mass = 0 | No material assigned | Call `get_material` to check, then `set_material` |
10 changes: 5 additions & 5 deletions docs/agents/sample-models-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ flowchart LR
| **1 – Simple** | Single sketch + one feature | `create_sketch`, `add_rectangle/circle`, `create_extrusion/revolve` |
| **2 – Intermediate** | 2–4 sketches, multiple features, fillets | + `set_dimension`, `add_sketch_constraint`, `create_extrusion` (multi-step) |
| **3 – Advanced** | Lofts, sweeps, multi-body, sheet metal | + `generate_vba_part_modeling`, `execute_macro` |
| **4 – Assembly** | Multiple parts mated together | `create_assembly`, `load_part`, `generate_vba_assembly_insert` |
| **4 – Assembly** | Multiple parts mated together | `create_assembly`, `insert_component`, `add_mate` |

---

Expand Down Expand Up @@ -244,12 +244,12 @@ Create a simple sheet metal bracket:

**Files**: 20+ parts in `Sprinkler/`

The sprinkler is the most complex assembly in the sample set. Use `batch_file_operations` to collect all part paths, then `load_assembly`.
The sprinkler is the most complex assembly in the sample set. Open it with `open_model`; `list_components` lists its parts.

```
1. load_assembly file_path="Sprinkler\Sprinkler.SLDASM"
2. get_file_properties ← read material, revision, descriptions
3. calculate_mass_properties ← total assembly mass
1. open_model file_path="Sprinkler\Sprinkler.SLDASM"
2. get_custom_properties ← read material, revision, descriptions
3. get_mass_properties ← total assembly mass
4. check_interference ← verify no clashes between components
5. export_step file_path="Sprinkler_export.step"
```
Expand Down
72 changes: 62 additions & 10 deletions docs/agents/tool-description-standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,27 +69,79 @@ Some tools have no adapter implementation, so every call returns
sentence: "Not available yet: no adapter implements it, so every call
returns an error with `error_type: "not_supported"`. It is planned for a
future release." Then point to the tool to use instead, if there is one, and
phrase what it would change or return as "once available". The list of these
tools is in `openspec/queue.md`.
phrase what it would change or return as "once available". Its support-level
reason names the queue item in `openspec/queue.md` that builds it.

## Support levels

Add one line to `SUPPORT_LEVELS` in `tools/support_levels.py` for every new
tool; registration fails without it. A tool is `stable` once a live test
calls it and it has no known fault, `beta` when it works on SolidWorks but
has a known fault or covers only part of its COM call, `experimental` when
no live test has checked it, and `planned` when nothing implements it (its
description says "Not available yet"). Below stable, give a one-sentence
reason.

Don't write the level into the docstring: the server opens a beta or
experimental tool's description with "Beta: <reason>" or "Experimental:
<reason>" from the table, adds the same sentence to its successful results as
`warning`, and tags every tool `level:<level>`. After changing a level, run
no live test has checked it, `planned` when nothing implements it (its
description says "Not available yet"), and `deprecated` when another tool
replaces it. Below stable, give a one-sentence reason.

A tool is deprecated, not removed, when it works and a client may call it.
Its entry is `_deprecated("<replacement>")` (or `_deprecated(None)` when
there is none), which records the version; it keeps working until the next
major release, when `tests/integration/test_support_levels.py` fails until
it is removed. Before deprecating a tool, make sure its replacement accepts
everything it did, or that its description names the tool that does the
rest.

Don't write the level into the docstring: the server opens a beta,
experimental or deprecated tool's description with "Beta: <reason>",
"Experimental: <reason>" or "Deprecated: use `<tool>`." from the table, adds
the same sentence to its successful results as `warning`, and tags every tool
`level:<level>`. After changing a level, run
`python -m solidworks_mcp.progress.generate` so the README image and the
[progress page](../progress.md) follow; `tests/integration/test_support_levels.py`
and `test_progress_up_to_date.py` check both.

## Tool names

A tool's name starts with one verb from this list, so an agent can guess a
name and tell two tools apart by name alone. Pick the verb by meaning:

| Verb | Meaning |
| --- | --- |
| `create_` | makes a new document, or a new feature built from a sketch or acting on the whole body (extrusion, rib, hole, shell) |
| `add_` | adds an entity to an open sketch or a drawing, or treats edges or faces of an existing body (fillet, chamfer, draft, thread) |
| `pattern_`, `mirror_` | repeats existing features |
| `sketch_` | an operation on the open sketch's entities (offset, mirror, pattern, convert) |
| `get_` | reads one thing |
| `list_` | reads a collection |
| `set_` | changes one value |
| `open_`, `save_`, `close_`, `export_` | file operations |
| `check_`, `verify_`, `measure_`, `compare_` | read-only checks |

`tests/integration/test_tool_descriptions.py` fails on any other name, except
these, which were registered before the list and are kept so that clients
don't break:

<!-- tool-name-exceptions:start -->
- `activate_document`, `arrange_dimensions`, `auto_center_marks`,
`auto_dimension_view`, `calculate_mass_properties`, `classify_feature_tree`,
`delete_feature`, `discover_solidworks_docs`, `execute_macro`, `exit_sketch`,
`find_related_api_members`
- `generate_drawing_package`, `generate_vba_assembly_insert`,
`generate_vba_assembly_mates`, `generate_vba_batch_export`,
`generate_vba_code`, `generate_vba_drawing_dimensions`,
`generate_vba_drawing_views`, `generate_vba_extrusion`,
`generate_vba_file_operations`, `generate_vba_macro_recorder`,
`generate_vba_part_modeling`, `generate_vba_revolve`
- `insert_bom_table`, `insert_component`, `insert_model_dimensions`,
`load_assembly`, `load_part`, `lookup_api_interface`, `lookup_api_method`,
`pack_and_go_assembly`, `rebuild_model`,
`rename_feature`, `reset_circuit_breaker`
- `search_solidworks_api_help`, `select_face_edges`, `select_feature`,
`suppress_feature`, `undo`, `update_sheet_format`, `update_title_block`
<!-- tool-name-exceptions:end -->

Don't add to the exceptions; name a new tool with a listed verb. When a
deprecated exception is removed, take it off the list too.

## Behaviour hints

Add one line to `TOOL_HINTS` in `tools/tool_hints.py` for every new tool;
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading