ArmaVita Meta Ads MCP

Instructions

Implementation Reference

• src/armavita_meta_ads_mcp/core/ads_archive_tools.py:21-59 (handler)

  The handler implementation for the search_ads_archive MCP tool. It uses decorators for registration and makes the API request via make_api_request.

  @mcp_server.tool()
  @meta_api_tool
  async def search_ads_archive(
      search_terms: str,
      ad_reached_countries: List[str],
      meta_access_token: Optional[str] = None,
      ad_type: str = "ALL",
      page_size: int = 25,
      page_cursor: str = "",
      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 ads in Meta's public Ads Library endpoint."""
      if not str(search_terms or "").strip():
          return json.dumps({"error": "search_terms parameter is required"}, indent=2)
  
      if not isinstance(ad_reached_countries, list) or not ad_reached_countries:
          return json.dumps({"error": "ad_reached_countries parameter is required"}, indent=2)
  
      countries = [str(code).strip().upper() for code in ad_reached_countries if str(code).strip()]
      if not countries:
          return json.dumps({"error": "ad_reached_countries parameter is required"}, indent=2)
  
      payload = {
          "search_terms": search_terms,
          "ad_reached_countries": countries,
          "ad_type": _normalize_ad_type(ad_type),
          "page_size": int(page_size),
          "fields": fields,
      }
      if page_cursor:
          payload["page_cursor"] = page_cursor
  
      result = await make_api_request("ads_archive", meta_access_token, payload, method="GET")
      return json.dumps(result, indent=2)