mcp-stargazing

Instructions

Implementation Reference

• src/functions/weather/impl.py:7-25 (handler)

  The main tool handler function for 'get_weather_by_name', decorated with @mcp.tool(). It validates the API key environment variable, calls the QWeather interaction helper, and formats the response.

  @mcp.tool()
  def get_weather_by_name(place_name: str):
      """
      Fetches weather data for a specified location by its name using the QWeather API.
  
      Args:
          place_name (str): The name of the location (e.g., city, region) for which weather data is requested.
  
      Returns:
          Dict with keys "data", "_meta". "data" contains the weather data.
  
      Raises:
          ValueError: If the `QWEATHER_API_KEY` environment variable is not set, preventing API access.
      """
      QWEATHER_API_KEY = os.getenv("QWEATHER_API_KEY", None)
      if QWEATHER_API_KEY is None:
          raise ValueError("QWEATHER_API_KEY environment variable not set.")
      result = qweather_get_weather_by_name(place_name, QWEATHER_API_KEY)
      return format_response(result)

• src/qweather_interaction.py:76-101 (helper)

  Core helper function that performs QWeather API calls: POI lookup for coordinates, then real-time weather and 10-day forecast retrieval.

  def qweather_get_weather_by_name(city: str, api_token: str) -> dict:
      """
      Fetches both real-time and 10-day forecast weather data for a given city name.
      Args:
          city (str): The city name (e.g., "上海市闵行区").
          api_token (str): The QWeather API authentication token.
  
      Returns:
          dict: A dictionary containing:
              - "real_time": Real-time weather data.
              - "ten_days_forcasts": 10-day weather forecast data.
          Returns None if any API call fails.
      """
      res = qweather_get_poi(city, api_token)
      if not res:
          return None
      
      lat, lon = res['poi'][0]['lat'], res['poi'][0]['lon']
      
      real_time_data = qweather_get_weather_by_coord_real_time(lon, lat, api_token)
      ten_days_forcasts = qweather_get_weather_by_coord_in_ten_days(lon, lat, api_token)
      
      return {
          "real_time": real_time_data,
          "ten_days_forcasts": ten_days_forcasts
      }