search_ads_library

Instructions

Implementation Reference

• src/tools/adslibrary.ts:58-75 (handler)

  The handler function for the search_ads_library tool. Validates that at least one of search_terms or search_page_ids is provided, then calls metaGet('/ads_archive', ...) to query Meta's public Ad Library.

  handler: async (args) => {
    if (!args.search_terms && !args.search_page_ids) {
      throw new Error(
        "search_ads_library requires either `search_terms` or `search_page_ids`.",
      );
    }
    return metaGet("/ads_archive", {
      search_terms: args.search_terms,
      search_page_ids: args.search_page_ids,
      ad_reached_countries: args.ad_reached_countries ?? ["US"],
      ad_type: args.ad_type ?? "ALL",
      ad_active_status: args.ad_active_status ?? "ACTIVE",
      publisher_platforms: args.publisher_platforms,
      limit: args.limit ?? 50,
      after: args.after,
      fields: args.fields ?? DEFAULT_AD_ARCHIVE_FIELDS,
    });
  },

• src/tools/adslibrary.ts:24-57 (schema)

  Input schema for search_ads_library using Zod definitions for search_terms, search_page_ids, ad_reached_countries, ad_type, ad_active_status, publisher_platforms, limit, after, and fields.

  inputSchema: {
    search_terms: z
      .string()
      .optional()
      .describe("Keywords to search ad text/creative"),
    search_page_ids: z
      .array(z.string())
      .optional()
      .describe("Specific Facebook Page IDs to look at"),
    ad_reached_countries: z
      .array(z.string().length(2))
      .optional()
      .describe("ISO-2 country codes. Default ['US']"),
    ad_type: z
      .enum([
        "ALL",
        "POLITICAL_AND_ISSUE_ADS",
        "HOUSING_ADS",
        "EMPLOYMENT_ADS",
        "CREDIT_ADS",
      ])
      .optional()
      .describe("Default ALL"),
    ad_active_status: z
      .enum(["ALL", "ACTIVE", "INACTIVE"])
      .optional()
      .describe("Default ACTIVE"),
    publisher_platforms: z
      .array(z.enum(["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER"]))
      .optional(),
    limit: z.number().int().positive().max(500).optional(),
    after: z.string().optional(),
    fields: z.string().optional().describe("Override default field list"),
  },

• src/tools/adslibrary.ts:14-77 (registration)

  The full ToolDef array export 'adsLibraryTools' containing the search_ads_library tool definition with name, description, inputSchema, and handler.

  export const adsLibraryTools: ToolDef[] = [
    {
      name: "search_ads_library",
      description:
        "Search Meta's public Ad Library for competitive research. Returns active and inactive " +
        "ads matching `search_terms` OR `search_page_ids` in the selected countries. Default " +
        "country = ['US']. Returns ad_snapshot_url (preview), creative bodies/titles, page_id, " +
        "delivery times, publisher_platforms.\n\n" +
        "Note: only ads in categories subject to public transparency (political / housing / " +
        "employment / credit) return full metadata; other categories return lighter data.",
      inputSchema: {
        search_terms: z
          .string()
          .optional()
          .describe("Keywords to search ad text/creative"),
        search_page_ids: z
          .array(z.string())
          .optional()
          .describe("Specific Facebook Page IDs to look at"),
        ad_reached_countries: z
          .array(z.string().length(2))
          .optional()
          .describe("ISO-2 country codes. Default ['US']"),
        ad_type: z
          .enum([
            "ALL",
            "POLITICAL_AND_ISSUE_ADS",
            "HOUSING_ADS",
            "EMPLOYMENT_ADS",
            "CREDIT_ADS",
          ])
          .optional()
          .describe("Default ALL"),
        ad_active_status: z
          .enum(["ALL", "ACTIVE", "INACTIVE"])
          .optional()
          .describe("Default ACTIVE"),
        publisher_platforms: z
          .array(z.enum(["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER"]))
          .optional(),
        limit: z.number().int().positive().max(500).optional(),
        after: z.string().optional(),
        fields: z.string().optional().describe("Override default field list"),
      },
      handler: async (args) => {
        if (!args.search_terms && !args.search_page_ids) {
          throw new Error(
            "search_ads_library requires either `search_terms` or `search_page_ids`.",
          );
        }
        return metaGet("/ads_archive", {
          search_terms: args.search_terms,
          search_page_ids: args.search_page_ids,
          ad_reached_countries: args.ad_reached_countries ?? ["US"],
          ad_type: args.ad_type ?? "ALL",
          ad_active_status: args.ad_active_status ?? "ACTIVE",
          publisher_platforms: args.publisher_platforms,
          limit: args.limit ?? 50,
          after: args.after,
          fields: args.fields ?? DEFAULT_AD_ARCHIVE_FIELDS,
        });
      },
    },
  ];

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

  Import of adsLibraryTools from adslibrary.ts in the stdio entrypoint.

  import { adsLibraryTools } from "./tools/adslibrary.js";

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

  adsLibraryTools spread into allTools array for registration with McpServer in stdio mode.

  ...adsLibraryTools,

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

  Import of adsLibraryTools from adslibrary.ts in the HTTP entrypoint.

  import { adsLibraryTools } from "./tools/adslibrary.js";

• src/http.ts:40-40 (registration)

  adsLibraryTools spread into allTools array for registration with McpServer in HTTP mode.

  ...adsLibraryTools,

• src/client.ts:144-160 (helper)

  The metaGet helper function used by the handler to make GET requests to the Meta Graph API.

  export async function metaGet<T = unknown>(
    path: string,
    params: Record<string, unknown> = {},
  ): Promise<T> {
    const qs = buildQuery(params);
    qs.append("access_token", getCurrentToken());
    const url = `${META_API_BASE}${normalizePath(path)}?${qs.toString()}`;
  
    const res = await fetch(url, { method: "GET" });
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      throw new Error(enhanceMetaError(res.status, text));
    }
    const raw = await res.text();
    if (!raw) return {} as T;
    return JSON.parse(raw) as T;
  }

• src/client.ts:17-17 (helper)

  The META_API_BASE constant pointing to https://graph.facebook.com/v24.0 used for the /ads_archive endpoint.

  export const META_API_BASE = "https://graph.facebook.com/v24.0";

• src/client.ts:26-38 (helper)

  The getCurrentToken function that resolves the Meta access token for API calls.

  function getCurrentToken(): string {
    const sessionToken = getMetaToken();
    if (sessionToken) return sessionToken;
    const envToken = process.env.META_ACCESS_TOKEN;
    if (envToken) return envToken;
    throw new Error(
      "META_ACCESS_TOKEN missing. Stdio mode: set the env var. HTTP mode: pass " +
        "the token via ?config=<base64(JSON)> query or Authorization: Bearer. " +
        "Get a token at https://developers.facebook.com/tools/explorer/ (2h) or " +
        "via Business Manager System User (never expires): " +
        "https://github.com/Mike25app/scaleforge-mcp-meta-ads#stable-tokens",
    );
  }

• src/helpers/session.ts:21-23 (helper)

  The getMetaToken helper that retrieves the per-request token from AsyncLocalStorage.

  export function getMetaToken(): string | undefined {
    return tokenStorage.getStore()?.token;
  }