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

aviationstack_mcp_server/errors/exceptions.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+
+class AviationstackError(Exception):
+    """Base exception for all Aviationstack application errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class AviationstackConfigurationError(AviationstackError):
+    """Raised when the Aviationstack client is incorrectly configured."""
+
+
+class AviationstackRequestError(AviationstackError):
+    """Raised when an HTTP request to Aviationstack fails."""
+
+
+class AviationstackAuthenticationError(AviationstackRequestError):
+    """Raised when Aviationstack rejects the API credentials."""
+
+
+class AviationstackAuthorizationError(AviationstackRequestError):
+    """Raised when the configured plan does not permit an operation."""
+
+
+class AviationstackRateLimitError(AviationstackRequestError):
+    """Raised when the Aviationstack API rate limit is exceeded."""
+
+
+class AviationstackNotFoundError(AviationstackRequestError):
+    """Raised when the requested Aviationstack resource is unavailable."""
+
+
+class AviationstackServerError(AviationstackRequestError):
+    """Raised when Aviationstack returns a server-side error."""
+
+
+class AviationstackTimeoutError(AviationstackRequestError):
+    """Raised when an Aviationstack request times out."""
+
+
+class AviationstackAPIError(AviationstackRequestError):
+    """Raised when Aviationstack returns an application-level API error."""

aviationstack_mcp_server/logging_config.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from aviationstack_mcp_server.observability import get_correlation_id
+
+DEFAULT_LOG_FORMAT: Final = (
+    "%(asctime)s | %(levelname)s | correlation_id=%(correlation_id)s | %(name)s | %(message)s"
+)
+
+LOGGER_NAME: Final = "aviationstack_mcp_server"
+
+
+class CorrelationIdFilter(logging.Filter):
+    """Add the current correlation ID to every log record."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.correlation_id = get_correlation_id() or "-"
+        return True
+
+
+def configure_logging(level: str) -> None:
+    """Configure application-wide logging.
+
+    This function is intentionally idempotent so it can safely be called
+    during application startup without creating duplicate handlers.
+    """
+
+    numeric_level = getattr(logging, level.upper(), None)
+
+    if not isinstance(numeric_level, int):
+        raise ValueError(f"Invalid log level: {level}")
+
+    root_logger = logging.getLogger()
+
+    root_logger.setLevel(numeric_level)
+
+    if not root_logger.handlers:
+        new_handler = logging.StreamHandler()
+        new_handler.setLevel(numeric_level)
+        new_handler.addFilter(CorrelationIdFilter())
+
+        formatter = logging.Formatter(DEFAULT_LOG_FORMAT)
+        new_handler.setFormatter(formatter)
+
+        root_logger.addHandler(new_handler)
+    else:
+        for handler in root_logger.handlers:
+            handler.setLevel(numeric_level)
+
+    logging.getLogger(LOGGER_NAME).setLevel(numeric_level)

aviationstack_mcp_server/mcp/__init__.py

@@ -0,0 +1,3 @@
+from aviationstack_mcp_server.mcp.server import create_server
+
+__all__ = ["create_server"]

aviationstack_mcp_server/mcp/dependencies.py

@@ -0,0 +1,64 @@
+import logging
+from dataclasses import dataclass
+
+from aviationstack_mcp_server.client.aviationstack import AviationstackClient
+from aviationstack_mcp_server.services.aircraft_service import AircraftService
+from aviationstack_mcp_server.services.airline_service import AirlineService
+from aviationstack_mcp_server.services.airport_service import AirportService
+from aviationstack_mcp_server.services.flight_service import FlightService
+from aviationstack_mcp_server.services.reference_service import ReferenceDataService
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceContainer:
+    """Application-level collection of domain services."""
+
+    flight: FlightService
+    airport: AirportService
+    airline: AirlineService
+    aircraft: AircraftService
+    reference: ReferenceDataService
+
+
+@dataclass(frozen=True, slots=True)
+class AppContext:
+    """Application dependencies shared across MCP requests."""
+
+    client: AviationstackClient
+    services: ServiceContainer
+
+
+def build_services(
+    client: AviationstackClient,
+) -> ServiceContainer:
+    """Build all domain services using a shared API client."""
+
+    services = ServiceContainer(
+        flight=FlightService(client),
+        airport=AirportService(client),
+        airline=AirlineService(client),
+        aircraft=AircraftService(client),
+        reference=ReferenceDataService(client),
+    )
+    logger.debug(
+        "Application services built: names=%s",
+        ("flight", "airport", "airline", "aircraft", "reference"),
+    )
+
+    return services
+
+
+def build_app_context(
+    client: AviationstackClient,
+) -> AppContext:
+    """Build the application dependency container."""
+
+    services = build_services(client)
+    logger.debug("Application dependency context built")
+
+    return AppContext(
+        client=client,
+        services=services,
+    )

aviationstack_mcp_server/mcp/errors.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from time import perf_counter
+from typing import Any
+
+from mcp.types import CallToolResult, TextContent
+
+from aviationstack_mcp_server.errors import (
+    AviationstackAPIError,
+    AviationstackAuthenticationError,
+    AviationstackAuthorizationError,
+    AviationstackConfigurationError,
+    AviationstackError,
+    AviationstackNotFoundError,
+    AviationstackRateLimitError,
+    AviationstackRequestError,
+    AviationstackServerError,
+    AviationstackTimeoutError,
+)
+from aviationstack_mcp_server.observability import (
+    generate_correlation_id,
+    set_correlation_id,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def translate_aviationstack_error(error: AviationstackError) -> str:
+    """Convert an internal exception into a safe MCP-facing message."""
+
+    if isinstance(error, AviationstackConfigurationError):
+        return "Server configuration is invalid."
+
+    if isinstance(error, AviationstackAuthenticationError):
+        return "Aviationstack authentication failed."
+
+    if isinstance(error, AviationstackAuthorizationError):
+        return "Aviationstack authorization failed."
+
+    if isinstance(error, AviationstackRateLimitError):
+        return "Aviationstack rate limit exceeded."
+
+    if isinstance(error, AviationstackNotFoundError):
+        return "The requested Aviationstack resource was not found."
+
+    if isinstance(error, AviationstackTimeoutError):
+        return "The Aviationstack request timed out."
+
+    if isinstance(error, AviationstackServerError):
+        return "The Aviationstack service is temporarily unavailable."
+
+    if isinstance(error, AviationstackAPIError):
+        return "The Aviationstack API rejected the request."
+
+    if isinstance(error, AviationstackRequestError):
+        return "Unable to reach the Aviationstack API."
+
+    return "An Aviationstack error occurred."
+
+
+def mcp_error_message(error: AviationstackError) -> str:
+    """Return the safe MCP-facing message for an Aviationstack error."""
+
+    return translate_aviationstack_error(error)
+
+
+def mcp_error_boundary[T](
+    func: Callable[..., Awaitable[T]],
+) -> Callable[..., Awaitable[T | CallToolResult]]:
+    """Convert tool failures into safe MCP-facing errors."""
+
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> T | CallToolResult:
+        tool_name = func.__name__
+        correlation = generate_correlation_id()
+        set_correlation_id(correlation)
+        started_at = perf_counter()
+        logger.info("MCP tool started tool=%s", tool_name)
+
+        try:
+            result = await func(*args, **kwargs)
+            duration_ms = (perf_counter() - started_at) * 1000
+            logger.info(
+                "MCP tool completed tool=%s duration_ms=%.2f",
+                tool_name,
+                duration_ms,
+            )
+            return result
+        except AviationstackError as exc:
+            duration_ms = (perf_counter() - started_at) * 1000
+            logger.error(
+                "MCP tool failed tool=%s duration_ms=%.2f error_type=%s",
+                tool_name,
+                duration_ms,
+                type(exc).__name__,
+            )
+            return CallToolResult(
+                content=[TextContent(text=translate_aviationstack_error(exc))],
+                is_error=True,
+            )
+        except Exception:
+            duration_ms = (perf_counter() - started_at) * 1000
+            logger.exception(
+                "Unexpected MCP tool failure tool=%s duration_ms=%.2f",
+                tool_name,
+                duration_ms,
+            )
+            return CallToolResult(
+                content=[TextContent(text="Internal server error.")],
+                is_error=True,
+            )
+        finally:
+            set_correlation_id("")
+
+    return wrapper

aviationstack_mcp_server/mcp/prompts/aviation.py

@@ -0,0 +1,98 @@
+import logging
+
+from mcp.server.mcpserver import MCPServer
+
+logger = logging.getLogger(__name__)
+
+
+def register_aviation_prompts(server: MCPServer) -> None:
+    """Register Aviationstack MCP prompts."""
+
+    logger.debug("Registering Aviationstack MCP prompts")
+
+    @server.prompt(
+        name="plan_flight_search",
+        title="Plan Flight Search",
+        description=(
+            "Help formulate a flight search using available Aviationstack flight filters."
+        ),
+    )
+    def plan_flight_search(
+        request: str,
+    ) -> str:
+        """Generate guidance for searching flights."""
+
+        prompt = (
+            "Plan a flight search using the Aviationstack MCP server.\n\n"
+            f"User request:\n{request}\n\n"
+            "Determine the relevant flight filters such as airline, "
+            "flight number, departure airport, arrival airport, "
+            "and date. Then use the search_flights tool with the "
+            "appropriate structured query."
+        )
+        logger.debug(
+            "Generated prompt: plan_flight_search request_length=%s prompt_length=%s",
+            len(request),
+            len(prompt),
+        )
+        return prompt
+
+    @server.prompt(
+        name="plan_schedule_search",
+        title="Plan Schedule Search",
+        description=("Help formulate an airport arrival or departure schedule search."),
+    )
+    def plan_schedule_search(
+        airport: str,
+        schedule_type: str = "departure",
+    ) -> str:
+        """Generate guidance for an airport schedule search."""
+
+        prompt = (
+            "Plan an Aviationstack airport schedule lookup.\n\n"
+            f"Airport: {airport}\n"
+            f"Schedule type: {schedule_type}\n\n"
+            "Use the get_flight_schedule tool. Ensure the airport "
+            "identifier and schedule type are mapped to the "
+            "corresponding structured query fields. Return the "
+            "schedule information relevant to the user's request."
+        )
+        logger.debug(
+            "Generated prompt: plan_schedule_search airport=%s schedule_type=%s prompt_length=%s",
+            airport,
+            schedule_type,
+            len(prompt),
+        )
+        return prompt
+
+    @server.prompt(
+        name="plan_reference_data_search",
+        title="Plan Reference Data Search",
+        description=(
+            "Help determine which Aviationstack reference-data tool should be used for a lookup."
+        ),
+    )
+    def plan_reference_data_search(
+        request: str,
+    ) -> str:
+        """Generate guidance for reference-data lookup."""
+
+        prompt = (
+            "Plan a reference-data lookup using the "
+            "Aviationstack MCP server.\n\n"
+            f"User request:\n{request}\n\n"
+            "Choose the appropriate reference-data capability:\n"
+            "- list_countries for country reference data\n"
+            "- list_cities for city reference data\n"
+            "- search_routes for airline route data\n"
+            "- search_taxes for aviation tax data\n"
+            "- list_aircraft_types for aircraft type data\n"
+            "- list_airplanes for individual airplane records\n\n"
+            "Use the selected tool with its structured query."
+        )
+        logger.debug(
+            "Generated prompt: plan_reference_data_search request_length=%s prompt_length=%s",
+            len(request),
+            len(prompt),
+        )
+        return prompt

aviationstack_mcp_server/mcp/resources/documentation.py

@@ -0,0 +1,165 @@
+import logging
+
+from mcp.server.mcpserver import MCPServer
+
+logger = logging.getLogger(__name__)
+
+
+def register_documentation_resources(server: MCPServer) -> None:
+    """Register MCP documentation resources."""
+
+    logger.debug("Registering Aviationstack documentation resources")
+
+    @server.resource(
+        "aviationstack://metadata/endpoints",
+        name="aviationstack_endpoints",
+        title="Aviationstack API Endpoints",
+        description=(
+            "Public documentation of the Aviationstack API domains used by this MCP server."
+        ),
+        mime_type="application/json",
+    )
+    def aviationstack_endpoints() -> dict[str, object]:
+        """Return public endpoint documentation."""
+
+        logger.debug("Reading documentation resource: aviationstack://metadata/endpoints")
+        return {
+            "flights": {
+                "endpoint": "/flights",
+                "operations": [
+                    "search_flights",
+                    "search_historical_flights",
+                ],
+            },
+            "schedule": {
+                "endpoint": "/timetable",
+                "operations": [
+                    "get_flight_schedule",
+                ],
+            },
+            "future_schedule": {
+                "endpoint": "/flightsFuture",
+                "operations": [
+                    "get_flight_schedule",
+                ],
+            },
+            "aircraft_types": {
+                "endpoint": "/aircraft_types",
+                "operations": [
+                    "list_aircraft_types",
+                ],
+            },
+            "airplanes": {
+                "endpoint": "/airplanes",
+                "operations": [
+                    "list_airplanes",
+                ],
+            },
+            "countries": {
+                "endpoint": "/countries",
+                "operations": [
+                    "list_countries",
+                ],
+            },
+            "cities": {
+                "endpoint": "/cities",
+                "operations": [
+                    "list_cities",
+                ],
+            },
+            "airports": {
+                "endpoint": "/airports",
+                "operations": [
+                    "search_airports",
+                ],
+            },
+            "airlines": {
+                "endpoint": "/airlines",
+                "operations": [
+                    "search_airlines",
+                ],
+            },
+            "routes": {
+                "endpoint": "/routes",
+                "operations": [
+                    "search_routes",
+                ],
+            },
+            "taxes": {
+                "endpoint": "/taxes",
+                "operations": [
+                    "search_taxes",
+                ],
+            },
+        }
+
+    @server.resource(
+        "aviationstack://documentation/tools",
+        name="tool_documentation",
+        title="Aviationstack MCP Tools",
+        description=("Documentation of the tools exposed by the Aviationstack MCP server."),
+        mime_type="application/json",
+    )
+    def tool_documentation() -> dict[str, object]:
+        """Return public MCP tool documentation."""
+
+        logger.debug("Reading documentation resource: aviationstack://documentation/tools")
+        return {
+            "tools": [
+                {
+                    "name": "search_flights",
+                    "domain": "flights",
+                    "purpose": "Search flight records.",
+                },
+                {
+                    "name": "search_historical_flights",
+                    "domain": "flights",
+                    "purpose": "Search historical flight records.",
+                },
+                {
+                    "name": "get_flight_schedule",
+                    "domain": "flights",
+                    "purpose": "Retrieve airport flight schedules.",
+                },
+                {
+                    "name": "search_airports",
+                    "domain": "airports",
+                    "purpose": "Search airport records.",
+                },
+                {
+                    "name": "search_airlines",
+                    "domain": "airlines",
+                    "purpose": "Search airline records.",
+                },
+                {
+                    "name": "list_aircraft_types",
+                    "domain": "aircraft",
+                    "purpose": "List aircraft type records.",
+                },
+                {
+                    "name": "list_airplanes",
+                    "domain": "aircraft",
+                    "purpose": "List airplane records.",
+                },
+                {
+                    "name": "list_countries",
+                    "domain": "reference_data",
+                    "purpose": "List country records.",
+                },
+                {
+                    "name": "list_cities",
+                    "domain": "reference_data",
+                    "purpose": "List city records.",
+                },
+                {
+                    "name": "search_routes",
+                    "domain": "reference_data",
+                    "purpose": "Search route records.",
+                },
+                {
+                    "name": "search_taxes",
+                    "domain": "reference_data",
+                    "purpose": "Search aviation tax records.",
+                },
+            ]
+        }

aviationstack_mcp_server/mcp/resources/metadata.py

@@ -0,0 +1,46 @@
+import logging
+
+from mcp.server.mcpserver import MCPServer
+
+logger = logging.getLogger(__name__)
+
+
+def register_metadata_resources(server: MCPServer) -> None:
+    """Register server metadata resources."""
+
+    logger.debug("Registering Aviationstack server metadata resource")
+
+    @server.resource(
+        "aviationstack://metadata/server",
+        name="server_metadata",
+        title="Aviationstack MCP Server Metadata",
+        description=(
+            "Metadata describing the Aviationstack MCP server, "
+            "its capabilities, and supported MCP primitives."
+        ),
+        mime_type="application/json",
+    )
+    def server_metadata() -> dict[str, object]:
+        """Return public server metadata."""
+
+        logger.debug("Reading metadata resource: aviationstack://metadata/server")
+        return {
+            "name": "aviationstack-mcp",
+            "project": "aviationstack_mcp_server",
+            "description": (
+                "MCP server providing structured access to "
+                "Aviationstack flight and aviation reference data."
+            ),
+            "capabilities": {
+                "tools": True,
+                "prompts": True,
+                "resources": True,
+            },
+            "domains": [
+                "flights",
+                "airports",
+                "airlines",
+                "aircraft",
+                "reference_data",
+            ],
+        }