# CST MCP Server(native / 跨版本版)

放进 Claude Code(或任何 MCP 客户端)后,你用**自然语言**描述天线,模型照 `cst-design` skill 的纪律调本 server 的工具,
在 CST Studio Suite(Microwave Studio)里**真的建模、求解、出结果**。

与 [hfss-mcp-native](../HFSS_Agent/hfss-mcp-native) 同构(同一套 server 壳、skill 分层、设计卡片库与指标驱动闭环),
驱动对象换成 CST。

> 标准 **MCP stdio server**(官方 `mcp` SDK),协议层不绑客户端。下文以 Claude Code 为例。

**目录**:[怎么连 CST](#怎么连-cst为什么能跨版本) · [能做什么](#能做什么73-个工具) · [skill 层](#skill-层三个) · [已验证](#已验证) · [安装](#安装) · [配置--用法](#配置--用法) · [代码结构](#代码结构) · [已知限制](#已知限制) · [真机踩坑](#真机踩坑已在工具内兜底)

## 怎么连 CST(为什么能跨版本)

- 连接 = `win32com.Dispatch("CSTStudio.Application.<年份>")`,**不依赖** CST 自带的 `cst.interface` / `cst.results`
  (那两个库随 CST 版本和 Python 版本绑定)。
- CST 的工程 COM 对象没有 typeinfo、查询方法大量带 ByRef 出参,win32com 直接调够不着。所以统一走 CST 自己的 VBA:
  - **写模型 = 历史树**:每个建模工具生成一段 `With Brick … .Create End With` 这类宏录制同款 VBA,
    包进临时 `.bas` 宏里调 `AddToHistory`,再用 `RunScript` 执行——失败时能拿到 **CST 的原文报错**
    (直接调 `AddToHistory` 只会返回 False)。模型因此天然参数化:改参数 → Rebuild → 几何跟着变。
  - **读模型/结果 = 查询宏**:临时宏把结果 `Print` 到文件再读回,ByRef 出参、数组、结果树遍历都能用。
- 这套 VBA 接口(Brick / Port / Monitor / Solver / FarfieldPlot / TOUCHSTONE / Resulttree…)是 CST 十几年来的稳定接口,
  所以方案本身不绑版本;**但目前只在 2026.1 上真机验证过**(见[已验证](#已验证))。

## 能做什么(73 个工具)

| 域 | 能力 |
|---|---|
| **会话** | 启动/关闭 CST(可指定版本;自动识别真装着的版本)、新建工程(**天线模板**:mm/GHz/ns + 真空 + 六面 expanded open + 时域)、打开/保存 .cst、单位 |
| **参数** | 批量建/改参数(改完自动 Rebuild,失败给原因)、列参数、删参数(被引用的拦住) |
| **几何** | brick / cylinder(圆管)/ cone / sphere / 多边形拉伸 / 零厚矩形面 / 任意 3D 多边形面;布尔 并/差(可保留工具体)/交;平移·旋转·镜像(带复制 = 线阵/环阵/对称件);删除/改名/换材料 |
| **材料** | 内置常用板材/金属表(FR-4、Rogers RO4003C/RO4350B/RO3003/RT5880/RT6010、F4B、PTFE、铜/铝/金/银…),几何工具里写名字**自动加载**;按数值自建(εr/tanδ/σ) |
| **边界/环境** | 频率范围、六面边界 + 对称面(electric/magnetic)、背景材料与留白 |
| **馈电** | 波导端口(Free 坐标)、**微带一步端口**(按 w/h 自动定端口尺寸)、**同轴探针一步馈电**(同轴 + 地板开孔 + 基板让位 + 端口)、离散端口(集总,间隙馈电);列/删端口 |
| **监视器** | 远场(多频点)、E/H/表面电流/功率流等场监视器;列/删 |
| **求解** | 时域 / 频域 / 积分方程 / 本征模切换与设置、网格密度、**网格数预估**、阻塞求解(完成自动存盘 + 回报日志里的 error/warning + **已知问题提示**) |
| **结果** | S 参数(Touchstone 导出并**重归一到 50Ω**;每端口按连续 −10dB 段分组的谐振/带宽/Zin,多端口传输)、VSWR + Zin(R+jX)+ VSWR<2 频段、任意 1D 结果曲线、结果树列表、Touchstone 导出 |
| **远场** | 一次取:峰值增益与方向 / 法向增益 / 前后比 / E、H 面 HPBW / 轴比与旋向 / 交叉极化 / 辐射与总效率;方向图切面曲线(自动 CSV);**轴比 vs 频率 + 3dB 轴比带宽** |
| **参数扫描** | server 侧循环:每点改参→重建→求解→当场提取 S 参数 + 远场指标;单点失败不中断;结果表 + CSV |
| **优化** | CST 内置优化器(Trust Region / Nelder-Mead / CMA-ES / GA / PSO),S 参数 dB 目标 |
| **自检/诊断** | 全景摘要、实体包围盒、**求解前自检**(端口/频率/远场监视器/介质穿模/金属悬空/退化实体)、**3D 视图截图**(模型用 Read 看图核几何)、历史树列表(含每步 VBA)、求解日志 |
| **辅助设计** | `search_designs` / `list_design_cards` / `read_design_card` 检索设计卡片取起手尺寸;`check_design_targets` 实测 vs 目标对标(闭环终止门) |
| **万能口** | `run_history_vba`(写进历史树的任意 CST VBA)、`run_vba_query`(不进历史的查询/后处理)——Floquet 端口、平面波、集总元件、曲线扫掠等都能补 |

## skill 层(三个)

MCP 工具是"手",skill 是"怎么正确用手"的纪律。三个 skill 各管一段,既能 `/名字` 直接点,也会按 description 自动匹配。

| 斜杠命令 | 什么时候用 | 它管什么 |
|---|---|---|
| **`/cst-design`** | 建几何、加端口、跑 S 参数/远场、扫参优化 —— **天线活儿的默认入口** | 读图解析 → 显式规划 → 坐标/层叠约定 → 求解前三重自检(bbox + 截图 + check_model)→ 馈电/远场/扫参/优化套路 → 指标驱动设计闭环 → 原生 VBA 写法 |
| **`/cst-search`** | 要找文献、"这类天线别人怎么设计的"、给了 PDF 要提炼 | 指标 → 英文检索式 → 五道筛选门 → 交回原文库精读 → 结构理解表交用户确认 |
| **`/cst-stackup`** | 丢来板厂叠层表(StackUp Report)、"按这个叠层建板子" | dump 表格 → 解析行业约定 → 总厚自校验 → 出层表确认 → 全参数化建模 |

`cst-design` 下三个库(随用变厚):

| 目录 | 装什么 | 判据 |
|---|---|---|
| `design/` | 可缩放的设计数据:闭式公式 > λ₀ 归一化常数 > 报告性能与出处(与仿真软件无关,可与 HFSS 版互通) | 换个频率/εr 还用得上 |
| `knowledge/` | 建模排错经验:CST 通用坑(`_general.md`,条条真机踩过)、优化方法论、按天线类型的机理与陷阱 | 换一篇同类但结构不同的论文还用得上 |
| `papers/` | 文献原文读法 `_HOWTO.md`(随分发)+ 个人原文索引与 PDF(不分发) | 卡片只够选型,要建就回原图 |

## 已验证

**真机:CST Studio Suite 2026.1(2026-09-22)**,经 MCP stdio 实跑:

| 案例 | 结果 |
|---|---|
| 2.45GHz inset 馈电贴片(FR4,微带波导端口) | 谐振 2.433GHz(闭式公式目标 2.45,−0.7%)、S11 −40dB、Zin 50.6Ω、带宽 2.8%、增益 3.3dBi、效率 47% |
| 同尺寸探针馈电贴片(`create_coax_feed`) | 谐振 2.417GHz、S11 −31.5dB、Zin 50.4Ω、增益 3.7dBi、前后比 14dB、HPBW 89°/92°、效率 51% |
| 半波偶极子(离散端口 73Ω) | 谐振 2.35GHz、Zin 70.9Ω、带宽 14.6%、增益 2.09dBi、效率 97% |
| 参数扫描(inset 深度 2 点)| 每点 ~21s,S 参数 + 远场指标逐点落表 |
| 内置优化器(Trust Region,单变量 L) | 8 次评估内把谐振从 2.431 推到 2.441GHz,约 2 分钟 |

- 其余工具(各几何图元、布尔、变换、材料、边界/背景、频域求解器与四面体网格、场监视器、端口增删、单位切换、
  历史树、截图、原生 VBA 两个口)在同一版本逐个调通。
- **协议层**:求解进行中 `tools/list` 0.004s 返回、纯本地工具(卡片检索)不排队;cwd 设为不可写的 `C:\Windows\System32`
  时 server 正常起来(目录自动退到用户目录)。
- **跨版本:未实测**。本机注册表里有 2022 / 2025 的 ProgID,但对应安装已卸载(exe 不存在),无法验证。
  方案只依赖 CST 长期稳定的 VBA 对象,预期老版本可用;若某个 VBA 写法在老版本不认,工具会原样返回 CST 报错
  (单位、网格设置已带老 API 兜底)。欢迎在其它版本上跑一遍反馈。

## 前置要求

- **Windows**(win32com / pywin32)。
- **CST Studio Suite**(本机实测 2026.1),license 可用、能正常手动启动。
- **Python 3.10+**(`mcp` 要求);建议虚拟环境。
- **Claude Code**(`claude` CLI 在 PATH);或其它支持 MCP stdio 的客户端。

## 安装

### 1. 装依赖

```powershell
cd D:\workspace\vscode\CST_MCP
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt    # 只有 mcp + pywin32
```

> ⚠️ `install.py` 会把"**当前正在跑它的那个 python 的绝对路径**"写进 MCP 配置。用哪个 python 装依赖、跑 install.py,
> server 以后就用哪个。

### 2. 自检(不启 CST)

```powershell
python smoke_mcp.py        # 看到 SMOKE OK = 依赖装好、73 个工具能注册、协议往返干净
```

### 3. 注册给 Claude Code

```powershell
python install.py                          # 只预览:打印 .mcp.json 块 + claude mcp add 命令 + 本机检测到的 CST 版本
python install.py --project D:\my\project  # 方式 A(推荐先用):写 .mcp.json + .claude/skills/ 三个 skill + settings 确认规则
python install.py --skill-user             # 方式 B:skill 装到 ~/.claude/skills/,再复制运行打印出的 claude mcp add 命令
```

方式 A 会写(已存在则合并,不覆盖):
- `<项目>\.mcp.json` ← MCP server 注册(名字固定 `cst-agent`)
- `<项目>\.claude\skills\cst-design|cst-search|cst-stackup\` ← skill(已存在的 `INDEX.md` 不覆盖,保护你攒的条目)
- `<项目>\.claude\settings.json` ← 给 `run_solver` / `run_parameter_sweep` / `run_optimizer` 加"执行前确认"

> 本脚本**绝不改全局 `~/.claude.json`**。

### 4. 生效 + 验证

1. **重启 Claude Code**,`/mcp` 应看到 **`cst-agent`**。
2. 说一句"用 CST 建一个 2.45GHz 微带贴片,跑 S11 和增益",Claude 会走 `cst-design` skill 建模、自检、求解、出结果。

## 配置 & 用法

- **连哪个版本**:env `CST_VERSION`(install.py 写入本机真装着的最高版本);对话里 `open_cst(version='2025')` 可覆盖。
- **license**:install.py 会把本机的 `CST_LICENSE_SERVER` / `DSLS_CONFIG` 等(若有)带进 server env;缺了按你平时启动 CST 的方式补。
- **工程 / 导出**:`.cst` 默认存 server cwd 下 `projects/`,Touchstone/方向图 CSV/截图存 `exports/`
  (`CST_PROJECTS_DIR` / `CST_EXPORTS_DIR` 覆盖);cwd 不可写时自动退到 `~/.cst-agent/`。
- **临时宏**:放 `%TEMP%\cst-agent\vba\`(`CST_AGENT_TMP` 覆盖),跑完即删。
- **设计卡片目录**:`CST_DESIGN_DIR` → 项目 `.claude/skills/cst-design/design` → `~/.claude/skills/cst-design/design` → bundle 内。
- **阻塞操作的确认**:stdio 下进程内确认已关,由客户端权限系统拦(方式 A 已写好规则)。

**换别的 MCP 客户端**:`python install.py` 打印的 `command` / `args` / `env` 三样通用。会丢两样 Claude Code 专属能力:
skill 不会自动加载(把 `skill/cst-design/SKILL.md` 放进那个 agent 的 system prompt 当指南;`design/` 卡片仍经 MCP 可取)、
确认门要靠客户端自己的工具授权。

## 代码结构

```
cst_mcp_server.py    MCP stdio 入口:stdout 隔离、常驻 ctx(app / project COM 句柄)、COM 专用单线程
tools/__init__.py    工具注册表(@tool)+ dispatch:工程存活检查、确认门、参数名纠错提示、trace 落盘
tools/_vba.py        ★ 与 CST 交互的唯一底层:临时宏 RunScript、AddToHistory 包装(拿原文报错)、查询宏、表达式/单位换算
tools/session.py     启动/关闭、已安装版本识别、新建(模板)/打开/保存工程、单位
tools/parameters.py  参数 + Rebuild
tools/materials.py   内置材料表 + 自动加载 + 自建材料
tools/geometry.py    图元 + 实体查询(bbox/材料)
tools/booleans.py    布尔 + 删除/改名/换材料
tools/transforms.py  平移/旋转/镜像(复制阵列)
tools/setup.py       频率范围、边界/对称面、背景
tools/ports.py       波导/微带/离散端口、同轴一步馈电
tools/monitors.py    远场/场监视器
tools/solver.py      求解器/网格/网格预估/求解/日志解析与提示
tools/results.py     结果树、1D 曲线、Touchstone 解析、S 参数指标
tools/farfield.py    远场点列取样 → 增益/HPBW/前后比/轴比/交叉极化/效率,方向图,AR vs f
tools/parametrics.py 参数扫描(server 侧循环)
tools/optimization.py CST 内置优化器
tools/diagnostics.py 全景摘要、历史树、求解前自检、截图
tools/design.py      设计卡片检索 + 对标门(纯本地,不排 COM 队列)
tools/vba_tools.py   原生 VBA 两个口
trace.py             每次工具调用一条 JSON line(traces/)
install.py           打印/写入 MCP 配置 + 安装 skill
smoke_mcp.py         不启 CST 的 stdio 冒烟
skill/cst-design/    建模纪律 skill(SKILL.md + design/ + knowledge/ + papers/_HOWTO.md)
skill/cst-search/    文献检索 skill
skill/cst-stackup/   PCB 叠层还原 skill
```

## 已知限制

1. **不能接管已在运行的 CST**:CST 不注册进 ROT,`GetActiveObject` 连不上。`open_cst` 每次新起一个 CST 进程;
   要继续手动开着的工程,先在那边存盘关闭,再 `open_project`。
2. **求解无法中途中止**(阻塞 COM 调用无中断点)。协议层不受影响(COM 走专用线程),但求解期间其它 CST 工具会排队。
3. **一次驱动一个工程**;Design Studio(电路/系统级)工程不支持。
4. **Floquet 端口 / 平面波 / 集总元件 / 螺旋线**还没有专用工具,走 `run_history_vba`。
5. **跨版本只在 2026.1 实测**(见[已验证](#已验证))。
6. 截图依赖 CST 以有界面方式运行。

## 真机踩坑(已在工具内兜底)

列在这里是为了别被"优化"回去。详细现象/原因/解法见 `skill/cst-design/knowledge/_general.md`。

| 坑 | 表现 | 兜底 |
|---|---|---|
| 波导端口 `PortOnBound=True` + expanded open | 端口被推到加出来的空气边界,S11≈0dB、效率≈0,日志"port mode excited below cutoff" | 端口默认 `on_bound=False`;日志命中该句时 `log_hints` 直接给原因 |
| 直接调 `AddToHistory` | 失败只回 False,没有原因 | 包进 RunScript 宏,从 COM 异常里取 CST 原文报错 |
| VBA 行尾 `_` 是续行符 | 以下划线结尾的变量名在行尾会吞掉下一行,"Expecting an expression" | 生成代码的临时变量一律不以 `_` 结尾 |
| `&` 拼接数字跟随系统 locale | 某些区域设置下小数点变逗号 | 查询宏统一 `N(x) = Trim(Str(x))` |
| `OpenFile` 返回 None | 拿不到工程句柄 | 打开后再取 `Active3D()` |
| 无工程时 `Active3D()` 抛异常 | 被误判为 CST 已死 | 只把 RPC 断连类 HRESULT 当作进程死亡 |
| `ExportImageToFile` 在宏里 "Invalid instruction" | 截图失败 | 视角在宏里设,截图走工程 COM 方法 |
| 优化器没先 `InitParameterList` | `SelectParameter` 静默无效,优化器秒退不报错 | 先 Init 再选参数;秒退且参数没动时报错 |
| 布尔交集为空 | 不报错,留下 bbox 全 0 的空实体 | 布尔后查 bbox,全 0 报错 |
| 改参数/扫参还原 | Rebuild 清掉旧结果 | 扫参每点当场提取;返回里写明结果已清 |
| 卸载后注册表残留 ProgID | `open_cst` 报"没有注册类" | 以 exe 是否存在判断已装版本;默认版本取真装着的最高版 |

## License

MIT,见 [LICENSE](LICENSE)。