MS-MCP

面向 Windows 与 BIOVIA Materials Studio 的外部 Model Context Protocol（MCP）服务器。它让 Codex 或其他 MCP 客户端通过官方 MaterialsScript 运行时执行建模、Forcite、DMol3、CASTEP、GUI 队列和结果读取，并提供本地 Dashboard。

当前版本：0.2.0。项目不是 BIOVIA/Dassault Systèmes 官方产品；使用前请确认 Materials Studio 许可证及 MaterialsScript 组件可用。

主要能力

• 检查 Materials Studio、RunMatScript.bat、工作区和会话状态。
• 创建/导入结构，维护当前 GUI 文档，并执行常用结构编辑。
• 执行 Forcite、DMol3、CASTEP 任务与预设工作流。
• 通过可选的 Materials Studio GUI 循环把脚本送入当前打开的项目。
• 从受限 HTTPS 白名单下载 CIF，并限制响应大小。
• 准备远程 CASTEP 任务，Dashboard 可通过 SSH 只读监控 Gateway 作业目录。
• 所有生成文件默认限制在独立工作区；任意 MaterialsScript 和外部输入默认关闭。

系统要求

• Windows 10/11（64 位）。
• BIOVIA Materials Studio，且已安装 MaterialsScript；必须能找到： MS_INSTALL_ROOT\etc\Scripting\bin\RunMatScript.bat。
• Node.js 20 或更高版本，包含 npm.cmd。
• Codex 或其他支持 stdio MCP 的客户端。
• 可选：Windows OpenSSH Client（只在远程 Dashboard 监控时使用）。

最快安装

下载 Release 压缩包或克隆仓库后，不要把项目放入随后会删除或改名的临时目录。推荐路径如 C:\Tools\MS-MCP。

1. 双击 Configure-MS-MCP.bat，逐项确认 Node、Materials Studio、工作区等路径。
2. 双击 Install-MS-MCP.bat，以 npm ci 安装锁定依赖并检查发布文件。
3. 双击 Test-MS-MCP.bat，验证路径、安全默认值和 MCP stdio 通信。
4. 打开生成的 config\codex-ms-mcp.local.toml，把完整内容合并到 %USERPROFILE%\.codex\config.toml。
5. 完全退出并重启 Codex，在 MCP 列表中确认 MS-MCP 可用。

完整逐步说明、路径示例和安装后修改方法见 安装与配置指南。

配置 BAT 会生成什么

Configure-MS-MCP.bat 是唯一推荐的本机配置入口，内部调用 PowerShell 完成验证和安全写入：

• config\ms-mcp.local.bat：供启动、测试、Dashboard、GUI 循环和 SSH 脚本统一读取。
• config\codex-ms-mcp.local.toml：供复制到 Codex 的 MCP 配置块。

这两个文件包含本机绝对路径，已由 .gitignore 排除，不能上传 GitHub。仓库只保留不含真实机器信息的 config\ms-mcp.example.bat、.mcp.example.json 和 codex-ms-mcp.toml.example。

必须根据机器修改的路径

变量/配置	含义	何时必须修改
NODE_EXE / command	node.exe 的绝对路径	Node 安装位置变化或换电脑
NPM_CMD	与 Node 配套的 npm.cmd	Node 安装位置变化
MS_INSTALL_ROOT	Materials Studio 安装根目录	版本、盘符或安装目录变化
MS_MCP_WORK_ROOT	可写的独立任务工作区	换电脑、迁移数据或调整存储盘
MCP args	本仓库 src\index.js	仓库移动、改名或重新解压
MCP cwd	本仓库根目录	仓库移动、改名或重新解压
MS_MCP_MODEL_ROOT	已有 Materials Studio 模型目录	仅使用 Chapter 3 同步时设置
MS_MCP_REMOTE_SSH_TARGET	user@host	仅使用远程监控时设置
MS_MCP_REMOTE_SSH_KEY	SSH 私钥绝对路径	使用非默认密钥或用户目录变化
MS_MCP_REMOTE_JOBS_ROOT	Linux Gateway 作业根目录	远端版本、用户或 Gateway 根目录变化

仓库移动后不要逐个修改启动脚本；重新运行 Configure-MS-MCP.bat，再用新生成的 TOML 更新 Codex 即可。

启动方式

MCP 服务器

正常情况下由 Codex 按 TOML 自动启动。调试时可运行：

Run-MS-MCP.bat

该进程使用 stdio 协议，命令窗口看似等待输入是正常现象；不要向 stdout 添加日志。

Dashboard

双击 Start-MS-MCP-Dashboard.bat，浏览器打开 http://127.0.0.1:4877/。端口可在重新配置时修改。MCP 也可在后台启动 Dashboard，但默认不会强制打开浏览器。

需要登录 Windows 后自动启动时，先完成配置与测试，再运行 Install-Dashboard-Autostart.bat。快捷方式使用相对仓库定位；若移动仓库，重新安装自启快捷方式。

Materials Studio GUI 循环

要把任务写入当前由用户打开的 Materials Studio 项目时：

1. 先运行 Configure-MS-MCP.bat。
2. 在 Materials Studio 中打开目标项目。
3. 从 Materials Studio 的脚本界面运行 materialscript\mcp_loop_gui.pl；或在正确的 Materials Studio 会话条件下使用 materialscript\start_mcp_loop.bat。
4. 队列位于 %MS_MCP_WORK_ROOT%\.mcp-queue，停止标记为 .mcp-queue\stop。

GUI 循环必须在 Materials Studio GUI 环境中运行，不能把普通 RunMatScript.bat 进程误当成已打开项目的 GUI 上下文。

远程 CASTEP Dashboard 监控（可选）

重新运行 Configure-MS-MCP.bat，填写 user@host 和远程 Gateway jobs 路径，然后运行 Setup-Dashboard-SSH.bat。脚本创建独立 Ed25519 密钥、把公钥加入远端 authorized_keys，并验证非交互登录。Dashboard 不保存服务器密码。

这只配置作业目录监控；Materials Studio Gateway、队列、许可证和计算核数仍需在 Materials Studio Job Control 中按实际服务器配置。

安全默认值

• MS_MCP_ALLOW_ARBITRARY_SCRIPT=0：禁用任意 MaterialsScript。
• MS_MCP_ALLOW_GUI_QUEUE=1：允许结构化 GUI 队列工具。
• MS_MCP_ALLOW_EXTERNAL_INPUTS=0：禁止读取工作区外输入。
• CIF 仅允许配置的 HTTPS 主机，默认最大 10 MiB。
• Dashboard 默认只监听 127.0.0.1；写操作默认关闭。启用写操作时必须配置至少 24 字符令牌。
• 工作区路径经边界与 junction/symlink 检查，防止任务越界写入。

更详细的部署原则见 LOCAL-HARDENING.md，漏洞报告见 SECURITY.md。

开发与验证

在已经加载正确环境变量的终端中：

npm ci
npm run check
npm run smoke
npm run security-smoke
npm run mcp-smoke

Windows 用户直接运行 Test-MS-MCP.bat 更简单，它会加载生成的本机配置。涉及真实 Forcite/DMol3/CASTEP 的计算仍应在授权的测试模型和服务器上单独验证。

仓库结构

MS-MCP/
├─ src/                         MCP 服务器与 MaterialsScript 生成逻辑
├─ materialscript/              Materials Studio GUI 循环
├─ GUI-Dashboard/               本地 Dashboard
├─ scripts/                     验证、解析、同步与远程准备脚本
├─ config/                      示例配置；本机生成配置不会上传
├─ docs/                        安装与配置文档
├─ examples/                    示例输入
├─ Configure-MS-MCP.bat         分步配置入口
├─ Install-MS-MCP.bat           锁定依赖安装
├─ Test-MS-MCP.bat              完整本机验证
└─ Run-MS-MCP.bat               手动 stdio 启动入口

GitHub 上传清单与排除项见 RELEASE-FILES.md。

常见问题

找不到 RunMatScript.bat：MS_INSTALL_ROOT 填得太上层或太下层。应直接指向包含 etc\Scripting 的 Materials Studio 版本目录，然后重新配置。

移动仓库后 Codex 启动失败：重新运行配置 BAT，并替换 Codex TOML 中旧的 command、args、cwd 与环境路径。

Node 可用但 npm.cmd 不存在：安装完整的 Node.js Windows 发行版，而不是只复制 node.exe。

Dashboard 可打开但没有结构/作业：先检查工作区与当前 session；远程作业还需要 SSH target、key 和 jobs root 三项同时有效。

MCP 修改不到当前 GUI 项目：确认 GUI 循环是在目标 Materials Studio 会话中运行，而不是只启动了独立 MaterialsScript 进程。

贡献与许可

提交 Issue/PR 前请阅读 CONTRIBUTING.md，不要提交许可证文件、真实结构数据、服务器地址、私钥、本机配置或计算输出。项目采用 MIT License。

致谢与视频教程

• 本项目初始代码基于 shenghhe-svg/shengh_he，感谢原作者的工作与分享。
• 安装、配置及使用视频教程可在抖音搜索：抖音号 Au.Tom，昵称 Dr.小叶。

独立的上游来源与教程声明见 NOTICE.md。