amazon-ads-mcp 0.2.7__py3-none-any.whl

amazon_ads_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""Amazon Ads API MCP Server package.
+
+This package provides a Model Context Protocol (MCP) server for interacting
+with the Amazon Advertising API. It includes authentication management,
+identity handling, and dynamic OpenAPI integration for seamless API access.
+
+:var __version__: Current package version
+:type __version__: str
+"""
+
+__version__ = "0.2.7"

amazon_ads_mcp/auth/__init__.py

@@ -0,0 +1,33 @@
+"""Authentication module for Amazon Ads MCP.
+
+This module provides authentication management for the Amazon Ads MCP server,
+including identity management, token handling, and authentication providers.
+Uses a pluggable provider architecture supporting multiple authentication methods.
+
+:var __all__: List of public exports from this module
+:type __all__: List[str]
+"""
+
+# Import providers to trigger registration
+from . import (  # noqa: F401  # imported for side effects (provider registration)
+    providers,
+)
+from .base import (
+    BaseAmazonAdsProvider,
+    BaseAuthProvider,
+    BaseIdentityProvider,
+    ProviderConfig,
+)
+from .manager import AuthManager, get_auth_manager
+from .registry import ProviderRegistry, register_provider
+
+__all__ = [
+    "AuthManager",
+    "get_auth_manager",
+    "ProviderRegistry",
+    "register_provider",
+    "BaseAuthProvider",
+    "BaseIdentityProvider",
+    "BaseAmazonAdsProvider",
+    "ProviderConfig",
+]

amazon_ads_mcp/auth/base.py

@@ -0,0 +1,211 @@
+"""Define base authentication provider interfaces.
+
+Provide abstract contracts for authentication providers and Amazon Ads
+specializations, enabling pluggable auth mechanisms (e.g., direct OAuth,
+OpenBridge) with consistent capabilities and region handling.
+
+Examples
+--------
+See the BaseAmazonAdsProvider class for a complete example of how to
+implement a custom authentication provider.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from ..models import AuthCredentials, Identity, Token
+from ..utils.region_config import RegionConfig
+
+
+class BaseAuthProvider(ABC):
+    """Provide the core authentication interface.
+
+    Define the minimal contract for all authentication providers regardless
+    of mechanism (OAuth2, API key, etc.).
+    """
+
+    @property
+    @abstractmethod
+    def provider_type(self) -> str:
+        """Return the provider type identifier.
+
+        :return: Provider type (e.g., "openbridge", "direct").
+        """
+        pass
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Initialize the provider.
+
+        Perform required setup (e.g., configuration validation).
+        """
+        pass
+
+    @abstractmethod
+    async def get_token(self) -> Token:
+        """Return a valid authentication token.
+
+        Refresh the token if necessary.
+
+        :return: Valid authentication token.
+        """
+        pass
+
+    @abstractmethod
+    async def validate_token(self, token: Token) -> bool:
+        """Return whether the token is still valid.
+
+        :param token: Token to validate.
+        :return: True if token is valid, False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Clean up provider resources."""
+        pass
+
+
+class BaseIdentityProvider(ABC):
+    """Provide multi-identity capabilities for providers.
+
+    Implementers can list identities, resolve an identity, and obtain
+    identity-scoped credentials for downstream API calls.
+    """
+
+    @abstractmethod
+    async def list_identities(self, **kwargs) -> List[Identity]:
+        """List available identities.
+
+        :param kwargs: Optional provider-specific filters.
+        :return: List of identities.
+        """
+        pass
+
+    @abstractmethod
+    async def get_identity(self, identity_id: str) -> Optional[Identity]:
+        """Return a specific identity by identifier.
+
+        :param identity_id: Identity identifier.
+        :return: Identity if found, otherwise None.
+        """
+        pass
+
+    @abstractmethod
+    async def get_identity_credentials(self, identity_id: str) -> AuthCredentials:
+        """Return credentials for a specific identity.
+
+        :param identity_id: Identity identifier.
+        :return: Authentication credentials for the identity.
+        """
+        pass
+
+
+class BaseAmazonAdsProvider(BaseAuthProvider):
+    """Provide Amazon Ads–specific provider functionality.
+
+    Add region handling, header generation, and endpoint resolution for
+    Amazon Advertising API integrations.
+    """
+
+    @property
+    @abstractmethod
+    def region(self) -> str:
+        """Return the current region code ("na", "eu", or "fe")."""
+        pass
+
+    @abstractmethod
+    async def get_headers(self) -> Dict[str, str]:
+        """Return authentication headers for Amazon Ads API requests.
+
+        The returned mapping can include Authorization, ClientId, and
+        optional scope headers as required by the downstream API.
+
+        :return: Header mapping for requests.
+        """
+        pass
+
+    def get_region_endpoint(self, region: str = None) -> str:
+        """Return the API endpoint for the given region.
+
+        :param region: Region code; defaults to the provider's region.
+        :return: API endpoint URL.
+        """
+        region = region or self.region
+        return RegionConfig.get_api_endpoint(region)
+
+    def requires_identity_region_routing(self) -> bool:
+        """Return whether requests must target the identity's region.
+
+        For providers that manage identities across regions, this indicates
+        whether API requests should always be routed to the region associated
+        with the active identity.
+
+        :return: True if identity-based region routing is required.
+        """
+        return False
+
+    def headers_are_identity_specific(self) -> bool:
+        """Return whether authentication headers vary per identity.
+
+        For providers where different identities require different headers
+        (e.g., different client IDs or tokens), this indicates headers
+        cannot be reconstructed from a cached token alone.
+
+        :return: True if headers are identity specific.
+        """
+        return False
+
+    def region_controlled_by_identity(self) -> bool:
+        """Return whether the region is determined by the active identity.
+
+        For providers that bind region to identity, region changes require
+        selecting an identity in the target region.
+
+        :return: True if region is controlled by identity.
+        """
+        return False
+
+    def get_oauth_endpoint(self, region: str = None) -> str:
+        """Return the OAuth endpoint for the given region.
+
+        :param region: Region code; defaults to the provider's region.
+        :return: OAuth endpoint URL.
+        """
+        region = region or self.region
+        return RegionConfig.get_oauth_endpoint(region)
+
+
+class ProviderConfig:
+    """Hold provider configuration values.
+
+    Store arbitrary configuration for providers with both mapping-style and
+    attribute-style access for convenience.
+    """
+
+    def __init__(self, **kwargs):
+        """Initialize configuration from keyword arguments.
+
+        :param kwargs: Provider-specific configuration parameters.
+        """
+        self._config = kwargs
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return configuration value by key.
+
+        :param key: Configuration key to retrieve.
+        :param default: Default value if key not present.
+        :return: The configuration value or the default.
+        """
+        return self._config.get(key, default)
+
+    def __getattr__(self, name: str) -> Any:
+        """Provide attribute-style access to configuration values.
+
+        :param name: Attribute name to access.
+        :return: The configuration value.
+        :raises AttributeError: If the attribute is not defined.
+        """
+        if name in self._config:
+            return self._config[name]
+        raise AttributeError(f"Config has no attribute '{name}'")

amazon_ads_mcp/auth/hooks.py

@@ -0,0 +1,172 @@
+"""FastMCP 2.11 authentication hooks for request authentication.
+
+This module provides request hooks that integrate with FastMCP 2.11's
+hook system to automatically add authentication headers to outgoing
+HTTP requests, replacing the need for custom HTTP clients.
+
+The module provides:
+- AuthHeaderHook: Automatic authentication header injection
+- Header pollution cleanup for MCP client compatibility
+- Special endpoint handling (e.g., profiles endpoint)
+- Response processing for auth-related errors
+"""
+
+import logging
+from typing import Optional
+
+import httpx
+from fastmcp import Context
+
+logger = logging.getLogger(__name__)
+
+
+class AuthHeaderHook:
+    """Request hook that adds authentication headers to outgoing requests.
+
+    This hook integrates with FastMCP 2.11's request lifecycle to automatically
+    inject authentication headers into all outgoing HTTP requests. It replaces
+    the need for a custom AuthenticatedClient by working with FastMCP's native
+    HTTP client.
+
+    The hook provides:
+    - Automatic authentication header injection
+    - Header pollution cleanup for MCP client compatibility
+    - Special endpoint handling (e.g., profiles endpoint)
+    - Response processing for auth-related errors
+
+    Example:
+        >>> auth_hook = AuthHeaderHook(auth_manager)
+        >>> base_mcp.add_request_hook(auth_hook)
+    """
+
+    def __init__(self, auth_manager):
+        """Initialize the authentication header hook.
+
+        Sets up the hook with the authentication manager that will
+        provide the necessary headers for requests.
+
+        :param auth_manager: The authentication manager instance that provides headers
+        :type auth_manager: AuthManager
+        :return: None
+        :rtype: None
+        """
+        self.auth_manager = auth_manager
+
+    async def before_request(
+        self, request: httpx.Request, ctx: Optional[Context] = None
+    ) -> httpx.Request:
+        """Add authentication headers before the request is sent.
+
+        This method is called by FastMCP before each HTTP request is sent.
+        It retrieves the current authentication headers from the auth manager
+        and adds them to the request, while also cleaning up any polluted
+        headers that might interfere with the Amazon Ads API.
+
+        :param request: The HTTP request to modify
+        :type request: httpx.Request
+        :param ctx: Optional FastMCP context for the current operation
+        :type ctx: Optional[Context]
+        :return: The modified request with authentication headers added
+        :rtype: httpx.Request
+        """
+        if not self.auth_manager:
+            return request
+
+        try:
+            # Get auth headers from manager
+            auth_headers = await self.auth_manager.get_headers()
+            logger.debug(f"Got auth headers: {list(auth_headers.keys())}")
+        except Exception as e:
+            logger.error(f"Failed to get auth headers: {e}")
+            return request
+
+        # Clean polluted MCP client headers
+        # FastMCP sometimes forwards headers from the MCP client that
+        # shouldn't go to the Amazon Ads API
+        polluted_headers = []
+        for key in list(request.headers.keys()):
+            key_lower = key.lower()
+            if any(
+                pattern in key_lower
+                for pattern in [
+                    "authorization",
+                    "clientid",
+                    "client-id",
+                    "client_id",
+                    "amazon-ads",
+                    "amazon-advertising",
+                    "scope",
+                ]
+            ):
+                polluted_headers.append(key)
+                del request.headers[key]
+
+        if polluted_headers:
+            logger.debug(
+                f"Removed {len(polluted_headers)} polluted headers: {polluted_headers}"
+            )
+
+        # Check for special endpoint handling
+        url = str(request.url)
+
+        # Handle profiles endpoint special case
+        # The /v2/profiles endpoint when listing (no profileId in URL)
+        # doesn't accept the Scope header
+        if "/v2/profiles" in url and "profileId" not in url:
+            auth_headers = auth_headers.copy()
+            auth_headers.pop("Amazon-Advertising-API-Scope", None)
+            logger.debug("Removed Scope header for profiles listing endpoint")
+
+        # Add auth headers to request
+        request.headers.update(auth_headers)
+
+        # Log final headers at DEBUG level only for production safety
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug("Final headers being sent to Amazon:")
+            for key, value in request.headers.items():
+                if "authorization" in key.lower():
+                    logger.debug(f"  {key}: {value[:50]}...")
+                else:
+                    logger.debug(f"  {key}: {value}")
+
+        return request
+
+    async def after_response(
+        self, response: httpx.Response, ctx: Optional[Context] = None
+    ) -> httpx.Response:
+        """Process response after it's received.
+
+        This method can be used to handle auth-related response processing,
+        such as detecting expired tokens or rate limits.
+
+        :param response: The HTTP response received
+        :type response: httpx.Response
+        :param ctx: Optional FastMCP context for the current operation
+        :type ctx: Optional[Context]
+        :return: The response, potentially modified
+        :rtype: httpx.Response
+        """
+        # Log auth-related errors with more detail
+        if response.status_code == 401:
+            error_detail = ""
+            try:
+                error_body = response.json()
+                error_detail = f" - Error: {error_body}"
+            except Exception:
+                error_detail = f" - Response: {response.text[:200]}"
+
+            logger.error(f"Received 401 Unauthorized - token may be expired or invalid{error_detail}")
+            logger.error(f"Request URL: {response.request.url}")
+            logger.error(f"Request had headers: {list(response.request.headers.keys())}")
+
+            # Check for specific auth headers
+            auth_header = response.request.headers.get("authorization", "")
+            if not auth_header:
+                logger.error("CRITICAL: No Authorization header in request!")
+            elif not auth_header.startswith("Bearer "):
+                logger.error(f"CRITICAL: Authorization header missing 'Bearer ' prefix: {auth_header[:20]}...")
+
+        elif response.status_code == 403:
+            logger.warning("Received 403 Forbidden - check permissions")
+
+        return response