Hydrata - ANUGA Flood Simulation

hydrata-mcp-server

适用于 Hydrata Cloud 的 MCP 服务——通过 Model Context Protocol，利用地形和输入图层构建 ANUGA 洪水模型、运行模拟、跟踪进度并获取结果。

连接和身份验证

端点： https://hydrata.com/mcp/ — 传输方式： Streamable HTTP。

每次工具调用都需要调用方自己的 hydrata.com 凭据：Agent 密钥（Authorization: Bearer hk_…）。这是一个有名称、可撤销的授权，共有三个级别（read < draft < launch），由账户所有者在网站的 Agent keys 页面（/agents/）创建；所有者可以逐个或一次性全部撤销。服务本身不持有任何身份信息，也不会解析密钥：它会将 Authorization 标头原样转发给 Hydrata REST API，由 Django 验证。因此，结果会根据真实用户的项目权限和密钥级别进行限制，审计记录也会标明用户。对于每个 JSON-RPC 请求——包括 initialize、tools/list 和 ping，以及 tools/call——如果未携带且只携带一个受支持的凭据（Agent 密钥，或在配置了一键连接流程时使用其访问令牌），服务器会在请求到达 MCP SDK 之前返回 401、JSON-RPC 错误 -32001 和 WWW-Authenticate: Bearer realm="hydrata.com"（配置了连接流程时还会附带 resource_metadata="…"）。不接受缺少 Authorization 标头、HTTP Basic 或任何其他 Bearer 令牌，例如 GeoNode OAuth 令牌。只有 Agent 密钥会受密钥级别、账户暂停开关、支出限额和 Agent 活动日志的约束。首次请求返回的 401 会告知 claude.ai 等支持 OAuth 的客户端该服务需要登录（TASK-3987），因此工具目录不会匿名提供。服务只检查凭据的格式（不持有密钥存储）；每次工具调用时，都会由 Django 验证密钥或令牌本身。非 JSON-RPC 请求正文会交由 SDK 返回其自身的错误，GET 请求则会收到 405。

该服务尚未向外部账户开放：目前没有自助方式可将你自己的 hydrata.com 登录账户连接到该服务，本 README 也有意不提供客户端凭据配置方法。如果你想使用该服务，请通过 hydrata.com 联系我们。

工具

0.2.0 版提供二十八个工具：十一个用于读取项目、输入和情景并启动运行；八个用于利用 Agent 已上传的地形和输入图层构建模型；六个用于记录洪水观测；另有三个用于将历史运行结果与这些观测进行比较（Compare with observations）。每个工具都带有 MCP 注释（title；十一个读取工具带有 readOnlyHint；只有 cancel_run 和 delete_observation 带有 destructiveHint）。

工具	描述
list_projects	列出 ANUGA 模拟项目（分页）
get_project	获取一个项目的信息——名称、投影、可见性、你的角色、base_map，以及打开地图的链接 ui_url
get_scenario	获取场景的精简状态——computed_status、其输入项（地形、边界、摩擦、入流、降雨、建筑、网格区域、涵洞、分辨率、时长）、网格三角形数量估算及细分、价格（compute_cost_estimate、vcpu_hours_estimate），以及最近一次运行的 ID／状态／错误——绝不返回原始详情
start_simulation	启动洪水模拟（本地／EC2／Batch 后端）；返回的运行记录会省略预签名下载链接；交接链接会打开该运行。如果运行费用超出 Agent 密钥的月度支出限额（默认 $0），或 Hydrata 无法估价，则不会启动：该工具会立即转发 Hydrata 的 CONSENT_REQUIRED，并提供用户在浏览器中打开的 consent_url（如果 consent_timeout_seconds > 0，还会轮询运行状态以检测用户是否已点击）
get_run_status	轻量级状态轮询（<50ms）；phase 永不为空（计算中的运行尚无进度时为 preparing_inputs）
get_run	获取包含时间信息、日志和结果图层的完整运行详情；预签名 s3_*_url 下载链接会被省略
cancel_run	取消正在运行的模拟；交接链接会打开场景
retry_run	重试失败的模拟（将场景重建为一次新运行）；交接链接会打开场景
list_runs	列出项目中的运行（可按状态筛选）；每一行中的预签名 s3_*_url 下载链接都会被省略
list_inputs	按类型列出项目的所有输入行（边界、摩擦、入流、降雨、建筑、网格区域、涵洞）——行 ID、标题、数据集、WFS typename，以及是否包含要素——因此 Agent 无需探查文件
list_time_series	列出项目的时间序列——ID、名称、类型、单位、行数，以及首末时间戳；绝不返回数据行
create_project	使用名称和 EPSG 投影创建 ANUGA 项目；返回其 base_map 和地图的 ui_url
presign_terrain_upload	返回预签名 URL 和密钥，让 Agent 自行 PUT 地形 GeoTIFF（文件字节不会经由 MCP 传输）
finalize_terrain_upload	注册已上传的地形；导入流程会为项目创建六个默认边界／摩擦／入流／降雨／建筑／网格区域行（不创建涵洞行：attach_input_layer 会按需创建“Culvert 01”）
get_terrain	轮询地形直至就绪（有上限；timed_out 表示需要再次调用）；phase 永不为空；摘要 = WGS84 包围框、高程最小值／最大值、无数据值比例、原生 CRS；链接会框选 DEM
create_time_series	根据 {"rowData": [...]} 创建时间序列（雨量站、流量过程线或潮汐／水位——series_type 和 units 是顶层字段）；降雨多边形按序列名称绑定到对应雨量站；摘要 = 行数 + 首末时间戳；链接会打开 Hydrology 面板
attach_input_layer	将 Agent 已上传的 GeoJSON 数据集附加为项目的边界／摩擦／入流／降雨／建筑／网格区域或涵洞图层（类型 structure = 已弃用的 building 别名）；涵洞属性会映射到涵洞字段并填入默认值，culvert_problems 会列出构建仍会拒绝的原因；不接受 breakline；摘要 = 要素数量（WFS 查询结果）+ WGS84 包围框 + 地图现在是否显示该图层；链接会打开 Inputs 并框选该图层
create_scenario	创建草稿场景，并返回网格三角形数量估算和价格（resolution——场景和网格区域的分辨率——单位为米）；链接会打开该场景
build_scenario	构建场景包；先显示估算，三角形数量超过 100,000 时需要 confirm=true；轮询 computed_status 直至状态变为 built；不会重复提交正在构建或已构建的任务（使用 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	列出项目的洪水观测图层，或某个图层中的观测数据——fid、子类型、水位／水深、sigma、边界、UTC 观测时间范围、基准状态（unknown = 未评分）、photo_count 和 problems
add_observations	添加洪水痕迹、水位时间记录、测站记录和无水点（每次最多 200 条；原生坐标使用 srid，无时区的时间使用 entry_timezone）；API 会逐条验证，返回被拒绝的行及错误字段，其余行则会成功写入
update_observation	编辑一条观测数据（对给定字段执行 PATCH；根据已存储的观测数据进行验证）
delete_observation	删除一条观测数据及其照片
add_observation_photo_link	将照片作为仅供参考的链接附加到观测数据（仅存储，不会获取）；若传入照片文件则会被拒绝并提供 UI 路径——工程师需在地图中该观测数据表单的照片栏上传文件
get_observation_comparison	查看历史运行与项目洪水观测数据的对比：headline（在给定容差下的数值，默认 0.3 m；无通过或失败判定）、statistics（n、within、bias、RMSE、weighted RMSE、MAE、max）、测站记录的峰值／时间／NSE、基准检查，以及每条观测数据对应的一行（残差 = 模拟值 - 观测值；包含未评分和已排除的行）。layer_id + fid 可将结果限定为一条观测数据，并显示其排除历史；除非设置 include_series，否则会省略测站记录的模拟序列。设计运行或未标记的运行会返回 has_comparison: false，而非错误
set_observation_exclusion	使用工程师提供的理由，将一条观测数据从运行对比中排除（必填：工具会拒绝空理由，Agent 必须询问），或重新纳入该观测数据；记录用户和理由；返回 headline_after
set_comparison_tolerance	保存项目默认对比容差（单位为米，大于 0 且不超过 5；Editor+）。除非传入 tolerance（此时不会保存任何内容），否则 get_observation_comparison 会使用该值

交接：工程师在地图中确认

每个会更改内容的工具（create_project、finalize_terrain_upload、get_terrain、create_time_series、attach_input_layer、create_scenario、build_scenario、start_simulation、cancel_run、retry_run、五个洪水观测写入工具，以及三个对比工具）也会返回：

• ui_url — https://<site>/catalogue/#/map/<base_map>?panel=…&layer=…&scenario=…&run=…，打开项目地图并显示发生更改的内容（聚焦已附加图层的 Inputs 面板、水文面板、情景或运行）；
• summary — 供工程师核对的数据（要素数量和 bbox、高程范围、行数和时间跨度、三角形估算数量和价格）；
• say_to_user — Agent 应转达给用户的句子。

服务端指示 Agent 在每个图层添加完成后将链接交给用户，并等待用户确认后再调用 start_simulation。用户可以在地图中修复的拒绝原因（没有边界、没有 External 边界边）也会附带链接。服务端转发的每个请求都会携带 X-Hydrata-Client: mcp/<version> 和 X-Hydrata-Session: <uuid>——仅供参考（由客户端声明），绝不用于确认操作作者。

没有工具接受内联文件内容。Agent 自行传输字节——将地形 GeoTIFF 上传至预签名 URL，将 GeoJSON 图层上传至 REST API 上传端点——然后把生成的键或上传 id 交给服务端。

没有读取工具会转发预签名 S3 URL。运行结果链接是有效期为 6 小时的访问凭证，其中包含临时 AWS 凭证；服务端转发调用者自己的凭证，而不是自行持有凭证。因此，若工具回显此类链接，就会让 Agent 对话记录的价值超出调用者的请求范围。每个读取工具（以及 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

欢迎贡献——请参阅 问题。

许可证

MIT