ArmaVita Meta Ads MCP

Instructions

Implementation Reference

• src/armavita_meta_ads_mcp/core/report_tools.py:222-290 (handler)

  The main handler function for the 'create_report' tool, which validates input parameters and initializes the report generation process.

  async def create_report(
      ad_account_id: str,
      meta_access_token: Optional[str] = None,
      report_type: str = "account",
      date_range: Union[str, Dict[str, str]] = "last_30d",
      campaign_ids: Optional[List[str]] = None,
      export_format: str = "pdf",
      report_name: Optional[str] = None,
      include_sections: Optional[List[str]] = None,
      breakdowns: Optional[List[str]] = None,
      action_breakdowns: Optional[List[str]] = None,
      summary_action_breakdowns: Optional[List[str]] = None,
      comparison_period: Optional[Union[str, Dict[str, str]]] = None,
  ) -> str:
      """Generate OSS-local performance reports for Meta Ads accounts/campaigns."""
      if not ad_account_id:
          return {
              "error": "invalid_parameters",
              "message": "ad_account_id is required",
              "details": {"required_parameter": "ad_account_id", "format": "act_XXXXXXXXX"},
          }
  
      normalized_type = str(report_type).strip().lower()
      normalized_export = str(export_format).strip().lower()
  
      if normalized_type not in {"account", "campaign", "comparison"}:
          return {
              "error": "invalid_parameters",
              "message": "report_type must be one of: account, campaign, comparison",
              "report_type": report_type,
          }
  
      if normalized_export not in {"json", "html", "pdf"}:
          return {
              "error": "invalid_parameters",
              "message": "export_format must be one of: json, html, pdf",
              "export_format": export_format,
          }
  
      if normalized_type in {"campaign", "comparison"} and not campaign_ids:
          return {
              "error": "invalid_parameters",
              "message": f"campaign_ids are required for {normalized_type} reports",
              "details": {"required_parameter": "campaign_ids"},
          }
  
      sections_requested = set(include_sections or [])
      if not sections_requested:
          sections_requested = {"summary", "kpis", "actions", "comparison"}
  
      generated_at = datetime.datetime.utcnow().replace(microsecond=0).isoformat() + "Z"
      report: Dict[str, Any] = {
          "success": True,
          "report_name": report_name or f"Meta Ads {normalized_type.title()} Report",
          "report_type": normalized_type,
          "generated_at": generated_at,
          "date_range": date_range,
          "breakdowns": breakdowns or [],
          "action_breakdowns": action_breakdowns or [],
          "summary_action_breakdowns": summary_action_breakdowns or [],
          "sections": {},
      }
  
      base_time_params, time_error, time_warnings = _resolve_time_params(date_range)
      if time_error:
          return {
              "error": "invalid_parameters",
              "message": time_error.get("message", "Invalid date range"),
              "details": time_error,