# hydrology-mcp-server

**Repository Path**: handaas/hydrology-mcp-server

## Basic Information

- **Project Name**: hydrology-mcp-server
- **Description**: HandaaS 水利水情监测预警 MCP Server — 江河/水库/重点站/省份统计/降雨TOP10/水情预警
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-09
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 水利水情监测预警

[该 MCP 服务提供河流水情、水库水情、重点监测站、分省监测统计、降雨量 TOP10 和水情预警查询能力，用于水情信息检索与辅助研判。](https://www.handaas.com/)

## 主要功能

- 🌊 河流水情监测记录查询
- 🏞️ 水库水情监测记录查询
- 📍 重点监测站降雨记录查询
- 🗺️ 分省监测站与异常等级统计
- 🌧️ 指定统计日期降雨量 TOP10 查询
- ⚠️ 洪水、干旱预警记录查询

## 工具速览

| Tool | 用途 | 关键参数 | 分页 |
| --- | --- | --- | --- |
| `hydrology_river_monitoring_list` | 查询江河水位与超警水位 | `province`、`basin`、`riverName`、`stationName`、日期范围 | `pageIndex` / `pageSize` |
| `hydrology_reservoir_monitoring_list` | 查询大型水库水位与日变幅 | `province`、`basin`、`riverName`、`stationName`、日期范围 | `pageIndex` / `pageSize` |
| `hydrology_key_station_list` | 查询重点站日降雨量 | `province`、`basin`、`riverName`、`stationName`、日期范围 | `pageIndex` / `pageSize` |
| `hydrology_province_statistics` | 查询分省站点、预警与异常等级统计 | `province` | 不分页 |
| `hydrology_rainfall_top10` | 查询指定日期或上游最新日期的降雨量 TOP10 | `statDate` | 不分页 |
| `hydrology_warning_list` | 查询洪水、干旱预警 | `warningLevel`、`warningType`、日期范围 | `pageIndex` / `pageSize` |

四个分页 Tool 只接受 `pageIndex`，不要传 `page`；`pageIndex` 默认 1、最小 1，`pageSize` 默认且最大为 10。

## 环境要求

- Python 3.10+
- 依赖包：python-dotenv、requests、mcp

## 本地快速启动

### 1. 克隆项目

GitHub（公开仓库）：

```bash
git clone https://github.com/handaas/hydrology-mcp-server.git
cd hydrology-mcp-server
```

也可以从 Gitee 克隆私有镜像；执行前需要获得仓库访问授权：

```bash
git clone https://gitee.com/handaas/hydrology-mcp-server.git
cd hydrology-mcp-server
```

以上地址是源码仓库，不是可直接连接的托管 MCP 服务地址。

### 2. 创建虚拟环境并安装依赖

```bash
python -m venv mcp_env
source mcp_env/bin/activate
pip install -r requirements.txt
```

### 3. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env`：

```env
INTEGRATOR_ID=your_integrator_id
SECRET_ID=your_secret_id
SECRET_KEY=your_secret_key
HANDAAS_REQUEST_TIMEOUT=30
FASTMCP_PORT=8001
```

- `INTEGRATOR_ID`、`SECRET_ID`、`SECRET_KEY`：HandaaS 对接器认证信息。
- `HANDAAS_REQUEST_TIMEOUT`：可选，上游请求超时秒数，默认 30。
- `FASTMCP_PORT`：可选，本地 HTTP 监听端口，默认 8000；示例使用 8001，以减少与其他 MCP 服务的端口冲突。

认证信息需要登录 [HandaaS](https://www.handaas.com/) 注册并开通对应数据产品后获取。不要提交 `.env`、真实凭据或真实业务响应。

服务启动时只自动读取本服务目录下的 `.env`。同名进程环境变量优先于 `.env`：适合在 CI 或 MCP 客户端中直接注入凭据。`python server/mcp_server.py ...` 可只使用进程环境变量，不强制要求 `.env` 文件；`start_mcp_server.sh` 则会先检查本目录的 `mcp_env/` 和 `.env`，缺少任一项都会退出。

### 4. 启动服务

服务支持 `stdio`、`sse` 和 `streamable-http` 三种传输方式：

```bash
# STDIO
python server/mcp_server.py stdio

# Streamable HTTP
python server/mcp_server.py streamable-http

# SSE
python server/mcp_server.py sse
```

也可以使用启动脚本；省略参数时默认启动 `streamable-http`：

```bash
./start_mcp_server.sh
./start_mcp_server.sh stdio
./start_mcp_server.sh sse
```

使用示例端口 `8001` 时，Streamable HTTP MCP 地址为 `http://127.0.0.1:8001/mcp`。

- 直接运行 Python 且省略传输参数时，默认使用 `stdio`。
- 启动脚本省略传输参数时，默认使用 `streamable-http`。
- `sse` 和 `streamable-http` 固定监听 `127.0.0.1`；端口取 `FASTMCP_PORT`，未配置时为 `8000`。修改端口后应同步修改客户端 URL。

## Cursor / Cherry Studio 配置

### Streamable HTTP

先在项目目录启动 `python server/mcp_server.py streamable-http`，再添加：

```json
{
  "mcpServers": {
    "hydrology-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}
```

### STDIO

将 `{workdir}` 替换为 `hydrology-mcp-server` 的绝对路径：

```json
{
  "mcpServers": {
    "hydrology-mcp-server": {
      "command": "{workdir}/mcp_env/bin/python",
      "args": ["{workdir}/server/mcp_server.py", "stdio"],
      "env": {
        "INTEGRATOR_ID": "your_integrator_id",
        "SECRET_ID": "your_secret_id",
        "SECRET_KEY": "your_secret_key",
        "HANDAAS_REQUEST_TIMEOUT": "30"
      }
    }
  }
}
```

## 使用官方 Remote 服务

当前服务尚未发布官方 Remote 地址。请使用本地 `stdio`、`sse` 或 `streamable-http` 方式运行；官方 Remote 地址发布后再补充远程配置。

## 推荐调用方式

1. 按河流、水库或重点站类型选择对应 Tool，不要混用不同记录类型的业务字段。
2. 需要区域筛选时，可在 `province` 或 `basin` 中用英文逗号分隔多个值，例如 `湖北省,湖南省`。
3. 需要最新降雨排行时省略 `statDate`，由上游选择最新统计日期；不要将运行 MCP 的计算机日期当作统计日期。
4. 预警结果必须结合 `isHistory`、`releaseTime`、`endTime` 和查询时刻判断是历史预警还是当前预警，并检查时间新鲜度。

## 响应约定

六个 Tool 成功时统一返回 `total/resultList`。以下内容是**合成结构示例**，不包含真实业务数据：

```json
{
  "total": 1,
  "resultList": [
    {
      "province": "示例省",
      "stationName": "示例站",
      "recordTime": "2026-01-01 08:00:00",
      "waterLevel": 12.3,
      "warningWaterLevel": 0,
      "extraUpstreamField": "客户端应兼容的上游扩展字段"
    }
  ]
}
```

MCP 会保留 `resultList` 每条记录中的上游未知字段，不会为了匹配本文档而删除扩展字段；客户端应读取所需字段并容忍额外字段。`total=0` 且 `resultList=[]` 只表示当前筛选没有返回记录，不能解释为现实中没有水情风险。

参数校验、网关或上游错误返回包含 `error` 的对象，并可能附带 `parameter`、`code`、`statusCode` 或 `diagnostic`。例如，无效日期的合成错误结构为：

```json
{
  "error": "startTime 必须为有效日期，格式 YYYY-MM-DD",
  "parameter": "startTime"
}
```

通过 MCP 调用时，类型、分页数值边界等 Schema 校验也可能在工具执行前直接返回 `isError=true`。客户端应同时处理 MCP 协议错误和 `structuredContent` 中的业务 `error`，不能只检查 HTTP 状态码。

## 可用工具

### 1. hydrology_river_monitoring_list

**功能**：分页查询河流水情监测记录。

**数据产品 ID**：`6a76cb19dfa4a2f37b18fe70`

**参数**：

- `province`（可选）：省份；多个值使用英文逗号分隔。
- `basin`（可选）：流域；多个值使用英文逗号分隔。
- `riverName`（可选）：河流名称，单个模糊查询字符串。
- `stationName`（可选）：监测站名称，单个模糊查询字符串。
- `startTime`（可选）：记录起始日期，严格使用 `YYYY-MM-DD`。
- `endTime`（可选）：记录结束日期，严格使用 `YYYY-MM-DD`，不能早于 `startTime`。
- `pageIndex`（可选）：页码，默认 1，最小 1。实际接口参数名是 `pageIndex`，不要传 `page`。
- `pageSize`（可选）：每页条数，默认 10，范围 1～10。

**返回值**：

- `total`：符合条件的河流监测记录总数。
- `resultList`：当前页记录列表。
  - `basin`：流域。
  - `province`：省份。
  - `riverName`：河流名称。
  - `stationName`：监测站名称。
  - `recordTime`：记录时间。
  - `waterLevel`：水位，浮点数，单位米。
  - `warningWaterLevel`：超警水位，浮点数，单位米；这是超出警戒水位的数值，`0` 表示未超警，不是警戒水位阈值。

**说明**：源 PDF 标注上游 `pageSize` 最大 50；MCP 为控制单次返回量，采用更保守的 1～10 限制。

### 2. hydrology_reservoir_monitoring_list

**功能**：分页查询水库水情监测记录。

**数据产品 ID**：`6a76d075dfa4a2f37b18ff6c`

**参数**：

- `province`（可选）：省份；多个值使用英文逗号分隔。
- `basin`（可选）：流域；多个值使用英文逗号分隔。
- `riverName`（可选）：河流名称，单个模糊查询字符串。
- `stationName`（可选）：监测站名称，单个模糊查询字符串。
- `startTime`（可选）：记录起始日期，严格使用 `YYYY-MM-DD`。
- `endTime`（可选）：记录结束日期，严格使用 `YYYY-MM-DD`，不能早于 `startTime`。
- `pageIndex`（可选）：页码，默认 1，最小 1。实际接口参数名是 `pageIndex`，不要传 `page`。
- `pageSize`（可选）：每页条数，默认 10，范围 1～10。

**返回值**：

- `total`：符合条件的水库监测记录总数。
- `resultList`：当前页记录列表。
  - `basin`：流域。
  - `province`：省份。
  - `riverName`：河流名称。
  - `stationName`：监测站名称。
  - `recordTime`：记录时间。
  - `reservoirWaterLevel`：水库水位，浮点数，单位米。
  - `dailyRange`：日变幅，浮点数，单位米；保留上游正负号，不转换为绝对值。

**说明**：源 PDF 标注上游 `pageSize` 最大 50；MCP 为控制单次返回量，采用更保守的 1～10 限制。

### 3. hydrology_key_station_list

**功能**：分页查询重点监测站降雨记录。

**数据产品 ID**：`6a76d1318c8d379dd486a91d`

**参数**：

- `province`（可选）：省份；多个值使用英文逗号分隔。
- `basin`（可选）：流域；多个值使用英文逗号分隔。
- `riverName`（可选）：河流名称，单个模糊查询字符串。
- `stationName`（可选）：监测站名称，单个模糊查询字符串。
- `startTime`（可选）：记录起始日期，严格使用 `YYYY-MM-DD`。
- `endTime`（可选）：记录结束日期，严格使用 `YYYY-MM-DD`，不能早于 `startTime`。
- `pageIndex`（可选）：页码，默认 1，最小 1。实际接口参数名是 `pageIndex`，不要传 `page`。
- `pageSize`（可选）：每页条数，默认 10，范围 1～10。

**返回值**：

- `total`：符合条件的重点站记录总数。
- `resultList`：当前页记录列表。
  - `basin`：流域。
  - `province`：省份。
  - `riverName`：河流名称。
  - `stationName`：监测站名称。
  - `recordTime`：记录时间。
  - `dailyRainfall`：日降雨量，浮点数，单位毫米；`0` 表示无降雨。

**说明**：源 PDF 标注上游 `pageSize` 最大 50；MCP 为控制单次返回量，采用更保守的 1～10 限制。

### 4. hydrology_province_statistics

**功能**：查询分省监测站数量、当前预警数量及水情异常等级。

**数据产品 ID**：`6a76d2d68c8d379dd486a955`

**参数**：

- `province`（可选）：省份；多个值使用英文逗号分隔。省略时查询全部省份。

**返回值**：

- `total`：规范化后的省份统计记录数。
- `resultList`：省份统计列表。上游直接返回单个对象时，MCP 包装为 `total=1` 和 `resultList=[record]`；上游返回列表或分页结构时也统一为该格式。
  - `province`：省份。
  - `totalStations`：监测站总数，整数计数。
  - `riverMonitorStations`：河流水情监测站数量，整数计数。
  - `largeReservoirStations`：大型水库监测站数量，整数计数。
  - `keyStations`：重点监测站数量，整数计数。
  - `currentWarnings`：当前预警数量，整数计数。
  - `riverInflowAnomalyLevel`：河流来水异常等级，字符串；源文档未给出固定枚举。
  - `reservoirStorageAnomalyLevel`：水库蓄水异常等级，字符串；源文档未给出固定枚举。
  - `soilMoistureAnomalyLevel`：土壤墒情异常等级，字符串；源文档未给出固定枚举。

**说明**：源 PDF 同时描述“全部省份”查询和单个 `data` 对象，响应形态存在歧义。2026-09-08 真实网关实测 `data` 为列表，不筛选时返回34条；单省及多省筛选均通过。单对象、分页外层兼容分支有离线测试覆盖，未声称上游实际使用这些变体。

### 5. hydrology_rainfall_top10

**功能**：查询指定统计日期或上游最新统计日期的日降雨量 TOP10。

**数据产品 ID**：`6a76d3d18c8d379dd486a972`

**参数**：

- `statDate`（可选）：统计日期，严格使用 `YYYY-MM-DD`。省略时由上游选择最新统计日期，不等同于运行 MCP 的计算机当天日期。

**返回值**：

- `total`：当前 TOP 列表长度，不是全国监测站总数。
- `resultList`：上游 `data.topRainList`，保持原顺序；源文档说明按 `dailyRainfall` 从高到低排列。
  - `basin`：流域。
  - `province`：省份。
  - `riverName`：河流名称。
  - `stationName`：监测站名称。
  - `recordTime`：记录时间。
  - `dailyRainfall`：日降雨量，数值，单位毫米。

**说明**：该 Tool 没有分页参数。MCP 不重新排序或补齐记录，直接保留上游 TOP 列表顺序。

### 6. hydrology_warning_list

**功能**：分页查询洪水或干旱预警记录。

**数据产品 ID**：`6a76d4df8c8d379dd486a97e`

**参数**：

- `warningLevel`（可选）：预警等级；可使用 `red`、`orange`、`yellow`、`blue`，多个值使用英文逗号分隔。
- `warningType`（可选）：预警类型，单个值，仅支持 `flood` 或 `drought`。
- `startTime`（可选）：预警发布时间范围起始日期，严格使用 `YYYY-MM-DD`。
- `endTime`（可选）：预警发布时间范围结束日期，严格使用 `YYYY-MM-DD`，不能早于 `startTime`。
- `pageIndex`（可选）：页码，默认 1，最小 1。实际接口参数名是 `pageIndex`，不要传 `page`。
- `pageSize`（可选）：每页条数，默认 10，范围 1～10。

**返回值**：

- `total`：符合条件的预警记录总数。
- `resultList`：当前页预警记录列表。
  - `level`：预警等级。
  - `type`：预警类型。
  - `title`：预警标题。
  - `unitName`：发布单位名称。
  - `unitNameId`：发布单位 ID。
  - `releaseTime`：发布时间。
  - `endTime`：结束时间。
  - `affectedRange`：影响范围。
  - `detail`：预警详情。
  - `isHistory`：是否为历史预警，布尔值。

**说明**：源 PDF 标注上游 `pageSize` 最大 20；MCP 为控制单次返回量，采用更保守的 1～10 限制。不能只凭标题判断预警是否仍然有效，必须结合 `isHistory`、发布时间、结束时间和查询时刻判断。

## 使用注意事项

1. **分页边界**：四个分页 Tool 的 MCP `pageSize` 都限制为 1～10。三个监测接口的源 PDF 上游上限为 50，预警接口的源 PDF 上游上限为 20；MCP 的保守上限不代表上游原始上限。
2. **分页参数名**：四个分页 Tool 统一使用 `pageIndex`，不支持 `page`。源 PDF 中的 `page` 已被 2026-09-08 用户提供的实际接口更正取代；以本 README 和当前 MCP Schema 的 `pageIndex` 为准。
3. **日期格式**：所有日期参数必须严格使用 `YYYY-MM-DD`，日期范围起点不能晚于终点。
4. **多值格式**：`province`、`basin`、`warningLevel` 的多个值使用英文逗号分隔；`riverName`、`stationName` 和 `warningType` 只接受单个查询字符串。
5. **字段语义**：`warningWaterLevel` 表示超警水位，`0` 表示未超警；`dailyRange` 保留正负号；`dailyRainfall=0` 表示无降雨。
6. **统一响应**：六个 Tool 成功时均统一返回 `total/resultList`。分省统计会兼容上游单对象、列表与分页结构；降雨 TOP10 的 `total` 仅是当前排行列表长度。
7. **时间新鲜度**：监测记录与预警都可能是历史数据。使用结论前应核对 `recordTime`、`releaseTime`、`endTime` 和 `isHistory`。
8. **空结果边界**：空响应只表示当前筛选条件下没有返回记录，不能据此断言没有洪水、干旱、超警或其他现实风险。
9. **能力边界**：本服务是按请求查询的只读接口，不是风险预测引擎，不执行定时监测，不发布告警，也不提供应急决策保证。
10. **验证状态**：六个 Tool 已取得真实非空样本，2026-09-09 已完成六接口连接与返回数据复检。

## 使用提问示例

### hydrology_river_monitoring_list（河流水情监测）

1. 查询长江流域湖北省最近一周的河流水位记录
2. 搜索河流名称中包含“黄河”的监测站，并查看是否存在超警水位
3. 使用 `pageIndex=2` 查询指定日期范围内某监测站的第 2 页记录，每页 10 条

### hydrology_reservoir_monitoring_list（水库水情监测）

1. 查询广东省水库最近 7 天的水位和日变幅
2. 查看珠江流域各水库监测站的最新记录
3. 使用 `pageIndex=2` 继续查询站名中包含“三峡”的水库水情，并保留日变幅正负号

### hydrology_key_station_list（重点监测站）

1. 查询湖南省重点监测站最近一周的日降雨量
2. 查询长江流域重点站记录，再在已读取分页中筛选日降雨量大于 0 的记录
3. 搜索站名中包含“武汉”的重点监测站，并用 `pageIndex=2` 查询第 2 页

### hydrology_province_statistics（分省水情统计）

1. 查询全国各省监测站数量和当前预警数量
2. 对比湖北省和湖南省的河流监测站、水库监测站及重点站数量
3. 查看四川省河流来水、水库蓄水和土壤墒情异常等级

### hydrology_rainfall_top10（降雨量 TOP10）

1. 查询上游最新统计日期的日降雨量 TOP10
2. 查看 2026-09-08 日降雨量最高的 10 个监测站
3. 列出指定日期 TOP10 的省份、流域、站名和降雨量

### hydrology_warning_list（水情预警）

1. 查询最近 7 天的红色和橙色洪水预警
2. 查看指定日期范围内的干旱预警，并区分历史预警和当前预警
3. 使用 `pageIndex=2` 查询蓝色和黄色预警的发布单位、影响范围及结束时间

## 测试验证

离线测试不需要真实凭据：

```bash
python -m py_compile server/mcp_server.py
python -m unittest discover -s tests -p 'test_*.py' -v
```

真实接口 smoke 测试必须显式传入 `--live`，并通过实际 MCP STDIO 会话完成初始化、Tool 调用和响应检查：

```bash
python tests/live_api_smoke.py --live
```

如需读取其他环境文件，可显式指定：

```bash
python tests/live_api_smoke.py --live --env-file /path/to/hydrology.env
```

显式指定 `--env-file` 时，脚本只在内存中读取该凭据文件，不复制到服务目录；文件中的值会写入测试子进程环境，并优先于同名当前环境变量。不要提交凭据文件。

smoke 测试只应输出去标识化的记录数量、字段名和延迟，不输出业务记录内容、请求签名或凭据。空结果是合法接口结果，测试应标记“未取得非空样本”，不能据此判断现实中没有风险。

2026-09-08 本地验证：28 个离线测试通过，包含真实 STDIO、SSE、Streamable HTTP 传输与合成上游响应的端到端测试；Ruff、Python 语法检查、Shell 语法检查和 mypy 检查通过（mypy 跳过未安装的第三方 requests stubs）。四个分页工具的 Schema 与请求键均已验证为 `pageIndex`。

2026-09-08 真实验证：STDIO 基线6/6通过且都有非空样本。HTTP 功能检查覆盖六个工具、单省/多省及流域筛选、模糊搜索、日期区间、分页大小与翻页、空结果、降雨排序、预警类型/等级、非法日期及参数边界。

2026-09-09 复检中六个 Tool 再次全部取得非空结果。

仓库内的 `tests/live_api_smoke.py` 每次只执行六个 Tool 的基线调用，不等同于全面功能验证。详细测试报告保留在开发工作区，不作为独立源码仓库文件发布。

接口源文档日期为2026-09-08，页码参数以用户同日提供的实际接口更正为准。测试只验证所覆盖场景，不代表遍历了全部水情记录或确认现实中没有风险。

## 常见问题

### 没有配置认证信息

Tool 会返回 `INTEGRATOR_ID 未配置`、`SECRET_ID 未配置` 或 `SECRET_KEY 未配置`。在本服务目录配置 `.env`，或通过启动进程 / MCP 客户端的环境变量注入；不要把真实凭据写入 README 或提交到仓库。

### 已配置凭据，但上游仍返回业务错误

确认当前 HandaaS 对接器已经开通本 README 所列数据产品权限。服务会保留上游业务错误的 `code` 和消息；产品未授权时不要修改 Product ID、签名逻辑或伪造空结果。

### 参数被拒绝

分页参数必须使用 `pageIndex`，不能使用 `page`；`pageIndex>=1`，`pageSize` 范围为1～10。日期必须是有效的 `YYYY-MM-DD`，起始日期不能晚于结束日期；枚举和多值格式见对应 Tool 参数表。

### 返回 405 或 HTML 响应

检查 `console.handaas.com` 的 DNS、PAC / 透明代理规则，以及网络是否允许向网关发送 POST。该诊断只说明连接路径需要排查，不代表凭据或产品权限有效。

### 本地端口冲突

为 `sse` 或 `streamable-http` 设置一个未占用的 `FASTMCP_PORT`，然后同步修改客户端 URL。`stdio` 不需要 HTTP 监听端口。

## 接口资料依据

接口说明依据父工作区 `doc/水利水情监测预警/` 下列文档整理；这些 PDF 不复制到独立源码仓库，也不在此创建可能失效的相对链接：

- `江河监测数据明细_2026-09-08_16-44-02.pdf`
- `大型水库数据明细_2026-09-08_16-44-09.pdf`
- `重点站点数据明细_2026-09-08_16-44-13.pdf`
- `水利水情省份分布统计_2026-09-08_16-44-17.pdf`
- `重点站日降雨量TOP10_2026-09-08_16-44-26.pdf`
- `全国水情预警明细_2026-09-08_16-44-30.pdf`