meta-ads-mcp 0.10.0__tar.gz → 0.10.2__tar.gz

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.10.0
-Summary: Model Context Protocol (MCP) plugin for interacting with Meta Ads API
+Version: 0.10.2
+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
 Author-email: Yves Junqueira <yves.junqueira@gmail.com>
@@ -43,6 +43,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 - [Features](#features)
 - [Configuration](#configuration)
 - [Available MCP Tools](#available-mcp-tools)
+- [Licensing](#licensing)
 - [Privacy and Security](#privacy-and-security)
 - [Testing](#testing)
 - [Troubleshooting](#troubleshooting)
@@ -407,6 +408,17 @@ For local installation configuration, authentication options, and advanced techn
       - `query`: Search query string (e.g., "Injury Payouts pages", "active campaigns")
     - Returns: List of matching record IDs in ChatGPT-compatible format
 
+## Licensing
+
+Meta Ads MCP is licensed under the [Business Source License 1.1](LICENSE), which means:
+
+- ✅ **Free to use** for individual and business purposes
+- ✅ **Modify and customize** as needed
+- ✅ **Redistribute** to others
+- ✅ **Becomes fully open source** (Apache 2.0) on January 1, 2029
+
+The only restriction is that you cannot offer this as a competing hosted service. For questions about commercial licensing, please contact us.
+
 ## Privacy and Security
 
 Meta Ads MCP follows security best practices with secure token management and automatic authentication handling. 

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/README.md

@@ -18,6 +18,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 - [Features](#features)
 - [Configuration](#configuration)
 - [Available MCP Tools](#available-mcp-tools)
+- [Licensing](#licensing)
 - [Privacy and Security](#privacy-and-security)
 - [Testing](#testing)
 - [Troubleshooting](#troubleshooting)
@@ -382,6 +383,17 @@ For local installation configuration, authentication options, and advanced techn
       - `query`: Search query string (e.g., "Injury Payouts pages", "active campaigns")
     - Returns: List of matching record IDs in ChatGPT-compatible format
 
+## Licensing
+
+Meta Ads MCP is licensed under the [Business Source License 1.1](LICENSE), which means:
+
+- ✅ **Free to use** for individual and business purposes
+- ✅ **Modify and customize** as needed
+- ✅ **Redistribute** to others
+- ✅ **Becomes fully open source** (Apache 2.0) on January 1, 2029
+
+The only restriction is that you cannot offer this as a competing hosted service. For questions about commercial licensing, please contact us.
+
 ## Privacy and Security
 
 Meta Ads MCP follows security best practices with secure token management and automatic authentication handling. 

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/meta_ads_mcp/__init__.py

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

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/meta_ads_mcp/core/adsets.py

@@ -130,8 +130,9 @@ async def create_adset(
         promoted_object: Mobile app configuration for APP_INSTALLS campaigns. Required fields: application_id, object_store_url.
                         Optional fields: custom_event_type, pixel_id, page_id.
                         Example: {"application_id": "123456789012345", "object_store_url": "https://apps.apple.com/app/id123456789"}
-        destination_type: Where users are directed after clicking the ad (e.g., 'APP_STORE', 'DEEPLINK', 'APP_INSTALL').
-                         Required for mobile app campaigns.
+        destination_type: Where users are directed after clicking the ad (e.g., 'APP_STORE', 'DEEPLINK', 'APP_INSTALL', 'ON_AD').
+                         Required for mobile app campaigns and lead generation campaigns.
+                         Use 'ON_AD' for lead generation campaigns where user interaction happens within the ad.
         access_token: Meta API access token (optional - will use cached token if not provided)
     """
     # Check required parameters
@@ -196,7 +197,7 @@ async def create_adset(
     
     # Validate destination_type if provided
     if destination_type:
-        valid_destination_types = ["APP_STORE", "DEEPLINK", "APP_INSTALL"]
+        valid_destination_types = ["APP_STORE", "DEEPLINK", "APP_INSTALL", "ON_AD"]
         if destination_type not in valid_destination_types:
             return json.dumps({
                 "error": f"Invalid destination_type: {destination_type}",

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/meta_ads_mcp/core/targeting.py

@@ -147,27 +147,16 @@ async def estimate_audience_size(
             }
         }, indent=2)
     
-    # Build delivery estimate request
-    endpoint = f"{account_id}/delivery_estimate"
+    # Build reach estimate request (using correct Meta API endpoint)
+    endpoint = f"{account_id}/reachestimate"
     params = {
-        "targeting": targeting,
-        "optimization_goal": optimization_goal
+        "targeting_spec": targeting
     }
     
-    # Add basic campaign parameters for estimation
-    if optimization_goal == "REACH":
-        params["objective"] = "REACH"
-    elif optimization_goal in ["LINK_CLICKS", "LANDING_PAGE_VIEWS"]:
-        params["objective"] = "TRAFFIC"
-    elif optimization_goal == "CONVERSIONS":
-        params["objective"] = "CONVERSIONS"
-    elif optimization_goal == "APP_INSTALLS":
-        params["objective"] = "APP_INSTALLS"
-    else:
-        params["objective"] = "REACH"  # Default fallback
+    # Note: reachestimate endpoint doesn't support optimization_goal or objective parameters
     
     try:
-        data = await make_api_request(endpoint, access_token, params, method="POST")
+        data = await make_api_request(endpoint, access_token, params, method="GET")
         
         # Format the response for easier consumption
         if "data" in data and len(data["data"]) > 0:
@@ -191,14 +180,69 @@ async def estimate_audience_size(
         else:
             return json.dumps({
                 "error": "No estimation data returned from Meta API",
-                "raw_response": data
+                "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)
     
     except Exception as e:
-        return json.dumps({
-            "error": f"Failed to get audience estimation: {str(e)}",
-            "details": "Check targeting parameters and account permissions"
-        }, indent=2)
+        # 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:
+            # Try to provide fallback estimation using individual interests if available
+            interests_found = []
+            if targeting and "interests" in targeting:
+                interests_found.extend([interest.get("id") for interest in targeting["interests"] if interest.get("id")])
+            elif targeting and "flexible_spec" in targeting:
+                for spec in targeting["flexible_spec"]:
+                    if "interests" in spec:
+                        interests_found.extend([interest.get("id") for interest in spec["interests"] if interest.get("id")])
+            
+            if interests_found:
+                # Attempt to get individual interest data as fallback
+                try:
+                    fallback_result = await estimate_audience_size(
+                        access_token=access_token,
+                        interest_fbid_list=interests_found
+                    )
+                    fallback_data = json.loads(fallback_result)
+                    
+                    return json.dumps({
+                        "comprehensive_targeting_failed": True,
+                        "error_code": "100-33",
+                        "fallback_used": True,
+                        "details": {
+                            "issue": "reachestimate endpoint returned error - possibly due to targeting parameters or account limitations",
+                            "solution": "Individual interest validation used as fallback - comprehensive targeting may have specific requirements",
+                            "endpoint_used": f"{account_id}/reachestimate"
+                        },
+                        "individual_interest_data": fallback_data,
+                        "note": "Individual interest audience sizes provided as fallback. Comprehensive targeting via reachestimate endpoint failed."
+                    }, indent=2)
+                except:
+                    pass
+            
+            return json.dumps({
+                "error": "reachestimate endpoint returned error (previously was incorrectly using delivery_estimate)",
+                "error_code": "100-33", 
+                "details": {
+                    "issue": "The endpoint returned an error, possibly due to targeting parameters or account limitations",
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "previous_issue": "Code was previously using non-existent delivery_estimate endpoint - now fixed",
+                    "available_alternative": "Use interest_list or interest_fbid_list parameters for individual interest validation"
+                },
+                "raw_error": error_str
+            }, indent=2)
+        else:
+            return json.dumps({
+                "error": f"Failed to get audience estimation from reachestimate endpoint: {str(e)}",
+                "details": "Check targeting parameters and account permissions",
+                "error_type": "general_api_error",
+                "endpoint_used": f"{account_id}/reachestimate"
+            }, indent=2)
 
 
 @mcp_server.tool()

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-ads-mcp"
-version = "0.10.0"
-description = "Model Context Protocol (MCP) plugin for interacting with Meta Ads API"
+version = "0.10.2"
+description = "Model Context Protocol (MCP) server for interacting with Meta Ads API"
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/tests/test_estimate_audience_size.py

@@ -3,7 +3,7 @@
 Unit tests for estimate_audience_size functionality in Meta Ads MCP.
 
 This module tests the new estimate_audience_size function that replaces validate_interests
-and provides comprehensive audience estimation using Meta's delivery_estimate API.
+and provides comprehensive audience estimation using Meta's reachestimate API.
 """
 
 import pytest
@@ -58,14 +58,12 @@ class TestEstimateAudienceSize:
             
             # Verify API call
             mock_api.assert_called_once_with(
-                "act_123456789/delivery_estimate",
+                "act_123456789/reachestimate",
                 "test_token",
                 {
-                    "targeting": targeting_spec,
-                    "optimization_goal": "REACH",
-                    "objective": "REACH"
+                    "targeting_spec": targeting_spec
                 },
-                method="POST"
+                method="GET"
             )
             
             # Verify response format
@@ -80,7 +78,7 @@ class TestEstimateAudienceSize:
     
     @pytest.mark.asyncio
     async def test_different_optimization_goals(self):
-        """Test audience estimation with different optimization goals"""
+        """Test audience estimation with different optimization goals (parameter is preserved in response)"""
         mock_response = {
             "data": [
                 {
@@ -98,19 +96,13 @@ class TestEstimateAudienceSize:
             "geo_locations": {"countries": ["US"]}
         }
         
-        test_cases = [
-            ("REACH", "REACH"),
-            ("LINK_CLICKS", "TRAFFIC"),
-            ("LANDING_PAGE_VIEWS", "TRAFFIC"),
-            ("CONVERSIONS", "CONVERSIONS"),
-            ("APP_INSTALLS", "APP_INSTALLS"),
-            ("UNKNOWN_GOAL", "REACH")  # Should fallback to REACH
-        ]
+        # Test different optimization goals - they should all use the same reachestimate endpoint
+        test_goals = ["REACH", "LINK_CLICKS", "LANDING_PAGE_VIEWS", "CONVERSIONS", "APP_INSTALLS"]
         
         with patch('meta_ads_mcp.core.targeting.make_api_request', new_callable=AsyncMock) as mock_api:
             mock_api.return_value = mock_response
             
-            for optimization_goal, expected_objective in test_cases:
+            for optimization_goal in test_goals:
                 mock_api.reset_mock()
                 
                 result = await estimate_audience_size(
@@ -120,16 +112,14 @@ class TestEstimateAudienceSize:
                     optimization_goal=optimization_goal
                 )
                 
-                # Verify correct objective mapping
+                # Verify API call uses reachestimate endpoint with simplified parameters
                 mock_api.assert_called_once_with(
-                    "act_123456789/delivery_estimate",
+                    "act_123456789/reachestimate",
                     "test_token",
                     {
-                        "targeting": targeting_spec,
-                        "optimization_goal": optimization_goal,
-                        "objective": expected_objective
+                        "targeting_spec": targeting_spec
                     },
-                    method="POST"
+                    method="GET"
                 )
                 
                 result_data = json.loads(result)
@@ -316,7 +306,7 @@ class TestEstimateAudienceSize:
     
     @pytest.mark.asyncio
     async def test_api_error_handling(self):
-        """Test handling of API errors from delivery_estimate"""
+        """Test handling of API errors from reachestimate"""
         targeting_spec = {
             "age_min": 25,
             "age_max": 65,
@@ -338,12 +328,12 @@ class TestEstimateAudienceSize:
             assert "data" in result_data
             nested_data = json.loads(result_data["data"])
             assert "error" in nested_data
-            assert "Failed to get audience estimation" in nested_data["error"]
+            assert "Failed to get audience estimation from reachestimate endpoint" in nested_data["error"]
             assert "details" in nested_data
     
     @pytest.mark.asyncio
     async def test_empty_api_response(self):
-        """Test handling of empty response from delivery_estimate API"""
+        """Test handling of empty response from reachestimate API"""
         targeting_spec = {
             "age_min": 25,
             "age_max": 65,

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/tests/test_estimate_audience_size_e2e.py

@@ -614,7 +614,7 @@ class AudienceEstimationTester:
             print(f"\n✅ Audience estimation tests: SUCCESS ({passed_tests}/{total_tests} passed)")
             print("   • Comprehensive audience estimation is working")
             print("   • Backwards compatibility is maintained")
-            print("   • Meta delivery_estimate API integration is functional")
+            print("   • Meta reachestimate API integration is functional")
             return True
         else:
             print(f"\n❌ Audience estimation tests: FAILED ({passed_tests}/{total_tests} passed)")

{meta_ads_mcp-0.10.0 → meta_ads_mcp-0.10.2}/tests/test_mobile_app_adset_creation.py

@@ -409,6 +409,57 @@ class TestMobileAppAdsetCreation:
         params = call_args[0][2]
         assert params['destination_type'] == "APP_INSTALL"
 
+    @pytest.mark.asyncio
+    async def test_on_ad_destination_type_for_lead_generation(
+        self, mock_api_request, mock_auth_manager, valid_mobile_app_params
+    ):
+        """Test ON_AD destination_type for lead generation campaigns (Issue #009 fix)"""
+        
+        # Create a lead generation adset configuration (without promoted_object since it's for lead gen, not mobile apps)
+        lead_gen_params = valid_mobile_app_params.copy()
+        lead_gen_params.update({
+            "optimization_goal": "LEAD_GENERATION",
+            "billing_event": "IMPRESSIONS"
+        })
+        
+        result = await create_adset(
+            **lead_gen_params,
+            destination_type="ON_AD"
+        )
+        
+        # Should pass validation and include destination_type in API call
+        call_args = mock_api_request.call_args
+        params = call_args[0][2]
+        assert params['destination_type'] == "ON_AD"
+
+    @pytest.mark.asyncio
+    async def test_on_ad_validation_passes(
+        self, mock_api_request, mock_auth_manager, valid_mobile_app_params
+    ):
+        """Test that ON_AD destination_type passes validation (Issue #009 regression test)"""
+        
+        # Use parameters that work with ON_AD (lead generation, not mobile app)
+        lead_gen_params = valid_mobile_app_params.copy()
+        lead_gen_params.update({
+            "optimization_goal": "LEAD_GENERATION",
+            "billing_event": "IMPRESSIONS"
+        })
+        
+        result = await create_adset(
+            **lead_gen_params,
+            destination_type="ON_AD"
+        )
+        
+        result_data = json.loads(result)
+        
+        # Should NOT return a validation error about destination_type
+        # Before the fix, this would return: "Invalid destination_type: ON_AD" 
+        if "data" in result_data:
+            error_data = json.loads(result_data["data"])
+            assert "error" not in error_data or "destination_type" not in error_data.get("error", "").lower()
+        else:
+            assert "error" not in result_data or "destination_type" not in result_data.get("error", "").lower()
+
     # Test: Error Handling
     @pytest.mark.asyncio
     async def test_meta_api_error_handling(