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

aviationstack_mcp_server/mcp/server.py

@@ -0,0 +1,164 @@
+import logging
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+
+from mcp.server import MCPServer
+
+from aviationstack_mcp_server.client.aviationstack import AviationstackClient
+from aviationstack_mcp_server.client.factory import create_aviationstack_client
+from aviationstack_mcp_server.config import get_settings
+from aviationstack_mcp_server.mcp.dependencies import (
+    AppContext,
+    build_app_context,
+)
+from aviationstack_mcp_server.mcp.prompts.aviation import (
+    register_aviation_prompts,
+)
+from aviationstack_mcp_server.mcp.resources.documentation import (
+    register_documentation_resources,
+)
+from aviationstack_mcp_server.mcp.resources.metadata import (
+    register_metadata_resources,
+)
+from aviationstack_mcp_server.mcp.tools.aircraft import register_aircraft_tools
+from aviationstack_mcp_server.mcp.tools.airlines import register_airline_tools
+from aviationstack_mcp_server.mcp.tools.airports import register_airport_tools
+from aviationstack_mcp_server.mcp.tools.flights import register_flight_tools
+from aviationstack_mcp_server.mcp.tools.reference import register_reference_tools
+
+logger = logging.getLogger(__name__)
+
+ClientFactory = Callable[[], AviationstackClient]
+
+
+def default_client_factory() -> AviationstackClient:
+    """Create the production Aviationstack client from application settings."""
+
+    settings = get_settings()
+    return create_aviationstack_client(settings)
+
+
+def create_lifespan(
+    client_factory: ClientFactory = default_client_factory,
+):
+    """Create the application lifespan with an injectable client factory."""
+
+    @asynccontextmanager
+    async def lifespan(
+        server: MCPServer[AppContext],
+    ) -> AsyncIterator[AppContext]:
+        logger.info("Starting Aviationstack MCP application lifespan")
+        client = client_factory()
+
+        try:
+            logger.info("Aviationstack API client initialized")
+
+            app_context = build_app_context(client)
+            logger.info("Aviationstack application context ready")
+
+            yield app_context
+        finally:
+            logger.info("Shutting down Aviationstack MCP application lifespan")
+            try:
+                await client.close()
+            except Exception:
+                logger.exception("Failed to close Aviationstack API client")
+                raise
+            else:
+                logger.info("Aviationstack API client closed")
+
+    return lifespan
+
+
+def create_server(
+    client_factory: ClientFactory = default_client_factory,
+) -> MCPServer[AppContext]:
+    """Create and configure the Aviationstack MCP server."""
+
+    logger.debug("Creating Aviationstack MCP server")
+    server = MCPServer(
+        "aviationstack-mcp",
+        lifespan=create_lifespan(client_factory),
+    )
+
+    # Tools
+    register_flight_tools(server)
+    register_airport_tools(server)
+    register_airline_tools(server)
+    register_aircraft_tools(server)
+    register_reference_tools(server)
+
+    # Prompts
+    register_aviation_prompts(server)
+
+    # Resources
+    register_metadata_resources(server)
+    register_documentation_resources(server)
+
+    logger.info("Aviationstack MCP server configured")
+    return server
+
+
+# from collections.abc import AsyncIterator
+# from contextlib import asynccontextmanager
+
+# from mcp.server import MCPServer
+
+# from aviationstack_mcp_server.client.factory import create_aviationstack_client
+# from aviationstack_mcp_server.config import get_settings
+# from aviationstack_mcp_server.mcp.dependencies import AppContext, build_app_context
+# from aviationstack_mcp_server.mcp.prompts.aviation import (
+#     register_aviation_prompts,
+# )
+# from aviationstack_mcp_server.mcp.resources.documentation import (
+#     register_documentation_resources,
+# )
+# from aviationstack_mcp_server.mcp.resources.metadata import (
+#     register_metadata_resources,
+# )
+# from aviationstack_mcp_server.mcp.tools.aircraft import register_aircraft_tools
+# from aviationstack_mcp_server.mcp.tools.airlines import register_airline_tools
+# from aviationstack_mcp_server.mcp.tools.airports import register_airport_tools
+# from aviationstack_mcp_server.mcp.tools.flights import register_flight_tools
+# from aviationstack_mcp_server.mcp.tools.reference import register_reference_tools
+
+
+# @asynccontextmanager
+# async def app_lifespan(
+#     server: MCPServer[AppContext],
+# ) -> AsyncIterator[AppContext]:
+#     """Initialize and clean up application-wide dependencies."""
+
+#     settings = get_settings()
+#     client = create_aviationstack_client(settings)
+
+#     try:
+#         app_context = build_app_context(client)
+
+#         yield app_context
+
+#     finally:
+#         await client.close()
+
+
+# def create_server() -> MCPServer[AppContext]:
+#     """Create and configure the Aviationstack MCP server."""
+
+#     server = MCPServer(
+#         "aviationstack-mcp",
+#         lifespan=app_lifespan,
+#     )
+
+#     register_flight_tools(server)
+#     register_airport_tools(server)
+#     register_airline_tools(server)
+#     register_aircraft_tools(server)
+#     register_reference_tools(server)
+
+#     register_aviation_prompts(server)
+
+#     # Resources
+#     register_metadata_resources(server)
+#     register_documentation_resources(server)
+
+#     return server

aviationstack_mcp_server/mcp/tools/aircraft.py

@@ -0,0 +1,64 @@
+import logging
+
+from mcp.server.mcpserver import Context
+
+from aviationstack_mcp_server.mcp.dependencies import AppContext
+from aviationstack_mcp_server.mcp.errors import mcp_error_boundary
+from aviationstack_mcp_server.models.queries import RecordLimitQuery
+
+logger = logging.getLogger(__name__)
+
+
+def register_aircraft_tools(server) -> None:
+    """Register aircraft-related MCP tools."""
+
+    @server.tool(
+        name="list_aircraft_types",
+        title="List Aircraft Types",
+        description=(
+            "List aircraft type records available from Aviationstack. "
+            "Use the limit parameter to control the number of records."
+        ),
+    )
+    @mcp_error_boundary
+    async def list_aircraft_types(
+        query: RecordLimitQuery,
+        ctx: Context[AppContext],
+    ):
+        """List aircraft type records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info("MCP tool called: list_aircraft_types limit=%s", query.limit)
+        records = await app.services.aircraft.list_aircraft_types(query)
+        logger.debug(
+            "MCP tool completed: list_aircraft_types returned=%s",
+            len(records),
+        )
+
+        return records
+
+    @server.tool(
+        name="list_airplanes",
+        title="List Airplanes",
+        description=(
+            "List individual airplane records available from "
+            "Aviationstack. Use the limit parameter to control "
+            "the number of records."
+        ),
+    )
+    @mcp_error_boundary
+    async def list_airplanes(
+        query: RecordLimitQuery,
+        ctx: Context[AppContext],
+    ):
+        """List individual airplane records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info("MCP tool called: list_airplanes limit=%s", query.limit)
+        records = await app.services.aircraft.list_airplanes(query)
+        logger.debug(
+            "MCP tool completed: list_airplanes returned=%s",
+            len(records),
+        )
+
+        return records

aviationstack_mcp_server/mcp/tools/airlines.py

@@ -0,0 +1,43 @@
+import logging
+
+from mcp.server.mcpserver import Context
+
+from aviationstack_mcp_server.mcp.dependencies import AppContext
+from aviationstack_mcp_server.mcp.errors import mcp_error_boundary
+from aviationstack_mcp_server.models.queries import AirlineSearchQuery
+
+logger = logging.getLogger(__name__)
+
+
+def register_airline_tools(server) -> None:
+    """Register airline-related MCP tools."""
+
+    @server.tool(
+        name="search_airlines",
+        title="Search Airlines",
+        description=(
+            "Search airline records using airline name, IATA code, "
+            "ICAO code, or other supported airline search criteria."
+        ),
+    )
+    @mcp_error_boundary
+    async def search_airlines(
+        query: AirlineSearchQuery,
+        ctx: Context[AppContext],
+    ):
+        """Search airline records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info(
+            "MCP tool called: search_airlines limit=%s offset=%s search_provided=%s",
+            query.limit,
+            query.offset,
+            query.search is not None,
+        )
+        records = await app.services.airline.search_airlines(query)
+        logger.debug(
+            "MCP tool completed: search_airlines returned=%s",
+            len(records),
+        )
+
+        return records

aviationstack_mcp_server/mcp/tools/airports.py

@@ -0,0 +1,43 @@
+import logging
+
+from mcp.server.mcpserver import Context
+
+from aviationstack_mcp_server.mcp.dependencies import AppContext
+from aviationstack_mcp_server.mcp.errors import mcp_error_boundary
+from aviationstack_mcp_server.models.queries import AirportSearchQuery
+
+logger = logging.getLogger(__name__)
+
+
+def register_airport_tools(server) -> None:
+    """Register airport-related MCP tools."""
+
+    @server.tool(
+        name="search_airports",
+        title="Search Airports",
+        description=(
+            "Search airports by airport name, IATA code, ICAO code, "
+            "city, or other supported airport search criteria."
+        ),
+    )
+    @mcp_error_boundary
+    async def search_airports(
+        query: AirportSearchQuery,
+        ctx: Context[AppContext],
+    ):
+        """Search airport records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info(
+            "MCP tool called: search_airports limit=%s offset=%s search_provided=%s",
+            query.limit,
+            query.offset,
+            query.search is not None,
+        )
+        records = await app.services.airport.search_airports(query)
+        logger.debug(
+            "MCP tool completed: search_airports returned=%s",
+            len(records),
+        )
+
+        return records

aviationstack_mcp_server/mcp/tools/flights.py

@@ -0,0 +1,125 @@
+import logging
+
+from mcp.server.mcpserver import Context
+
+from aviationstack_mcp_server.mcp.dependencies import AppContext
+from aviationstack_mcp_server.mcp.errors import mcp_error_boundary
+from aviationstack_mcp_server.models.queries import (
+    AirportScheduleQuery,
+    FlightSearchQuery,
+    HistoricalFlightQuery,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def register_flight_tools(
+    server,
+) -> None:
+    """Register flight-related MCP tools."""
+
+    @server.tool(
+        name="search_flights",
+        title="Search Flights",
+        description=(
+            "Search flights using airline, flight number, departure, "
+            "arrival, date, and pagination filters."
+        ),
+    )
+    @mcp_error_boundary
+    async def search_flights(
+        query: FlightSearchQuery,
+        ctx: Context[AppContext],
+    ):
+        """Search scheduled flight records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info(
+            "MCP tool called: search_flights limit=%s filters=%s",
+            query.limit,
+            [
+                field
+                for field in (
+                    "airline_name",
+                    "airline_iata",
+                    "flight_iata",
+                    "flight_icao",
+                    "departure_iata",
+                    "arrival_iata",
+                )
+                if getattr(query, field) is not None
+            ],
+        )
+        records = await app.services.flight.search_flights(query)
+        logger.debug(
+            "MCP tool completed: search_flights returned=%s",
+            len(records),
+        )
+
+        return records
+
+    @server.tool(
+        name="search_historical_flights",
+        title="Search Historical Flights",
+        description=(
+            "Search historical flight records for a specific date "
+            "using optional airline, flight number, departure, "
+            "arrival, and pagination filters."
+        ),
+    )
+    @mcp_error_boundary
+    async def search_historical_flights(
+        query: HistoricalFlightQuery,
+        ctx: Context[AppContext],
+    ):
+        """Search historical flight records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info(
+            "MCP tool called: search_historical_flights date=%s limit=%s filters=%s",
+            query.flight_date,
+            query.limit,
+            [
+                field
+                for field in ("airline_iata", "departure_iata", "arrival_iata")
+                if getattr(query, field) is not None
+            ],
+        )
+        records = await app.services.flight.get_historical_flights(query)
+        logger.debug(
+            "MCP tool completed: search_historical_flights returned=%s",
+            len(records),
+        )
+
+        return records
+
+    @server.tool(
+        name="get_flight_schedule",
+        title="Get Flight Schedule",
+        description=(
+            "Retrieve airport arrival or departure schedules using "
+            "an airport IATA code and schedule filters."
+        ),
+    )
+    @mcp_error_boundary
+    async def get_flight_schedule(
+        query: AirportScheduleQuery,
+        ctx: Context[AppContext],
+    ):
+        """Retrieve airport flight schedules."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info(
+            "MCP tool called: get_flight_schedule airport=%s type=%s airline_filter=%s limit=%s",
+            query.airport_iata,
+            query.schedule_type.value,
+            query.airline_name is not None,
+            query.limit,
+        )
+        records = await app.services.flight.get_airport_schedule(query)
+        logger.debug(
+            "MCP tool completed: get_flight_schedule returned=%s",
+            len(records),
+        )
+
+        return records

aviationstack_mcp_server/mcp/tools/reference.py

@@ -0,0 +1,129 @@
+import logging
+
+from mcp.server.mcpserver import Context
+
+from aviationstack_mcp_server.mcp.dependencies import AppContext
+from aviationstack_mcp_server.mcp.errors import mcp_error_boundary
+from aviationstack_mcp_server.models.queries import (
+    RecordLimitQuery,
+    RouteSearchQuery,
+    TaxSearchQuery,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def register_reference_tools(server) -> None:
+    """Register reference-data MCP tools."""
+
+    @server.tool(
+        name="list_countries",
+        title="List Countries",
+        description=(
+            "List country records available from Aviationstack. "
+            "Use the limit parameter to control the number of records."
+        ),
+    )
+    @mcp_error_boundary
+    async def list_countries(
+        query: RecordLimitQuery,
+        ctx: Context[AppContext],
+    ):
+        """List country reference records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info("MCP tool called: list_countries limit=%s", query.limit)
+        records = await app.services.reference.list_countries(query)
+        logger.debug(
+            "MCP tool completed: list_countries returned=%s",
+            len(records),
+        )
+
+        return records
+
+    @server.tool(
+        name="list_cities",
+        title="List Cities",
+        description=(
+            "List city records available from Aviationstack. "
+            "Use the limit parameter to control the number of records."
+        ),
+    )
+    @mcp_error_boundary
+    async def list_cities(
+        query: RecordLimitQuery,
+        ctx: Context[AppContext],
+    ):
+        """List city reference records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info("MCP tool called: list_cities limit=%s", query.limit)
+        records = await app.services.reference.list_cities(query)
+        logger.debug(
+            "MCP tool completed: list_cities returned=%s",
+            len(records),
+        )
+
+        return records
+
+    @server.tool(
+        name="search_routes",
+        title="Search Routes",
+        description=(
+            "Search airline route records using supported route "
+            "filters such as airline, departure airport, arrival "
+            "airport, and pagination."
+        ),
+    )
+    @mcp_error_boundary
+    async def search_routes(
+        query: RouteSearchQuery,
+        ctx: Context[AppContext],
+    ):
+        """Search route records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info(
+            "MCP tool called: search_routes limit=%s offset=%s filters=%s",
+            query.limit,
+            query.offset,
+            [
+                field
+                for field in ("airline_iata", "departure_iata", "arrival_iata")
+                if getattr(query, field) is not None
+            ],
+        )
+        records = await app.services.reference.search_routes(query)
+        logger.debug(
+            "MCP tool completed: search_routes returned=%s",
+            len(records),
+        )
+
+        return records
+
+    @server.tool(
+        name="search_taxes",
+        title="Search Taxes",
+        description=("Search aviation tax records using supported tax filters and pagination."),
+    )
+    @mcp_error_boundary
+    async def search_taxes(
+        query: TaxSearchQuery,
+        ctx: Context[AppContext],
+    ):
+        """Search tax records."""
+
+        app = ctx.request_context.lifespan_context
+        logger.info(
+            "MCP tool called: search_taxes limit=%s offset=%s search_provided=%s",
+            query.limit,
+            query.offset,
+            query.search is not None,
+        )
+        records = await app.services.reference.search_taxes(query)
+        logger.debug(
+            "MCP tool completed: search_taxes returned=%s",
+            len(records),
+        )
+
+        return records

aviationstack_mcp_server/models/__init__.py

@@ -0,0 +1,81 @@
+from .aircraft import (
+    AircraftType,
+    AircraftTypeResponse,
+    Airplane,
+    AirplaneResponse,
+)
+from .airline import Airline, AirlineResponse
+from .airport import Airport, AirportResponse
+from .common import AviationstackModel, AviationstackResponse
+from .flight import (
+    AirlineReference,
+    AirportReference,
+    Flight,
+    FlightAircraftReference,
+    FlightIdentifier,
+    FlightResponse,
+    ScheduleFlight,
+    ScheduleFlightIdentifier,
+    ScheduleResponse,
+    ScheduleTimeReference,
+)
+from .location import City, CityResponse, Country, CountryResponse
+from .queries import (
+    AirlineSearchQuery,
+    AirportScheduleQuery,
+    AirportSearchQuery,
+    FlightSearchQuery,
+    FutureScheduleQuery,
+    HistoricalFlightQuery,
+    PaginationQuery,
+    QueryModel,
+    RecordLimitQuery,
+    RouteSearchQuery,
+    ScheduleType,
+    TaxSearchQuery,
+)
+from .route import Route, RouteResponse
+from .tax import Tax, TaxResponse
+
+__all__ = [
+    "AircraftType",
+    "AircraftTypeResponse",
+    "Airline",
+    "AirlineReference",
+    "AirlineResponse",
+    "Airport",
+    "AirportReference",
+    "AirportResponse",
+    "AviationstackModel",
+    "AviationstackResponse",
+    "Airplane",
+    "AirplaneResponse",
+    "City",
+    "CityResponse",
+    "Country",
+    "CountryResponse",
+    "Flight",
+    "FlightAircraftReference",
+    "FlightIdentifier",
+    "FlightResponse",
+    "Route",
+    "RouteResponse",
+    "ScheduleFlight",
+    "ScheduleFlightIdentifier",
+    "ScheduleResponse",
+    "ScheduleTimeReference",
+    "Tax",
+    "TaxResponse",
+    "AirlineSearchQuery",
+    "AirportScheduleQuery",
+    "AirportSearchQuery",
+    "FlightSearchQuery",
+    "FutureScheduleQuery",
+    "HistoricalFlightQuery",
+    "PaginationQuery",
+    "QueryModel",
+    "RecordLimitQuery",
+    "RouteSearchQuery",
+    "ScheduleType",
+    "TaxSearchQuery",
+]

aviationstack_mcp_server/models/aircraft.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from aviationstack_mcp_server.models.common import AviationstackModel
+
+
+class AircraftType(AviationstackModel):
+    """Aircraft type reference data."""
+
+    aircraft_name: str | None = None
+    iata_code: str | None = None
+    icao_code: str | None = None
+
+
+class AircraftTypeResponse(AviationstackModel):
+    """Response containing aircraft types."""
+
+    pagination: dict | None = None
+    data: list[AircraftType] = Field(default_factory=list)
+
+
+class Airplane(AviationstackModel):
+    """Detailed airplane information."""
+
+    production_line: str | None = None
+    plane_owner: str | None = None
+    plane_age: int | float | None = None
+    model_name: str | None = None
+    model_code: str | None = None
+    plane_series: str | None = None
+    registration_number: str | None = None
+    engines_type: str | None = None
+    engines_count: int | None = None
+    delivery_date: str | None = None
+    first_flight_date: str | None = None
+
+
+class AirplaneResponse(AviationstackModel):
+    """Response containing airplane records."""
+
+    pagination: dict | None = None
+    data: list[Airplane] = Field(default_factory=list)