Usgs Water MCP

🚀 USGS Water MCP

本項目提供了一個MCP服務器，可通過三個API全面訪問美國地質調查局（USGS）的水資源數據，為水資源相關的研究、監測和決策提供有力支持。

🚀 快速開始

若你想使用一個簡潔的Web界面來調用這些工具，請訪問 https://aqua-node.onrender.com/landing 並協助我進行一些測試！

✨ 主要特性

此MCP服務器通過三個API提供對USGS水資源數據的全面訪問：

1. USGS Water Services API - 即時水資源測量數據（如水流、水位、溫度等）
2. Real-Time Flood Impacts API - 當前洪水狀況和參考點
3. OGC API - 監測位置元數據、機構代碼和地質信息

服務器採用模塊化設計，通過單個入口點統一不同的API處理程序。

📦 安裝指南

通過pip安裝

pip install -e .

手動安裝

1. 克隆此倉庫
2. 安裝依賴項：

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）

🔧 技術細節

常見問題

1. API連接錯誤：確保你有活躍的互聯網連接，並且USGS API可訪問。
2. 無效的站點編號：使用 USGS Water Data for the Nation 網站驗證站點編號是否存在。
3. 無可用數據：某些站點可能在請求的時間段或參數下沒有數據。
4. 速率限制：USGS API有使用限制；避免連續快速發出過多請求。

查找站點編號

使用 USGS Water Data for the Nation 網站查找你感興趣區域的監測站站點編號。

徽章