meta-ads-mcp 0.2.6__py3-none-any.whl → 0.2.9__py3-none-any.whl

meta_ads_mcp/__init__.py

@@ -7,7 +7,7 @@ with the Claude LLM.
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.2.6"
+__version__ = "0.2.9"
 
 __all__ = [
     'get_ad_accounts',

meta_ads_mcp/api.py

@@ -30,7 +30,7 @@ USER_AGENT = "meta-ads-mcp/1.0"
 META_APP_ID = os.environ.get("META_APP_ID", "")  # Default to empty string
 
 # Auth constants
-AUTH_SCOPE = "ads_management,ads_read,business_management"
+AUTH_SCOPE = "ads_management,ads_read,business_management,public_profile"
 AUTH_REDIRECT_URI = "http://localhost:8888/callback"
 AUTH_RESPONSE_TYPE = "token"
 
@@ -521,45 +521,40 @@ def meta_api_tool(func):
         if not access_token:
             needs_authentication = True
             
-            # Start the callback server
-            port = start_callback_server()
+            # Check if we're using Pipeboard authentication
+            using_pipeboard = bool(os.environ.get("PIPEBOARD_API_TOKEN", ""))
             
-            # Get current app ID from config
-            current_app_id = meta_config.get_app_id()
-            if not current_app_id:
-                return json.dumps({
-                    "error": "No Meta App ID provided. Please provide a valid app ID via environment variable META_APP_ID or --app-id CLI argument.",
-                    "help": "This is required for authentication with Meta Graph API."
-                }, indent=2)
-                
-            # Update auth manager with current app ID
-            auth_manager.app_id = current_app_id
-            print(f"Using Meta App ID from config: {current_app_id}")
-            
-            # Update auth manager's redirect URI with the current port
-            auth_manager.redirect_uri = f"http://localhost:{port}/callback"
-            
-            # Generate the authentication URL
-            login_url = auth_manager.get_auth_url()
-            
-            # Return a user-friendly authentication required response
-            return json.dumps({
-                "error": "Authentication Required",
-                "details": {
-                    "message": "You need to authenticate with the Meta API before using this tool",
-                    "action_required": "Please authenticate using the link below",
-                    "login_url": login_url,
-                    "markdown_link": f"[Click here to authenticate with Meta Ads API]({login_url})"
-                }
-            }, indent=2)
-        
-        # Call the original function
-        try:
-            result = await func(**kwargs)
-            
-            # If authentication is needed after the call (e.g., token was invalidated)
-            if needs_authentication:
-                # Start the callback server
+            if using_pipeboard:
+                # For Pipeboard, we use a different authentication flow
+                try:
+                    # Here we'd import dynamically to avoid circular imports
+                    from .core.pipeboard_auth import pipeboard_auth_manager
+                    
+                    # Initiate the Pipeboard auth flow
+                    auth_data = pipeboard_auth_manager.initiate_auth_flow()
+                    login_url = auth_data.get("loginUrl")
+                    
+                    # Return a user-friendly authentication required response for Pipeboard
+                    return json.dumps({
+                        "error": "Authentication Required",
+                        "details": {
+                            "message": "You need to authenticate with the Meta API via Pipeboard",
+                            "action_required": "Please authenticate using the link below",
+                            "login_url": login_url,
+                            "markdown_link": f"[Click here to authenticate with Meta Ads API via Pipeboard]({login_url})",
+                            "authentication_method": "pipeboard"
+                        }
+                    }, indent=2)
+                except Exception as e:
+                    return json.dumps({
+                        "error": f"Pipeboard Authentication Error: {str(e)}",
+                        "details": {
+                            "message": "Failed to initiate Pipeboard authentication flow",
+                            "action_required": "Please check your PIPEBOARD_API_TOKEN environment variable"
+                        }
+                    }, indent=2)
+            else:
+                # For direct Meta auth, start the callback server
                 port = start_callback_server()
                 
                 # Get current app ID from config
@@ -570,6 +565,7 @@ def meta_api_tool(func):
                         "help": "This is required for authentication with Meta Graph API."
                     }, indent=2)
                     
+                # Update auth manager with current app ID
                 auth_manager.app_id = current_app_id
                 print(f"Using Meta App ID from config: {current_app_id}")
                 
@@ -579,21 +575,94 @@ def meta_api_tool(func):
                 # Generate the authentication URL
                 login_url = auth_manager.get_auth_url()
                 
-                # Create a resource response that includes the markdown link format
-                response = {
-                    "error": "Session expired or token invalid. Please re-authenticate with Meta Ads API",
-                    "login_url": login_url,
-                    "server_status": f"Callback server running on port {port}",
-                    "markdown_link": f"[Click here to re-authenticate with Meta Ads API]({login_url})",
-                    "message": "IMPORTANT: Please use the Markdown link format in your response to allow the user to click it.",
-                    "instructions_for_llm": "You must present this link as clickable Markdown to the user using the markdown_link format provided.",
-                    "note": "After authenticating, the token will be automatically saved."
-                }
-                
-                # Wait a moment to ensure the server is fully started
-                await asyncio.sleep(1)
+                # Return a user-friendly authentication required response
+                return json.dumps({
+                    "error": "Authentication Required",
+                    "details": {
+                        "message": "You need to authenticate with the Meta API before using this tool",
+                        "action_required": "Please authenticate using the link below",
+                        "login_url": login_url,
+                        "markdown_link": f"[Click here to authenticate with Meta Ads API]({login_url})",
+                        "authentication_method": "meta_oauth"
+                    }
+                }, indent=2)
+        
+        # Call the original function
+        try:
+            result = await func(**kwargs)
+            
+            # If authentication is needed after the call (e.g., token was invalidated)
+            if needs_authentication:
+                # Check if we're using Pipeboard authentication
+                using_pipeboard = bool(os.environ.get("PIPEBOARD_API_TOKEN", ""))
                 
-                return json.dumps(response, indent=2)
+                if using_pipeboard:
+                    # For Pipeboard, we use a different authentication flow
+                    try:
+                        # Here we'd import dynamically to avoid circular imports
+                        from .core.pipeboard_auth import pipeboard_auth_manager
+                        
+                        # Initiate the Pipeboard auth flow
+                        auth_data = pipeboard_auth_manager.initiate_auth_flow()
+                        login_url = auth_data.get("loginUrl")
+                        
+                        # Create a resource response that includes the markdown link format
+                        response = {
+                            "error": "Session expired or token invalid. Please re-authenticate with Meta Ads API",
+                            "login_url": login_url,
+                            "markdown_link": f"[Click here to re-authenticate with Meta Ads API via Pipeboard]({login_url})",
+                            "message": "IMPORTANT: Please use the Markdown link format in your response to allow the user to click it.",
+                            "instructions_for_llm": "You must present this link as clickable Markdown to the user using the markdown_link format provided.",
+                            "authentication_method": "pipeboard",
+                            "note": "After authenticating, the token will be automatically saved."
+                        }
+                        
+                        return json.dumps(response, indent=2)
+                    except Exception as e:
+                        return json.dumps({
+                            "error": f"Pipeboard Authentication Error: {str(e)}",
+                            "details": {
+                                "message": "Failed to initiate Pipeboard authentication flow",
+                                "action_required": "Please check your PIPEBOARD_API_TOKEN environment variable"
+                            }
+                        }, indent=2)
+                else:
+                    # For direct Meta auth, start the callback server
+                    port = start_callback_server()
+                    
+                    # Get current app ID from config
+                    current_app_id = meta_config.get_app_id()
+                    if not current_app_id:
+                        return json.dumps({
+                            "error": "No Meta App ID provided. Please provide a valid app ID via environment variable META_APP_ID or --app-id CLI argument.",
+                            "help": "This is required for authentication with Meta Graph API."
+                        }, indent=2)
+                        
+                    auth_manager.app_id = current_app_id
+                    print(f"Using Meta App ID from config: {current_app_id}")
+                    
+                    # Update auth manager's redirect URI with the current port
+                    auth_manager.redirect_uri = f"http://localhost:{port}/callback"
+                    
+                    # Generate the authentication URL
+                    login_url = auth_manager.get_auth_url()
+                    
+                    # Create a resource response that includes the markdown link format
+                    response = {
+                        "error": "Session expired or token invalid. Please re-authenticate with Meta Ads API",
+                        "login_url": login_url,
+                        "server_status": f"Callback server running on port {port}",
+                        "markdown_link": f"[Click here to re-authenticate with Meta Ads API]({login_url})",
+                        "message": "IMPORTANT: Please use the Markdown link format in your response to allow the user to click it.",
+                        "instructions_for_llm": "You must present this link as clickable Markdown to the user using the markdown_link format provided.",
+                        "authentication_method": "meta_oauth",
+                        "note": "After authenticating, the token will be automatically saved."
+                    }
+                    
+                    # Wait a moment to ensure the server is fully started
+                    await asyncio.sleep(1)
+                    
+                    return json.dumps(response, indent=2)
             
             # If result is a string (JSON), check for app ID errors and improve them
             if isinstance(result, str):

meta_ads_mcp/core/__init__.py

@@ -4,7 +4,7 @@ from .server import mcp_server
 from .accounts import get_ad_accounts, get_account_info
 from .campaigns import get_campaigns, get_campaign_details, create_campaign
 from .adsets import get_adsets, get_adset_details, update_adset
-from .ads import get_ads, get_ad_details, get_ad_creatives, get_ad_image
+from .ads import get_ads, get_ad_details, get_ad_creatives, get_ad_image, update_ad
 from .insights import get_insights, debug_image_download
 from .authentication import get_login_link
 from .server import login_cli, main
@@ -24,6 +24,7 @@ __all__ = [
     'get_ad_details',
     'get_ad_creatives',
     'get_ad_image',
+    'update_ad',
     'get_insights',
     'debug_image_download',
     'get_login_link',

meta_ads_mcp/core/ads.py

@@ -1,7 +1,7 @@
 """Ad and Creative-related functionality for Meta Ads API."""
 
 import json
-from typing import Optional, Dict, Any
+from typing import Optional, Dict, Any, List
 import io
 from PIL import Image as PILImage
 from mcp.server.fastmcp import Image
@@ -36,18 +36,27 @@ async def get_ads(access_token: str = None, account_id: str = None, limit: int =
         else:
             return json.dumps({"error": "No account ID specified and no accounts found for user"}, indent=2)
     
-    endpoint = f"{account_id}/ads"
-    params = {
-        "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
-        "limit": limit
-    }
-    
+    # Use campaign-specific endpoint if campaign_id is provided
     if campaign_id:
-        params["campaign_id"] = campaign_id
-    
-    if adset_id:
-        params["adset_id"] = adset_id
-    
+        endpoint = f"{campaign_id}/ads"
+        params = {
+            "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
+            "limit": limit
+        }
+        # Adset ID can still be used to filter within the campaign
+        if adset_id:
+            params["adset_id"] = adset_id
+    else:
+        # Default to account-level endpoint if no campaign_id
+        endpoint = f"{account_id}/ads"
+        params = {
+            "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
+            "limit": limit
+        }
+        # Adset ID can filter at the account level if no campaign specified
+        if adset_id:
+            params["adset_id"] = adset_id
+
     data = await make_api_request(endpoint, access_token, params)
     
     return json.dumps(data, indent=2)
@@ -78,156 +87,98 @@ async def get_ad_details(access_token: str = None, ad_id: str = None) -> str:
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_ad_creatives(access_token: str = None, ad_id: str = None) -> str:
+async def create_ad(
+    account_id: str = None,
+    name: str = None,
+    adset_id: str = None,
+    creative_id: str = None,
+    status: str = "PAUSED",
+    bid_amount = None,
+    tracking_specs: Optional[List[Dict[str, Any]]] = None,
+    access_token: str = None
+) -> str:
     """
-    Get creative details for a specific ad. Best if combined with get_ad_image to get the full image.
+    Create a new ad with an existing creative.
     
     Args:
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        name: Ad name
+        adset_id: Ad set ID where this ad will be placed
+        creative_id: ID of an existing creative to use
+        status: Initial ad status (default: PAUSED)
+        bid_amount: Optional bid amount in account currency (in cents)
+        tracking_specs: Optional tracking specifications (e.g., for pixel events).
+                      Example: [{"action.type":"offsite_conversion","fb_pixel":["YOUR_PIXEL_ID"]}]
         access_token: Meta API access token (optional - will use cached token if not provided)
-        ad_id: Meta Ads ad ID
     """
-    if not ad_id:
-        return json.dumps({"error": "No ad ID provided"}, indent=2)
-        
-    # First, get the creative ID from the ad
-    endpoint = f"{ad_id}"
-    params = {
-        "fields": "creative"
-    }
+    # Check required parameters
+    if not account_id:
+        return json.dumps({"error": "No account ID provided"}, indent=2)
     
-    ad_data = await make_api_request(endpoint, access_token, params)
+    if not name:
+        return json.dumps({"error": "No ad name provided"}, indent=2)
     
-    if "error" in ad_data:
-        return json.dumps(ad_data, indent=2)
+    if not adset_id:
+        return json.dumps({"error": "No ad set ID provided"}, indent=2)
     
-    if "creative" not in ad_data:
-        return json.dumps({"error": "No creative found for this ad"}, indent=2)
-    
-    creative_id = ad_data.get("creative", {}).get("id")
     if not creative_id:
-        return json.dumps({"error": "Creative ID not found", "ad_data": ad_data}, indent=2)
+        return json.dumps({"error": "No creative ID provided"}, indent=2)
     
-    # Now get the creative details with essential fields
-    creative_endpoint = f"{creative_id}"
-    creative_params = {
-        "fields": "id,name,title,body,image_url,object_story_spec,url_tags,link_url,thumbnail_url,image_hash,asset_feed_spec,object_type"
-    }
+    endpoint = f"{account_id}/ads"
     
-    creative_data = await make_api_request(creative_endpoint, access_token, creative_params)
+    params = {
+        "name": name,
+        "adset_id": adset_id,
+        "creative": {"creative_id": creative_id},
+        "status": status
+    }
     
-    # Try to get full-size images in different ways:
+    # Add bid amount if provided
+    if bid_amount is not None:
+        params["bid_amount"] = str(bid_amount)
+        
+    # Add tracking specs if provided
+    if tracking_specs is not None:
+        params["tracking_specs"] = json.dumps(tracking_specs) # Needs to be JSON encoded string
     
-    # 1. First approach: Get ad images directly using the adimages endpoint
-    if "image_hash" in creative_data:
-        image_hash = creative_data.get("image_hash")
-        image_endpoint = f"act_{ad_data.get('account_id', '')}/adimages"
-        image_params = {
-            "hashes": [image_hash]
-        }
-        image_data = await make_api_request(image_endpoint, access_token, image_params)
-        if "data" in image_data and len(image_data["data"]) > 0:
-            creative_data["full_image_url"] = image_data["data"][0].get("url")
+    try:
+        data = await make_api_request(endpoint, access_token, params, method="POST")
+        return json.dumps(data, indent=2)
+    except Exception as e:
+        error_msg = str(e)
+        return json.dumps({
+            "error": "Failed to create ad",
+            "details": error_msg,
+            "params_sent": params
+        }, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_ad_creatives(access_token: str = None, ad_id: str = None) -> str:
+    """
+    Get creative details for a specific ad. Best if combined with get_ad_image to get the full image.
     
-    # 2. For creatives with object_story_spec
-    if "object_story_spec" in creative_data:
-        spec = creative_data.get("object_story_spec", {})
-        
-        # For link ads
-        if "link_data" in spec:
-            link_data = spec.get("link_data", {})
-            # If there's an explicit image_url, use it
-            if "image_url" in link_data:
-                creative_data["full_image_url"] = link_data.get("image_url")
-            # If there's an image_hash, try to get the full image
-            elif "image_hash" in link_data:
-                image_hash = link_data.get("image_hash")
-                account_id = ad_data.get('account_id', '')
-                if not account_id:
-                    # Try to get account ID from ad ID
-                    ad_details_endpoint = f"{ad_id}"
-                    ad_details_params = {
-                        "fields": "account_id"
-                    }
-                    ad_details = await make_api_request(ad_details_endpoint, access_token, ad_details_params)
-                    account_id = ad_details.get('account_id', '')
-                
-                if account_id:
-                    image_endpoint = f"act_{account_id}/adimages"
-                    image_params = {
-                        "hashes": [image_hash]
-                    }
-                    image_data = await make_api_request(image_endpoint, access_token, image_params)
-                    if "data" in image_data and len(image_data["data"]) > 0:
-                        creative_data["full_image_url"] = image_data["data"][0].get("url")
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+    """
+    if not ad_id:
+        return json.dumps({"error": "No ad ID provided"}, indent=2)
         
-        # For photo ads
-        if "photo_data" in spec:
-            photo_data = spec.get("photo_data", {})
-            if "image_hash" in photo_data:
-                image_hash = photo_data.get("image_hash")
-                account_id = ad_data.get('account_id', '')
-                if not account_id:
-                    # Try to get account ID from ad ID
-                    ad_details_endpoint = f"{ad_id}"
-                    ad_details_params = {
-                        "fields": "account_id"
-                    }
-                    ad_details = await make_api_request(ad_details_endpoint, access_token, ad_details_params)
-                    account_id = ad_details.get('account_id', '')
-                
-                if account_id:
-                    image_endpoint = f"act_{account_id}/adimages"
-                    image_params = {
-                        "hashes": [image_hash]
-                    }
-                    image_data = await make_api_request(image_endpoint, access_token, image_params)
-                    if "data" in image_data and len(image_data["data"]) > 0:
-                        creative_data["full_image_url"] = image_data["data"][0].get("url")
-    
-    # 3. If there's an asset_feed_spec, try to get images from there
-    if "asset_feed_spec" in creative_data and "images" in creative_data["asset_feed_spec"]:
-        images = creative_data["asset_feed_spec"]["images"]
-        if images and len(images) > 0 and "hash" in images[0]:
-            image_hash = images[0]["hash"]
-            account_id = ad_data.get('account_id', '')
-            if not account_id:
-                # Try to get account ID
-                ad_details_endpoint = f"{ad_id}"
-                ad_details_params = {
-                    "fields": "account_id"
-                }
-                ad_details = await make_api_request(ad_details_endpoint, access_token, ad_details_params)
-                account_id = ad_details.get('account_id', '')
-            
-            if account_id:
-                image_endpoint = f"act_{account_id}/adimages"
-                image_params = {
-                    "hashes": [image_hash]
-                }
-                image_data = await make_api_request(image_endpoint, access_token, image_params)
-                if "data" in image_data and len(image_data["data"]) > 0:
-                    creative_data["full_image_url"] = image_data["data"][0].get("url")
-    
-    # If we have a thumbnail_url but no full_image_url, let's attempt to convert the thumbnail URL to full size
-    if "thumbnail_url" in creative_data and "full_image_url" not in creative_data:
-        thumbnail_url = creative_data["thumbnail_url"]
-        # Try to convert the URL to get higher resolution by removing size parameters
-        if "p64x64" in thumbnail_url:
-            full_url = thumbnail_url.replace("p64x64", "p1080x1080")
-            creative_data["full_image_url"] = full_url
-        elif "dst-emg0" in thumbnail_url:
-            # Remove the dst-emg0 parameter that seems to reduce size
-            full_url = thumbnail_url.replace("dst-emg0_", "")
-            creative_data["full_image_url"] = full_url
-    
-    # Fallback to using thumbnail or image_url if we still don't have a full image
-    if "full_image_url" not in creative_data:
-        if "thumbnail_url" in creative_data:
-            creative_data["full_image_url"] = creative_data["thumbnail_url"]
-        elif "image_url" in creative_data:
-            creative_data["full_image_url"] = creative_data["image_url"]
-    
-    return json.dumps(creative_data, indent=2)
+    endpoint = f"{ad_id}/adcreatives"
+    params = {
+        "fields": "id,name,status,thumbnail_url,image_url,image_hash,object_story_spec" # Added image_hash
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    # Add image URLs for direct viewing if available
+    if 'data' in data:
+        for creative in data['data']:
+            creative['image_urls_for_viewing'] = ad_creative_images(creative)
+
+    return json.dumps(data, indent=2)
 
 
 @mcp_server.tool()
@@ -368,7 +319,13 @@ async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
 
 @mcp_server.tool()
 @meta_api_tool
-async def update_ad(ad_id: str, status: str = None, bid_amount: int = None, access_token: str = None) -> str:
+async def update_ad(
+    ad_id: str,
+    status: str = None,
+    bid_amount: int = None,
+    tracking_specs = None,
+    access_token: str = None
+) -> str:
     """
     Update an ad with new settings.
     
@@ -376,51 +333,25 @@ async def update_ad(ad_id: str, status: str = None, bid_amount: int = None, acce
         ad_id: Meta Ads ad ID
         status: Update ad status (ACTIVE, PAUSED, etc.)
         bid_amount: Bid amount in account currency (in cents for USD)
+        tracking_specs: Optional tracking specifications (e.g., for pixel events).
         access_token: Meta API access token (optional - will use cached token if not provided)
     """
     if not ad_id:
-        return json.dumps({"error": "No ad ID provided"}, indent=2)
-    
-    changes = {}
-    
-    if status is not None:
-        changes['status'] = status
-        
+        return json.dumps({"error": "Ad ID is required"}, indent=2)
+
+    params = {}
+    if status:
+        params["status"] = status
     if bid_amount is not None:
-        changes['bid_amount'] = bid_amount
-    
-    if not changes:
-        return json.dumps({"error": "No update parameters provided"}, indent=2)
-    
-    # Get current ad details for comparison
-    current_details_json = await get_ad_details(ad_id=ad_id, access_token=access_token)
-    current_details = json.loads(current_details_json)
-    
-    # Import the callback server components
-    from .callback_server import start_callback_server, update_confirmation
-    import urllib.parse
-    
-    # Start the callback server if not already running
-    port = start_callback_server()
-    
-    # Generate confirmation URL with properly encoded parameters
-    changes_json = json.dumps(changes)
-    encoded_changes = urllib.parse.quote(changes_json)
-    confirmation_url = f"http://localhost:{port}/confirm-update?ad_id={ad_id}&token={access_token}&changes={encoded_changes}"
-    
-    # Reset the update confirmation
-    update_confirmation.clear()
-    update_confirmation.update({"approved": False})
-    
-    # Return the confirmation link
-    response = {
-        "message": "Please confirm the ad update",
-        "confirmation_url": confirmation_url,
-        "markdown_link": f"[Click here to confirm ad update]({confirmation_url})",
-        "current_details": current_details,
-        "proposed_changes": changes,
-        "instructions_for_llm": "You must present this link as clickable Markdown to the user using the markdown_link format provided.",
-        "note": "After authenticating, the token will be automatically saved and your ad will be updated. Refresh the browser page if it doesn't load immediately."
-    }
-    
-    return json.dumps(response, indent=2) 
+        # Ensure bid_amount is sent as a string if it's not null
+        params["bid_amount"] = str(bid_amount)
+    if tracking_specs is not None: # Add tracking_specs to params if provided
+        params["tracking_specs"] = json.dumps(tracking_specs) # Needs to be JSON encoded string
+
+    if not params:
+        return json.dumps({"error": "No update parameters provided (status, bid_amount, or tracking_specs)"}, indent=2)
+
+    endpoint = f"{ad_id}"
+    data = await make_api_request(endpoint, access_token, params, method='POST')
+
+    return json.dumps(data, indent=2)