list_adgroups

Instructions

Implementation Reference

• src/kakao_moment_mcp/tools/adgroups.py:10-89 (handler)

  Core handler function `list_adgroups` that calls the Kakao Momentum API at /openapi/v4/adGroups, optionally fetches per-group details (bid, budget, schedule), merges results, computes summary stats, and returns items with count and summary text.

  async def list_adgroups(
      client: KakaoMomentClient,
      campaign_id: str | None = None,
      *,
      with_details: bool = True,
  ) -> dict[str, Any]:
      """광고그룹 목록.
  
      Args:
          campaign_id: 특정 캠페인의 광고그룹만 필터. 카카오모먼트는 campaign_id 가
                       없으면 KakaoMomentException(-813) 을 던지므로 필수에 가깝습니다.
          with_details: True 면 광고그룹별 detail 을 동시 호출해 일예산/입찰가/기간 보강.
      """
      if not campaign_id:
          raise ValueError(
              "list_adgroups 는 campaign_id 가 필요합니다. "
              "list_campaigns 로 ID 를 먼저 얻어 전달하세요."
          )
      params: dict[str, Any] = {"campaignId": campaign_id}
      data = await client.get("/openapi/v4/adGroups", params=params)
      rows = extract_rows(data)
  
      details: dict[Any, dict[str, Any]] = {}
      if with_details and rows:
          details = await fetch_details(
              client,
              "/openapi/v4/adGroups/{id}",
              [r.get("id") for r in rows],
          )
  
      items: list[dict[str, Any]] = []
      for r in rows:
          merged = {**r, **details.get(r.get("id"), {})}
          schedule = merged.get("schedule")
          begin_date = (
              schedule.get("beginDate") if isinstance(schedule, dict) else None
          )
          end_date = schedule.get("endDate") if isinstance(schedule, dict) else None
          items.append(
              {
                  "id": merged.get("id"),
                  "name": merged.get("name"),
                  "campaign_id": (
                      merged.get("campaign", {}).get("id")
                      if isinstance(merged.get("campaign"), dict)
                      else merged.get("campaignId")
                  )
                  or campaign_id,
                  "status": merged.get("config") or merged.get("status"),
                  "daily_budget": merged.get("dailyBudgetAmount")
                  or merged.get("dailyBudget"),
                  "bid_amount": merged.get("bidAmount"),
                  "bid_strategy": merged.get("bidStrategy"),
                  "pricing_type": merged.get("pricingType"),
                  "pacing": merged.get("pacing"),
                  "begin_date": begin_date,
                  "end_date": end_date,
                  "creative_count": merged.get("creativeCount"),
                  "status_description": merged.get("statusDescription"),
                  "created_at": merged.get("createdDate"),
              }
          )
  
      on_count = sum(1 for it in items if str(it.get("status", "")).upper() == "ON")
      off_count = sum(
          1 for it in items if str(it.get("status", "")).upper() in ("OFF", "PAUSED")
      )
      total_budget = sum(
          float(it.get("daily_budget") or 0) for it in items if it.get("daily_budget")
      )
      summary = (
          f"광고그룹 {len(items)}개 (진행 {on_count} · 일시정지 {off_count})"
          f" · 일예산 합계 {int(total_budget):,}원"
      )
      return {
          "count": len(items),
          "items": items,
          "summary": summary,
          "raw": data,
      }

• src/kakao_moment_mcp/tools/adgroups.py:7-7 (helper)

  Imports `extract_rows` and `fetch_details` helpers from `._common` which are used by `list_adgroups` to parse API responses and fetch per-group details.

  from ._common import extract_rows, fetch_details