HFSS FSS MCP Server

通过 Model Context Protocol (MCP) 和 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 个对象，避免意外创建超大模型。

Related MCP server: hfss-agent-native

已验证环境

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

安装

1. 准备环境

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

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，只修改：

HFSS_VERSION = "2023.1"

例如切换到 2025 R1：

HFSS_VERSION = "2025.1"

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

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

3. 注册到 Codex

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

.\register_codex.bat

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

也可以手动注册：

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

直接启动服务：

.\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 个工具。

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

测试

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

python test_smoke.py
python test_protocol.py

基础 HFSS 端到端测试：

python test_live_session.py

FSS 专项端到端测试：

python test_fss_features.py

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

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

python examples/create_fr4_cross_fss.py

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

项目结构

.
├── 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。本项目在此基础方向上独立实现了版本发现、单线程会话、FSS 周期边界、Floquet 端口、旋转/镜像、有限布阵和专项端到端测试。

许可证

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