list_rf_predictions

Instructions

Implementation Reference

• src/tools/reach_frequency.ts:7-27 (handler)

  Handler function for 'list_rf_predictions' tool. Calls client.get() to fetch reachfrequencypredictions from the Meta Ads API with optional fields, limit, and pagination cursor. Returns paginated results or error.

  server.tool(
    "list_rf_predictions",
    "List reach & frequency predictions for the ad account. Returns paginated results.",
    {
      fields: z.string().optional().describe("Comma-separated fields to return"),
      limit: z.number().optional().default(25).describe("Number of results (default 25)"),
      after: z.string().optional().describe("Pagination cursor for next page"),
    },
    async ({ fields, limit, after }) => {
      try {
        const params: Record<string, unknown> = {};
        if (fields) params.fields = fields;
        if (limit) params.limit = limit;
        if (after) params.after = after;
        const { data, rateLimit } = await client.get(`${client.accountPath}/reachfrequencypredictions`, params);
        return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/tools/reach_frequency.ts:10-14 (schema)

  Input schema for 'list_rf_predictions': optional 'fields' (comma-separated string), optional 'limit' (number, default 25), optional 'after' (pagination cursor string). Defined using Zod.

  {
    fields: z.string().optional().describe("Comma-separated fields to return"),
    limit: z.number().optional().default(25).describe("Number of results (default 25)"),
    after: z.string().optional().describe("Pagination cursor for next page"),
  },

• src/tools/reach_frequency.ts:5-95 (registration)

  The function registerReachFrequencyTools registers all RF tools on an McpServer instance including 'list_rf_predictions' via server.tool().

  export function registerReachFrequencyTools(server: McpServer, client: AdsClient): void {
    // ─── list_rf_predictions ──────────────────────────────────────
    server.tool(
      "list_rf_predictions",
      "List reach & frequency predictions for the ad account. Returns paginated results.",
      {
        fields: z.string().optional().describe("Comma-separated fields to return"),
        limit: z.number().optional().default(25).describe("Number of results (default 25)"),
        after: z.string().optional().describe("Pagination cursor for next page"),
      },
      async ({ fields, limit, after }) => {
        try {
          const params: Record<string, unknown> = {};
          if (fields) params.fields = fields;
          if (limit) params.limit = limit;
          if (after) params.after = after;
          const { data, rateLimit } = await client.get(`${client.accountPath}/reachfrequencypredictions`, params);
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── create_rf_prediction ─────────────────────────────────────
    server.tool(
      "create_rf_prediction",
      "Create a new reach & frequency prediction. Provide targeting spec as JSON string, budget in cents, and scheduling info.",
      {
        target_spec: z.string().describe("JSON string of targeting specification"),
        start_time: z.string().describe("Prediction start time (ISO 8601 or Unix timestamp)"),
        stop_time: z.string().describe("Prediction stop time (ISO 8601 or Unix timestamp)"),
        budget: z.number().describe("Budget in account currency cents"),
        frequency_cap: z.number().describe("Maximum frequency cap per user"),
        destination_id: z.string().describe("Destination ID (e.g. Facebook Page ID)"),
      },
      async ({ target_spec, start_time, stop_time, budget, frequency_cap, destination_id }) => {
        try {
          const params: Record<string, unknown> = {
            target_spec,
            start_time,
            stop_time,
            budget,
            frequency_cap,
            destination_id,
          };
          const { data, rateLimit } = await client.post(`${client.accountPath}/reachfrequencypredictions`, params);
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── get_rf_prediction ────────────────────────────────────────
    server.tool(
      "get_rf_prediction",
      "Get details of a specific reach & frequency prediction by ID.",
      {
        prediction_id: z.string().describe("Prediction ID"),
        fields: z.string().optional().describe("Comma-separated fields to return"),
      },
      async ({ prediction_id, fields }) => {
        try {
          const params: Record<string, unknown> = {};
          if (fields) params.fields = fields;
          const { data, rateLimit } = await client.get(`/${prediction_id}`, params);
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── delete_rf_prediction ─────────────────────────────────────
    server.tool(
      "delete_rf_prediction",
      "Delete a reach & frequency prediction. This action is irreversible.",
      {
        prediction_id: z.string().describe("Prediction ID to delete"),
      },
      async ({ prediction_id }) => {
        try {
          const { data, rateLimit } = await client.delete(`/${prediction_id}`);
          return { content: [{ type: "text" as const, text: JSON.stringify({ success: true, ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  }

• src/index.ts:27-27 (registration)

  Import of the registerReachFrequencyTools function in the main entry point.

  import { registerReachFrequencyTools } from "./tools/reach_frequency.js";

• src/index.ts:83-83 (registration)

  Registration call: registerReachFrequencyTools(server, client) in the main server setup.

  registerReachFrequencyTools(server, client);