meta-ads-mcp-python 1.0.79__py3-none-any.whl

meta_ads_mcp/core/http_auth_integration.py

@@ -0,0 +1,307 @@
+"""
+FastMCP HTTP Authentication Integration for Meta Ads MCP
+
+This module provides direct integration with FastMCP to inject authentication
+from HTTP headers into the tool execution context.
+"""
+
+import asyncio
+import contextvars
+from typing import Optional
+from .utils import logger
+import json
+
+# Use context variables instead of thread-local storage for better async support
+_auth_token: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar('auth_token', default=None)
+_pipeboard_token: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar('pipeboard_token', default=None)
+
+class FastMCPAuthIntegration:
+    """Direct integration with FastMCP for HTTP authentication"""
+    
+    @staticmethod
+    def set_auth_token(token: str) -> None:
+        """Set authentication token for the current context
+        
+        Args:
+            token: Access token to use for this request
+        """
+        _auth_token.set(token)
+    
+    @staticmethod
+    def get_auth_token() -> Optional[str]:
+        """Get authentication token for the current context
+        
+        Returns:
+            Access token if set, None otherwise
+        """
+        return _auth_token.get(None)
+    
+    @staticmethod
+    def set_pipeboard_token(token: str) -> None:
+        """Set Pipeboard token for the current context
+        
+        Args:
+            token: Pipeboard API token to use for this request
+        """
+        _pipeboard_token.set(token)
+    
+    @staticmethod
+    def get_pipeboard_token() -> Optional[str]:
+        """Get Pipeboard token for the current context
+        
+        Returns:
+            Pipeboard token if set, None otherwise
+        """
+        return _pipeboard_token.get(None)
+    
+    @staticmethod
+    def clear_auth_token() -> None:
+        """Clear authentication token for the current context"""
+        _auth_token.set(None)
+    
+    @staticmethod
+    def clear_pipeboard_token() -> None:
+        """Clear Pipeboard token for the current context"""
+        _pipeboard_token.set(None)
+    
+    @staticmethod
+    def extract_token_from_headers(headers: dict) -> Optional[str]:
+        """Extract token from HTTP headers
+        
+        Args:
+            headers: HTTP request headers
+            
+        Returns:
+            Token if found, None otherwise
+        """
+        # Check for Bearer token in Authorization header (primary method)
+        auth_header = headers.get('Authorization') or headers.get('authorization')
+        if auth_header and auth_header.lower().startswith('bearer '):
+            token = auth_header[7:].strip()
+            logger.debug("Found Bearer token in Authorization header")
+            return token
+        
+        # Check for direct Meta access token
+        meta_token = headers.get('X-META-ACCESS-TOKEN') or headers.get('x-meta-access-token')
+        if meta_token:
+            return meta_token
+        
+        # Check for Pipeboard token (legacy support, to be removed)
+        pipeboard_token = headers.get('X-PIPEBOARD-API-TOKEN') or headers.get('x-pipeboard-api-token')
+        if pipeboard_token:
+            logger.debug("Found Pipeboard token in legacy headers")
+            return pipeboard_token
+        
+        return None
+    
+    @staticmethod
+    def extract_pipeboard_token_from_headers(headers: dict) -> Optional[str]:
+        """Extract Pipeboard token from HTTP headers
+        
+        Args:
+            headers: HTTP request headers
+            
+        Returns:
+            Pipeboard token if found, None otherwise
+        """
+        # Check for Pipeboard token in X-Pipeboard-Token header (duplication API pattern)
+        pipeboard_token = headers.get('X-Pipeboard-Token') or headers.get('x-pipeboard-token')
+        if pipeboard_token:
+            logger.debug("Found Pipeboard token in X-Pipeboard-Token header")
+            return pipeboard_token
+        
+        # Check for legacy Pipeboard token header
+        legacy_token = headers.get('X-PIPEBOARD-API-TOKEN') or headers.get('x-pipeboard-api-token')
+        if legacy_token:
+            logger.debug("Found Pipeboard token in legacy X-PIPEBOARD-API-TOKEN header")
+            return legacy_token
+        
+        return None
+
+def patch_fastmcp_server(mcp_server):
+    """Patch FastMCP server to inject authentication from HTTP headers
+    
+    Args:
+        mcp_server: FastMCP server instance to patch
+    """
+    logger.info("Patching FastMCP server for HTTP authentication")
+    
+    # Store the original run method
+    original_run = mcp_server.run
+    
+    def patched_run(transport="stdio", **kwargs):
+        """Enhanced run method that sets up HTTP auth integration"""
+        logger.debug(f"Starting FastMCP with transport: {transport}")
+        
+        if transport == "streamable-http":
+            logger.debug("Setting up HTTP authentication for streamable-http transport")
+            setup_http_auth_patching()
+        
+        # Call the original run method
+        return original_run(transport=transport, **kwargs)
+    
+    # Replace the run method
+    mcp_server.run = patched_run
+    logger.info("FastMCP server patching complete")
+
+def setup_http_auth_patching():
+    """Setup HTTP authentication patching for auth system"""
+    logger.info("Setting up HTTP authentication patching")
+    
+    # Import and patch the auth system
+    from . import auth
+    from . import api
+    from . import authentication
+    
+    # Store the original function
+    original_get_current_access_token = auth.get_current_access_token
+    
+    async def get_current_access_token_with_http_support() -> Optional[str]:
+        """Enhanced get_current_access_token that checks HTTP context first"""
+        
+        # Check for context-scoped token first
+        context_token = FastMCPAuthIntegration.get_auth_token()
+        if context_token:
+            return context_token
+        
+        # Fall back to original implementation
+        return await original_get_current_access_token()
+    
+    # Replace the function in all modules that imported it
+    auth.get_current_access_token = get_current_access_token_with_http_support
+    api.get_current_access_token = get_current_access_token_with_http_support
+    authentication.get_current_access_token = get_current_access_token_with_http_support
+    
+    logger.info("Auth system patching complete - patched in auth, api, and authentication modules")
+
+# Global instance for easy access
+fastmcp_auth = FastMCPAuthIntegration()
+
+# Forward declaration of setup_starlette_middleware
+def setup_starlette_middleware(app):
+    pass
+
+def setup_fastmcp_http_auth(mcp_server):
+    """Setup HTTP authentication integration with FastMCP
+    
+    Args:
+        mcp_server: FastMCP server instance to configure
+    """
+    logger.info("Setting up FastMCP HTTP authentication integration")
+    
+    # 1. Patch FastMCP's run method to ensure our get_current_access_token patch is applied
+    # This remains crucial for the token to be picked up by tool calls.
+    patch_fastmcp_server(mcp_server) # This patches mcp_server.run
+    
+    # 2. Patch the methods that provide the Starlette app instance
+    # This ensures our middleware is added to the app Uvicorn will actually serve.
+
+    app_provider_methods = []
+    if mcp_server.settings.json_response:
+        if hasattr(mcp_server, "streamable_http_app") and callable(mcp_server.streamable_http_app):
+            app_provider_methods.append("streamable_http_app")
+        else:
+            logger.warning("mcp_server.streamable_http_app not found or not callable, cannot patch for JSON responses.")
+    else: # SSE
+        if hasattr(mcp_server, "sse_app") and callable(mcp_server.sse_app):
+            app_provider_methods.append("sse_app")
+        else:
+            logger.warning("mcp_server.sse_app not found or not callable, cannot patch for SSE responses.")
+
+    if not app_provider_methods:
+        logger.error("No suitable app provider method (streamable_http_app or sse_app) found on mcp_server. Cannot add HTTP Auth middleware.")
+        # Fallback or error handling might be needed here if this is critical
+    
+    for method_name in app_provider_methods:
+        original_app_provider_method = getattr(mcp_server, method_name)
+        
+        def new_patched_app_provider_method(*args, **kwargs):
+            # Call the original method to get/create the Starlette app
+            app = original_app_provider_method(*args, **kwargs)
+            if app:
+                logger.debug(f"Original {method_name} returned app: {type(app)}. Adding AuthInjectionMiddleware.")
+                # Now, add our middleware to this specific app instance
+                setup_starlette_middleware(app) 
+            else:
+                logger.error(f"Original {method_name} returned None or a non-app object.")
+            return app
+            
+        setattr(mcp_server, method_name, new_patched_app_provider_method)
+        logger.debug(f"Patched mcp_server.{method_name} to inject AuthInjectionMiddleware.")
+
+    # The old setup_request_middleware call is no longer needed here,
+    # as middleware addition is now handled by patching the app provider methods.
+    # try:
+    #     setup_request_middleware(mcp_server) 
+    # except Exception as e:
+    #     logger.warning(f"Could not setup request middleware: {e}")
+
+    logger.info("FastMCP HTTP authentication integration setup attempt complete.")
+
+# Remove the old setup_request_middleware function as its logic is integrated above
+# def setup_request_middleware(mcp_server): ... (delete this function)
+
+# --- AuthInjectionMiddleware definition ---
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+import json # Ensure json is imported if not already at the top
+
+class AuthInjectionMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        logger.debug(f"HTTP Auth Middleware: Processing request to {request.url.path}")
+        logger.debug(f"HTTP Auth Middleware: Request headers: {list(request.headers.keys())}")
+        
+        # Extract both types of tokens for dual-header authentication
+        auth_token = FastMCPAuthIntegration.extract_token_from_headers(dict(request.headers))
+        pipeboard_token = FastMCPAuthIntegration.extract_pipeboard_token_from_headers(dict(request.headers))
+        
+        if auth_token:
+            logger.debug(f"HTTP Auth Middleware: Extracted auth token: {auth_token[:10]}...")
+            logger.debug("Injecting auth token into request context")
+            FastMCPAuthIntegration.set_auth_token(auth_token)
+        
+        if pipeboard_token:
+            logger.debug(f"HTTP Auth Middleware: Extracted Pipeboard token: {pipeboard_token[:10]}...")
+            logger.debug("Injecting Pipeboard token into request context")
+            FastMCPAuthIntegration.set_pipeboard_token(pipeboard_token)
+        
+        if not auth_token and not pipeboard_token:
+            logger.warning("HTTP Auth Middleware: No authentication tokens found in headers")
+        
+        try:
+            response = await call_next(request)
+            return response
+        finally:
+            # Clear tokens that were set for this request
+            if auth_token:
+                FastMCPAuthIntegration.clear_auth_token()
+            if pipeboard_token:
+                FastMCPAuthIntegration.clear_pipeboard_token()
+
+def setup_starlette_middleware(app):
+    """Add AuthInjectionMiddleware to the Starlette app if not already present.
+    
+    Args:
+        app: Starlette app instance
+    """
+    if not app:
+        logger.error("Cannot setup Starlette middleware, app is None.")
+        return
+
+    # Check if our specific middleware class is already in the stack
+    already_added = False
+    # Starlette's app.middleware is a list of Middleware objects.
+    # app.user_middleware contains middleware added by app.add_middleware()
+    for middleware_item in app.user_middleware:
+        if middleware_item.cls == AuthInjectionMiddleware:
+            already_added = True
+            break
+            
+    if not already_added:
+        try:
+            app.add_middleware(AuthInjectionMiddleware)
+            logger.info("AuthInjectionMiddleware added to Starlette app successfully.")
+        except Exception as e:
+            logger.error(f"Failed to add AuthInjectionMiddleware to Starlette app: {e}", exc_info=True)
+    else:
+        logger.debug("AuthInjectionMiddleware already present in Starlette app's middleware stack.") 

meta_ads_mcp/core/insights.py

@@ -0,0 +1,161 @@
+"""Insights and Reporting functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Union, Dict, List
+from .api import meta_api_tool, make_api_request
+from .utils import download_image, try_multiple_download_methods, ad_creative_images, create_resource_from_image
+from .server import mcp_server
+import base64
+import datetime
+
+
+# Prefixes of action_type values that are always redundant duplicates of other
+# action types already present in the response.  For every canonical event
+# (e.g. "purchase"), the Meta API returns 5-8 variants that carry the exact
+# same numeric value:
+#   omni_purchase, onsite_web_purchase, onsite_web_app_purchase,
+#   web_in_store_purchase, web_app_in_store_purchase,
+#   offsite_conversion.fb_pixel_purchase  ...
+# Removing these cuts each insight row from ~4 KB to ~1 KB without any
+# information loss.
+_REDUNDANT_ACTION_PREFIXES = (
+    "omni_",                       # omnichannel roll-up  (== onsite_web_app_*)
+    "onsite_web_app_",             # web+app combined     (== onsite_web_*)
+    "onsite_web_",                 # web-only subset      (== canonical + onsite)
+    "onsite_app_",                 # app-only subset      (== onsite_conversion.*)
+    "web_app_in_store_",           # web+app in-store     (== web_in_store_*)
+    "offsite_conversion.fb_pixel_",  # pixel attribution  (== canonical type)
+)
+
+
+def _strip_redundant_actions(row: dict) -> dict:
+    """Remove redundant action-type entries from a single insight row."""
+    for key in ("actions", "action_values", "cost_per_action_type"):
+        items = row.get(key)
+        if not isinstance(items, list):
+            continue
+        row[key] = [
+            item for item in items
+            if not any(
+                item.get("action_type", "").startswith(prefix)
+                for prefix in _REDUNDANT_ACTION_PREFIXES
+            )
+        ]
+    return row
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_insights(object_id: str = "", access_token: Optional[str] = None,
+                      time_range: Union[str, Dict[str, str]] = "maximum", breakdown: str = "",
+                      level: str = "ad", limit: int = 25, after: str = "",
+                      action_attribution_windows: Optional[List[str]] = None,
+                      compact: bool = False,
+                      account_id: str = "", campaign_id: str = "",
+                      adset_id: str = "", ad_id: str = "") -> str:
+    """
+    Get performance insights for a campaign, ad set, ad or account.
+
+    Args:
+        object_id: ID of the campaign, ad set, ad or account. You can also use the alias parameters below.
+        account_id: Alias for object_id when querying account-level insights
+        campaign_id: Alias for object_id when querying campaign-level insights
+        adset_id: Alias for object_id when querying ad-set-level insights
+        ad_id: Alias for object_id when querying ad-level insights
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        time_range: Either a preset time range string or a dictionary with "since" and "until" dates in YYYY-MM-DD format
+                   Preset options: today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, 
+                   last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, 
+                   last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year
+                   Dictionary example: {"since":"2023-01-01","until":"2023-01-31"}
+        breakdown: Optional breakdown dimension. Valid values include:
+                   Demographic: age, gender, country, region, dma
+                   Platform/Device: device_platform, platform_position, publisher_platform, impression_device
+                   Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset, 
+                                  image_asset, link_url_asset, title_asset, video_asset, media_asset_url,
+                                  media_creator, media_destination_url, media_format, media_origin_url,
+                                  media_text_content, media_type, creative_relaxation_asset_type,
+                                  flexible_format_asset_type, gen_ai_asset_type
+                   Campaign/Ad Attributes: breakdown_ad_objective, breakdown_reporting_ad_id, app_id, product_id
+                   Conversion Tracking: coarse_conversion_value, conversion_destination, standard_event_content_type,
+                                       signal_source_bucket, is_conversion_id_modeled, fidelity_type, redownload
+                   Time-based: hourly_stats_aggregated_by_advertiser_time_zone, 
+                              hourly_stats_aggregated_by_audience_time_zone, frequency_value
+                   Extensions/Landing: ad_extension_domain, ad_extension_url, landing_destination, 
+                                      mdsa_landing_destination
+                   Attribution: sot_attribution_model_type, sot_attribution_window, sot_channel, 
+                               sot_event_type, sot_source
+                   Mobile/SKAN: skan_campaign_id, skan_conversion_id, skan_version, postback_sequence_index
+                   CRM/Business: crm_advertiser_l12_territory_ids, crm_advertiser_subvertical_id,
+                                crm_advertiser_vertical_id, crm_ult_advertiser_id, user_persona_id, user_persona_name
+                   Advanced: hsid, is_auto_advance, is_rendered_as_delayed_skip_ad, mmm, place_page_id,
+                            marketing_messages_btn_name, impression_view_time_advertiser_hour_v2, comscore_market,
+                            comscore_market_code
+        level: Level of aggregation (ad, adset, campaign, account)
+        limit: Maximum number of results to return per page (default: 25, Meta API allows much higher values)
+        after: Pagination cursor to get the next set of results. Use the 'after' cursor from previous response's paging.next field.
+        action_attribution_windows: Optional list of attribution windows (e.g., ["1d_click", "7d_click", "1d_view"]).
+                   When specified, actions include additional fields for each window. The 'value' field always shows 7d_click.
+        compact: When True, strips redundant action-type duplicates from the response
+                 (omni_*, onsite_web_*, offsite_conversion.fb_pixel_*, etc.) to reduce
+                 payload size by ~60%. The canonical action types (purchase, add_to_cart,
+                 view_content, etc.) are always preserved. Default: False.
+
+    Note on response size: This tool always returns a fixed set of fields (impressions, clicks,
+    spend, cpc, cpm, ctr, reach, actions, action_values, etc.) and cannot filter to a subset.
+    For large result sets (50+ rows), the actions/action_values arrays can make responses very
+    large (1-2MB+). If you only need specific metrics like spend or impressions, consider using
+    bulk_get_insights with compact=true and the fields parameter:
+        bulk_get_insights(level="ad", account_ids=[...], compact=true, fields=["spend", "impressions"])
+    bulk_get_insights supports level="ad", "adset", "campaign", and "account".
+    """
+    # Accept common aliases for object_id (LLMs frequently use these instead)
+    if not object_id:
+        object_id = account_id or campaign_id or adset_id or ad_id
+
+    if not object_id:
+        return json.dumps({"error": "No object ID provided. Use object_id, account_id, campaign_id, adset_id, or ad_id."}, indent=2)
+        
+    endpoint = f"{object_id}/insights"
+    params = {
+        "fields": "account_id,account_name,campaign_id,campaign_name,adset_id,adset_name,ad_id,ad_name,impressions,clicks,spend,cpc,cpm,ctr,reach,frequency,actions,action_values,conversions,unique_clicks,cost_per_action_type",
+        "level": level,
+        "limit": limit
+    }
+    
+    # Handle time range based on type
+    if isinstance(time_range, dict):
+        # Use custom date range with since/until parameters
+        if "since" in time_range and "until" in time_range:
+            params["time_range"] = json.dumps(time_range)
+        else:
+            return json.dumps({"error": "Custom time_range must contain both 'since' and 'until' keys in YYYY-MM-DD format"}, indent=2)
+    else:
+        # Use preset date range
+        params["date_preset"] = time_range
+    
+    if breakdown:
+        params["breakdowns"] = breakdown
+    
+    if after:
+        params["after"] = after
+
+    if action_attribution_windows:
+        # Meta API expects single-quote format: ['1d_click','7d_click']
+        params["action_attribution_windows"] = "[" + ",".join(f"'{w}'" for w in action_attribution_windows) + "]"
+
+    data = await make_api_request(endpoint, access_token, params)
+
+    # In compact mode, strip redundant action-type duplicates to reduce response size.
+    if compact and isinstance(data, dict):
+        for row in data.get("data", []):
+            if isinstance(row, dict):
+                _strip_redundant_actions(row)
+
+    return json.dumps(data, indent=2)
+
+
+
+
+
+