# cst-mcp 🛰️

**MCP server for CST Studio Suite — THz metamaterial absorber design, unit-cell automation & Floquet port control**

[English](#english) | [中文](#中文)

---

<a id="english"></a>
## ✨ What is this?

`cst-mcp` turns **CST Studio Suite** into an AI-controllable electromagnetic design lab through the
[Model Context Protocol](https://modelcontextprotocol.io). Point Claude/Cursor/DSH at it and drive
full-wave simulations conversationally:

- 🧱 **One-shot unit-cell builder** — MIM absorber stacks (square ring / patch / circular ring),
  auto-materializes Floquet ports and sets **1 mode by script** (~50× faster per point, no GUI clicks)
- 🎛️ **Floquet port suite with the *correct* 2026 API** — mode count / scan angles / polarization,
  all scriptable (`SetNumberOfModesConsidered`, uppercase `"Zmax"` …). Most public examples use a
  renamed legacy API that silently fails on CST 2026 — this server is verified against CST 2026.
- ⚡ **Absorber quick-design workflow** — set params → solve → full 200-pt absorption spectrum +
  A_peak / in-band A_min / ≥90 % bandwidth in one tool call
- 🔁 **Checkpoint-resume batch runner** — config fingerprints, PID lock, point-level watchdog that
  survives solver hangs and COM channel death (survived 2100+ unattended points)
- 📈 **Surrogate-model hooks** — millisecond spectrum prediction & inverse design TopK when a trained
  pipeline is provided
- 🩺 **Self-diagnosis** — CST error-log tail tooling and session restart tools for unattended runs

## 🚀 Quick start

```powershell
pip install -r requirements.txt          # mcp>=1.2,<2  (2.x removed FastMCP path!)
set PYTHONPATH=C:\PATH\TO\CST\AMD64\python_cst_libraries
python src/cst_absorber_mcp.py           # stdio MCP server
```

Register with your MCP client:

```json
{
  "mcpServers": {
    "cst-mcp": {
      "command": "C:\\CST\\Python\\python.exe",
      "args": ["path/to/src/cst_absorber_mcp.py"],
      "env": { "PYTHONPATH": "C:\\CST\\AMD64\\python_cst_libraries",
               "CST_MCP_WORKDIR": "D:\\cst_mcp_work" }
    }
  }
}
```

## 🧰 Tools (23)

| Family | Tools |
| :--- | :--- |
| Health | `cst_status` `cst_log_tail` `cst_session_restart` |
| Project | `cst_unitcell_build` `cst_project_open` `cst_param_set` `cst_param_list` |
| Floquet ports | `cst_floquet_set_modes` `cst_floquet_set_angles` `cst_floquet_set_polarization` `cst_port_modes_read` |
| Simulate | `cst_solve` `cst_get_absorption` `cst_read_sparams_offline` `cst_export_tree_csv` |
| Absorber flow | `absorber_quick_design` `absorber_batch` `absorber_progress` |
| Surrogate | `absorber_surrogate_predict` `absorber_inverse_design` |
| Docs | `doc_export_step` `doc_export_structure_png` |

*(see docstrings inside `src/cst_absorber_mcp.py` for exact signatures)*

## 📐 Verified reference results (real CST 2026 runs)

| Case | Result |
| :--- | :--- |
| Metal-ring narrowband (P65/L50/t8/h12/Rs10 Ω/sq) | A_peak = **0.87 @ 1.08 THz** |
| Script-set 1-mode vs default 18 modes | ~10 s/pt vs ~462 s/pt |
| Unattended batch | 2099 points, auto-heal from solver hangs |

## 📚 docs/

- `reflect_tables.json` — reflected method tables of key COM objects (model3d 387 methods,
  FDSolver 112, Material 589, Port 75, FloquetPort 25 …) discovered on CST 2026
- `results_api_table.json` — offline S-parameter reading API surface

## ⚠️ Notes

- Windows only (COM automation); CST license required.
- Keep project paths **ASCII-only** — non-ASCII paths break `project.save()` (encoding bug).
- Use mcp SDK **1.x**; v2.0 dropped the FastMCP import path.

<a id="中文"></a>
## 中文简介

把 CST Studio Suite 变成 AI 可对话操控的电磁设计实验室：一句话建单元胞（方环/贴片/圆环 MIM）、
脚本化设置 Floquet 端口模数/扫描角/极化（CST2026 正确 API，全网首发实测）、一键求解并返回
200 点吸收谱与指标、断点续跑批量仿真（经 2100+ 点无人值守验证）、可选代理模型毫秒级预测与逆向设计。
安装与配置见上方英文区；工具签名见源码 docstring。

## License

MIT — see [LICENSE](LICENSE)。CST Studio Suite 是 Dassault Systèmes 产品，本项目仅通过官方 Python 接口驱动。