CST-MCP
by woson-L
README.md
# CST-MCP — CST Studio Suite 2026 through the Model Context Protocol
[English](README.md) | [简体中文](README.zh-CN.md)
[](LICENSE)
[](pyproject.toml)
[](https://modelcontextprotocol.io)
[](#requirements)
[](docs/use/tool-catalogue.md)
[](https://github.com/woson-L/cst-studio-suite-mcp/actions/workflows/ci.yml)
An MCP server that drives **CST Studio Suite 2026** through CST's own automation API
(`cst.interface`, `cst.results`): modelling, materials, ports, boundaries, mesh, solver
selection, frequency range, monitors, solver runs, result reading and evidence export.
**84 tools · 14 categories · stdio transport · no network access.**
New here? **[Install](docs/start/install.md)** → **[Quick start](docs/use/quickstart.md)**
→ **[Verify with the demo project](docs/start/verify-with-demo.md)**.
---
## Origin
This server is a **refactor** of the CST MCP inside
[`Cai-aa/CAE-Agent-Hub`](https://github.com/Cai-aa/CAE-Agent-Hub) (`MCP/CST/`). That
project is MIT-licensed and its copyright notice is retained in [`LICENSE`](LICENSE).
| | Upstream | Here |
| --- | --- | --- |
| Tools | 51, in one 623-line `mcp_server.py` | **84 across 14 categories**, in a `cst_mcp/` package |
| Vendored runtime CLI | 824 files | none — a built-in command registry |
| Offline checks, CI | none covering this component | 9 gates on every push, Python 3.10 and 3.12 |
| Documentation, skills | one README; skills at the hub root | 17 documents, 2 bundled skills |
Added here: guard rails that refuse a history block CST would hang on, mesh sizing derived
from the smallest feature, project overwrite that does not strand a `Result/` directory,
and a port verdict instead of raw numbers.
**Full comparison: [Differences from upstream](docs/reference/differences-from-upstream.md).**
---
## Why this exists
A model with generic CST knowledge produces automation that *looks* right and fails in
specific, quiet ways. Every trap below was measured on CST 2026.2; the raw messages are
recorded in [`tests/evidence/known_failures.md`](tests/evidence/known_failures.md).
| Trap | What it looks like |
| --- | --- |
| **Evanescent port mode** | A waveguide port on a 1.6 mm microstrip cross-section had a **51.9 GHz cutoff** and a **6.2 kΩ** wave impedance at 2.4 GHz. S-parameters were referenced to 7623 Ω instead of 50 Ω and S11 was a flat **−0.6 dB** line — easy to mistake for an antenna. The solver had reported success. |
| **`Rebuild` inside a structure macro** | CST refuses it, and in testing the Design Environment was left **permanently unresponsive** — every later call hung. |
| **Library material + parameter change** | A library-loaded material does not survive save/reopen, so the next rebuild fails at the solid that uses it. A parameter sweep over such a project fails on **every** case. |
| **Overwriting a project by deleting the `.cst`** | A CST project is the file *plus* a companion directory holding `Model/` and `Result/`. Deleting only the file leaves the directory, and CST answers `The project directory … already exists and is non-empty`. Interactively that is the "delete the previous results?" prompt. |
| **Ports in a local coordinate system** | Endpoint coordinates are read as global `xyz`, so a `uvw` port silently lands somewhere else. |
The server turns those findings into guards, defaults and refusal messages, so the mistake
fails **loudly at the tool call** instead of quietly in the results.
## What it does
| Category | Tools | Covers |
| --- | --- | --- |
| `session` | 14 | health, detect, connect, project create/open/save/close, messages, raw VBA, history blocks, release |
| `parameters` | 4 | read, create, change, delete design parameters |
| `geometry` | 14 | brick, cylinder, sphere, cone, torus, elliptical cylinder, bond wire, boolean, transform, extrude, component |
| `material` | 3 | create, assign, load from library |
| `port` | 3 | discrete port, waveguide port, list ports |
| `solver` | 11 | solver choice, frequency range, FD/TD/eigenmode configuration, boundary, symmetry, background, run |
| `mesh` | 2 | mesh type and density, including `smallest_feature_mm` |
| `monitor` | 2 | add and list field monitors |
| `results` | 2 | result tree, read a 1D item |
| `verify` | 5 | S11, reference impedance, port info with verdict, energy budget, model audit |
| `export` | 3 | Touchstone, ASCII, summary JSON |
| `sweep` | 2 | parameter sweep: preview the case count, then run |
| `runtime` | 16 | built-in command bridge and typed wrapper generation |
| `meta` | 3 | list tools, full manifest, dynamic dispatch |
The full surface, with parameters and examples, is in
[`docs/mcp_tools.json`](docs/mcp_tools.json) — machine-readable, so another agent can read
it directly.
## Requirements
| | |
| --- | --- |
| **CST Studio Suite 2026** | Commercial software. **Not distributed here** — obtain and license it separately. Verified against the 2026.2 build. |
| **Operating system** | Windows. CST's automation API is Windows-only. |
| **Python** | 3.10 or newer, able to `import mcp`. The Python bundled with CST works. |
| **Network** | Not required. Configuration is read from a local `.env` file. |
## Quick start
```bash
# 1. find CST on this machine and write .env for you
python check_install.py --fix
# 2. verify: Python, packages, .env, the tool registry, and a real MCP handshake
python check_install.py
# 3. point your MCP client at it
# command: python
# args: ["<path to>\\mcp_server.py"]
# cwd: <path to this folder>
# 4. first call
# cst_health_check_tool {}
```
`check_install.py` exits `0` when ready, `1` on warnings, `2` on problems. The full
walkthrough — including what to do on a machine with no internet access — is in
[Installation](docs/start/install.md).
## Verify the installation
`check_install.py` proves the server *loads*. To prove it can actually **drive CST** —
open a project, build geometry, place a port, set the band, solve — hand the prompt below
to your AI. It installs the MCP and the two skills, then runs a verification task against
the demo project bundled in [`test_demo/`](test_demo).
Fill in the two placeholders and copy the whole block.
```text
Install this cst-studio-suite-mcp into my local harness (<your harness: dsh, codex,
WorkBuddy, ...>). The MCP path is: <the folder you installed it in>. Also install the two
skills in the skills folder: `cst-studio-suite-mcp` and `cst2026-simulation-execution`.
Then verify the installation through that MCP and those two skills. The verification task:
1. Open the project at `<MCP folder>\test_demo\test_demo.cst`.
2. Create a cube named box, 50 mm per side, material iron.
3. Create a thin sheet 2 mm below the box, 5 mm thick, 50 mm x 50 mm, material PEC.
4. Place an excitation port at the centre of that sheet: a discrete port connecting the
box and the sheet.
5. Set the frequency range to 0-100 MHz.
6. Solve for S-parameters.
When the install and the verification are done, report the files used, the steps taken and
the result.
```
A Chinese version of the same prompt is in [README.zh-CN.md](README.zh-CN.md).
What a pass looks like — and the two traps worth knowing, namely that the reference
impedance must read 50 Ω and that a 50 mm cube at 0–100 MHz is far below resonance so S11
near 0 dB is the correct answer — is in
**[Verify with the demo project](docs/start/verify-with-demo.md)**.
## What a session looks like
A complete worked run against live CST: build a model, configure the solver, solve, read
the result and export evidence — **30 tool calls, 0 failures**. Condensed:
```
cst_connect_tool {"launch_if_needed": true}
cst_new_project_tool {"project_type": "mws", "path": "…\\123.cst"}
cst_define_parameters_tool {"parameters": {"L": 50, "gap": 2, "tsheet": 5}}
cst_create_brick_tool {"component": "parts", "name": "box", "xrange": ["-L/2","L/2"], …}
cst_add_discrete_port_tool {"port_number": 1, "point1": [0,0,"-gap"], "point2": [0,0,"0"], "impedance": 50.0}
cst_set_solver_tool {"solver": "HF Frequency Domain"}
cst_set_frequency_range_tool {"fmin": 0, "fmax": 100, "unit": "MHz"}
cst_set_mesh_tool {"mesh_type": "Tetrahedral", "steps_per_wavelength": 8}
cst_save_project_tool {"path": "…\\123.cst", "overwrite": true}
cst_run_solver_tool {}
cst_read_s11_tool {"target_frequency": 100}
cst_read_reference_impedance_tool {}
cst_export_touchstone_tool {"filename": "…\\evidence\\123_s11", "impedance": 50.0}
```
The per-call record is in
[`tests/evidence/mcp_calls_123_report.md`](tests/evidence/mcp_calls_123_report.md).
## Documentation
Everything lives in [`docs/`](docs/), indexed in **[docs/README.md](docs/README.md)**.
| I want to | Read |
| --- | --- |
| Install on this machine | [Installation](docs/start/install.md) |
| **Prove it works end to end** | **[Verify with the demo project](docs/start/verify-with-demo.md)** |
| Hand the install to another AI | [Install via another agent](docs/start/install-via-agent.md) |
| Update an existing installation | [Upgrading](docs/start/upgrade.md) |
| Start using the server | [Quick start](docs/use/quickstart.md) |
| See what a session looks like | [Usage](docs/use/usage.md) |
| Browse the tools | [Tool catalogue](docs/use/tool-catalogue.md) |
| Know the rules that keep results trustworthy | [Rules](docs/use/rules.md) |
| Know what CST 2026.2 does not expose | [CST 2026.2 limits](docs/use/cst-2026-limits.md) |
| Know the server's own limits | [Known limits](docs/use/known-limits.md) |
| Add a tool or a tool family | [Extending](docs/extend/overview.md) |
| Understand the repository layout | [Layout](docs/dev/layout.md) |
| Run the verification | [Verification](docs/dev/verification.md) |
Documentation follows progressive disclosure: each file is short and links to its
siblings. Read only the file that answers the current question.
## Verification
The offline checks need no CST installation and run in CI:
```bash
python check_install.py --quick
python tests/smoke_registry.py
python tests/check_mcp_compliance.py
python tests/check_self_description.py
python tests/check_skill_tool_refs.py
python tests/check_skill_layout.py
python tests/check_docs_consistency.py
python tests/test_audit_regressions.py
python tests/test_port_info_verdict.py
python tests/test_save_overwrite.py
```
The live runners need a licensed CST and a spare ~2 GB of RAM; they are run by hand, and
their results are recorded in [Verification](docs/dev/verification.md).
## Repository layout
```
├── mcp_server.py MCP entry point, registry bootstrap, manifest builder
├── check_install.py installation acceptance check
├── cst_mcp/ server implementation, one module per tool category
├── skills/ two bundled agent skills
├── docs/ documentation, grouped index in docs/README.md
├── tests/ offline gates, live runners, curated evidence
└── .env.example configuration template (`.env` is never committed)
```
Full tree with per-file notes: [Layout](docs/dev/layout.md).
## Contributing
Read [`AGENTS.md`](AGENTS.md) first — it defines the documentation-sync requirement, and
it is enforced by the checks above. Then see [`CONTRIBUTING.md`](CONTRIBUTING.md).
Two ground rules, because the project drives a commercial simulator:
1. **A change includes its documentation.** If your change makes a document inaccurate,
that document is corrected in the same pull request.
2. **Do not document behaviour you have not verified.** Read the implementation, or
measure it against CST. Untested claims are removed, not merged.
## Security
The server runs locally, speaks MCP over stdio and makes no network requests. Report
vulnerabilities privately — see [`SECURITY.md`](SECURITY.md).
## License
[MIT](LICENSE) © 2026 Thompson Labs.
This project **does not distribute CST Studio Suite**, which is commercial software and
must be obtained and licensed separately. It calls the automation API that CST ships.
TDQS
C2.4/5.0
Scored across 84 tools
Disambiguation2/5
Several tools are explicit aliases or overlapping dispatch mechanisms (e.g., cst_runtime_detect_tool / cst_toolbox_detect_tool, cst_runtime_invoke_tool / cst_toolbox_invoke_tool, plus cst_call_tool and cst_run_vba_tool). While many geometry and solver tools are distinct, the runtime/toolbox/meta families create real confusion about which tool to call.
Naming Consistency4/5
Almost all tools follow a consistent cst_ prefix, snake_case, and _tool suffix pattern. The main deviation is the runtime vs. toolbox alias naming, which is still readable and predictable.
Tool Count1/5
With 84 tools, this server is far beyond the typical well-scoped range. The count is inflated by duplicate aliases and meta/runtime wrappers, making the surface heavy and hard to manage.
Completeness4/5
The tool set covers project lifecycle, geometry creation, materials, ports, boundaries, solver configuration, results reading, sweeps, and exports broadly. Some operations such as mesh generation are explicitly unsupported, leaving minor gaps rather than major dead ends.
Maintenance
ActivityMaintained
ResponsivenessNo issues