HFSS MCP Server

基于 Model Context Protocol (MCP) 的 ANSYS HFSS 自动化服务器，支持持久化 HFSS 连接。

目录说明

• hfss_server.py：主服务端代码，负责 MCP 协议、HFSS 会话管理、日志、异常处理等。
• requirements.txt：Python 依赖清单，可通过 pip install -r requirements.txt 一键安装。
• HFSS_MCP_EXPERIENCE.md：开发经验与已知问题记录。

功能特性

• 🔌 持久化连接 - HFSS 连接在多次调用间保持不断开
• 🚀 MCP 协议兼容 - 可与支持 MCP 的 AI 助手集成
• 📦 26 个内置工具 - 覆盖建模、端口、边界、仿真、后处理全流程
• 🎯 会话管理 - 支持多项目切换和会话恢复
• 📚 建模知识库检索 - 可基于本地 ANSYS PDF 文档构建并检索 HFSS 建模知识

快速开始

1. 安装依赖

pip install -r requirements.txt

依赖包：mcp、pyaedt、psutil、pypdf

注意：包名为 pyaedt，而非 ansys-aedt-core（后者在 PyPI 上不存在）。

2. 启动服务器

python hfss_server.py

3. 配置 MCP 客户端（以 VS Code 为例）

{
  "servers": {
    "hfss": {
      "command": "python",
      "args": ["e:/project/GitHub/HFSS_McpServer/HFSS_McpServer/hfss_server.py"],
      "type": "stdio"
    }
  }
}

可用工具（26 个）

会话与应用管理

工具名称	描述
hfss_start_app	连接现有 HFSS 应用
hfss_launch_app	启动新的 HFSS 应用（含 GUI）
hfss_stop_app	停止 HFSS 应用并释放资源
hfss_restart_app	重启 HFSS 应用
hfss_get_session_status	获取当前会话详细状态
hfss_get_process_status	获取 HFSS 进程状态
hfss_get_messages	获取 HFSS 日志消息

项目管理

工具名称	描述
hfss_create_project	创建新工程（支持 Terminal/DrivenModal 等解法类型）
hfss_save_project	保存当前工程
hfss_close_project	关闭当前工程（会话保持）
hfss_list_projects	列出所有活跃会话
hfss_import_project	导入工程文件
hfss_export_project	导出当前工程

建模与几何

工具名称	描述
hfss_create_box	创建长方体（指定中心坐标与尺寸）
hfss_create_cylinder	创建圆柱体（支持 X/Y/Z 轴方向）
hfss_create_sphere	创建球体
hfss_list_objects	列出所有模型对象
hfss_get_object_info	获取指定对象详细信息（材质、边界盒、体积等）

端口与边界条件

工具名称	描述
hfss_assign_wave_port	为指定面分配波导端口
hfss_assign_radiation_boundary	为指定面分配辐射边界条件

变量与参数化

工具名称	描述
hfss_list_variables	列出所有设计变量
hfss_set_variable	设置/修改设计变量（如 '10mm'）
hfss_delete_variable	删除设计变量

仿真控制与后处理

工具名称	描述
hfss_create_setup	创建仿真设置（指定名称与频率）
hfss_run_analysis	运行仿真分析
hfss_get_s_parameters	提取 S 参数结果（兼容不同 PyAEDT 版本）

建模知识库

工具名称	描述
hfss_get_modeling_knowledge_status	查看本地 HFSS 建模知识库状态
hfss_query_modeling_knowledge	按问题检索建模经验（端口/边界/setup/网格等）

---

从 ANSYS 文档构建 HFSS 知识库

如果你本机有完整的 ANSYS ProductDocPDF，可用脚本提取和索引与 HFSS/AEDT 建模相关内容：

python scripts/build_hfss_kb.py --doc-root "E:/download/ANSYS2026R1/ANSYS2026R1_ProductDocPDF/v261"

默认会在项目根目录生成：

• hfss_modeling_knowledge_base.json

建议在以下时机重新构建：

• 升级 ANSYS 主版本后
• 更换文档路径后
• 自动建模策略更新后

自动建模流程建议：

1. 先调用 hfss_query_modeling_knowledge 检索当前建模任务关键字
2. 将返回的 recommendation 映射到端口/边界/setup 工具调用
3. 完成建模后再执行仿真和结果提取

---

已知问题与注意事项

详见 HFSS_MCP_EXPERIENCE.md，包含以下问题的根因与修复方案：

• PyAEDT 辐射边界 API 版本差异（assign_radiation_boundary_to_faces）
• Wave Port API 面 ID 使用方式
• S 参数提取版本兼容性回退逻辑
• InsertInfiniteSphereSetup 在 gRPC 模式下失败
• C 盘满时 pip 静默失败的绕过方法

---

开发与维护说明

• 主支持文件：仅 hfss_server.py 作为主服务端代码，建议所有新功能、性能优化、日志改进等均在此文件实现。
• 依赖安装问题：若 C 盘空间不足导致 pip 静默失败，需将 TEMP、TMP、PIP_CACHE_DIR 环境变量重定向至其他磁盘（如 E:\pip-tmp）后再安装。
• 兼容版本：已在 AEDT 2026.1 + PyAEDT 0.25.1 + Python 3.12 下验证通过。

日志改进建议

• 推荐统一使用 logging 标准库，设置合理的日志级别（INFO/DEBUG/ERROR），并输出到文件和控制台。
• 日志格式建议包含时间、模块、级别、消息，便于排查问题。
• 关键操作（如会话创建、关闭、异常、外部调用）应有详细日志。
• 可考虑增加日志轮转（如 logging.handlers.RotatingFileHandler）。

贡献与开发规范

• 代码需包含必要的注释和类型标注，便于后续维护。
• 建议为核心功能补充单元测试（可用 pytest）。
• 重要变更请在本 README 或代码注释中说明。

---

如需扩展功能、性能优化或日志增强，请直接修改 hfss_server.py 并遵循上述规范。

---

🎯 快速入门：HFSS 自动建模知识库

从官方 ANSYS 文档自动提取和检索 HFSS 建模规则，在自动建模时提供实时建议。

三行命令启动

# 1. 构建知识库（从你的 ANSYS 文档目录）
python quickstart.py build

# 2. 检查状态
python quickstart.py status

# 3. 启动 MCP 服务器
python quickstart.py server

自动建模中查询知识

{
  "method": "tools/call",
  "params": {
    "name": "hfss_query_modeling_knowledge",
    "arguments": {
      "query": "wave port setup for coaxial antenna feed",
      "top_k": 5
    }
  }
}

📖 详细指南：MODELING_KB_GUIDE.md

1. 先启动 HFSS（打开任意工程或空白界面）
2. 在 VS Code 中重新加载窗口（Ctrl+Shift+P → Reload Window）
3. MCP 服务器将自动连接
4. 开始使用工具调用

测试验证

手动测试 MCP 服务器

可以通过命令行直接测试 MCP 协议：

cd e:/project/GitHub/HFSS_McpServer/HFSS_McpServer
python hfss_server.py

测试请求文件格式：

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hfss_start_app","arguments":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"hfss_get_session_status","arguments":{}}}

保存为 test_mcp.txt，然后运行：

type test_mcp.txt | python hfss_server.py

测试结果示例

成功连接后会显示：

=== HFSS Session Status ===

Current Design:
  Project: Project1
  Design: HFSSDesign1
  Solution Type: Terminal
  Objects: 0

All Designs in Project1:
  - HFSSDesign1 [CURRENT]

Project Path: E:/documant/Ansoft/

技术细节

• PyAEDT 版本: 0.25.1+
• AEDT 版本: 2026.1
• 连接方式: gRPC (端口 50051)
• 协议版本: MCP 2024-11-05
• 会话持久化: 自动保存状态到 hfss_session_state.json

可用工具

工具名称	描述
hfss_start_app	连接现有 HFSS 应用
hfss_launch_app	启动新的 HFSS 应用
hfss_create_project	创建新工程
hfss_create_box	创建长方体模型
hfss_list_objects	列出所有模型对象
hfss_get_object_info	获取指定对象的详细信息（类型、材质、边界盒、体积）
hfss_save_project	保存当前工程
hfss_get_session_status	获取会话状态
hfss_get_messages	获取 HFSS 日志消息
hfss_stop_app	停止 HFSS 应用

项目结构

hfss_mcp/
├── hfss_server.py      # MCP 服务器主程序
├── mcp_config.json     # MCP 配置示例
├── test_*.py           # 测试脚本
├── debug_*.py          # 调试脚本
└── README.md

工作原理

1. MCP 服务器启动时，在导入 PyAEDT 之前禁用 atexit.register
2. 这可以防止 Python 退出时释放 HFSS Desktop
3. HFSS 连接通过 gRPC 保持活跃
4. 每次工具调用复用同一连接

故障排除

Q: 每次调用后 HFSS 连接断开？ A: 确保在导入 ansys.aedt.core 之前禁用 atexit.register

Q: 找不到 HFSS 进程？ A: 确保 HFSS 应用程序已经在运行（打开任意工程）

License

MIT