Metadata-Version: 2.4
Name: ras-commander-mcp
Version: 0.3.0
Summary: MCP server for querying HEC-RAS project information
Project-URL: Homepage, https://github.com/fema-ffrd/ras-commander-mcp
Project-URL: Documentation, https://github.com/fema-ffrd/ras-commander-mcp/blob/main/README.md
Project-URL: Repository, https://github.com/fema-ffrd/ras-commander-mcp.git
Project-URL: Issues, https://github.com/fema-ffrd/ras-commander-mcp/issues
Author: RAS Commander Team
License: MIT
License-File: LICENSE
Keywords: claude,hecras,hydraulic-modeling,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Requires-Dist: matplotlib
Requires-Dist: mcp
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: ras-commander
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# HEC-RAS MCP Server

<div align="center">
  <img src="ras_commander_mcp_logo.svg" alt="RAS Commander MCP Logo" width="70%">
</div>  

The RAS Commander MCP (Model Context Protocol) server provides tools for querying HEC-RAS project information using the ras-commander library. This allows Claude Desktop to interact with HEC-RAS hydraulic modeling projects.

## Key Features

- **Stateful Context**: Initialize a project once, then query it multiple times without repeating the project path
- **Comprehensive Project Summary**: Get all project info including plans, geometries, flows, and projection data
- **Flexible Plan Queries**: Get all plans or specific plan details
- **Infiltration Analysis**: Extract and analyze soil infiltration data
- **Results Summary**: Access unsteady flow results, volume accounting, and runtime statistics
- **Smart Path Handling**: Automatic HDF file detection for projection info
- **Error Handling**: Helpful diagnostics for common issues

## Prerequisites

1. **HEC-RAS Installation**: HEC-RAS must be installed on your system (default expects version 6.6)
2. **Python**: Python 3.8+ with Anaconda recommended
3. **Claude Desktop**: For MCP integration

## Installation

### For Claude Desktop Users (Recommended)

1. **Install uv** (one-time setup):
   - **Windows**: 
     ```powershell
     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
     ```
   - **macOS/Linux**: 
     ```bash
     curl -LsSf https://astral.sh/uv/install.sh | sh
     ```

2. **Configure Claude Desktop**:
   Add the following to your Claude Desktop configuration file:

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

   ```json
   {
     "mcpServers": {
       "hecras": {
         "command": "uvx",
         "args": ["ras-commander-mcp"],
         "env": {
           "HECRAS_VERSION": "6.6"
         }
       }
     }
   }
   ```

3. **Restart Claude Desktop**

That's it! The MCP server will be automatically downloaded and run when needed.

### For Developers

To install for development:

```bash
# Clone the repository
git clone <repository-url>
cd ras-commander-mcp

# Install in development mode with uv
uv pip install -e .

# Or with standard pip
pip install -e .
```

### Legacy Installation (Alternative)

If you prefer the traditional approach:

1. Clone this repository:
```bash
git clone <repository-url>
cd ras-commander-mcp
```

2. Install dependencies using the Anaconda environment:
```bash
# Create and activate conda environment
conda create -n hecras-mcp python=3.9
conda activate hecras-mcp
pip install -r requirements.txt
```

## Configuration

### Configuration Options

You can configure the server through environment variables in the Claude Desktop config:

```json
{
  "mcpServers": {
    "hecras": {
      "command": "uvx",
      "args": ["ras-commander-mcp"],
      "env": {
        "HECRAS_VERSION": "6.5",  // HEC-RAS version (default: 6.6)
        "HECRAS_PATH": "C:\\Custom\\Path\\To\\HEC-RAS.exe"  // Custom HEC-RAS path
      }
    }
  }
}
```

### Legacy Configuration (for manual installation)

If you're using the legacy installation method:

```json
{
  "mcpServers": {
    "hecras": {
      "command": "python",
      "args": ["path/to/your/ras-commander-mcp/server.py"],
      "env": {
        "HECRAS_VERSION": "6.5"
      }
    }
  }
}
```

### Troubleshooting

If you encounter issues:

1. **Verify uv installation**: Run `uv --version` in a terminal
2. **Check HEC-RAS installation**: Ensure HEC-RAS is installed in the default location or set `HECRAS_PATH`
3. **Test the server**: Run `uvx ras-commander-mcp` in a terminal to see any error messages
4. **Clear uv cache**: If you have issues with updates, run `uv cache clean`

## Available Tools

### 1. **get_ras_projectsummary**
Get comprehensive project information including plans, geometries, flows, boundaries, and projection info. This tool initializes the project context for subsequent calls.

**Parameters:**
- `project_path` (optional): Full path to HEC-RAS project folder
- `include_boundaries` (optional): Include boundary conditions data (default: false)

### 2. **get_ras_planinfo**
Get plan information from the project. Can return all plans or a specific plan.

**Parameters:**
- `project_path` (optional): Full path to HEC-RAS project folder
- `plan_number` (optional): Specific plan number (e.g., "01", "02")

### 3. **get_ras_infiltration**
Get infiltration layer data and soil statistics from the project.

**Parameters:**
- `project_path` (optional): Full path to HEC-RAS project folder
- `significant_threshold` (optional): Minimum percentage threshold for significant mukeys (default: 1.0)

### 4. **get_ras_resultssummary**
Get comprehensive results from a specific plan including unsteady info, volume accounting, and runtime data.

**Parameters:**
- `plan_name` (required): Name or number of the plan
- `project_path` (optional): Full path to HEC-RAS project folder

### 5. **get_projection_info**
Get spatial projection information (WKT string) from HDF files.

**Parameters:**
- `hdf_path` (optional): Full path to HDF file (auto-detects if not provided)

### 6. **get_1d_profile_results**
Get maximum water surface elevation and velocity for 1D cross sections in a river/reach.

**Parameters:**
- `plan_name` (required): Name or number of the plan
- `river_name` (optional): River name (if not specified, returns all rivers)
- `reach_name` (optional): Reach name (only used if river_name is specified)
- `project_path` (optional): Full path to HEC-RAS project folder

**Returns:** Formatted table with station, max WSEL, and max velocity for each cross section.

### 7. **compare_1d_profiles**
Compare maximum water surface elevations between two plans for 1D cross sections.

**Parameters:**
- `plan1_name` (required): Name or number of the first plan (baseline)
- `plan2_name` (required): Name or number of the second plan (comparison)
- `river_name` (optional): River name (if not specified, returns all rivers)
- `reach_name` (optional): Reach name (only used if river_name is specified)
- `project_path` (optional): Full path to HEC-RAS project folder

**Returns:** Comparison table with differences and comprehensive statistics including stations unique to each plan.

### 8. **plot_1d_profile**
Plot 1D profile results showing water surface elevation vs station.

**Parameters:**
- `plan_name` (required): Name or number of the plan to plot
- `river_name` (optional): River name (if not specified, shows all rivers)
- `reach_name` (optional): Reach name (only used if river_name is specified)
- `project_path` (optional): Full path to HEC-RAS project folder

**Returns:** Embedded PNG plot as base64 image in markdown format.

### 9. **plot_1d_profile_comparison**
Plot comparison of 1D profiles between two plans.

**Parameters:**
- `plan1_name` (required): Name or number of the first plan (baseline)
- `plan2_name` (required): Name or number of the second plan (comparison)
- `river_name` (optional): River name (if not specified, shows all rivers)
- `reach_name` (optional): Reach name (only used if river_name is specified)
- `project_path` (optional): Full path to HEC-RAS project folder

**Returns:** Embedded PNG comparison plot with thalweg data, annotations, and detailed statistics.

### 10. **get_1d_xsec_timeseries**
Get detailed time series results for a specific 1D cross section including water surface elevation, velocity, flow, and other hydraulic variables.

**Parameters:**
- `plan_name` (required): Name or number of the plan
- `river_name` (required): River name
- `reach_name` (required): Reach name  
- `station` (required): River station (e.g., '27857.47')
- `project_path` (optional): Full path to HEC-RAS project folder

**Returns:** Time series data with summary statistics (max, min, mean, time of max) for each variable.

## Usage Examples

### In Claude Desktop

Once configured, you can ask Claude:

```
"Get the project summary for C:/Projects/MyRiverModel"
"Show me plan 04 details"  (no path needed after initialization!)
"Get infiltration data with 5% threshold"
"Show results summary for plan 04"
"What's the projection info?"
```

### Key Feature: Stateful Context

The server maintains project context between calls:

1. **First call** - Initialize with project path:
   ```
   "Get project summary for C:/Projects/MyRiverModel"
   ```

2. **Subsequent calls** - No path needed:
   ```
   "Show me plan 02"
   "Get infiltration data"
   "Show results for plan 04"
   ```

3. **Switch projects** - Just provide a new path:
   ```
   "Get project summary for C:/Projects/AnotherModel"
   ```

### Testing

Run the example client to test the server:

```bash
# Using the activated conda environment
python example_client.py
```

Or test directly without MCP protocol:

```bash
python test_server.py
```

## Test Data

The `testdata/Muncie/` folder contains a complete HEC-RAS project for testing, including:
- Multiple plan configurations
- HDF5 result files
- Terrain and infiltration data
- Geometry files
- Boundary conditions

## Troubleshooting

1. **ImportError for ras-commander**: Ensure ras-commander is installed and HEC-RAS is properly installed
2. **Project not found**: Verify the project path exists and contains .prj files
3. **Version errors**: Check that the specified HEC-RAS version matches your installation
4. **No context available**: Make sure to initialize a project first with `get_ras_projectsummary`

## Development

To modify or extend the server:

1. Edit `server.py` to add new tools or modify existing ones
2. Test changes with `test_server.py` (direct testing)
3. Test MCP integration with `example_client.py`
4. Update Claude Desktop configuration if needed

## What's New in v0.3.0

- **Enhanced 1D Profile Comparison**: Properly handles mismatched stations between plans
- **Improved Statistics**: Separate statistics for matching vs non-matching stations
- **Better Plotting**: Enhanced plots with thalweg data, annotations, and visual markers
- **New Tool**: `get_1d_xsec_timeseries` for detailed cross-section time series analysis
- **Outer Join Logic**: Shows stations that exist in only one plan during comparisons
- **Thalweg Integration**: Automatic thalweg plotting from geometry data where available
- **Enhanced Annotations**: Plot annotations show maximum differences and locations
- **Better Error Handling**: More robust data extraction and error reporting

## What's New in v0.2.0

- **Stateful Context**: Project persistence between tool calls
- **Improved Tool Names**: More consistent `get_ras_*` naming convention
- **Consolidated Tools**: Geometry info now included in project summary
- **Smart Defaults**: Auto-detection of HDF files for projection info
- **Enhanced Plan Queries**: Support for querying by plan number
- **Better Error Messages**: More helpful context-aware error handling

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Trademarks

See [TRADEMARKS.md](TRADEMARKS.md) for trademark information and compliance policies.