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

amazon_ads_mcp/utils/openapi/loader.py

@@ -0,0 +1,263 @@
+"""Dynamic OpenAPI specification loader for Amazon Ads MCP server.
+
+This module provides functionality for loading, merging, and managing
+OpenAPI specifications for the Amazon Ads API, enabling dynamic
+API integration.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAPISpecLoader:
+    """Load and merge OpenAPI specifications dynamically.
+
+    Handles loading of multiple OpenAPI specifications from a manifest
+    file and merging them into a single comprehensive specification
+    for the Amazon Ads API.
+
+    :param base_path: Base path for OpenAPI specifications
+    :type base_path: Path
+    :param manifest_path: Path to the manifest file
+    :type manifest_path: Path
+    :param specs: Dictionary of loaded specifications
+    :type specs: Dict[str, Any]
+    :param merged_spec: Cached merged specification
+    :type merged_spec: Optional[Dict[str, Any]]
+    """
+
+    def __init__(self, base_path: Path = Path("openapi/amazon_ads_apis")):
+        self.base_path = base_path
+        self.manifest_path = base_path / "manifest.json"
+        self.specs = {}
+        self.merged_spec = None
+
+    def load_all_specs(self) -> Dict[str, Any]:
+        """Load all OpenAPI specifications from the manifest.
+
+        Loads all OpenAPI specifications listed in the manifest file.
+        Falls back to legacy specifications if manifest is not found.
+
+        :return: Dictionary of loaded specifications
+        :rtype: Dict[str, Any]
+        """
+        if not self.manifest_path.exists():
+            logger.warning(f"Manifest not found at {self.manifest_path}")
+            return self._load_legacy_specs()
+
+        with open(self.manifest_path) as f:
+            manifest = json.load(f)
+
+        logger.info(f"Loading {manifest['successful']} OpenAPI specifications")
+
+        # Load each successful spec
+        for spec_info in manifest["specs"]:
+            if spec_info["status"] == "success":
+                # Fix path - the manifest stores paths relative to openapi/
+                spec_path = self.base_path.parent / spec_info["file"]
+                if spec_path.exists():
+                    try:
+                        with open(spec_path) as f:
+                            spec = json.load(f)
+
+                        category = spec_info["category"]
+                        resource = spec_info["resource"]
+                        key = f"{category}/{resource}"
+
+                        self.specs[key] = {"spec": spec, "info": spec_info}
+                        logger.debug(f"Loaded {key}")
+                    except Exception as e:
+                        logger.error(f"Failed to load {spec_path}: {e}")
+
+        logger.info(f"Successfully loaded {len(self.specs)} specifications")
+        return self.specs
+
+    def _load_legacy_specs(self) -> Dict[str, Any]:
+        """Load legacy manually downloaded specs as fallback.
+
+        Loads legacy OpenAPI specifications as a fallback when
+        the manifest file is not available.
+
+        :return: Dictionary of loaded legacy specifications
+        :rtype: Dict[str, Any]
+        """
+        legacy_specs = {
+            "test_accounts": "openapi/test_account.json",
+            "profiles": "openapi/profiles.json",
+            "exports": "openapi/exports.json",
+            "ads_api": "openapi/amazon_ads_all.json",
+        }
+
+        for name, path in legacy_specs.items():
+            spec_path = Path(path)
+            if spec_path.exists():
+                try:
+                    with open(spec_path) as f:
+                        spec = json.load(f)
+                    self.specs[name] = {
+                        "spec": spec,
+                        "info": {"resource": name, "category": "legacy"},
+                    }
+                    logger.info(f"Loaded legacy spec: {name}")
+                except Exception as e:
+                    logger.error(f"Failed to load legacy spec {path}: {e}")
+
+        return self.specs
+
+    def merge_specs(self) -> Dict[str, Any]:
+        """Merge all loaded specs into a single OpenAPI specification.
+
+        Combines all loaded OpenAPI specifications into a single
+        comprehensive specification for the Amazon Ads API.
+
+        :return: Merged OpenAPI specification
+        :rtype: Dict[str, Any]
+        """
+        if self.merged_spec:
+            return self.merged_spec
+
+        # Base structure
+        merged = {
+            "openapi": "3.0.1",
+            "info": {
+                "title": "Amazon Ads API - Complete",
+                "version": "1.0",
+                "description": "Comprehensive Amazon Ads API including all services",
+            },
+            "servers": [
+                {
+                    "url": "https://advertising-api.amazon.com",
+                    "description": "North America",
+                },
+                {
+                    "url": "https://advertising-api-eu.amazon.com",
+                    "description": "Europe",
+                },
+                {
+                    "url": "https://advertising-api-fe.amazon.com",
+                    "description": "Far East",
+                },
+            ],
+            "paths": {},
+            "components": {
+                "schemas": {},
+                "securitySchemes": {
+                    "bearerAuth": {
+                        "type": "http",
+                        "scheme": "bearer",
+                    }
+                },
+                "parameters": {},
+                "responses": {},
+            },
+        }
+
+        # Merge paths and components from each spec
+        for key, spec_data in self.specs.items():
+            spec = spec_data["spec"]
+
+            # Merge paths
+            if "paths" in spec:
+                for path, path_item in spec["paths"].items():
+                    # Process each path item to remove auth headers
+                    processed_path_item = self._remove_auth_headers(path_item)
+
+                    if path not in merged["paths"]:
+                        merged["paths"][path] = processed_path_item
+                    else:
+                        # Merge operations if path already exists
+                        for method, operation in processed_path_item.items():
+                            if method not in merged["paths"][path]:
+                                merged["paths"][path][method] = operation
+
+            # Merge components
+            if "components" in spec:
+                for component_type in [
+                    "schemas",
+                    "parameters",
+                    "responses",
+                    "examples",
+                    "requestBodies",
+                    "headers",
+                ]:
+                    if component_type in spec["components"]:
+                        if component_type not in merged["components"]:
+                            merged["components"][component_type] = {}
+
+                        # Add prefix to avoid conflicts
+                        prefix = key.replace("/", "_").replace(" ", "_")
+                        for name, component in spec["components"][
+                            component_type
+                        ].items():
+                            # Use original name if no conflict, otherwise prefix it
+                            final_name = name
+                            if name in merged["components"][component_type]:
+                                final_name = f"{prefix}_{name}"
+                            merged["components"][component_type][
+                                final_name
+                            ] = component
+
+        self.merged_spec = merged
+        logger.info(
+            f"Merged {len(merged['paths'])} paths from {len(self.specs)} specifications"
+        )
+
+        return merged
+
+    def get_categories(self) -> Dict[str, List[str]]:
+        """Get all categories and their resources."""
+        categories = {}
+        for key, spec_data in self.specs.items():
+            info = spec_data["info"]
+            category = info.get("category", "unknown")
+            resource = info.get("resource", key)
+
+            if category not in categories:
+                categories[category] = []
+            categories[category].append(resource)
+
+        return categories
+
+    def _remove_auth_headers(
+        self, path_item: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Remove authentication headers from path item parameters."""
+        auth_headers = {
+            "Amazon-Advertising-API-ClientId",
+            "Amazon-Advertising-API-Scope",
+            "Authorization",
+        }
+
+        processed = {}
+        for method, operation in path_item.items():
+            if method in ["get", "post", "put", "delete", "patch"]:
+                processed[method] = operation.copy()
+
+                # Remove auth headers from parameters
+                if "parameters" in operation:
+                    processed[method]["parameters"] = [
+                        param
+                        for param in operation["parameters"]
+                        if not (
+                            param.get("in") == "header"
+                            and param.get("name") in auth_headers
+                        )
+                    ]
+
+        return processed
+
+    def save_merged_spec(self, output_path: Path):
+        """Save the merged specification to a file."""
+        merged = self.merge_specs()
+        with open(output_path, "w") as f:
+            json.dump(merged, f, indent=2)
+        logger.info(f"Saved merged spec to {output_path}")
+
+    def load_and_merge_specs(self) -> Dict[str, Any]:
+        """Load all specs and return the merged specification."""
+        self.load_all_specs()
+        return self.merge_specs()

amazon_ads_mcp/utils/openapi/refs.py

@@ -0,0 +1,46 @@
+"""Reference utilities for OpenAPI specs.
+
+This module provides utilities for handling OpenAPI specification references
+($ref pointers). It includes functionality to dereference JSON Schema
+references within OpenAPI documents, allowing access to the actual schema
+definitions rather than just reference pointers.
+"""
+
+from typing import Any, Optional
+
+
+def deref(spec: dict, obj: Optional[dict]) -> Optional[dict]:
+    """Dereference a $ref pointer in an OpenAPI spec.
+
+    This function resolves JSON Schema references ($ref) within OpenAPI
+    specifications. It follows the reference path from the root of the
+    specification to retrieve the actual schema object that the reference
+    points to.
+
+    The function handles relative references that start with "#/" and
+    traverses the specification structure using the path components.
+    If the reference cannot be resolved (invalid path, missing keys,
+    or non-dict target), it returns the original object unchanged.
+
+    :param spec: The complete OpenAPI specification dictionary
+    :type spec: dict
+    :param obj: Object that may contain a $ref pointer to dereference
+    :type obj: Optional[dict]
+    :return: Dereferenced object if successful, original object if
+             dereferencing fails or is not needed
+    :rtype: Optional[dict]
+    """
+    if not isinstance(obj, dict):
+        return obj
+    ref = obj.get("$ref")
+    if not isinstance(ref, str) or not ref.startswith("#/"):
+        return obj
+    cur: Any = spec
+    for part in ref.lstrip("#/").split("/"):
+        if not isinstance(cur, dict) or part not in cur:
+            return obj
+        cur = cur[part]
+    return cur if isinstance(cur, dict) else obj
+
+
+__all__ = ["deref"]

amazon_ads_mcp/utils/region_config.py

@@ -0,0 +1,200 @@
+"""Centralized region configuration for Amazon Ads API.
+
+This module provides a single source of truth for all region-specific
+configurations including API endpoints, OAuth endpoints, and region metadata.
+All region mappings should be defined here to avoid duplication.
+"""
+
+from typing import Dict, Literal, Optional
+from urllib.parse import urlparse
+
+# Type alias for region codes
+RegionCode = Literal["na", "eu", "fe"]
+
+
+class RegionConfig:
+    """Centralized configuration for Amazon Ads API regions.
+
+    This class provides a single source of truth for all region-specific
+    endpoints and configurations. All components should use this class
+    instead of defining their own region mappings.
+    """
+
+    # Single source of truth for API endpoints
+    API_ENDPOINTS: Dict[RegionCode, str] = {
+        "na": "https://advertising-api.amazon.com",
+        "eu": "https://advertising-api-eu.amazon.com",
+        "fe": "https://advertising-api-fe.amazon.com",
+    }
+
+    # Single source of truth for OAuth token endpoints
+    OAUTH_ENDPOINTS: Dict[RegionCode, str] = {
+        "na": "https://api.amazon.com/auth/o2/token",
+        "eu": "https://api.amazon.co.uk/auth/o2/token",
+        "fe": "https://api.amazon.co.jp/auth/o2/token",
+    }
+
+    # Host mappings for URL parsing (without https://)
+    API_HOSTS: Dict[RegionCode, str] = {
+        "na": "advertising-api.amazon.com",
+        "eu": "advertising-api-eu.amazon.com",
+        "fe": "advertising-api-fe.amazon.com",
+    }
+
+    # Region display names for UI/logging
+    REGION_NAMES: Dict[RegionCode, str] = {
+        "na": "North America",
+        "eu": "Europe",
+        "fe": "Far East",
+    }
+
+    # Default region if none specified
+    DEFAULT_REGION: RegionCode = "na"
+
+    @classmethod
+    def get_api_endpoint(cls, region: Optional[str] = None) -> str:
+        """Get API endpoint URL for the specified region.
+
+        :param region: Region code (na, eu, fe) or None for default
+        :type region: Optional[str]
+        :return: Full API endpoint URL
+        :rtype: str
+
+        Example:
+            >>> RegionConfig.get_api_endpoint("eu")
+            'https://advertising-api-eu.amazon.com'
+        """
+        if region is None:
+            region = cls.DEFAULT_REGION
+        region = region.lower()
+        return cls.API_ENDPOINTS.get(region, cls.API_ENDPOINTS[cls.DEFAULT_REGION])
+
+    @classmethod
+    def get_oauth_endpoint(cls, region: Optional[str] = None) -> str:
+        """Get OAuth token endpoint URL for the specified region.
+
+        :param region: Region code (na, eu, fe) or None for default
+        :type region: Optional[str]
+        :return: Full OAuth token endpoint URL
+        :rtype: str
+
+        Example:
+            >>> RegionConfig.get_oauth_endpoint("fe")
+            'https://api.amazon.co.jp/auth/o2/token'
+        """
+        if region is None:
+            region = cls.DEFAULT_REGION
+        region = region.lower()
+        return cls.OAUTH_ENDPOINTS.get(region, cls.OAUTH_ENDPOINTS[cls.DEFAULT_REGION])
+
+    @classmethod
+    def get_api_host(cls, region: Optional[str] = None) -> str:
+        """Get API host (without protocol) for the specified region.
+
+        :param region: Region code (na, eu, fe) or None for default
+        :type region: Optional[str]
+        :return: API host without https://
+        :rtype: str
+
+        Example:
+            >>> RegionConfig.get_api_host("eu")
+            'advertising-api-eu.amazon.com'
+        """
+        if region is None:
+            region = cls.DEFAULT_REGION
+        region = region.lower()
+        return cls.API_HOSTS.get(region, cls.API_HOSTS[cls.DEFAULT_REGION])
+
+    @classmethod
+    def get_region_from_url(cls, url: str) -> str:
+        """Extract region code from an API or OAuth URL.
+
+        :param url: URL to parse for region
+        :type url: str
+        :return: Region code (na, eu, fe)
+        :rtype: str
+
+        Example:
+            >>> RegionConfig.get_region_from_url("https://advertising-api-eu.amazon.com/v2/profiles")
+            'eu'
+        """
+        if not url:
+            return cls.DEFAULT_REGION
+
+        # Parse URL and extract hostname only
+        parsed = urlparse(url)
+        hostname = (parsed.hostname or parsed.netloc or "").lower()
+
+        if not hostname:
+            return cls.DEFAULT_REGION
+
+        # Check for EU indicators in hostname only
+        if "-eu." in hostname or hostname.endswith(".co.uk") or "api-eu" in hostname:
+            return "eu"
+
+        # Check for FE indicators in hostname only
+        if "-fe." in hostname or hostname.endswith(".co.jp") or "api-fe" in hostname:
+            return "fe"
+
+        # Default to NA
+        return "na"
+
+    @classmethod
+    def is_valid_region(cls, region: str) -> bool:
+        """Check if a region code is valid.
+
+        :param region: Region code to validate
+        :type region: str
+        :return: True if valid, False otherwise
+        :rtype: bool
+
+        Example:
+            >>> RegionConfig.is_valid_region("eu")
+            True
+            >>> RegionConfig.is_valid_region("invalid")
+            False
+        """
+        if not region:
+            return False
+        return region.lower() in cls.API_ENDPOINTS
+
+    @classmethod
+    def get_region_name(cls, region: Optional[str] = None) -> str:
+        """Get display name for a region.
+
+        :param region: Region code (na, eu, fe) or None for default
+        :type region: Optional[str]
+        :return: Human-readable region name
+        :rtype: str
+
+        Example:
+            >>> RegionConfig.get_region_name("na")
+            'North America'
+        """
+        if region is None:
+            region = cls.DEFAULT_REGION
+        region = region.lower()
+        return cls.REGION_NAMES.get(region, cls.REGION_NAMES[cls.DEFAULT_REGION])
+
+    @classmethod
+    def get_all_regions(cls) -> Dict[str, Dict[str, str]]:
+        """Get all region configurations.
+
+        :return: Dictionary of all regions with their configurations
+        :rtype: Dict[str, Dict[str, str]]
+
+        Example:
+            >>> regions = RegionConfig.get_all_regions()
+            >>> regions["na"]["api_endpoint"]
+            'https://advertising-api.amazon.com'
+        """
+        result = {}
+        for region in cls.API_ENDPOINTS.keys():
+            result[region] = {
+                "code": region,
+                "name": cls.get_region_name(region),
+                "api_endpoint": cls.get_api_endpoint(region),
+                "oauth_endpoint": cls.get_oauth_endpoint(region),
+                "api_host": cls.get_api_host(region),
+            }
+        return result

amazon_ads_mcp/utils/response_wrapper.py

@@ -0,0 +1,171 @@
+"""Response wrapper to avoid manipulating private httpx attributes."""
+
+import json
+import logging
+from typing import Any, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseWrapper:
+    """
+    Wrapper for HTTP responses that avoids accessing private attributes.
+
+    This wrapper provides a clean interface for response manipulation
+    without relying on httpx internals.
+    """
+
+    def __init__(self, response: httpx.Response):
+        """
+        Initialize the response wrapper.
+
+        Args:
+            response: The original httpx response
+        """
+        self.original_response = response
+        self._modified_content: Optional[bytes] = None
+        self._modified_json: Optional[Any] = None
+
+    @property
+    def status_code(self) -> int:
+        """Get the status code."""
+        return self.original_response.status_code
+
+    @property
+    def headers(self) -> httpx.Headers:
+        """Get the response headers."""
+        return self.original_response.headers
+
+    @property
+    def content(self) -> bytes:
+        """Get the response content, either modified or original."""
+        if self._modified_content is not None:
+            return self._modified_content
+        return self.original_response.content
+
+    def json(self) -> Any:
+        """Get the JSON content, either modified or original."""
+        if self._modified_json is not None:
+            return self._modified_json
+        if self._modified_content is not None:
+            return json.loads(self._modified_content)
+        return self.original_response.json()
+
+    def set_content(self, content: bytes):
+        """
+        Set modified content.
+
+        Args:
+            content: The new content bytes
+        """
+        self._modified_content = content
+        self._modified_json = None  # Clear JSON cache
+
+    def set_json(self, data: Any):
+        """
+        Set modified JSON content.
+
+        Args:
+            data: The new JSON data
+        """
+        self._modified_json = data
+        self._modified_content = json.dumps(data).encode("utf-8")
+
+    def modify_json(self, modifier: callable) -> "ResponseWrapper":
+        """
+        Modify JSON content with a function.
+
+        Args:
+            modifier: Function that takes JSON data and returns modified data
+
+        Returns:
+            Self for chaining
+        """
+        try:
+            current_json = self.json()
+            modified_json = modifier(current_json)
+            self.set_json(modified_json)
+        except Exception as e:
+            logger.warning(f"Failed to modify JSON response: {e}")
+        return self
+
+
+def shape_amc_response(response: httpx.Response) -> httpx.Response:
+    """
+    Shape AMC responses without accessing private attributes.
+
+    Args:
+        response: The original response
+
+    Returns:
+        The response (potentially modified)
+    """
+    try:
+        # Check if this is an AMC response that needs shaping
+        if response.status_code != 200:
+            return response
+
+        content_type = response.headers.get("content-type", "")
+        if "application/json" not in content_type:
+            return response
+
+        # Parse response
+        try:
+            data = response.json()
+        except Exception:
+            return response
+
+        # Check if shaping is needed
+        modified = False
+
+        # Handle data wrapper
+        if isinstance(data, dict) and "data" in data:
+            # Unwrap single data element
+            if isinstance(data["data"], list) and len(data["data"]) == 1:
+                data = data["data"][0]
+                modified = True
+
+        # Handle ISO date conversion
+        if isinstance(data, dict):
+            for key, value in data.items():
+                if isinstance(value, str) and "T" in value and "Z" in value:
+                    # Looks like ISO date, leave as-is (don't convert to epoch)
+                    pass
+
+        if modified:
+            # Create a new response with modified content
+            # Instead of modifying private _content attribute
+            content_bytes = json.dumps(data).encode("utf-8")
+
+            # Create new response object
+            new_response = httpx.Response(
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                content=content_bytes,
+                request=response.request,
+            )
+
+            # Update content-length header
+            new_response.headers["content-length"] = str(len(content_bytes))
+
+            return new_response
+
+    except Exception as e:
+        logger.debug(f"AMC response shaping failed: {e}")
+
+    return response
+
+
+def wrap_response(response: httpx.Response) -> ResponseWrapper:
+    """
+    Wrap an httpx response for safe manipulation.
+
+    Args:
+        response: The original response
+
+    Returns:
+        Wrapped response
+    """
+    return ResponseWrapper(response)