Content
# MS-MCP
An external Model Context Protocol (MCP) server for Windows and BIOVIA Materials Studio. It allows Codex or other MCP clients to execute modeling, Forcite, DMol3, CASTEP, GUI queue, and result reading through the official MaterialsScript runtime, and provides a local Dashboard.
> Current version: `0.2.0`. The project is not an official BIOVIA/Dassault Systèmes product; please confirm Materials Studio license and MaterialsScript component availability before use.
## Main Capabilities
- Check Materials Studio, `RunMatScript.bat`, workspace, and session status.
- Create/import structures, maintain current GUI documents, and perform common structure editing.
- Execute Forcite, DMol3, CASTEP tasks and preset workflows.
- Send scripts to the currently open project through an optional Materials Studio GUI loop.
- Download CIF from a restricted HTTPS whitelist and limit response size.
- Prepare remote CASTEP tasks, and the Dashboard can monitor the Gateway job directory through SSH read-only.
- All generated files are limited to independent workspaces by default; arbitrary MaterialsScript and external inputs are disabled by default.
## System Requirements
- Windows 10/11 (64-bit).
- BIOVIA Materials Studio with MaterialsScript installed; `MS_INSTALL_ROOT\etc\Scripting\bin\RunMatScript.bat` must be found.
- Node.js 20 or higher, including `npm.cmd`.
- Codex or other stdio MCP clients.
- Optional: Windows OpenSSH Client (only used for remote Dashboard monitoring).
## Quick Installation
Download the Release package or clone the repository, and do not put the project into a temporary directory that will be deleted or renamed later. Recommended path: `C:\Tools\MS-MCP`.
1. Double-click `Configure-MS-MCP.bat` to confirm Node, Materials Studio, workspace, and other paths.
2. Double-click `Install-MS-MCP.bat` to install locked dependencies and check release files using `npm ci`.
3. Double-click `Test-MS-MCP.bat` to verify paths, security defaults, and MCP stdio communication.
4. Open the generated `config\codex-ms-mcp.local.toml` and merge the complete content into `%USERPROFILE%\.codex\config.toml`.
5. Exit and restart Codex completely, and confirm `MS-MCP` is available in the MCP list.
For detailed step-by-step instructions, path examples, and post-installation modification methods, see [Installation and Configuration Guide](docs/INSTALLATION.zh-CN.md).
## What does the configuration BAT generate?
`Configure-MS-MCP.bat` is the only recommended local configuration entry, which internally calls PowerShell to complete verification and secure writing:
- `config\ms-mcp.local.bat`: unified reading for startup, testing, Dashboard, GUI loop, and SSH scripts.
- `config\codex-ms-mcp.local.toml`: MCP configuration block for copying to Codex.
These files contain local absolute paths, excluded by `.gitignore`, and cannot be uploaded to GitHub. The repository only retains `config\ms-mcp.example.bat`, `.mcp.example.json`, and `codex-ms-mcp.toml.example` without real machine information.
## Paths that must be modified according to the machine
| Variable/Configuration | Meaning | When to modify |
|---|---|---|
| `NODE_EXE` / `command` | Absolute path of `node.exe` | Node installation location changes or computer changes |
| `NPM_CMD` | Node-compatible `npm.cmd` | Node installation location changes |
| `MS_INSTALL_ROOT` | Materials Studio installation root directory | Version, drive letter, or installation directory changes |
| `MS_MCP_WORK_ROOT` | Writable independent task workspace | Computer changes, data migration, or storage disk adjustment |
| MCP `args` | `src\index.js` of this repository | Repository movement, renaming, or re-decompression |
| MCP `cwd` | Root directory of this repository | Repository movement, renaming, or re-decompression |
| `MS_MCP_MODEL_ROOT` | Existing Materials Studio model directory | Only set when using Chapter 3 synchronization |
| `MS_MCP_REMOTE_SSH_TARGET` | `user@host` | Only set when using remote monitoring |
| `MS_MCP_REMOTE_SSH_KEY` | Absolute path of SSH private key | Using non-default key or user directory changes |
| `MS_MCP_REMOTE_JOBS_ROOT` | Linux Gateway job root directory | Remote version, user, or Gateway root directory changes |
Do not modify startup scripts one by one after repository movement; re-run `Configure-MS-MCP.bat` and update Codex with the newly generated TOML.
## Startup Methods
### MCP Server
Normally started by Codex according to TOML automatically. For debugging, run:
```bat
Run-MS-MCP.bat
```
This process uses the stdio protocol, and the command window appears to be waiting for input, which is normal; do not add logs to stdout.
### Dashboard
Double-click `Start-MS-MCP-Dashboard.bat`, and the browser opens `http://127.0.0.1:4877/`. The port can be modified during reconfiguration. MCP can also start the Dashboard in the background, but it will not forcibly open the browser.
For automatic startup after Windows login, complete configuration and testing, then run `Install-Dashboard-Autostart.bat`. The shortcut uses relative repository positioning; if the repository is moved, reinstall the autostart shortcut.
### Materials Studio GUI Loop
To write tasks to the currently opened Materials Studio project:
1. Run `Configure-MS-MCP.bat`.
2. Open the target project in Materials Studio.
3. Run `materialscript\mcp_loop_gui.pl` from the Materials Studio script interface; or use `materialscript\start_mcp_loop.bat` under the correct Materials Studio session conditions.
4. The queue is located at `%MS_MCP_WORK_ROOT%\.mcp-queue`, and the stop mark is `.mcp-queue\stop`.
The GUI loop must run in the Materials Studio GUI environment and cannot mistake the ordinary `RunMatScript.bat` process for the opened project's GUI context.
### Remote CASTEP Dashboard Monitoring (Optional)
Re-run `Configure-MS-MCP.bat`, fill in `user@host` and the remote Gateway jobs path, then run `Setup-Dashboard-SSH.bat`. The script creates an independent Ed25519 key, adds the public key to the remote `authorized_keys`, and verifies non-interactive login. The Dashboard does not save server passwords.
This only configures job directory monitoring; Materials Studio Gateway, queue, license, and computing core number still need to be configured in Materials Studio Job Control according to the actual server configuration.
## Security Defaults
- `MS_MCP_ALLOW_ARBITRARY_SCRIPT=0`: Disable arbitrary MaterialsScript.
- `MS_MCP_ALLOW_GUI_QUEUE=1`: Allow structured GUI queue tools.
- `MS_MCP_ALLOW_EXTERNAL_INPUTS=0`: Prohibit reading external inputs to the workspace.
- CIF only allows configured HTTPS hosts, with a default maximum of 10 MiB.
- Dashboard listens only to `127.0.0.1` by default; write operations are disabled by default. When enabling write operations, a token of at least 24 characters must be configured.
- Workspace paths are checked against boundaries and junction/symlink to prevent task write overflow.
For more detailed deployment principles, see [LOCAL-HARDENING.md](LOCAL-HARDENING.md), and for vulnerability reporting, see [SECURITY.md](SECURITY.md).
## Development and Verification
In a terminal with correctly loaded environment variables:
```powershell
npm ci
npm run check
npm run smoke
npm run security-smoke
npm run mcp-smoke
```
For Windows users, directly running `Test-MS-MCP.bat` is simpler, which loads the generated local configuration. Calculations involving real Forcite/DMol3/CASTEP still need to be verified separately on authorized test models and servers.
## Repository Structure
```text
MS-MCP/
├─ src/ MCP server and MaterialsScript generation logic
├─ materialscript/ Materials Studio GUI loop
├─ GUI-Dashboard/ Local Dashboard
├─ scripts/ Verification, parsing, synchronization, and remote preparation scripts
├─ config/ Example configuration; local configuration generated will not be uploaded
├─ docs/ Installation and configuration documentation
├─ examples/ Example inputs
├─ Configure-MS-MCP.bat Step-by-step configuration entry
├─ Install-MS-MCP.bat Locked dependency installation
├─ Test-MS-MCP.bat Complete local verification
└─ Run-MS-MCP.bat Manual stdio startup entry
```
GitHub upload list and exclusions see [RELEASE-FILES.md](RELEASE-FILES.md).
## Frequently Asked Questions
**Cannot find `RunMatScript.bat`**: `MS_INSTALL_ROOT` is filled too high or too low. It should directly point to the Materials Studio version directory containing `etc\Scripting`, then reconfigure.
**Codex startup fails after repository movement**: Re-run the configuration BAT and replace the old `command`, `args`, `cwd`, and environment paths in Codex TOML.
**Node available but `npm.cmd` does not exist**: Install the complete Node.js Windows distribution, not just copying `node.exe`.
**Dashboard can be opened but no structure/jobs**: Check the workspace and current session; remote jobs also require SSH target, key, and jobs root to be valid simultaneously.
**MCP cannot modify the current GUI project**: Confirm the GUI loop is running in the target Materials Studio session, not just starting an independent MaterialsScript process.
## Contribution and License
Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting issues/PRs, and do not submit license files, real structure data, server addresses, private keys, local configurations, or calculation outputs. The project uses the [MIT License](LICENSE).
## Acknowledgments and Video Tutorials
- The initial code of this project is based on [shenghhe-svg/shengh_he](https://github.com/shenghhe-svg/shengh_he), thanks to the original author's work and sharing.
- Installation, configuration, and use video tutorials can be searched on Douyin: Douyin ID `Au.Tom`, nickname `Dr. Xiaoye`.
Independent upstream sources and tutorial statements see [NOTICE.md](NOTICE.md).
