SysCAD MCP Server

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. 典型调用顺序

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

验证安装

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

在 Claude Code 中执行 /mcp list，确认存在 syscad_mcp
或直接调用 health_check
若返回 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 文件。