li_get_audience_insights

Instructions

Implementation Reference

• src/index.ts:162-169 (registration)

  Registration of the 'li_get_audience_insights' tool on the MCP server, wiring the schema and handler.

  // ─── Audiences ───────────────────────────────────────────────────────────────
  
  server.tool(
    "li_get_audience_insights",
    "List DMP (Data Management Platform) segments attached to a LinkedIn ad account. Segments represent matched audiences (USER type: contact list uploads, website retargeting, lookalike audiences) and company lists (COMPANY type: for account-based marketing). Returns segment name, type, source, estimated size (where LinkedIn reports it), and status. Use to audit available audiences before building campaigns, or to confirm a matched audience uploaded successfully and has enough members to serve ads.",
    getAudienceInsightsSchema,
    async (args) => { try { return ok(await getAudienceInsights(args)); } catch (e) { return err(e); } }
  );

• src/tools/audiences.ts:8-18 (schema)

  Zod input schema for 'li_get_audience_insights': accepts optional ad_account_id, type filter (USER/COMPANY/COMBINED), and page_size (default 50).

  export const getAudienceInsightsSchema = {
    ad_account_id: z.string().optional(),
    type: z
      .enum(SEGMENT_TYPES)
      .optional()
      .describe(
        "Filter segment type: USER (contact list / matched audience), " +
        "COMPANY (company list for ABM), COMBINED (combined / lookalike segment)."
      ),
    page_size: z.number().int().min(1).max(100).default(50),
  };

• src/tools/audiences.ts:20-35 (handler)

  Handler function 'getAudienceInsights' that resolves the ad account, builds query params, and calls liGet('/dmpSegments', params) to fetch DMP segments from LinkedIn.

  export async function getAudienceInsights(args: {
    ad_account_id?: string;
    type?: string;
    page_size?: number;
  }) {
    const account = resolveAdAccount(args.ad_account_id);
    const params: Record<string, string | number> = {
      q: "account",
      account,
      count: args.page_size ?? 50,
    };
    if (args.type) {
      params["type"] = args.type;
    }
    return liGet("/dmpSegments", params);
  }

• src/client.ts:85-93 (helper)

  Helper 'resolveAdAccount' used by the handler to resolve ad account ID to a full LinkedIn URN, falling back to LINKEDIN_DEFAULT_AD_ACCOUNT env var.

  export function resolveAdAccount(override?: string): string {
    const v = (override ?? process.env.LINKEDIN_DEFAULT_AD_ACCOUNT ?? "").trim();
    if (!v) {
      throw new LinkedInError(
        "No ad account provided. Pass ad_account_id or set LINKEDIN_DEFAULT_AD_ACCOUNT in .env."
      );
    }
    return urn("sponsoredAccount", v);
  }

• src/client.ts:39-50 (helper)

  Helper 'liGet' making authenticated GET requests to LinkedIn REST API, used to call /dmpSegments endpoint.

  export async function liGet<T = unknown>(
    path: string,
    query?: Record<string, string | number | boolean | undefined>
  ): Promise<T> {
    const url = new URL(BASE_URL + path);
    if (query) {
      for (const [k, v] of Object.entries(query)) {
        if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
      }
    }
    return liFetch<T>("GET", url.toString());
  }