SolidWorks MCP

SolidWorks MCP 是一个 Python 3.11+ MCP 2.0 stdio server。V2 把工程意图、CAD 执行和证据验收分离，用受控工作流实现可追溯的 SolidWorks 自动化；它不是开放式 CAD 脚本、任意宏或底层 sw_* 命令平台。

Product boundary

V2 的唯一公共链路是：

EngineeringCase / immutable Revision
→ EngineeringSpec
→ DesignIR
→ immutable ExecutionBundle
→ confirmed(bundle_id + bundle_hash)
→ isolated execution
→ EvidenceBundle
→ Acceptance / Repair
→ human release

• 公共 MCP surface 固定为 10 tools、3 resource templates、1 prompt；不公开 ModelPlan、raw FeatureDAG、COM 调用或 direct sw_*。
• 首发设计域为通用零件/配置、装配/mates/BOM/干涉、钣金、焊件、完整工程图和线性静力。Routing、Mold、CAM、Motion、CFD、非线性分析和任意宏不在 V2 首发范围。
• 默认工程标准为 GB/ISO、公制毫米和第一角投影；任何偏离必须在 EngineeringSpec 中显式记录。
• R3 表示会改变需求真值的关键未知，阻断 Spec；R2 表示需要工程师选择的设计决策，阻断编译；R1 可采用明确默认值，但必须保留记录。
• protocol_simulated 只证明 schema、哈希绑定和编排，可到 orchestration_ready；它不能生成 geometry、model 或 engineering-quality verified 证据。
• engineering_quality_candidate 只是自动化真实证据门禁的结果。最终 human_released 必须绑定精确交付包哈希，并由两个独立高级机械工程师批准；它不等于执行确认。
• 每个功能的真实状态必须同时读取 protocol_surface、implementation_maturity、engineering_evidence 和 policy，不得用单一 available 推断生产能力。

完整能力真值见 Protocol catalog，工作流语义见 Engineering workflow V2。

Quick start

安装开发环境：

uv sync --group dev

启动 V2 MCP server。启动本身不会连接 SolidWorks：

$env:SOLIDWORKS_MCP_ENGINEERING_STORE_DIR = "D:\SolidWorksMCP\engineering-v2"
uv run solidworks-mcp

默认从 SOLIDWORKS_MCP_OUTPUT_DIR\engineering_v2 保存不可变 case/run 记录；显式设置 SOLIDWORKS_MCP_ENGINEERING_STORE_DIR 可覆盖该位置。

客户端必须先发现 10 个高层工具，再按响应里的 next_actions、资源 URI 和哈希推进。不要让模型自行构造 COM 操作序列。stdio 配置和 operator 规则见 MCP client configuration。

严格 V2 输入示例：

• v2_create_engineering_case.json
• v2_compile_mounting_plate.json
• v2_prepare_execution_bundle.json
• v2_execute_execution_bundle.json

示例中的 ID 和 64 位哈希是 schema-valid 占位值；实际调用必须原样使用上一阶段结构化响应返回的 ID/hash。

Core commands

V2 领域、surface 和文档最小门禁：

uv run pytest -q tests\unit\engineering -W error
uv run pytest -q tests\contracts\test_public_surfaces.py -W error
uv run pytest -q tests\contracts\test_documentation_contracts.py -W error
uv run python scripts\check_mcp_tool_schemas.py
uv run python scripts\release_engineering_v2_gate.py --summary-only

The V2 release gate is no-COM and protocol-simulated. Exit code 0 means the V2 orchestration contract passed; the report still sets production_release_ready=false and lists real SolidWorks, geometry, engineering-quality and human-release blockers.

完整 no-COM 回归：

uv run pytest -q -W error

scripts\check_mounting_plate_schema.py、scripts\check_atomic_model_session.py、scripts\smoke_mounting_plate.py 和 scripts\release_production_gate.py 仍可能被内部 V1 fixtures/tests 使用。旧 *_plan.json 和旧 production_verdict 不属于 V2 公共合同，也不能充当 V2 release evidence。

REAL-ONLY：V2 真实 worker 只会在操作员固定的 qualification portfolio path/hash 对当前源码、依赖、SolidWorks build/revision、两个独立 profile manifest、sealed evidence、package 和全部 artifact 复核通过后绑定。默认 Registry 保持保守；当前 portfolio 必须同时包含受控 mounting-plate 与 sheet-metal profile，共覆盖 9 个唯一能力，且不等于 human_released。

uv sync --extra windows
uv run python scripts\real_validation\engineering_v2_mounting_plate.py --output-root <new_output_root> --confirmed
uv run python scripts\real_validation\engineering_v2_sheet_metal.py --output-root <new_output_root> --confirmed
uv run python scripts\build_engineering_qualification_portfolio.py --portfolio-root <common_archive_root> --manifest <mounting_manifest.json> --manifest <sheet_metal_manifest.json> --solidworks-executable <SLDWORKS.exe>
uv run python scripts\verify_engineering_qualification.py --portfolio <portfolio.json> --portfolio-hash <sha256> --summary-only

两个真实 gate 各自输出 profile manifest；只有 portfolio builder 输出的精确 path 和 portfolio_hash 可以配置为 SOLIDWORKS_MCP_QUALIFICATION_PORTFOLIO / SOLIDWORKS_MCP_QUALIFICATION_PORTFOLIO_HASH。单一 manifest 和旧环境变量不会启用真实 worker；完整失效规则见 MCP client configuration。旧 scripts\smoke_mounting_plate.py、scripts\real_validation\imported_model_drawing.py 和 production_verdict 仍只是 V1/internal evidence，不是 V2 资格。

Safety rules

• 所有输入模型都是严格 Pydantic 合同，未声明字段直接拒绝；公共编译入口只接受版本化 Design Pattern，不接受 raw FeatureDAG 或自由操作列表。
• create_engineering_case 会把 inline/local sources 哈希并快照到 revision 工作区；本地源 CAD 不在原地修改。
• compile 与 prepare 都携带 case_id、base_revision_id、spec_hash 乐观并发前置条件。旧 revision 或错误 hash 必须 fail closed。
• 只有 confirmed=true 且 bundle_id、bundle_hash 与已持久化不可变 bundle 完全一致时才能执行。
• 任何被 bundle hash 覆盖的语义变化都必须创建新 revision、重新编译、重新 prepare 并重新确认。
• Repair 只生成证据绑定的 typed proposal；应用 repair 总是派生新 revision，不能原地改模型或重开 sealed evidence。
• Acceptance 必须从原始、sealed、append-only evidence 重新计算；请求值回显、mock success、export success 或保存的旧 verdict 都不算独立证据。
• solidworks_isolated 只有在所需 capability 全部 hardened + release_qualified + allowed 且配置隔离 worker 后才允许 prepare/execute。
• 最终放行只由 record_human_release 记录，且必须绑定 acceptance hash、package hash 和两个独立批准证词。

Run artifacts

V2 持久化目录按 case/revision/run 隔离：

<engineering_store>/
├── engineering_cases/<case_id>/
│   ├── case.json
│   └── revisions/<revision_id>/
│       ├── revision.json
│       ├── sources/<sha256>/...
│       ├── state_events/*.json
│       └── records/
│           ├── design_compilation.json
│           ├── capability_snapshot.json
│           └── execution_bundle.json
└── engineering_runs/<run_id>/
    ├── run.json
    ├── evidence.json
    ├── acceptance.json
    ├── package.json
    └── release.json

记录使用 canonical JSON、内容哈希和不可变写入。读取 case/run resource 时仍会做严格解析；不得通过手工编辑记录修复失败，必须创建新 revision。

outputs/、test_outputs*/、dist/ 和缓存属于生成状态。真实 CAD 证据只有在外部归档、哈希复核、当前 acceptance 复算和人工放行记录完整后才可进入交付流程。

Documentation

• Engineering workflow V2：生命周期、R1/R2/R3、确认、证据、repair 与 human release。
• Protocol catalog：10/3/1 surface 和四轴 capability truth。
• MCP client configuration：stdio 配置、工具调用顺序、结构化响应和 operator 边界。
• External MCP adoption backlog：外部项目调研 backlog；不是能力承诺。
• examples/v2_*.json：当前严格 V2 API 输入示例。
• examples/*_plan.json：仅供内部 V1 回归 fixture；不是公共 ModelPlan 合同。
• AGENTS.md 及各目录的 AGENTS.md：代码所有权、局部约束和验证命令。