内容
# SolidWorks MCP — 运行、测试和自动修复VBA宏
一个MCP服务器，通过COM（pywin32）连接到正在运行的 **SolidWorks 2022**，
运行您的VBA宏（或内联VBA），检查生成的模型，并返回 **结构化诊断**，
以便Claude可以修复错误并重新运行，直到模型成功构建。
它还附带一个 **API文档管道**，该管道渲染仅限JavaScript的`help.solidworks.com/2022`页面，
并提取方法/枚举事实，以保持生成的代码正确。
为与`soldworks-vba`技能配对而构建：该技能 *编写* 已验证样式的宏；
此服务器 *运行、测试和修复* 它们。
## 工作原理
```bash
Claude (+ solidworks-vba 技能)
│ 编写 / 修复 VBA
▼
run_and_verify ──► COM 工作线程 (STA) ──► SolidWorks 2022
│ │
│ ◄── 结果：运行？重建错误？ ◄───────┘
▼ 错误特征？VBA错误？
如果不成功：读取错误，重新生成，调用再次 （Claude驱动的循环）
```
- **内联VBA** 编写到一个临时 `.swb` 文件中，并使用 `RunMacro2` 执行（SolidWorks 动态编译 `.swb` 文本 - 无需 `.swp` 编作者，无需 VBA 信任访问设置）。
- 所有 COM 访问都在 **一个 STA 工作线程** 上运行（COM 对象是公寓绑定的）。
- 生成/自动化的宏使用 **静默日志** （`SWMCP_Log`）代替 `MsgBox`，并且 **对话框监视器** 自动关闭 stray 模态对话框，以免宏永远阻塞服务器。
- 服务器永远不会编辑您的 VBA。它返回丰富的错误；Claude 修复它们。
## 会话优先的快速工作流
每个建模请求都应以 `prepare_modeling_context(request)` 开始。
它在一个往返中执行完整的预检：
1. 通过其确切的 ROT monikers 检测正在运行的 SOLIDWORKS 进程。
2. 自动选择唯一的会话，或在需要选择时返回进程列表。
3. 如果没有会话运行，则使用 `action=start_solidworks` 停止 - 此时不会静默启动任何内容。
4. 在生成任何代码之前，返回匹配的技能，专业设计指导，捆绑的 Cosmon 引用，
和本地 SOLIDWORKS CHM 结果。
5. 将每个后续建模工具绑定到选定的进程。
`sw_list_sessions`，`sw_select_session(process_id)` 和 `sw_disconnect_session`
提供显式控制。执行抑制图形/树变化可逆转，
生成的宏重建一次，验证扫描特征树一次，
并且重复的 Cosmon 搜索从内存中提供服务。
## 需求
- Windows + **SolidWorks 2022** （COM ProgID `SldWorks.Application`）。
- **Python 3.10+**。
- 在 SolidWorks 中配置 **默认零件/装配/图纸模板** （工具 ▸ 选项 ▸ 默认模板）- 如果未设置，宏将干净地中止。
## 安装
```bash
pip install -e .
python -m playwright install chromium # 一次性，用于文档管道
```
## 注册到 Claude 代码
已经在用户范围内注册：
```bash
claude mcp add solidworks -s user -- C:/Python313/python.exe -m sw_mcp.server
```
或者，对于项目范围的、可共享的配置，在项目根目录中放置一个 `.mcp.json` 文件（参见 [install/register-mcp.md](install/register-mcp.md)）。使用 `claude mcp list` 确认（查找 `solidworks: ... ✓ Connected`）。
## 工具
**会话和预检** — `prepare_modeling_context`，`sw_status`，
`sw_list_sessions`，`sw_select_session`，`sw_disconnect_session`
**专业设计知识（主动）**
- `get_design_guidance(query)` — **在建模之前调用此函数。** 返回匹配的专业 **原型配方** （有序特征序列，
设计意图实践，关键尺寸），相关的通用设计原则，
以及对于公差查询的 GD&T 参考。从真实的 SolidWorks 教程 (`transcripts.txt`) 中提炼，
以便构建工具生成真正的工程部件，而不是一个简单的块或圆柱体。
- `list_design_recipes()` — 可用的原型（轴承，发动机，瓶子，
歧管，旋转壳体，安装板）。参见 [`DESIGN_PLAYBOOK.md`](src/sw_mcp/resources/knowledge/DESIGN_PLAYBOOK.md)。
**执行和验证**
- `run_macro(path, module, procedure)` — 运行现有的 `.swp`/`.swb` 文件。
- `run_vba(code, procedure, module)` — 运行内联 VBA 字符串。
- `run_and_verify(code | macro_path, …)` — 运行 → 重建 → 扫描 → 一个判决。
**自动修复循环基元。**
**诊断** — `rebuild_model`，`get_build_errors`，`get_feature_tree`，
`get_mass_properties`，`get_bounding_box`，`capture_screenshot`
**文档** — `new_document`，`open_model`，`save_model`，`close_model`，
`export_file` （STEP/IGES/STL/X_T/PDF/PNG 通过扩展名）
**特征生成器** — 单个特征 *基元* （已验证的 VBA，每个构建 → 运行 → 重建 → 错误扫描）。这些是构建块和烟雾测试，
**不是** 完成的零件；专业部件由它们（加上内联 `run_vba`）组成，
按照 `get_design_guidance` 的配方：`create_extrusion`，`create_cylinder`，`create_fillet`，`create_chamfer`，
`create_shell`，`create_draft`，`create_rib` （L 型支架 + 肋），
`create_revolve` （管），`create_sweep` （扫描沟槽），`create_loft` （ loft 切割），
`create_hole_wizard` （公制沉孔），`create_thread` （真实切割螺纹），
`create_spring` （螺旋线 + 扫描），`create_linear_pattern`，`create_mirror`，
`create_circular_pattern`，`create_assembly` （2个组件完全配合）。
**曲面建模：** `create_surface_extrude`，`create_surface_planar`，
`create_surface_revolve`，`create_surface_thicken` （曲面→实体）。
**钣金：** `create_sheet_base_flange` （平板），`create_sheet_lbracket`
（弯曲，真实弯曲）。通过在 `feature_tools.py` 中添加构建器来扩展（参见下文）。
图案变体尚未给出一个调用工具（曲线/草图/表格/填充），钣金边缘法兰/折边/斜切，
以及其他特征可以通过 `run_vba` + `solidworks-vba` 技能 + 自动修复循环完全构建。
**自我改进的知识库** — `learn_rule`，`list_rules`。每个固定的错误
成为一个持久的规则（`resources/knowledge/rules.json`，人类可读的
`LESSONS.md`）。在失败时，`run_and_verify` 返回 `suggested_fixes`，
与过去的规则匹配，因此相同的错误永远不会被解决两次。
**API 文档** — `docs_lookup_method(interface, method)`，
`docs_lookup_enum(enum_name)`，`docs_get(url)`。读取 `remarks` 字段 —
它包含选择标记/前提条件的详细信息，这些信息将工作代码与崩溃代码区分开来。
**Cosmon 兼容的资源和技能** —
`engineering_resources_status`，`list_engineering_resources`，
`search_engineering_resources`，`get_engineering_resource`，`list_skills`，
`get_skill`，`create_skill`，`update_skill`，`delete_skill`，`import_skill`。
服务器捆绑 Cosmon 完整的 SOLIDWORKS 文档负载—
包括大型特征/功能数据库—加上 C# 模板，持久服务源，
以及所有 12 个打包技能。安装的 Cosmon 资源仍然是一个备用源。
设置 `COSMON_RESOURCES_DIR` 以获取非默认的 Cosmon 位置，
并设置 `SW_MCP_SKILLS_DIR` 以获取可编辑的技能覆盖。
## 自动修复循环
1. Claude 编写一个宏（通过 `solidworks-vba` 技能）并调用
`run_and_verify`。
2. 返回判决： `{success, ran, run_error, log[], log_errors[]，
errors[], errored_features[], suppressed_features[], feature_count}`。
3. 如果 `success == false`，Claude 读取 `log_errors`/`errors` （并查找确切的 API，
通过 `docs_lookup_method`），重新生成纠正后的 VBA，并再次调用
`run_and_verify` — 直到 `success == true`。
## 设计专业零件（不是简单的块）
构建循环仅检查几何体 **重建** — 独自放置，
最简单的形状如果构建干净，则是一个块或圆柱体。要获得真正的工程部件，
设计意图必须来自某个地方。就是 `get_design_guidance` 层（`design_library.py`，
从教程记录中提取）：
1. 调用 `get_design_guidance("<零件描述>")` （例如 `"深槽球轴承"`，
`"带螺栓圆的安装底板"`，`"空排气歧管"`，`"轴公差 / GD&T"`）。
2. 按照返回的 **特征序列** 和 **设计意图** 注释 — 围绕中心线旋转，
完全定义草图，在构造 PCD 上定位孔并进行圆形图案，
每个边缘都断开，对于薄壁零件使用表面然后加厚，
对于空心零件使用组合然后壳体，对于装配体先固定然后完全约束，
对功能特征应用 GD&T。
3. 发出 VBA （下面的特征基元，或内联 `run_vba`）并驱动它
通过 `run_and_verify` 直到 `success == true`。
配方是 **索引**；**原则** 适用于每个零件。相同的知识在 `rules.json` 中镜像为反应规则，
因此相关的构建错误也会将相关的专业实践作为 **suggested_fix** 显示出来。
## 编写更多特征生成器
生成器发出 `solidworks-vba` 样式的 VBA 并通过 `run_and_verify` 运行。两个 **不可妥协的规则**
适用于内联 `.swb` 代码（从 `src/sw_mcp/vba/helpers.vba` 中学习）：
1. **永远不要使用按位 `If Not x` 测试 API 布尔值。** 在即时 `.swb` 中，
API `VARIANT_BOOL` 返回值为 `+1`，而 VBA 的 `Not` 是按位（`Not 1 = -2`，真）。始终编写 `If x = False Then`。
对象检查（`Is Nothing`）是好的。
2. **`Create*Rectangle` 返回一个 Variant 数组，而不是对象。** 使用 `Dim v As Variant: v = ...` 捕获并检查 `IsArray(v)` —
永远不要 `Set seg = …` （引发运行时错误 424）。
在 `feature_tools.py` 中添加 `build_<feature>()` （重用 `assemble_part_macro`）
并在 `server.py` 中添加一个薄 `@mcp.tool()` 包装器。
## 诊断脚本
`scripts/` 包含用于验证每个层的独立测试程序
（`spike_connect`，`spike_runmacro`，`spike_build`，`spike_autofix`，...）。它们对于在不经过 MCP 传输的情况下调试 COM 链接很有用。
