内容
# CST MCP / CST 自动化 MCP Server
[中文](#中文) | [English](#english)
## 中文
这是一个用于 **CST Studio Suite** 的轻量级 MCP server。它通过 Node.js stdio JSON-RPC 实现 MCP 协议，并通过 Windows PowerShell 调用 CST 的 COM 自动化接口，方便 Codex 或其他 MCP client 控制 CST 工程。
项目不依赖第三方 npm 包，下载后只需要 Node.js、PowerShell 和本机已安装的 CST Studio Suite。
### 功能
当前提供 9 个工具：
| 工具 | 作用 |
| --- | --- |
| `cst_ping` | 连接 CST COM，确认 CST 自动化接口可用 |
| `cst_open_project` | 打开已有 `.cst` 工程 |
| `cst_save_project` | 保存当前工程，或另存为指定路径 |
| `cst_run_vba_code` | 在当前工程中运行 VBA 代码 |
| `cst_run_vba_file` | 运行 `.bas` / `.vbs` 宏文件 |
| `cst_add_to_history` | 向 History List 添加一步 |
| `cst_set_parameter` | 写入或更新工程参数 |
| `cst_rebuild` | 重建模型 |
| `cst_start_solver` | 启动求解器 |
### 前置条件
- Windows
- CST Studio Suite 已安装，并支持 COM 自动化
- PowerShell 5.1 或更高版本
- Node.js 18 或更高版本
- 一个支持 MCP 的客户端，例如 Codex
> 如果直接运行 `node` 被 Windows Store 占位程序拦截，请安装 Node.js，或在 MCP 配置里把 `command` 改成真实的 `node.exe` 绝对路径。
### 下载
```powershell
git clone https://github.com/RFer-Dreaming/cst-mcp.git
cd cst-mcp
```
也可以在 GitHub 页面点击 **Code -> Download ZIP**，解压到本机目录。
### 配置 Codex MCP
把下面配置加入 Codex 的 MCP 配置文件，并把 `C:\\path\\to\\cst-mcp` 改成你本机实际路径：
```toml
[mcp_servers.cst]
command = "node"
args = ["C:\\path\\to\\cst-mcp\\cst-mcp-server.js"]
env = { CST_MCP_POWERSHELL = "powershell.exe" }
```
完整示例见 [codex-mcp-config.example.toml](codex-mcp-config.example.toml)。
### 基础测试
协议烟测不需要启动 CST，只检查 MCP server 是否能初始化并列出工具：
```powershell
npm run smoke
```
或直接运行：
```powershell
node scripts\smoke-test.js
```
如果你已经安装 CST，可以运行可选的 COM 连接测试：
```powershell
npm run smoke:cst
```
成功时会看到 `cst_ping` 返回的 JSON 结果。失败时通常需要检查 CST 是否已安装、COM ProgID 是否匹配、或 PowerShell 执行策略是否被系统策略限制。
### 常见问题
**1. 提示找不到 `node` 怎么办？**
安装 Node.js 18+，或在 `codex-mcp-config.example.toml` 中把 `command` 改为真实路径，例如 `C:\\Program Files\\nodejs\\node.exe`。
**2. `cst_ping` 连接失败怎么办？**
先确认 CST Studio Suite 可以正常打开。不同 CST 版本可能注册不同 ProgID，可以在调用工具时传入 `progId`，例如 `CSTStudio.Application.2025`。
**3. 这个项目会上传 CST 工程文件吗？**
不会。仓库用于分享自动化 MCP server，本项目默认忽略 `.cst` 工程、日志、临时文件和本地依赖目录。
**4. 是否需要安装 npm 依赖？**
不需要。`package.json` 只用于提供脚本命令和项目元数据。
### 许可证
MIT License. 见 [LICENSE](LICENSE)。
## English
This is a lightweight MCP server for **CST Studio Suite**. It implements MCP over Node.js stdio JSON-RPC and delegates CST operations to a Windows PowerShell helper that talks to CST through COM automation.
There are no third-party npm dependencies. After downloading the repository, you only need Node.js, PowerShell, and a local CST Studio Suite installation.
### Tools
The server exposes 9 tools:
| Tool | Purpose |
| --- | --- |
| `cst_ping` | Connect to CST COM and report basic status |
| `cst_open_project` | Open an existing `.cst` project |
| `cst_save_project` | Save the active project, or save it to a new path |
| `cst_run_vba_code` | Run VBA code in the active project |
| `cst_run_vba_file` | Run a `.bas` / `.vbs` macro file |
| `cst_add_to_history` | Add one step to the History List |
| `cst_set_parameter` | Set or update a project parameter |
| `cst_rebuild` | Rebuild the model |
| `cst_start_solver` | Start the solver |
### Requirements
- Windows
- CST Studio Suite with COM automation support
- PowerShell 5.1 or later
- Node.js 18 or later
- An MCP client, such as Codex
> If `node` is intercepted by the Windows Store app execution alias, install Node.js or use the absolute path to the real `node.exe` in your MCP config.
### Download
```powershell
git clone https://github.com/RFer-Dreaming/cst-mcp.git
cd cst-mcp
```
You can also use **Code -> Download ZIP** on GitHub and extract the folder locally.
### Codex MCP Configuration
Add this block to your Codex MCP config, replacing `C:\\path\\to\\cst-mcp` with your local checkout path:
```toml
[mcp_servers.cst]
command = "node"
args = ["C:\\path\\to\\cst-mcp\\cst-mcp-server.js"]
env = { CST_MCP_POWERSHELL = "powershell.exe" }
```
See [codex-mcp-config.example.toml](codex-mcp-config.example.toml) for a complete example.
### Smoke Tests
The default smoke test does not require CST. It only checks that the MCP server can initialize and list its tools:
```powershell
npm run smoke
```
Or run it directly:
```powershell
node scripts\smoke-test.js
```
If CST is installed, you can run the optional COM test:
```powershell
npm run smoke:cst
```
On success, it prints the JSON result returned by `cst_ping`. If it fails, check that CST is installed, the COM ProgID matches your CST version, and PowerShell execution is not blocked by system policy.
### Notes
- This repository is intended for GitHub sharing and direct download, not npm publishing.
- CST project files, logs, local dependencies, and temporary files are ignored by default.
- The default CST COM ProgID is `CSTStudio.Application`; versioned ProgIDs such as `CSTStudio.Application.2025` can be passed through tool arguments when needed.
### License
MIT License. See [LICENSE](LICENSE).
