random_cities_detailed_info

Instructions

Implementation Reference

• src/aviationstack_mcp/server.py:197-206 (schema)

  Input schema (Pydantic model) for the random_cities_detailed_info tool, validating number_of_cities is a positive integer with 'extra=forbid'.

  class RandomCitiesDetailedInfoInput(BaseModel):
      """Input schema for random_cities_detailed_info tool."""
  
      model_config = ConfigDict(extra="forbid")
  
      number_of_cities: int = Field(
          ...,
          description="Number of random cities to return.",
          gt=0,
      )

• src/aviationstack_mcp/server.py:653-679 (handler)

  Core handler: validates input, fetches 'cities' endpoint data via fetch_flight_data, samples randomly with _sample_data, extracts detailed fields (gmt, city_id, iata_code, country_iso2, geoname_id, latitude, longitude, timezone, city_name), and returns JSON.

  def random_cities_detailed_info(number_of_cities: int) -> str:
      """Get detailed info for random cities."""
      try:
          _validate_positive_int(number_of_cities, "number_of_cities")
          data = fetch_flight_data("cities", {"limit": number_of_cities})
          sampled_cities = _sample_data(data.get("data", []), number_of_cities)
  
          cities = []
          for city in sampled_cities:
              cities.append(
                  {
                      "gmt": city.get("gmt"),
                      "city_id": city.get("city_id"),
                      "iata_code": city.get("iata_code"),
                      "country_iso2": city.get("country_iso2"),
                      "geoname_id": city.get("geoname_id"),
                      "latitude": city.get("latitude"),
                      "longitude": city.get("longitude"),
                      "timezone": city.get("timezone"),
                      "city_name": city.get("city_name"),
                  }
              )
          return json.dumps(cities)
      except requests.RequestException as exc:
          return _error_response("fetching cities", exc)
      except (KeyError, ValueError, TypeError) as exc:
          return _error_response("fetching cities", exc)

• src/aviationstack_mcp/server.py:984-995 (registration)

  Tool registration using @mcp.tool decorator with name 'random_cities_detailed_info', description, and the wrapper function that validates input and delegates to the core handler.

  @mcp.tool(
      name="random_cities_detailed_info",
      description="Return detailed metadata for random cities.",
  )
  def random_cities_detailed_info_tool(
      number_of_cities: Annotated[
          int, Field(description="Number of random cities to return.", gt=0)
      ],
  ) -> str:
      """Tool wrapper for random_cities_detailed_info."""
      validated_input = RandomCitiesDetailedInfoInput(number_of_cities=number_of_cities)
      return random_cities_detailed_info(number_of_cities=validated_input.number_of_cities)

• src/aviationstack_mcp/server.py:311-313 (helper)

  Helper: validates positive integer, used to ensure number_of_cities > 0.

  def _validate_positive_int(value: int, param_name: str) -> None:
      if value <= 0:
          raise ValueError(f"'{param_name}' must be greater than 0.")

• src/aviationstack_mcp/server.py:335-338 (helper)

  Helper: randomly samples up to count items from a list, used to pick random cities from API results.

  def _sample_data(items: list[dict[str, Any]], count: int) -> list[dict[str, Any]]:
      _validate_positive_int(count, "count")
      number_to_fetch = min(count, len(items))
      return random.sample(items, number_to_fetch)