GageLink

Hydrology data for AI agents, with the reference frames kept attached.

River levels, streamflow, flood forecasts, drainage basins and satellite water levels from USGS, NOAA, Hub'Eau, the UK Environment Agency and SWOT. Every value arrives carrying its unit, the datum it was measured from, its timezone, and whether the record is provisional or approved.

mcp-name: io.github.Adeniyikayodee/gagelink

Pre-alpha. The API may change.

Install

pip install gagelink for the library. From an MCP client, with nothing installed:

{
  "mcpServers": {
    "gagelink": {
      "command": "uvx",
      "args": ["--from", "gagelink", "gagelink-mcp"]
    }
  }
}

Or open the .mcpb bundle, which carries the server and its dependencies in one file.

No account is needed. A free key raises the allowance from 50 requests an hour to 1,000; set it as GAGELINK_API_KEY.

What can it answer?

• How high is the river, and how does that compare with flood stage?
• How much freeboard is there between the water and a surveyed levee crest?
• What is the flow now, and what fraction of the record peak is that?
• What is forecast over the next few days, and does it cross a flood category?
• What lies upstream or downstream along the river network?
• How large is the basin draining to this point?
• What did a station record over a date range, and has that record been revised?
• What is the water surface elevation of a river with no gage on it?
• Is a reading provisional or approved, and how old is it?

Why the frames matter

At Little Falls on the Potomac, a river stage of 3.02 ft is measured upward from the gage's own zero. A surveyed levee crest of 41 ft is measured upward from a national datum. Both are lengths in feet, so subtracting one from the other produces a number that reads as freeboard, and a units library will pass it.

The gage zero at this station sits 37.04 ft above NAVD88, so the stage is 40.06 ft on that datum and the freeboard is 0.94 ft. Subtracting without the offset gives 37.98 ft, which overstates the margin by a factor of 40 in the direction of calling a levee safe.

GageLink refuses that subtraction and returns the offset that makes it well defined. The same applies to satellite elevations, which sit on a geoid, and to modelled flows, which may have no measurement behind them.

python demo/freeboard.py runs the whole example offline from recorded responses.

Converting a datum

The offset is available for most stations, so the refusal can become an answer. Pass on_datum to describe_location and the station's offset is converted through NOAA's VDatum, with the uncertainty of the conversion returned beside it:

altitude_of_gage_datum        4860 ft (NGVD29)      Boulder Creek at mouth, CO
altitude_accuracy             10 ft, interpolated from a topographic map
altitude_on_requested_datum   4863.061 ft (NAVD88)
conversion_uncertainty        0.17 ft
offset_uncertainty            10 ft

Two things this surfaces are easy to miss.

The offset has an accuracy of its own. Across 7,361 USGS stream stations sampled in four states, 3,397 publish an altitude for their gage datum. Of those, 72% are known no better than a foot. The commonest published accuracy is 15 ft, a third were interpolated from a topographic map, and about one in twenty is levelled to a hundredth. A freeboard is bounded by that figure whatever precision the stage was read to, so describe_location returns it alongside the method used to determine it.

Most stations are on the older datum. 58% of those altitudes are published on NGVD29 while a modern survey or lidar product is on NAVD88. Across the contiguous states the difference runs to feet.

on_datum also takes the tidal datums (MLLW, MLW, LMSL, MTL, DTL, MHW, MHHW) for questions about level relative to the tide, and `get_satellite_pa

... View full README on GitHub