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

amazon_ads_mcp/models/base_models.py

@@ -0,0 +1,215 @@
+"""Shared Pydantic models for the Amazon Ads MCP project.
+
+This module contains all the data models used throughout the Amazon Ads MCP
+server, including authentication tokens, identity management, API responses,
+and OpenBridge integration models.
+
+The models provide type safety and validation for:
+- Authentication and token management
+- Identity and profile management
+- API request/response handling
+- OpenBridge integration
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+# Auth Models
+class Token(BaseModel):
+    """Authentication token model for Amazon Ads API access.
+
+    Represents an OAuth2 access token with expiration and metadata.
+    Used for authenticating requests to the Amazon Advertising API.
+
+    :param value: The actual token string value
+    :type value: str
+    :param expires_at: When the token expires
+    :type expires_at: datetime
+    :param token_type: Type of token (default: "Bearer")
+    :type token_type: str
+    :param scope: Optional scope string for the token
+    :type scope: Optional[str]
+    :param metadata: Additional token metadata
+    :type metadata: Dict[str, Any]
+    """
+
+    value: str
+    expires_at: datetime
+    token_type: str = "Bearer"
+    scope: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class Identity(BaseModel):
+    """Simplified identity model - passthrough from Openbridge.
+
+    Represents a remote identity from OpenBridge with all
+    attributes and relationships preserved.
+
+    :param id: Unique identifier for the identity
+    :type id: str
+    :param type: Type of identity (default: "RemoteIdentity")
+    :type type: str
+    :param attributes: All attributes from Openbridge
+    :type attributes: Dict[str, Any]
+    :param relationships: All relationships from Openbridge
+    :type relationships: Optional[Dict[str, Any]]
+    """
+
+    id: str
+    type: str = "RemoteIdentity"
+    attributes: Dict[str, Any]
+    relationships: Optional[Dict[str, Any]] = None
+
+
+class AuthCredentials(BaseModel):
+    """Credentials for API access.
+
+    Contains all necessary authentication information for making
+    authenticated requests to the Amazon Advertising API.
+
+    :param identity_id: ID of the identity these credentials belong to
+    :type identity_id: str
+    :param access_token: OAuth2 access token for API authentication
+    :type access_token: str
+    :param token_type: Type of token (default: "Bearer")
+    :type token_type: str
+    :param expires_at: When the access token expires
+    :type expires_at: datetime
+    :param base_url: Base URL for API requests (default: Amazon API URL)
+    :type base_url: str
+    :param headers: Additional headers to include in requests
+    :type headers: Dict[str, str]
+    """
+
+    identity_id: str
+    access_token: str
+    token_type: str = "Bearer"
+    expires_at: datetime
+    base_url: str = "https://advertising-api.amazon.com"
+    headers: Dict[str, str] = Field(default_factory=dict)
+
+
+# API Models
+class AccountInfo(BaseModel):
+    """Account information model.
+
+    Represents account information returned by the Amazon Advertising API.
+    Contains marketplace details and account status information.
+
+    :param marketplace_string_id: Marketplace identifier string
+    :type marketplace_string_id: str
+    :param id: Account ID
+    :type id: str
+    :param type: Type of account
+    :type type: str
+    :param name: Account name
+    :type name: str
+    :param valid_payment_method: Whether account has valid payment method
+    :type valid_payment_method: Optional[bool]
+    """
+
+    marketplace_string_id: str = Field(alias="marketplaceStringId")
+    id: str
+    type: str
+    name: str
+    valid_payment_method: Optional[bool] = Field(
+        alias="validPaymentMethod", default=None
+    )
+
+
+class Profile(BaseModel):
+    """Amazon Ads Profile model.
+
+    Represents an Amazon Advertising profile with location, currency,
+    and budget information. Profiles are used to organize campaigns
+    and manage advertising accounts.
+
+    :param profile_id: Unique profile identifier
+    :type profile_id: int
+    :param country_code: ISO country code for the profile
+    :type country_code: str
+    :param currency_code: ISO currency code for the profile
+    :type currency_code: str
+    :param timezone: Timezone for the profile
+    :type timezone: str
+    :param daily_budget: Optional daily budget limit
+    :type daily_budget: Optional[float]
+    :param account_info: Associated account information
+    :type account_info: AccountInfo
+    """
+
+    profile_id: int = Field(alias="profileId")
+    country_code: str = Field(alias="countryCode")
+    currency_code: str = Field(alias="currencyCode")
+    timezone: str
+    daily_budget: Optional[float] = Field(alias="dailyBudget", default=None)
+    account_info: AccountInfo = Field(alias="accountInfo")
+
+    model_config = {"populate_by_name": True}
+
+
+# Request/Response Models
+class IdentityListResponse(BaseModel):
+    """Response model for identity list.
+
+    Represents a paginated response containing a list of available
+    identities that can be used for Amazon Ads API access.
+
+    :param identities: List of available identities
+    :type identities: List[Identity]
+    :param total: Total number of identities available
+    :type total: int
+    :param has_more: Whether there are more identities to fetch
+    :type has_more: bool
+    """
+
+    identities: List[Identity]
+    total: int
+    has_more: bool = False
+
+
+class SetActiveIdentityRequest(BaseModel):
+    """Request model for setting active identity.
+
+    Used when requesting to set a specific identity as the active
+    identity for Amazon Ads API operations.
+
+    :param identity_id: ID of the identity to activate
+    :type identity_id: str
+    :param persist: Whether to persist this choice across sessions
+    :type persist: bool
+    """
+
+    identity_id: str
+    persist: bool = False
+
+
+class SetActiveIdentityResponse(BaseModel):
+    """Response model for setting active identity.
+
+    Response indicating the result of setting an identity as active,
+    including whether credentials were successfully loaded.
+
+    :param success: Whether the operation was successful
+    :type success: bool
+    :param identity: The identity that was set as active
+    :type identity: Identity
+    :param credentials_loaded: Whether credentials were loaded for identity
+    :type credentials_loaded: bool
+    :param message: Optional message about the operation result
+    :type message: Optional[str]
+    """
+
+    success: bool
+    identity: Identity
+    credentials_loaded: bool = False
+    message: Optional[str] = None
+
+
+# OpenBridge API Models
+# OpenbridgeIdentity is now just an alias for Identity since we're passing through
+OpenbridgeIdentity = Identity

amazon_ads_mcp/models/builtin_responses.py

@@ -0,0 +1,496 @@
+"""Response models for builtin MCP tools.
+
+This module defines structured Pydantic response models for all builtin tools
+in the Amazon Ads MCP server. These models enable:
+- Client-side validation of tool responses
+- IDE autocompletion and type hints
+- Automatic JSON schema generation for MCP clients
+- Self-documenting API responses
+
+All models inherit from BaseModel with consistent patterns:
+- `success: bool` field for operation status
+- Optional `message: str` for human-readable feedback
+- Typed fields for all response data
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+# ============================================================================
+# Region Tool Responses
+# ============================================================================
+
+
+class RegionInfo(BaseModel):
+    """Information about a single Amazon Ads region.
+
+    :param name: Human-readable region name
+    :param api_endpoint: API endpoint URL for this region
+    :param oauth_endpoint: OAuth token endpoint URL
+    :param marketplaces: List of marketplace codes in this region
+    :param sandbox: Whether this is a sandbox endpoint
+    """
+
+    name: str
+    api_endpoint: str
+    oauth_endpoint: str
+    marketplaces: List[str]
+    sandbox: bool = False
+
+
+class SetRegionResponse(BaseModel):
+    """Response from set_region tool.
+
+    :param success: Whether the operation succeeded
+    :param previous_region: Region before the change
+    :param new_region: Region after the change
+    :param region_name: Human-readable name of new region
+    :param api_endpoint: API endpoint URL for new region
+    :param oauth_endpoint: OAuth endpoint URL (if available)
+    :param message: Human-readable status message
+    :param error: Error code if operation failed
+    :param identity: Identity name if region is identity-controlled
+    """
+
+    success: bool
+    previous_region: Optional[str] = None
+    new_region: Optional[str] = None
+    region_name: Optional[str] = None
+    api_endpoint: Optional[str] = None
+    oauth_endpoint: Optional[str] = None
+    message: Optional[str] = None
+    error: Optional[str] = None
+    identity: Optional[str] = None
+    current_identity: Optional[str] = None
+    identity_region: Optional[str] = None
+    requested_region: Optional[str] = None
+    region: Optional[str] = None
+
+
+class GetRegionResponse(BaseModel):
+    """Response from get_region tool.
+
+    :param success: Whether the operation succeeded
+    :param region: Current region code (na/eu/fe)
+    :param region_name: Human-readable region name
+    :param api_endpoint: API endpoint URL
+    :param oauth_endpoint: OAuth endpoint URL (if using direct auth)
+    :param sandbox_mode: Whether sandbox mode is enabled
+    :param auth_method: Authentication method (direct/openbridge)
+    :param source: Where region setting comes from (identity/config)
+    :param identity_region: Region from active identity (if applicable)
+    """
+
+    success: bool
+    region: str
+    region_name: str
+    api_endpoint: str
+    oauth_endpoint: Optional[str] = None
+    sandbox_mode: bool = False
+    auth_method: Literal["direct", "openbridge"] = "openbridge"
+    source: Literal["identity", "config"] = "config"
+    identity_region: Optional[str] = None
+
+
+class ListRegionsResponse(BaseModel):
+    """Response from list_regions tool.
+
+    :param success: Whether the operation succeeded
+    :param current_region: Currently active region code
+    :param sandbox_mode: Whether sandbox mode is enabled
+    :param regions: Map of region code to region info
+    """
+
+    success: bool
+    current_region: str
+    sandbox_mode: bool = False
+    regions: Dict[str, RegionInfo]
+
+
+# ============================================================================
+# Profile Tool Responses
+# ============================================================================
+
+
+class SetProfileResponse(BaseModel):
+    """Response from set_active_profile tool.
+
+    :param success: Whether the operation succeeded
+    :param profile_id: The profile ID that was set
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    profile_id: str
+    message: str
+
+
+class GetProfileResponse(BaseModel):
+    """Response from get_active_profile tool.
+
+    :param success: Whether the operation succeeded
+    :param profile_id: Current active profile ID (None if not set)
+    :param source: Where profile setting comes from (explicit/environment/default)
+    :param message: Human-readable status message (when no profile set)
+    """
+
+    success: bool
+    profile_id: Optional[str] = None
+    source: Optional[str] = None
+    message: Optional[str] = None
+
+
+class ClearProfileResponse(BaseModel):
+    """Response from clear_active_profile tool.
+
+    :param success: Whether the operation succeeded
+    :param message: Human-readable status message
+    :param fallback_profile_id: Profile ID that will be used after clearing
+    """
+
+    success: bool
+    message: str
+    fallback_profile_id: Optional[str] = None
+
+
+# ============================================================================
+# Identity Tool Responses
+# ============================================================================
+
+
+class GetActiveIdentityResponse(BaseModel):
+    """Response from get_active_identity tool.
+
+    :param success: Whether the operation succeeded
+    :param identity: Active identity details (None if not set)
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    identity: Optional[Dict[str, Any]] = None
+    message: Optional[str] = None
+
+
+class ProfileSelectorResponse(BaseModel):
+    """Response from select_profile interactive tool.
+
+    :param success: Whether the operation succeeded
+    :param action: User action (accept/decline/cancel)
+    :param profile_id: Selected profile ID (if accepted)
+    :param profile_name: Selected profile name/description (if accepted)
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    action: Literal["accept", "decline", "cancel"]
+    profile_id: Optional[str] = None
+    profile_name: Optional[str] = None
+    message: str
+
+
+# ============================================================================
+# Profile Listing Tool Responses
+# ============================================================================
+
+
+class ProfileListItem(BaseModel):
+    """Normalized profile list item used by wrapper tools.
+
+    :param profile_id: Amazon Ads profile ID
+    :param name: Account name or advertiser name
+    :param country_code: Marketplace country code
+    :param type: Account type (seller/vendor/agency)
+    """
+
+    profile_id: str
+    name: str
+    country_code: str
+    type: str
+
+
+class ProfileSummaryResponse(BaseModel):
+    """Response from summarize_profiles tool.
+
+    :param total_count: Total profiles available
+    :param by_country: Counts by country code
+    :param by_type: Counts by account type
+    :param message: Optional guidance or status message
+    :param stale: Whether cached data was used after a refresh failure
+    """
+
+    total_count: int
+    by_country: Dict[str, int]
+    by_type: Dict[str, int]
+    message: Optional[str] = None
+    stale: bool = False
+
+
+class ProfileSearchResponse(BaseModel):
+    """Response from search_profiles tool.
+
+    :param items: Matching profile items
+    :param total_count: Total matches available
+    :param returned_count: Number of items returned
+    :param has_more: Whether more matches are available
+    :param message: Optional guidance or status message
+    :param stale: Whether cached data was used after a refresh failure
+    """
+
+    items: List[ProfileListItem]
+    total_count: int
+    returned_count: int
+    has_more: bool
+    message: Optional[str] = None
+    stale: bool = False
+
+
+class ProfilePageResponse(BaseModel):
+    """Response from page_profiles tool.
+
+    :param items: Page of profile items
+    :param total_count: Total profiles available for this filter
+    :param returned_count: Number of items returned
+    :param has_more: Whether more items are available
+    :param next_offset: Offset for the next page (if available)
+    :param message: Optional guidance or status message
+    :param stale: Whether cached data was used after a refresh failure
+    """
+
+    items: List[ProfileListItem]
+    total_count: int
+    returned_count: int
+    has_more: bool
+    next_offset: Optional[int] = None
+    message: Optional[str] = None
+    stale: bool = False
+
+
+class ProfileCacheRefreshResponse(BaseModel):
+    """Response from refresh_profiles_cache tool.
+
+    :param success: Whether the refresh succeeded
+    :param total_count: Total profiles cached
+    :param cache_timestamp: Timestamp of the cached data (epoch seconds)
+    :param stale: Whether cached data was returned after refresh failure
+    :param message: Optional guidance or status message
+    """
+
+    success: bool
+    total_count: int
+    cache_timestamp: Optional[float] = None
+    stale: bool = False
+    message: Optional[str] = None
+
+
+# ============================================================================
+# Download Tool Responses
+# ============================================================================
+
+
+class DownloadExportResponse(BaseModel):
+    """Response from download_export tool.
+
+    :param success: Whether the download succeeded
+    :param file_path: Local path where file was saved
+    :param export_type: Type of export (campaigns/adgroups/ads/targets/general)
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    file_path: str
+    export_type: str
+    message: str
+
+
+class DownloadedFile(BaseModel):
+    """Information about a downloaded file.
+
+    :param filename: Name of the file
+    :param path: Full path to the file
+    :param size: File size in bytes
+    :param modified: Last modified timestamp
+    :param resource_type: Type of resource (report/export/etc)
+    """
+
+    filename: str
+    path: str
+    size: int
+    modified: str
+    resource_type: Optional[str] = None
+
+
+class ListDownloadsResponse(BaseModel):
+    """Response from list_downloads tool.
+
+    :param success: Whether the operation succeeded
+    :param files: List of downloaded files
+    :param count: Total number of files
+    :param download_dir: Directory where downloads are stored
+    """
+
+    success: bool
+    files: List[DownloadedFile]
+    count: int
+    download_dir: str
+
+
+class GetDownloadUrlResponse(BaseModel):
+    """Response from get_download_url tool.
+
+    :param success: Whether the URL was generated successfully
+    :param download_url: HTTP URL to download the file
+    :param file_name: Name of the file
+    :param size_bytes: File size in bytes
+    :param profile_id: Profile ID the file belongs to
+    :param instructions: Instructions for using the download URL
+    :param error: Error message if failed
+    :param hint: Helpful hint for resolving issues
+    """
+
+    success: bool
+    download_url: Optional[str] = None
+    file_name: Optional[str] = None
+    size_bytes: Optional[int] = None
+    profile_id: Optional[str] = None
+    instructions: Optional[str] = None
+    error: Optional[str] = None
+    hint: Optional[str] = None
+
+
+# ============================================================================
+# Reporting Tool Responses
+# ============================================================================
+
+
+class AsyncReportResponse(BaseModel):
+    """Response from request_async_report tool.
+
+    :param success: Whether the report was generated successfully
+    :param report_id: Amazon Ads report ID
+    :param report_type: Type of report requested
+    :param file_path: Local path where report was saved (if successful)
+    :param status: Final report status
+    :param error: Error message if operation failed
+    :param download_url: Report download URL (if available but download failed)
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    report_id: Optional[str] = None
+    report_type: Optional[str] = None
+    file_path: Optional[str] = None
+    status: Optional[str] = None
+    error: Optional[str] = None
+    download_url: Optional[str] = None
+    message: Optional[str] = None
+
+
+# ============================================================================
+# OAuth Tool Responses
+# ============================================================================
+
+
+class OAuthFlowResponse(BaseModel):
+    """Response from start_oauth_flow tool.
+
+    :param success: Whether the flow started successfully
+    :param authorization_url: URL to redirect user for authorization
+    :param state: OAuth state parameter for CSRF protection
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    authorization_url: Optional[str] = None
+    state: Optional[str] = None
+    message: Optional[str] = None
+
+
+class OAuthStatusResponse(BaseModel):
+    """Response from check_oauth_status tool.
+
+    :param success: Whether the check succeeded
+    :param authenticated: Whether user is authenticated
+    :param token_valid: Whether current token is valid
+    :param expires_at: Token expiration timestamp
+    :param scopes: Granted OAuth scopes
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    authenticated: bool = False
+    token_valid: bool = False
+    expires_at: Optional[str] = None
+    scopes: Optional[List[str]] = None
+    message: Optional[str] = None
+
+
+class OAuthRefreshResponse(BaseModel):
+    """Response from refresh_oauth_token tool.
+
+    :param success: Whether the refresh succeeded
+    :param message: Human-readable status message
+    :param expires_at: New token expiration timestamp
+    """
+
+    success: bool
+    message: str
+    expires_at: Optional[str] = None
+
+
+class OAuthClearResponse(BaseModel):
+    """Response from clear_oauth_tokens tool.
+
+    :param success: Whether the clear succeeded
+    :param message: Human-readable status message
+    """
+
+    success: bool
+    message: str
+
+
+# ============================================================================
+# Routing State Response
+# ============================================================================
+
+
+class RoutingStateResponse(BaseModel):
+    """Response from get_routing_state tool.
+
+    :param region: Current region code
+    :param host: API host URL
+    :param headers: Current routing headers
+    :param sandbox: Whether sandbox mode is enabled
+    """
+
+    region: str
+    host: str
+    headers: Dict[str, str] = Field(default_factory=dict)
+    sandbox: bool = False
+
+
+# ============================================================================
+# Sampling Tool Responses
+# ============================================================================
+
+
+class SamplingTestResponse(BaseModel):
+    """Response from test_sampling tool.
+
+    :param success: Whether sampling executed successfully
+    :param message: Human-readable status message
+    :param response: Response from the sampled model
+    :param sampling_enabled: Whether sampling is enabled in settings
+    :param used_fallback: Note about fallback usage
+    :param error: Error message if operation failed
+    :param note: Additional notes about configuration
+    """
+
+    success: bool
+    message: Optional[str] = None
+    response: Optional[str] = None
+    sampling_enabled: bool = False
+    used_fallback: Optional[str] = None
+    error: Optional[str] = None
+    note: Optional[str] = None