list_airlines

Instructions

Implementation Reference

• src/aviationstack_mcp/server.py:711-736 (handler)

  Core handler function that calls the Aviationstack 'airlines' endpoint via _list_reference_data, validates inputs, and returns a JSON string of airline records.

  def list_airlines(limit: int = 10, offset: int = 0, search: str = "") -> str:
      """List airlines (supports basic-plan autocomplete through `search`)."""
      try:
          _validate_positive_int(limit, "limit")
          _validate_non_negative_int(offset, "offset")
          params: dict[str, Any] = {"limit": limit, "offset": offset}
          if search:
              params["search"] = search
  
          return _list_reference_data(
              "airlines",
              params,
              lambda airline: {
                  "airline_name": airline.get("airline_name"),
                  "iata_code": airline.get("iata_code"),
                  "icao_code": airline.get("icao_code"),
                  "callsign": airline.get("callsign"),
                  "status": airline.get("status"),
                  "country_name": airline.get("country_name"),
                  "country_iso2": airline.get("country_iso2"),
              },
          )
      except requests.RequestException as exc:
          return _error_response("fetching airlines", exc)
      except (KeyError, ValueError, TypeError) as exc:
          return _error_response("fetching airlines", exc)

• src/aviationstack_mcp/server.py:1018-1035 (registration)

  MCP tool registration decorator that defines the 'list_airlines' tool with FastMCP and wraps the core handler with Pydantic input validation.

  @mcp.tool(
      name="list_airlines",
      description="List airlines with pagination and optional search.",
  )
  def list_airlines_tool(
      limit: Annotated[int, Field(description="Maximum number of airlines to return.", gt=0)] = 10,
      offset: Annotated[int, Field(description="Offset for pagination.", ge=0)] = 0,
      search: Annotated[
          str, Field(description="Optional airline search text for autocomplete.")
      ] = "",
  ) -> str:
      """Tool wrapper for list_airlines."""
      validated_input = ListAirlinesInput(limit=limit, offset=offset, search=search)
      return list_airlines(
          limit=validated_input.limit,
          offset=validated_input.offset,
          search=validated_input.search,
      )

• src/aviationstack_mcp/server.py:230-248 (schema)

  Pydantic input schema for the list_airlines tool, defining limit, offset, and search fields with validation.

  class ListAirlinesInput(BaseModel):
      """Input schema for list_airlines tool."""
  
      model_config = ConfigDict(extra="forbid")
  
      limit: int = Field(
          default=10,
          description="Maximum number of airlines to return.",
          gt=0,
      )
      offset: int = Field(
          default=0,
          description="Offset for pagination.",
          ge=0,
      )
      search: str = Field(
          default="",
          description="Optional airline search text for autocomplete.",
      )

• src/aviationstack_mcp/server.py:376-382 (helper)

  Generic helper used by list_airlines (and similar tools) to fetch reference data from an endpoint, apply a mapping function, and return JSON.

  def _list_reference_data(
      endpoint: str,
      params: dict[str, Any],
      mapper: Callable[[dict[str, Any]], dict[str, Any]],
  ) -> str:
      data = fetch_flight_data(endpoint, params)
      return json.dumps([mapper(item) for item in data.get("data", [])])