solidworks-mcp CLAUDE.md

Repository guidance

Operating rules for automated contributors and maintainers working in this repository.

Project scope

MCP_CAD exposes a constrained MCP interface for controlled SOLIDWORKS automation. The core server is client- and model-provider agnostic.

Safety constraints

1. Design files remain local. Do not upload or commit .sldprt, .sldasm, .slddrw, STEP files, captures derived from private designs, or other user geometry.
2. Use the constrained tool surface. Automation must call predefined, deterministic operations rather than arbitrary SOLIDWORKS API methods.
3. Require explicit approval for model changes. Do not mutate geometry without the user's approval.
4. Protect credentials. Keep API keys in user-controlled configuration; never log, transmit, or commit them.
5. Do not collect design telemetry. Avoid analytics containing model contents, file names, geometry patterns, or derived design data.

Architecture

• src/mcp_cad/server.py defines FastMCP tools and binds them to the module-level client.
• src/mcp_cad/solidworks.py defines the SolidWorksClient Protocol, the in-memory mock, and the Windows pywin32 COM implementation.
• MCP_CAD_USE_MOCK=1 selects the mock for development on systems without SOLIDWORKS.

New geometry behavior should be added end to end: Protocol, mock implementation, COM implementation, then MCP tool. Keep pywin32-specific code out of server.py. Advisory and composite operations may live only in server.py when they do not require a new Protocol method.

The live tool catalog and tool docstrings are authoritative. Tool descriptions consume MCP context on every tools/list, so keep them concise and keep orchestration guidance in repository documentation.

Build discipline

• Prefer the currently open document. Read its state first, and create a new document only when requested or necessary.
• Use millimeters and degrees above the COM boundary. Convert millimeters to meters only inside WinComSolidWorksClient.
• SOLIDWORKS COM mutation is serial. Never run geometry-mutating calls concurrently.
• Issue one mutator at a time unless using an explicit batch or plan runner.
• Treat each mutation as at most once. After a lost or ambiguous response, inspect live state before deciding whether anything should be retried.
• Use receipt.feature_count as the normal post-mutation signal. Perform separate reads when receipts are missing or unexpected.
• Save early and again after verification.
• Prefer reversible suppression or modification over deletion. Do not add destructive behavior casually.
• Reuse an indexed part or edit a driving dimension when either is appropriate; do not rebuild existing geometry unnecessarily.
• Never invent missing dimensions, tolerance classes, materials, or standards. Ask a focused question or report the unresolved requirement.