Develop PyFluent-MCP#

Set up your development environment and start contributing code to PyFluent-MCP.

Naming conventions#

PyFluent-MCP uses the standard PyAnsys MCP naming pattern:

Surface

Name

GitHub repository

pyfluent-mcp

PyPI distribution

ansys-fluent-mcp

Python namespace

ansys.fluent.mcp

Console script

ansys-fluent-mcp

Module launch

python -m ansys.fluent.mcp

Documentation title

PyFluent-MCP

Architecture#

PyFluent-MCP is built on the PyAnsysBaseMCP framework (from ansys-common-mcp), which is itself built on top of FastMCP. The server is a stateless MCP leaf: each tool call is self-contained, and the only persistent state across calls is the live Fluent connection and the per-session REPL namespace used by run_code.

Startup

  • Initializes the Solve MCP server (SolveMCP).

  • Loads the offline settings schema from settings_271.json.gz.

  • Waits for MCP client connections over STDIO or streamable HTTP.

Runtime

  • Exposes 22 MCP tools for Fluent interaction.

  • Routes live operations through the PyFluent backend.

  • Runs Python through an AST sandbox before it reaches the solver.

Shutdown

  • Releases the Fluent connection when disconnect is called or the server exits.

Package layout#

pyfluent-mcp/
├── src/ansys/fluent/mcp/     # Main package (ansys.fluent.mcp)
│   ├── __init__.py           # Version + public re-exports
│   ├── __main__.py           # ``python -m ansys.fluent.mcp``
│   ├── py.typed              # PEP 561 typing marker
│   ├── server.py             # ``launcher`` CLI entry point
│   ├── common/               # Shared infrastructure
│   │   ├── base.py           # FluidsLeafMCP
│   │   ├── backend.py        # Backend ABC
│   │   ├── config.py         # FLUIDS_MCP_* env vars
│   │   ├── network.py        # TLS and HTTP helpers
│   │   └── validation.py     # AST sandbox
│   └── solve/                # Fluent Solve MCP leaf
│       ├── mcp/              # SolveMCP
│       ├── backends/         # PyFluent backend (+ plugins)
│       ├── catalog/          # Schema and local API search
│       ├── lib/              # Domain tools
│       ├── data/             # settings_271.json.gz
│       └── skills/           # MCP-host routing skill
├── tests/
└── doc/                      # Sphinx documentation

ansys/ and ansys/fluent/ are namespace packages (no __init__.py), matching the PyAnsys layout used by ansys.fluent.core.

Check prerequisites#

Before you begin, ensure you have:

  • Python 3.12 or higher

  • Git installed

  • A text editor or IDE (such as Visual Studio Code or PyCharm)

  • A GitHub account

  • Ansys Fluent and PyFluent (for live-session testing)

Clone the repository#

  1. Fork the GitHub repository.

  2. Clone your fork locally:

    git clone https://github.com/YOUR_USERNAME/pyfluent-mcp.git
cd pyfluent-mcp

  3. Add the upstream repository as a remote:

    git remote add upstream https://github.com/ansys/pyfluent-mcp.git

Set up your development environment#

  1. Create a virtual environment:

    python -m venv .venv

  2. Activate the virtual environment:

    On Windows:

    .venv\Scripts\activate

    On macOS/Linux:

    source .venv/bin/activate

  3. Install the package in editable mode with development dependencies:

    pip install -e ".[pyfluent,tests]"

Run tests#

The test suite is offline-only (no live Fluent required):

pytest -q

Lint with Ruff:

ruff check src tests

Add a domain tool#

Domain tools are stateless backend/catalog operations registered in ansys.fluent.mcp.solve.lib.domain_tools. To add one:

  1. Write a typed coroutine in solve/lib/<area>.py:

    async def my_tool_impl(
    backend: Backend,
    *,
    arg1: str,
    arg2: float | None = None,
) -> dict[str, Any]:
    ...

  2. Append a DomainTool entry to get_solve_domain_tools() in solve/lib/domain_tools.py.

SolveMCP._register_tools() already registers everything returned by that function.

For a full walkthrough, see Implement a custom domain tool.

Install external backends#

You can install packages through the ansys.fluent.mcp.solve_backends entry-point group to provide additional execution backends. At construction time, SolveMCP discovers and merges external backends without modifying this repository.

Submit changes#

  1. Create a feature branch from main.

  2. Make your changes with tests.

  3. Run pytest and ruff check.

  4. Open a pull request against ansys/pyfluent-mcp.

Next steps#