SolidWorks Skill + MCP

AI Skill + MCP toolkit for reliable desktop CAD automation.

让 Codex、Claude、Cursor 等 Agent 通过自然语言调用真实 CAD 软件，并对执行结果进行验证与追踪。

Tool success is not treated as task success.

工具调用成功，不代表任务真的完成；需要 Review 的任务会经过结果验证后再交付。

当前主产品版本为 v2.1.0：默认交付 Agent Skill ZIP 与标准 MCPB，不要求安装桌面程序。CAD Studio 是独立版本、可选发布的图形界面渠道。下载入口和升级说明见 v2.1.0 发布说明。

可选的 CAD Studio 会对各生产执行器统一检查交付文件是否为本轮新增或内容已变化；旧文件拒绝交付，证据不足转为待复核。扫描范围、兼容性与验证方法见本轮交付门禁。

User → Agent (Codex / Claude / Cursor) → Skill / MCP → Execution Core → CAD → Artifacts + Evidence

AI 负责理解意图、查证 API、规划步骤；Execution Core 保证执行过程可追踪、可验证、失败可恢复。

See It In Action

一个真实流程：自然语言需求 → Agent 调用 Skill → SolidWorks 生成原生 SLDPRT + SLDDRW → 导出 PDF → 自动复核尺寸与证据。

Related MCP server: SolidWorks MCP Server

Prerequisites

安装 Python 依赖：

python -m pip install -r requirements.txt
# 只有开放格式（OCCT）能力才需要：
python -m pip install -r requirements-occt.txt

只读环境自检（不会打开或关闭 CAD）：

python scripts/cad_doctor.py           # 发现的安装路径、版本、COM 注册状态
python scripts/sw_capability_probe.py  # 类型库与能力清单

模板与材料库默认自动探测，不需要写死路径。只有非标准安装位置才需要 config/runtime.example.json 与 SOLIDWORKS_TYPELIB_DIRS， 见 config/README.md。

Quick Start

Skill + MCP 是主产品，二者任选其一即可；CAD Studio 是第三个可选桌面渠道，不参与核心发布门禁。

Option 1 — Skill

npx github:dreamchaseryuan/solidworks-skill-mcp --target claude

该命令获取本仓库并执行根目录的 install.js（package.json 的 bin 入口）。

默认行为（安全优先，2026-10-28 起）：

• 只装到已经存在 skills 目录的客户端（.agents / .claude / .codex / .cursor / .openclaw）； 一个都没检测到时不会替你创建目录，而是提示改用 --target 显式指定。

• 目标目录已存在但不是本仓库的 git 检出（手动放置、解压、或其他来源）时， 拒绝安装且不删除任何文件。

• 由本仓库安装的目录用 git pull --ff-only 更新；无法快进时只报告，不删除。

• 默认自动安装 Python 依赖；Windows 上没有 Python 3.10+ 时尝试使用 winget 为当前用户安装 Python 3.12。失败时给出提示；--no-install-deps 可关闭此行为。

• 非 Windows 平台默认拒绝（SolidWorks COM 不可用）；确需使用开放格式能力加 --allow-non-windows。

安装使用 git clone --depth 1，只取工作树、不拉完整历史。仓库完整工作树约 13 MB， 其中 apps/（桌面端源码，约 6 MB）与 Skill 运行无关。 若 npx 在当前网络环境不可用，改用下方 Option 2 的克隆方式，再执行 node install.js。

Option 2 — MCP

支持 MCP Bundle 的客户端可直接从 GitHub Releases 导入 SolidWorks-Automation-Skill-2.1.0.mcpb；该包同时提供标准版与 Smithery 版。

git clone https://github.com/dreamchaseryuan/solidworks-skill-mcp.git
cd solidworks-skill-mcp
python -m pip install -r requirements.txt -r mcp-server/requirements.txt
node mcp-server/register_all_ai_mcp.js --help          # 查看全部参数
node mcp-server/register_all_ai_mcp.js --clients codex,claude-code,cursor

注册脚本会写入对应客户端的 MCP 配置，并在写入前生成 .bak 备份；加 --strict 可让任一客户端失败时非零退出。

Option 3 — Optional CAD Studio Desktop

从 GitHub Releases 下载 Windows 安装包。

桌面端启动本地执行器时，如果 Windows 没有可用的 Python 3.10+，会尝试通过 winget 为当前用户安装 Python 3.12；无法安装时显示错误。环境诊断仍只读。SolidWorks 必须由用户另行安装并具备许可；API 查证所需的 7-Zip、Python 包和可验证的本地 API Help 按需自动配置，详情见 references/api-lookup.md。

Start with Skill or MCP. Install the desktop app only when you need a GUI.

Skill 与 MCP 共用同一套能力清单（capabilities.yaml）、脚本与证据系统，是默认安装路径。CAD Studio 只是可选的 GUI 封装，不会阻塞 Skill/MCP 独立发版，也不要求所有用户承担 WebView2、Python 环境、签名和 Windows 安装包维护成本。安装后可用 python scripts/cad_doctor.py 做环境诊断；桌面端细节见 docs/CAD_STUDIO_USER_MANUAL.md。

Why This Project

LLM 会规划，但常见的 AI CAD 自动化有几个真实问题：

• LLM 会规划，但不会真正操作桌面 CAD 软件

• Tool 返回 success 不代表任务真的完成

• CAD API 版本、环境、Backend 差异复杂

• 固定 Tool 集合覆盖不完所有工程需求

• Agent 执行过程通常不可追踪、不可审计

本项目的解法：

Architecture

User / Agent
  ↓
Skill / MCP
  ↓
Execution Core（Capability · Verification · Recovery Decision · Trace）
  ↓
Backend Router
  ↓
Python COM / C# / OCCT
  ↓
CAD Software
  ↓
Artifacts + Evidence

• Root Skill = 通用能力、规则与执行基础设施（连接、建模、审查、MCP）。

• Subskills = 专项领域工作流（工程图、螺纹孔、CNC 圆角、VibeCAD、AutoCAD），由 Root Skill 按需调用，不需要用户手动启动。

• Execution Core = 内部可靠执行层：统一状态、结果验证、失败恢复决策与执行追踪。它是内部实现，不是独立服务、不需要用户启动。

• Capability Gap = 找不到能力时结构化返回 CAPABILITY_GAP，交还 Agent 查证，而不是「做不了」：

  Existing Tools → Tool Composition → Backend Fallback → Capability Gap
    → Agent 查 references / 官方 API / SDK → 最小实现 → Verification

  Execution Core 自身不会自动联网执行未知代码。

详细：docs/architecture/execution-core.md

Reliability

当前附带 43 个 deterministic reliability scenarios（12 nominal + 31 robustness）， 覆盖正常执行、故障注入、后端回退、能力缺口与策略门禁；由 golden-workflows.yaml 的 12 个 workflow 派生。

这是 deterministic engineering benchmark（Fake Handler/Reviewer + 故障注入）， 不是生产 SLA 或真实用户成功率。详见 docs/architecture/v2-evaluation.md。

验证边界（Verification Boundary）

本项目的验证分三层，结论不能跨层套用：

必须明确的三点：

1. 远端不存在 CAD 真机执行证据。 仓库没有自托管 Runner，Windows CAD Regression 工作流为手动触发、 不是必需检查，当前无法执行。任何"远程 CAD CI 已通过"的表述都是错的。

2. 本机通过 ≠ 跨机器通过。 换一台机器请按 Prerequisites 与 docs/CAD_STUDIO_USER_MANUAL.md 重新自检， 不要直接引用维护者的验收结论。

3. L2 通过 ≠ 治理闭环。 必需检查只保护 main；指向特性分支的 PR（含 stacked PR）不受该规则约束。

原生 SolidWorks 操作当前以 2026 为支持与验收目标。方案 B 保留现有执行架构，修复失败状态、原生阵列、草图可编辑性和文档归属，并提供可选 HTTP 与可验证的产物取回。

完整模式暴露 69 个命名工具；默认发现模式只暴露 3 个检索入口（sw_search_tools / sw_describe_tool / sw_call_tool）。原有命名工具保持兼容；发现模式 按需检索；写操作经过策略检查，审批行为与信任边界取决于配置。模式切换、审批与回滚见 mcp-server/README.md。

Capabilities & Status

状态等级（capabilities.yaml 定义）：

真机基线：SolidWorks 2024 / 2026、AutoCAD 2024。未验证能力不会被包装成无人值守交付。

• 完整能力矩阵（每个能力的精确等级/版本/限制）→ capabilities.yaml

• 领域工作流 → subskills/ · SUBSKILLS.md

No SolidWorks Installed?

没有 SolidWorks 时，部分开放格式任务仍可完成：

STEP · IGES · BREP · STL · OBJ · GLB · DXF · SVG · PDF · PNG

（通过 OCCT/OCP 隔离进程真实写入。）

但原生 SLDPRT / SLDASM / SLDDRW 仍需要合法 SolidWorks 环境。

Examples

examples/ 目录包含从基础零件到装配、工程图、Motion、FEA 的可运行示例。

Documentation

Roadmap & Contributing

Roadmap：更广的真机验证 · 更可靠的能力路由 · 更好的 CAD Studio 可观测性 · 更多 verified 子技能 · 社区贡献工作流。

Contributing：新增能力时，先查 capabilities.yaml，优先复用现有 backend，新增 tests + evidence，不要把未验证 capability 标为 verified。详见 CONTRIBUTING.md。

License & Community

MIT · Code of Conduct · GitHub Issues · Star History

English

SolidWorks Skill + MCP is an AI Skill + MCP toolkit for reliable desktop CAD automation. Codex, Claude, Cursor, and other agents drive real SolidWorks / CAD workflows through natural language, with verification, deterministic recovery decisions, and execution tracing. Skill and MCP are the primary products. CAD Studio is an optional, independently versioned desktop GUI and does not block the core release.

关注抖音 @balance. · 嵌入式开发、SolidWorks 自动化和 AI 辅助工程实践持续更新

装配干涉检查 API

solidworks_interference_check 使用 IAssemblyDoc.InterferenceDetectionManager， 通过 GetInterferences() 计算并读取 IInterference.Components 和体积，最后调用 Done()。隐藏实体和已忽略结果参与检查；同一个多实体零件内部的相交不计入。 计算失败、计数读取失败、数组数量不一致或结束检查失败均返回 blocked，不会误报零干涉。 抑制组件不参与计算；零结果仍需核对组件解析状态和设计意图。 离线回归覆盖调用顺序、失败处理和 SI 体积换算（26 项通过）。 SOLIDWORKS 2026 SP4.1（34.4.1）、Python 3.10 上已通过 MCP 实测正常返回； 该真机样例为零干涉，非零结果读取仍以离线回归为证据。