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.

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.

Related MCP server: COMSOL MCP Server

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)

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.

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.