list_campaigns

Instructions

Implementation Reference

• src/tools/campaigns.ts:73-93 (handler)

  The async handler function that executes the list_campaigns tool logic: parses args (status, limit, offset), builds the API path, calls client.getPaginated<Campaign[]> on '/campaigns', validates response data with CampaignOutputSchema, and returns the result as formatted JSON.

    async (args) => {
      const { status, limit, offset } = ListCampaignsInputSchema.parse(args);
  
      let path = "/campaigns";
      if (status !== undefined) {
        path += `?status=${status}`;
      }
  
      const response = await client.getPaginated<Campaign[]>(path, { limit, offset });
      const campaigns = Array.isArray(response.data) ? response.data : [];
  
      const result = {
        pagination: response.pagination,
        campaigns: campaigns.map((c) => CampaignOutputSchema.parse(c)),
      };
  
      return {
        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
      };
    }
  );

• src/tools/campaigns.ts:49-94 (registration)

  The registerCampaignsTools function registers the list_campaigns tool on the MCP server with its name, description, input schema (status, limit, offset), and the async handler.

  /** Registers the list_campaigns tool. */
  export function registerCampaignsTools(server: McpServer, client: AsaClient): void {
    server.tool(
      "list_campaigns",
      "List all campaigns in the configured Apple Search Ads organization. Requires ASA authentication; read-only. Returns campaign metadata (id, name, status, budget, country, channel type) but not performance metrics — use get_campaign_report for metrics. Optionally filter by status. Supports pagination via limit/offset; default limit 20, max 1000.",
      {
        status: z
          .enum(["ENABLED", "PAUSED", "DELETED"])
          .optional()
          .describe("Filter results to campaigns with this status. Omit to return all statuses."),
        limit: z
          .number()
          .int()
          .min(1)
          .max(1000)
          .optional()
          .describe("Max campaigns 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 { status, limit, offset } = ListCampaignsInputSchema.parse(args);
  
        let path = "/campaigns";
        if (status !== undefined) {
          path += `?status=${status}`;
        }
  
        const response = await client.getPaginated<Campaign[]>(path, { limit, offset });
        const campaigns = Array.isArray(response.data) ? response.data : [];
  
        const result = {
          pagination: response.pagination,
          campaigns: campaigns.map((c) => CampaignOutputSchema.parse(c)),
        };
  
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
        };
      }
    );
  }

• src/tools/campaigns.ts:27-44 (schema)

  CampaignOutputSchema defines the shape of each campaign returned by list_campaigns (id, orgId, name, status, budget, etc.), used to parse/validate API response data.

  export const CampaignOutputSchema = z.object({
    id: z.number(),
    orgId: z.number(),
    name: z.string(),
    status: z.enum(["ENABLED", "PAUSED", "DELETED"]),
    servingStatus: z.string().nullable(),
    adamId: z.number(),
    budgetAmount: MoneySchema,
    dailyBudgetAmount: MoneySchema.optional(),
    countriesOrRegions: z.array(z.string()),
    supplySources: z.array(z.string()),
    adChannelType: z.string(),
    billingEvent: z.string(),
    startTime: z.string(),
    endTime: z.string().nullable().optional(),
    creationTime: z.string(),
    modificationTime: z.string(),
  });

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

  ListCampaignsInputSchema defines and validates the input parameters for list_campaigns: optional status filter (ENABLED/PAUSED/DELETED), limit (1-1000, default 20), and offset (min 0, default 0).

  export const ListCampaignsInputSchema = z.object({
    status: z.enum(["ENABLED", "PAUSED", "DELETED"]).optional().describe("Filter by campaign status"),
    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/asa/client.ts:28-36 (helper)

  The getPaginated helper method used by list_campaigns to make a GET request with offset-based pagination query parameters (limit/offset) appended to the API path.

  async getPaginated<T>(
    path: string,
    pagination: PaginationParams = {}
  ): Promise<AsaApiResponse<T>> {
    const limit = pagination.limit ?? 20;
    const offset = pagination.offset ?? 0;
    const separator = path.includes("?") ? "&" : "?";
    return this.request<T>("GET", `${path}${separator}limit=${limit}&offset=${offset}`);
  }