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

amazon_ads_mcp/utils/media/__init__.py

@@ -0,0 +1,21 @@
+"""Media utilities public API (re-exports)."""
+
+from .negotiator import (
+    EnhancedMediaTypeRegistry,
+    ResourceTypeNegotiator,
+    create_enhanced_registry,
+)
+from .types import (
+    MediaTypeRegistry,
+    build_media_maps_from_spec,
+    split_method_path_key,
+)
+
+__all__ = [
+    "MediaTypeRegistry",
+    "split_method_path_key",
+    "build_media_maps_from_spec",
+    "ResourceTypeNegotiator",
+    "EnhancedMediaTypeRegistry",
+    "create_enhanced_registry",
+]

amazon_ads_mcp/utils/media/negotiator.py

@@ -0,0 +1,243 @@
+"""Media type negotiation helpers.
+
+This module provides functionality for negotiating media types based on
+resource types and URL patterns. It includes a resource type negotiator
+that can determine appropriate content types for specific resources,
+particularly for export operations where the content type depends on
+the export ID and resource type.
+
+The module also provides an enhanced media type registry that combines
+base registry functionality with negotiation capabilities.
+"""
+
+import base64
+import logging
+import re
+from typing import Callable, Dict, List, Optional
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+def _decode_export_id(export_id: str) -> Optional[str]:
+    pad_len = (-len(export_id)) % 4
+    padded = export_id + ("=" * pad_len)
+    for decoder in (base64.urlsafe_b64decode, base64.b64decode):
+        try:
+            return decoder(padded).decode("utf-8")
+        except Exception:
+            continue
+    return None
+
+
+class ResourceTypeNegotiator:
+    """Negotiator for determining media types based on resource types.
+
+    This class provides a framework for negotiating appropriate media
+    types based on the resource type extracted from URLs. It supports
+    registering custom negotiators for different resource types and
+    includes built-in negotiation logic for export operations.
+
+    The negotiator extracts resource types from URL paths and applies
+    type-specific logic to determine the most appropriate content type
+    from available options.
+    """
+
+    def __init__(self):
+        """Initialize the resource type negotiator.
+
+        Sets up internal storage for negotiator functions and registers
+        the default negotiator for export operations.
+        """
+        self._negotiators: Dict[
+            str, Callable[[str, str, List[str]], Optional[str]]
+        ] = {}
+        self._register_default_negotiators()
+
+    def _register_default_negotiators(self):
+        """Register the default negotiator for export operations.
+
+        Sets up the built-in negotiator for handling export resource
+        types, which determines content types based on export ID suffixes.
+        """
+        self.register_negotiator("exports", self._negotiate_exports)
+
+    def register_negotiator(
+        self,
+        resource_type: str,
+        negotiator: Callable[[str, str, List[str]], Optional[str]],
+    ):
+        """Register a custom negotiator function for a resource type.
+
+        :param resource_type: The resource type to register the negotiator for
+        :type resource_type: str
+        :param negotiator: Function that implements negotiation logic for the
+                          resource type
+        :type negotiator: Callable[[str, str, List[str]], Optional[str]]
+        """
+        self._negotiators[resource_type.lower()] = negotiator
+        logger.debug("Registered negotiator for resource type: %s", resource_type)
+
+    def negotiate(
+        self, method: str, url: str, available_types: List[str]
+    ) -> Optional[str]:
+        """Negotiate the appropriate media type for a request.
+
+        Extracts the resource type from the URL and applies the appropriate
+        negotiator to determine the best content type from the available
+        options. Falls back gracefully if negotiation fails.
+
+        :param method: HTTP method of the request
+        :type method: str
+        :param url: URL to negotiate media type for
+        :type url: str
+        :param available_types: List of available content types to choose from
+        :type available_types: List[str]
+        :return: Negotiated content type or None if negotiation fails
+        :rtype: Optional[str]
+        """
+        resource_type = self._extract_resource_type(url)
+        if resource_type and resource_type in self._negotiators:
+            try:
+                result = self._negotiators[resource_type](method, url, available_types)
+                if result:
+                    logger.debug("Negotiated %s for %s resource", result, resource_type)
+                    return result
+            except Exception as e:
+                logger.warning("Negotiator failed for %s: %s", resource_type, e)
+        return None
+
+    def _extract_resource_type(self, url: str) -> Optional[str]:
+        """Extract the resource type from a URL path.
+
+        Parses the URL path to identify the resource type, handling
+        version prefixes and normalizing the result.
+
+        :param url: URL to extract resource type from
+        :type url: str
+        :return: Resource type string or None if extraction fails
+        :rtype: Optional[str]
+        """
+        path = urlparse(url).path
+        path = re.sub(r"^/v\d+/", "/", path)
+        match = re.match(r"^/([^/]+)", path)
+        if match:
+            return match.group(1).lower()
+        return None
+
+    def _negotiate_exports(
+        self, method: str, url: str, available_types: List[str]
+    ) -> Optional[str]:
+        """Negotiate media type for export operations.
+
+        This negotiator handles export-specific media type determination
+        by decoding the export ID from the URL and mapping suffix codes
+        to appropriate content types. It only processes GET requests
+        and expects URLs in the format /exports/{export_id}.
+
+        :param method: HTTP method of the request
+        :type method: str
+        :param url: URL containing the export ID
+        :type url: str
+        :param available_types: List of available content types
+        :type available_types: List[str]
+        :return: Appropriate content type for the export or None if
+                 negotiation fails
+        :rtype: Optional[str]
+        """
+        if method.upper() != "GET":
+            return None
+        m = re.search(r"/exports/([^/?]+)", url)
+        if not m:
+            return None
+        export_id = m.group(1)
+        try:
+            decoded = _decode_export_id(export_id)
+            if not decoded:
+                return None
+            if "," in decoded:
+                _, suffix = decoded.rsplit(",", 1)
+                suffix_map = {
+                    "C": "application/vnd.campaignsexport.v1+json",
+                    "A": "application/vnd.adgroupsexport.v1+json",
+                    "AD": "application/vnd.adsexport.v1+json",
+                    # Some export IDs use ',R' for ads exports.
+                    "R": "application/vnd.adsexport.v1+json",
+                    "T": "application/vnd.targetsexport.v1+json",
+                }
+                ct = suffix_map.get(suffix.upper())
+                if ct and ct in available_types:
+                    return ct
+        except Exception:
+            pass
+        return None
+
+
+class EnhancedMediaTypeRegistry:
+    """Enhanced media type registry with negotiation capabilities.
+
+    This class extends a base media type registry with negotiation
+    functionality. It can resolve media types using the base registry
+    and then apply negotiation logic when multiple content types are
+    available to select the most appropriate one.
+    """
+
+    def __init__(self, base_registry):
+        """Initialize the enhanced registry with a base registry.
+
+        :param base_registry: Base media type registry to extend
+        :type base_registry: Any
+        """
+        self.base_registry = base_registry
+        self.negotiator = ResourceTypeNegotiator()
+
+    def resolve(self, method: str, url: str):
+        """Resolve media types with optional negotiation.
+
+        First attempts to resolve media types using the base registry.
+        If multiple response content types are available, applies
+        negotiation to select the most appropriate one.
+
+        :param method: HTTP method of the request
+        :type method: str
+        :param url: URL to resolve media types for
+        :type url: str
+        :return: Tuple of (request_content_type, response_content_types)
+        :rtype: tuple
+        """
+        content_type, accepts = self.base_registry.resolve(method, url)
+        if accepts and len(accepts) > 1:
+            negotiated = self.negotiator.negotiate(method, url, accepts)
+            if negotiated:
+                return content_type, [negotiated]
+        return content_type, accepts
+
+    def add_negotiator(self, resource_type: str, negotiator: Callable):
+        """Add a custom negotiator for a specific resource type.
+
+        :param resource_type: Resource type to add negotiator for
+        :type resource_type: str
+        :param negotiator: Negotiation function to register
+        :type negotiator: Callable
+        """
+        self.negotiator.register_negotiator(resource_type, negotiator)
+
+
+def create_enhanced_registry(base_registry) -> EnhancedMediaTypeRegistry:
+    """Create an enhanced media type registry.
+
+    Factory function that creates an EnhancedMediaTypeRegistry instance
+    with the provided base registry.
+
+    :param base_registry: Base media type registry to enhance
+    :type base_registry: Any
+    :return: Enhanced media type registry instance
+    :rtype: EnhancedMediaTypeRegistry
+    """
+    return EnhancedMediaTypeRegistry(base_registry)
+
+
+__all__ = [
+    "ResourceTypeNegotiator",
+    "EnhancedMediaTypeRegistry",
+    "create_enhanced_registry",
+]

amazon_ads_mcp/utils/media/types.py

@@ -0,0 +1,199 @@
+"""Media type registry and resolution for OpenAPI specifications.
+
+This module provides functionality for managing and resolving media types
+from OpenAPI specifications and sidecar files. It includes a registry
+class that can build media type mappings from OpenAPI specs and resolve
+content types for specific HTTP methods and URL paths.
+
+The module handles both request and response media types, supports
+templated paths, and provides caching for performance optimization.
+"""
+
+import re
+from typing import Dict, List, Optional, Set, Tuple
+from urllib.parse import urlparse
+
+from amazon_ads_mcp.utils.openapi import deref, oai_template_to_regex
+
+
+class MediaTypeRegistry:
+    """Registry for managing media types from OpenAPI specs and sidecars.
+
+    This class maintains a registry of media types for both requests and
+    responses, extracted from OpenAPI specifications and sidecar files.
+    It provides methods to add media type mappings and resolve the
+    appropriate content types for specific HTTP methods and URL paths.
+
+    The registry supports templated paths and includes caching for
+    improved performance when resolving media types.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the media type registry.
+
+        Sets up internal storage for request entries, response entries,
+        and a cache for resolved media type lookups.
+        """
+        self._req_entries: List[Dict[Tuple[str, str], str]] = []
+        self._resp_entries: List[Dict[Tuple[str, str], List[str]]] = []
+        self._cache: Dict[
+            Tuple[str, str], Tuple[Optional[str], Optional[List[str]]]
+        ] = {}
+
+    def add_from_spec(self, spec: dict) -> None:
+        """Add media type mappings from an OpenAPI specification.
+
+        Extracts request and response media types from the provided
+        OpenAPI specification and adds them to the registry. Clears
+        the internal cache to ensure fresh lookups.
+
+        :param spec: OpenAPI specification dictionary
+        :type spec: dict
+        """
+        req_map, resp_map = build_media_maps_from_spec(spec)
+        self._req_entries.append(req_map)
+        self._resp_entries.append(resp_map)
+        self._cache.clear()
+
+    def add_from_sidecar(self, sidecar: dict) -> None:
+        """Add media type mappings from a sidecar configuration file.
+
+        Processes sidecar configuration to extract request and response
+        media type mappings. The sidecar should contain 'requests' and
+        'responses' sections with method+path keys and media type values.
+
+        :param sidecar: Sidecar configuration dictionary
+        :type sidecar: dict
+        """
+        req_map: Dict[Tuple[str, str], str] = {}
+        resp_map: Dict[Tuple[str, str], List[str]] = {}
+        for k, v in (sidecar.get("requests") or {}).items():
+            m, p = split_method_path_key(k)
+            if m and p and isinstance(v, str):
+                req_map[(m, p)] = v
+        for k, v in (sidecar.get("responses") or {}).items():
+            m, p = split_method_path_key(k)
+            if m and p and isinstance(v, list):
+                resp_map[(m, p)] = list(v)
+        if req_map or resp_map:
+            self._req_entries.append(req_map)
+            self._resp_entries.append(resp_map)
+            self._cache.clear()
+
+    def resolve(
+        self, method: str, url: str
+    ) -> Tuple[Optional[str], Optional[List[str]]]:
+        """Resolve media types for a specific HTTP method and URL.
+
+        Attempts to find the appropriate request and response media
+        types for the given method and URL. First checks for exact
+        matches, then falls back to templated path matching. Results
+        are cached for subsequent lookups.
+
+        :param method: HTTP method (e.g., 'GET', 'POST')
+        :type method: str
+        :param url: URL to resolve media types for
+        :type url: str
+        :return: Tuple of (request_media_type, response_media_types)
+        :rtype: Tuple[Optional[str], Optional[List[str]]]
+        """
+        m = (method or "get").lower()
+        path = (urlparse(url).path or "/").rstrip("/") or "/"
+        cache_key = (m, path)
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+        for req_map, resp_map in zip(self._req_entries, self._resp_entries):
+            if (m, path) in req_map or (m, path) in resp_map:
+                result = (req_map.get((m, path)), resp_map.get((m, path)))
+                self._cache[cache_key] = result
+                return result
+        for req_map, resp_map in zip(self._req_entries, self._resp_entries):
+            keys: Set[Tuple[str, str]] = set(req_map.keys()) | set(resp_map.keys())
+            for mm, templated in keys:
+                if mm != m:
+                    continue
+                if re.match(oai_template_to_regex(templated), path):
+                    result = (
+                        req_map.get((mm, templated)),
+                        resp_map.get((mm, templated)),
+                    )
+                    self._cache[cache_key] = result
+                    return result
+        result = (None, None)
+        self._cache[cache_key] = result
+        return result
+
+
+def split_method_path_key(key: str) -> Tuple[Optional[str], Optional[str]]:
+    """Split a method+path key into separate method and path components.
+
+    Parses keys in the format "METHOD /path" (e.g., "GET /users/{id}")
+    and returns the method and path as separate components. Handles
+    path normalization including leading slash addition and trailing
+    slash removal.
+
+    :param key: Method+path key string (e.g., "POST /api/users")
+    :type key: str
+    :return: Tuple of (method, path) or (None, None) if parsing fails
+    :rtype: Tuple[Optional[str], Optional[str]]
+    """
+    parts = (key or "").strip().split(" ", 1)
+    if len(parts) != 2:
+        return None, None
+    method = parts[0].lower()
+    path = parts[1].strip()
+    if not path.startswith("/"):
+        path = "/" + path
+    path = path.rstrip("/") or "/"
+    return method, path
+
+
+def build_media_maps_from_spec(
+    openapi_spec: dict,
+) -> Tuple[Dict[Tuple[str, str], str], Dict[Tuple[str, str], List[str]]]:
+    """Build media type mappings from an OpenAPI specification.
+
+    Extracts request and response media types from the OpenAPI spec's
+    paths section. For each operation, it identifies the content types
+    for request bodies and response content, building comprehensive
+    mappings keyed by method and path.
+
+    :param openapi_spec: OpenAPI specification dictionary
+    :type openapi_spec: dict
+    :return: Tuple of (request_media_map, response_media_map)
+    :rtype: Tuple[Dict[Tuple[str, str], str], Dict[Tuple[str, str], List[str]]]
+    """
+    req_media: Dict[Tuple[str, str], str] = {}
+    resp_media: Dict[Tuple[str, str], List[str]] = {}
+    paths = openapi_spec.get("paths", {}) or {}
+    for raw_path, ops in paths.items():
+        if not isinstance(ops, dict):
+            continue
+        norm_path = (raw_path or "/").rstrip("/") or "/"
+        for method, op in ops.items():
+            if not isinstance(op, dict):
+                continue
+            m = method.lower()
+            rb = deref(openapi_spec, op.get("requestBody"))
+            rb_content = (rb or {}).get("content", {}) if isinstance(rb, dict) else {}
+            if isinstance(rb_content, dict) and rb_content:
+                ct = sorted(rb_content.keys())[0]
+                req_media[(m, norm_path)] = ct
+            responses = (op.get("responses") or {}) if isinstance(op, dict) else {}
+            accepts: Set[str] = set()
+            if isinstance(responses, dict):
+                for _, r in responses.items():
+                    r = deref(openapi_spec, r)
+                    rc = (r or {}).get("content", {}) if isinstance(r, dict) else {}
+                    if isinstance(rc, dict):
+                        accepts.update(rc.keys())
+            if accepts:
+                resp_media[(m, norm_path)] = sorted(accepts)
+    return req_media, resp_media
+
+
+__all__ = [
+    "MediaTypeRegistry",
+    "split_method_path_key",
+    "build_media_maps_from_spec",
+]

amazon_ads_mcp/utils/openapi/__init__.py

@@ -0,0 +1,16 @@
+"""OpenAPI utilities public API (re-exports).
+
+Recommended imports:
+    from amazon_ads_mcp.utils.openapi import json_load, deref, oai_template_to_regex, OpenAPISpecLoader
+"""
+
+from .json import json_load, oai_template_to_regex
+from .loader import OpenAPISpecLoader
+from .refs import deref
+
+__all__ = [
+    "json_load",
+    "deref",
+    "oai_template_to_regex",
+    "OpenAPISpecLoader",
+]

amazon_ads_mcp/utils/openapi/json.py

@@ -0,0 +1,55 @@
+"""JSON and path helpers for OpenAPI specs.
+
+This module provides utility functions for working with JSON files and
+OpenAPI path templates. It includes functionality for loading JSON files
+with proper encoding and converting OpenAPI path templates to regular
+expressions for pattern matching.
+"""
+
+import json
+import re
+from pathlib import Path
+
+
+def json_load(path: Path) -> dict:
+    """Load JSON from a file path with UTF-8 encoding.
+
+    This function opens a JSON file at the specified path and loads
+    its contents as a Python dictionary. It ensures proper UTF-8
+    encoding handling and automatically closes the file after reading.
+
+    :param path: Path to the JSON file to load
+    :type path: Path
+    :return: Parsed JSON content as a dictionary
+    :rtype: dict
+    :raises FileNotFoundError: If the specified file path does not exist
+    :raises json.JSONDecodeError: If the file contains invalid JSON
+    """
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def oai_template_to_regex(path_template: str) -> str:
+    """Convert OpenAPI path template to regex pattern.
+
+    This function converts OpenAPI path templates (e.g., "/users/{id}/posts")
+    to regular expression patterns that can be used for matching actual
+    URL paths. It handles parameter placeholders by converting them to
+    regex patterns that match any non-slash characters.
+
+    The function ensures the resulting regex is anchored to the start and
+    end of the string, and handles trailing slashes appropriately.
+
+    :param path_template: OpenAPI path template string (e.g., "/users/{id}")
+    :type path_template: str
+    :return: Regular expression pattern string
+    :rtype: str
+    """
+    return (
+        "^"
+        + re.sub(r"\{[^/]+\}", r"[^/]+", path_template.rstrip("/") or "/")
+        + "$"
+    )
+
+
+__all__ = ["json_load", "oai_template_to_regex"]