# ANSYS Fluent MCP Server

A Model Context Protocol (MCP) server that helps AI assistants navigate ANSYS Fluent online documentation efficiently.

## Features

- **Smart URL Navigator** - Find relevant ANSYS Help documentation URLs instantly
- **35+ Topic Routes** - Pre-mapped paths to common Fluent topics
- **Always Up-to-Date** - Points to official ANSYS documentation
- **Zero Maintenance** - No static content to update
- **Lightweight** - Fast URL generation, no heavy indexing

## Quick Start

### Prerequisites

- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager

### Installation

Choose your MCP client below for setup instructions:

<details>
<summary><b>Claude Code</b> (CLI)</summary>

```bash
claude mcp add fluent -- uvx fluent-mcp-server
```

**Verify:**
```bash
claude mcp list
claude mcp info fluent
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "fluent": {
      "command": "uvx",
      "args": ["fluent-mcp-server"]
    }
  }
}
```

Restart Claude Desktop completely after saving.

</details>

<details>
<summary><b>Cursor</b></summary>

Go to `Cursor Settings` → `MCP` → `Add new MCP Server`:
- **Name**: `fluent`
- **Command**: `uvx fluent-mcp-server`

Or edit config file:

**macOS**: `~/Library/Application Support/Cursor/mcp_config.json`
**Windows**: `%APPDATA%\Cursor\mcp_config.json`
**Linux**: `~/.config/Cursor/mcp_config.json`

```json
{
  "mcpServers": {
    "fluent": {
      "command": "uvx",
      "args": ["fluent-mcp-server"]
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b> (GitHub Copilot)</summary>

**CLI:**
```bash
code --add-mcp '{"name":"fluent","command":"uvx","args":["fluent-mcp-server"]}'
```

**Or add to VS Code settings:**
```json
{
  "github.copilot.chat.mcp.servers": {
    "fluent": {
      "command": "uvx",
      "args": ["fluent-mcp-server"]
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b> (VS Code Extension)</summary>

Install [Cline extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev), then add to VS Code settings:

```json
{
  "cline.mcpServers": {
    "fluent": {
      "command": "uvx",
      "args": ["fluent-mcp-server"]
    }
  }
}
```

Reload VS Code window after saving.

</details>

**For 11 additional clients** (Windsurf, Continue, Amp, Codex, Gemini CLI, Goose, Kiro, LM Studio, opencode, Qodo Gen, Warp), see **[Complete Setup Guide →](md-files/MCP_CLIENT_SETUP.md)**

### Local Development

```bash
# Clone the repository
git clone https://github.com/your-org/fluent-mcp-server.git
cd fluent-mcp-server

# Install with uv
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run server
uv run fluent-mcp-server
```

**Development configuration** (`.mcp.json` in project root):

```json
{
  "mcpServers": {
    "fluent": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/fluent-mcp-server",
        "run",
        "fluent-mcp-server"
      ]
    }
  }
}
```

## Available Tools

### `search_help`

Find ANSYS Fluent documentation URLs for your query. Returns search URLs and suggested manual sections.

**Parameters:**
- `query` (required): Search term (e.g., "flamelet model", "read case", "turbulence")
- `max_suggestions` (optional): Maximum manual section suggestions (default: 3)

**Returns:**
- ANSYS Help search URL
- Suggested manual sections (if topic is pre-mapped)
- Links to all major manuals

**Example:**
```python
search_help("flamelet model")
# Returns:
# - Search URL: https://ansyshelp.ansys.com/search?q=flamelet+model
# - Suggested: flamelet User Guide + Theory Guide
# - All manuals: User Guide, TUI, Theory, UDF

search_help("read case")
# Returns URLs to file/read-case TUI documentation
```

### `list_topics`

List the 35+ topics with pre-mapped documentation routes.

**Returns:** List of topics like: file, turbulence, combustion, flamelet, mesh, boundary, udf, etc.

**Example:**
```python
list_topics()
```

### `get_manual_link`

Get direct link to a specific Fluent manual or section.

**Parameters:**
- `manual` (required): Manual name (`user_guide`, `tui`, `theory`, `udf`)
- `section` (optional): Section path (e.g., "turbulence", "file/read-case")

**Example:**
```python
get_manual_link("udf", "introduction")
# Returns: https://ansyshelp.ansys.com/.../flu_udf/introduction.html
```

## Usage Examples

### In Claude Code / AI Assistant

```
You: How do I use the flamelet model in Fluent?
Claude: [Calls search_help("flamelet model")]
        [Receives URLs to flamelet documentation]
        [Uses WebFetch to read the actual documentation]
        [Provides answer based on official ANSYS docs]

You: Show me the command to read a case file
Claude: [Calls search_help("read case")]
        [Gets URL to file/read-case TUI command]
        [Retrieves documentation and shows syntax]
```

### Architecture Flow

```
User Query → MCP search_help → Returns URLs →
LLM uses WebFetch → Reads official docs → Answers user
```

The MCP server acts as a **smart navigator**, not a content database.

## Architecture

```
fluent-mcp-server/
├── src/fluent_mcp_server/
│   ├── server.py          # FastMCP server & tool definitions
│   ├── doc_finder.py      # Smart URL router (35+ topic mappings)
│   └── __init__.py
├── md-files/
│   ├── ARCHITECTURE.md    # Technical architecture
│   └── ...
├── tests/                 # Unit tests
├── examples/              # Usage examples
└── pyproject.toml        # Project configuration
```

## Roadmap

**Phase 1.x: Route Expansion (Future)**
- Add more topic routes based on usage patterns
- Version selection (v251, v252, v253)
- Usage analytics to identify popular topics

**Phase 2: PyFluent Integration (Planned)**
- Connect to Fluent sessions
- Execute TUI commands programmatically
- Case I/O via PyFluent API
- Mesh quality automation
- Convergence monitoring

**Phase 3: Workflow Automation (Planned)**
- Boundary condition templates
- Solver configuration wizards
- Post-processing automation
- Parametric studies

See [`md-files/ARCHITECTURE.md`](md-files/ARCHITECTURE.md) for detailed roadmap.

## Documentation

**Getting Started:**
- [`md-files/QUICKSTART.md`](md-files/QUICKSTART.md) - Setup and usage guide
- [`README.md`](README.md) - This file (overview)

**Technical Documentation:**
- [`md-files/ARCHITECTURE.md`](md-files/ARCHITECTURE.md) - System architecture and design
- [`md-files/TOOLS.md`](md-files/TOOLS.md) - Complete tool catalog
- [`md-files/ANSYS_HELP_GUIDE.md`](md-files/ANSYS_HELP_GUIDE.md) - ANSYS Help site patterns

**Validation & Analysis:**
- [`md-files/REDDIT_REAL_WORLD_EXAMPLES.md`](md-files/REDDIT_REAL_WORLD_EXAMPLES.md) - Real user questions
- [`md-files/GAP_ANALYSIS.md`](md-files/GAP_ANALYSIS.md) - Coverage analysis
- [`md-files/USERSTORY.md`](md-files/USERSTORY.md) - User scenarios

**Development:**
- [`examples/`](examples/) - Usage examples
- [`tests/`](tests/) - Unit tests

## License

MIT License

## Contributing

Contributions welcome! Please ensure:
- Tests pass: `uv run pytest`
- Code follows existing style
- Documentation updated
# fluent-mcp-server