meta-ads-mcp 0.7.1__tar.gz → 0.7.3__tar.gz

{meta_ads_mcp-0.7.1 → meta_ads_mcp-0.7.3}/PKG-INFO

@@ -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 → meta_ads_mcp-0.7.3}/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-0.7.3/meta_ads_mcp/core/ads_library.py

@@ -0,0 +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
+
+
+# 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", ""))
+
+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.
+
+        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.
+
+        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 search_terms:
+            return json.dumps({"error": "search_terms parameter is required"}, indent=2)
+
+        if not ad_reached_countries:
+            return json.dumps({"error": "ad_reached_countries 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,
+        }
+
+        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-0.7.1 → meta_ads_mcp-0.7.3}/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 → meta_ads_mcp-0.7.3}/pyproject.toml

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

meta_ads_mcp-0.7.1/meta_ads_mcp/core/ads_library.py

@@ -1,69 +0,0 @@
-"""Adds Library-related functionality for Meta Ads API."""
-
-import json
-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.
-
-    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.
-
-    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 search_terms:
-        return json.dumps({"error": "search_terms parameter is required"}, indent=2)
-
-    if not ad_reached_countries:
-        return json.dumps({"error": "ad_reached_countries 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,
-    }
-
-    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)