gagelink

GageLink

为 AI Agent 提供水文数据，并附带参考基准。

来自 USGS、NOAA、Hub'Eau、UK Environment Agency 和 SWOT 的河流水位、流量、洪水预报、流域和卫星水位。每个数值都附带单位、测量所依据的基准、时区，以及记录是暂定还是已核准。

mcp-name: io.github.Adeniyikayodee/gagelink

预 Alpha 阶段。API 可能会更改。

安装

pip install gagelink 安装库。使用 MCP 客户端且无需安装任何内容时：

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

或者打开 .mcpb bundle，其中将服务及其依赖项打包在一个文件中。

无需账户。免费密钥可将额度从每小时 50 次请求提高到 1,000 次；将其设置为 GAGELINK_API_KEY。

它能回答什么？

• 河流水位有多高？与洪水水位相比如何？
• 水面与经过测量的堤坝顶之间有多少超高？
• 当前流量是多少？占历史峰值流量的比例是多少？
• 未来几天的预报是什么？是否会达到某个洪水级别？
• 沿河流网络向上游或下游有什么？
• 流向此处的流域有多大？
• 某个站点在一段日期范围内记录了什么？该记录是否经过修订？
• 没有水位计的河流，其水面高程是多少？
• 读数是暂定还是已核准？记录有多旧？

为什么参考基准很重要

在波托马克河上的 Little Falls，河流水位 3.02 ft 是从水位计自身的零点向上测量的。经过测量的堤坝顶高程 41 ft 是从国家基准向上测量的。两者单位都是英尺，因此相减会得到一个看似代表超高的数值，单位库也会接受它。

该站的水位计零点位于 NAVD88 基准面以上 37.04 ft，因此水位在该基准面上的高程为 40.06 ft，超高为 0.94 ft。不加偏移量直接相减会得出 37.98 ft，使安全余量被高估 40 倍，进而误判堤坝安全。

GageLink 会拒绝这种相减，并返回使其定义明确的偏移量。卫星高程也一样，它们以大地水准面为基准；模型流量也一样，可能没有实际测量作为依据。

运行 python demo/freeboard.py，即可离线使用记录的响应完整运行此示例。

转换基准

大多数站点都提供偏移量，因此被拒绝的计算可以转化为答案。将 on_datum 传给 describe_location，站点偏移量便会通过 NOAA 的 VDatum 进行转换，同时返回转换的不确定度：

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

这会揭示两件容易被忽视的事。

偏移量本身也有精度。 在四个州抽样的 7,361 个 USGS 河流站点中，有 3,397 个公布了水位计基准面的高程。其中 72% 的精度不优于 1 ft。最常见的公布精度是 15 ft；三分之一的高程是从地形图上插值得出的；约二十分之一的高程经过水准测量，精确到百分之一英尺。无论水位读数精确到什么程度，超高的精度都受这一数值限制，因此 describe_location 会同时返回该数值及确定它所采用的方法。

大多数站点采用较旧的基准。 这些高程中有 58% 是以 NGVD29 为基准公布的，而现代测量或激光雷达产品则使用 NAVD88。在美国本土各州，二者的差值可达数英尺。

对于相对于潮汐的水位问题，on_datum 也支持潮汐基准（MLLW、MLW、LMSL、MTL、DTL、MHW、MHHW）；get_satellite_passes 则使用它，将 SWOT 高程从其测量所依据的 EGM2008 大地水准面转换出去。两者的覆盖范围均为美国本土。超出该范围时，转换会被拒绝，并说明原因。

工具

工具	功能
find_locations	查找监测站
describe_location	站点元数据和参考坐标系
get_latest	获取每个参数的最新读数
get_series	获取指定日期范围内的时间序列
slice_series	处理已检索序列中的一部分
get_peaks	年度峰值流量
get_forecast	预测和洪水阈值
get_model_forecast	获取无测站河段的模拟流量
get_satellite_passes	获取卫星轨道测得的水位
navigate_network	查找上游和下游站点
get_basin	汇水流域
lookup_parameter	查询参数代码
export_manifest	导出所有用于回答问题的信息

这 13 个工具均为只读工具，并已明确标注，因此客户端只需征求一次许可。

结果会按照各工具的输出架构以结构化数据形式返回，因此客户端可以直接读取单位、基准面或等级字段。

序列会以包含摘要的句柄形式返回。一年的 15 分钟间隔记录有 35,000 个值，但任何答案都不需要把它们放进上下文窗口。

提示词

工具列表说明了可以调用哪些工具，却没有说明应先调用哪个；上文的基准面规则是一套操作顺序，而不是一次调用。有 4 个提示词说明了模型自行组合这些步骤时容易出错的地方。

提示词	说明内容
freeboard_check	获取偏移量，再计算差值，最后限定答案范围
flood_status	对照洪水等级评估当前及预测期间的水位
find_a_station	相关机构实际使用的筛选条件
reproducible_answer	给出答案，然后导出清单

资源

这些表格不会因调用而改变，无需消耗每小时配额中的请求即可读取。

资源	内容
gagelink://instructions	判断答案是否正确的 4 条规则
gagelink://parameters	常见参数代码及其测量内容
gagelink://datums	此处提及的所有基准面，以及哪些可以相互转换
gagelink://coverage	各工具适用的国家，以及各项服务未涵盖的内容
gagelink://manifest	本次对话的记录，无需调用工具

gagelink://parameter/{code} 和 gagelink://datum/{name} 是模板，其变量支持补全：服务端会针对它们以及提示词参数返回 completion/complete，并提供一组封闭的可选值。规范将补全范围限定为提示词参数和资源模板变量，因此这两组词汇除了在工具架构中提供，也会作为模板公开。

覆盖范围

区域	服务	可用功能
美国	USGS、NOAA NWPS、NOAA National Water Model、NLDI、VDatum	全部 13 个工具
法国	Hub'Eau	搜索、元数据、最新读数、时间序列
英国	Environment Agency	搜索、元数据、最新读数
全球	SWOT	卫星水面高程

ERA5、GRACE、CAMELS 和 HydroBASINS 可供库调用者使用。

各项服务发布的数据量各不相同，工具会说明具体情况。Hub'Eau 未标注任何数值的单位，因此此处根据记录表，将水位标为毫米、流量标为升/秒。Environment Agency 不会在实时数据中发布记录等级，因此读数的新旧程度是判断英国读数是否过时的唯一依据。

要查找英国站点，请在 find_locations 中使用 country=GB。该机构会按完整名称及其自身拼写匹配河流和城镇，因此 River Thames 会返回站点，而 Thames 不会返回任何结果。当不清楚该机构采用的拼写时，应使用与站点名称匹配的自由文本筛选。

协议支持

GageLink 支持 MCP 修订版 2026-07-28 及此前三个握手修订版（2025-06-18、2025-03-26、2024-11-05）。它声明了工具、提示词、资源和补全功能，并将它们的 listChanged 全部声明为 false：所有列表都在导入时构建，因此订阅了列表的客户端只能等待一条永远不会到来的通知。

2026 修订版移除了 initialize 握手。每个请求都携带自己的版本和能力，因此客户端会在第一条消息中调用工具，并通过 server/discover 了解服务端的功能。使用早期修订版的客户端仍会开启会话并保持会话。

由于连接不再代表一次对话，想要记录自己台账的客户端应在 _meta 中指定一个名称：

{"_meta": {"io.github.adeniyikayodee.gagelink/conversation": "whatever-you-call-it"}}

每个名称都有各自的清单、数量和检查项。不指定名称的客户端会共享默认台账。

对于无法启动本地进程的客户端：

gagelink-mcp --http          # http://127.0.0.1:8765/mcp

这会绑定到环回地址并检查 Origin 标头。它没有身份验证，因此在可访问的网络接口上使用 --host 会暴露你的每小时限额。

可复现的答案

每次检索都会记录其 URL、执行时间以及响应正文的哈希值。export_manifest 会返回这条记录，会话也可以稍后通过三种模式重放：

• offline 使用已归档的正文
• strict 检查实时服务返回的数据是否完全相同
• revision_aware 区分因官方记录修订而变化的答案与因代码变化而变化的答案

设有第三种模式，是因为水文数据会修订。临时测量值通常会在几个月后获批或更正，因此答案可能会因与代码无关的原因发生变化。revision_aware 会区分这两种原因。

系统也会根据台账检查数值，因此答案可以接受审计：

[ok]         3.02 ft        from get_latest.00065
[ok]         2960 ft3/s     from get_latest.00060
[UNSOURCED]  116000 ft3/s   no tool output produced this value

基准测试

waterbench 用于衡量该接口能否改变模型答对问题的情况。它在三种条件下运行相同的 9 项任务：原始 API 响应、移除元数据后的结构化结果，以及完整工具包。

首轮结果：gpt-oss-120b，8 次重复，共 216 次运行：

条件	正确数
原始 API	61/72
结构化结果，无元数据	63/72
GageLink	70/72

9 项任务中有 6 项的正确率达到上限，这是对测试集本身的一项发现。在能拉开差距的任务中，原因清晰可见。两项长记录任务通过原始 JSON 发送了 49,864 和 42,006 个提示词 token，而通过工具包只发送了 5,462 和 2,384 个。在单位不明确的任务中，移除参考框架后，8 次运行中有 7 次落入记录在案的陷阱：回答采用 USGS 的流量值 3010 ft³/s，而不是预测服务发布的 2.95 kcfs。

这些数字来自一个模型和一个小型测试集，只能作为接口表现的初步信号。要提出普遍性结论，还需要更多模型和更多任务。

开发

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

需要 Python 3.10 或更高版本。该套件根据录制的固定数据作答，无需网络访问。mypy src/gagelink 预期不会报错。

许可证

MIT