# HFSS FSS MCP Server

通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 和 PyAEDT，让 AI 客户端以结构化工具控制本机 Ansys HFSS。

项目面向 FSS、超表面和周期结构建模，覆盖周期单元、Lattice Pair 周期边界、Floquet 端口、旋转/镜像、有限阵列、求解设置和结果导出。服务采用 stdio 通信，不开放网络端口。

> 本项目不是 Ansys 官方产品。运行前需要合法安装并授权 Ansys Electronics Desktop / HFSS。

## 主要能力

- 一条配置切换 HFSS 版本，例如从 2023 R1 切换到 2025 R1
- 自动发现 Windows 注册表、`ANSYSEM_ROOTxxx` 环境变量和常见安装目录
- 创建长方体、圆柱、矩形、圆和 FSS 周期单元
- 布尔合并/相减，平移，绕指定中心旋转，镜像及镜像复制
- 线阵、二维矩形阵列和圆周阵列
- Perfect E、有限电导率和阻抗薄片
- 自动或手动建立 Lattice Pair
- 自动或显式晶格矢量的 Floquet 端口
- 一键配置四侧周期边界和上下两个 Floquet 端口
- 创建自适应 Setup、扫频、求解、读取曲线和导出 Touchstone
- 所有 PyAEDT 操作固定在同一工作线程，适配 Windows AEDT 会话模型

阵列操作默认限制一次最多生成 2500 个对象，避免意外创建超大模型。

## 已验证环境

| 组件 | 已验证版本 |
| --- | --- |
| Windows | Windows 10/11 |
| Python | 3.11.14 |
| Ansys HFSS | 2023 R1 |
| PyAEDT | 0.24.1 |
| MCP Python SDK | 2.1.1 |

代码同时兼容 MCP Python SDK 1.x/2.x，并为不同 PyAEDT 参数命名保留了兼容处理。其他 HFSS 版本需要在对应安装环境中验证。

## 安装

### 1. 准备环境

推荐使用 Conda 或 venv，Python 3.10 及以上：

```powershell
conda create -n hfss-mcp python=3.11 -y
conda activate hfss-mcp
python -m pip install -r requirements.txt
```

如果已经有安装 PyAEDT 的虚拟环境，激活该环境后执行最后一行即可。

### 2. 选择 HFSS 版本

打开 `config.py`，只修改：

```python
HFSS_VERSION = "2023.1"
```

例如切换到 2025 R1：

```python
HFSS_VERSION = "2025.1"
```

目标版本必须已安装。自动发现失败时，可在同一文件指定 AEDT 的 `Win64` 目录：

```python
AEDT_INSTALL_DIR = r"C:\Program Files\AnsysEM\v251\Win64"
```

### 3. 注册到 Codex

在已激活的 Python 环境中运行：

```powershell
.\register_codex.bat
```

脚本会自动读取当前 Python 路径和仓库路径。注册完成后重启 Codex。

也可以手动注册：

```powershell
python -c "import sys; print(sys.executable)"
codex mcp add hfss -- "<上一步输出的 python.exe>" "<仓库绝对路径>\server.py"
```

直接启动服务：

```powershell
.\start_server.bat
```

stdio MCP 启动后没有普通控制台输出并持续等待属于正常现象。

## FSS / 超表面工作流

典型的周期单元流程：

1. 调用 `hfss_status` 检查目标版本。
2. 调用 `hfss_launch` 启动 HFSS。
3. 用 `hfss_create_fss_unit_cell` 创建空气周期单元。
4. 创建贴片、开槽或介质几何。
5. 使用旋转、镜像、布尔和阵列工具完成单元图案。
6. 分配 Perfect E、有限电导率或阻抗边界。
7. 调用 `hfss_setup_fss_boundaries` 自动创建两组 Lattice Pair 和上下 Floquet 端口。
8. 创建 Setup 和频率扫描。
9. 保存工程，按需调用 `hfss_analyze` 求解。

可以直接向支持 MCP 的 AI 客户端描述：

> 启动 HFSS 2023 R1，创建 10 mm × 10 mm、Z 方向从 -5 mm 到 5 mm 的周期单元；在 Z=0 创建一个 5 mm × 4 mm 的铜贴片并旋转 30°；自动配置 XY 周期边界和两个 Floquet 端口；创建 10 GHz 自适应设置以及 6–14 GHz 扫频，最后保存工程。

## MCP 工具

服务当前提供 37 个工具。

| 分组 | 工具 |
| --- | --- |
| 会话与工程 | `hfss_status`, `hfss_launch`, `hfss_connect`, `hfss_project_info`, `hfss_activate_design`, `hfss_save_project`, `hfss_close` |
| 参数与求解 | `hfss_get_variables`, `hfss_set_variable`, `hfss_analyze`, `hfss_get_solution_data`, `hfss_export_touchstone` |
| 几何 | `hfss_list_objects`, `hfss_get_object_info`, `hfss_create_box`, `hfss_create_cylinder`, `hfss_create_rectangle`, `hfss_create_circle`, `hfss_create_fss_unit_cell`, `hfss_unite`, `hfss_subtract` |
| 变换与布阵 | `hfss_move`, `hfss_rotate`, `hfss_mirror`, `hfss_duplicate_linear`, `hfss_duplicate_circular`, `hfss_rectangular_array` |
| 导体与表面 | `hfss_assign_perfect_e`, `hfss_assign_finite_conductivity`, `hfss_assign_impedance_sheet` |
| 周期与端口 | `hfss_list_boundaries`, `hfss_assign_lattice_pair`, `hfss_auto_assign_lattice_pairs`, `hfss_create_floquet_port`, `hfss_setup_fss_boundaries` |
| 仿真配置 | `hfss_create_setup`, `hfss_create_frequency_sweep` |

工具参数和返回结构可由 MCP 客户端自动读取，无需手写协议消息。

## 测试

不启动 HFSS、不占用许可证：

```powershell
python test_smoke.py
python test_protocol.py
```

基础 HFSS 端到端测试：

```powershell
python test_live_session.py
```

FSS 专项端到端测试：

```powershell
python test_fss_features.py
```

FSS 测试会真实启动 HFSS，创建周期单元、旋转/镜像结构、矩形阵列、圆周阵列、周期边界、Floquet 端口、Setup 和扫频，随后保存到 `test_output/` 并关闭本次启动的 AEDT。运行前请确认许可证可用。

参数化 FR4 金属十字架 FSS 示例：

```powershell
python examples/create_fr4_cross_fss.py
```

该示例通过 MCP 创建 10 mm 周期、1.6 mm FR4 基板和有限电导率铜十字架，并配置周期边界、Floquet 端口、10 GHz 自适应设置及 6–14 GHz 扫频。

## 项目结构

```text
.
├── server.py              # MCP 入口和通用 HFSS 工具
├── hfss_backend.py        # AEDT 发现、版本兼容和单线程会话
├── hfss_fss.py            # FSS、周期边界、几何和阵列后端
├── fss_tools.py           # FSS MCP 工具注册
├── config.py              # 用户配置
├── requirements.txt
├── register_codex.bat
├── start_server.bat
├── examples/
│   └── create_fr4_cross_fss.py
└── test_*.py
```

## 注意事项

- 对重要工程操作前建议先备份；MCP 工具可以修改并保存 AEDT 工程。
- `hfss_analyze` 是阻塞调用，大型模型可能长时间运行。
- 公开仓库不应提交 `.aedt`、结果目录、日志或本机虚拟环境，项目的 `.gitignore` 已默认排除这些内容。
- HFSS、AEDT、Ansys 和 PyAEDT 的商标及许可归其各自所有者。

## 致谢

几何建模工具的组织方式参考了 [leonardwy/HFSS_McpServer](https://github.com/leonardwy/HFSS_McpServer)。本项目在此基础方向上独立实现了版本发现、单线程会话、FSS 周期边界、Floquet 端口、旋转/镜像、有限布阵和专项端到端测试。

## 许可证

本项目采用 [MIT License](LICENSE)。许可证仅覆盖本仓库代码，不包含 Ansys HFSS、AEDT 或其他第三方软件的使用授权。