cst-sim-agent

中文版

A Claude Code plugin that turns 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.

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

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

# Option 1: install from the GitHub marketplace (available after publishing to GitHub)
claude plugin marketplace add https://github.com/<your-name>/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; community behavior is governed by the CODE_OF_CONDUCT; security vulnerability reporting is in SECURITY. Version history is in CHANGELOG.

License

Apache License 2.0