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

aviationstack_mcp_server/__main__.py

@@ -0,0 +1,15 @@
+from aviationstack_mcp_server.config import get_settings
+from aviationstack_mcp_server.logging_config import configure_logging
+from aviationstack_mcp_server.mcp.server import create_server
+
+
+def main() -> None:
+    settings = get_settings()
+    configure_logging(settings.log_level)
+
+    server = create_server()
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

aviationstack_mcp_server/client/__init__.py

@@ -0,0 +1,9 @@
+from .aviationstack import AviationstackClient
+from .factory import create_aviationstack_client
+from .http import HTTPClient
+
+__all__ = [
+    "AviationstackClient",
+    "HTTPClient",
+    "create_aviationstack_client",
+]

aviationstack_mcp_server/client/aviationstack.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from aviationstack_mcp_server.client.http import HTTPClient
+from aviationstack_mcp_server.config import Settings
+from aviationstack_mcp_server.errors import (
+    AviationstackAPIError,
+)
+from aviationstack_mcp_server.security import validate_endpoint
+
+logger = logging.getLogger(__name__)
+
+
+class AviationstackClient:
+    """Asynchronous client for the Aviationstack REST API."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        http_client: HTTPClient,
+    ) -> None:
+        self._settings = settings
+        self._http_client = http_client
+
+    async def get(
+        self,
+        endpoint: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Perform a GET request against an Aviationstack endpoint."""
+
+        url = self._build_url(endpoint)
+
+        request_params = {
+            "access_key": self._settings.aviationstack_api_key.get_secret_value(),
+        }
+
+        if params:
+            request_params.update(
+                {key: value for key, value in params.items() if value is not None}
+            )
+
+        logger.debug(
+            "Sending Aviationstack request: method=%s endpoint=%s params=%s",
+            "GET",
+            endpoint,
+            sorted(key for key in request_params if key != "access_key"),
+        )
+
+        response = await self._http_client.request(
+            "GET",
+            url,
+            params=request_params,
+        )
+
+        logger.debug(
+            "Received Aviationstack response: method=%s endpoint=%s status=%s",
+            "GET",
+            endpoint,
+            response.status_code,
+        )
+
+        payload = self._parse_response(response)
+
+        self._raise_for_api_error(payload)
+
+        return payload
+
+    async def close(self) -> None:
+        logger.debug("Closing Aviationstack HTTP client")
+        await self._http_client.close()
+
+    def _build_url(self, endpoint: str) -> str:
+        """Build an endpoint URL safely."""
+
+        validate_endpoint(endpoint)
+        normalized_base_url = self._settings.aviationstack_base_url.rstrip("/")
+        normalized_endpoint = endpoint.strip("/")
+
+        return f"{normalized_base_url}/{normalized_endpoint}"
+
+    @staticmethod
+    def _parse_response(response: Any) -> dict[str, Any]:
+        """Parse an Aviationstack JSON response."""
+
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            logger.warning("Aviationstack returned invalid JSON")
+            raise AviationstackAPIError("Aviationstack returned an invalid JSON response.") from exc
+
+        if not isinstance(payload, dict):
+            logger.warning(
+                "Aviationstack returned an unexpected response type: %s",
+                type(payload).__name__,
+            )
+            raise AviationstackAPIError("Aviationstack returned an unexpected response format.")
+
+        return payload
+
+    @staticmethod
+    def _raise_for_api_error(
+        payload: dict[str, Any],
+    ) -> None:
+        """Translate Aviationstack application-level errors."""
+
+        error = payload.get("error")
+
+        if not isinstance(error, dict):
+            return
+
+        error_type = error.get("type")
+        error_code = error.get("code")
+        message = error.get("message")
+
+        if not isinstance(error_type, str):
+            error_type = "api_error"
+
+        if not isinstance(error_code, str):
+            error_code = None
+
+        if not isinstance(message, str):
+            message = "Aviationstack returned an API error."
+
+        logger.warning(
+            "Aviationstack API error: type=%s code=%s",
+            error_type,
+            error_code,
+        )
+
+        raise AviationstackAPIError(
+            f"{error_type}: {message}",
+            error_code=error_code,
+        )

aviationstack_mcp_server/client/factory.py

@@ -0,0 +1,30 @@
+import logging
+
+from aviationstack_mcp_server.client.aviationstack import AviationstackClient
+from aviationstack_mcp_server.client.http import HTTPClient
+from aviationstack_mcp_server.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+def create_aviationstack_client(
+    settings: Settings,
+) -> AviationstackClient:
+    """Create a configured Aviationstack API client."""
+
+    logger.debug(
+        "Creating Aviationstack client: base_url=%s connect_timeout=%s "
+        "read_timeout=%s max_retries=%s retry_backoff=%s",
+        settings.aviationstack_base_url,
+        settings.aviationstack_connect_timeout,
+        settings.aviationstack_read_timeout,
+        settings.aviationstack_retry_max_attempts,
+        settings.aviationstack_retry_backoff_factor,
+    )
+
+    http_client = HTTPClient(settings)
+
+    return AviationstackClient(
+        settings=settings,
+        http_client=http_client,
+    )

aviationstack_mcp_server/client/http.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections.abc import Mapping
+from time import perf_counter
+from typing import Any
+
+import httpx
+
+from aviationstack_mcp_server.config import Settings
+from aviationstack_mcp_server.errors import (
+    AviationstackAuthenticationError,
+    AviationstackAuthorizationError,
+    AviationstackNotFoundError,
+    AviationstackRateLimitError,
+    AviationstackRequestError,
+    AviationstackServerError,
+    AviationstackTimeoutError,
+)
+
+logger = logging.getLogger(__name__)
+
+MAX_RETRY_DELAY = 30.0
+RETRYABLE_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
+
+
+def is_retryable_status(status_code: int) -> bool:
+    """Return whether an HTTP status represents a transient failure."""
+
+    return status_code in RETRYABLE_STATUS_CODES
+
+
+class HTTPClient:
+    """Reusable asynchronous HTTP client with retry and timeout handling."""
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+
+        timeout = httpx.Timeout(
+            connect=settings.aviationstack_connect_timeout,
+            read=settings.aviationstack_read_timeout,
+            write=settings.aviationstack_write_timeout,
+            pool=settings.aviationstack_pool_timeout,
+        )
+
+        self._client = httpx.AsyncClient(
+            timeout=timeout,
+            follow_redirects=True,
+            headers={
+                "Accept": "application/json",
+                "User-Agent": "aviationstack-mcp-server/0.1.0",
+            },
+        )
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Execute an HTTP request with retry handling."""
+
+        max_attempts = self._settings.aviationstack_retry_max_attempts
+        endpoint = httpx.URL(url).path or "/"
+
+        for attempt_number in range(1, max_attempts + 1):
+            started_at = perf_counter()
+            logger.debug(
+                "HTTP request started method=%s endpoint=%s attempt=%s params=%s",
+                method,
+                endpoint,
+                attempt_number,
+                sorted(key for key in params if key != "access_key") if params else [],
+            )
+
+            try:
+                response = await self._client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as exc:
+                duration_ms = (perf_counter() - started_at) * 1000
+                if attempt_number >= max_attempts:
+                    logger.error(
+                        "HTTP request failed after %s attempts: method=%s endpoint=%s "
+                        "error_type=%s duration_ms=%.2f",
+                        max_attempts,
+                        method,
+                        endpoint,
+                        type(exc).__name__,
+                        duration_ms,
+                    )
+                    raise AviationstackTimeoutError("Aviationstack request timed out.") from exc
+
+                await self._sleep_before_retry(
+                    attempt_number,
+                    method=method,
+                    url=url,
+                )
+                continue
+            except httpx.RequestError as exc:
+                duration_ms = (perf_counter() - started_at) * 1000
+                if attempt_number >= max_attempts:
+                    logger.error(
+                        "HTTP request failed after %s attempts: method=%s endpoint=%s "
+                        "error_type=%s duration_ms=%.2f",
+                        max_attempts,
+                        method,
+                        endpoint,
+                        type(exc).__name__,
+                        duration_ms,
+                    )
+                    raise AviationstackRequestError(
+                        "Unable to reach the Aviationstack API."
+                    ) from exc
+
+                await self._sleep_before_retry(
+                    attempt_number,
+                    method=method,
+                    url=url,
+                )
+                continue
+
+            duration_ms = (perf_counter() - started_at) * 1000
+            logger.debug(
+                "HTTP response received method=%s endpoint=%s status=%s "
+                "attempt=%s duration_ms=%.2f",
+                method,
+                endpoint,
+                response.status_code,
+                attempt_number,
+                duration_ms,
+            )
+
+            if is_retryable_status(response.status_code):
+                if attempt_number >= max_attempts:
+                    logger.error(
+                        "HTTP request failed after %s attempts: method=%s endpoint=%s "
+                        "status=%s duration_ms=%.2f",
+                        max_attempts,
+                        method,
+                        endpoint,
+                        response.status_code,
+                        duration_ms,
+                    )
+                    self._raise_for_status(response)
+
+                await self._sleep_before_retry(
+                    attempt_number,
+                    method=method,
+                    url=url,
+                    response=response,
+                )
+                continue
+
+            self._raise_for_status(response)
+            return response
+
+        raise AviationstackRequestError("Aviationstack request failed unexpectedly.")
+
+    async def _sleep_before_retry(
+        self,
+        attempt_number: int,
+        *,
+        method: str,
+        url: str,
+        response: httpx.Response | None = None,
+    ) -> None:
+        """Wait before a retry using Retry-After or capped jittered backoff."""
+
+        retry_after = self._retry_after_seconds(response)
+        if retry_after is not None:
+            delay = min(retry_after, MAX_RETRY_DELAY)
+            retry_after_detail = f" retry_after={delay}"
+        else:
+            base_delay = min(
+                self._settings.aviationstack_retry_backoff_factor * (2 ** (attempt_number - 1)),
+                MAX_RETRY_DELAY,
+            )
+            jitter = random.uniform(0, base_delay * 0.1)
+            delay = min(base_delay + jitter, MAX_RETRY_DELAY)
+            retry_after_detail = ""
+
+        logger.warning(
+            "Retrying HTTP request: method=%s endpoint=%s attempt=%s delay=%.3f%s",
+            method,
+            httpx.URL(url).path or "/",
+            attempt_number + 1,
+            delay,
+            retry_after_detail,
+        )
+        await asyncio.sleep(delay)
+
+    @staticmethod
+    def _retry_after_seconds(response: httpx.Response | None) -> float | None:
+        """Parse a non-negative numeric Retry-After header, if present."""
+
+        if response is None:
+            return None
+
+        retry_after = response.headers.get("Retry-After")
+        if retry_after is None:
+            return None
+
+        try:
+            delay = float(retry_after)
+        except ValueError:
+            return None
+
+        return delay if delay >= 0 else None
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+
+        logger.debug("Closing HTTP client")
+        await self._client.aclose()
+
+    @staticmethod
+    def _raise_for_status(
+        response: httpx.Response,
+    ) -> None:
+        status_code = response.status_code
+        error_code = HTTPClient._extract_error_code(response)
+
+        if status_code >= 400:
+            logger.warning(
+                "Aviationstack HTTP error response: status=%s",
+                status_code,
+            )
+
+        if status_code == 401:
+            raise AviationstackAuthenticationError(
+                "Aviationstack authentication failed.",
+                status_code=status_code,
+                error_code=error_code,
+            )
+
+        if status_code == 403:
+            raise AviationstackAuthorizationError(
+                "Aviationstack authorization failed.",
+                status_code=status_code,
+                error_code=error_code,
+            )
+
+        if status_code == 404:
+            raise AviationstackNotFoundError(
+                "The requested Aviationstack resource was not found.",
+                status_code=status_code,
+            )
+
+        if status_code == 429:
+            raise AviationstackRateLimitError(
+                "Aviationstack rate limit exceeded.",
+                status_code=status_code,
+                error_code=error_code,
+            )
+        if 500 <= status_code <= 599:
+            raise AviationstackServerError(
+                "Aviationstack returned a server error.",
+                status_code=status_code,
+            )
+
+        if status_code >= 400:
+            raise AviationstackRequestError(
+                "Aviationstack request failed.",
+                status_code=status_code,
+            )
+
+    @staticmethod
+    def _extract_error_code(response: httpx.Response) -> str | None:
+        """Extract only a structured provider error code from an error response."""
+
+        try:
+            payload = response.json()
+        except ValueError:
+            return None
+
+        if not isinstance(payload, dict):
+            return None
+
+        error = payload.get("error")
+        if not isinstance(error, dict):
+            return None
+
+        error_code = error.get("code")
+        return error_code if isinstance(error_code, str) else None

aviationstack_mcp_server/config/__init__.py

@@ -0,0 +1,3 @@
+from .settings import Settings, get_settings
+
+__all__ = ["Settings", "get_settings"]

aviationstack_mcp_server/config/settings.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import logging
+from enum import StrEnum
+from functools import lru_cache
+
+from pydantic import (
+    AnyHttpUrl,
+    Field,
+    SecretStr,
+    TypeAdapter,
+    field_validator,
+    model_validator,
+)
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from aviationstack_mcp_server.security import validate_api_base_url
+
+_http_url_adapter = TypeAdapter(AnyHttpUrl)
+
+logger = logging.getLogger(__name__)
+
+
+class Environment(StrEnum):
+    """Supported application environments."""
+
+    DEVELOPMENT = "development"
+    TESTING = "testing"
+    STAGING = "staging"
+    PRODUCTION = "production"
+
+
+class Settings(BaseSettings):
+    """Application configuration loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # ------------------------------------------------------------------
+    # Application
+    # ------------------------------------------------------------------
+
+    app_name: str = "aviationstack-mcp-server"
+
+    environment: Environment = Environment.DEVELOPMENT
+
+    log_level: str = Field(
+        default="INFO",
+    )
+
+    # ------------------------------------------------------------------
+    # Aviationstack
+    # ------------------------------------------------------------------
+
+    aviationstack_api_key: SecretStr = Field(
+        ...,
+        min_length=1,
+    )
+
+    aviationstack_base_url: str = Field(
+        default="https://api.aviationstack.com/v1",
+    )
+
+    # ------------------------------------------------------------------
+    # HTTP client
+    # ------------------------------------------------------------------
+
+    aviationstack_connect_timeout: float = Field(
+        default=5.0,
+        gt=0,
+    )
+
+    aviationstack_read_timeout: float = Field(
+        default=30.0,
+        gt=0,
+    )
+
+    aviationstack_write_timeout: float = Field(
+        default=30.0,
+        gt=0,
+    )
+
+    aviationstack_pool_timeout: float = Field(
+        default=5.0,
+        gt=0,
+    )
+
+    # ------------------------------------------------------------------
+    # Retry configuration
+    # ------------------------------------------------------------------
+
+    aviationstack_retry_max_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+    )
+
+    aviationstack_retry_backoff_factor: float = Field(
+        default=0.5,
+        ge=0,
+    )
+
+    # ------------------------------------------------------------------
+    # Validators
+    # ------------------------------------------------------------------
+
+    @field_validator("aviationstack_api_key")
+    @classmethod
+    def validate_api_key(
+        cls,
+        value: SecretStr,
+    ) -> SecretStr:
+        """Reject empty or whitespace-only API keys."""
+
+        if not value.get_secret_value().strip():
+            raise ValueError("AVIATIONSTACK_API_KEY must not be empty.")
+
+        return value
+
+    @field_validator("aviationstack_base_url")
+    @classmethod
+    def validate_base_url(cls, value: str) -> str:
+        """Ensure the base URL is a valid HTTP/HTTPS URL."""
+
+        _http_url_adapter.validate_python(value)
+
+        return value
+
+    @model_validator(mode="after")
+    def validate_environment_security(self) -> Settings:
+        """Apply stricter API URL policy to production configuration."""
+
+        validate_api_base_url(
+            self.aviationstack_base_url,
+            environment=self.environment.value,
+        )
+        return self
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return the cached application settings."""
+
+    settings = Settings()
+    logger.debug(
+        "Loaded Aviationstack settings: environment=%s log_level=%s "
+        "base_url=%s connect_timeout=%s read_timeout=%s max_retries=%s "
+        "retry_backoff=%s",
+        settings.environment,
+        settings.log_level,
+        settings.aviationstack_base_url,
+        settings.aviationstack_connect_timeout,
+        settings.aviationstack_read_timeout,
+        settings.aviationstack_retry_max_attempts,
+        settings.aviationstack_retry_backoff_factor,
+    )
+
+    return settings

aviationstack_mcp_server/errors/__init__.py

@@ -0,0 +1,25 @@
+from .exceptions import (
+    AviationstackAPIError,
+    AviationstackAuthenticationError,
+    AviationstackAuthorizationError,
+    AviationstackConfigurationError,
+    AviationstackError,
+    AviationstackNotFoundError,
+    AviationstackRateLimitError,
+    AviationstackRequestError,
+    AviationstackServerError,
+    AviationstackTimeoutError,
+)
+
+__all__ = [
+    "AviationstackAPIError",
+    "AviationstackAuthenticationError",
+    "AviationstackAuthorizationError",
+    "AviationstackConfigurationError",
+    "AviationstackError",
+    "AviationstackNotFoundError",
+    "AviationstackRateLimitError",
+    "AviationstackRequestError",
+    "AviationstackServerError",
+    "AviationstackTimeoutError",
+]