Agentic HEC-RAS

A headless, natural-language-driven, automated modelling workflow for HEC-RAS. Skills + an MCP server for Claude Code, Codex, Hermes, or OpenClaw: describe a goal in plain language and the agent inspects, edits, runs, reads, compares and plots a HEC-RAS model — 1D, 2D or 1D/2D — without ever opening the GUI.

<p> <a href="https://github.com/Zhonghao1995/Agentic-HEC-RAS/actions/workflows/ci.yml"><img src="https://github.com/Zhonghao1995/Agentic-HEC-RAS/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <img src="https://img.shields.io/badge/python-3.10%2B-3776AB" alt="Python 3.10+" /> <img src="https://img.shields.io/badge/HEC--RAS-6.x%20%7C%207.0.1-1F6FEB" alt="HEC-RAS 6.x / 7.0.1" /> <img src="https://img.shields.io/badge/MCP-1.x%20%7C%202.x-7C3AED" alt="MCP 1.x / 2.x" /> <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" /> <img src="https://img.shields.io/badge/status-experimental-orange" alt="experimental" /> </p>

Experimental / pre-release. One MCP server (10 tools) + 5 skills, a thin layer over ras-commander (MIT) and h5py. Verified end to end on HEC's official Muncie 2D example with HEC-RAS 7.0.1. Sibling of agentic-swmm-workflow (urban drainage) and Agentic-MIKE-Plus (MIKE+): together they cover sewer network → river / 2D flood hydraulics under one agentic pattern.

Install: just tell your agent

Paste this to your AI coding agent (Claude Code, Codex, Hermes, OpenClaw):

Install "Agentic HEC-RAS" for me: an MCP server + skills to drive HEC-RAS headless.

1. Clone https://github.com/Zhonghao1995/Agentic-HEC-RAS and skim its README.
2. With Python 3.10+:
     python -m venv .venv
     .venv\Scripts\python.exe -m pip install -e .
3. Register with me (Claude Code):
     claude mcp add hec-ras -- "<abs-repo>\.venv\Scripts\python.exe" -m hecras_mcp.server
   (Codex / Hermes / OpenClaw: copy config/mcp.sample.json)
4. Copy skills/* into ~/.claude/skills/, then run scripts/smoke_test.py (should list 10 tools).
5. Tell me which tools need HEC-RAS installed (only ras_run does) and where Ras.exe was found
   (set HECRAS_EXE if it was not).

Two install profiles:

• Read / compare / plot / edit files. Cross-platform, no HEC-RAS: pip install -e . — everything except ras_run works on any machine that has the .p##.hdf results (or the project text files).
• Run too. Windows + HEC-RAS 6.x / 7.0.1 installed (free download, no license). Ras.exe is auto-detected in the default install folder, or set HECRAS_EXE.

Why it matters

• Natural-language-driven. "Run the 2D plan with 20 % more inflow and tell me how much the downstream stage rises" — the agent copies the project, edits the .u##, runs Ras.exe -c, reads the HDF, compares, plots, and writes a manifest.
• Fully headless. No GUI, no COM controller: HEC-RAS's own command line (Ras.exe -c project.prj plan.p##) inside a copied project folder.
• MCP-native and portable. One server speaks the Model Context Protocol; works with Claude Code, Codex, Hermes or OpenClaw via a single config line.
• HEC-RAS optional for reading. Results (.p##.hdf), comparison and figures need only Python — teammates without HEC-RAS can still analyse.
• Verification-first. ras_run returns a QA status (max WSEL error, volume error %, ERROR / WARNING lines) the skills must gate on; every case ends with a sha256 manifest.
• Small and testable. Pure-Python contracts (boundary-table rewriting, QA classification, comparison, manifest) with a HEC-RAS-free unit-test suite in CI; add a tool or skill by dropping in a file.

How it works

Skills (markdown playbooks) tell the agent when and how; the agent calls MCP tools; the tools call ras-commander (project parsing, .p## edits, Ras.exe -c) and h5py (results). The server never imports HEC-RAS itself, so it starts anywhere.

agent  ->  reads skills/ras-*/SKILL.md  ->  calls MCP tools  ->  ras-commander / h5py  ->  Ras.exe -c  /  .p##.hdf

Tools (one server, hec-ras)

Tool	Does	HEC-RAS
ras_project_info	plans (title, g##/u##, sim window, intervals, cores, results present?), geometries, flow files, boundary conditions (river/reach/RS or 2D BC line, kind, interval, n, peak)	no
ras_project_copy	copy the whole project folder (terrain / DSS refs stay valid) before any edit or run	no
ras_plan_set	simulation window, computation / output / mapping interval, cores, short id, title, description, geometry, flow file	no
ras_flow_set_hydrograph	replace or scale one boundary table (flow / stage / lateral / precipitation / gate), set QMult, change interval	no
ras_run	Ras.exe -c headless run + QA: status, max WSEL error, volume error %, log tail, runtime, HDF path	yes
ras_results_summary	run QA, volume accounting, cross-section peaks, 2D wet cells / max depth, reference lines, units	no
ras_results_timeseries	one series (cross section, reference line / point, boundary, 2D cell) with peak and timing	no
ras_results_compare	baseline vs scenario: delta peak / timing / RMSE / NSE / volume, or every cross section ranked by change	no
ras_plot	hydrograph overlay, max-WSE profile, 2D max-depth map (PNG)	no
ras_manifest_write	provenance manifest: project, plan, inputs, results, figures with sha256, run QA, edits, tool calls	no

Five skills orchestrate them: ras-end-to-end (the SOP: modes, run directory, hard rules, stop rules, QA gates), ras-model, ras-runner, ras-results, ras-audit.

Install the skills into any skills-aware agent (Claude Code, Codex, OpenCode, …) in one command, no clone needed:

npx skills add Zhonghao1995/Agentic-HEC-RAS      # all 5; add --list to preview, or --skill <name> for one

Demo: Muncie (official 2D example, HEC-RAS 7.0.1)

Baseline vs +20 % upstream inflow, entirely through the tools (scripts/e2e_muncie.py): two 24-hour 1D/2D runs of ~65 s each on 4 cores, downstream peak flow 21,000 → 25,200 cfs (+20.0 %), downstream max stage 938.7 → 940.7 ft (+2.0 ft), 2D area 4,905 → 4,997 wet cells, max depth 20.3 → 20.4 ft.

<p align="center"> <img src="docs/figs/downstream_flow.png" alt="Downstream flow hydrograph, baseline vs +20% inflow" width="900" /> </p> <p align="center"> <img src="docs/figs/max_wse_profile.png" alt="Maximum water surface profile along the White River reach" width="900" /> </p> <p align="center"> <img src="docs/figs/max_depth_map.png" alt="Maximum depth map of the 2D Interior Area" width="600" /> </p>

Full evidence (commands, tool returns, and the honest scope boundary) is in docs/verification.md.

Scope (v0.1) and honest boundaries

• Operates on existing HEC-RAS projects: inspect, edit boundaries / plan settings, run, read, compare, plot, audit.
• Building a new model (terrain, 2D mesh, cross sections, infiltration layers, structures) still needs RAS Mapper / the GUI.
• Runs need Windows + HEC-RAS. HEC-RAS 7.0.1 ships Linux compute engines (RasUnsteady, run via WSL) but they need Windows-side preprocessing; they are not wired into ras_run yet.
• HEC-RAS may show its Terms and Conditions for Use form on headless launches; ras_run accepts it for you (accept_tcu, default true — read the terms at hec.usace.army.mil/software/hec-ras) and kills runs after timeout_s.
• Gridded (DSS) precipitation and steady-flow (.f##) profiles are read but not edited.

Development

pip install -e ".[dev]"
pytest                          # ~3 s, no HEC-RAS needed
python scripts/smoke_test.py    # tool discovery + real stdio MCP round-trip
python scripts/call_tool.py --list
python scripts/call_tool.py ras_results_summary "{\"hdf\": \"C:/models/Muncie/Muncie.p03.hdf\"}"

The tests pin the .u## boundary-table writer (fixed-width, touching fields, count line, CRLF), the QA classifier, the comparison metrics, the manifest, tool discovery and the server's failure shape. Add a tool or skill by dropping a file under hecras_mcp/tools/ or skills/ (auto-discovered), and ship a test with it.

License

MIT © 2026 Zhonghao Zhang, University of Victoria. Built on ras-commander (MIT), h5py, pandas, matplotlib and the Model Context Protocol. HEC-RAS is developed and distributed free of charge by the U.S. Army Corps of Engineers Hydrologic Engineering Center; it is not open source and is not redistributed here.