Syscad

---

  syscad-mcp-server 是面向 MCP 协议的独立 SysCAD 服务封装。它依赖 sysplorer-mcp-server 提供的 Sysplorer 主会话管理能力，自身只暴露 SysCAD 相关能力；在调用 start 前，应确保 sysplorer-mcp-server 已启动并存在可连接的 Sysplorer 运行实例。

当前包结构按 sidecar 形态组织：

• main.py：顶层 launcher。只负责定位 bundle 根目录，并转入 syscad_mcp_server/main.py
• syscad_mcp_server/：全部 MCP 实现代码、测试和运行期目录
• resources/：顶层资源目录，包含 SysCAD quickref、rules、examples 和 resources_manifest.json
• install_mcp.ps1：Windows 安装脚本

其中，MCP 服务启动时会自动读取 resources/ 下的规则摘要，并把它们注入 MCP instructions。

系统要求

• Windows 10/11 64 位
• Sysplorer 2026a
• 支持 MCP 的客户端，例如 Claude Code、OpenCode、Codex

SysCAD 软件

SysCAD 是几何原型设计环境，可与 Sysplorer 联合实现几何设计-仿真-优化的迭代闭环。SysCAD 软件请联系我们获取。

安装方式

快速安装

本包根目录与 main.py 同级执行安装脚本即可：

Windows：

.\install_mcp.ps1

安装脚本会把 syscad_mcp 写入以下客户端配置：

• Claude Code: %USERPROFILE%\.claude.json
• OpenCode: %USERPROFILE%\.config\opencode\opencode.json
• Codex: %USERPROFILE%\.codex\config.toml

脚本写入的是当前 bundle 根目录下的 main.py 绝对路径，并显式传入：

• --mworks-install-dir
• --resources-dir

手动启动

若只想本地启动服务进行调试，可直接运行：

python .\main.py --mworks-install-dir "C:\Program Files\MWORKS\Sysplorer 2026a"

如果资源目录不在默认位置，可补充：

python .\main.py --mworks-install-dir "C:\Program Files\MWORKS\Sysplorer 2026a" --resources-dir "D:\path\to\resources"

启动参数

顶层 main.py 会把参数透传给 syscad_mcp_server/main.py。当前实际支持的启动参数如下：

• --mworks-install-dir：指定 Sysplorer 安装目录
• --resources-dir：指定资源目录，目录下应包含 resources_manifest.json 和 SysCAD 相关资源文件

MCP Tools

工具列表

当前服务共提供 6 个工具，与 sysplorer-mcp-server 提供的建模、仿真和资源检索能力不同，这 6 个工具只聚焦 SysCAD 侧的能力：启动与关闭 SysCAD、执行 SysCAD 内部 Python 脚本、同步参数，以及触发 Modelica 导出。它们适合承担整个 CAD 到系统模型流程中“几何建模与导出”这一段工作。

从用途上看，这些工具可以分为以下 3 类。

1. 会话准备与生命周期

工具英文名	工具中文描述	工具具体功能描述
health_check	健康检查工具	用于检查 SysCAD IPC named pipe 是否在线，是判断当前客户端能否和 SysCAD 建立通信的最轻量入口。若返回找不到 pipe，通常说明 MCP 服务本身已启动，但 SysCAD 尚未启动或尚未附着完成。
start	启动 SysCAD 工具	用于先附着到现有 Sysplorer 会话，再由 Sysplorer 拉起 SysCAD。它通常是所有 CAD 建模任务的第一步；如果复用了已有 Sysplorer 实例，返回中的 detail 可能为 false，但只要 ok=true，仍应按成功处理。
close	关闭 SysCAD 工具	用于通过 SysCADStarter.CloseSysCAD(force) 关闭 SysCAD。默认会尽量正常关闭；若存在未保存文档导致确认框阻塞，可传入 force=true 丢弃未保存修改并强制关闭。

2. 参数同步与导出

工具英文名	工具中文描述	工具具体功能描述
update_param	参数同步工具	用于触发 Sysplorer 到 SysCAD 的参数同步，使 Sysplorer 侧的设计参数、表达式或配置变更回写到当前 CAD 模型。适合在参数驱动建模、设计变量迭代以及重新导出前执行。
generate_mo	Modelica 导出工具	用于调用 SysCADStarter.GenerateMo() 触发 Modelica 导出。它只表示“导出请求已受理并入队”，不表示导出已经完成；调用前应尽量确保相关文档已保存，导出后再回到 sysplorer-mcp-server 侧继续做加载、检查、翻译或仿真验证。

3. 脚本化建模与自动化

工具英文名	工具中文描述	工具具体功能描述
run_script	脚本执行工具	用于在 SysCAD 内部 Python 环境中执行完整脚本文本，是几何建模、导入 CAD、分组、材质设置、标架与运动副创建等自动化任务的核心入口。

4. 典型调用顺序

1. 先调用 health_check 判断 SysCAD 是否已经就绪；若尚未就绪，则调用 start。
2. 使用 run_script 一次性完成几何、参数、分组和运动副相关操作，尽量不要把同一装配拆成多次异步脚本调用。
3. 如果 Sysplorer 侧参数发生变化，先调用 update_param 把参数同步到 SysCAD。
4. 调用 generate_mo 触发 Modelica 导出，再切回 sysplorer-mcp-server 侧继续做模型加载、检查、翻译或仿真。
5. 工作结束后，按需调用 close 关闭 SysCAD。

返回格式

它们全部返回统一 JSON 结构：

{
  "ok": true,
  "detail": {},
  "message": "",
  "error": "",
  "advice": ""
}

运行约束

• 本服务不会自行启动 Sysplorer 主会话，只会附着到已存在的 Sysplorer 运行实例。
• generate_mo 表示“导出请求已入队”，不表示导出已经完成。
• 编写 run_script 时，优先遵守 resources/syscad/quickref/02-syscad_python_api.md 与 resources/syscad/rules/syscad_workflow_rules.md。
• 涉及完整装配时，应尽量把几何、参数、分组和运动副放进一次 run_script 调用中完成。

验证安装

完成安装后，重启客户端并验证：

1. 在 Claude Code 中执行 /mcp list，确认存在 syscad_mcp
2. 或直接调用 health_check
3. 若返回 No SysCAD IPC pipe found，说明服务已启动，但 SysCAD 尚未启动；此时继续检查 Sysplorer 会话并调用 start

开发测试

当前自动化测试位于 syscad_mcp_server/tests/。在仓库根目录执行：

python -m pytest -q

真实环境 smoke test 默认跳过；若已配置好本机 Sysplorer / SysCAD，可设置 SYSCAD_RUN_LIVE_TESTS=1 后再运行。

案例

仓库内置了一个六自由度机械臂案例：samples/6dof-robot-arm-main。

这个案例展示了从 SysCAD CAD 模型到 Modelica 系统模型的完整样例链路，主要包含三部分：

• cad/：六轴机械臂的 SysCAD 源模型
• modelica/：导出的机械臂本体模型，以及面向“小球颜色分拣”的分拣系统模型
• scripts/：用于构建 CAD、运行分拣场景和导出验证报告的辅助脚本

从功能上看，这个案例可以用来演示六轴机械臂本体建模、抓取放置循环验证，以及单球、多球、感知噪声、执行误差和鲁棒性等分拣场景的系统级仿真与验证。

许可证

本项目采用 MIT 许可证授权，有关详细信息，请参阅 LICENSE 文件。