gagelink

GageLink

基準座標系を付随させた、AI エージェント向けの水文データです。

USGS、NOAA、Hub'Eau、英国環境庁、SWOTから、河川水位、河川流量、洪水予測、流域、衛星による水位を取得できます。各値には、単位、測定基準となる標高基準面、タイムゾーン、記録が暫定値か承認済みかが付随します。

mcp-name: io.github.Adeniyikayodee/gagelink

プレアルファ版です。APIは変更される場合があります。

インストール

ライブラリをインストールするには、pip install gagelink を実行します。MCP クライアントからは、何もインストールせずに利用できます。

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

または、サーバーとその依存関係を1つのファイルにまとめた .mcpb バンドルを開きます。

アカウントは不要です。無料キーを使うと、1時間あたりのリクエスト上限が50件から1,000件に増えます。GAGELINK_API_KEY に設定してください。

どのような質問に答えられますか？

• 川の水位はどのくらいで、洪水位と比べるとどうですか？
• 水面と測量済み堤防天端の間に、どれだけ余裕高がありますか？
• 現在の流量はどのくらいで、記録上のピーク流量に対してどの程度ですか？
• 今後数日間の予測はどうなっていて、洪水区分を超えますか？
• 河川網に沿って、上流または下流には何がありますか？
• この地点に流れ込む流域の面積はどのくらいですか？
• ある期間に観測所が記録した値は何ですか？また、その記録は改訂されていますか？
• 水位観測所のない川の水面標高はどのくらいですか？
• 観測値は暫定値ですか、それとも承認済みですか？また、どのくらい前の値ですか？

基準座標系が重要な理由

ポトマック川のリトルフォールズでは、河川水位 3.02 ft は観測所固有のゼロ点から上向きに測定されます。測量済みの堤防天端の高さ 41 ft は、全国標高基準面から上向きに測定されます。どちらもフィート単位の長さであるため、一方から他方を差し引くと余裕高らしい数値が得られ、単位ライブラリもその計算を通してしまいます。

この観測所のゼロ点はNAVD88より37.04 ft高い位置にあるため、この基準面での水位は40.06 ft、余裕高は0.94 ftです。オフセットを無視して差し引くと37.98 ftとなり、余裕高を40倍も過大評価して堤防が安全だと判断することになります。

GageLinkはこの引き算を拒否し、計算が正しく定義されるためのオフセットを返します。ジオイドを基準とする衛星標高や、実測値に基づかない場合があるモデル流量についても同様です。

python demo/freeboard.py を実行すると、記録済みの応答を使って、例全体をオフラインで確認できます。

基準面の変換

ほとんどの観測所ではオフセットを利用できるため、変換を拒否する代わりに答えを返せます。describe_location に on_datum を渡すと、その観測所のオフセットが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

見落としやすい点が2つあります。

オフセット自体にも精度があります。 4つの州から抽出した7,361か所のUSGS河川観測所のうち、標高基準面に対する高度を公開しているのは3,397か所です。そのうち72%は、精度が1フィート以内であることが分かっていません。公開されている精度で最も多いのは15 ftで、3分の1は地形図から補間されており、およそ20分の1は0.01 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 分間隔の記録が 1 年分あると 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 を返します。仕様では補完の対象をプロンプト引数とリソーステンプレート変数に限定しているため、この 2 つの語彙はテンプレートとしてもツールスキーマ内でも公開されています。

対応範囲

地域	サービス	利用可能な機能
米国	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 と、その前の 3 つのハンドシェイク用リビジョン（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 を使うと、1 時間あたりの利用枠が公開されてしまいます。

再現可能な回答

取得のたびに、URL、取得時刻、レスポンス本文のハッシュが記録されます。export_manifest はその記録を返し、セッションは後から 3 つのモードで再生できます。

• offline はアーカイブ済みの本文を使用します
• strict はライブサービスが同一のデータを返すことを確認します
• revision_aware は、公式記録のリビジョンによる回答の変化と、コードの変更による変化を区別します

3 つ目のモードがあるのは、水文学データが改訂されるためです。暫定的な測定値は数か月後に承認または修正されることがよくあるため、コードとは無関係な理由で回答が変わることがあります。revision_aware は、この 2 つの原因を区別します。

値は台帳とも照合されるため、回答を監査できます。

[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 の生レスポンス、メタデータを除いた構造化結果、ツールキット全体という 3 つの条件で実行します。

初回の結果、gpt-oss-120b、8 回の反復、216 回の実行：

条件	正答数
API の生レスポンス	61/72
構造化、メタデータなし	63/72
GageLink	70/72

9 つのタスクのうち 6 つは天井効果に達しており、これはテストセットについての知見です。差が出るタスクでは、その原因が明確です。長期記録に関する 2 つのタスクでは、生の JSON を通じて 49,864 トークンと 42,006 トークンのプロンプトが送られましたが、ツールキットでは 5,462 トークンと 2,384 トークンでした。単位が不明瞭なタスクでは、参照枠を取り除くと 8 回中 7 回が記録済みの誤答に陥り、予報サービスが公表した 2.95 kcfs ではなく、USGS の流量 3010 ft³/s と回答しました。

モデルは 1 つ、テストセットも小規模であるため、これらの数値はインターフェースに関する初期の兆候です。一般的な主張をするには、より多くのモデルとタスクが必要です。

開発

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

Python 3.10 以降が必要です。このスイートは記録済みのフィクスチャから回答するため、ネットワークアクセスは不要です。mypy src/gagelink はエラーがない状態であることが期待されます。

ライセンス

MIT