HFSS_MCP

# HFSS MCP Server (native / cross-version) After putting it into Claude Code (or any MCP client), you describe the antenna in **natural language**, and the model follows the `hfss-antenna-modeling` skill to automatically build and solve in HFSS. > This server is a standard **MCP stdio server** (official `mcp` SDK), and the protocol layer does not bind any client. The following uses Claude Code as an example; for other MCP clients, see [Using other MCP clients](#using-other-mcp-clients). **The connection uses win32com to directly call AEDT's native scripting API** (oDesktop/oEditor/oModule), **not relying on PyAEDT**, so it can cross versions - **tested to work on 2019.2 and 2025.2**, suitable for driving PyAEDT/gRPC to reach **older versions of HFSS** (like 2019). ## Why Cross-Version - Connection = `win32com.Dispatch("Ansoft.ElectronicsDesktop." + version)` (ProgID registered for each installed version), not limited by PyAEDT version, nor dependent on gRPC (available from 2022R2 onwards). - Operations = AEDT native scripting API (macro recording), stable from ~v15. ## Capabilities (66 tools) | Domain | Capabilities | |---|---| | **Session** | open/attach/close, new project and design, **open existing .aedt from path**, switch/list, reset | | **Geometry** | box/rectangle/cylinder/sphere/polyline, boolean (union/subtract/intersect), transform (move/rotate/mirror/array replication), variable-driven, material (including **custom εr/tanδ**), delete | | **Self-Inspection** | `get_object_bbox` (check overlap/jump), `design_summary`, list_objects/variables | | **Boundary** | Perfect E / Perfect H / finite conductivity / impedance surface / lumped RLC, open radiation boundary, far-field sphere | | **Feed** | lumped port, edge feed/microstrip (one-step), coaxial probe (one-step) - all verified to produce **true matching** | | **Periodic Unit** | Master/Slave boundary + Floquet port (one-step, automatic lattice vector derivation) - infinite array/FSS/metamaterial unit simulation with scan angle | | **Solve & Results** | setup + sweep + analyze; S11/resonance/-10dB bandwidth, **VSWR + input impedance Zin**, **far-field pattern** | | **Parametric Sweep** | one solve for all combinations + 6 index extractions: S11 / gain / axial ratio / front-to-back ratio / HPBW / cross-polarization isolation | | **Optimization** | HFSS built-in optimizer (automatic iteration to approach target) | | **Auxiliary Design** | `search_designs` / `list_design_cards` - search design cards by index; `check_design_targets` - compare actual vs target values | **Usability**: before solving, bbox self-inspection prevents incorrect modeling, automatic coloring (conductor gold/copper, dielectric translucent, air nearly transparent), and confirmation prompts for blocking operations. **Skill Layer** (making "reproducing from papers" possible): read and parse diagrams (numbers from parameter tables, topology only), experience library (`skill/.../knowledge/`, error mechanism) + design card library (`skill/.../design/`, forward design) → explicit planning → coordinate/layer stacking convention → pre-solve self-inspection → feed/sweep/optimization routine → **design closed-loop** (search card → scaling → modeling → `check_design_targets` comparison → directional adjustment). ## Verified - **Cross-Version**: connection + modeling tested on 2019.2 and 2025.2. - **Core tools for modeling/solving/sweeping** tested on 2019.2 (including the most difficult parametric sweep result extraction); auxiliary design tools (3 tools) are pure native logic and single-test passed. - **Periodic unit tools** (Master/Slave boundary + Floquet port) implemented using AEDT scripting API, parameter construction verified offline, but **COM behavior not thoroughly regression-tested on all versions** - please monitor results for first use. - **The entire pipeline produced a correct matching antenna** (probe-fed patch: S11 −11.7dB / VSWR 1.7 / Zin~50Ω, self-consistent) - the "modeling + solving" part verified. ## Prerequisites - **Operating System: Windows**. Connection uses win32com (pywin32), **only Windows**, Linux/macOS not supported. - **HFSS / Ansys Electronics Desktop**: target version installed on the machine (tested on 2019.2, 2025.2), license available and manually startable. - **Python 3.10+** (`mcp` requirement); recommend using a virtual environment (reasons below). - **Claude Code** installed (`claude` CLI in PATH); or other MCP stdio clients. ## Installation ### 1. Get Code + Install Dependencies ```powershell git clone https://github.com/K-13ROBOT/HFSS_MCP.git cd HFSS_MCP # Recommended to create a virtual environment python -m venv .venv .venv\Scripts\Activate.ps1 python -m pip install -r requirements.txt # Only install mcp + pywin32, not pyaedt ``` > ⚠️ **Critical**: `install.py` writes the **absolute path of the Python currently running it** into the MCP configuration as the startup command. So, **which Python you use to install dependencies and run install.py, the server will use that**. If using venv, activate it and run all subsequent `python ...` commands. ### 2. Self-Test (without starting HFSS) ```powershell python smoke_mcp.py # Seeing SMOKE OK = dependencies installed, tools registered ``` ### 3. Register with Claude Code Preview the configuration to be written (without modifying any files): ```powershell python install.py ``` It prints: ① a `.mcp.json` segment, ② a `claude mcp add` command, and ③ inferred env. Choose one of two methods: **Method A — For a specific project (recommended)** ```powershell python install.py --project D:\path\to\your\project ``` One command writes three things (if existing, merge, not overwrite): - `<project>\.mcp.json` ← MCP server registration (project-level) - `<project>\.claude\skills\hfss-antenna-modeling\` ← skill (including knowledge/ experience library + design card library) - `<project>\.claude\settings.json` ← add "pre-execution confirmation" for `analyze` (prevent accidental blocking operations) **Method B — Global (available for all projects)** ```powershell python install.py --skill-user # ① Install skill to ~/.claude/skills/ ``` Then **copy and run the `claude mcp add` command** printed in the previous step, like: ```powershell claude mcp add hfss-agent-native --scope user -e HFSS_VERSION="2025.2" -- "C:\...\.venv\Scripts\python.exe" "C:\...\HFSS_MCP\hfss_mcp_server.py" ``` > This script **never modifies the global `~/.claude.json`**; global MCP registration is done through that `claude mcp add` command (you can see what it writes). ### 4. Take Effect + Verification 1. **Restart Claude Code** (configuration change requires restart). 2. `/mcp` should show **`hfss-agent-native`**. 3. Directly say "Use HFSS to build a 2.45GHz microstrip patch and run S11", and Claude will automatically use the `hfss-antenna-modeling` skill to build, solve, and output results. ## Configuration & Usage **Which version to connect to**: defaults to the `HFSS_VERSION` in the env (inferred from the highest `ANSYSEM_ROOT###` environment variable; defaults to `2025.2` if not found). **To connect to an older version (e.g., 2019.2)**: in the conversation, let `open_desktop` pass `version="2019.2"`, or modify the `HFSS_VERSION` in `.mcp.json` env. **License**: `install.py` brings the machine's `ANSYSLMD_LICENSE_FILE` / `ANSYSLIC_DIR` (if any) into the server env; if missing, add it manually as you normally start HFSS. **Project files**: default to `projects/` under the server's running directory (cwd); can be overridden with the `HFSS_PROJECTS_DIR` environment variable. **Blocking operation confirmation**: `analyze` / parametric sweep / optimization are time-consuming and blocking. The stdio's intra-process `[y/N]` prompt is disabled (stdio occupied by the protocol), replaced by the **client's permission system** - Claude Code uses `settings.json`'s `ask` rule (written by `install.py --project`). Other clients need their own tool authorization. **Design card directory** (auxiliary design search): `search_designs` looks for cards in `HFSS_DESIGN_DIR` → `~/.claude/skills/.../design/` → bundle's `skill/.../design/`, generally no need to configure. ## Using Other MCP Clients The server is a standard MCP stdio, **any MCP client can connect** (Claude Desktop, Cline, Continue, Cursor, or self-written MCP agent). The `command` / `args` / `env` in the configuration printed by `python install.py` are universal; fill them according to the target client's configuration format: ```jsonc { "command": "<python path>", // Python with installed dependencies (venv if used) "args": ["<bundle>/hfss_mcp_server.py"], "env": { "HFSS_VERSION": "2025.2", "ANSYSLMD_LICENSE_FILE": "..." } } ``` Switching clients will **lose two Claude Code exclusive features**, know them: 1. **Skill not automatically loaded** - `hfss-antenna-modeling` is Claude's skill mechanism, not read by other clients. Tools still work, but lose the discipline (coordinate/layer stacking convention, pre-solve self-inspection, experience library, design closed-loop). - Workaround: put the content of this repo's `skill/hfss-antenna-modeling/SKILL.md` (and `knowledge/`, `design/`) into the agent's system prompt/context as a guide. 2. **Confirmation gate** - as above, intra-process confirmation in stdio is disabled. If the client lacks a tool authorization UI, `analyze`/parametric sweep/optimization will **run directly without prompting**. Use an MCP tool-authorized client or be cautious. ## Current Limitations 1. **The weakest part is "reading/ understanding complex structures"**, not the modeling pipeline. For complex topologies like folding/multi-layer/custom feed, AI may make mistakes; still rely on user confirmation (skill §0 attempts to cover). 2. `analyze` blocking, **no Ctrl+C interruption**. 3. Experience library is young (growing with use). 4. Too many tools (66), each token has a cost. ## Future Directions - **Near-term (refining)**: end-to-end "reading diagrams" to modeling with real papers; experience library grows with use. - **Mid-term (adding capabilities)**: more feed/structure types, field/current distribution export, tools converging to reduce tokens. - **Long-term vision (design advisor)**: evolve from "modeling by example" to "referencing literature for design assistance" - given indices/reference papers, it suggests structures + dimensions and implements, simulates, and iterates to meet targets; underlying λ-normalized design card library + experience library. ## Known Points - Server name **`hfss-agent-native`** (hardcoded in settings' `mcp__hfss-agent-native__analyze` confirmation rule). - Projects saved to `projects/` under the server's cwd (can be overridden by `HFSS_PROJECTS_DIR`). - **CreateReport cross-version arity difference** (2019=8 args, 2025=7 args); result extraction uses multiple forms to cover. - **CreateRectangle's XZ plane Width/Height axis** opposite to intuition (corrected in tools); **port integral line** variable names automatically parsed as literal values (except coaxial).