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

amazon_ads_mcp/tools/__init__.py

@@ -0,0 +1,22 @@
+"""Tools module for Amazon Ads MCP.
+
+This module provides MCP tools for Amazon Ads API integration,
+including identity management and API operation tools.
+
+:var __all__: List of public exports from this module
+:type __all__: List[str]
+"""
+
+from .identity import (
+    get_active_identity,
+    get_identity_info,
+    list_remote_identities,
+    set_active_identity,
+)
+
+__all__ = [
+    "list_remote_identities",
+    "get_active_identity",
+    "set_active_identity",
+    "get_identity_info",
+]

amazon_ads_mcp/tools/cache_management.py

@@ -0,0 +1,105 @@
+"""Cache management tools for MCP server.
+
+This module provides tools for managing and clearing caches
+to ensure fresh data is fetched from the API.
+"""
+
+import logging
+from typing import Dict
+
+from ..auth.manager import get_auth_manager
+
+logger = logging.getLogger(__name__)
+
+
+async def clear_identity_cache() -> Dict:
+    """Clear the OpenBridge identity cache to force fresh fetch.
+
+    This function clears the cached identities in the OpenBridge provider
+    to ensure the next call to list_identities fetches fresh data from
+    the API instead of returning cached results.
+
+    :return: Status of the cache clearing operation
+    :rtype: Dict
+    """
+    try:
+        auth_manager = get_auth_manager()
+
+        # Check if provider has cache
+        if hasattr(auth_manager.provider, "_identities_cache"):
+            cache_size = len(auth_manager.provider._identities_cache)
+            auth_manager.provider._identities_cache.clear()
+            logger.info(f"Cleared identity cache ({cache_size} entries)")
+
+            return {
+                "success": True,
+                "message": f"Identity cache cleared ({cache_size} entries removed)",
+                "cache_size_before": cache_size,
+                "cache_size_after": 0,
+            }
+        else:
+            return {
+                "success": True,
+                "message": "No identity cache found (provider may not use caching)",
+                "cache_size_before": 0,
+                "cache_size_after": 0,
+            }
+
+    except Exception as e:
+        logger.error(f"Failed to clear identity cache: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "message": "Failed to clear identity cache",
+        }
+
+
+async def get_cache_status() -> Dict:
+    """Get the current status of the identity cache.
+
+    Returns information about the current cache state including
+    the number of cached entries and their keys.
+
+    :return: Cache status information
+    :rtype: Dict
+    """
+    try:
+        auth_manager = get_auth_manager()
+
+        if hasattr(auth_manager.provider, "_identities_cache"):
+            cache = auth_manager.provider._identities_cache
+            cache_keys = list(cache.keys())
+            cache_size = len(cache)
+
+            # Count identities in cache
+            total_identities = 0
+            cache_details = []
+            for key in cache_keys:
+                identities = cache[key]
+                total_identities += len(identities)
+                cache_details.append(
+                    {"key": str(key), "identity_count": len(identities)}
+                )
+
+            return {
+                "success": True,
+                "cache_enabled": True,
+                "cache_size": cache_size,
+                "total_identities_cached": total_identities,
+                "cache_entries": cache_details,
+                "message": f"Cache contains {cache_size} entries with {total_identities} total identities",
+            }
+        else:
+            return {
+                "success": True,
+                "cache_enabled": False,
+                "message": "No identity cache found",
+            }
+
+    except Exception as e:
+        logger.error(f"Failed to get cache status: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "message": "Failed to get cache status",
+        }

amazon_ads_mcp/tools/download_tools.py

@@ -0,0 +1,267 @@
+"""Download management tools for Amazon Ads MCP server.
+
+This module provides tools for managing downloads of exports and reports
+from the Amazon Ads API. It handles export status checking, file
+downloading, local file management, and cleanup operations.
+
+The tools integrate with the export download handler to provide a
+unified interface for managing downloaded data files.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..utils.export_download_handler import get_download_handler
+
+logger = logging.getLogger(__name__)
+
+
+async def check_and_download_export(
+    export_id: str,
+    export_response: Dict[str, Any],
+    export_type: Optional[str] = None,
+    profile_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Check export status and download if ready.
+
+    This function checks the status of an export and attempts to download
+    it if it's ready. It can infer the export type from the export ID
+    if not provided, and handles various export statuses appropriately.
+
+    :param export_id: The export ID to check and download
+    :type export_id: str
+    :param export_response: Response from the GetExport API call
+    :type export_response: Dict[str, Any]
+    :param export_type: Optional export type (campaign, adgroup, etc.)
+    :type export_type: Optional[str]
+    :param profile_id: Optional profile ID for scoped storage
+    :type profile_id: Optional[str]
+    :return: Dictionary containing status and download information
+    :rtype: Dict[str, Any]
+    """
+    handler = get_download_handler()
+
+    # Infer export type from response if not provided
+    if not export_type and export_id:
+        # Try to decode from export ID
+        import base64
+
+        try:
+            padded = export_id + "=" * (4 - len(export_id) % 4)
+            decoded = base64.b64decode(padded).decode("utf-8")
+            if "," in decoded:
+                _, suffix = decoded.rsplit(",", 1)
+                type_map = {
+                    "C": "campaigns",
+                    "A": "adgroups",
+                    "AD": "ads",
+                    "T": "targets",
+                }
+                export_type = type_map.get(suffix.upper(), "general")
+        except (AttributeError, TypeError, ValueError, KeyError):
+            export_type = "general"
+
+    # Handle the export response with profile scoping
+    file_path = await handler.handle_export_response(
+        export_response, export_type, profile_id=profile_id
+    )
+
+    if file_path:
+        return {
+            "success": True,
+            "status": "downloaded",
+            "file_path": str(file_path),
+            "export_id": export_id,
+            "message": f"Export downloaded successfully to {file_path}",
+        }
+    else:
+        status = export_response.get("status", "UNKNOWN")
+        if status == "PROCESSING":
+            return {
+                "success": False,
+                "status": "processing",
+                "export_id": export_id,
+                "message": "Export is still being processed. Check again later.",
+            }
+        elif status == "FAILED":
+            error = export_response.get("error", {})
+            return {
+                "success": False,
+                "status": "failed",
+                "export_id": export_id,
+                "error": error,
+                "message": f"Export failed: {error.get('message', 'Unknown error')}",
+            }
+        else:
+            return {
+                "success": False,
+                "status": status.lower(),
+                "export_id": export_id,
+                "message": f"Export has status {status} - no download available",
+            }
+
+
+async def list_downloaded_files(
+    resource_type: Optional[str] = None,
+    profile_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """List all downloaded files in the data directory.
+
+    Scans the data directory for downloaded files and provides a summary
+    of all available downloads. Can filter by resource type to show only
+    specific types of downloads.
+
+    When profile_id is provided:
+        - Lists files only from data/profiles/{profile_id}/
+
+    When profile_id is None:
+        - Lists files only from legacy (non-profile) directories
+
+    :param resource_type: Optional filter to show only specific resource types
+    :type resource_type: Optional[str]
+    :param profile_id: Optional profile ID for scoped listing
+    :type profile_id: Optional[str]
+    :return: Dictionary containing download summary and file listings
+    :rtype: Dict[str, Any]
+    """
+    handler = get_download_handler()
+    # handler.list_downloads returns a flat list of file dicts
+    files = handler.list_downloads(resource_type, profile_id=profile_id)
+
+    # Calculate totals from the flat list
+    total_files = len(files)
+    total_size = sum(f.get("size", 0) for f in files)
+
+    return {
+        "base_directory": str(handler.base_dir),
+        "total_files": total_files,
+        "total_size_bytes": total_size,
+        "files": files,  # Flat list format
+    }
+
+
+async def get_download_metadata(file_path: str) -> Dict[str, Any]:
+    """Get metadata for a downloaded file.
+
+    Retrieves metadata associated with a downloaded file, including
+    any custom metadata stored alongside the file. Falls back to
+    basic file information if no metadata is available.
+
+    :param file_path: Path to the downloaded file
+    :type file_path: str
+    :return: Dictionary containing file metadata and status
+    :rtype: Dict[str, Any]
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        return {
+            "success": False,
+            "error": "File not found",
+            "file_path": file_path,
+        }
+
+    meta_path = path.with_suffix(".meta.json")
+
+    if meta_path.exists():
+        with open(meta_path) as f:
+            metadata = json.load(f)
+        return {"success": True, "file_path": file_path, "metadata": metadata}
+    else:
+        # Return basic file info
+        stat = path.stat()
+        return {
+            "success": True,
+            "file_path": file_path,
+            "metadata": {
+                "file_name": path.name,
+                "file_size": stat.st_size,
+                "modified": stat.st_mtime,
+                "note": "No detailed metadata available",
+            },
+        }
+
+
+async def clean_old_downloads(
+    profile_id: str,
+    resource_type: Optional[str] = None,
+    days_old: int = 7,
+) -> Dict[str, Any]:
+    """Clean up old downloaded files for a specific profile.
+
+    Removes downloaded files that are older than the specified number
+    of days within the profile's storage directory. This helps manage
+    disk space by cleaning up outdated export data. Can filter by
+    resource type to clean only specific types of downloads.
+
+    IMPORTANT: This function is profile-scoped to maintain multi-tenant
+    isolation. It only deletes files within data/profiles/{profile_id}/.
+
+    :param profile_id: Profile ID for scoped cleanup (required)
+    :type profile_id: str
+    :param resource_type: Optional filter by resource type
+    :type resource_type: Optional[str]
+    :param days_old: Delete files older than this many days
+    :type days_old: int
+    :return: Dictionary containing cleanup summary and deleted file list
+    :rtype: Dict[str, Any]
+    """
+    from datetime import datetime, timedelta
+
+    if not profile_id:
+        return {
+            "success": False,
+            "error": "profile_id is required for cleanup operations",
+            "deleted_files": 0,
+            "deleted_size_bytes": 0,
+            "files": [],
+        }
+
+    handler = get_download_handler()
+    cutoff_date = datetime.now() - timedelta(days=days_old)
+
+    # Use profile-scoped base directory for multi-tenant isolation
+    profile_base = handler.get_profile_base_dir(profile_id)
+
+    deleted_files = []
+    deleted_size = 0
+
+    if resource_type:
+        search_paths = [profile_base / resource_type]
+    else:
+        # Only search directories within the profile's storage
+        search_paths = [
+            p for p in profile_base.iterdir() if p.is_dir()
+        ] if profile_base.exists() else []
+
+    for resource_dir in search_paths:
+        if not resource_dir.exists():
+            continue
+
+        for sub_dir in resource_dir.iterdir():
+            if sub_dir.is_dir():
+                for file_path in sub_dir.iterdir():
+                    if file_path.is_file():
+                        stat = file_path.stat()
+                        modified = datetime.fromtimestamp(stat.st_mtime)
+
+                        if modified < cutoff_date:
+                            deleted_size += stat.st_size
+                            deleted_files.append(str(file_path))
+
+                            # Delete the file and its metadata
+                            file_path.unlink()
+                            meta_path = file_path.with_suffix(".meta.json")
+                            if meta_path.exists():
+                                meta_path.unlink()
+
+    return {
+        "success": True,
+        "profile_id": profile_id,
+        "deleted_files": len(deleted_files),
+        "deleted_size_bytes": deleted_size,
+        "files": deleted_files,
+        "message": f"Deleted {len(deleted_files)} files older than {days_old} days for profile {profile_id}",
+    }

amazon_ads_mcp/tools/identity.py

@@ -0,0 +1,236 @@
+"""MCP tools for identity management.
+
+This module provides MCP tools for managing remote identities
+for Amazon Ads API access, including listing, selecting, and
+querying identity information.
+
+The tools provide:
+
+- List all available remote identities from OpenBridge
+- Set active identity for Amazon Ads API operations
+- Get current active identity information
+- Get detailed information about specific identities
+- Comprehensive error handling and logging
+
+Examples:
+    >>> identities = await list_remote_identities()
+    >>> active = await get_active_identity()
+    >>> response = await set_active_identity(
+    ...     SetActiveIdentityRequest(identity_id="123")
+    ... )
+"""
+
+import logging
+from typing import Optional
+
+from ..auth.manager import get_auth_manager
+from ..models import (
+    Identity,
+    IdentityListResponse,
+    SetActiveIdentityRequest,
+    SetActiveIdentityResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def list_remote_identities(
+    identity_type: Optional[str] = "14",
+) -> IdentityListResponse:
+    """List all available Amazon Ads remote identities.
+
+    Returns a list of remote identities that can be used to access
+    different Amazon Ads accounts through OpenBridge. By default, filters
+    for Amazon Ads identities (type 14). The function handles both
+    OpenBridge and direct authentication providers.
+
+    The function automatically determines the provider type and calls the
+    appropriate method for listing identities. For OpenBridge providers,
+    it passes the identity_type filter to get only relevant identities.
+
+    :param identity_type: Filter by remote identity type (default "14" for Amazon Ads)
+    :type identity_type: Optional[str]
+    :return: Response containing the list of available identities
+    :rtype: IdentityListResponse
+    :raises Exception: If listing identities fails
+
+    .. note::
+       Identity type "14" corresponds to Amazon Ads identities in OpenBridge.
+
+    .. example::
+       >>> response = await list_remote_identities()
+       >>> print(f"Found {response.total} identities")
+    """
+    logger.info(f"Listing remote identities (type={identity_type})")
+
+    try:
+        auth_manager = get_auth_manager()
+        # Pass the identity_type filter to the provider
+        if hasattr(auth_manager.provider, "list_identities"):
+            identities = await auth_manager.provider.list_identities(
+                identity_type=identity_type
+            )
+        else:
+            identities = await auth_manager.list_identities()
+
+        return IdentityListResponse(
+            identities=identities, total=len(identities), has_more=False
+        )
+    except Exception as e:
+        logger.error(f"Failed to list identities: {e}")
+        raise
+
+
+async def get_active_identity() -> Optional[Identity]:
+    """Get the currently active remote identity.
+
+    Returns the identity that is currently being used for Amazon Ads API calls.
+    This function provides access to the currently selected identity
+    and logs information about it for debugging purposes.
+
+    The function retrieves the active identity from the authentication manager
+    and logs relevant information for troubleshooting.
+
+    :return: The active Identity, or None if no identity is set
+    :rtype: Optional[Identity]
+
+    .. example::
+       >>> identity = await get_active_identity()
+       >>> if identity:
+       ...     print(f"Active: {identity.attributes.get('name')}")
+    """
+    logger.info("Getting active identity")
+
+    auth_manager = get_auth_manager()
+    active_identity = auth_manager.get_active_identity()
+
+    if active_identity:
+        name = active_identity.attributes.get("name", active_identity.id)
+        logger.info(f"Active identity: {name} ({active_identity.id})")
+    else:
+        logger.info("No active identity set")
+
+    return active_identity
+
+
+async def set_active_identity(
+    request: SetActiveIdentityRequest,
+) -> SetActiveIdentityResponse:
+    """Set the active remote identity for Amazon Ads API operations.
+
+    This identity will be used for all subsequent Amazon Ads API calls
+    until a different identity is selected. The function also attempts
+    to pre-load credentials for the selected identity.
+
+    The function performs identity validation and credential pre-loading
+    to ensure the selected identity is ready for use. If credential
+    loading fails, the identity is still set but a warning is included
+    in the response.
+
+    :param request: Request containing the identity_id to activate
+    :type request: SetActiveIdentityRequest
+    :return: Response indicating success and the activated identity
+    :rtype: SetActiveIdentityResponse
+    :raises ValueError: If the specified identity is invalid
+    :raises Exception: If setting the active identity fails
+
+    .. example::
+       >>> request = SetActiveIdentityRequest(identity_id="abc123")
+       >>> response = await set_active_identity(request)
+       >>> if response.success:
+       ...     print("Identity activated successfully")
+    """
+    logger.info(f"Setting active identity: {request.identity_id}")
+
+    try:
+        auth_manager = get_auth_manager()
+
+        # Set the active identity
+        identity = await auth_manager.set_active_identity(request.identity_id)
+
+        # Try to pre-load credentials
+        credentials_loaded = False
+        message = None
+        try:
+            await auth_manager.get_active_credentials()
+            credentials_loaded = True
+            logger.info("Credentials pre-loaded successfully")
+        except Exception as e:
+            message = f"Identity set but credentials not loaded: {str(e)}"
+            logger.warning(message)
+
+        return SetActiveIdentityResponse(
+            success=True,
+            identity=identity,
+            credentials_loaded=credentials_loaded,
+            message=message,
+        )
+
+    except ValueError as e:
+        logger.error(f"Invalid identity: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Failed to set active identity: {e}")
+        raise
+
+
+async def get_identity_info(identity_id: str) -> Optional[Identity]:
+    """Get detailed information about a specific remote identity.
+
+    Retrieves detailed information about a specific remote identity
+    by its unique identifier. This function is useful for getting
+    additional details about an identity before selecting it.
+
+    The function queries the authentication manager for the specified
+    identity and returns its details including attributes and metadata.
+
+    :param identity_id: The ID of the identity to retrieve
+    :type identity_id: str
+    :return: The Identity if found, None otherwise
+    :rtype: Optional[Identity]
+    :raises Exception: If retrieving identity info fails
+
+    .. example::
+       >>> identity = await get_identity_info("abc123")
+       >>> if identity:
+       ...     name = identity.attributes.get("name", "Unknown")
+       ...     print(f"Identity: {name}")
+    """
+    logger.info(f"Getting identity info for: {identity_id}")
+
+    try:
+        auth_manager = get_auth_manager()
+        identity = await auth_manager.get_identity(identity_id)
+
+        if identity:
+            name = identity.attributes.get("name", identity.id)
+            logger.info(f"Found identity: {name}")
+        else:
+            logger.info(f"Identity not found: {identity_id}")
+
+        return identity
+    except Exception as e:
+        logger.error(f"Failed to get identity info: {e}")
+        raise
+
+
+async def list_identities() -> IdentityListResponse:
+    """List all available identities.
+
+    Retrieves a list of all available identities from the current
+    authentication provider. This is a simplified wrapper around
+    list_remote_identities for common use cases.
+
+    This function uses the default identity type filter and is equivalent
+    to calling list_remote_identities() with no parameters.
+
+    :return: List of available identities
+    :rtype: IdentityListResponse
+    :raises Exception: If listing identities fails
+
+    .. example::
+       >>> identities = await list_identities()
+       >>> for identity in identities.identities:
+       ...     print(f"ID: {identity.id}")
+    """
+    return await list_remote_identities()