Ansys Fluent MCP

ANSYS Fluent MCP (standalone) — Authoring Playbook

This skill targets the tool surface that ansys-fluent-mcp ships. The server gives you composable primitives — discovery, state read, schema discovery, validation, sandboxed execution — and you build everything else by chaining them. It is stateless: each call stands alone, there is no plan builder, journal, or undo.

Tool roster (this is what you actually have)

That is the complete surface. There is no propose_step, finalize, summarize_session, inspect_api, describe_command, get_allowed_values, query_reports, validate_setup, diagnose_divergence, or engineering-correlation helper (compute_htc, lookup_emissivity, …) on this server. Don't call them — they don't exist here.

The composition pattern

For nearly every intent, the loop is:

1. Discover    → find_api / get_help / list_named_objects / summarize_setup
2. Author      → your host or user supplies PyFluent settings-API Python
3. Validate    → validate_code (offline AST check)
4. Execute     → run_code (mutates the live solver)
5. Verify      → get_state / summarize_setup / simulation_report

Intent-to-code translation is not part of this leaf. If a host wants to translate user intent into Python, it should do so outside this server, then pass the resulting Python through validate_code before calling run_code.

Path roots (universal Fluent knowledge)

PyFluent has exactly five top-level path roots:

setup. | solution. | results. | file. | mesh.

setup.solution.* does not exist.

Recipes for common intents

"Show mesh quality / skewness / orthogonal quality / aspect ratio / check mesh"

Use the mesh_quality tool — it returns structured skewness / orthogonal-quality / aspect-ratio histograms and, when include_check=true, also embeds the output of Fluent's mesh.check():

mesh_quality(include_check=true)

Do NOT route these intents through run_code, simulation_report, or summarize_setup — the dedicated tool already wraps the raw PyFluent calls and normalises their output across versions.

"What fields are available?" / "list scalar fields"

list_fields(scope="any")     # any | cell | node | face

Returns the flat list usable in report defs, contours, vectors.

"Compare two case files"

compare_files(path_a="/abs/path/A.cas.h5", path_b="/abs/path/B.cas.h5")

Both files open in separate ephemeral PyFluent sessions with lightweight_setup=true — your live workspace session is NOT touched. Returns a markdown summary table in the summary field; echo that string verbatim to the user.

"Compute h for natural convection?" / "Porous resistance?" / "Emissivity / roughness of X?"

These engineering correlations and material lookups are not on this server. Ground the value yourself (textbook / handbook) and use it in host-authored Python rather than calling a non-existent tool.

"Show me the current setup"

summarize_setup(scope='models') or summarize_setup(scope='bcs') — don't dump the whole tree. Scoped output keeps client context small and the response on-topic.

"Enable energy" / "set BC outlet to pressure-outlet" / "switch turbulence to k-ω SST"

Author PyFluent settings-API Python, validate it with validate_code, then execute it with run_code.

Always show the generated code to the user before run_code — it mutates the solver immediately and there is no undo on this server.

"What's the path for ?"

find_api(query="velocity inlet thermal temperature", kind="path")

Pick the most-specific match and then:

get_help(path="setup.boundary_conditions.velocity_inlet.<zone>.thermal.t")

"List my zones / BCs / materials"

list_named_objects(path="setup.boundary_conditions.velocity_inlet")
list_named_objects(path="setup.cell_zone_conditions.fluid")
list_named_objects(path="setup.materials.fluid")

For predicate filtering, use select_named_objects with where=[...].

"Read a value"

get_state(path="setup.models.viscous.k_omega_model") — pass a string, not a list. The result is the live value.

"Iterate N steps"

run_code(code="solver.solution.run_calculation.iterate(iter_count=200)")

There's no streaming progress on this surface — you'll get the final residual snapshot. Use solver_status to confirm completion.

"Load a case / mesh"

run_code(code="solver.file.read_case(file_name=r'<path>')")
run_code(code="solver.file.read_data(file_name=r'<path>')")

Golden rules

• NEVER emit .tui.* calls from run_code. Always solver.settings.* / solver.<root>.<path>... (the settings API is what's available in 27.1).
• .list() / .list_properties() are void — they print only. Use list_named_objects instead for programmatic discovery.
• run_code mutates the live solver. There is no journal / rollback on this surface. Show the user the code before you run it.
• Named expressions REQUIRE units when dimensional: '288.15 [K]', '1.225 [kg/m^3]', '1 [m/s]'. Bare numbers silently break downstream report defs and BC values.
• get_state(path=...) takes a string, not a list. Same for find_api(query=...).

Anti-patterns (do not do)

• .tui.* calls of any kind, including via run_code.
• Calling planning/governance tools (propose_step, finalize, summarize_session, inspect_api, validate_setup) — they are NOT part of this server.
• Routing "mesh quality" / "skewness" / "orthogonal quality" / "aspect ratio" / "check mesh" through simulation_report, summarize_setup, or hand-written run_code — call the dedicated mesh_quality tool instead (it returns the structured histograms directly and optionally wraps Fluent's mesh.check()).
• Calling run_code with intent strings (it expects Python, not executable code). Translate intent outside this leaf, validate the resulting Python, then execute it with run_code.
• Skipping validate_code on host-authored Python for safety-critical operations (model toggles, BC writes, file.write_*).

Planning, retries, and recovery — host responsibility

This server is stateless. It deliberately ships no planner, no journal, no recipe registry, and no rollback. Multi-step plan construction, undo, retry policies, and "propose → confirm → apply" flows are the host's responsibility (VS Code Copilot, Cursor, Claude Desktop, or any custom agent that connects over MCP).

If the host has its own planner / agent loop, let it drive the discover → generate → validate → execute → verify cycle. This server will:

• accept and run each step,
• return rich error envelopes the host's planner can branch on,
• never retry, queue, or sequence steps internally.

Intent-guard error codes (defense-in-depth at run_code)

run_code runs an offline, stateless intent guard before exec to catch a fixed set of Fluent-specific crash signatures. It is NOT a planner — it inspects only the snippet you submitted. Disable with FLUIDS_MCP_INTENT_GUARD=0 if your host wants full control.

When the guard fires, run_code returns one of these error codes:

The blocking signatures (return risk_blocked / sequence_error) are:

1. bc.rename.whitespace — boundary rename whose new name contains whitespace. Use underscores instead ("oil_inlet", not "oil inlet").
2. multiphase.number_of_phases.shape — direct integer assignment to multiphase.number_of_phases. Use multiphase.number_of_phases.number_of_eulerian_phases = N.
3. seq.phase.material_before_rename — phase rename happens AFTER the material assignment in the same snippet. Rename first, then assign material to the new key.
4. runtime.write_during_iter — setup.* mutation while the solver is iterating. Interrupt first (solver.solution.run_calculation.interrupt()), then write.
5. seq.named_expr.use_before_create — a named expression is referenced before it is created in the same snippet. Reorder, or split into two run_code calls.
6. reportdef.surface_field — a report definition is given a surfaces field (attribute, .locations.surfaces, or a create-dict key). Report definitions take surface_names=[...] (surfaces is the graphics-object field).

In addition, non-blocking advisories are returned in the successful result's warnings list (they do NOT stop execution):

• named_expr.missing_units — a named expression is created with a bare number ({"definition": "9.81"}). Add a unit, e.g. "9.81 [m s^-2]"; a unit-less number is dimensionless and fails when consumed by a dimensioned slot.
• tui.usage — the snippet uses .tui.*. Prefer the solver.settings.* tree, which the rest of this server validates against.

These exist purely to prevent today's most expensive failure modes from killing the gRPC channel (blocks) or silently mis-configuring the case (warnings); they do not constitute a planner and they do not cross-call each other.