🚀 USGS Water MCP
本项目提供了一个MCP服务器，可通过三个API全面访问美国地质调查局（USGS）的水资源数据，为水资源相关的研究、监测和决策提供有力支持。
🚀 快速开始
若你想使用一个简洁的Web界面来调用这些工具，请访问 https://aqua-node.onrender.com/landing 并协助我进行一些测试！
✨ 主要特性
此MCP服务器通过三个API提供对USGS水资源数据的全面访问：
- USGS Water Services API - 实时水资源测量数据（如水流、水位、温度等）
- Real-Time Flood Impacts API - 当前洪水状况和参考点
- OGC API - 监测位置元数据、机构代码和地质信息
服务器采用模块化设计，通过单个入口点统一不同的API处理程序。
📦 安装指南
通过pip安装
pip install -e .
手动安装
- 克隆此仓库
- 安装依赖项：
pip install httpx mcp
💻 使用示例
基础用法
以下是一个获取波托马克河水流数据的示例：
{
"name": "USGS:01646500:00060:00000",
"sourceInfo": {
"siteName": "POTOMAC RIVER NEAR WASHINGTON, DC",
"siteCode": [
{
"value": "01646500",
"network": "NWIS",
"agencyCode": "USGS"
}
]
},
"variable": {
"variableCode": [
{
"value": "00060",
"network": "NWIS",
"vocabulary": "NWIS:UnitValues",
"variableName": "Streamflow, ft³/s",
"variableDescription": "Discharge, cubic feet per second"
}
]
},
"values": [
{
"value": [
{
"value": "6420",
"qualifiers": ["A"],
"dateTime": "2023-10-01T12:00:00.000"
}
]
}
]
}
📚 详细文档
项目结构
usgs-water-mcp/
├── main.py # 统一入口点
├── water_data_api.py # USGS Water Services API工具
├── flood_impact_api.py # Real-Time Flood Impacts API工具
├── ogc_api.py # OGC API工具
├── current_water_levels.py # 旧的组合文件（已弃用）
├── Dockerfile # Docker配置
├── pyproject.toml # 项目依赖项
└── README.md # 本文件
可用工具
水资源数据工具
fetch_usgs_data
从USGS监测站获取即时水资源数据。 参数：
sites（必需）：以逗号分隔的站点编号（例如，"01646500" 或 "01646500,01647000"）parameter_codes（可选）：以逗号分隔的参数代码（例如，"00060,00065"）start_date（可选）：ISO格式的开始日期（YYYY-MM-DD 或 YYYY-MM-DDTHH:MM）end_date（可选）：ISO格式的结束日期period（可选）：周期代码（例如，"P7D" 表示7天）
常见参数代码：
00060：流量（水流）00065：水位00010：水温00300：溶解氧00400：pH值
使用示例：
获取华盛顿特区附近波托马克河的当前水流：
sites: "01646500"
parameter_codes: "00060"
实时洪水影响工具
get_flooding_reference_points
获取当前正在发生洪水的参考点（每30分钟更新一次）。
get_reference_points
获取参考点的分页列表。 参数：
page（可选）：页码（默认值：1）limit（可选）：每页的结果数量（默认值：100）
get_reference_point_by_id
通过ID获取特定的参考点。 参数：
reference_point_id（必需）：参考点ID
get_reference_points_by_state
获取特定州的参考点。 参数：
state_id（必需）：州ID（例如，"CA"，"TX"）
get_reference_point_by_nwis_id
通过USGS水位计ID获取参考点。 参数：
nwis_id（必需）：USGS国家水资源信息系统站点ID
get_reference_points_by_nws_id
通过国家气象局ID获取参考点。 参数：
nws_id（必需）：国家气象局位置ID
get_inactive_reference_points
获取非活动参考点。
get_states
获取州列表。
get_state_by_id
获取特定州的信息。 参数：
state_id（必需）：州ID（例如，"CA"，"TX"）
get_counties
获取县列表。
get_counties_by_state
获取特定州的县。 参数：
state_id（必需）：州ID（例如，"CA"，"TX"）
get_nws_usgs_crosswalk
获取国家气象局/USGS交叉引用数据。
OGC API工具
get_monitoring_locations
获取具有广泛过滤选项的监测位置。 参数：
bbox（可选）：以 "minx,miny,maxx,maxy" 表示的边界框limit（可选）：最大结果数量（默认值：100）offset（可选）：分页的起始偏移量（默认值：0）agency_code（可选）：按机构代码过滤（例如，"USGS"）state_code（可选）：按州代码过滤（例如，"CA"）county_code（可选）：按县代码过滤site_type_code（可选）：按站点类型代码过滤monitoring_location_number（可选）：特定的监测位置编号
get_monitoring_location_by_id
通过ID获取特定的监测位置。 参数：
location_id（必需）：监测位置ID
get_agency_codes
获取机构识别代码。 参数：
limit（可选）：最大结果数量（默认值：100）offset（可选）：分页的起始偏移量（默认值：0）
get_altitude_datums
获取垂直基准信息（推荐：NAVD88）。 参数：
limit（可选）：最大结果数量（默认值：100）offset（可选）：分页的起始偏移量（默认值：0）
get_aquifer_codes
获取含水层识别信息。 参数：
limit（可选）：最大结果数量（默认值：100）offset（可选）：分页的起始偏移量（默认值：0）
get_aquifer_types
获取含水层类型信息（承压与非承压）。 参数：
limit（可选）：最大结果数量（默认值：100）offset（可选）：分页的起始偏移量（默认值：0）
get_coordinate_accuracy_codes
获取经纬度值的坐标精度代码。 参数：
limit（可选）：最大结果数量（默认值：100）offset（可选）：分页的起始偏移量（默认值：0）
🔧 技术细节
常见问题
- API连接错误：确保你有活跃的互联网连接，并且USGS API可访问。
- 无效的站点编号：使用 USGS Water Data for the Nation 网站验证站点编号是否存在。
- 无可用数据：某些站点可能在请求的时间段或参数下没有数据。
- 速率限制：USGS API有使用限制；避免连续快速发出过多请求。
查找站点编号
使用 USGS Water Data for the Nation 网站查找你感兴趣区域的监测站站点编号。