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 个）

会话与应用管理

项目管理

建模与几何

端口与边界条件

变量与参数化

仿真控制与后处理

建模知识库

从 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_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