meta-ads-mcp 0.11.4__py3-none-any.whl → 0.11.6__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.4"
+__version__ = "0.11.6"
 
 __all__ = [
     'get_ad_accounts',

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/duplication.py

@@ -30,7 +30,7 @@ if ENABLE_DUPLICATION:
         """
         Duplicate a Meta Ads campaign with all its ad sets and ads.
 
-        **SUBSCRIPTION REQUIRED**: This feature requires an active subscription.
+        Recommended: Use this to run robust experiments.
         
         Args:
             campaign_id: Meta Ads campaign ID to duplicate
@@ -73,7 +73,7 @@ if ENABLE_DUPLICATION:
         """
         Duplicate a Meta Ads ad set with its ads.
 
-        **SUBSCRIPTION REQUIRED**: This feature requires an active subscription.
+        Recommended: Use this to run robust experiments.
         
         Args:
             adset_id: Meta Ads ad set ID to duplicate
@@ -114,7 +114,7 @@ if ENABLE_DUPLICATION:
         """
         Duplicate a Meta Ads ad.
 
-        **SUBSCRIPTION REQUIRED**: This feature requires an active subscription.
+        Recommended: Use this to run robust experiments.
         
         Args:
             ad_id: Meta Ads ad ID to duplicate
@@ -152,7 +152,7 @@ if ENABLE_DUPLICATION:
         """
         Duplicate a Meta Ads creative.
 
-        **SUBSCRIPTION REQUIRED**: This feature requires an active subscription.
+        Recommended: Use this to run robust experiments.
         
         Args:
             creative_id: Meta Ads creative ID to duplicate

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.4.dist-info → meta_ads_mcp-0.11.6.dist-info}/METADATA

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

@@ -1,17 +1,17 @@
-meta_ads_mcp/__init__.py,sha256=4ruafDZ8uRX6-M1cFTV4c2wPA_D37Y3cpfLDKY5jQ4g,1477
+meta_ads_mcp/__init__.py,sha256=gdm32l1E4vgI6a8WI_vbxqmq9Tfvl4g4TeWUcZkSWbg,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=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
 meta_ads_mcp/core/callback_server.py,sha256=LIAJv9DW--83kdZ7VWWZal8xEprYjRZ8iug4rMczYbQ,9372
 meta_ads_mcp/core/campaigns.py,sha256=m24epO1QmyBVBXfqHIFZAi6sRCTlOGLQckjy0azqkvo,14319
-meta_ads_mcp/core/duplication.py,sha256=wtLLuO5ohbuXO79g-CRdS-_yNLUCZwRkJxukhufdH9g,19024
+meta_ads_mcp/core/duplication.py,sha256=ae9GisFg9MMXbgX8zqb6ekEFIv7DGNCMV-lwkDXSL-c,18928
 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=68ayGopnBSPEYhN9R1sFvTXtyWtM0lji9aWS3uSXnLY,18649
@@ -19,10 +19,10 @@ meta_ads_mcp/core/pipeboard_auth.py,sha256=vv0yc4RBcGOm7VOovud-QNV1JmvBF-njOKICz
 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.4.dist-info/METADATA,sha256=pI9J1eNS624ATvgJQKdrYDSldUQ7MKRan1DDEjNo5IM,24245
-meta_ads_mcp-0.11.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.11.4.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.11.4.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
-meta_ads_mcp-0.11.4.dist-info/RECORD,,
+meta_ads_mcp-0.11.6.dist-info/METADATA,sha256=8ZciePGi_K5-6VYwh7D50rbJDjPVLlyLHpAv0JWFWAA,24245
+meta_ads_mcp-0.11.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.11.6.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.11.6.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
+meta_ads_mcp-0.11.6.dist-info/RECORD,,