onshape-mcp：让智能体操作 CAD，先把写入边界画清楚

2026-10-19

工业智能, 工业软件

让助手在 Onshape 里画一个带孔支架，最容易误判的是“画出来了”这句话。API 返回成功、特征树没有报错、截图看起来像支架、导出的 STEP 能用于下游校核，是四种不同的检查。onshape-mcp 把对 Onshape 的访问接进 MCP，适合把这几步串成可检查的工程试验；它并没有替设计者决定尺寸、公差和制造工艺。

按本次选题提供的截至 2026 年 10 月 8 日信息，项目版本为 2026 年 8 月 7 日发布的 v0.5.2。仓库把自己定位为早期开发项目：可浏览文档、创建草图和拉伸等特征、查看 Part Studio 截图、导出 STL/STEP，也能通过 API 处理 FeatureScript；不同操作的可靠性并不相同。代码提供 Apache-2.0 或 MIT 双许可证选择。这里讨论的是在自己机器上运行的 MCP 服务连接 Onshape REST API，不是把模型文件交给某个公开的代管机器人。项目明确说没有公开托管的 MCP 端点，也没有公开 OAuth 代理；Streamable HTTP 可供自行部署，但仍属实验性，不能把示例地址当成可用服务。

一次请求究竟经过哪些层

推荐的入口是本地 stdio：MCP 客户端启动 npx --yes onshape-mcp，或启动从 Releases 下载的二进制文件。仓库示例覆盖 Claude Desktop、OpenCode，其他支持 stdio 的 MCP 客户端也可以接入。服务本身是 Rust 实现，内嵌一份 Onshape OpenAPI 描述；智能体先用 onshape_api_search 查操作，再用 onshape_api_explain 看路径、参数和请求体，遇到多态 BTType 结构时用 onshape_api_schema 查具体类型，最后才由 onshape_api_call 发请求。它没有把每个 REST 端点都包装成独立 MCP 工具。这个设计省了工具定义的上下文，但不会免去理解 CAD 对象和请求体的工作。

比如一句“在顶面建草图并拉伸”，实际需要定位文档 did、工作空间 wid、Part Studio 元素 eid，确定草图所在面，组织实体与约束，再添加后续特征。工具的 path_params 是独立的命名字段，不是让模型拼接整段 URL。草图文档给了一个很实在的陷阱：草图里标成 isConstruction: true 的线只作参考，不生成供普通拉伸使用的封闭区域；长度约束的 expression 要带单位，如 "50 mm"。请求 JSON 格式合法，并不等于草图可求解、轮廓可拉伸。默认基准面的标识也应针对当前元素查询，不能把某个例子的 ID 当作全局常量。

这就是“完整 REST API 有可能触达”和“已经有成熟的高层 CAD 工作流”之间的距离。README 列出草图、拉伸、旋转、扫描、圆角、基准面及导出等用途；但很多路径仍需模型逐步查端点和构造参数。FeatureScript 也是如此：仓库资料给出读取和更新 Feature Studio 内容的 API 方式，却指出 Feature Studio 的编译通知没有直接的 API 查询入口；若同文档的 Part Studio 导入了该脚本，可间接用 evalFeatureScript 的 notices 查看，或者回到浏览器里的通知面板核对。不能把“脚本已写入”报道为“编译通过”。

凭据留在本地，不等于没有泄露面

本地模式默认建议自己创建 Onshape OAuth 应用，把回调地址设为 http://localhost:18338/callback，再执行 onshape-mcp auth login。授权码由本机回调处理，项目不要求经过其公开代理；也支持 Onshape API access/secret key 作为替代。OAuth 的好处是授权可按 scope 管理，访问也可撤回。真正的权限仍取决于 Onshape 授权和文档共享设置，而不是聊天里写一句“只读”。

仓库认证文档说明，Unix 上 OAuth token 默认保存在 ~/.local/share/onshape-mcp/tokens.json，配置和 token 文件要求所有者读写权限（0600）；自动检测时，已有 OAuth token 优先于 API key。OAuth token 会刷新，文件里也可能保留后续刷新所需的客户端元数据。因此应把运行它的本机账户、备份和日志都纳入凭据边界。优先用配置或 ONSHAPE_MCP_AUTH__CLIENT_ID、ONSHAPE_MCP_AUTH__CLIENT_SECRET，不要把 secret 塞进命令行参数：仓库明确提醒后者可能进入 shell 历史或进程列表。MCP 的登录工具接口目前仍接受 client_secret 参数，也不宜让聊天记录或工具日志保存该值。

本地 stdio 能直接读写本机文件，用于导出文件、截图及 FeatureScript 文件引用；便利与文件访问风险是一体的。让测试进程在独立用户环境中运行，只给必需目录权限，尤其不要让它看到生产图纸库和通用云盘挂载。远程 HTTP 则是另一种边界：项目特意禁用了该传输中的 MCP 文件读写，不能拿 HTTP 连接去读客户端电脑上的路径；而自托管服务器的运营者会接触到该连接下的 Onshape 授权，先问清访问、保留和日志策略。README 还记录了 ChatGPT 连接已知失败的问题，试验环境应以本地 stdio 为准。

用“特征列表”验收，而不是用一次 200 响应验收

我会先挑一个无商业敏感信息的测试文档，做带安装孔的简易夹具：固定底板厚度、孔径和孔距，记录预期的特征顺序与数量，要求输出带孔的实体和 STEP 文件。第一轮只允许浏览：读取当前文档、Part Studio 元素及其特征，核对 did/wid/eid 和现存状态；再让助手提出要调用的操作及尺寸单位。第二轮才允许它在测试工作空间写入，每添加一项后读回 getPartStudioFeatures 的特征列表和 featureStates。该接口里的状态可显示 OK/ERROR 等，但不提供详细报错文本；有错误时再针对对应 featureId 用 evalFeatureScript 调 getFeatureStatus()，辨别是参数错误、特征重建错误，还是 Feature Studio 编译问题。

截图适合人工确认拓扑方向与孔位。onshape_screenshot 是包装 Part Studio 着色视图的便捷工具，可指定 front、top、isometric 等视角，并把 PNG 写到本地路径；它不是尺寸测量证据。STEP/STL 导出之后还应在独立查看器里检查实体数量、单位与外形尺寸；STL 是网格数据，不能据此证明参数化特征树正确。若做性能或成功率评价，记录每次的 API 调用顺序、读回的特征数量、错误状态和人工核验结果，比展示一张好看的等轴测图有用。

写入操作尤其要处理“不确定成功”。项目文档把 408、429 和部分 5xx 等响应归为 transient，但明确说 transient 不意味着可以安全重放：网关报错前，Onshape 一侧可能已经完成了添加特征。超时后先重新读取当前特征列表，检查名称、ID 和状态，再决定要不要补写；盲目重试可能得到两个重叠的拉伸。重新接续旧会话也一样，先核对当前文档，不把上轮聊天摘要当事实。

最小权限最好从系统外层落实：单独的测试文档或工作空间、按需授权的 OAuth scope、明确的写入窗口；删特征、覆盖 FeatureScript、修改共享设置以及导出敏感几何前，要求人看过目标 ID 和预期结果后确认。项目文档虽然设计了 read/modify/destroy 三档模式，却在实现清单中把权限模式和模式切换工具标为未实现。不要把规划中的开关误当作现成的强制保护。写错后的回退方案也要预先约定：保留未修改的基准版本，记录变更前特征列表，在 Onshape 中人工复核并恢复或重建测试分支；不要假定 MCP 帮你提供跨多个 REST 调用的原子事务或自动撤销。

这样的试验可回答一个具体问题：在给定图纸要求、授权边界与验收脚本下，智能体能否稳定生成可复核的 CAD 候选件。它还不能直接替车间决定材料、工装、加工路径和安全放行。上机制造之前，工程师仍要检查几何、配合、公差和导出文件。把 AI 放在 CAD 评估台上，而不是放在机床的启动按钮上，才是这个早期项目目前较合适的位置。

配图为概念示意。