usgs-mcp 0.1.0__tar.gz

usgs_mcp-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# Lock files (each server manages its own)
+uv.lock
+
+# Environment
+.env
+.env.local
+
+# Registry tokens
+.mcpregistry_*

usgs_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mansur Ali Jisan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

usgs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: usgs-mcp
+Version: 0.1.0
+Summary: MCP server providing access to USGS Water Services for streamflow, flood stages, and peak events
+Project-URL: Homepage, https://github.com/mansurjisan/ocean-mcp
+Project-URL: Repository, https://github.com/mansurjisan/ocean-mcp
+Project-URL: Bug Tracker, https://github.com/mansurjisan/ocean-mcp/issues
+Project-URL: Documentation, https://github.com/mansurjisan/ocean-mcp/tree/main/servers/usgs-mcp
+Project-URL: Changelog, https://github.com/mansurjisan/ocean-mcp/releases
+Author-email: Mansur Ali Jisan <mansur.jisan@noaa.gov>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: discharge,flood,gage-height,hydrology,mcp,model-context-protocol,river,streamflow,usgs,water-services
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# usgs-mcp
+
+<!-- mcp-name: io.github.mansurjisan/usgs-mcp -->
+
+MCP server providing access to **USGS Water Services** for real-time streamflow, flood stages, peak events, and historical statistics.
+
+This server fills a critical gap in the ocean-mcp ecosystem by providing **inland flooding and river data** — often the deadliest aspect of hurricanes and storms.
+
+## Data Sources
+
+- **USGS Water Services** (`waterservices.usgs.gov`) — real-time and historical streamflow data
+- **USGS NWIS Peak** (`nwis.waterdata.usgs.gov`) — annual peak streamflow records
+
+No API key required. All data is public domain.
+
+## Tools (10)
+
+### Site Discovery
+| Tool | Description |
+|------|-------------|
+| `usgs_find_sites` | Find gauge stations by state or bounding box |
+| `usgs_get_site_info` | Get detailed metadata for a specific site |
+| `usgs_find_nearest_sites` | Find sites near a lat/lon point |
+
+### Streamflow Data
+| Tool | Description |
+|------|-------------|
+| `usgs_get_instantaneous_values` | Real-time ~15-minute interval data (up to 120 days) |
+| `usgs_get_daily_values` | Daily mean/min/max values (decades of history) |
+| `usgs_get_hydrograph` | Summary with trend and historical median comparison |
+
+### Flood Analysis
+| Tool | Description |
+|------|-------------|
+| `usgs_get_peak_streamflow` | Annual peak flow records (50+ years at many sites) |
+| `usgs_get_flood_status` | Current conditions vs. historical context |
+
+### Statistics
+| Tool | Description |
+|------|-------------|
+| `usgs_get_monthly_stats` | Monthly mean/min/max/percentiles |
+| `usgs_get_daily_stats` | Daily percentiles (flow duration) |
+
+## Quick Start
+
+### Install from PyPI
+```bash
+uvx usgs-mcp
+```
+
+### Install from source
+```bash
+cd servers/usgs-mcp
+uv sync
+uv run usgs-mcp
+```
+
+### Claude Desktop Configuration
+```json
+{
+  "mcpServers": {
+    "usgs": {
+      "command": "uvx",
+      "args": ["usgs-mcp"]
+    }
+  }
+}
+```
+
+## Example Queries
+
+- "What is the current streamflow on the Potomac River?" → `usgs_get_instantaneous_values(site_number="01646500")`
+- "Find USGS gauges in Texas" → `usgs_find_sites(state_code="TX")`
+- "Is the Mississippi at St. Louis flooding?" → `usgs_get_flood_status(site_number="07010000")`
+- "What were the biggest floods on the Potomac?" → `usgs_get_peak_streamflow(site_number="01646500")`
+
+## Development
+
+```bash
+cd servers/usgs-mcp
+uv sync --group dev
+
+# Unit tests (no network)
+uv run pytest tests/ --ignore=tests/test_live.py --ignore=tests/test_mcp_protocol.py -v
+
+# Integration tests (needs network)
+uv run pytest tests/test_live.py -v
+
+# MCP protocol test
+uv run pytest tests/test_mcp_protocol.py -v
+```
+
+## License
+
+MIT

usgs_mcp-0.1.0/README.md

@@ -0,0 +1,95 @@
+# usgs-mcp
+
+<!-- mcp-name: io.github.mansurjisan/usgs-mcp -->
+
+MCP server providing access to **USGS Water Services** for real-time streamflow, flood stages, peak events, and historical statistics.
+
+This server fills a critical gap in the ocean-mcp ecosystem by providing **inland flooding and river data** — often the deadliest aspect of hurricanes and storms.
+
+## Data Sources
+
+- **USGS Water Services** (`waterservices.usgs.gov`) — real-time and historical streamflow data
+- **USGS NWIS Peak** (`nwis.waterdata.usgs.gov`) — annual peak streamflow records
+
+No API key required. All data is public domain.
+
+## Tools (10)
+
+### Site Discovery
+| Tool | Description |
+|------|-------------|
+| `usgs_find_sites` | Find gauge stations by state or bounding box |
+| `usgs_get_site_info` | Get detailed metadata for a specific site |
+| `usgs_find_nearest_sites` | Find sites near a lat/lon point |
+
+### Streamflow Data
+| Tool | Description |
+|------|-------------|
+| `usgs_get_instantaneous_values` | Real-time ~15-minute interval data (up to 120 days) |
+| `usgs_get_daily_values` | Daily mean/min/max values (decades of history) |
+| `usgs_get_hydrograph` | Summary with trend and historical median comparison |
+
+### Flood Analysis
+| Tool | Description |
+|------|-------------|
+| `usgs_get_peak_streamflow` | Annual peak flow records (50+ years at many sites) |
+| `usgs_get_flood_status` | Current conditions vs. historical context |
+
+### Statistics
+| Tool | Description |
+|------|-------------|
+| `usgs_get_monthly_stats` | Monthly mean/min/max/percentiles |
+| `usgs_get_daily_stats` | Daily percentiles (flow duration) |
+
+## Quick Start
+
+### Install from PyPI
+```bash
+uvx usgs-mcp
+```
+
+### Install from source
+```bash
+cd servers/usgs-mcp
+uv sync
+uv run usgs-mcp
+```
+
+### Claude Desktop Configuration
+```json
+{
+  "mcpServers": {
+    "usgs": {
+      "command": "uvx",
+      "args": ["usgs-mcp"]
+    }
+  }
+}
+```
+
+## Example Queries
+
+- "What is the current streamflow on the Potomac River?" → `usgs_get_instantaneous_values(site_number="01646500")`
+- "Find USGS gauges in Texas" → `usgs_find_sites(state_code="TX")`
+- "Is the Mississippi at St. Louis flooding?" → `usgs_get_flood_status(site_number="07010000")`
+- "What were the biggest floods on the Potomac?" → `usgs_get_peak_streamflow(site_number="01646500")`
+
+## Development
+
+```bash
+cd servers/usgs-mcp
+uv sync --group dev
+
+# Unit tests (no network)
+uv run pytest tests/ --ignore=tests/test_live.py --ignore=tests/test_mcp_protocol.py -v
+
+# Integration tests (needs network)
+uv run pytest tests/test_live.py -v
+
+# MCP protocol test
+uv run pytest tests/test_mcp_protocol.py -v
+```
+
+## License
+
+MIT

usgs_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usgs-mcp"
+version = "0.1.0"
+description = "MCP server providing access to USGS Water Services for streamflow, flood stages, and peak events"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    {name = "Mansur Ali Jisan", email = "mansur.jisan@noaa.gov"},
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "usgs",
+    "streamflow",
+    "flood",
+    "water-services",
+    "hydrology",
+    "river",
+    "discharge",
+    "gage-height",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/mansurjisan/ocean-mcp"
+Repository = "https://github.com/mansurjisan/ocean-mcp"
+"Bug Tracker" = "https://github.com/mansurjisan/ocean-mcp/issues"
+Documentation = "https://github.com/mansurjisan/ocean-mcp/tree/main/servers/usgs-mcp"
+Changelog = "https://github.com/mansurjisan/ocean-mcp/releases"
+
+[project.scripts]
+usgs-mcp = "usgs_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/usgs_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "integration: tests that hit live USGS APIs (deselect with '-m \"not integration\"')",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "respx>=0.22.0",
+]

usgs_mcp-0.1.0/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mansurjisan/usgs-mcp",
+  "title": "USGS Water Services MCP Server",
+  "description": "USGS Water Services streamflow, flood stages, and peak events via waterservices.usgs.gov",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/mansurjisan/ocean-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "usgs-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

usgs_mcp-0.1.0/smithery.yaml

@@ -0,0 +1,9 @@
+# Smithery configuration — https://smithery.ai/docs/config
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required: []
+    properties: {}
+  commandFunction: |-
+    (config) => ({ command: 'uvx', args: ['usgs-mcp'] })

usgs_mcp-0.1.0/src/usgs_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

usgs_mcp-0.1.0/src/usgs_mcp/client.py

@@ -0,0 +1,78 @@
+"""Async HTTP client for USGS Water Services API."""
+
+from typing import Any
+
+import httpx
+
+from .models import USGS_BASE_URL, USGS_PEAK_URL, USER_AGENT
+
+
+class USGSAPIError(Exception):
+    """Custom exception for USGS API errors."""
+
+    pass
+
+
+def parse_rdb(text: str) -> list[dict[str, str]]:
+    """Parse USGS RDB tab-delimited format to list of dicts.
+
+    RDB format: # comment lines, then header row, then data type row
+    (5s, 15n, etc.), then data rows.
+    """
+    lines = [line for line in text.strip().split("\n") if not line.startswith("#")]
+    if len(lines) < 2:
+        return []
+    headers = lines[0].split("\t")
+    # Skip lines[1] — data type definitions (e.g., "5s\t15s\t20d")
+    rows = []
+    for line in lines[2:]:
+        if not line.strip():
+            continue
+        vals = line.split("\t")
+        rows.append(dict(zip(headers, vals)))
+    return rows
+
+
+class USGSClient:
+    """Async client for USGS Water Services API."""
+
+    def __init__(self) -> None:
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                timeout=30.0,
+                headers={"User-Agent": USER_AGENT},
+            )
+        return self._client
+
+    async def get_json(self, endpoint: str, params: dict[str, Any]) -> dict:
+        """Fetch JSON from IV/DV endpoints."""
+        params["format"] = "json"
+        client = await self._get_client()
+        response = await client.get(f"{USGS_BASE_URL}/{endpoint}/", params=params)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_rdb(
+        self, endpoint: str, params: dict[str, Any]
+    ) -> list[dict[str, str]]:
+        """Fetch RDB (tab-delimited) from site/stat endpoints."""
+        params["format"] = "rdb"
+        client = await self._get_client()
+        response = await client.get(f"{USGS_BASE_URL}/{endpoint}/", params=params)
+        response.raise_for_status()
+        return parse_rdb(response.text)
+
+    async def get_peak(self, params: dict[str, Any]) -> list[dict[str, str]]:
+        """Fetch peak streamflow RDB from nwis.waterdata.usgs.gov."""
+        params["format"] = "rdb"
+        client = await self._get_client()
+        response = await client.get(USGS_PEAK_URL, params=params)
+        response.raise_for_status()
+        return parse_rdb(response.text)
+
+    async def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()

usgs_mcp-0.1.0/src/usgs_mcp/models.py

@@ -0,0 +1,141 @@
+"""Constants and helpers for usgs-mcp."""
+
+USGS_BASE_URL = "https://waterservices.usgs.gov/nwis"
+USGS_PEAK_URL = "https://nwis.waterdata.usgs.gov/nwis/peak"
+
+USER_AGENT = "usgs-mcp/0.1.0 (https://github.com/mansurjisan/ocean-mcp)"
+
+# Well-known USGS parameter codes
+PARAMETER_CODES: dict[str, dict] = {
+    "00060": {
+        "name": "Discharge",
+        "units": "ft³/s (cfs)",
+        "description": "Streamflow discharge",
+    },
+    "00065": {
+        "name": "Gage height",
+        "units": "ft",
+        "description": "Water surface elevation above datum",
+    },
+    "00010": {"name": "Temperature", "units": "°C", "description": "Water temperature"},
+    "00045": {
+        "name": "Precipitation",
+        "units": "in",
+        "description": "Accumulated precipitation",
+    },
+    "00095": {
+        "name": "Specific conductance",
+        "units": "µS/cm",
+        "description": "Specific conductance at 25°C",
+    },
+    "00300": {
+        "name": "Dissolved oxygen",
+        "units": "mg/L",
+        "description": "Dissolved oxygen",
+    },
+    "00400": {"name": "pH", "units": "standard units", "description": "pH of water"},
+    "63680": {"name": "Turbidity", "units": "FNU", "description": "Turbidity"},
+}
+
+# Well-known reference sites for testing and examples
+REFERENCE_SITES: dict[str, dict] = {
+    "01646500": {"name": "Potomac River at Little Falls, MD", "state": "MD"},
+    "02037500": {"name": "James River at Richmond, VA", "state": "VA"},
+    "07010000": {"name": "Mississippi River at St. Louis, MO", "state": "MO"},
+    "08066500": {"name": "Trinity River at Romayor, TX", "state": "TX"},
+    "02146000": {"name": "Catawba River near Pleasant Garden, NC", "state": "NC"},
+}
+
+# US state codes for site queries
+US_STATE_CODES: dict[str, str] = {
+    "AL": "Alabama",
+    "AK": "Alaska",
+    "AZ": "Arizona",
+    "AR": "Arkansas",
+    "CA": "California",
+    "CO": "Colorado",
+    "CT": "Connecticut",
+    "DE": "Delaware",
+    "FL": "Florida",
+    "GA": "Georgia",
+    "HI": "Hawaii",
+    "ID": "Idaho",
+    "IL": "Illinois",
+    "IN": "Indiana",
+    "IA": "Iowa",
+    "KS": "Kansas",
+    "KY": "Kentucky",
+    "LA": "Louisiana",
+    "ME": "Maine",
+    "MD": "Maryland",
+    "MA": "Massachusetts",
+    "MI": "Michigan",
+    "MN": "Minnesota",
+    "MS": "Mississippi",
+    "MO": "Missouri",
+    "MT": "Montana",
+    "NE": "Nebraska",
+    "NV": "Nevada",
+    "NH": "New Hampshire",
+    "NJ": "New Jersey",
+    "NM": "New Mexico",
+    "NY": "New York",
+    "NC": "North Carolina",
+    "ND": "North Dakota",
+    "OH": "Ohio",
+    "OK": "Oklahoma",
+    "OR": "Oregon",
+    "PA": "Pennsylvania",
+    "RI": "Rhode Island",
+    "SC": "South Carolina",
+    "SD": "South Dakota",
+    "TN": "Tennessee",
+    "TX": "Texas",
+    "UT": "Utah",
+    "VT": "Vermont",
+    "VA": "Virginia",
+    "WA": "Washington",
+    "WV": "West Virginia",
+    "WI": "Wisconsin",
+    "WY": "Wyoming",
+    "DC": "District of Columbia",
+    "PR": "Puerto Rico",
+    "VI": "Virgin Islands",
+    "GU": "Guam",
+    "AS": "American Samoa",
+    "MP": "Northern Mariana Islands",
+}
+
+# NWS flood stage categories
+FLOOD_CATEGORIES: dict[str, str] = {
+    "action": "Water is approaching bankfull; begin monitoring",
+    "flood": "Minor flooding is occurring or imminent",
+    "moderate": "Moderate flooding; some inundation of structures/roads",
+    "major": "Major flooding; extensive inundation, significant threat to life/property",
+}
+
+# Stat report types
+STAT_REPORT_TYPES: dict[str, str] = {
+    "daily": "Daily statistics",
+    "monthly": "Monthly statistics",
+    "annual": "Annual statistics",
+}
+
+# USGS data qualification codes
+QUALIFICATION_CODES: dict[str, str] = {
+    "A": "Approved for publication",
+    "P": "Provisional, subject to revision",
+    "e": "Estimated",
+    "Eqp": "Equipment malfunction",
+    "Mnt": "Maintenance",
+    "Dry": "Dry conditions",
+    "Ssn": "Parameter monitored seasonally",
+}
+
+
+def format_parameter(code: str) -> str:
+    """Return a human-readable name for a USGS parameter code."""
+    info = PARAMETER_CODES.get(code)
+    if info:
+        return f"{info['name']} ({info['units']})"
+    return f"Parameter {code}"

usgs_mcp-0.1.0/src/usgs_mcp/server.py

@@ -0,0 +1,32 @@
+"""FastMCP server entry point for USGS Water Services."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import USGSClient
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[dict]:
+    """Manage the shared USGSClient lifecycle."""
+    client = USGSClient()
+    try:
+        yield {"usgs_client": client}
+    finally:
+        await client.close()
+
+
+mcp = FastMCP("usgs_mcp", lifespan=app_lifespan)
+
+# Import tool modules to register them with the server
+from .tools import flood, sites, statistics, streamflow  # noqa: E402, F401
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()