list_ad_groups

Instructions

Implementation Reference

• src/tools/ad-groups.ts:46-89 (registration)

  Registers the 'list_ad_groups' tool on the MCP server via server.tool('list_ad_groups', ...). Also defines the handler function that executes the tool logic.

  export function registerAdGroupsTools(server: McpServer, client: AsaClient): void {
    server.tool(
      "list_ad_groups",
      "List ad groups within a specific Apple Search Ads campaign. Requires ASA authentication; read-only. Returns ad group metadata (id, name, status, default bid, automated keyword opt-in) but not performance metrics — use get_ad_group_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.",
      {
        campaignId: z
          .number()
          .int()
          .positive()
          .describe("ID of the campaign whose ad groups to list. Obtain from list_campaigns."),
        limit: z
          .number()
          .int()
          .min(1)
          .max(1000)
          .optional()
          .describe("Max ad groups to return (1–1000). Defaults to 20."),
        offset: z
          .number()
          .int()
          .min(0)
          .optional()
          .describe("Zero-based page offset for pagination. Defaults to 0."),
      },
      async (args) => {
        const { campaignId, limit, offset } = ListAdGroupsInputSchema.parse(args);
  
        const response = await client.getPaginated<AdGroup[]>(`/campaigns/${campaignId}/adgroups`, {
          limit,
          offset,
        });
        const adGroups = Array.isArray(response.data) ? response.data : [];
  
        const result = {
          pagination: response.pagination,
          adGroups: adGroups.map((ag) => AdGroupOutputSchema.parse(ag)),
        };
  
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
        };
      }
    );
  }

• src/tools/ad-groups.ts:70-87 (handler)

  The async handler for 'list_ad_groups': parses input via ListAdGroupsInputSchema, calls client.getPaginated on /campaigns/{campaignId}/adgroups, validates each ad group with AdGroupOutputSchema, and returns paginated results as JSON.

  async (args) => {
    const { campaignId, limit, offset } = ListAdGroupsInputSchema.parse(args);
  
    const response = await client.getPaginated<AdGroup[]>(`/campaigns/${campaignId}/adgroups`, {
      limit,
      offset,
    });
    const adGroups = Array.isArray(response.data) ? response.data : [];
  
    const result = {
      pagination: response.pagination,
      adGroups: adGroups.map((ag) => AdGroupOutputSchema.parse(ag)),
    };
  
    return {
      content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
    };
  }

• src/tools/ad-groups.ts:6-23 (schema)

  ListAdGroupsInputSchema: validates input with Zod (campaignId required, limit default 20/max 1000, offset default 0).

  export const ListAdGroupsInputSchema = z.object({
    campaignId: z.number().int().positive().describe("Campaign ID to list ad groups for"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(1000)
      .optional()
      .default(20)
      .describe("Max results to return (1–1000)"),
    offset: z
      .number()
      .int()
      .min(0)
      .optional()
      .default(0)
      .describe("Zero-based offset for pagination"),
  });

• src/tools/ad-groups.ts:27-40 (schema)

  AdGroupOutputSchema: defines the shape of each returned ad group (id, campaignId, name, status, servingStatus, defaultBidAmount, etc.).

  export const AdGroupOutputSchema = z.object({
    id: z.number(),
    campaignId: z.number(),
    orgId: z.number(),
    name: z.string(),
    status: z.enum(["ENABLED", "PAUSED", "DELETED"]),
    servingStatus: z.string().nullable(),
    defaultBidAmount: MoneySchema,
    automatedKeywordsOptIn: z.boolean(),
    startTime: z.string(),
    endTime: z.string().nullable().optional(),
    creationTime: z.string(),
    modificationTime: z.string(),
  });

• src/server.ts:26-26 (registration)

  Calls registerAdGroupsTools(server, client) to wire the tool into the MCP server during initialization.

  registerAdGroupsTools(server, client);