meta-ads-mcp 0.10.9__tar.gz → 0.11.1__tar.gz

{meta_ads_mcp-0.10.9 → meta_ads_mcp-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.10.9
+Version: 0.11.1
 Summary: Model Context Protocol (MCP) server for interacting with Meta Ads API
 Project-URL: Homepage, https://github.com/pipeboard-co/meta-ads-mcp
 Project-URL: Bug Tracker, https://github.com/pipeboard-co/meta-ads-mcp/issues

{meta_ads_mcp-0.10.9 → meta_ads_mcp-0.11.1}/meta_ads_mcp/__init__.py

@@ -6,7 +6,7 @@ This package provides a Meta Ads MCP integration
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.10.9"
+__version__ = "0.11.1"
 
 __all__ = [
     'get_ad_accounts',

{meta_ads_mcp-0.10.9 → meta_ads_mcp-0.11.1}/meta_ads_mcp/core/accounts.py

@@ -1,14 +1,14 @@
 """Account-related functionality for Meta Ads API."""
 
 import json
-from typing import Optional
+from typing import Optional, Dict, Any
 from .api import meta_api_tool, make_api_request
 from .server import mcp_server
 
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_ad_accounts(access_token: str = None, user_id: str = "me", limit: int = 200) -> str:
+async def get_ad_accounts(access_token: Optional[str] = None, user_id: str = "me", limit: int = 200) -> str:
     """
     Get ad accounts accessible by a user.
     
@@ -30,13 +30,13 @@ async def get_ad_accounts(access_token: str = None, user_id: str = "me", limit:
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_account_info(access_token: str = None, account_id: str = None) -> str:
+async def get_account_info(account_id: str, access_token: Optional[str] = None) -> str:
     """
     Get detailed information about a specific ad account.
     
     Args:
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
         access_token: Meta API access token (optional - will use cached token if not provided)
-        account_id: Meta Ads account ID (format: act_XXXXXXXXX) - REQUIRED
     """
     if not account_id:
         return {

{meta_ads_mcp-0.10.9 → meta_ads_mcp-0.11.1}/meta_ads_mcp/core/ads.py

@@ -14,29 +14,27 @@ from .utils import download_image, try_multiple_download_methods, ad_creative_im
 from .server import mcp_server
 
 
+# Only register the save_ad_image_locally function if explicitly enabled via environment variable
+ENABLE_SAVE_AD_IMAGE_LOCALLY = bool(os.environ.get("META_ADS_ENABLE_SAVE_AD_IMAGE_LOCALLY", ""))
+
+
 @mcp_server.tool()
 @meta_api_tool
-async def get_ads(access_token: str = None, account_id: str = None, limit: int = 10, 
+async def get_ads(account_id: str, access_token: Optional[str] = None, limit: int = 10, 
                  campaign_id: str = "", adset_id: str = "") -> str:
     """
     Get ads for a Meta Ads account with optional filtering.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        access_token: Meta API access token (optional - will use cached token if not provided)
         limit: Maximum number of ads to return (default: 10)
         campaign_id: Optional campaign ID to filter by
         adset_id: Optional ad set ID to filter by
     """
-    # If no account ID is specified, try to get the first one for the user
+    # Require explicit account_id
     if not account_id:
-        accounts_json = await get_ad_accounts("me", json.dumps({"limit": 1}), access_token)
-        accounts_data = json.loads(accounts_json)
-        
-        if "data" in accounts_data and accounts_data["data"]:
-            account_id = accounts_data["data"][0]["id"]
-        else:
-            return json.dumps({"error": "No account ID specified and no accounts found for user"}, indent=2)
+        return json.dumps({"error": "No account ID specified"}, indent=2)
     
     # Prioritize adset_id over campaign_id - use adset-specific endpoint
     if adset_id:
@@ -67,13 +65,13 @@ async def get_ads(access_token: str = None, account_id: str = None, limit: int =
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_ad_details(access_token: str = None, ad_id: str = None) -> str:
+async def get_ad_details(ad_id: str, access_token: Optional[str] = None) -> str:
     """
     Get detailed information about a specific ad.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         ad_id: Meta Ads ad ID
+        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)
@@ -91,14 +89,14 @@ async def get_ad_details(access_token: str = None, ad_id: str = None) -> str:
 @mcp_server.tool()
 @meta_api_tool
 async def create_ad(
-    account_id: str = None,
-    name: str = None,
-    adset_id: str = None,
-    creative_id: str = None,
+    account_id: str,
+    name: str,
+    adset_id: str,
+    creative_id: str,
     status: str = "PAUSED",
-    bid_amount = None,
+    bid_amount: Optional[int] = None,
     tracking_specs: Optional[List[Dict[str, Any]]] = None,
-    access_token: str = None
+    access_token: Optional[str] = None
 ) -> str:
     """
     Create a new ad with an existing creative.
@@ -158,13 +156,13 @@ async def create_ad(
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_ad_creatives(access_token: str = None, ad_id: str = None) -> str:
+async def get_ad_creatives(ad_id: str, access_token: Optional[str] = None) -> str:
     """
     Get creative details for a specific ad. Best if combined with get_ad_image to get the full image.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         ad_id: Meta Ads ad ID
+        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)
@@ -186,13 +184,13 @@ async def get_ad_creatives(access_token: str = None, ad_id: str = None) -> str:
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
+async def get_ad_image(ad_id: str, access_token: Optional[str] = None) -> Image:
     """
     Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         ad_id: Meta Ads ad ID
+        access_token: Meta API access token (optional - will use cached token if not provided)
     
     Returns:
         The ad image ready for direct visual analysis
@@ -386,141 +384,142 @@ async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
         return f"Error processing image: {str(e)}"
 
 
-@mcp_server.tool()
-@meta_api_tool
-async def save_ad_image_locally(access_token: str = None, ad_id: str = None, output_dir: str = "ad_images") -> str:
-    """
-    Get, download, and save a Meta ad image locally, returning the file path.
-    
-    Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
-        ad_id: Meta Ads ad ID
-        output_dir: Directory to save the image file (default: 'ad_images')
-    
-    Returns:
-        The file path to the saved image, or an error message string.
-    """
-    if not ad_id:
-        return json.dumps({"error": "No ad ID provided"}, indent=2)
+if ENABLE_SAVE_AD_IMAGE_LOCALLY:
+    @mcp_server.tool()
+    @meta_api_tool
+    async def save_ad_image_locally(ad_id: str, access_token: Optional[str] = None, output_dir: str = "ad_images") -> str:
+        """
+        Get, download, and save a Meta ad image locally, returning the file path.
         
-    print(f"Attempting to get and save creative image for ad {ad_id}")
-    
-    # First, get creative and account IDs
-    ad_endpoint = f"{ad_id}"
-    ad_params = {
-        "fields": "creative{id},account_id"
-    }
-    
-    ad_data = await make_api_request(ad_endpoint, access_token, ad_params)
-    
-    if "error" in ad_data:
-        return json.dumps({"error": f"Could not get ad data - {json.dumps(ad_data)}"}, indent=2)
-    
-    account_id = ad_data.get("account_id")
-    if not account_id:
-        return json.dumps({"error": "No account ID found for ad"}, indent=2)
-    
-    if "creative" not in ad_data:
-        return json.dumps({"error": "No creative found for this ad"}, indent=2)
+        Args:
+            ad_id: Meta Ads ad ID
+            access_token: Meta API access token (optional - will use cached token if not provided)
+            output_dir: Directory to save the image file (default: 'ad_images')
         
-    creative_data = ad_data.get("creative", {})
-    creative_id = creative_data.get("id")
-    if not creative_id:
-        return json.dumps({"error": "No creative ID found"}, indent=2)
-    
-    # Get creative details to find image hash
-    creative_endpoint = f"{creative_id}"
-    creative_params = {
-        "fields": "id,name,image_hash,asset_feed_spec"
-    }
-    creative_details = await make_api_request(creative_endpoint, access_token, creative_params)
-    
-    image_hashes = []
-    if "image_hash" in creative_details:
-        image_hashes.append(creative_details["image_hash"])
-    if "asset_feed_spec" in creative_details and "images" in creative_details["asset_feed_spec"]:
-        for image in creative_details["asset_feed_spec"]["images"]:
-            if "hash" in image:
-                image_hashes.append(image["hash"])
-    
-    if not image_hashes:
-        # Fallback attempt (as in get_ad_image)
-        creative_json = await get_ad_creatives(ad_id=ad_id, access_token=access_token) # Ensure ad_id is passed correctly
-        creative_data_list = json.loads(creative_json)
-        if 'data' in creative_data_list and creative_data_list['data']:
-             first_creative = creative_data_list['data'][0]
-             if 'object_story_spec' in first_creative and 'link_data' in first_creative['object_story_spec'] and 'image_hash' in first_creative['object_story_spec']['link_data']:
-                 image_hashes.append(first_creative['object_story_spec']['link_data']['image_hash'])
-             elif 'image_hash' in first_creative: # Check direct hash on creative data
-                  image_hashes.append(first_creative['image_hash'])
+        Returns:
+            The file path to the saved image, or an error message string.
+        """
+        if not ad_id:
+            return json.dumps({"error": "No ad ID provided"}, indent=2)
+            
+        print(f"Attempting to get and save creative image for ad {ad_id}")
+        
+        # First, get creative and account IDs
+        ad_endpoint = f"{ad_id}"
+        ad_params = {
+            "fields": "creative{id},account_id"
+        }
+        
+        ad_data = await make_api_request(ad_endpoint, access_token, ad_params)
+        
+        if "error" in ad_data:
+            return json.dumps({"error": f"Could not get ad data - {json.dumps(ad_data)}"}, indent=2)
+        
+        account_id = ad_data.get("account_id")
+        if not account_id:
+            return json.dumps({"error": "No account ID found for ad"}, indent=2)
+        
+        if "creative" not in ad_data:
+            return json.dumps({"error": "No creative found for this ad"}, indent=2)
+            
+        creative_data = ad_data.get("creative", {})
+        creative_id = creative_data.get("id")
+        if not creative_id:
+            return json.dumps({"error": "No creative ID found"}, indent=2)
+        
+        # Get creative details to find image hash
+        creative_endpoint = f"{creative_id}"
+        creative_params = {
+            "fields": "id,name,image_hash,asset_feed_spec"
+        }
+        creative_details = await make_api_request(creative_endpoint, access_token, creative_params)
+        
+        image_hashes = []
+        if "image_hash" in creative_details:
+            image_hashes.append(creative_details["image_hash"])
+        if "asset_feed_spec" in creative_details and "images" in creative_details["asset_feed_spec"]:
+            for image in creative_details["asset_feed_spec"]["images"]:
+                if "hash" in image:
+                    image_hashes.append(image["hash"])
+        
+        if not image_hashes:
+            # Fallback attempt (as in get_ad_image)
+            creative_json = await get_ad_creatives(ad_id=ad_id, access_token=access_token) # Ensure ad_id is passed correctly
+            creative_data_list = json.loads(creative_json)
+            if 'data' in creative_data_list and creative_data_list['data']:
+                 first_creative = creative_data_list['data'][0]
+                 if 'object_story_spec' in first_creative and 'link_data' in first_creative['object_story_spec'] and 'image_hash' in first_creative['object_story_spec']['link_data']:
+                     image_hashes.append(first_creative['object_story_spec']['link_data']['image_hash'])
+                 elif 'image_hash' in first_creative: # Check direct hash on creative data
+                      image_hashes.append(first_creative['image_hash'])
 
 
-    if not image_hashes:
-        return json.dumps({"error": "No image hashes found in creative or fallback"}, indent=2)
+        if not image_hashes:
+            return json.dumps({"error": "No image hashes found in creative or fallback"}, indent=2)
 
-    print(f"Found image hashes: {image_hashes}")
-    
-    # Fetch image data using the first hash
-    image_endpoint = f"act_{account_id}/adimages"
-    hashes_str = f'["{image_hashes[0]}"]'
-    image_params = {
-        "fields": "hash,url,width,height,name,status",
-        "hashes": hashes_str
-    }
-    
-    print(f"Requesting image data with params: {image_params}")
-    image_data = await make_api_request(image_endpoint, access_token, image_params)
-    
-    if "error" in image_data:
-        return json.dumps({"error": f"Failed to get image data - {json.dumps(image_data)}"}, indent=2)
-    
-    if "data" not in image_data or not image_data["data"]:
-        return json.dumps({"error": "No image data returned from API"}, indent=2)
+        print(f"Found image hashes: {image_hashes}")
         
-    first_image = image_data["data"][0]
-    image_url = first_image.get("url")
-    
-    if not image_url:
-        return json.dumps({"error": "No valid image URL found in API response"}, indent=2)
+        # Fetch image data using the first hash
+        image_endpoint = f"act_{account_id}/adimages"
+        hashes_str = f'["{image_hashes[0]}"]'
+        image_params = {
+            "fields": "hash,url,width,height,name,status",
+            "hashes": hashes_str
+        }
         
-    print(f"Downloading image from URL: {image_url}")
-    
-    # Download and Save Image
-    image_bytes = await download_image(image_url)
-    
-    if not image_bytes:
-        return json.dumps({"error": "Failed to download image"}, indent=2)
+        print(f"Requesting image data with params: {image_params}")
+        image_data = await make_api_request(image_endpoint, access_token, image_params)
         
-    try:
-        # Ensure output directory exists
-        if not os.path.exists(output_dir):
-            os.makedirs(output_dir)
+        if "error" in image_data:
+            return json.dumps({"error": f"Failed to get image data - {json.dumps(image_data)}"}, indent=2)
+        
+        if "data" not in image_data or not image_data["data"]:
+            return json.dumps({"error": "No image data returned from API"}, indent=2)
             
-        # Create a filename (e.g., using ad_id and image hash)
-        file_extension = ".jpg" # Default extension, could try to infer from headers later
-        filename = f"{ad_id}_{image_hashes[0]}{file_extension}"
-        filepath = os.path.join(output_dir, filename)
-        
-        # Save the image bytes to the file
-        with open(filepath, "wb") as f:
-            f.write(image_bytes)
+        first_image = image_data["data"][0]
+        image_url = first_image.get("url")
+        
+        if not image_url:
+            return json.dumps({"error": "No valid image URL found in API response"}, indent=2)
             
-        print(f"Image saved successfully to: {filepath}")
-        return json.dumps({"filepath": filepath}, indent=2) # Return JSON with filepath
+        print(f"Downloading image from URL: {image_url}")
+        
+        # Download and Save Image
+        image_bytes = await download_image(image_url)
+        
+        if not image_bytes:
+            return json.dumps({"error": "Failed to download image"}, indent=2)
+            
+        try:
+            # Ensure output directory exists
+            if not os.path.exists(output_dir):
+                os.makedirs(output_dir)
+                
+            # Create a filename (e.g., using ad_id and image hash)
+            file_extension = ".jpg" # Default extension, could try to infer from headers later
+            filename = f"{ad_id}_{image_hashes[0]}{file_extension}"
+            filepath = os.path.join(output_dir, filename)
+            
+            # Save the image bytes to the file
+            with open(filepath, "wb") as f:
+                f.write(image_bytes)
+                
+            print(f"Image saved successfully to: {filepath}")
+            return json.dumps({"filepath": filepath}, indent=2) # Return JSON with filepath
 
-    except Exception as e:
-        return json.dumps({"error": f"Failed to save image: {str(e)}"}, indent=2)
+        except Exception as e:
+            return json.dumps({"error": f"Failed to save image: {str(e)}"}, indent=2)
 
 
 @mcp_server.tool()
 @meta_api_tool
 async def update_ad(
     ad_id: str,
-    status: str = None,
-    bid_amount: int = None,
-    tracking_specs = None,
-    creative_id: str = None,
-    access_token: str = None
+    status: Optional[str] = None,
+    bid_amount: Optional[int] = None,
+    tracking_specs: Optional[List[Dict[str, Any]]] = None,
+    creative_id: Optional[str] = None,
+    access_token: Optional[str] = None
 ) -> str:
     """
     Update an ad with new settings.
@@ -562,18 +561,18 @@ async def update_ad(
 @mcp_server.tool()
 @meta_api_tool
 async def upload_ad_image(
-    access_token: str = None,
-    account_id: str = None,
-    file: str = None,
-    image_url: str = None,
-    name: str = None
+    account_id: str,
+    access_token: Optional[str] = None,
+    file: Optional[str] = None,
+    image_url: Optional[str] = None,
+    name: Optional[str] = None
 ) -> str:
     """
     Upload an image to use in Meta Ads creatives.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        access_token: Meta API access token (optional - will use cached token if not provided)
         file: Data URL or raw base64 string of the image (e.g., "data:image/png;base64,iVBORw0KG...")
         image_url: Direct URL to an image to fetch and upload
         name: Optional name for the image (default: filename)
@@ -731,29 +730,29 @@ async def upload_ad_image(
 @mcp_server.tool()
 @meta_api_tool
 async def create_ad_creative(
-    access_token: str = None,
-    account_id: str = None,
-    name: str = None,
-    image_hash: str = None,
-    page_id: str = None,
-    link_url: str = None,
-    message: str = None,
-    headline: str = None,
-    headlines: List[str] = None,
-    description: str = None,
-    descriptions: List[str] = None,
-    dynamic_creative_spec: Dict[str, Any] = None,
-    call_to_action_type: str = None,
-    instagram_actor_id: str = None
+    account_id: str,
+    image_hash: str,
+    access_token: Optional[str] = None,
+    name: Optional[str] = None,
+    page_id: Optional[str] = None,
+    link_url: Optional[str] = None,
+    message: Optional[str] = None,
+    headline: Optional[str] = None,
+    headlines: Optional[List[str]] = None,
+    description: Optional[str] = None,
+    descriptions: Optional[List[str]] = None,
+    dynamic_creative_spec: Optional[Dict[str, Any]] = None,
+    call_to_action_type: Optional[str] = None,
+    instagram_actor_id: Optional[str] = None
 ) -> str:
     """
     Create a new ad creative using an uploaded image hash.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
-        name: Creative name
         image_hash: Hash of the uploaded image
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        name: Creative name
         page_id: Facebook Page ID to be used for the ad
         link_url: Destination URL for the ad
         message: Ad copy/text
@@ -943,23 +942,23 @@ async def create_ad_creative(
 @mcp_server.tool()
 @meta_api_tool
 async def update_ad_creative(
-    access_token: str = None,
-    creative_id: str = None,
-    name: str = None,
-    message: str = None,
-    headline: str = None,
-    headlines: List[str] = None,
-    description: str = None,
-    descriptions: List[str] = None,
-    dynamic_creative_spec: Dict[str, Any] = None,
-    call_to_action_type: str = None
+    creative_id: str,
+    access_token: Optional[str] = None,
+    name: Optional[str] = None,
+    message: Optional[str] = None,
+    headline: Optional[str] = None,
+    headlines: Optional[List[str]] = None,
+    description: Optional[str] = None,
+    descriptions: Optional[List[str]] = None,
+    dynamic_creative_spec: Optional[Dict[str, Any]] = None,
+    call_to_action_type: Optional[str] = None
 ) -> str:
     """
     Update an existing ad creative with new content or settings.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         creative_id: Meta Ads creative ID to update
+        access_token: Meta API access token (optional - will use cached token if not provided)
         name: New creative name
         message: New ad copy/text
         headline: Single headline for simple ads (cannot be used with headlines)
@@ -1252,13 +1251,13 @@ async def _search_pages_by_name_core(access_token: str, account_id: str, search_
 
 @mcp_server.tool()
 @meta_api_tool
-async def search_pages_by_name(access_token: str = None, account_id: str = None, search_term: str = None) -> str:
+async def search_pages_by_name(account_id: str, access_token: Optional[str] = None, search_term: Optional[str] = None) -> str:
     """
     Search for pages by name within an account.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        access_token: Meta API access token (optional - will use cached token if not provided)
         search_term: Search term to find pages by name (optional - returns all pages if not provided)
     
     Returns:
@@ -1275,13 +1274,13 @@ async def search_pages_by_name(access_token: str = None, account_id: str = None,
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_account_pages(access_token: str = None, account_id: str = None) -> str:
+async def get_account_pages(account_id: str, access_token: Optional[str] = None) -> str:
     """
     Get pages associated with a Meta Ads account.
     
     Args:
-        access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        access_token: Meta API access token (optional - will use cached token if not provided)
     
     Returns:
         JSON response with pages associated with the account

{meta_ads_mcp-0.10.9 → meta_ads_mcp-0.11.1}/meta_ads_mcp/core/ads_library.py

@@ -14,10 +14,10 @@ if not DISABLE_ADS_LIBRARY:
     @mcp_server.tool()
     @meta_api_tool
     async def search_ads_archive(
-        access_token: str = None,
-        search_terms: str = None,
+        search_terms: str,
+        ad_reached_countries: List[str],
+        access_token: Optional[str] = None,
         ad_type: str = "ALL",
-        ad_reached_countries: List[str] = None,
         limit: int = 25,  # Default limit, adjust as needed
         fields: str = "ad_creation_time,ad_creative_body,ad_creative_link_caption,ad_creative_link_description,ad_creative_link_title,ad_delivery_start_time,ad_delivery_stop_time,ad_snapshot_url,currency,demographic_distribution,funding_entity,impressions,page_id,page_name,publisher_platform,region_distribution,spend"
     ) -> str:
@@ -25,10 +25,10 @@ if not DISABLE_ADS_LIBRARY:
         Search the Facebook Ads Library archive.
 
         Args:
-            access_token: Meta API access token (optional - will use cached token if not provided).
             search_terms: The search query for ads.
-            ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
             ad_reached_countries: List of country codes (e.g., ["US", "GB"]).
+            access_token: Meta API access token (optional - will use cached token if not provided).
+            ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
             limit: Maximum number of ads to return.
             fields: Comma-separated string of fields to retrieve for each ad.