MVG Störung MCP Server (inofficial)

# MVG Störung MCP Server A Model Context Protocol (MCP) server that provides cached access to Munich Public Transport (MVG) disruption data.  ## Features - **Cached Data**: Automatically caches MVG incident data for at least 10 minutes to reduce API calls - **Real-time Incidents**: Fetches current incidents from the official MVG API - **Search Functionality**: Search incidents by line, title, or description - **Enhanced Data**: Adds human-readable timestamps and formats data for easy consumption - **MCP Compatible**: Works with any MCP-compatible client ## Data Source This server uses the official MVG API endpoint: `https://www.mvg.de/api/bgw-pt/v3/messages` The server filters the API response to only return incidents (type=INCIDENT) and enhances the data with: - Human-readable timestamps - Formatted descriptions - Deduplicated line information ## Installation ```bash # Install dependencies pip install -r requirements.txt # Or install as a package pip install -e . ``` ## Usage ### Running the Server ```bash python mvg_mcp_server.py ``` ### Available Tools 1. **get_mvg_incidents**: Get current MVG incidents (cached for 10+ minutes) - Optional parameter: `force_refresh` (boolean) - Force refresh cache even if not expired 2. **get_cache_status**: Get information about the cache status 3. **search_incidents**: Search incidents by line, title, or description - Required parameter: `query` (string) - Search query - Optional parameter: `line` (string) - Filter by specific line (e.g., 'U6', 'S1') ### Available Resources 1. **mvg://incidents**: Current incidents from Munich Public Transport (MVG) 2. **mvg://cache-info**: Information about the current cache status ## Example Usage ### Get All Current Incidents ```json { "method": "tools/call", "params": { "name": "get_mvg_incidents" } } ``` ### Search for U6 Line Issues ```json { "method": "tools/call", "params": { "name": "search_incidents", "arguments": { "query": "verspätung", "line": "U6" } } } ``` ### Force Cache Refresh ```json { "method": "tools/call", "params": { "name": "get_mvg_incidents", "arguments": { "force_refresh": true } } } ``` ## Cache Behavior - **Cache Duration**: 10 minutes minimum (configurable) - **Automatic Refresh**: Cache is automatically refreshed when expired - **Force Refresh**: Can be manually triggered via the `force_refresh` parameter - **Cache Info**: View cache status including expiration time and cached item count ## Data Format Each incident includes: - `title`: Incident title - `description`: Detailed description - `type`: Always "INCIDENT" - `publication`: Publication timestamp (Unix milliseconds) - `publication_readable`: Human-readable publication time - `validFrom`/`validTo`: Validity period - `validFrom_readable`/`validTo_readable`: Human-readable validity times - `lines`: Affected transport lines with details - `provider`: Always "MVG" ## Error Handling The server handles various error conditions: - API timeouts and connection errors - Invalid JSON responses - Cache expiration - Missing or malformed data ## Development ### Project Structure ``` ├── mvg_mcp_server.py # Main MCP server implementation ├── requirements.txt # Python dependencies ├── pyproject.toml # Project configuration └── README.md # This file ``` ### Dependencies - `mcp>=1.0.0`: Model Context Protocol framework - `httpx>=0.25.0`: Async HTTP client - `pydantic>=2.0.0`: Data validation and serialization ## License This project is dedicated to the public domain under the CC0 1.0 Universal license. See the [LICENSE](LICENSE) file for details. ## Contributing Contributions are welcome! Please feel free to submit issues and pull requests. ## Disclaimer This project is not an official MVG project, not endorsed or recommended. Please ask MVG for permission prior to using it.