ArmaVita Meta Ads MCP

Instructions

Implementation Reference

• src/armavita_meta_ads_mcp/core/insight_tools.py:93-150 (handler)

  The list_insights function serves as the primary handler for fetching insights from Meta Ads. It validates parameters, normalizes time and breakdown inputs, performs the API request, and formats the response.

  async def list_insights(
      object_id: str,
      meta_access_token: Optional[str] = None,
      date_range: Union[str, Dict[str, str]] = "maximum",
      breakdown: str = "",
      breakdowns: Optional[List[str]] = None,
      action_breakdowns: Optional[List[str]] = None,
      summary_action_breakdowns: Optional[List[str]] = None,
      level: str = "ad",
      page_size: int = 25,
      page_cursor: str = "",
      action_attribution_windows: Optional[List[str]] = None,
      compact: bool = False,
  ) -> str:
      """Fetch insights for an account, campaign, ad set, or ad."""
      if not str(object_id or "").strip():
          return json.dumps({"error": "No object ID provided"}, indent=2)
  
      params: Dict[str, Any] = {
          "fields": _DEFAULT_FIELDS,
          "level": level,
          "page_size": int(page_size),
      }
  
      time_params, time_error, normalization_warnings = normalize_time_input(date_range, default_preset="maximum")
      if time_error:
          return json.dumps(time_error, indent=2)
      params.update(time_params or {})
  
      breakdown_params, breakdown_warnings = normalize_breakdown_inputs(
          breakdown=breakdown,
          breakdowns=breakdowns,
          action_breakdowns=action_breakdowns,
          summary_action_breakdowns=summary_action_breakdowns,
      )
      params.update(breakdown_params)
      normalization_warnings.extend(breakdown_warnings)
  
      if page_cursor:
          params["page_cursor"] = page_cursor
  
      deprecated_windows = _deprecated_windows(action_attribution_windows)
      if action_attribution_windows:
          params["action_attribution_windows"] = list(action_attribution_windows)
  
      payload = await make_api_request(f"{object_id}/insights", meta_access_token, params)
  
      if isinstance(payload, dict):
          _append_warnings(payload, normalization_warnings)
          _with_warning(payload, deprecated_windows)
  
          if compact and isinstance(payload.get("data"), list):
              payload["data"] = [
                  _strip_redundant_actions(row) if isinstance(row, dict) else row
                  for row in payload["data"]
              ]
  
      return json.dumps(payload, indent=2)