ArmaVita Meta Ads MCP

Implementation Reference

• src/armavita_meta_ads_mcp/core/ad_tools.py:470-516 (handler)

  The `list_ad_previews` function is defined as an MCP tool in `src/armavita_meta_ads_mcp/core/ad_tools.py`. It fetches ad previews from the Meta API and implements a fallback mechanism if the API requires an explicit `ad_format`.

  @mcp_server.tool()
  @meta_api_tool
  async def list_ad_previews(
      ad_id: str,
      meta_access_token: Optional[str] = None,
      ad_format: Optional[str] = None,
      locale: Optional[str] = None,
      render_type: Optional[str] = None,
      width: Optional[int] = None,
      height: Optional[int] = None,
  ) -> str:
      if not ad_id:
          return _json({"error": "No ad ID provided"})
  
      params: Dict[str, Any] = {}
      if ad_format:
          params["ad_format"] = ad_format
      if locale:
          params["locale"] = locale
      if render_type:
          params["render_type"] = render_type
      if width is not None:
          params["width"] = width
      if height is not None:
          params["height"] = height
  
      payload = await make_api_request(f"{ad_id}/previews", meta_access_token, params)
  
      if not ad_format and _preview_requires_ad_format(payload):
          attempted_formats: List[str] = []
          for fallback_format in _PREVIEW_FALLBACK_AD_FORMATS:
              attempted_formats.append(fallback_format)
              fallback_params = dict(params)
              fallback_params["ad_format"] = fallback_format
              fallback_payload = await make_api_request(f"{ad_id}/previews", meta_access_token, fallback_params)
              if not (isinstance(fallback_payload, dict) and fallback_payload.get("error")):
                  if isinstance(fallback_payload, dict):
                      fallback_payload.setdefault("request_context", {})
                      if isinstance(fallback_payload["request_context"], dict):
                          fallback_payload["request_context"]["ad_format"] = fallback_format
                          fallback_payload["request_context"]["auto_selected"] = True
                  return _json(fallback_payload)
  
          if isinstance(payload.get("error"), dict):
              payload["error"]["attempted_ad_formats"] = attempted_formats
  
      return _json(payload)