# 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 助手集成
- 📦 **43 个内置工具** - 覆盖会话管理、建模、端口、边界、仿真、后处理与知识检索全流程
- 🎯 **会话管理** - 支持多项目切换和会话恢复
- 📚 **建模知识库检索** - 可基于本地 ANSYS PDF 文档构建并检索 HFSS 建模知识

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

依赖包：`mcp`、`pyaedt`、`psutil`、`pypdf`

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

### 2. 启动服务器

```bash
python hfss_server.py
```

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

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

## 可用工具（43 个）

### 会话与应用管理

| 工具名称 | 描述 |
|---------|------|
| `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_parametric_box` | 创建可使用设计变量作为尺寸或位置的参数化长方体 |
| `hfss_create_cylinder` | 创建圆柱体（支持 X/Y/Z 轴方向） |
| `hfss_create_sphere` | 创建球体 |
| `hfss_create_rectangle` | 创建指定平面上的矩形面 |
| `hfss_create_polygon_sheet` | 根据顶点创建多边形面 |
| `hfss_create_material` | 创建或更新介电材料属性（介电常数、损耗角正切、导电率） |
| `hfss_create_region` | 创建空气计算域（Region） |
| `hfss_create_infinite_sphere` | 创建远场结果所需的无限球设置 |
| `hfss_delete_objects` | 删除指定模型对象 |
| `hfss_unite_objects` | 合并多个模型对象 |
| `hfss_subtract_objects` | 从目标对象中减去工具对象 |
| `hfss_clear_design` | 清除设计中的对象、边界、网格操作、Setup 和设计变量（需确认） |
| `hfss_list_objects` | 列出所有模型对象 |
| `hfss_get_object_info` | 获取指定对象详细信息（材质、边界盒、体积等） |

### 端口与边界条件

| 工具名称 | 描述 |
|---------|------|
| `hfss_assign_wave_port` | 为指定面分配波导端口 |
| `hfss_assign_radiation_boundary` | 为指定面分配辐射边界条件 |
| `hfss_assign_radiation_boundary_to_object` | 为指定对象分配辐射边界条件 |
| `hfss_assign_lumped_port` | 在指定对象与参考对象之间分配集总端口 |

### 变量与参数化

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

### 仿真控制与后处理

| 工具名称 | 描述 |
|---------|------|
| `hfss_create_setup` | 创建仿真设置（指定名称与频率） |
| `hfss_set_solution_type` | 修改当前设计的求解类型 |
| `hfss_create_frequency_sweep` | 创建线性计数频率扫描 |
| `hfss_run_analysis` | 运行仿真分析 |
| `hfss_get_s_parameters` | 提取 S 参数结果（兼容不同 PyAEDT 版本） |
| `hfss_get_peak_realized_gain` | 提取指定频点的峰值实现增益 |

### 建模知识库

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

---

## 从 ANSYS 文档构建 HFSS 知识库

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

```bash
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](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 建模规则，在自动建模时提供实时建议。

### 三行命令启动

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

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

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

### 自动建模中查询知识

```json
{
  "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](MODELING_KB_GUIDE.md)

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

## 测试验证

### 手动测试 MCP 服务器

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

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

测试请求文件格式：

```json
{"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`，然后运行：
```bash
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`

完整的 43 个工具清单见前文「可用工具（43 个）」。MCP 客户端会在初始化时直接获取服务端当前注册的工具定义。

## 项目结构

```
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