aviationstack-mcp-server 0.1.0__py3-none-any.whl

aviationstack_mcp_server/models/airline.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from aviationstack_mcp_server.models.common import AviationstackModel
+
+
+class Airline(AviationstackModel):
+    """Airline reference data."""
+
+    airline_name: str | None = None
+    iata_code: str | None = None
+    icao_code: str | None = None
+    callsign: str | None = None
+    status: str | None = None
+    country_name: str | None = None
+    country_iso2: str | None = None
+
+    airline_id: str | None = Field(
+        default=None,
+        alias="airline_id",
+    )
+
+
+class AirlineResponse(AviationstackModel):
+    """Aviationstack airline response."""
+
+    pagination: dict | None = None
+    data: list[Airline] = Field(default_factory=list)

aviationstack_mcp_server/models/airport.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from aviationstack_mcp_server.models.common import AviationstackModel
+
+
+class Airport(AviationstackModel):
+    """Airport reference data."""
+
+    airport_name: str | None = None
+    iata_code: str | None = None
+    icao_code: str | None = None
+    city_iata_code: str | None = None
+    country_name: str | None = None
+    country_iso2: str | None = None
+    timezone: str | None = None
+    gmt: str | None = None
+
+    latitude: float | None = None
+    longitude: float | None = None
+
+    airport_id: str | None = Field(
+        default=None,
+        alias="airport_id",
+    )
+
+
+class AirportResponse(AviationstackModel):
+    """Aviationstack airport response."""
+
+    pagination: dict | None = None
+    data: list[Airport] = Field(default_factory=list)

aviationstack_mcp_server/models/common.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AviationstackModel(BaseModel):
+    """Base model for Aviationstack API data."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+
+
+class AviationstackResponse(AviationstackModel):
+    """Generic envelope returned by Aviationstack."""
+
+    pagination: dict[str, Any] | None = None

aviationstack_mcp_server/models/flight.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from aviationstack_mcp_server.models.common import AviationstackModel
+
+
+class FlightIdentifier(AviationstackModel):
+    """Flight identification information."""
+
+    iata: str | None = None
+    icao: str | None = None
+    number: str | None = None
+
+
+class AirlineReference(AviationstackModel):
+    """Airline information associated with a flight."""
+
+    name: str | None = None
+    iata: str | None = None
+    icao: str | None = None
+
+
+class AirportReference(AviationstackModel):
+    """Airport information associated with a flight."""
+
+    airport: str | None = None
+    iata: str | None = None
+    icao: str | None = None
+    timezone: str | None = None
+    terminal: str | None = None
+    gate: str | None = None
+
+    scheduled: str | None = None
+    estimated: str | None = None
+    actual: str | None = None
+    delay: int | None = None
+
+
+class FlightAircraftReference(AviationstackModel):
+    """Aircraft information associated with a flight."""
+
+    registration: str | None = None
+    iata: str | None = None
+    icao: str | None = None
+    model: str | None = None
+    model_code: str | None = None
+    model_text: str | None = Field(
+        default=None,
+        alias="modelText",
+    )
+
+
+class Flight(AviationstackModel):
+    """Aviationstack flight record."""
+
+    flight_date: str | None = None
+    flight_status: str | None = None
+
+    flight: FlightIdentifier | None = None
+    airline: AirlineReference | None = None
+    departure: AirportReference | None = None
+    arrival: AirportReference | None = None
+    aircraft: FlightAircraftReference | None = None
+
+
+class FlightResponse(AviationstackModel):
+    """Aviationstack response containing flight records."""
+
+    pagination: dict | None = None
+    data: list[Flight] = Field(default_factory=list)
+
+
+class ScheduleFlightIdentifier(AviationstackModel):
+    """Flight identifier returned by timetable endpoints."""
+
+    iata_number: str | None = Field(
+        default=None,
+        alias="iataNumber",
+    )
+    icao_number: str | None = Field(
+        default=None,
+        alias="icaoNumber",
+    )
+
+
+class ScheduleTimeReference(AviationstackModel):
+    """Schedule timing information."""
+
+    estimated_time: str | None = Field(
+        default=None,
+        alias="estimatedTime",
+    )
+    scheduled_time: str | None = Field(
+        default=None,
+        alias="scheduledTime",
+    )
+    actual_time: str | None = Field(
+        default=None,
+        alias="actualTime",
+    )
+    iata_code: str | None = Field(
+        default=None,
+        alias="iataCode",
+    )
+    terminal: str | None = None
+    gate: str | None = None
+    delay: int | None = None
+
+
+class ScheduleFlight(AviationstackModel):
+    """Flight record returned by timetable/future schedule endpoints."""
+
+    airline: AirlineReference | None = None
+    flight: ScheduleFlightIdentifier | None = None
+    departure: ScheduleTimeReference | None = None
+    arrival: ScheduleTimeReference | None = None
+    aircraft: FlightAircraftReference | None = None
+
+
+class ScheduleResponse(AviationstackModel):
+    """Response containing scheduled flights."""
+
+    pagination: dict | None = None
+    data: list[ScheduleFlight] = Field(default_factory=list)

aviationstack_mcp_server/models/location.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from aviationstack_mcp_server.models.common import AviationstackModel
+
+
+class Country(AviationstackModel):
+    """Country reference data."""
+
+    name: str | None = None
+    capital: str | None = None
+    currency_code: str | None = None
+    fips_code: str | None = None
+    country_iso2: str | None = None
+    country_iso3: str | None = None
+    continent: str | None = None
+    country_id: str | None = None
+    currency_name: str | None = None
+    country_iso_numeric: str | None = None
+    phone_prefix: str | None = None
+    population: int | None = None
+
+
+class CountryResponse(AviationstackModel):
+    """Response containing countries."""
+
+    pagination: dict | None = None
+    data: list[Country] = Field(default_factory=list)
+
+
+class City(AviationstackModel):
+    """City reference data."""
+
+    gmt: str | None = None
+    city_id: str | None = None
+    iata_code: str | None = None
+    country_iso2: str | None = None
+    geoname_id: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    timezone: str | None = None
+    city_name: str | None = None
+
+
+class CityResponse(AviationstackModel):
+    """Response containing cities."""
+
+    pagination: dict | None = None
+    data: list[City] = Field(default_factory=list)

aviationstack_mcp_server/models/queries.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+from datetime import date as Date
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class QueryModel(BaseModel):
+    """Base model for application query/input objects."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        str_strip_whitespace=True,
+    )
+
+
+class PaginationQuery(QueryModel):
+    """Common pagination parameters."""
+
+    limit: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Maximum number of records to return.",
+    )
+
+    offset: int = Field(
+        default=0,
+        ge=0,
+        description="Number of records to skip.",
+    )
+
+
+class ScheduleType(StrEnum):
+    """Supported airport schedule types."""
+
+    ARRIVAL = "arrival"
+    DEPARTURE = "departure"
+
+
+class FlightSearchQuery(QueryModel):
+    """Parameters for searching live flights."""
+
+    airline_name: str | None = Field(
+        default=None,
+        description="Airline name, such as Delta Air Lines.",
+    )
+
+    airline_iata: str | None = Field(
+        default=None,
+        min_length=2,
+        max_length=3,
+        description="Airline IATA code, such as DL.",
+    )
+
+    flight_iata: str | None = Field(
+        default=None,
+        description="Flight IATA number, such as DL123.",
+    )
+
+    flight_icao: str | None = Field(
+        default=None,
+        description="Flight ICAO identifier.",
+    )
+
+    departure_iata: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=3,
+        description="Departure airport IATA code.",
+    )
+
+    arrival_iata: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=3,
+        description="Arrival airport IATA code.",
+    )
+
+    limit: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+    )
+
+    @field_validator(
+        "airline_iata",
+        "departure_iata",
+        "arrival_iata",
+        mode="before",
+    )
+    @classmethod
+    def normalize_iata_code(cls, value: str | None) -> str | None:
+        """Normalize IATA codes to uppercase."""
+
+        if value is None:
+            return None
+
+        return value.strip().upper()
+
+
+class HistoricalFlightQuery(QueryModel):
+    """Parameters for historical flight searches."""
+
+    flight_date: Date = Field(
+        description="Flight date in YYYY-MM-DD format.",
+    )
+
+    airline_iata: str | None = Field(
+        default=None,
+        min_length=2,
+        max_length=3,
+    )
+
+    departure_iata: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=3,
+    )
+
+    arrival_iata: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=3,
+    )
+
+    limit: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+    )
+
+    @field_validator(
+        "airline_iata",
+        "departure_iata",
+        "arrival_iata",
+        mode="before",
+    )
+    @classmethod
+    def normalize_iata_code(cls, value: str | None) -> str | None:
+        """Normalize IATA codes."""
+
+        if value is None:
+            return None
+
+        return value.strip().upper()
+
+
+class AirportScheduleQuery(QueryModel):
+    """Parameters for airport arrival/departure schedule queries."""
+
+    airport_iata: str = Field(
+        min_length=3,
+        max_length=3,
+        description="Airport IATA code.",
+    )
+
+    schedule_type: ScheduleType = Field(
+        description="Whether to retrieve arrival or departure schedules.",
+    )
+
+    airline_name: str | None = Field(
+        default=None,
+        description="Optional airline name filter.",
+    )
+
+    limit: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+    )
+
+    @field_validator("airport_iata", mode="before")
+    @classmethod
+    def normalize_airport_code(cls, value: str) -> str:
+        """Normalize airport IATA code."""
+
+        return value.strip().upper()
+
+
+class FutureScheduleQuery(QueryModel):
+    """Parameters for future airport schedule queries."""
+
+    airport_iata: str = Field(
+        min_length=3,
+        max_length=3,
+        description="Airport IATA code.",
+    )
+
+    schedule_type: ScheduleType
+
+    date: Date = Field(
+        description="Future schedule date.",
+    )
+
+    airline_iata: str | None = Field(
+        default=None,
+        min_length=2,
+        max_length=3,
+    )
+
+    limit: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+    )
+
+    @field_validator("airport_iata", mode="before")
+    @classmethod
+    def normalize_airport_code(cls, value: str) -> str:
+        return value.strip().upper()
+
+
+class AirportSearchQuery(PaginationQuery):
+    """Parameters for airport searches."""
+
+    search: str | None = Field(
+        default=None,
+        description="Airport name, city, or other search text.",
+    )
+
+
+class AirlineSearchQuery(PaginationQuery):
+    """Parameters for airline searches."""
+
+    search: str | None = Field(
+        default=None,
+        description="Airline search text.",
+    )
+
+
+class RouteSearchQuery(PaginationQuery):
+    """Parameters for route searches."""
+
+    airline_iata: str | None = Field(
+        default=None,
+        min_length=2,
+        max_length=3,
+    )
+
+    departure_iata: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=3,
+    )
+
+    arrival_iata: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=3,
+    )
+
+    @field_validator(
+        "airline_iata",
+        "departure_iata",
+        "arrival_iata",
+        mode="before",
+    )
+    @classmethod
+    def normalize_codes(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+
+        return value.strip().upper()
+
+
+class TaxSearchQuery(PaginationQuery):
+    """Parameters for tax searches."""
+
+    search: str | None = Field(
+        default=None,
+        description="Tax name or code search text.",
+    )
+
+
+class RecordLimitQuery(QueryModel):
+    """Query for bounded reference-data retrieval."""
+
+    limit: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+    )

aviationstack_mcp_server/models/route.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from aviationstack_mcp_server.models.common import AviationstackModel
+
+
+class Route(AviationstackModel):
+    """Airline route reference data."""
+
+    airline_iata: str | None = None
+    airline_icao: str | None = None
+    flight_number: str | None = None
+    dep_iata: str | None = None
+    dep_icao: str | None = None
+    arr_iata: str | None = None
+    arr_icao: str | None = None
+
+
+class RouteResponse(AviationstackModel):
+    """Response containing routes."""
+
+    pagination: dict | None = None
+    data: list[Route] = Field(default_factory=list)

aviationstack_mcp_server/models/tax.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from aviationstack_mcp_server.models.common import AviationstackModel
+
+
+class Tax(AviationstackModel):
+    """Aviation tax reference data."""
+
+    tax_id: str | None = None
+    tax_name: str | None = None
+    iata_code: str | None = None
+
+
+class TaxResponse(AviationstackModel):
+    """Response containing aviation taxes."""
+
+    pagination: dict | None = None
+    data: list[Tax] = Field(default_factory=list)

aviationstack_mcp_server/observability.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from uuid import uuid4
+
+correlation_id: ContextVar[str] = ContextVar(
+    "correlation_id",
+    default="",
+)
+
+
+def generate_correlation_id() -> str:
+    """Generate a correlation ID for an operation."""
+
+    return uuid4().hex
+
+
+def get_correlation_id() -> str:
+    """Return the current correlation ID."""
+
+    return correlation_id.get()
+
+
+def set_correlation_id(value: str) -> None:
+    """Set the current correlation ID."""
+
+    correlation_id.set(value)

aviationstack_mcp_server/security.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from aviationstack_mcp_server.errors import AviationstackConfigurationError
+
+SENSITIVE_KEYS = frozenset(
+    {
+        "access_key",
+        "api_key",
+        "apikey",
+        "authorization",
+        "token",
+        "password",
+        "secret",
+    }
+)
+
+
+def redact_mapping(
+    values: dict[str, object],
+) -> dict[str, object]:
+    """Return a copy with sensitive values redacted."""
+
+    return {
+        key: ("***REDACTED***" if key.lower() in SENSITIVE_KEYS else value)
+        for key, value in values.items()
+    }
+
+
+def validate_api_base_url(
+    base_url: str,
+    *,
+    environment: str,
+) -> None:
+    """Enforce secure, provider-specific API URL policy in production."""
+
+    parsed = urlparse(base_url)
+
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise AviationstackConfigurationError(
+            "API base URL must not contain credentials, query parameters, or fragments."
+        )
+
+    if environment == "production":
+        if parsed.scheme != "https":
+            raise AviationstackConfigurationError("Production API base URL must use HTTPS.")
+
+        if parsed.hostname != "api.aviationstack.com":
+            raise AviationstackConfigurationError(
+                "Production API base URL must use the Aviationstack API host."
+            )
+
+
+def validate_endpoint(endpoint: str) -> None:
+    """Reject endpoint inputs that could turn the client into a URL proxy."""
+
+    parsed = urlparse(endpoint)
+    if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment:
+        raise AviationstackConfigurationError(
+            "Aviationstack endpoints must be relative paths without query parameters."
+        )

aviationstack_mcp_server/services/__init__.py

@@ -0,0 +1,13 @@
+from .aircraft_service import AircraftService
+from .airline_service import AirlineService
+from .airport_service import AirportService
+from .flight_service import FlightService
+from .reference_service import ReferenceDataService
+
+__all__ = [
+    "AircraftService",
+    "AirlineService",
+    "AirportService",
+    "FlightService",
+    "ReferenceDataService",
+]