# MCP_CAD

A SolidWorks-resident AI copilot for Mexican autoparts manufacturing PYMEs.

The product gives a junior, Spanish-speaking CAD designer an AI assistant that drives SolidWorks through chat — assembly mating, configurations, sketching, extrusion, edge-break — using a constrained, deterministic toolset that runs on the customer's own machine.

**Positioning:** Spanish, on-prem, SolidWorks, PYME — the four-word frame that separates this from every other AI/CAD product.

---

## Status

Pre-product, in structured discovery and customer validation. Self-funded.

> **Direction (June 2026 pivot).** From-scratch generation of complex parts — from images (PDF→CAD, retired) *and* from prompts — hit a hard model-capability ceiling. So the product now invests in **task/batch automation + contextual reuse**, routing *around* that ceiling, delivered through a constrained, auditable, on-prem surface (a stronger enterprise story than a cloud + arbitrary-macro approach). See [`docs/AUTOMATION_LANE.md`](docs/AUTOMATION_LANE.md). Single-part generation from prompts/images is a legacy path.

The codebase is **substantial and running** even though no paying customer exists yet:

- **Live MCP tool surface** exposed via [FastMCP](https://github.com/modelcontextprotocol/python-sdk) ([`src/mcp_cad/server.py`](src/mcp_cad/server.py)) — **assembly orchestration + configurations** (skeleton/insert/mate, `record_assembly_plan` → `run_assembly_plan`), **part-design composites** (`build_*`) as substrate, **variant families** (`build_variant_family` + expression-driven profile coords), **library reuse** (`build_part_index` / `query_part_library` — "¿ya hicimos algo así?"), a `verify_setup` diagnostic, a `clarify_autoparts_intent` Spanglish vocabulary, a `capture_views` + `get_bounding_box` + `verify_build_report` verification loop, and document-lifecycle tools (`new_part` / `new_assembly` / `undo`)
- **Batch/automation lane** ([`docs/AUTOMATION_LANE.md`](docs/AUTOMATION_LANE.md)) — the forward direction: a `BatchJobPlan` (`record_batch_job` → `run_batch_job`) that operates over *many files* on the metadata/export/drawing-doc/BOM/health surfaces. **Proposal — not yet built;** mirrors the shipped `record→review→run` orchestrators
- **Spanglish-autoparts vocabulary** ([`src/mcp_cad/vocabulary.py`](src/mcp_cad/vocabulary.py)) — ~20 curated terms (`rin`, `buje`, `soporte`, `brida`, `cubo`, `flecha`, `polea`, …) with primary archetype, alternatives, typical dimension ranges, and disambiguation questions. Surfaced via `clarify_autoparts_intent`; pulled before plan-mode to ground informal terms
- **Customer deployment guide** at [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — install, daily workflow, troubleshooting
- **SolidWorks COM driver** ([`src/mcp_cad/solidworks.py`](src/mcp_cad/solidworks.py)) — Protocol seam, in-memory mock, and live `pywin32` late-binding client

The architecture is settled (Python + MCP + SolidWorks COM); the product surface continues to evolve.

---

## Why this exists

**The problem.** Mexican autoparts PYMEs (30–200 employees) supply tier 1's like Schaeffler, DENSO, Aisin, and Toyoda Gosei. Senior CAD talent leaks to the OEMs and tier 1's, where pay is 2–3× higher. The juniors who stay can't reliably handle complex assembly work — mating, configurations, tooling. PYMEs cope with overtime, expensive consultants on retainer, training spend, or by refusing OEM jobs they can't deliver.

**The thesis.** The AI orchestrates SolidWorks. It does not invent geometry. The MCP server exposes a fixed set of typed, deterministic operations; an LLM (Claude) chooses which to call and with what arguments; every model change requires a designer's explicit approval before commit.

---

## Critical product constraints (DO NOT VIOLATE)

These are the contract with PYME customers whose OEM supplier agreements (e.g. Schaeffler) impose strict NDA and IP terms. If a code change weakens any of these, surface the tradeoff before merging.

1. **Geometry stays on the customer's machine.** `.sldprt`, `.sldasm`, `.slddrw` files never leave the host. The MCP server runs locally and uses SolidWorks COM in-process. Only abstracted text intent + structured tool-call arguments are transmitted.
2. **Constrained tool surface.** The AI orchestrates pre-defined SolidWorks operations. It does NOT call arbitrary SolidWorks API methods. Each tool is deterministic and reviewed.
3. **Human-in-the-loop on every model change.** No autonomous design changes. Every AI suggestion requires designer approval.
4. **Customer credentials are sacred.** API keys (Anthropic, etc.) are stored in customer-controlled config and never logged, telemetered, or committed.
5. **No telemetry of customer work.** No analytics that capture model contents, file names, geometry patterns, or anything derived from customer designs.

Lifted nearly verbatim from [`CLAUDE.md`](CLAUDE.md). Read that file before contributing.

---

## Architecture

```
  Designer chat (Claude Code, Claude Desktop, etc.)
                  │
                  ▼  MCP over stdio
       FastMCP server (server.py)
                  │
                  ▼  Protocol calls  (mm + degrees, Spanglish errors)
         SolidWorksClient (Protocol)
              ┌───────────┴───────────┐
              ▼                       ▼
    MockSolidWorksClient        WinComSolidWorksClient
    (in-memory fake;            (pywin32 late binding,
     used for non-Windows        DISPID + InvokeTypes for
     dev)                        methods that COM marshalling
                                 mishandles)
                                        │
                                        ▼ COM (m + radians)
                                Running SolidWorks
```

**Source files** sharing a single Protocol seam:

- [`src/mcp_cad/server.py`](src/mcp_cad/server.py) — FastMCP server. Declares the `@mcp.tool()` functions and binds each to a method on a single `client` instance. The module catalog (and the [MCP `instructions`](https://spec.modelcontextprotocol.io/specification/server/) preamble) is **auto-generated at module load** by walking the FastMCP registry — see `_generate_catalog()`.
- [`src/mcp_cad/solidworks.py`](src/mcp_cad/solidworks.py) — Defines the `SolidWorksClient` Protocol, `MockSolidWorksClient` (deterministic fake), and `WinComSolidWorksClient` (live COM via `pywin32`). All COM constants and DISPID/typelib metadata live here.
- [`src/mcp_cad/vocabulary.py`](src/mcp_cad/vocabulary.py) — Curated Mexican-Spanish autoparts glossary surfaced via `clarify_autoparts_intent`.

**Units convention.** Protocol surface uses **mm** for lengths and **degrees** for angles. Conversion to SolidWorks-native meters/radians happens inside `WinComSolidWorksClient` only. Stay mm + deg native everywhere above the COM layer.

**Spanish-language is a product requirement, not a translation.** Tool descriptions, error messages, and UI text use the Spanglish CAD vocabulary Mexican designers actually use (`croquis`, `vaciado`, `redondeo`, `chaflán`, `barreno`, `ensamble`). Tools that accept plane names take both English (`"front"`/`"top"`/`"right"`) and Spanish UI names (`"Alzado"`/`"Planta"`/`"Vista lateral"`). Error messages follow the format:

```
<Spanish lead>: {dynamic detail}
[en: <English fallback>]
```

---

## Tech stack & platform requirements

- **Python** ≥ 3.10
- **`mcp`** ≥ 1.0.0 (the Anthropic [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk))
- **`pywin32`** ≥ 306 — Windows-only via the `platform_system=='Windows'` marker
- **SolidWorks** running locally — required for live operation. Non-Windows boxes can develop against the mock with `MCP_CAD_USE_MOCK=1`.
- **AI provider:** Anthropic Claude.
- **Tooling:** [`uv`](https://docs.astral.sh/uv/) for dependency management. No linter or type checker is wired up by design — the minimal-deps default is intentional.

See [`pyproject.toml`](pyproject.toml).

---

## Quick start (developer)

```bash
git clone https://github.com/danielproxd2/MCP_CAD.git
cd MCP_CAD
uv sync --extra dev
```

Create a local `.mcp.json` at the repo root (this file is gitignored — each developer creates their own):

```json
{
  "mcpServers": {
    "mcp_cad": {
      "command": "uv",
      "args": ["run", "mcp_cad"]
    }
  }
}
```

Reload Claude Code. The `mcp_cad__*` tools should appear in the session's tool list.

**Develop on macOS or Linux:**

```bash
MCP_CAD_USE_MOCK=1 uv run mcp_cad
```

The mock keeps in-process state across calls and exercises the full Protocol contract.

---

## Quick start (Claude Code user)

Once the MCP server is connected, an LLM session sees:

- **`list_capabilities()`** — the authoritative live tool inventory (count + alphabetical names). Names only by design: full tool descriptions already ship with every `tools/list`, so the catalog confirms the surface without duplicating them.
- **`verify_setup()`** — diagnostic tool. Returns a checklist (MCP server / SolidWorks connection / active document) so a non-technical customer can confirm the install is healthy. See [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) for the full customer onboarding flow.
- **`query_part_library(...)` / `build_part_index(folder)`** — library reuse. Index a folder of `.sldprt` into a local PDM-lite catalog, then ask "¿ya hicimos algo así?" before modeling — a near-match becomes a variant, not a remodel.
- **`record_assembly_plan(...)` / `run_assembly_plan(...)`** — the assembly orchestrator: pin skeleton + ordered components-with-mates as data, review, then insert+mate under one approval with a mate-count gate.
- **`build_variant_family(...)`** — a configuration family from a base part + a variables table (profile coordinates accept expressions like `"A-29"`, so one solved design replays at any size).
- **`clarify_autoparts_intent(term)`** — Spanglish vocabulary lookup. Returns the curated archetype + typical dimension ranges + disambiguation question for ~20 informal Mexican-Spanish autoparts terms, to ground the interpretation before modeling. See [`PART_DESIGN.md`](PART_DESIGN.md) §0.5.
- **`verify_build_report(...)`** — closes a build with bbox/mass/feature-count + occluded/internal-feature evidence (advisory; human visual diff still required).
- **MCP `initialize` preamble** — sent once per session. Carries the Spanish header + the reuse-first / edit-first / automation-first directives so the LLM routes through the right discipline.

> Legacy (dormant): a structured generate-from-spec spine — `record_drawing_spec` → `compile_feature_plan_from_drawing_spec` → `run_feature_plan` — still builds a part from a recorded spec and enforces its internal features, but generating parts this way is no longer the product focus (PDF *perception* was retired).

For the live, authoritative tool list call `list_capabilities()` from any MCP session. For per-tool documentation — args, returns, gotchas, examples, and workflow recipes — see [`docs/TOOLS.md`](docs/TOOLS.md).

---

## Project layout

```
MCP_CAD/
├── README.md                     # this file
├── CLAUDE.md                     # operating rules — read before contributing
├── PART_DESIGN.md                # prompt-engineering guide for part-design tasks
├── ASSEMBLY_DESIGN.md            # prompt-engineering guide for assembly tasks
├── FIELD_NOTES.md                # compact operating cheat-sheet
├── pyproject.toml                # name, deps, console script, build backend
├── uv.lock                       # pinned dependency tree
├── docs/
│   ├── AUTOMATION_LANE.md        # product direction — batch lane scope (proposal)
│   ├── TOOLS.md                  # per-tool reference doc
│   └── DEPLOYMENT.md             # customer deployment guide
├── src/mcp_cad/
│   ├── __init__.py
│   ├── server.py                 # FastMCP entry, auto-catalog
│   ├── solidworks.py             # Protocol + Mock + WinCom COM driver
│   ├── verification.py           # built-geometry verification toolkit (universal)
│   ├── part_index.py             # PDM-lite local part-library index (reuse)
│   ├── assembly_ir.py            # AssemblyPlan record→review→run orchestrator
│   ├── dsl.py                    # fluent build123d-style DSL → execute_batch
│   ├── drawing_ir.py             # dormant DrawingSpec / FeaturePlan compiler (legacy)
│   └── vocabulary.py             # Spanglish autoparts glossary
└── .claude/
    ├── agents/                   # part-build-executor, build-verifier, autoparts-researcher
    └── skills/                   # build-part (build/modify a part)
```

`prospects/`, `interviews/`, `customers/`, and any `*.sldprt` / `*.sldasm` / `*.slddrw` / `*.STEP` files are gitignored.

---

## Contributing

Contributions are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the dev setup, test workflow, and the conventions below, and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for community expectations. This is an early-stage project, so opening an issue to discuss a change before a large PR is appreciated.

**Adding a new tool — the pipeline:**

1. Add the method to the `SolidWorksClient` Protocol.
2. Implement on `MockSolidWorksClient` with a deterministic fake.
3. Implement on `WinComSolidWorksClient`. Verify COM constants against the swconst typelib — many constants in `solidworks.py` carry "verified empirically" comments because pywin32 late binding misreports some values. Some methods (`AddMate3`, `SelectByID2`) cannot be marshalled by late-binding dispatch and must be invoked via DISPID + `_oleobj_.InvokeTypes`. Use the existing `_DISPID_*` / `_*_ARGS` blocks as prior art.
4. Expose as `@mcp.tool()` in `server.py`. The module catalog regenerates automatically — no manual catalog updates.

**Build discipline.** One tool, end-to-end, before the next. No premature abstraction; no batched half-implementations. The forward wedge is *task/batch automation* ([`docs/AUTOMATION_LANE.md`](docs/AUTOMATION_LANE.md)); assembly orchestration + library reuse are the shipped substrate it builds on.

**Behavioral guidelines** ("Karpathy guidelines" in `CLAUDE.md`):

- **Think before coding** — state assumptions explicitly, surface tradeoffs.
- **Simplicity first** — minimum code that solves the problem, nothing speculative.
- **Surgical changes** — every changed line should trace directly to the user's request.
- **Goal-driven execution** — define success criteria, loop until verified.

**Spanish-language is a product requirement, not a translation.** Tool docstrings and error messages should use the actual Spanglish CAD vocabulary Mexican designers use (`ensamble`, `croquis`, `redondeo`, `vaciado`, `chaflán`, etc.). Plane-name args take both English and Spanish UI names — preserve this dual-input pattern when adding new tools.

**Customer geometry must never enter the repo.** Synthetic fixtures only.

---

## Reference documents

| File | Purpose |
|---|---|
| [`CLAUDE.md`](CLAUDE.md) | Operating rules for any AI-coding session in this repo. |
| [`docs/AUTOMATION_LANE.md`](docs/AUTOMATION_LANE.md) | Product direction — batch/automation lane scope (proposal). |
| [`PART_DESIGN.md`](PART_DESIGN.md) | Prompt-engineering guide for part-design tasks (substrate). |
| [`ASSEMBLY_DESIGN.md`](ASSEMBLY_DESIGN.md) | Prompt-engineering guide for assembly tasks. |
| [`FIELD_NOTES.md`](FIELD_NOTES.md) | Compact operating cheat-sheet — environment gotchas, save discipline. |
| [`docs/TOOLS.md`](docs/TOOLS.md) | Per-tool reference — args, returns, gotchas, examples. |
| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Customer deployment guide. |

---

## License

Licensed under the [Apache License, Version 2.0](LICENSE). Bundled third-party
components retain their own licenses — see [`NOTICE`](NOTICE).