Hydrata - ANUGA Flood Simulation

hydrata-mcp-server

Hydrata Cloud 向けの MCP サーバーです。Model Context Protocol を通じて、地形データと入力レイヤーから ANUGA の洪水モデルを構築し、シミュレーションを実行し、進捗を追跡して、結果を取得できます。

接続と認証

エンドポイント： https://hydrata.com/mcp/ — トランスポート： Streamable HTTP。

各ツール呼び出しには、呼び出し元自身の hydrata.com 認証情報が必要です。アカウント所有者がサイトのエージェントキーのページ（/agents/）で作成し、個別または一括で失効できる、3 段階（read < draft < launch）の名前付きで失効可能な許可である エージェントキー（Authorization: Bearer hk_…）です。サーバーは独自の ID を持たず、キーを解析することもありません。Authorization ヘッダーをそのまま Hydrata REST API に転送し、そこで Django が検証します。そのため、結果は実際のユーザーのプロジェクト権限とキーのレベルに応じて制限され、監査ログにはユーザー名が記録されます。受け入れ可能な認証情報（エージェントキー、またはワンクリック接続フローが設定されている場合はそのアクセストークン）を正確に 1 つ含まないすべての JSON-RPC リクエスト（initialize、tools/list、ping、tools/call を含む）は、MCP SDK に到達する前に、401、JSON-RPC エラー -32001、および WWW-Authenticate: Bearer realm="hydrata.com"（接続フローが設定されている場合は resource_metadata="…" も）を伴って応答されます。Authorization ヘッダーがない場合、HTTP Basic の場合、または GeoNode OAuth トークンなど、他の Bearer トークンの場合も同様です。キーのレベル、アカウントの一時停止スイッチ、利用上限、エージェントのアクティビティログが適用されるのは、エージェントキーのみです。最初のリクエストで 401 を返すことで、claude.ai などの OAuth 対応クライアントにサーバーへのサインインが必要であることを通知するため（TASK-3987）、ツールカタログが匿名で提供されることはありません。サーバーが確認するのは認証情報の形式だけです（キーの保存場所は持ちません）。Django がツール呼び出しのたびにキーまたはトークンを検証します。JSON-RPC ではないリクエストボディは SDK 独自のエラー処理に委ねられ、GET リクエストには 405 が返されます。

このサーバーは、まだ外部アカウントには公開されていません。現在、自分の hydrata.com ログインをサーバーに接続するセルフサービスの方法はなく、この README には意図的にクライアント側の認証情報設定手順を記載していません。利用をご希望の場合は、hydrata.com までお問い合わせください。

ツール

バージョン 0.2.0 では 28 個のツールを公開しています。プロジェクト、入力データ、シナリオを読み取り、実行を開始するツールが 11 個、エージェントがすでにアップロードした地形データと入力レイヤーからモデルを構築するツールが 8 個、洪水の観測記録を登録するツールが 6 個、過去の実行結果と観測記録を比較するツール（観測結果との比較）が 3 個です。すべてのツールに MCP アノテーション（title）が付いています。また、読み取り専用の 11 個のツールには readOnlyHint が、cancel_run と delete_observation のみに destructiveHint が付いています。

ツール	説明
list_projects	ANUGA シミュレーションプロジェクトの一覧を取得します（ページネーション対応）
get_project	1 つのプロジェクトの名前、投影法、公開設定、自分のロール、base_map に加え、マップを開くリンクである ui_url を取得します
get_scenario	シナリオの簡潔な状態を取得します。computed_status、入力（地形、境界、摩擦、流入、降雨、建物、メッシュ領域、カルバート、解像度、継続時間）、メッシュ三角形の推定数と内訳、料金（compute_cost_estimate、vcpu_hours_estimate）、最新の実行の ID／ステータス／エラーが含まれます。生の詳細は返しません
start_simulation	洪水シミュレーションを開始します（ローカル／EC2／Batch バックエンド）。返される実行レコードでは、署名付きダウンロードリンクが省略されます。引き渡しリンクを開くと実行が表示されます。エージェントキーの月間支出上限（既定値は $0）を超える実行、または Hydrata が料金を算出できない実行は開始されません。その場合、ツールは Hydrata の CONSENT_REQUIRED と、ユーザーがブラウザーで開く consent_url を直ちに返します（consent_timeout_seconds が 0 より大きい場合は、ユーザーがクリックするまで実行をポーリングします）
get_run_status	軽量なステータスポーリング（50 ミリ秒未満）です。phase が空になることはありません（計算中の実行で進捗がまだない場合は preparing_inputs）
get_run	実行の詳細情報を、タイミング、ログ、結果レイヤーとともに取得します。署名付き s3_*_url ダウンロードリンクは省略されます
cancel_run	実行中のシミュレーションをキャンセルします。引き渡しリンクを開くとシナリオが表示されます
retry_run	失敗したシミュレーションを再試行します（シナリオを新しい実行として再構築します）。引き渡しリンクを開くとシナリオが表示されます
list_runs	プロジェクト全体の実行一覧を取得します（ステータスで絞り込み可能）。各行の署名付き s3_*_url ダウンロードリンクは省略されます
list_inputs	プロジェクト内の種類ごと（境界、摩擦、流入、降雨、建物、メッシュ領域、カルバート）のすべての入力行を取得します。行 ID、タイトル、データセット、WFS typename、フィーチャーの有無が含まれるため、エージェントがファイルを調べる必要はありません
list_time_series	プロジェクトの時系列を取得します。ID、名前、種類、単位、行数、最初と最後のタイムスタンプが含まれます。データ行は返されません
create_project	名前と EPSG 投影法を指定して ANUGA プロジェクトを作成します。base_map と、そのマップの ui_url を返します
presign_terrain_upload	署名付き URL とキーを返します。エージェントが地形 GeoTIFF を自分で PUT するためのもので、ファイルのバイト列は MCP を経由しません
finalize_terrain_upload	アップロードした地形を登録します。インポート処理により、プロジェクトの既定の境界／摩擦／流入／降雨／建物／メッシュ領域の 6 行が作成されます（カルバート行は作成されません。attach_input_layer が必要に応じて「Culvert 01」を作成します）
get_terrain	地形が利用可能になるまでポーリングします（上限あり。timed_out の場合は再度呼び出してください）。phase が空になることはありません。概要には WGS84 の bbox、標高の最小値／最大値、nodata の割合、ネイティブ CRS が含まれます。リンクを開くと DEM が表示されます
create_time_series	{"rowData": [...]} から時系列（雨量計、水位ハイドログラフ、または潮位／水位）を作成します（series_type と units はトップレベルのフィールドです）。降雨ポリゴンは時系列名で雨量計に紐付けられます。概要には行数と最初／最後のタイムスタンプが含まれます。リンクを開くと Hydrology パネルが表示されます
attach_input_layer	エージェントがアップロード済みの GeoJSON データセットを、プロジェクトの境界／摩擦／流入／降雨／建物／メッシュ領域／カルバートレイヤーとして追加します（種類 structure は非推奨の building の別名です）。カルバート属性は既定値を補完してカルバートフィールドに割り当てられます。culvert_problems には、ビルドで引き続き拒否される項目が示されます。ブレークラインは拒否されます。概要にはフィーチャー数（WFS のヒット数）、WGS84 の bbox、マップにレイヤーが表示されるようになったかどうかが含まれます。リンクを開くと Inputs が表示され、レイヤーにフォーカスします
create_scenario	下書きシナリオを作成し、メッシュ三角形の推定数と料金を返します（resolution はシナリオとメッシュ領域の両方でメートル単位の長さです）。リンクを開くとシナリオが表示されます
build_scenario	シナリオパッケージをビルドします。最初に推定値を表示し、三角形が 100,000 個を超える場合は confirm=true が必要です。computed_status をポーリングしてビルド完了を確認します。進行中またはすでにビルド済みのビルドを再送信することはありません（強制するには rebuild=true を指定します）。サーバーによる 422 の拒否（MESH_TOO_LARGE、BOUNDARY_NO_EXTERNAL、MESH_REGION_UNITS_UNMARKED）をそのまま返します。境界が欠落している、空である、または外周がない場合は、ユーザーにマップでの描画または修正を案内します。概要には三角形の数と再計算された料金が含まれます
create_observation_layer	洪水観測レイヤーを作成します（プロジェクトレベルであり、シナリオ入力にはなりません）。鉛直基準面（terrain、AHD、EGM2008、ellipsoidal、または local と datum_offset_m）を指定します。マップレイヤーが利用可能になるまで待機します（ready、上限あり）。リンクを開くと Observations グループ内にフォーカスします
list_observations	プロジェクトの洪水観測レイヤー、または 1 つのレイヤーの観測データを取得します。fid、サブタイプ、水位／深さ、シグマ、境界、UTC の観測期間、基準面のステータス（unknown はスコア対象外）、photo_count、problems が含まれます
add_observations	洪水痕跡、水位の時刻記録、雨量計記録、乾燥地点を追加します（1 回の呼び出しにつき最大 200 件。ネイティブ座標には srid、タイムゾーン情報のない時刻には entry_timezone を指定します）。API は各項目を検証します。拒否された行には誤りのあるフィールドが示され、残りの行は登録されます
update_observation	1 つの観測データを編集します（指定したフィールドを PATCH し、保存済みの観測データに照らして検証します）
delete_observation	1 つの観測データとその写真を削除します
add_observation_photo_link	参照リンクのみとして観測データに写真を添付します（保存されますが、取得はされません）。写真 FILE は拒否され、その場合は UI の手順が示されます。技術者はマップ上の観測フォームにある写真ストリップからファイルをアップロードします
get_observation_comparison	過去の実行とプロジェクトの洪水観測データとの比較結果を取得します。headline（許容誤差に対する数値。既定値は 0.3 m で、合否判定はありません）、statistics（n、許容範囲内、バイアス、RMSE、加重 RMSE、MAE、最大値）、雨量計記録のピーク／タイミング／NSE、基準面チェック、および観測データごとの行が含まれます（残差 = モデル値 - 観測値。スコア対象外と除外された行も含まれます）。layer_id と fid を指定すると 1 つの観測データに絞り込まれ、その除外履歴も表示されます。include_series を指定しない限り、雨量計記録のモデル時系列は省略されます。設計用またはラベルなしの実行では、エラーではなく has_comparison: false が返されます
set_observation_exclusion	技術者が理由を指定して、1 つの観測データを実行の比較対象から除外するか、再び含めます（理由は必須です。空欄の場合はツールが拒否するため、エージェントは理由を尋ねる必要があります）。ユーザーと理由が記録され、headline_after が返されます
set_comparison_tolerance	プロジェクトの既定の比較許容誤差を保存します（メートル単位で、0 より大きく 5 以下。Editor+）。get_observation_comparison は tolerance が渡されない限り、この値を使用します。tolerance を渡しても保存されません

引き継ぎ：エンジニアがマップで確認して完了します

何かを変更する各ツール（create_project、finalize_terrain_upload、get_terrain、create_time_series、attach_input_layer、create_scenario、build_scenario、start_simulation、cancel_run、retry_run、5つの洪水観測データ書き込みツール、および3つの比較ツール）は、次の情報も返します。

• ui_url — https://<site>/catalogue/#/map/<base_map>?panel=…&layer=…&scenario=…&run=…。変更対象（添付レイヤーを表示するInputsパネル、Hydrologyパネル、シナリオ、実行）を開いた状態で、プロジェクトマップを表示します。
• summary — エンジニアが確認できる数値（フィーチャ数とbbox、標高範囲、行数と期間、三角形の推定数と価格）。
• say_to_user — エージェントがユーザーに伝えるべき文です。

サーバーの指示では、レイヤーが追加されるたびにエージェントがユーザーへリンクを渡し、start_simulation の前にユーザーの確認を待つよう定めています。境界がない、External境界エッジがないなど、ユーザーがマップ上で修正できる理由による拒否にもリンクが含まれます。サーバーが転送するすべてのリクエストには X-Hydrata-Client: mcp/<version> と X-Hydrata-Session: <uuid> が付与されます。これらは情報提供のみを目的とするものであり（クライアントが申告）、作成者の特定には使用されません。

ファイルの内容をインラインで受け取るツールはありません。エージェント自身がバイト列を転送します。地形GeoTIFFは事前署名URLへ、GeoJSONレイヤーはREST APIのアップロードエンドポイントへ転送し、生成されたキーまたはアップロードIDをサーバーに渡します。

読み取りツールが事前署名付きS3 URLを中継することはありません。実行結果へのリンクは、一時的なAWS認証情報を含む6時間有効のケイパビリティです。また、サーバーは認証情報を保持せず、呼び出し元自身の認証情報を転送します。そのため、このようなリンクをそのまま返すツールがあると、呼び出し元が求めた範囲を超えて、エージェントのトランスクリプトの価値を高めてしまいます。すべての読み取りツール（および start_simulation）では、キー名（s3_*_url）と値の形式（X-Amz-Signature／X-Amz-Security-Tokenを含むすべての文字列）の両方に基づき、再帰的にそれらを除外します。ログ行の残りの部分を保持するため、該当箇所のみが伏せられます。結果は引き続きgn_layer_* WMSエントリから表示できます。唯一の例外は presign_terrain_upload です。このツールの upload_url は、呼び出し元が明示的に要求したURLです。

典型的なワークフロー

既存のシナリオを実行します。

list_projects → get_scenario → start_simulation → poll get_run_status → get_run

モデルをインポートして実行します。

create_project → presign_terrain_upload → PUT the GeoTIFF → finalize_terrain_upload → get_terrain
→ create_time_series / attach_input_layer → create_scenario → build_scenario
→ start_simulation → poll get_run_status → get_run

Hydrataとは？

Hydrataは、地理空間水理モデリングプラットフォームです。ANUGAによる洪水シミュレーションをクラウドで実行できます。地形データをアップロードし、シナリオを設定して、マネージドコンピューティング（Celery、EC2、AWS Batch）でシミュレーションを実行し、インタラクティブマップで結果を可視化できます。

ANUGAは、Geoscience AustraliaとAustralian National Universityが開発したオープンソースの水理モデルです。非構造三角形メッシュ上で有限体積法を用いて、浅水波方程式を解きます。

開発

git clone https://github.com/Hydrata/hydrata-mcp-server.git
cd hydrata-mcp-server
pip install -e ".[dev]"
pytest -v

貢献を歓迎します。issueをご覧ください。

ライセンス

MIT