Skip to main content
Glama
hexpress-mcp

hexpress-mcp

by GaillumXc

hexpress-mcp

English README | 中文

面向 AI Agent(Kimi Code、Claude、Cursor 等)的 NUMECA HEXPRESS/Hybrid 10.1 网格生成 MCP 服务器。

HEXPRESS 本身不提供任何现代自动化接口,本项目驱动的是安装目录里自带、但鲜为人知的三条批处理通道——不操控 GUI、不依赖显示器、不占许可证席位:

  1. 批划分器 — hexpresshybridx86_64.exe <conf> [-print]:由关键字 .conf 文件驱动(与 GUI 导出的 "batch configuration" 完全同格式),八叉树混合网格 / S2V 表面网格、MPI 并行;

  2. 批处理脚本 — hexpressx86_64.exe -batch -script <script.py>:无头 Python 2.7 + 内嵌 HXP API(CAD 导入/导出、几何查询、布尔运算、网格生成全链路);

  3. 格式转换 — hexpressfileconvertx86_64.exe <in> <out> -print。

IMPORTANT

非官方项目,与 Siemens Digital Industries Software(原 NUMECA)无任何关系。 本项目不包含、也不分发任何 HEXPRESS 软件、库或数据文件。运行时需要你在本机 合法安装 HEXPRESS/Hybrid 10.1 并拥有可用许可证;请遵守你的许可证协议。

特性

  • 8 个 MCP 工具,覆盖网格生成全流程:环境探测 → 几何检查 → CAD 转存 → conf 生成 → 网格划分(含 MPI)→ 统计解析

  • run_mesh 自动解析日志中的单元计数与质量指标(负雅可比、skewness、edge length、耗时),结构化返回

  • 每个工具调用都是独立子进程:崩溃不传染、不驻留、不持许可证

  • 工具永不抛出——所有错误以 JSON 返回,Agent 可读取自愈

  • 实测案例:方盒 STL、双部件翼身组合体(命名 selection + BC 落盘验证)、3.6 m 固定翼无人机全机模型(SolidWorks 2023 Parasolid V34)46 489 单元混合网格

Related MCP server: openfoam-mcp

安装

uv venv --python 3.11 .venv
uv pip install -e .          # 或: uv pip install .
python -m hexpress_mcp --selftest   # 探测本机 HEXPRESS 安装与许可证

依赖:Python ≥ 3.11、FastMCP ≥ 2.0、Windows(HEXPRESS 仅发布 Windows/Linux x86_64;本服务器在 Windows 10/11 实测)。

接入 MCP 客户端

Kimi Code(~/.kimi-code/mcp.json,用户级)

"hexpress": {
  "command": "D:\\path\\to\\hexpress-mcp\\.venv\\Scripts\\python.exe",
  "args": ["-m", "hexpress_mcp"],
  "cwd": "D:\\path\\to\\hexpress-mcp",
  "env": {
    "PYTHONPATH": "D:\\path\\to\\hexpress-mcp\\src",
    "PYTHONUTF8": "1",
    "HEXPRESS_DIR": "C:\\NUMECA_SOFTWARE\\hexpress101"
  }
}

HEXPRESS_DIR 可选:服务器会自动发现 C:\NUMECA_SOFTWARE\hexpress*\bin64\hexpressx86_64.exe,并缓存到 %APPDATA%\hexpress-mcp\config.json。

Claude Desktop / 其他 stdio MCP 客户端

{
  "mcpServers": {
    "hexpress": {
      "command": "D:\\path\\to\\hexpress-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "hexpress_mcp"],
      "env": { "PYTHONPATH": "D:\\path\\to\\hexpress-mcp\\src", "HEXPRESS_DIR": "C:\\NUMECA_SOFTWARE\\hexpress101" }
    }
  }
}

工具一览

工具

功能

get_status

安装路径、6 个可执行文件、许可证服务状态、版本探测(hexpressview -batch -print)、GUI 是否在运行

inspect_geometry

解析 STL 的 solid 名(即批划分器将生成的 selection 名),写 conf 前先查真名

convert_cad

用 GUI 内核的 Parasolid 桥重新导出 .x_t/.x_b——修复批划分器读新版 Parasolid 传输文件时段错误(0xC0000005)的问题

generate_conf

生成批划分 .conf(BASEH、局部加密、边界条件、边界层、S2V 模式;按系统 ANSI 代码页写盘,中文路径安全)

run_mesh

在 conf 上运行 hexpresshybridx86_64.exe,支持 np>1 MPI;返回 mesh_stats 结构化统计 + 日志尾部

run_script

在 -batch -script 下运行 Python 2 脚本(HXP API 全量可用),wrapper 自动捕获被 HEXPRESS 吞掉的 stdout 并回传 SCRIPT_RETURN_VALUE

convert_file

网格/几何格式互转(hexpressfileconvertx86_64.exe)

launch_gui

启动交互式 GUI(分离进程)

典型流程:get_status → inspect_geometry / convert_cad → generate_conf → run_mesh → 读 mesh_stats。

WARNING

run_mesh 返回 returncode: 0 不代表成功——NUMECA 的 commAbort 仍然以 0 退出。判定标准:mesh_stats.counts.cells 非空,且日志尾部无 Error: 行。工具无法替你判断网格是否满足你的工程要求,最终质量责任在使用者。

实战示例

例 1:STL 几何 + 命名 selection + 边界条件

# 1. 几何里 solid 名 = selection 名,先查
inspect_geometry(input_file=r"D:\geo\wing_fuselage.stl")
# → {"solid_names": ["wing", "fuselage"], ...}

# 2. 生成 conf:翼面加密 1 级,两个部件设 SOL 壁面
generate_conf(
    input_files=[r"D:\geo\wing_fuselage.stl"],
    output_mesh="wingFuselageMesh.msh",
    base_h=0.15,
    refinements={"wing": [1, 1]},
    boundary_conditions={"wing": "SOL", "fuselage": "SOL"},
    mark_all_outer=True)

# 3. 跑网格
run_mesh(conf_file=r"...\confs\wing_fuselage.conf")

输出的 Fluent 网格 zone 定义里可以看到 wall wing / wall fuselage(BC 真实落盘)。完整可运行示例见 examples/box_demo/(含几何生成脚本)。

例 2:SolidWorks/CATIA 导出的 Parasolid 全机模型

# 0. 若原始 x_t 让批划分器段错误(V33+ 传输文件常见),先转存
convert_cad(input_file=r"D:\cad\uav.x_t")   # → uav_v32.X_T

# 1. 估算特征尺度后选 base_h(见"排错"节:Surface Smoother 失败 = base_h 太大)
generate_conf(input_files=[r"D:\cad\uav_v32.X_T"],
              output_mesh="uav.msh", base_h=0.02, mark_all_outer=True)
run_mesh(conf_file=r"...\confs\mesh.conf", np=8)   # MPI 8 核

实测:3.6 m 固定翼、2 mm 薄特征,base_h=0.02 → 46 489 单元(64% 六面体),最大 skewness 0.91,14 s。

例 3:HXP API 脚本(Python 2 语法!)

run_script 的脚本在 HEXPRESS 内嵌 Python 2.7 上执行,预加载 HXP 模块:

igg_script_version(2.1)
HXP.import_parasolid(r"C:\work\geom.x_t")
bodies = get_all_bodies()
for b in bodies:
    print b.get_name(), "faces:", b.num_faces(), "healthy:", b.check()
HXP.export_parasolid(r"C:\work\geom_reexported.x_t")
print "SCRIPT_RETURN_VALUE", 0
  • 脚本 stdout/stderr 被 wrapper 捕获后随结果返回(HEXPRESS 批模式自身会吞掉它们)

  • print "SCRIPT_RETURN_VALUE", 0 是显式成功信号;未打印则按"无异常=0 / 异常=1"判定

.conf 关键字参考(源自安装目录自带测试集)

INFILENAMES            <个数> 随后逐行列出路径
OUTFILENAME            <文件名>     (resultMesh.msh / out.spb.gz ...)
BASEH                  <基础单元尺寸>  (八叉树基准,必须解析最小特征!)
SUPPRESSPREFIX / MARKALLOUTER / EXACTMESHING / GENERATEFULLHEXAMESH
NUMBNDLAYERS           <n>          (粘性边界层数)
BNDLAYERTRANSITION     <0|1>
LOCALREFINEMENTDEFINITION <名> <初始加密级> <最小加密级>
BCDEFINITION           <名> <类型>    (SOL / INL / OUT / SYM ...)
GENERATES2VMESH        (表面到体积模式)
S2VPARAM GENERATESURFACEMESH MIXED   (只出表面网格)
CADIMPORTPARAM MEDIUM                (CAD 导入精度;COARSE/FINE 会报错)
CREATEALLEDGESFROMMODEL NOPREFIX
USEBINFILEVERSION 11
END

未列出的关键字可通过 extra_lines 原样透传。更多示例见安装目录 C:\NUMECA_SOFTWARE\hexpress101\_python\_tests_db\_installations\hexpress\*.conf。

排错(全部是实测踩过的坑)

症状

原因与对策

returncode 3221225477(0xC0000005)

批划分器读新版 Parasolid 传输文件崩溃 → 先 convert_cad 转存

Surface Smoother failed ... geometry might be open

几乎都是 base_h 太大,网格投影不到薄特征。按最小特征尺寸 1/5~1/10 取 base_h; drones/薄翼型建议先 0.02 试算

Warning: Geometry or mesh does not contain any selection which corresponds to: X

conf 里的名字与几何 selection 不符 → 先用 inspect_geometry(STL)或在 CAD 里查看面名(Parasolid)

批脚本"静默失败"、无任何输出

Py2 编码:脚本含非 ASCII(如中文路径)必须有 # -*- coding: utf-8 -*-(run_script 自动生成);语法必须是 Python 2

conf 里中文路径变乱码、报"file not present"

hexpresshybridx86_64 按系统 ANSI 代码页读 conf——generate_conf 已用 mbcs 写盘;手动编辑 conf 请用 GBK/ANSI 保存

run_mesh 报 license 错

FLEXlm 服务未启动:以管理员运行 C:\NUMECA_SOFTWARE\NUMECA_License_Server*\server_install.bat

MPI(np>1)不起作用

检查安装目录 pvm/ 是否完整;10.1 的 -ompi -np N 需要机器名解析正常

开发

uv pip install pytest ruff
ruff check src tests
pytest
python -m hexpress_mcp --selftest
  • tests/ 不依赖 HEXPRESS 安装(纯函数与错误路径),可在任意机器上跑

  • 运行时数据(confs / 脚本 / 日志)写在 %APPDATA%\hexpress-mcp\,不进仓库

  • 新增工具后:改 server.py → ruff → pytest → 重启 MCP 客户端会话(stdio 服务器不热加载)

免责声明

  • 本项目为独立开源作品,不附属于、不认可于、不受支持于 Siemens/NUMECA

  • HEXPRESS、FINE、NUMECA 及其标志均为各自所有者的商标

  • 按 MIT 许可证发布;商用 HEXPRESS 许可证的条款由你与软件供应商的协议约束

相关项目

  • xflr5-mcp — XFLR5 翼型/机翼分析 MCP 服务器(同一作者)

  • profili-mcp — Profili 翼型库 MCP 服务器

Available Tools

8 tools
convert_cadConvert CadA

Re-export a Parasolid CAD file through the HEXPRESS GUI kernel.

hexpresshybridx86_64.exe (batch mesher) can segfault (0xC0000005) reading newer Parasolid transmits that hexpressx86_64.exe imports fine — passing the file through this converter (import + export) produces a byte-level V32-era transmit the batch mesher digests. Also useful to bake/validate any Parasolid .x_t/.x_b before meshing. Output defaults to _v32.X_T next to the input. Returns the exported path.

Inputs: input_file (required), timeout, install_dir, output_file. Returns: result

convert_fileConvert FileB

Convert between mesh/geometry formats (hexpressfileconvertx86_64.exe).

e.g. .spb -> .msh, .spb.gz -> .cgns ... Formats are inferred from the extensions. Returns returncode and the log tail.

Inputs: input_file (required), output_file (required), timeout, install_dir. Returns: result

generate_confGenerate ConfA

Generate a HEXPRESS batch .conf file (without running it).

input_files: geometry/mesh inputs (STL, .spb, .CATPart, .igs ...), absolute paths recommended. output_mesh: output file name, e.g. resultMesh.msh (FNMB mesh) or .spb.gz. base_h: base cell size for the octree mesher. refinements: {selection_name: [initial_level, min_level]} — LOCALREFINEMENTDEFINITION. boundary_conditions: {selection_name: bc_type} — BCDEFINITION (e.g. SOL, INL, OUT, SYM). num_boundary_layers: viscous layer count (NUMBNDLAYERS). s2v_mesh: surface-to-volume (tet-dominant) mode instead of octree hybrid. Returns the written path and the full conf content.

Inputs: input_files (required), output_mesh (required), base_h, s2v_mesh, +11 more. Returns: result

get_statusGet StatusA

Probe the environment: HEXPRESS install paths, executables, license server state, whether the GUI is running, and platform notes. Call first.

Inputs: install_dir. Returns: result

inspect_geometryInspect GeometryA

Report the selection names a geometry file will produce for BCDEFINITION / LOCALREFINEMENTDEFINITION in a batch conf.

For .stl: reads the solid names directly (hexpresshybridx86_64 groups triangles by STL solid name — import_mode 2, the default). Empty-string names mean a binary STL (no names stored) — use feature grouping (import_mode 1) there and discover TMP-style names from the mesh log. For .spb/.igg project files the names live inside the project; open it in the GUI once or query via run_script. Non-STL inputs raise an error.

Inputs: input_file (required), timeout, import_mode, install_dir. Returns: result

launch_guiLaunch GuiC

Start the interactive HEXPRESS GUI (hexpressx86_64.exe), detached.

Inputs: install_dir. Returns: result

run_meshRun MeshA

Run hexpresshybridx86_64.exe on a .conf file (generate a mesh in batch).

conf_file: path returned by generate_conf (or any HEXPRESS-exported conf). np: number of MPI processes (>1 adds -ompi -np N). timeout: seconds before the run is killed (default 1 h; big meshes need more). Returns returncode, elapsed time, output file info and the log tail.

Inputs: conf_file (required), np, timeout, install_dir. Returns: result

run_scriptRun ScriptA

Run a Python 2 script inside headless HEXPRESS (-batch -script).

The script executes with the embedded HXP API preloaded (HXP.open_project, HXP.generate_initial_mesh, HXP.insert_viscous_layers, ... — see _python/_igg/HXP.py in the install), wrapped so that its stdout (which HEXPRESS batch mode otherwise swallows) is captured, and a SCRIPT_RETURN_VALUE line — printed as print "SCRIPT_RETURN_VALUE", 0 — or 0/1 on success/exception is read back from a result file. Provide exactly one of script_text (written to a temp file) or script_file. Returns returncode, script_return_value, captured script stdout and the process log tail.

Inputs: timeout, install_dir, script_file, script_text. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    Each tool has a fairly distinct role, but boundaries blur in a couple of places: convert_file and convert_cad both perform format conversion, and run_script is a general escape hatch that could overlap with generate_conf/run_mesh for a determined agent. Descriptions do clarify the differences, so misselection risk is low but not zero.

    Naming Consistency5/5

    All eight names follow a strict verb_noun snake_case pattern (get_status, generate_conf, run_mesh, run_script, convert_file, convert_cad, inspect_geometry, launch_gui). No style mixing or vague single-word names.

    Tool Count5/5

    Eight tools is well within the healthy 3-15 range for a domain-specific meshing server. Each tool maps to a distinct stage of the workflow (probe, generate, run, script, convert, inspect, launch), so all earn their place.

    Completeness4/5

    The surface covers the full meshing lifecycle from environment probing through conf generation, execution, conversion, and geometry inspection. Minor gaps exist: there is no tool to cancel/terminate an in-flight job or to inspect mesh quality/results post-run, which agents may need to work around.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Automates OpenFOAM CFD simulations via MCP, enabling AI agents to mesh, run, and post-process cases from natural language prompts without any API keys.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Turns an AI assistant into an OpenFOAM setup and debugging co-pilot, enabling case scaffolding, dictionary edits, mesh sizing, turbulence calculations, and solver log analysis through natural language.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables an AI assistant to drive Abaqus/CAE through file IPC—sending Python commands, querying model info, submiting jobs, and capturing viewport screenshots—so finite element models can be built and solved without manual GUI interaction.
      2
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to drive OpenFOAM end to end: cloning tutorials or custom cases, editing dictionaries, meshing and running solvers in the background, tracking convergence and job status, and analyzing results. It also renders flow images — slices, patches, streamlines, iso-surfaces and residual or force plots — back to the agent.
      25
      1
      MIT