IPMA Weather MCP Server

Instructions

Implementation Reference

• weather.py:213-291 (handler)

  The core handler function for the 'get_sea_forecast' tool, decorated with @mcp.tool() for automatic registration in the FastMCP server. It fetches sea state forecasts from the IPMA API for specified day (0-2) and optional location, formatting wave height, total sea, period, direction, and sea temperature. Uses the shared 'make_ipma_request' helper.
  @mcp.tool() async def get_sea_forecast(location_name: str = "", day: int = 0) -> str: """Get sea state forecast for Portuguese coastal areas (Previsão Estado do Mar até 3 dias). Args: location_name: Name of coastal location (e.g., 'Porto', 'Lisboa', 'Faro', 'Funchal', 'Leiria'). Leave empty to see all available locations. day: Forecast day (0=today, 1=tomorrow, 2=day after tomorrow). Valid range: 0-2 Returns sea state forecast including wave height, period, direction, and sea temperature. """ if day < 0 or day > 2: return "Invalid day parameter. Please use 0 (today), 1 (tomorrow), or 2 (day after tomorrow)." # Get sea forecast forecast_url = f"{IPMA_API_BASE}/forecast/oceanography/daily/hp-daily-sea-forecast-day{day}.json" forecast_data = await make_ipma_request(forecast_url) if not forecast_data or "data" not in forecast_data: return "Unable to fetch sea forecast data." # Get location names locations_url = f"{IPMA_API_BASE}/sea-locations.json" locations_data = await make_ipma_request(locations_url) # Create location mapping location_map = {} if locations_data and isinstance(locations_data, list): for loc in locations_data: location_map[loc.get('globalIdLocal')] = loc.get('local', 'Unknown') result = f"""Sea State Forecast Forecast Date: {forecast_data.get('forecastDate', 'Unknown')} Owner: {forecast_data.get('owner', 'IPMA')} """ if not location_name: # Show all locations result += f"Available Locations ({len(forecast_data['data'])} total):\n\n" for location in forecast_data['data'][:10]: loc_id = location.get('globalIdLocal') loc_name = location_map.get(loc_id, f"ID: {loc_id}") result += f"""Location: {loc_name} Position: {location.get('latitude', 'N/A')}°N, {location.get('longitude', 'N/A')}°E Wave Height: {location.get('waveHighMin', 'N/A')}m - {location.get('waveHighMax', 'N/A')}m Total Sea: {location.get('totalSeaMin', 'N/A')}m - {location.get('totalSeaMax', 'N/A')}m Wave Period: {location.get('wavePeriodMin', 'N/A')}s - {location.get('wavePeriodMax', 'N/A')}s Wave Direction: {location.get('predWaveDir', 'N/A')} Sea Temperature: {location.get('sstMin', 'N/A')}°C - {location.get('sstMax', 'N/A')}°C --- """ else: # Search for specific location location_name_lower = location_name.lower() found = False for location in forecast_data['data']: loc_id = location.get('globalIdLocal') loc_name = location_map.get(loc_id, '') if location_name_lower in loc_name.lower(): found = True result += f"""Location: {loc_name} Position: {location.get('latitude', 'N/A')}°N, {location.get('longitude', 'N/A')}°E Wave Height: {location.get('waveHighMin', 'N/A')}m - {location.get('waveHighMax', 'N/A')}m Total Sea: {location.get('totalSeaMin', 'N/A')}m - {location.get('totalSeaMax', 'N/A')}m Wave Period: {location.get('wavePeriodMin', 'N/A')}s - {location.get('wavePeriodMax', 'N/A')}s Wave Direction: {location.get('predWaveDir', 'N/A')} Sea Temperature: {location.get('sstMin', 'N/A')}°C - {location.get('sstMax', 'N/A')}°C """ break if not found: available = [location_map.get(loc.get('globalIdLocal'), f"ID: {loc.get('globalIdLocal')}") for loc in forecast_data['data'][:10]] result += f"Location '{location_name}' not found.\nAvailable locations: {', '.join(available)}" return result