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

amazon_ads_mcp/tools/region.py

@@ -0,0 +1,320 @@
+"""Manage Amazon Ads API region for the MCP server.
+
+Provide utilities to set, inspect, and list region information including
+endpoints and sandbox state.
+
+Examples
+--------
+.. code-block:: python
+
+   import asyncio
+   from amazon_ads_mcp.tools.region import set_active_region, get_active_region
+
+   async def main():
+       await set_active_region("na")
+       info = await get_active_region()
+       print(info["region"])  # "na"
+
+   asyncio.run(main())
+"""
+
+import logging
+from typing import Literal
+
+from ..auth.manager import get_auth_manager
+from ..config.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+
+async def set_active_region(region: Literal["na", "eu", "fe"]) -> dict:
+    """Set the active Amazon Ads API region.
+
+    Update API and OAuth endpoints for subsequent calls. When the provider
+    binds region to identity, advise switching identities instead.
+
+    :param region: Target region ("na", "eu", or "fe").
+    :return: Result payload with region info and endpoints.
+    :raises ValueError: If the region value is invalid.
+    :raises Exception: If updating the region fails.
+    """
+    try:
+        # Validate region
+        if region not in ["na", "eu", "fe"]:
+            raise ValueError(f"Invalid region: {region}. Must be 'na', 'eu', or 'fe'")
+
+        # Get auth manager to check provider capabilities
+        auth_manager = get_auth_manager()
+
+        # Check if provider controls region through identity
+        if (
+            hasattr(auth_manager.provider, "region_controlled_by_identity")
+            and auth_manager.provider.region_controlled_by_identity()
+        ):
+            # For providers where region is identity-controlled, we can't directly set the region
+            # The region is determined by the active identity
+            current_identity = auth_manager.get_active_identity()
+            if current_identity:
+                identity_region = current_identity.attributes.get("region", "na")
+                if identity_region != region:
+                    return {
+                        "success": False,
+                        "error": "REGION_MISMATCH",
+                        "message": f"Cannot set region to '{region}' when using {auth_manager.provider.provider_type} authentication. "
+                        f"Current identity is in '{identity_region}' region. "
+                        f"Please select an identity in the '{region}' region instead.",
+                        "current_identity": current_identity.attributes.get(
+                            "name", current_identity.id
+                        ),
+                        "identity_region": identity_region,
+                        "requested_region": region,
+                    }
+                else:
+                    # Region already matches the identity's region
+                    return {
+                        "success": True,
+                        "message": f"Region is already set to '{region}' via OpenBridge identity",
+                        "region": region,
+                        "identity": current_identity.attributes.get(
+                            "name", current_identity.id
+                        ),
+                    }
+            else:
+                return {
+                    "success": False,
+                    "error": "NO_IDENTITY",
+                    "message": "No active identity set. Please select an identity first using 'set_active_identity'",
+                    "requested_region": region,
+                }
+
+        # For non-OpenBridge providers (like DirectAmazonAdsProvider)
+        # Get the current region first
+        old_region = (
+            auth_manager.provider.region
+            if hasattr(auth_manager.provider, "region")
+            else "na"
+        )
+
+        # If using direct auth, update the provider's region
+        if hasattr(auth_manager.provider, "_region"):
+            # For DirectAmazonAdsProvider - it has a settable _region attribute
+            auth_manager.provider._region = region
+            # Note: OAuth endpoint is determined dynamically via get_oauth_endpoint()
+            # so no need to update it explicitly
+
+            # Clear cached tokens as they might be region-specific
+            if hasattr(auth_manager.provider, "_access_token"):
+                auth_manager.provider._access_token = None
+                logger.info("Cleared cached access token due to region change")
+
+        # Map region to name for clarity
+        region_names = {
+            "na": "North America",
+            "eu": "Europe",
+            "fe": "Far East",
+        }
+
+        # Get the new endpoint URLs from provider if available
+        if hasattr(auth_manager.provider, "get_region_endpoint"):
+            region_endpoint = auth_manager.provider.get_region_endpoint(region)
+        else:
+            # Fallback to settings for display
+            settings = Settings()
+            region_endpoint = settings.region_endpoint
+
+        # Get OAuth endpoint if available
+        oauth_endpoint = None
+        if hasattr(auth_manager.provider, "get_oauth_endpoint"):
+            oauth_endpoint = auth_manager.provider.get_oauth_endpoint(region)
+
+        # Build response
+        response = {
+            "success": True,
+            "previous_region": old_region,
+            "new_region": region,
+            "region_name": region_names[region],
+            "api_endpoint": region_endpoint,
+            "message": f"Region changed from {old_region} to {region}",
+        }
+
+        # Add OAuth endpoint if available
+        if oauth_endpoint:
+            response["oauth_endpoint"] = oauth_endpoint
+
+        logger.info(
+            f"Region changed from {old_region} to {region} ({region_names[region]})"
+        )
+        return response
+
+    except Exception as e:
+        logger.error(f"Failed to set active region: {e}")
+        raise
+
+
+async def get_active_region() -> dict:
+    """Return information about the active region.
+
+    Include endpoints, sandbox mode, active auth method, and whether the
+    region source is identity or configuration.
+
+    :return: Region information with endpoints and metadata.
+    :raises Exception: If retrieval fails.
+    """
+    try:
+        # Get auth manager to access current region
+        auth_manager = get_auth_manager()
+
+        # Get region from provider if available, otherwise use default
+        if hasattr(auth_manager.provider, "region"):
+            region = auth_manager.provider.region
+        else:
+            # Fallback to environment/default if provider doesn't have region
+            settings = Settings()
+            region = settings.amazon_ads_region
+
+        # Map region to name
+        region_names = {
+            "na": "North America",
+            "eu": "Europe",
+            "fe": "Far East",
+        }
+
+        # Get endpoint URLs from provider if available, otherwise from settings
+        if hasattr(auth_manager.provider, "get_region_endpoint"):
+            region_endpoint = auth_manager.provider.get_region_endpoint()
+        else:
+            settings = Settings()
+            region_endpoint = settings.region_endpoint
+
+        # Get sandbox mode from settings
+        settings = Settings()
+        sandbox_mode = settings.amazon_ads_sandbox_mode
+
+        response = {
+            "success": True,
+            "region": region,
+            "region_name": region_names.get(region, "Unknown"),
+            "api_endpoint": region_endpoint,
+            "sandbox_mode": sandbox_mode,
+        }
+
+        # Add OAuth endpoint if available
+        if hasattr(auth_manager.provider, "get_oauth_endpoint"):
+            response["oauth_endpoint"] = auth_manager.provider.get_oauth_endpoint()
+            response["auth_method"] = "direct"
+        else:
+            response["auth_method"] = "openbridge"
+
+        # Check if region is from identity (OpenBridge) or config
+        if auth_manager.get_active_identity():
+            identity_region = auth_manager.get_active_region()
+            if identity_region:
+                response["identity_region"] = identity_region
+                response["source"] = (
+                    "identity" if identity_region == region else "config"
+                )
+            else:
+                response["source"] = "config"
+        else:
+            response["source"] = "config"
+
+        return response
+
+    except Exception as e:
+        logger.error(f"Failed to get active region: {e}")
+        raise
+
+
+async def list_available_regions() -> dict:
+    """List available regions and their endpoints.
+
+    Include API and OAuth endpoints, marketplaces, sandbox mode, and the
+    currently selected region.
+
+    :return: Mapping containing region details.
+    :raises Exception: If listing fails.
+    """
+    try:
+        # Get auth manager to access current region
+        auth_manager = get_auth_manager()
+
+        # Get current region from provider or settings
+        if hasattr(auth_manager.provider, "region"):
+            current_region = auth_manager.provider.region
+        else:
+            settings = Settings()
+            current_region = settings.amazon_ads_region
+
+        # Get sandbox mode from settings
+        settings = Settings()
+        sandbox_mode = settings.amazon_ads_sandbox_mode
+
+        regions = {
+            "na": {
+                "name": "North America",
+                "api_endpoint": "https://advertising-api.amazon.com",
+                "oauth_endpoint": "https://api.amazon.com/auth/o2/token",
+                "marketplaces": ["US", "CA", "MX", "BR"],
+            },
+            "eu": {
+                "name": "Europe",
+                "api_endpoint": "https://advertising-api-eu.amazon.com",
+                "oauth_endpoint": "https://api.amazon.co.uk/auth/o2/token",
+                "marketplaces": [
+                    "UK",
+                    "DE",
+                    "FR",
+                    "IT",
+                    "ES",
+                    "NL",
+                    "AE",
+                    "SE",
+                    "PL",
+                    "TR",
+                    "SG",
+                    "AU",
+                    "IN",
+                ],
+            },
+            "fe": {
+                "name": "Far East",
+                "api_endpoint": "https://advertising-api-fe.amazon.com",
+                "oauth_endpoint": "https://api.amazon.co.jp/auth/o2/token",
+                "marketplaces": ["JP"],
+            },
+        }
+
+        # Adjust for sandbox mode
+        if sandbox_mode:
+            for region_data in regions.values():
+                region_data["api_endpoint"] = region_data["api_endpoint"].replace(
+                    "advertising-api", "advertising-api-test"
+                )
+                region_data["sandbox"] = True
+
+        return {
+            "success": True,
+            "current_region": current_region,
+            "sandbox_mode": sandbox_mode,
+            "regions": regions,
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to list regions: {e}")
+        raise
+
+
+# Alias functions for backward compatibility with builtin_tools
+async def set_region(region: Literal["na", "eu", "fe"]) -> dict:
+    """Alias for set_active_region for backward compatibility."""
+    return await set_active_region(region)
+
+
+async def get_region() -> dict:
+    """Alias for get_active_region for backward compatibility."""
+    return await get_active_region()
+
+
+async def list_regions() -> dict:
+    """Alias for list_available_regions for backward compatibility."""
+    return await list_available_regions()

amazon_ads_mcp/tools/region_identity.py

@@ -0,0 +1,175 @@
+"""Region-aware identity selection tools.
+
+This module provides tools to help find and switch to identities
+in specific regions when using OpenBridge authentication.
+"""
+
+import logging
+from typing import Dict, Optional
+
+from ..auth.manager import get_auth_manager
+
+logger = logging.getLogger(__name__)
+
+
+async def list_identities_by_region(region: Optional[str] = None) -> Dict:
+    """List identities grouped by region.
+
+    This is particularly useful for OpenBridge authentication where
+    regions are tied to identities rather than being freely switchable.
+
+    :param region: Optional region filter ('na', 'eu', 'fe')
+    :type region: Optional[str]
+    :return: Dictionary with identities grouped by region
+    :rtype: Dict
+    """
+    try:
+        auth_manager = get_auth_manager()
+
+        # Get all identities
+        if hasattr(auth_manager.provider, "list_identities"):
+            all_identities = await auth_manager.provider.list_identities()
+        else:
+            all_identities = await auth_manager.list_identities()
+
+        # Group by region
+        by_region = {"na": [], "eu": [], "fe": [], "unknown": []}
+
+        for identity in all_identities:
+            identity_region = identity.attributes.get("region", "unknown").lower()
+            if identity_region in by_region:
+                by_region[identity_region].append(
+                    {
+                        "id": identity.id,
+                        "name": identity.attributes.get("name", identity.id),
+                        "email": identity.attributes.get("email", ""),
+                        "region": identity_region,
+                        "account_id": identity.attributes.get("account_id", ""),
+                    }
+                )
+            else:
+                by_region["unknown"].append(
+                    {
+                        "id": identity.id,
+                        "name": identity.attributes.get("name", identity.id),
+                        "region": identity_region,
+                    }
+                )
+
+        # Get current active identity
+        current_identity = auth_manager.get_active_identity()
+        current_id = current_identity.id if current_identity else None
+
+        # Filter by region if specified
+        if region and region in ["na", "eu", "fe"]:
+            filtered = {
+                region: by_region[region],
+                "total": len(by_region[region]),
+                "current_identity": current_id,
+                "message": f"Found {len(by_region[region])} identities in {region.upper()} region",
+            }
+            return filtered
+
+        # Return all grouped by region
+        return {
+            "regions": by_region,
+            "totals": {k: len(v) for k, v in by_region.items()},
+            "current_identity": current_id,
+            "message": "Identities grouped by region",
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to list identities by region: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "message": "Failed to list identities by region",
+        }
+
+
+async def switch_to_region_identity(
+    target_region: str, identity_id: Optional[str] = None
+) -> Dict:
+    """Switch to an identity in the specified region.
+
+    If identity_id is provided, switches to that specific identity if it's in the
+    target region. Otherwise, switches to the first available identity in the region.
+
+    :param target_region: Target region ('na', 'eu', 'fe')
+    :type target_region: str
+    :param identity_id: Optional specific identity ID to switch to
+    :type identity_id: Optional[str]
+    :return: Result of the switch operation
+    :rtype: Dict
+    """
+    try:
+        if target_region not in ["na", "eu", "fe"]:
+            return {
+                "success": False,
+                "error": "INVALID_REGION",
+                "message": f"Invalid region: {target_region}. Must be 'na', 'eu', or 'fe'",
+            }
+
+        # Get identities in the target region
+        region_data = await list_identities_by_region(target_region)
+
+        if "error" in region_data:
+            return region_data
+
+        target_identities = region_data.get(target_region, [])
+
+        if not target_identities:
+            return {
+                "success": False,
+                "error": "NO_IDENTITIES",
+                "message": f"No identities found in {target_region.upper()} region",
+                "region": target_region,
+            }
+
+        # If specific identity requested, validate it's in the region
+        if identity_id:
+            matching = [i for i in target_identities if i["id"] == identity_id]
+            if not matching:
+                return {
+                    "success": False,
+                    "error": "IDENTITY_NOT_IN_REGION",
+                    "message": f"Identity {identity_id} is not in {target_region.upper()} region",
+                    "available_identities": target_identities,
+                }
+            selected = matching[0]
+        else:
+            # Select first available identity in region
+            selected = target_identities[0]
+
+        # Switch to the selected identity
+        from ..models import SetActiveIdentityRequest
+
+        request = SetActiveIdentityRequest(identity_id=selected["id"], persist=True)
+
+        from . import identity
+
+        result = await identity.set_active_identity(request)
+
+        if result.success:
+            return {
+                "success": True,
+                "message": f"Switched to {selected['name']} in {target_region.upper()} region",
+                "identity": selected,
+                "region": target_region,
+                "credentials_loaded": result.credentials_loaded,
+            }
+        else:
+            return {
+                "success": False,
+                "error": "SWITCH_FAILED",
+                "message": f"Failed to switch to identity: {result.message}",
+                "identity": selected,
+            }
+
+    except Exception as e:
+        logger.error(f"Failed to switch to region identity: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "message": "Failed to switch to region identity",
+        }

amazon_ads_mcp/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Utility functions for Amazon Ads API MCP server.
+
+This module provides utility functions and classes for the Amazon Ads
+MCP server, including OpenAPI specification handling and other
+helper functionality.
+"""