create_lead_form

Instructions

Implementation Reference

• src/tools/leads.ts:64-91 (handler)

  The handler function for the create_lead_form tool. It calls the Facebook Graph API POST /{page_id}/leadgen_forms with the provided parameters (name, questions, privacy_policy, follow_up_action_url, thank_you_page) to create a new lead generation form.

  // ─── create_lead_form ───────────────────────────────────────
  server.tool(
    "create_lead_form",
    "Create a new lead generation form on a Facebook Page. Requires pages_manage_ads permission.",
    {
      page_id: z.string().describe("Facebook Page ID"),
      name: z.string().describe("Lead form name"),
      questions: z.string().describe("JSON array of questions. Each: {key: string, type: 'CUSTOM'|'EMAIL'|'PHONE'|'FULL_NAME'|'CITY'|'STATE'|'COUNTRY'|'ZIP'|'JOB_TITLE'|'COMPANY_NAME', label?: string}"),
      privacy_policy_url: z.string().describe("URL to privacy policy"),
      follow_up_action_url: z.string().optional().describe("URL to redirect after submission"),
      thank_you_page: z.string().optional().describe("JSON object: {title: string, body: string, button_text?: string, button_type?: 'VIEW_WEBSITE'|'DOWNLOAD'}"),
    },
    async ({ page_id, name, questions, privacy_policy_url, follow_up_action_url, thank_you_page }) => {
      try {
        const params: Record<string, unknown> = {
          name,
          questions,
          privacy_policy: JSON.stringify({ url: privacy_policy_url }),
        };
        if (follow_up_action_url) params.follow_up_action_url = follow_up_action_url;
        if (thank_you_page) params.thank_you_page = thank_you_page;
        const { data, rateLimit } = await client.post(`/${page_id}/leadgen_forms`, 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/leads.ts:68-75 (schema)

  Zod input schema for create_lead_form. Defines required fields: page_id, name, questions (JSON array), privacy_policy_url, and optional fields: follow_up_action_url, thank_you_page.

  {
    page_id: z.string().describe("Facebook Page ID"),
    name: z.string().describe("Lead form name"),
    questions: z.string().describe("JSON array of questions. Each: {key: string, type: 'CUSTOM'|'EMAIL'|'PHONE'|'FULL_NAME'|'CITY'|'STATE'|'COUNTRY'|'ZIP'|'JOB_TITLE'|'COMPANY_NAME', label?: string}"),
    privacy_policy_url: z.string().describe("URL to privacy policy"),
    follow_up_action_url: z.string().optional().describe("URL to redirect after submission"),
    thank_you_page: z.string().optional().describe("JSON object: {title: string, body: string, button_text?: string, button_type?: 'VIEW_WEBSITE'|'DOWNLOAD'}"),
  },

• src/tools/leads.ts:5-68 (registration)

  The registerLeadTools function in src/tools/leads.ts registers the create_lead_form tool via server.tool().

  export function registerLeadTools(server: McpServer, client: AdsClient): void {
    // ─── get_form_leads ────────────────────────────────────────
    server.tool(
      "get_form_leads",
      "Get leads submitted through a lead generation form.",
      {
        form_id: z.string().describe("Lead form ID"),
        fields: z.string().optional().describe("Comma-separated fields to return"),
        limit: z.number().optional().default(25).describe("Number of results to return"),
        after: z.string().optional().describe("Pagination cursor for next page"),
      },
      async ({ form_id, ...params }) => {
        try {
          const { data, rateLimit } = await client.get(`/${form_id}/leads`, { ...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_lead ──────────────────────────────────────────────
    server.tool(
      "get_lead",
      "Get details of a specific lead by ID.",
      {
        lead_id: z.string().describe("Lead ID"),
        fields: z.string().optional().describe("Comma-separated fields to return"),
      },
      async ({ lead_id, ...params }) => {
        try {
          const { data, rateLimit } = await client.get(`/${lead_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 };
        }
      }
    );
  
    // ─── list_lead_forms ───────────────────────────────────────
    server.tool(
      "list_lead_forms",
      "List lead generation forms for a Facebook Page.",
      {
        page_id: z.string().describe("Facebook Page ID"),
        fields: z.string().optional().describe("Comma-separated fields to return"),
        limit: z.number().optional().default(25).describe("Number of results to return"),
        after: z.string().optional().describe("Pagination cursor for next page"),
      },
      async ({ page_id, ...params }) => {
        try {
          const { data, rateLimit } = await client.get(`/${page_id}/leadgen_forms`, { ...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_lead_form ───────────────────────────────────────
    server.tool(
      "create_lead_form",
      "Create a new lead generation form on a Facebook Page. Requires pages_manage_ads permission.",
      {

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

  Registration call in the main entry point: registerLeadTools(server, client) is invoked at line 68.

  registerLeadTools(server, client);