meta-ads-mcp 0.11.3__py3-none-any.whl → 0.11.5__py3-none-any.whl

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.11.3"
+__version__ = "0.11.5"
 
 __all__ = [
     'get_ad_accounts',

meta_ads_mcp/core/ads.py

@@ -635,15 +635,27 @@ async def upload_ad_image(
                 image_bytes = await try_multiple_download_methods(image_url)
             except Exception as download_error:
                 return json.dumps({
-                    "error": "Failed to download image from URL",
-                    "details": str(download_error),
+                    "error": "We couldn’t download the image from the link provided.",
+                    "reason": "The server returned an error while trying to fetch the image.",
                     "image_url": image_url,
+                    "details": str(download_error),
+                    "suggestions": [
+                        "Make sure the link is publicly reachable (no login, VPN, or IP restrictions).",
+                        "If the image is hosted on a private app or server, move it to a public URL or a CDN and try again.",
+                        "Verify the URL is correct and serves the actual image file."
+                    ]
                 }, indent=2)
 
             if not image_bytes:
                 return json.dumps({
-                    "error": "No data returned when downloading image from URL",
+                    "error": "We couldn’t access the image at the link you provided.",
+                    "reason": "The image link doesn’t appear to be publicly accessible or didn’t return any data.",
                     "image_url": image_url,
+                    "suggestions": [
+                        "Double‑check that the link is public and does not require login, VPN, or IP allow‑listing.",
+                        "If the image is stored in a private app (for example, a self‑hosted gallery), upload it to a public URL or a CDN and try again.",
+                        "Confirm the URL is correct and points directly to an image file (e.g., .jpg, .png)."
+                    ]
                 }, indent=2)
 
             import base64  # Local import

meta_ads_mcp/core/api.py

@@ -87,7 +87,14 @@ async def make_api_request(
     async with httpx.AsyncClient() as client:
         try:
             if method == "GET":
-                response = await client.get(url, params=request_params, headers=headers, timeout=30.0)
+                # For GET, JSON-encode dict/list params (e.g., targeting_spec) to proper strings
+                encoded_params = {}
+                for key, value in request_params.items():
+                    if isinstance(value, (dict, list)):
+                        encoded_params[key] = json.dumps(value)
+                    else:
+                        encoded_params[key] = value
+                response = await client.get(url, params=encoded_params, headers=headers, timeout=30.0)
             elif method == "POST":
                 # For Meta API, POST requests need data, not JSON
                 if 'targeting' in request_params and isinstance(request_params['targeting'], dict):

meta_ads_mcp/core/openai_deep_research.py

@@ -315,8 +315,6 @@ async def search(
 ) -> str:
     """
     Search through Meta Ads data and return matching record IDs.
-    
-    This tool is required for OpenAI ChatGPT Deep Research integration.
     It searches across ad accounts, campaigns, ads, pages, and businesses to find relevant records
     based on the provided query.
     
@@ -371,8 +369,6 @@ async def fetch(
 ) -> str:
     """
     Fetch complete record data by ID.
-    
-    This tool is required for OpenAI ChatGPT Deep Research integration.
     It retrieves the full data for a specific record identified by its ID.
     
     Args:

meta_ads_mcp/core/targeting.py

@@ -2,6 +2,7 @@
 
 import json
 from typing import Optional, List, Dict, Any
+import os
 from .api import meta_api_tool, make_api_request
 from .server import mcp_server
 
@@ -147,6 +148,49 @@ async def estimate_audience_size(
             }
         }, indent=2)
     
+    # Preflight validation: require at least one location OR a custom audience
+    def _has_location_or_custom_audience(t: Dict[str, Any]) -> bool:
+        if not isinstance(t, dict):
+            return False
+        geo = t.get("geo_locations") or {}
+        if isinstance(geo, dict):
+            for key in [
+                "countries",
+                "regions",
+                "cities",
+                "zips",
+                "geo_markets",
+                "country_groups"
+            ]:
+                val = geo.get(key)
+                if isinstance(val, list) and len(val) > 0:
+                    return True
+        # Top-level custom audiences
+        ca = t.get("custom_audiences")
+        if isinstance(ca, list) and len(ca) > 0:
+            return True
+        # Custom audiences within flexible_spec
+        flex = t.get("flexible_spec")
+        if isinstance(flex, list):
+            for spec in flex:
+                if isinstance(spec, dict):
+                    ca_spec = spec.get("custom_audiences")
+                    if isinstance(ca_spec, list) and len(ca_spec) > 0:
+                        return True
+        return False
+
+    if not _has_location_or_custom_audience(targeting):
+        return json.dumps({
+            "error": "Missing target audience location",
+            "details": "Select at least one location in targeting.geo_locations or include a custom audience.",
+            "action_required": "Add geo_locations with countries/regions/cities/zips or include custom_audiences.",
+            "example": {
+                "geo_locations": {"countries": ["US"]},
+                "age_min": 25,
+                "age_max": 65
+            }
+        }, indent=2)
+    
     # Build reach estimate request (using correct Meta API endpoint)
     endpoint = f"{account_id}/reachestimate"
     params = {
@@ -158,25 +202,153 @@ async def estimate_audience_size(
     try:
         data = await make_api_request(endpoint, access_token, params, method="GET")
         
+        # Surface Graph API errors directly for better diagnostics.
+        # If reachestimate fails, optionally attempt a fallback using delivery_estimate.
+        if isinstance(data, dict) and "error" in data:
+            # Special handling for Missing Target Audience Location error (subcode 1885364)
+            try:
+                err_wrapper = data.get("error", {})
+                details_obj = err_wrapper.get("details", {})
+                raw_err = details_obj.get("error", {}) if isinstance(details_obj, dict) else {}
+                if (
+                    isinstance(raw_err, dict) and (
+                        raw_err.get("error_subcode") == 1885364 or
+                        raw_err.get("error_user_title") == "Missing Target Audience Location"
+                    )
+                ):
+                    return json.dumps({
+                        "error": "Missing target audience location",
+                        "details": raw_err.get("error_user_msg") or "Select at least one location, or choose a custom audience.",
+                        "endpoint_used": f"{account_id}/reachestimate",
+                        "action_required": "Add geo_locations with at least one of countries/regions/cities/zips or include custom_audiences.",
+                        "blame_field_specs": raw_err.get("error_data", {}).get("blame_field_specs") if isinstance(raw_err.get("error_data"), dict) else None
+                    }, indent=2)
+            except Exception:
+                pass
+            # Allow disabling fallback via environment variable
+            # Default: fallback disabled unless explicitly enabled by setting DISABLE flag to "0"
+            disable_fallback = os.environ.get("META_MCP_DISABLE_DELIVERY_FALLBACK", "1") == "1"
+            if disable_fallback:
+                return json.dumps({
+                    "error": "Graph API returned an error for reachestimate",
+                    "details": data.get("error"),
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "request_params": {
+                        "has_targeting_spec": bool(targeting),
+                    },
+                    "note": "delivery_estimate fallback disabled via META_MCP_DISABLE_DELIVERY_FALLBACK"
+                }, indent=2)
+
+            # Try fallback to delivery_estimate endpoint
+            try:
+                fallback_endpoint = f"{account_id}/delivery_estimate"
+                fallback_params = {
+                    "targeting_spec": json.dumps(targeting),
+                    # Some API versions accept optimization_goal here
+                    "optimization_goal": optimization_goal
+                }
+                fallback_data = await make_api_request(fallback_endpoint, access_token, fallback_params, method="GET")
+                
+                # If fallback returns usable data, format similarly
+                if isinstance(fallback_data, dict) and "data" in fallback_data and len(fallback_data["data"]) > 0:
+                    estimate_data = fallback_data["data"][0]
+                    formatted_response = {
+                        "success": True,
+                        "account_id": account_id,
+                        "targeting": targeting,
+                        "optimization_goal": optimization_goal,
+                        "estimated_audience_size": estimate_data.get("estimate_mau", 0),
+                        "estimate_details": {
+                            "monthly_active_users": estimate_data.get("estimate_mau", 0),
+                            "daily_outcomes_curve": estimate_data.get("estimate_dau", []),
+                            "bid_estimate": estimate_data.get("bid_estimates", {}),
+                            "unsupported_targeting": estimate_data.get("unsupported_targeting", [])
+                        },
+                        "raw_response": fallback_data,
+                        "fallback_endpoint_used": "delivery_estimate"
+                    }
+                    return json.dumps(formatted_response, indent=2)
+                
+                # Fallback returned but not in expected format
+                return json.dumps({
+                    "error": "Graph API returned an error for reachestimate; delivery_estimate fallback did not return usable data",
+                    "reachestimate_error": data.get("error"),
+                    "fallback_endpoint_used": "delivery_estimate",
+                    "fallback_raw_response": fallback_data,
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "request_params": {
+                        "has_targeting_spec": bool(targeting)
+                    }
+                }, indent=2)
+            except Exception as _fallback_exc:
+                return json.dumps({
+                    "error": "Graph API returned an error for reachestimate; delivery_estimate fallback also failed",
+                    "reachestimate_error": data.get("error"),
+                    "fallback_endpoint_used": "delivery_estimate",
+                    "fallback_exception": str(_fallback_exc),
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "request_params": {
+                        "has_targeting_spec": bool(targeting)
+                    }
+                }, indent=2)
+
         # Format the response for easier consumption
-        if "data" in data and len(data["data"]) > 0:
-            estimate_data = data["data"][0]
-            formatted_response = {
-                "success": True,
-                "account_id": account_id,
-                "targeting": targeting,
-                "optimization_goal": optimization_goal,
-                "estimated_audience_size": estimate_data.get("estimate_mau", 0),
-                "estimate_details": {
-                    "monthly_active_users": estimate_data.get("estimate_mau", 0),
-                    "daily_outcomes_curve": estimate_data.get("estimate_dau", []),
-                    "bid_estimate": estimate_data.get("bid_estimates", {}),
-                    "unsupported_targeting": estimate_data.get("unsupported_targeting", [])
-                },
-                "raw_response": data
-            }
-            
-            return json.dumps(formatted_response, indent=2)
+        if "data" in data:
+            response_data = data["data"]
+            # Case 1: delivery_estimate-like list structure
+            if isinstance(response_data, list) and len(response_data) > 0:
+                estimate_data = response_data[0]
+                formatted_response = {
+                    "success": True,
+                    "account_id": account_id,
+                    "targeting": targeting,
+                    "optimization_goal": optimization_goal,
+                    "estimated_audience_size": estimate_data.get("estimate_mau", 0),
+                    "estimate_details": {
+                        "monthly_active_users": estimate_data.get("estimate_mau", 0),
+                        "daily_outcomes_curve": estimate_data.get("estimate_dau", []),
+                        "bid_estimate": estimate_data.get("bid_estimates", {}),
+                        "unsupported_targeting": estimate_data.get("unsupported_targeting", [])
+                    },
+                    "raw_response": data
+                }
+                return json.dumps(formatted_response, indent=2)
+            # Case 1b: explicit handling for empty list responses
+            if isinstance(response_data, list) and len(response_data) == 0:
+                return json.dumps({
+                    "error": "No estimation data returned from Meta API",
+                    "raw_response": data,
+                    "debug_info": {
+                        "response_keys": list(data.keys()) if isinstance(data, dict) else "not_a_dict",
+                        "response_type": str(type(data)),
+                        "endpoint_used": f"{account_id}/reachestimate"
+                    }
+                }, indent=2)
+            # Case 2: reachestimate dict structure with bounds
+            if isinstance(response_data, dict):
+                lower = response_data.get("users_lower_bound", response_data.get("estimate_mau_lower_bound"))
+                upper = response_data.get("users_upper_bound", response_data.get("estimate_mau_upper_bound"))
+                estimate_ready = response_data.get("estimate_ready")
+                midpoint = None
+                try:
+                    if isinstance(lower, (int, float)) and isinstance(upper, (int, float)):
+                        midpoint = int((lower + upper) / 2)
+                except Exception:
+                    midpoint = None
+                formatted_response = {
+                    "success": True,
+                    "account_id": account_id,
+                    "targeting": targeting,
+                    "optimization_goal": optimization_goal,
+                    "estimated_audience_size": midpoint if midpoint is not None else 0,
+                    "estimate_details": {
+                        "users_lower_bound": lower,
+                        "users_upper_bound": upper,
+                        "estimate_ready": estimate_ready
+                    },
+                    "raw_response": data
+                }
+                return json.dumps(formatted_response, indent=2)
         else:
             return json.dumps({
                 "error": "No estimation data returned from Meta API",
@@ -189,6 +361,40 @@ async def estimate_audience_size(
             }, indent=2)
     
     except Exception as e:
+        # Try fallback to delivery_estimate first when an exception occurs (unless disabled)
+        # Default: fallback disabled unless explicitly enabled by setting DISABLE flag to "0"
+        disable_fallback = os.environ.get("META_MCP_DISABLE_DELIVERY_FALLBACK", "1") == "1"
+        if not disable_fallback:
+            try:
+                fallback_endpoint = f"{account_id}/delivery_estimate"
+                fallback_params = {
+                "targeting_spec": json.dumps(targeting) if isinstance(targeting, dict) else targeting,
+                "optimization_goal": optimization_goal
+            }
+                fallback_data = await make_api_request(fallback_endpoint, access_token, fallback_params, method="GET")
+            
+                if isinstance(fallback_data, dict) and "data" in fallback_data and len(fallback_data["data"]) > 0:
+                    estimate_data = fallback_data["data"][0]
+                    formatted_response = {
+                        "success": True,
+                        "account_id": account_id,
+                        "targeting": targeting,
+                        "optimization_goal": optimization_goal,
+                        "estimated_audience_size": estimate_data.get("estimate_mau", 0),
+                        "estimate_details": {
+                            "monthly_active_users": estimate_data.get("estimate_mau", 0),
+                            "daily_outcomes_curve": estimate_data.get("estimate_dau", []),
+                            "bid_estimate": estimate_data.get("bid_estimates", {}),
+                            "unsupported_targeting": estimate_data.get("unsupported_targeting", [])
+                        },
+                        "raw_response": fallback_data,
+                        "fallback_endpoint_used": "delivery_estimate"
+                    }
+                    return json.dumps(formatted_response, indent=2)
+            except Exception as _fallback_exc:
+                # If fallback also fails, proceed to detailed error handling below
+                pass
+
         # Check if this is the specific Business Manager system user permission error
         error_str = str(e)
         if "100" in error_str and "33" in error_str:

{meta_ads_mcp-0.11.3.dist-info → meta_ads_mcp-0.11.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.11.3
+Version: 0.11.5
 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.11.3.dist-info → meta_ads_mcp-0.11.5.dist-info}/RECORD

@@ -1,11 +1,11 @@
-meta_ads_mcp/__init__.py,sha256=XuSDqKHzz24tD7w_n-jpx5OHOhle9OiucexV-62FU_4,1477
+meta_ads_mcp/__init__.py,sha256=154Mtk_I8LIeWAnmdGzm5XsuH2zV8pO0QpokRsmL74Y,1477
 meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
 meta_ads_mcp/core/__init__.py,sha256=IEJtqpyUo0CZSUWeQPljQ-D2vKorTFwXnpBQWSi1hIM,1819
 meta_ads_mcp/core/accounts.py,sha256=7Zoqq0zMIJi_Xsxe9-_b3EYx-UTeieJJvO7HxVRuUS0,4327
-meta_ads_mcp/core/ads.py,sha256=gda9FRDAgIFzUjLuyKVWB0H-CfEvWI7hdbB3B22BTUg,60306
+meta_ads_mcp/core/ads.py,sha256=5ulQ4p3lLo1_sIiAoMdyeo0O2y7Yq2zSDuvqkNiqX1c,61376
 meta_ads_mcp/core/ads_library.py,sha256=smGz9FhM6RIUjlQT4Jv1BaZmXahGdK21eRCB7QMhK-4,3228
 meta_ads_mcp/core/adsets.py,sha256=3Ok3EwPTReKshtsVs4gRMlws6LMTUJTb4ZeGPPM8JR8,16570
-meta_ads_mcp/core/api.py,sha256=58F6fRrg3ny_vuLgHu1ZN1yueNAxVXz_nEcF6JlxlWk,16469
+meta_ads_mcp/core/api.py,sha256=dR1h3sTnSmIdEz8OSttqELA0YxBkbjMnSflgM5LsJ1A,16858
 meta_ads_mcp/core/auth.py,sha256=l_IvejK2KYXg8yhBiP0ifE6mGwJ6ZujqYQbVw1KOUME,23649
 meta_ads_mcp/core/authentication.py,sha256=ftoKec1HpfYCCVYIVKUD3ezvVAk6n_CJlBuePn8fzpM,10547
 meta_ads_mcp/core/budget_schedules.py,sha256=FVyJuKbjUE4cmtlPJEbIwpN6JmU-1WQjc7io1y5JaHE,2911
@@ -14,15 +14,15 @@ meta_ads_mcp/core/campaigns.py,sha256=m24epO1QmyBVBXfqHIFZAi6sRCTlOGLQckjy0azqkv
 meta_ads_mcp/core/duplication.py,sha256=wtLLuO5ohbuXO79g-CRdS-_yNLUCZwRkJxukhufdH9g,19024
 meta_ads_mcp/core/http_auth_integration.py,sha256=lGpKhfzJcyWugBcYEvypY-qnlt-3UDBLqh7xAUH0DGw,12473
 meta_ads_mcp/core/insights.py,sha256=O8eldZG7wi46_heVgnOGiHPK3M_YNzvfT81wZQt9m0Q,4710
-meta_ads_mcp/core/openai_deep_research.py,sha256=mqnDK72GXLyH6noJSOXKXnvYGInlk2bst8dOcYLnZ9A,18803
+meta_ads_mcp/core/openai_deep_research.py,sha256=68ayGopnBSPEYhN9R1sFvTXtyWtM0lji9aWS3uSXnLY,18649
 meta_ads_mcp/core/pipeboard_auth.py,sha256=vv0yc4RBcGOm7VOovud-QNV1JmvBF-njOKICzAOlyf0,24602
 meta_ads_mcp/core/reports.py,sha256=2pXYCCjYc3MZ8GlrbSHND436W62WlbfbtMll1dfJdqE,5750
 meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
 meta_ads_mcp/core/server.py,sha256=9SlgM_qvdlxo24ctnZzLgW1e1nfAspCSx3YyJQkKP64,17856
-meta_ads_mcp/core/targeting.py,sha256=-QziS2MvTWzM02pwiUtId4sblWURd3UYPR_YYfVuiUk,13913
+meta_ads_mcp/core/targeting.py,sha256=d2uLWbIEtucRuTgwZEdtVKLDZJgaxQ1lDtZ0ZgkBJC4,25150
 meta_ads_mcp/core/utils.py,sha256=ytj41yC5SqduLrAiZYBSd6OUwlJRaIClTwnnYKpNFds,9387
-meta_ads_mcp-0.11.3.dist-info/METADATA,sha256=-aZjT1svggAzROezO06i6qUHssheEoWUytVXxpG8LEk,24245
-meta_ads_mcp-0.11.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.11.3.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.11.3.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
-meta_ads_mcp-0.11.3.dist-info/RECORD,,
+meta_ads_mcp-0.11.5.dist-info/METADATA,sha256=geRT3vtN0sWL0Iz2viYgiLwvWtPNmS0tpdx41HBX-cI,24245
+meta_ads_mcp-0.11.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.11.5.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.11.5.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
+meta_ads_mcp-0.11.5.dist-info/RECORD,,