内容
# PyFluent-MCP
[](https://docs.pyansys.com/)
[](https://www.python.org/)
[](https://opensource.org/licenses/Apache-2.0)
PyFluent-MCP（`ansys-fluent-mcp`）为您提供一个 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，允许 AI 助手通过 [PyFluent](https://fluent.docs.pyansys.com/) 与 Ansys Fluent 进行交互。您可以使用自然语言设置、运行和后处理 CFD 求解器工作流程。
PyFluent-MCP 建立在 PyAnsys 公共 MCP（[ansys-common-mcp](https://github.com/ansys/pyansys-common-mcp)）之上，这是一个共享的 PyAnsys MCP 基础。
您可以将此软件包作为独立的 MCP 服务器运行。它还作为更高级别产品的 **核心 + 求解** 基础。这些产品依赖于此软件包，并通过 MCP 调用求解工具。依赖关系始终是单向的。此软件包永远不会依赖、导入或引用使用它的产品。
有关架构详细信息、图表和完整的工具参考，请参阅 [PyFluent-MCP 文档](https://fluent-mcp.docs.pyansys.com)。有关贡献信息，包括如何在本地构建文档，请参阅 [贡献](https://fluent-mcp.docs.pyansys.com/version/stable/getting_started/contribution.html)。
## 概述
服务器是一个 **无状态** 的 MCP 叶子节点。您的外部 LLM 主机（VS Code Copilot、Claude Desktop、Cursor 或自定义代理）调用一组专注的工具。
LLM 永远不会直接写入 Fluent。服务器仅通过验证的沙盒执行路径运行 Python。
主要功能包括：
- **动态管理连接**：启动新的 Fluent 会话，附加到现有的会话（本地或远程），或按需断开连接。
- **检查实时设置树**：浏览活动 Fluent 设置 API、命名对象、允许值和目标上下文。
- **离线生成代码**：使用捆绑的设置模式在不使用网络服务的情况下从自然语言生成 Fluent 设置 API 代码。
- **通过验证的执行路径运行代码**：在 AST 沙盒后面运行或预检查 Python 代码。
- **查看结果和诊断**：总结设置、构建模拟报告、检查网格质量、列出字段、比较案例文件和捕获截图。
- **使用模型和提供者无关的 LLM 支持**：通过单个进程内传输缝隙与任何模型和提供者合作：原生 API（OpenAI、Azure、Anthropic 和 Google Gemini）通过 LiteLLM，或 OpenAI 兼容的端点。
- **使用可插拔的后端扩展**：默认使用本地 PyFluent 后端，并通过单独安装的入口点包添加执行后端。
## 工具表面
服务器暴露了 22 个工具，您可以使用：
| 分组 | 工具 |
|-------|-------|
| 连接和会话 | `connect`, `disconnect`, `session_status`, `solver_status` |
| 模式发现 | `find_api`, `get_help`, `get_state`, `get_targeted_context` |
| 命名对象 | `list_named_objects`, `find_named_object`, `select_named_objects` |
| 代码生成和执行 | `codegen`, `clarify`, `run_code`, `validate_code` |
| 报告和检查 | `summarize_setup`, `simulation_report`, `screenshot`, `manage_component` |
| 网格/字段/比较 | `mesh_quality`, `list_fields`, `compare_files` |
## 需求
| 需求 | 何时需要 | 备注 |
|-------------|-------------|-------|
| Python 3.13 或更高版本 | 始终 | 支持 3.13 和 3.14 |
| 核心运行时依赖 | 始终（自动安装） | `ansys-common-mcp`, `fastmcp`, `httpx`, `pydantic` |
| [PyFluent](https://fluent.docs.pyansys.com/)（`ansys-fluent-core` 0.27 或更高版本） | 驱动实时 Fluent 会话（`connect`, `run_code`, `get_state`, `mesh_quality`, …） | 执行后端的可选 `pyfluent` |
| 许可的本地 ANSYS Fluent 安装 | 实际启动/附加求解器 | PyFluent 通过 gRPC 与此 Fluent 安装通信 |
| `h5py` 3.0 或更高版本 | 仅用于 `.h5`/`.cas.h5` 文件的 `compare_files` | `file-probe` 可选 |
> **PyFluent 对于实时会话工具是必需的。** 您可以使用可选的 `pyfluent` 额外功能安装它，而不是作为硬依赖项。这样可以在没有 Fluent 的情况下使用离线工具（`find_api`, `get_help`, `codegen`, `clarify` 和 `validate_code`）。任何涉及求解器的工具，包括 `connect`, `run_code`, `get_state`, `summarize_setup`, `mesh_quality` 和 `screenshot`，都需要 `ansys-fluent-core` 和您机器上的许可 Fluent 安装。
## 安装
安装最新版本：
```bash
pip install ansys-fluent-mcp
```
同时拉取本地 PyFluent 后端（实时 Fluent 会话所需）：
```bash
pip install "ansys-fluent-mcp[pyfluent]"
```
有关更多信息，请参阅 [需求](#需求)。
要添加 `compare_files` 使用的可选 HDF5 文件探测支持：
```bash
pip install "ansys-fluent-mcp[pyfluent,file-probe]"
```
如果您想要具有 PyFluent 后端和测试依赖的可编辑开发人员安装：
```bash
git clone https://github.com/ansys/pyfluent-mcp.git
cd pyfluent-mcp
pip install -e ".[pyfluent,tests]"
```
## 用法
对于启动服务器进程的桌面 MCP 客户端，请使用 STDIO。对于仅在受信任网络或提供身份验证和 TLS 的基础设施后面的 HTTP，请使用 HTTP。
通过 STDIO（默认 MCP 传输）运行服务器：
```bash
ansys-fluent-mcp
```
或通过可流式 HTTP 运行服务器：
```bash
ansys-fluent-mcp --transport http --host 127.0.0.1 --port 8000
```
启动 MCP 服务器仅使工具可用。您仍然需要一个与之连接的 MCP 兼容客户端，例如 VS Code Copilot、Claude Desktop、Cursor 或另一个助手主机，以连接并调用这些工具。在选择传输后，在客户端的 MCP 配置中注册服务器。
如果您运行本地 Windows 检查，请在客户端指向虚拟环境入口点。对于 VS Code MCP 支持，请在 VS Code MCP 配置中添加类似以下内容的服务器条目：
```json
{
"servers": {
"ansys-fluent-mcp": {
"type": "stdio",
"command": "D:\\Development\\fluent\\pyfluent-mcp\\.venv\\Scripts\\ansys-fluent-mcp.exe"
}
}
}
```
## 配置
您可以通过 `FLUIDS_MCP_*` 环境变量配置服务器。常见变量如下：
| 变量 | 效果 |
|----------|--------|
| `FLUIDS_MCP_SETTINGS_JSON` | 使用外部文件覆盖捆绑的设置模式 |
| `FLUIDS_MCP_LOG_LEVEL` | 设置日志级别（默认 `INFO`） |
| `FLUIDS_MCP_API_RETRIEVER_URL`/`FLUIDS_MCP_QDRANT_URL` | 选择加入语义 API 检索器（默认离线） |
| `FLUIDS_MCP_DISABLE_SESSION_LOGS` | 设置为 `1` 以禁用会话日志 |
| `FLUIDS_MCP_LLM_MAX_STEPS` | 设置 LLM 代码生成工具循环迭代的上限（默认 `30`） |
### 模型和提供者无关的 LLM 配置
#### 简介
一些功能使用 AI 模型。您需要设置三个环境变量：
- 设置 AI 提供者。
- 设置 AI 模型。
- 设置 API 密钥。
选择与您的设置匹配的示例。替换 `<...>` 并启动服务器。系统会自动解析其余部分。
**OpenAI 密钥**
```bash
export OPENAI_API_KEY="<your-openai-key>"
export LLM_PROVIDER="openai"
export LLM_MODEL="gpt-4o"
```
**Anthropic (Claude) 密钥**
```bash
export ANTHROPIC_API_KEY="<your-anthropic-key>"
export LLM_PROVIDER="anthropic"
export LLM_MODEL="claude-3-5-sonnet"
```
**Google Gemini 密钥**
```bash
export GEMINI_API_KEY="<your-gemini-key>"
export LLM_PROVIDER="gemini"
export LLM_MODEL="gemini-1.5-pro"
```
**您组织提供的 URL 和密钥** （Azure OpenAI 或任何 OpenAI 兼容网关）
```bash
export LLM_ENDPOINT="<the-url-you-were-given>"
export LLM_API_KEY="<your-key>"
export LLM_MODEL="gpt-4o"
```
对于前三个选项，请安装提供者连接器一次：
`pip install ansys-fluent-mcp[providers]`。连接器是免费的。您只需支付 AI 提供者的费用。
#### 完整参考
每个 LLM 驱动的功能都是模型和提供者无关的。服务器根据您的模型和端点在两种传输之间进行选择：
- **原生供应商 API** （OpenAI、Azure OpenAI、Anthropic、Google Gemini）：服务器通过 **LiteLLM SDK 作为进程内库** 访问这些 API，而不是代理。设置 `LLM_PROVIDER` （或使用原生模型名称，例如 `claude-3-5-sonnet`）和匹配的 API 密钥。
- **OpenAI 兼容的 `/chat/completions`** 自定义端点（vLLM、Ollama 或网关）：设置 `LLM_ENDPOINT`。服务器直接通过 `httpx` 发送请求。
单个功能配置文件（`LLMProfile`）控制路由选择、传输、工具模式、提供者特定的令牌缓存和重试行为。`llm_wire.acall()`、`llm_wire.call()` 和 `llm_wire.astream()` 方法是唯一请求路径。解析和请求塑形位于 `ansys.fluent.mcp.common.llm_wire` 中。`common/config.py` 显示解析的提供者/传输。
> **成本：** LiteLLM SDK 采用 MIT 许可，免费使用。您只需通过自己的密钥支付提供者的令牌费用。匿名 LiteLLM 遥测被集成禁用。
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `LLM_PROVIDER` | 自动 | `openai`/`azure`/`anthropic`/`gemini`/`compat` （根据模型/端点推断，当未设置时） |
| `LLM_TRANSPORT` | 自动 | `litellm` （原生 API）或 `openai_compat` （通过 `LLM_ENDPOINT` 使用 httpx） |
| `LLM_ENDPOINT` | 未设置 | OpenAI 兼容的聊天完成 URL（自定义/本地端点） |
| `LLM_API_KEY` | 未设置 | 兼容路径的 Bearer 令牌（或 Azure 密钥） |
| `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`/`GEMINI_API_KEY`/`AZURE_API_KEY` | 未设置 | 原生路径的每个供应商密钥 |
| `LLM_API_BASE`/`LLM_API_VERSION` | 未设置 | Azure 基址/版本（也从 `AZURE_API_BASE` / `AZURE_API_VERSION` 读取） |
| `LLM_MODEL` | `gpt-4o-mini` | 模型名称（第一个空格令牌有效）；可以是 `provider/model` 路由 |
| `LLM_AUTH_STYLE` | 自动 | `bearer` 或 `azure-api-key` （兼容路径） |
| `LLM_CACHE_MECHANISM` | 自动 | `openai_auto`/`anthropic_cache_control`/`gemini_context`/`none` |
| `LLM_CACHE_TTL_SECONDS` | 每个提供者 | 缓存 TTL 提示，用于调整保持活动状态 |
| `LLM_MAX_TOKENS_PARAM` | 自动 | `max_tokens` 与 `max_completion_tokens` （自动适用于 gpt-5 / o 系列） |
| `LLM_SEND_TEMPERATURE` | 自动 | `0` 省略 `temperature` （自动关闭 gpt-5/o 系列） |
| `LLM_SEND_CACHE_KEY` | `1` | `0` 省略缓存路由提示/缓存断点 |
| `LLM_MAX_RETRIES`/`LLM_TIMEOUT_SECONDS` | `3`/`60` | 传输缝隙重试/超时 |
### TLS 和网络出口控制
默认情况下，为所有外出的 LLM 和检索调用启用 TLS 证书验证。如果您需要信任公司或自签名 CA，请将客户端指向您的 CA 捆绑包，而不是禁用验证。
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `LLM_CA_BUNDLE` | 未设置 | 用于验证 TLS 的 PEM CA 捆绑包路径（也读取 `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`） |
| `LLM_TLS_INSECURE` | `0` | `1` 禁用 TLS 验证（记录警告；将密钥/提示暴露给中间人 - 仅限开发） |
| `FLUIDS_AGENT_OFFLINE` | `0` | `1` 禁止所有外出的 LLM 和网络检索调用（紧急开关） |
| `FLUIDS_AGENT_ALLOWED_LLM_HOSTS` | 未设置 | 以逗号分隔的主机允许列表，在任何外出的调用之前强制执行 |
服务器自动应用 **每个提供者的令牌缓存**。
- OpenAI 和 Azure 使用自动前缀缓存和稳定的 `prompt_cache_key`。
- Anthropic 使用稳定的系统前缀上的临时 `cache_control` 断点。
- Gemini 依赖于隐式上下文缓存。
服务器将提供者之间的用法标准化为规范的 `cached_prompt_tokens` （缓存读取）和 `cache_creation_tokens` （缓存写入）。
要安装原生提供者：
```bash
pip install ansys-fluent-mcp[providers]
```
模型特定的逻辑被隔离到 `llm_wire` 中的一个小型前缀键控异常表中（目前为 gpt-5、o1、o3 和 o4）。当您在那里添加模型系列时，每个调用站点都继承行为，而无需逐个调用特殊情况或运行时错误字符串嗅探。
## 许可证
该项目根据 Apache 2.0 许可协议许可。有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 资源
- [PyFluent 文档](https://fluent.docs.pyansys.com/)
- [模型上下文协议](https://modelcontextprotocol.io/)
- [ansys-common-mcp](https://github.com/ansys/pyansys-common-mcp)
有关 PyAnsys 的一般问题，请发送电子邮件至 pyansys.core@ansys.com。
