# cst-sim-agent

[中文版](README_CN.md)

A Claude Code plugin that turns [CST Studio Suite](https://www.3ds.com/products/simulia/cst-studio-suite) into a conversational electromagnetic simulation assistant via MCP.

**AI for Science (AI4S) is pushing AI from "chatting" toward "actually doing research and engineering."**

For electromagnetic simulation, a real bottleneck is this: an agent needs to operate professional software like CST, yet cannot communicate with it smoothly — even after a successful connection, it doesn't know the correct VBA method names or the CST-adapted Python idioms. General-purpose LLMs were never trained on how to operate CST; writing raw code produces invented phantom methods, and a single `(10091)` error can waste hours.

cst-sim-agent solves this with a three-layer design: **an MCP toolset** lets natural language drive modeling → material assignment → port setup → solving → result reading; **an embedded domain knowledge base** (an 8-domain VBA syntax library, 158 official examples, pitfall checklists) lets the agent look things up and use them directly — without re-reading technical documentation, re-learning interface settings, or even re-learning physics when switching application domains, the way a human engineer would have to; **constraint hooks** check the library before writing VBA and check the CST message window after execution, guarding against hallucination and silent failure. In end-to-end validation practice, this mechanism **completed close to 20 multi-method simulation projects in 2 days** (modeling, method switching, parametric comparison) — the same output would take weeks through a purely manual workflow. More importantly, the mechanism **self-evolves with your use** — every pitfall you hit and every experience you validate is guided back into the knowledge base at wrap-up, forming a "use → consolidate → reuse" loop: the more you use it, the smarter it gets, and the smoother similar tasks run.

**Our vision** is to bring AI for Science onto engineers' and researchers' simulation workbenches — not to replace engineers, but to extend humanity's ability to do science through physical simulation: leave the repetitive, mechanical operations and cross-domain learning to the agent, keep humans in electromagnetic design and physical judgment, and free human engineers.

## Features

| Category | Tools |
|----------|-------|
| Connection & project | `cst_connect` / `cst_disconnect` / `cst_create_project` / `cst_open_project` / `cst_save_project` / `cst_close_project` / `cst_get_project_state` / checkpoint series |
| Geometry query | `cst_query_geometry` / `cst_get_model_tree` / `cst_get_materials` |
| Modeling primitives | `cst_create_brick` / `cst_create_cylinder` / `cst_create_cone` / `cst_create_sphere` / boolean operations / transforms / delete |
| Materials | `cst_create_material` / `cst_create_sit_material` (SIT impedance table) / `cst_set_material` |
| Solver | `cst_set_frequency_range` / `cst_start_solver` / `cst_is_solver_running` / `cst_stop_solver` / `cst_run_simulation` / `cst_parameter_sweep` |
| SBR/RCS | `cst_configure_sbr` / `cst_run_sbr` / `cst_farfield_read` |
| VBA/scripting | `cst_execute_vba` (arbitrary CST VBA) |
| Operations | `cst_get_messages` / `cst_check_status` / `cst_detect_popups` / `cst_dismiss_popup` |

## Maturity & verification

This plugin grew out of several CST automation engineering projects, iterated internally over multiple rounds, and passed an independent blind acceptance test before its first public release. Verified coverage: installation & hooks, connecting to a real CST instance, the official patch-antenna tutorial end to end, knowledge base & residue review. Not yet fully covered: multi-version CST compatibility, more complex models, and more tool combinations — these need community developers to validate together.

The end-to-end official example (circular patch antenna, 2–3 GHz) ran through: S11 resonance at **2.40 GHz**, matching CST's official tutorial reference value (≈2.4 GHz). See the [verification report](docs/verification-report.md). Watch the demo video on Bilibili: https://www.bilibili.com/video/BV1CC896qEAt/

Technology selection and design decisions (VBA channel primary, official API auxiliary) are documented in the [architecture document](docs/architecture.md).

## Prerequisites

- **Windows** (CST's COM interface lives on Windows)
- **CST Studio Suite 2024/2025/2026** (2026 recommended; older versions should work but are not individually verified)
- **Python 3.10+** (including the Windows `py` launcher — ships with the official Python installer; the MCP server starts via `py -3` and does not depend on `python` being on PATH)
- Python dependencies: `pip install -r requirements.txt` (`mcp`, `pywin32`)

CST official Python library path resolution (`src/controller.py`, `src/connection.py`):
1. Read the environment variable **`CST_INSTALL_DIR`** first (points to the CST installation root, e.g. `C:\Program Files\CST Studio Suite 2026`)
2. Otherwise auto-detect common install locations (`C:\Program Files\CST Studio Suite 202x`, etc.)

> Setting the `CST_INSTALL_DIR` environment variable is recommended for the most reliable path resolution.

## Installation

```bash
# Option 1: install from the GitHub marketplace (available after publishing to GitHub)
claude plugin marketplace add https://github.com/valenZW/cst-sim-agent
claude plugin install cst-sim-agent@cst-sim-agent

# Option 2: install from a local directory (development / offline)
claude plugin marketplace add /path/to/cst-sim-agent
claude plugin install cst-sim-agent@cst-sim-agent
```

Restart Claude Code after installation, and confirm the plugin is loaded via `/plugins`; then `cst_*` tools are callable directly in conversation.

> The plugin root ships its own `.claude-plugin/marketplace.json` — it is itself a marketplace (source=./). `directory`-type marketplaces load in place without copying.

## Hook mechanism (injected on demand)

The plugin declares 4 hooks in `hooks/`; they only inject reminders when `cst_*` tools are actually called in a session:

| Hook | Trigger | Reminder |
|------|---------|----------|
| `pre_vba` | just before `cst_execute_vba` | check the syntax library before writing VBA (per-domain sniffing for precise hints) |
| `post_vba` | after `cst_execute_vba` | check the CST message window + look up the library before writing next |
| `post_mutate` | after geometry/material-changing tools | save immediately after critical operations |
| `stop_check` | at wrap-up of a CST-touching session | force experience consolidation (into the knowledge base) |

All hooks only remind, never block (they return no `permissionDecision`).

## Self-evolution: the more you use it, the smarter it gets

The embedded knowledge base is both the initial knowledge and the accumulation container:

- **Use**: the agent performs modeling, solving, and result analysis in each simulation;
- **Consolidate**: at session wrap-up, the `stop_check` hook forces a reminder to write this session's pitfalls and validated conclusions into `references/` (pitfall checklist, VBA syntax library, experience manual);
- **Reuse**: next time a similar problem appears, the `pre_vba` / `post_vba` hooks guide you to hit the library first, instead of re-treading the same pitfall.

This forms a "use → consolidate → reuse" self-evolving loop — the plugin keeps accumulating domain experience with use, and similar tasks run more smoothly each time. The knowledge base is under your control (`skills/cst-expert/references/`) — what gets consolidated and what gets kept is entirely your call.

## Skill knowledge base

Bundled with the plugin in `skills/cst-expert/references/`:

- `vba-rules.md` — four iron rules, code comment conventions, MCP troubleshooting
- `official-docs.md` — official documentation map & lookup techniques
- `case-study-flow.md` — official example deep-learning workflow
- `common-pitfalls.md` — general pitfall checklist (port / mesh / solver / API traps)
- `best-practices-template.md` — blank incremental-experience template (for your own additions)
- `knowledge/` — VBA syntax library (8 domains), 158 official-example index, 35 deep dives, experience manual

## Directory structure

```
cst-sim-agent/
├── .claude-plugin/plugin.json   # plugin manifest
├── .mcp.json                    # MCP server definition (cst-sim)
├── src/                         # MCP server implementation
│   ├── server.py                # tool registration (FastMCP)
│   ├── controller.py            # unified controller (facade)
│   ├── connection.py            # CST process/project lifecycle
│   ├── dezip.py                 # CST DE-ZIP container parser
│   ├── popup_utils.py           # popup detect/dismiss
│   ├── popup_watchdog.py        # popup watchdog
│   └── version_manager.py       # checkpoint versioning
├── hooks/                       # constraint mechanization hooks
├── skills/cst-expert/           # domain-knowledge skill
└── requirements.txt
```

## FAQ

- **`cst_connect` fails / tools don't appear**: first look at the Claude CLI MCP log (`Server stderr` inside `%LOCALAPPDATA%\claude-cli-nodejs\Cache\<workdir-encoded>\mcp-logs-*.jsonl`); don't guess.
- **Tool reports CST not found**: confirm `CST_INSTALL_DIR` is set, or that CST is installed in a standard location.
- **`.cst` won't open**: `.cst` is CST's private DE-ZIP container; Python's `zipfile` can't open it — use `src/dezip.py`.
- **SBR results all zero**: check geometry material first — STEP-imported geometry defaults to a scatter-transparent material; assign PEC / dielectric before expecting scattering.

## Contributing

We welcome community validation and improvement: report issues, submit code, add knowledge-base experience. Development and submission conventions are in [CONTRIBUTING](CONTRIBUTING.md); community behavior is governed by the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md); security vulnerability reporting is in [SECURITY](SECURITY.md). Version history is in [CHANGELOG](CHANGELOG.md).

## License

[Apache License 2.0](LICENSE)