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

meta_ads_mcp/core/ads_library.py

@@ -1,69 +1,74 @@
 """Adds Library-related functionality for Meta Ads API."""
 
 import json
+import os
 from typing import Optional, List, Dict, Any
 from .api import meta_api_tool, make_api_request
 from .server import mcp_server
 
 
-@mcp_server.tool()
-@meta_api_tool
-async def search_ads_archive(
-    access_token: str = None,
-    search_terms: 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:
-    """
-    Search the Facebook Ads Library archive.
+# Only register the search_ads_archive function if the environment variable is NOT set
+DISABLE_ADS_LIBRARY = bool(os.environ.get("META_ADS_DISABLE_ADS_LIBRARY", ""))
 
-    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"]).
-        limit: Maximum number of ads to return.
-        fields: Comma-separated string of fields to retrieve for each ad.
+if not DISABLE_ADS_LIBRARY:
+    @mcp_server.tool()
+    @meta_api_tool
+    async def search_ads_archive(
+        access_token: str = None,
+        search_terms: 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:
+        """
+        Search the Facebook Ads Library archive.
 
-    Example Usage via curl equivalent:
-        curl -G \\
-        -d "search_terms='california'" \\
-        -d "ad_type=POLITICAL_AND_ISSUE_ADS" \\
-        -d "ad_reached_countries=['US']" \\
-        -d "fields=ad_snapshot_url,spend" \\
-        -d "access_token=<ACCESS_TOKEN>" \\
-        "https://graph.facebook.com/<API_VERSION>/ads_archive"
-    """
-    if not access_token:
-        # Attempt to get token implicitly if not provided - meta_api_tool handles this
-        pass
+        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"]).
+            limit: Maximum number of ads to return.
+            fields: Comma-separated string of fields to retrieve for each ad.
 
-    if not search_terms:
-        return json.dumps({"error": "search_terms parameter is required"}, indent=2)
+        Example Usage via curl equivalent:
+            curl -G \\
+            -d "search_terms='california'" \\
+            -d "ad_type=POLITICAL_AND_ISSUE_ADS" \\
+            -d "ad_reached_countries=['US']" \\
+            -d "fields=ad_snapshot_url,spend" \\
+            -d "access_token=<ACCESS_TOKEN>" \\
+            "https://graph.facebook.com/<API_VERSION>/ads_archive"
+        """
+        if not access_token:
+            # Attempt to get token implicitly if not provided - meta_api_tool handles this
+            pass
 
-    if not ad_reached_countries:
-        return json.dumps({"error": "ad_reached_countries parameter is required"}, indent=2)
+        if not search_terms:
+            return json.dumps({"error": "search_terms parameter is required"}, indent=2)
 
-    endpoint = "ads_archive"
-    params = {
-        "search_terms": search_terms,
-        "ad_type": ad_type,
-        "ad_reached_countries": json.dumps(ad_reached_countries), # API expects a JSON array string
-        "limit": limit,
-        "fields": fields,
-    }
+        if not ad_reached_countries:
+            return json.dumps({"error": "ad_reached_countries parameter is required"}, indent=2)
 
-    try:
-        data = await make_api_request(endpoint, access_token, params, method="GET")
-        return json.dumps(data, indent=2)
-    except Exception as e:
-        error_msg = str(e)
-        # Consider logging the full error for debugging
-        # print(f"Error calling Ads Library API: {error_msg}")
-        return json.dumps({
-            "error": "Failed to search ads archive",
-            "details": error_msg,
-            "params_sent": {k: v for k, v in params.items() if k != 'access_token'} # Avoid logging token
-        }, indent=2) 
+        endpoint = "ads_archive"
+        params = {
+            "search_terms": search_terms,
+            "ad_type": ad_type,
+            "ad_reached_countries": json.dumps(ad_reached_countries), # API expects a JSON array string
+            "limit": limit,
+            "fields": fields,
+        }
+
+        try:
+            data = await make_api_request(endpoint, access_token, params, method="GET")
+            return json.dumps(data, indent=2)
+        except Exception as e:
+            error_msg = str(e)
+            # Consider logging the full error for debugging
+            # print(f"Error calling Ads Library API: {error_msg}")
+            return json.dumps({
+                "error": "Failed to search ads archive",
+                "details": error_msg,
+                "params_sent": {k: v for k, v in params.items() if k != 'access_token'} # Avoid logging token
+            }, indent=2) 

meta_ads_mcp/core/authentication.py

@@ -60,18 +60,22 @@ async def get_login_link(access_token: str = None) -> str:
             # If an access token was provided, this is likely a test - return success
             if access_token:
                 return json.dumps({
-                    "message": "Manual token provided",
-                    "token_status": "Provided token",
-                    "authentication_method": "manual_token"
+                    "message": "✅ Authentication Token Provided",
+                    "status": "Using provided access token for authentication",
+                    "token_info": f"Token preview: {access_token[:10]}...",
+                    "authentication_method": "manual_token",
+                    "ready_to_use": "You can now use all Meta Ads MCP tools and commands."
                 }, indent=2)
             
             # Check if Pipeboard token is working
             token = pipeboard_auth_manager.get_access_token()
             if token:
                 return json.dumps({
-                    "message": "Already authenticated via Pipeboard",
-                    "token_status": "Valid Pipeboard token",
-                    "authentication_method": "pipeboard_token"
+                    "message": "✅ Already Authenticated",
+                    "status": "You're successfully authenticated with Meta Ads via Pipeboard!",
+                    "token_info": f"Token preview: {token[:10]}...",
+                    "authentication_method": "pipeboard_token",
+                    "ready_to_use": "You can now use all Meta Ads MCP tools and commands."
                 }, indent=2)
             
             # Start Pipeboard auth flow
@@ -80,39 +84,51 @@ async def get_login_link(access_token: str = None) -> str:
             
             if login_url:
                 return json.dumps({
+                    "message": "🔗 Click to Authenticate",
                     "login_url": login_url,
-                    "markdown_link": f"[Click here to authenticate with Meta Ads 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.",
+                    "markdown_link": f"[🚀 Authenticate with Meta Ads]({login_url})",
+                    "instructions": "Click the link above to complete authentication with Meta Ads.",
                     "authentication_method": "pipeboard_oauth",
-                    "note": "After authenticating, the token will be automatically retrieved from Pipeboard."
+                    "what_happens_next": "After clicking, you'll be redirected to Meta's authentication page. Once completed, your token will be automatically saved.",
+                    "token_duration": "Your token will be valid for approximately 60 days."
                 }, indent=2)
             else:
                 return json.dumps({
-                    "error": "No login URL received from Pipeboard",
+                    "message": "❌ Authentication Error",
+                    "error": "Could not generate authentication URL from Pipeboard",
+                    "troubleshooting": [
+                        "Check that your PIPEBOARD_API_TOKEN is valid",
+                        "Ensure the Pipeboard service is accessible",
+                        "Try again in a few moments"
+                    ],
                     "authentication_method": "pipeboard_oauth_failed"
                 }, indent=2)
                 
         except Exception as e:
             logger.error(f"Error initiating Pipeboard auth flow: {e}")
             return json.dumps({
+                "message": "❌ Pipeboard Authentication Error",
                 "error": f"Failed to initiate Pipeboard authentication: {str(e)}",
-                "message": "Please check your PIPEBOARD_API_TOKEN environment variable.",
-                "authentication_method": "pipeboard"
+                "troubleshooting": [
+                    "✅ Check that PIPEBOARD_API_TOKEN environment variable is set correctly",
+                    "🌐 Verify that pipeboard.co is accessible from your network",
+                    "🔄 Try refreshing your Pipeboard API token",
+                    "⏰ Wait a moment and try again"
+                ],
+                "get_help": "Contact support if the issue persists",
+                "authentication_method": "pipeboard_error"
             }, indent=2)
     elif callback_server_disabled:
         # Production OAuth flow - use Pipeboard OAuth endpoints directly
         logger.info("Production OAuth flow - using Pipeboard OAuth endpoints")
         
         return json.dumps({
-            "authorization_endpoint": "https://pipeboard.co/oauth/authorize", 
-            "token_endpoint": "https://pipeboard.co/oauth/token",
-            "registration_endpoint": "https://pipeboard.co/oauth/register",
-            "discovery_endpoint": "/.well-known/oauth-authorization-server",
-            "message": "Production OAuth flow - use dynamic client registration",
-            "instructions": "MCP clients should use the OAuth discovery endpoint to get authorization URLs",
-            "authentication_method": "production_oauth",
-            "note": "For manual authentication, clients need to register with Pipeboard OAuth service first"
+            "message": "🔐 Authentication Required",
+            "instructions": "Please sign in to your Pipeboard account to authenticate with Meta Ads.",
+            "sign_in_url": "https://pipeboard.co/auth/signin",
+            "markdown_link": "[🚀 Sign in to Pipeboard](https://pipeboard.co/auth/signin)",
+            "what_to_do": "Click the link above to sign in to your Pipeboard account and complete authentication.",
+            "authentication_method": "production_oauth"
         }, indent=2)
     else:
         # Original Meta authentication flow (development/local)
@@ -124,12 +140,13 @@ async def get_login_link(access_token: str = None) -> str:
         if cached_token and not access_token:
             logger.info("get_login_link called with existing valid token")
             return json.dumps({
-                "message": "Already authenticated",
-                "token_status": token_status,
-                "token_preview": cached_token[:10] + "...",
+                "message": "✅ Already Authenticated", 
+                "status": "You're successfully authenticated with Meta Ads!",
+                "token_info": f"Token preview: {cached_token[:10]}...",
                 "created_at": auth_manager.token_info.created_at if hasattr(auth_manager, "token_info") else None,
                 "expires_in": auth_manager.token_info.expires_in if hasattr(auth_manager, "token_info") else None,
-                "authentication_method": "meta_oauth"
+                "authentication_method": "meta_oauth",
+                "ready_to_use": "You can now use all Meta Ads MCP tools and commands."
             }, indent=2)
         
         # IMPORTANT: Start the callback server first by calling our helper function
@@ -147,9 +164,14 @@ async def get_login_link(access_token: str = None) -> str:
         except Exception as e:
             logger.error(f"Failed to start callback server: {e}")
             return json.dumps({
-                "error": "Callback server disabled",
-                "message": str(e),
-                "suggestion": "Use Pipeboard authentication (set PIPEBOARD_API_TOKEN) or provide a direct access token",
+                "message": "❌ Local Authentication Unavailable",
+                "error": "Cannot start local callback server for authentication",
+                "reason": str(e),
+                "solutions": [
+                    "🌐 Use Pipeboard authentication: Set PIPEBOARD_API_TOKEN environment variable",
+                    "🔑 Use direct token: Set META_ACCESS_TOKEN environment variable", 
+                    "🔧 Check if another service is using the required ports"
+                ],
                 "authentication_method": "meta_oauth_disabled"
             }, indent=2)
         
@@ -159,19 +181,15 @@ async def get_login_link(access_token: str = None) -> str:
         
         # Return a special format that helps the LLM format the response properly
         response = {
+            "message": "🔗 Click to Authenticate",
             "login_url": login_url,
-            "token_status": token_status,
-            "server_status": f"Callback server running on port {port}",
-            "markdown_link": f"[Click here to authenticate with Meta Ads]({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.",
-            "token_exchange": "enabled" if token_exchange_supported else "disabled",
-            "token_duration": token_duration,
+            "markdown_link": f"[🚀 Authenticate with Meta Ads]({login_url})",
+            "instructions": "Click the link above to authenticate with Meta Ads.",
+            "server_info": f"Local callback server running on port {port}",
+            "token_duration": f"Your token will be valid for approximately {token_duration}",
             "authentication_method": "meta_oauth",
-            "token_exchange_message": f"Your authentication token will be valid for approximately {token_duration}." + 
-                                    (" Long-lived token exchange is enabled." if token_exchange_supported else 
-                                    " For direct Meta authentication, long-lived tokens require META_APP_SECRET. Consider using Pipeboard authentication instead (60-day tokens by default)."),
-            "note": "After authenticating, the token will be automatically saved."
+            "what_happens_next": "After clicking, you'll be redirected to Meta's authentication page. Once completed, your token will be automatically saved.",
+            "security_note": "This uses a secure local callback server for development purposes."
         }
         
         # Wait a moment to ensure the server is fully started

{meta_ads_mcp-0.7.1.dist-info → meta_ads_mcp-0.7.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.7.1
+Version: 0.7.3
 Summary: Model Context Protocol (MCP) plugin 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.7.1.dist-info → meta_ads_mcp-0.7.3.dist-info}/RECORD

@@ -1,13 +1,13 @@
-meta_ads_mcp/__init__.py,sha256=NX5qdfpot2sNJBbh373KM5xNYIYBL3Wq_rNQz9Dop1M,1492
+meta_ads_mcp/__init__.py,sha256=zoHok7v3IrW0q7qRG2A-7SKBUairjLpMXZTtDJsvpxY,1492
 meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
 meta_ads_mcp/core/__init__.py,sha256=IHBUfLTQW44VLbH_gZDT83nqzGrVWZ0l7FG4P3bp_bU,1706
 meta_ads_mcp/core/accounts.py,sha256=Nmp7lPxO9wmq25jWV7_H0LIqnEbBhpCVBlLGW2HUaq0,2277
 meta_ads_mcp/core/ads.py,sha256=aaK70mgfhBJRXr4cdkKag5mjYzvHuHpRttJvTMzPk4Y,36156
-meta_ads_mcp/core/ads_library.py,sha256=onStn9UkRqYDC60gOPS-iKDtP1plz6DygUb7hUZ0Jw8,2807
+meta_ads_mcp/core/ads_library.py,sha256=BBGVbtjO5eFV42iiY3XPU-wIV8HupzUKpHgPBrydSvU,3232
 meta_ads_mcp/core/adsets.py,sha256=k76rm3rkhEebUzvBnM_QaVktrzGTKvTJOtWbBd6s3i8,10399
 meta_ads_mcp/core/api.py,sha256=aAzM6Q75VQOFXtr5D-mDmBRhxWK4wsiODsJYnR3mpDI,14994
 meta_ads_mcp/core/auth.py,sha256=H-0s0O2fLo14rmi81Hh5S64pyRl1HS7dm9Q_8UCa3Jg,21622
-meta_ads_mcp/core/authentication.py,sha256=K_LqL1NHtgVlO4aHsnXqHc9zrH9jMmuPpREZBO4KVss,9205
+meta_ads_mcp/core/authentication.py,sha256=-AJxa3a5ZshRCvmJThBaNwCAJ1D2_qOgUkvu539c_MY,10159
 meta_ads_mcp/core/budget_schedules.py,sha256=UxseExsvKAiPwfDCY9aycT4kys4xqeNytyq-yyDOxrs,2901
 meta_ads_mcp/core/callback_server.py,sha256=LIAJv9DW--83kdZ7VWWZal8xEprYjRZ8iug4rMczYbQ,9372
 meta_ads_mcp/core/campaigns.py,sha256=Fd477GsD1Gx08Ve0uXUCvr4fC-xQCeVHPBwRVaeRQKk,10965
@@ -21,8 +21,8 @@ meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0
 meta_ads_mcp/core/server.py,sha256=WhbAag7xdhbGcp7rnU4sKhqXJ8Slapa_ba3T23Yp_2U,17889
 meta_ads_mcp/core/targeting.py,sha256=3HW1qirEdwaQurlBZGenbIwawcb5J06ghJKRfgu9ZEs,6318
 meta_ads_mcp/core/utils.py,sha256=ofKUhyo-5SZoJVuBeTVFPPQCffk0UKpwmDMrd8qQxNc,8715
-meta_ads_mcp-0.7.1.dist-info/METADATA,sha256=6H5Wclw8Xg2KH3UYh4VphwFDQGgZVq2pDdXClqannjg,20409
-meta_ads_mcp-0.7.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.7.1.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.7.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-meta_ads_mcp-0.7.1.dist-info/RECORD,,
+meta_ads_mcp-0.7.3.dist-info/METADATA,sha256=VIUGrJrlUcsNKtHH45dK7H0CXn3YuK87_T4BCdM_0UA,20409
+meta_ads_mcp-0.7.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.7.3.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.7.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+meta_ads_mcp-0.7.3.dist-info/RECORD,,