mcp-server-environment-agency 1.0.0

package/readme-md.md

@@ -0,0 +1,243 @@
+# Environment Agency Flood Monitoring MCP Server
+
+A Model Context Protocol (MCP) server that provides access to the UK Environment Agency's Real Time Flood Monitoring API. This server allows you to access near real-time flood warnings, water level measurements, flow data, and monitoring station information.
+
+## Features
+
+- **Flood Warnings & Alerts**: Get current flood warnings and alerts with severity levels
+- **Flood Areas**: Access information about flood alert and warning areas
+- **Monitoring Stations**: Find water level and flow monitoring stations across the UK
+- **Real-time Measurements**: Access water levels, flows, and other measurements updated every 15 minutes
+- **Historical Data**: Retrieve historical readings and measurements
+- **Geographic Filtering**: Filter data by location using latitude, longitude, and distance
+- **No API Key Required**: Uses open government data with no registration needed
+
+## Data Attribution
+
+This server uses Environment Agency flood and river level data from the real-time data API (Beta), provided under the Open Government Licence.
+
+## Installation
+
+```bash
+npm install -g mcp-server-environment-agency
+```
+
+## Configuration
+
+### Claude Desktop Configuration
+
+Add this to your Claude Desktop configuration file:
+
+#### macOS
+`~/Library/Application Support/Claude/claude_desktop_config.json`
+
+#### Windows
+`%APPDATA%/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "environment-agency": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-environment-agency"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Flood Warning Tools
+
+- **get_flood_warnings**: Get current flood warnings and alerts
+- **get_flood_warning**: Get details of a specific flood warning
+- **get_flood_areas**: Get flood areas (regions where warnings may apply)
+- **get_flood_area**: Get details of a specific flood area
+
+### Monitoring Station Tools
+
+- **get_monitoring_stations**: Get monitoring stations that measure water levels, flows, etc.
+- **get_monitoring_station**: Get detailed information about a specific monitoring station
+- **get_measures**: Get measurement types available across all stations
+- **get_station_measures**: Get all measurement types from a specific station
+
+### Reading Tools
+
+- **get_readings**: Get measurement readings from all stations
+- **get_measure_readings**: Get readings for a specific measurement type
+- **get_station_readings**: Get all readings from a specific monitoring station
+
+## Usage Examples
+
+### Get Current Flood Warnings
+
+```typescript
+// Get all current flood warnings
+get_flood_warnings({})
+
+// Get severe flood warnings only
+get_flood_warnings({
+  min_severity: 1
+})
+
+// Get flood warnings in Somerset
+get_flood_warnings({
+  county: "Somerset"
+})
+
+// Get flood warnings near a location
+get_flood_warnings({
+  lat: 51.5074,
+  long: -0.1278,
+  dist: 10
+})
+```
+
+### Find Monitoring Stations
+
+```typescript
+// Find all stations measuring water levels
+get_monitoring_stations({
+  parameter: "level"
+})
+
+// Find stations near London
+get_monitoring_stations({
+  lat: 51.5074,
+  long: -0.1278,
+  dist: 25
+})
+
+// Search for stations on River Thames
+get_monitoring_stations({
+  search: "River Thames"
+})
+
+// Find groundwater monitoring stations
+get_monitoring_stations({
+  qualifier: "Groundwater"
+})
+```
+
+### Get Real-time Data
+
+```typescript
+// Get latest readings from all stations
+get_readings({
+  latest: true,
+  limit: 100
+})
+
+// Get latest flow readings
+get_readings({
+  latest: true,
+  parameter: "flow"
+})
+
+// Get today's readings from a specific station
+get_station_readings({
+  station_id: "1491TH",
+  today: true
+})
+
+// Get readings from the last week
+get_readings({
+  startdate: "2024-01-01",
+  enddate: "2024-01-07",
+  parameter: "level"
+})
+```
+
+## Data Types and Severity Levels
+
+### Flood Warning Severity Levels
+
+1. **Severe Flood Warning**: Severe Flooding, Danger to Life
+2. **Flood Warning**: Flooding is Expected, Immediate Action Required
+3. **Flood Alert**: Flooding is Possible, Be Prepared
+4. **Warning no Longer in Force**: The warning is no longer in force
+
+### Measurement Parameters
+
+- **Water Level** (`level`): Water levels at monitoring stations
+- **Flow** (`flow`): Water flow rates
+- **Temperature** (`temperature`): Air temperature
+- **Wind** (`wind`): Wind direction and speed
+
+### Station Types
+
+- **SingleLevel**: Single water level measurement
+- **MultiTraceLevel**: Multiple level measurements
+- **Coastal**: Coastal monitoring stations
+- **Groundwater**: Groundwater level monitoring
+- **Meteorological**: Weather measurements
+
+## API Updates and Reliability
+
+- Data is updated every 15 minutes
+- The API may redirect during high load - the client follows redirects automatically
+- Responses may be cached for short periods
+- No service level guarantee - not suitable for safety-critical applications
+
+## Rate Limits and Best Practices
+
+- For tracking all measurements, use a single call every 15 minutes: `get_readings({ latest: true })`
+- Use geographic and parameter filters to reduce response sizes
+- The API has built-in limits: default 500 items, maximum 10,000 for readings
+- Use pagination with `limit` and `offset` parameters for large datasets
+
+## Examples of Common Use Cases
+
+### Monitor Flood Risk in an Area
+
+```typescript
+// 1. Get current warnings
+const warnings = get_flood_warnings({
+  county: "Yorkshire",
+  min_severity: 3
+});
+
+// 2. Find nearby monitoring stations
+const stations = get_monitoring_stations({
+  lat: 53.8008,
+  long: -1.5491,
+  dist: 20,
+  parameter: "level"
+});
+
+// 3. Get latest readings
+const readings = get_readings({
+  latest: true,
+  lat: 53.8008,
+  long: -1.5491,
+  dist: 20
+});
+```
+
+### Track a Specific River
+
+```typescript
+// Find stations on River Severn
+const stations = get_monitoring_stations({
+  river_name: "Severn"
+});
+
+// Get latest readings from all Severn stations
+const readings = get_readings({
+  latest: true,
+  station_reference: "station_ref_from_above"
+});
+```
+
+### Historical Analysis
+
+```typescript
+// Get a week of data for analysis
+const historical = get_readings({
+  startdate: "2024-01-01",
+  enddate: "2024-01-07",
+  parameter: "level",
+  sorted: true,
+  limit: 1000
+});
+```