IPMA Weather MCP Server

Instructions

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.

Implementation Reference

• weather.py:213-291 (handler)

  The handler function decorated with @mcp.tool(), which registers it as an MCP tool and implements the core logic: fetches sea forecast from IPMA API for specified day, optionally filters by location, maps location names, and formats output with wave heights, periods, directions, and sea temperatures.

  @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