ArmaVita Meta Ads MCP

Instructions

Implementation Reference

• src/armavita_meta_ads_mcp/core/account_tools.py:127-184 (handler)

  The implementation of the read_ad_account tool, which fetches metadata for a specific Meta Ad Account and includes normalization and error handling.

  async def read_ad_account(ad_account_id: str, meta_access_token: Optional[str] = None) -> str:
      """Return account metadata for a single ad account."""
      normalized_account_id = _normalize_account_id(ad_account_id)
      if not normalized_account_id:
          return json.dumps(
              {
                  "error": {
                      "message": "Account ID is required",
                      "details": "Please specify an ad_account_id parameter",
                      "example": "Use ad_account_id='act_123456789' or ad_account_id='123456789'",
                  }
              },
              indent=2,
          )
  
      payload = await make_api_request(
          normalized_account_id,
          meta_access_token,
          {
              "fields": (
                  "id,name,account_id,account_status,amount_spent,balance,currency,age,"
                  "business_city,business_country_code,timezone_name"
              )
          },
      )
  
      if isinstance(payload, dict) and payload.get("error") and _looks_like_access_error(payload):
          accounts_payload = await _list_accessible_accounts(meta_access_token)
          if isinstance(accounts_payload, dict) and isinstance(accounts_payload.get("data"), list):
              visible = [
                  {"id": item.get("id"), "name": item.get("name")}
                  for item in accounts_payload["data"]
                  if isinstance(item, dict)
              ]
              return json.dumps(
                  {
                      "error": {
                          "message": f"Account {normalized_account_id} is not accessible to your user account",
                          "details": "This account either doesn't exist or you don't have permission to access it",
                          "accessible_accounts": visible[:10],
                          "total_accessible_accounts": len(visible),
                          "suggestion": "Try using one of the accessible account IDs listed above",
                      }
                  },
                  indent=2,
              )
  
      if isinstance(payload, dict) and not payload.get("error"):
          _normalize_money_fields(payload)
          country = str(payload.get("business_country_code", "")).upper()
          payload["dsa_required"] = country in _EU_DSA_COUNTRIES
          payload["dsa_compliance_note"] = (
              "This account is subject to European DSA (Digital Services Act) requirements"
              if payload["dsa_required"]
              else "This account is not subject to European DSA requirements"
          )
  
      return json.dumps(payload, indent=2)