ultron-onshape-mcp

# Ultron Onshape MCP 专注于性能和可靠性的[jarvis-onshape-mcp](https://github.com/ReshefElisha/jarvis-onshape-mcp)分支版本，由Reshef Elisha（MIT许可）创建。所有架构、愿景工作流程和原始工具表面的功劳都归上游——此分支版本保持其完整，并针对更快速、更经济的现实世界迭代进行了调优。 ## 本分支版本的变化 在90面叶片式叶轮（此分支版本调优的零件）上进行测量： - **验证循环速度快3.2倍。** `describe_part_studio`从9.3秒→2.9秒：验证过程中跳过了每个面的切平面FeatureScript探针（`list_entities`增加了`include_frames`），并且边界框+面面积探针合并为单个评估，以便零件仅再生一次，而不是三次。 - **每次验证调用的令牌数减少约46%** （约6,300→约3,370）：主体拓扑结构被总结（按实际面积划分的最大平面面 + 每种曲面类型的代表，`verboseTopology=true`用于完整转储），默认渲染为1024x680的3个视图，而不是1200x800的4个视图，并且所有工具响应都使用紧凑的JSON。 - **`create_circular_pattern`实际有效。** 原生轴查询（`qCreatedBy(makeId("FRONT"), EntityType.EDGE)`）永远无法解析——基准面没有边。世界轴模式（轴=X/Y/Z）现在自动生成FeatureScript `opPattern` + `rotationAround`特征；新的`axisEdgeId`参数在可用真实模型边时使用原生模式。 - **针对Onshape当前API的特性参数兼容性修复** （例如，`libraryRelationType: "NONE"`拒绝）和`create_revolve`确定性边轴选项。 Claude Code插件，允许Claude驱动真实的Onshape CAD：草图、拉伸、圆角、配合、通过变量工作室的参数化迭代、自定义FeatureScript特性。每个变异工具返回一个结构化的真相：更改了什么，regen引发了什么警告，以及下一个操作的提示。多视图PNG渲染作为图像内容返回，以便Claude实际上可以看到该零件。 包括一个视觉分解技能，引导Claude阅读工程参考图像 *在* 构建之前。有关该工作流程的基准数据，请参见 `RESEARCH.md`。 > "感觉比我尝试过的任何LLM CAD工具都更像是在编写代码。" ## 您将获得 - **每次变异都说出真相。** 每个工具返回 `{ok, status, feature_id, feature_name, error_message, changes?, hints?}`。无声的regen失败被提出，警告被丰富为可行的修复。 - **视觉。** `render_part_studio_views` 和 `render_assembly_views` 返回阴影PNG（前/上/右/等距）。`crop_image` 将区域缩放。`load_local_image` 缓存用户分享的参考图像（绘图，照片，草图），您可以将其裁剪到同一位置。`compare_to_reference` 渲染正在进行的零件，并直接在其下合成参考图像，以便在单个图像中进行并排视觉差异比较。 - **视觉分解技能。** `/skill vision-decompose` - 当用户提供参考图像并要求您构建它时，此技能引导您完成结构化的缩放和描述过程 *在* 开始构建之前。生成一个特性树，用户可以进行健全性检查。我们测量这将“代理快速浏览图像并构建错误的形状”转换为“代理仔细阅读图像，请求用户确认，然后构建”。有关研究，请参见下面的内容。 - **绘图OCR。** `extract_drawing_dimensions` 在工程绘图上运行Tesseract，并返回每个数字标注（长度/半径/直径/线程/角度/计数）按类型分组，并带有像素位置。在难以阅读的绘图PNG上使用它，其中小尺寸文本被Claude的视觉降采样弄乱。 - **带有外法线的实体发现。** `list_entities` 返回确定性的面ID，表面类型和法线，以便后续特性可以定位几何体而无需猜测。 - **每个特性的几何差异。** 在每个特性之后，您将获得一个 `changes:` 块，包含边界框增量，零件数量增量，质量增量 - 您在渲染之前看到效果。 - **参数化迭代。** 一流的变量工作室。 `set_variable` 是按名称插入的，因此重新参数化NEMA 17→NEMA 23只需要几个值。 - **FeatureScript逃生口。** `write_featurescript_feature` 允许Claude直接编写自定义特性（螺旋，扫描线程，带有参数的壳）当工具按基元曲面不够用时。 Regen错误显示FS通知文本。 - **提示轮换。** 当特性以已知模式失败时，提示指向修复（`BOOLEAN_SUBTRACT_NO_OP → oppositeDirection`，`SKETCH_DIMENSION_MISSING_PARAMETER → add missing variable`，...）。 - **装配。** 紧固，滑动，旋转，圆柱配合；面坐标系；实例对齐；边界框干扰检查。 ## 安装 ``` /plugin install github:ReshefElisha/jarvis-onshape-mcp ``` Claude Code 将提示您： - `ONSHAPE_API_KEY` — Onshape开发者门户中的“访问密钥”。 - `ONSHAPE_API_SECRET` — 创建密钥对时显示的“密钥”。 在 [dev-portal.onshape.com](https://dev-portal.onshape.com/) 获取密钥对。两个值都存储在OS密钥链中，从未以明文写入磁盘。 ### 要求 - [uv](https://docs.astral.sh/uv/) 在您的PATH上（`brew install uv` 或官方安装程序）。插件通过 `uv run` 启动其MCP服务器。 - 支持插件的Claude Code桌面版或CLI。 - Onshape账户。 ## 快速开始 安装完成后，重启Claude Code并尝试： > “创建一个新的Onshape文档，添加一个零件工作室，并为我制作一个60×40×8毫米的安装板，四个Ø4毫米的孔距角6毫米。” Claude将渲染结果，显示边界框增量，并提出regen警告。如果在拉伸过程中出现方向错误，`BOOLEAN_SUBTRACT_NO_OP`提示将生效并自我纠正。 ## 协议指南 Claude Code自动发现的两个插件技能： - `skills/onshape/SKILL.md` — **CAD构建技能**。加载到每个Onshape会话中。涵盖单位（毫米中的裸数），坐标系（Front是XZ，带有Y法线符号翻转），先渲染和先实体的工作流程，迭代规则，何时调用`write_featurescript_feature`，以及陷阱（REMOVE-on-face自动翻转，变量工作室作为单独元素，确定性ID重新映射）。 - `skills/vision-decompose/SKILL.md` — **视觉分解**。在用户分享参考图像时，在 *构建之前* 使用它。引导代理完成概述→缓存→缩放每个特性→结构化规格。输出是一个特性树（类型，角色，大小，位置，面），用户可以在提交构建之前审查。参见“推荐工作流程”。 您可以将两者加载到任何Claude会话中作为系统提示，以获得与插件上下文外的相同行为。 ## 推荐工作流程 插件作为协作者使用效果最佳，而不是自动完成。有两种模式： **模式A — 文本优先设计。** 用纯文本描述零件（“一个100×60×30毫米的铝制散热器，带有1毫米间距的翅片和4个角落Ø3.5安装孔”），让Claude构建。这很好用——瓶颈不是CAD执行，而是图像解释。 **模式B — 图像参考。** 放入绘图、照片、草图或竞赛提示，并要求Claude构建它。 1. 调用视觉分解技能： `/skill vision-decompose`。 2. Claude从图像生成结构化的特性树。 3. 审查它 - 修复误读，填写图像不明显的细节。 4. 告诉Claude“按照该规格构建”。它针对确认的树运行CAD流水线。 带有仔细的人工审查的模式B优于让Claude单独尝试整个过程。有关建议，请参见 `RESEARCH.md` 中的实验数据。 ## 工具表面 大约60种工具，分为以下几组： | 组 | 亮点 | |-------|-----------| | 文档 | `create_document`, `find_part_studios`, `get_elements` | | 草图 | `create_sketch`（多实体），以及矩形/圆形/线条/弧线/圆角矩形基元 | | 特性 | `create_extrude`, `create_revolve`, `create_thicken`, `create_fillet`, `create_chamfer`, `create_boolean`, `create_linear_pattern`, `create_circular_pattern` | | 装配 | `add_assembly_instance`, `create_fastened_mate`, `create_slider_mate`, `create_revolute_mate`, `create_cylindrical_mate`, `align_instance_to_face`, `check_assembly_interference` | | 自省 | `describe_part_studio`, `list_entities`, `get_body_details`, `get_bounding_box`, `get_mass_properties`, `measure`, `get_face_coordinate_system` | | 变量 | `create_variable_studio`, `set_variable`, `get_variables` | | FeatureScript | `eval_featurescript`, `write_featurescript_feature` | | 渲染 | `render_part_studio_views`, `render_assembly_views`, `crop_image`, `load_local_image`, `compare_to_reference`, `extract_drawing_dimensions` | | 导出 | `export_part_studio`, `export_assembly`（STL / STEP / GLTF / ...） | 完整的模式可通过Claude的 `ToolSearch` 发现 - 无需阅读单独的文档。 ## 已知限制 - **剖面视图在Onshape平台级别被阻止。** REST API没有剖面视图端点；只有UI `Shift+X`起作用。 - `create_fillet` 使用 `variableCenter` 目前会遇到Onshape方面的幻影参考错误。裸半径起作用。 - `opHelix` 标准库调用在某些上下文中不稳定；食谱使用 `opFitSpline` 作为变通方法。 ## 开发 ``` git clone https://github.com/ReshefElisha/jarvis-onshape-mcp cd jarvis-onshape-mcp uv sync export ONSHAPE_API_KEY=... export ONSHAPE_API_SECRET=... uv run onshape-mcp # 在stdio上启动MCP服务器 uv run pytest # 单元测试 ``` ## 致谢 脚手架（Onshape REST客户端 + HMAC身份验证，BTMFeature-134 / BTMParameterQuantity-147 / BTMIndividualQuery-138有效载荷构建器，以及第一版工具按基元的MCP表面）从 [hedless/onshape-mcp](https://github.com/hedless/onshape-mcp) 分叉而来 — 感谢hedless将其启动。 在此基础上构建的所有内容（说真话，视觉，实体发现，参数化变量工作室，FeatureScript编排，每个特性的几何差异，提示轮换，通过Claude Agent SDK的迭代代理托管，以及大部分当前的工具表面）都是在这里构建的。 有关完整线索，请参见 `NOTICE` 和 `git log` 。 ## 许可证 MIT。 见 `LICENSE`。