mcp-server-environment-agency 1.0.0 → 1.1.0

package/{license.txt → LICENSE}

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Dwain Barnes
-
-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
+MIT License
+
+Copyright (c) 2025 Dwain Barnes
+
+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.

package/README.md

@@ -0,0 +1,172 @@
+# Environment Agency Flood Monitoring MCP Server
+
+[![npm version](https://badge.fury.io/js/mcp-server-environment-agency.svg)](https://badge.fury.io/js/mcp-server-environment-agency)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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.
+
+## 🆕 What's new in 1.1.0
+
+Migrated to the modern MCP SDK (`@modelcontextprotocol/sdk` 1.x), added Zod input validation (range, format, and cross-field checks), 30s request timeouts with actionable errors, id sanitization, and response capping (polygon omission, default/max limits, and 60 KB truncation) to protect the client's context window.
+
+## 🌊 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
+
+## 📦 Installation
+
+### For Claude Desktop Users
+
+Add this to your Claude Desktop configuration:
+
+**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"]
+    }
+  }
+}
+```
+
+### For Developers
+
+```bash
+npm install -g 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 detailed information for station 1029TH (Bourton Dickler)
+Find monitoring stations within 25km of Cambridge
+Find monitoring stations in Yorkshire
+Show me today's water level readings from any 5 stations
+```
+
+
+## 📊 Data Types
+
+### 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
+
+## 🚀 Development
+
+### Prerequisites
+- Node.js 20+
+- TypeScript
+
+### Setup
+```bash
+git clone https://github.com/dwain-barnes/mcp-server-environment-agency.git
+cd mcp-server-environment-agency
+npm install
+```
+
+### Build
+```bash
+npm run build
+```
+
+### Test
+```bash
+# Build and run the end-to-end smoke test (spawns the server over stdio,
+# lists tools, exercises a live query, and checks id sanitization)
+npm test
+```
+
+### Local Development
+```bash
+# Link for local testing
+npm link
+
+# Test with Claude Desktop using local version
+```
+
+## 📄 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](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
+
+## 🔄 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
+- 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
+
+## 📉 Response Limits
+
+To keep responses friendly to LLM context windows, this server shapes and caps API results:
+
+- **Default page size**: 50 items for stations, measures and flood areas; 100 for readings (applied when you don't pass `limit`).
+- **Maximum `limit`**: 500 for any list tool. The Environment Agency API itself allows more, but this server caps for context safety — use `offset` to paginate.
+- **Polygon geometry omitted**: flood-area and flood-warning polygons are replaced with a short placeholder, as they are the single largest field in the API.
+- **60 KB truncation**: if a rendered response still exceeds ~60,000 characters, the items list is progressively truncated and a note explains how many items were omitted and which filters (`county`, `river_name`, `town`, or `lat`+`long`+`dist`) or pagination to use.
+- Responses use a compact `{ meta, count, items }` envelope with the API `@context` field stripped.
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Environment Agency for providing open flood monitoring data
+- Model Context Protocol team for the excellent framework
+- UK Government for open data initiatives
+
+
+
+**Built by [Dwain Barnes](https://github.com/dwain-barnes)** 🇬🇧