@praise25/meta-mcp-server 0.1.0

package/dist/tools/ads/get-insights.d.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    object_id: z.ZodUnion<[z.ZodString, z.ZodString]>;
+    level: z.ZodDefault<z.ZodEnum<["account", "campaign", "adset", "ad"]>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    date_preset: z.ZodDefault<z.ZodEnum<["today", "yesterday", "this_month", "last_month", "this_quarter", "maximum", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "last_week_mon_sun", "last_week_sun_sat", "last_quarter", "last_year", "this_week_mon_today", "this_week_sun_today", "this_year"]>>;
+    time_range: z.ZodOptional<z.ZodObject<{
+        since: z.ZodString;
+        until: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        since: string;
+        until: string;
+    }, {
+        since: string;
+        until: string;
+    }>>;
+    breakdowns: z.ZodOptional<z.ZodArray<z.ZodEnum<["age", "gender", "country", "region", "dma", "impression_device", "publisher_platform", "platform_position", "device_platform", "product_id", "hourly_stats_aggregated_by_advertiser_time_zone"]>, "many">>;
+    action_breakdowns: z.ZodOptional<z.ZodArray<z.ZodEnum<["action_type", "action_destination", "action_device", "action_target_id", "action_video_sound", "action_video_type", "action_reaction"]>, "many">>;
+    time_increment: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"monthly">, z.ZodLiteral<"all_days">, z.ZodNumber]>>;
+    filtering: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodString;
+        value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">]>;
+    }, "strip", z.ZodTypeAny, {
+        value: string | number | (string | number)[];
+        field: string;
+        operator: string;
+    }, {
+        value: string | number | (string | number)[];
+        field: string;
+        operator: string;
+    }>, "many">>;
+    sort: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    object_id: string;
+    level: "account" | "campaign" | "adset" | "ad";
+    date_preset: "today" | "yesterday" | "this_month" | "last_month" | "this_quarter" | "maximum" | "last_3d" | "last_7d" | "last_14d" | "last_28d" | "last_30d" | "last_90d" | "last_week_mon_sun" | "last_week_sun_sat" | "last_quarter" | "last_year" | "this_week_mon_today" | "this_week_sun_today" | "this_year";
+    sort?: string[] | undefined;
+    after?: string | undefined;
+    time_range?: {
+        since: string;
+        until: string;
+    } | undefined;
+    breakdowns?: ("age" | "gender" | "country" | "region" | "dma" | "impression_device" | "publisher_platform" | "platform_position" | "device_platform" | "product_id" | "hourly_stats_aggregated_by_advertiser_time_zone")[] | undefined;
+    action_breakdowns?: ("action_type" | "action_destination" | "action_device" | "action_target_id" | "action_video_sound" | "action_video_type" | "action_reaction")[] | undefined;
+    time_increment?: number | "monthly" | "all_days" | undefined;
+    filtering?: {
+        value: string | number | (string | number)[];
+        field: string;
+        operator: string;
+    }[] | undefined;
+}, {
+    object_id: string;
+    sort?: string[] | undefined;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    level?: "account" | "campaign" | "adset" | "ad" | undefined;
+    date_preset?: "today" | "yesterday" | "this_month" | "last_month" | "this_quarter" | "maximum" | "last_3d" | "last_7d" | "last_14d" | "last_28d" | "last_30d" | "last_90d" | "last_week_mon_sun" | "last_week_sun_sat" | "last_quarter" | "last_year" | "this_week_mon_today" | "this_week_sun_today" | "this_year" | undefined;
+    time_range?: {
+        since: string;
+        until: string;
+    } | undefined;
+    breakdowns?: ("age" | "gender" | "country" | "region" | "dma" | "impression_device" | "publisher_platform" | "platform_position" | "device_platform" | "product_id" | "hourly_stats_aggregated_by_advertiser_time_zone")[] | undefined;
+    action_breakdowns?: ("action_type" | "action_destination" | "action_device" | "action_target_id" | "action_video_sound" | "action_video_type" | "action_reaction")[] | undefined;
+    time_increment?: number | "monthly" | "all_days" | undefined;
+    filtering?: {
+        value: string | number | (string | number)[];
+        field: string;
+        operator: string;
+    }[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_get_insights";
+    readonly title: "Get Marketing API insights (the workhorse)";
+    readonly description: "Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.\n\nReturns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.\n\nTips for the AI consuming this:\n- Default date_preset is last_30d. Override via date_preset or time_range.\n- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.\n- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.\n- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.\n\nRequires 'ads_read' token scope.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        object_id: z.ZodUnion<[z.ZodString, z.ZodString]>;
+        level: z.ZodDefault<z.ZodEnum<["account", "campaign", "adset", "ad"]>>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        date_preset: z.ZodDefault<z.ZodEnum<["today", "yesterday", "this_month", "last_month", "this_quarter", "maximum", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "last_week_mon_sun", "last_week_sun_sat", "last_quarter", "last_year", "this_week_mon_today", "this_week_sun_today", "this_year"]>>;
+        time_range: z.ZodOptional<z.ZodObject<{
+            since: z.ZodString;
+            until: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            since: string;
+            until: string;
+        }, {
+            since: string;
+            until: string;
+        }>>;
+        breakdowns: z.ZodOptional<z.ZodArray<z.ZodEnum<["age", "gender", "country", "region", "dma", "impression_device", "publisher_platform", "platform_position", "device_platform", "product_id", "hourly_stats_aggregated_by_advertiser_time_zone"]>, "many">>;
+        action_breakdowns: z.ZodOptional<z.ZodArray<z.ZodEnum<["action_type", "action_destination", "action_device", "action_target_id", "action_video_sound", "action_video_type", "action_reaction"]>, "many">>;
+        time_increment: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"monthly">, z.ZodLiteral<"all_days">, z.ZodNumber]>>;
+        filtering: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            operator: z.ZodString;
+            value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">]>;
+        }, "strip", z.ZodTypeAny, {
+            value: string | number | (string | number)[];
+            field: string;
+            operator: string;
+        }, {
+            value: string | number | (string | number)[];
+            field: string;
+            operator: string;
+        }>, "many">>;
+        sort: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/ads/get-insights.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { adAccountIdSchema, datePresetSchema, metaIdSchema, paginationShape, timeRangeSchema, } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+const LEVEL = z.enum(["account", "campaign", "adset", "ad"]);
+const BREAKDOWN = z.enum([
+    "age",
+    "gender",
+    "country",
+    "region",
+    "dma",
+    "impression_device",
+    "publisher_platform",
+    "platform_position",
+    "device_platform",
+    "product_id",
+    "hourly_stats_aggregated_by_advertiser_time_zone",
+]);
+const ACTION_BREAKDOWN = z.enum([
+    "action_type",
+    "action_destination",
+    "action_device",
+    "action_target_id",
+    "action_video_sound",
+    "action_video_type",
+    "action_reaction",
+]);
+export const inputSchema = z
+    .object({
+    object_id: z
+        .union([adAccountIdSchema, metaIdSchema])
+        .describe("ID to read insights from: ad account 'act_<digits>', campaign ID, ad-set ID, or ad ID. Must match level."),
+    level: LEVEL.default("account").describe("Aggregation level. 'account' returns one row per account per breakdown combo; 'ad' returns one row per ad."),
+    fields: z
+        .array(z.string())
+        .default([
+        "date_start",
+        "date_stop",
+        "account_id",
+        "account_name",
+        "campaign_id",
+        "campaign_name",
+        "adset_id",
+        "adset_name",
+        "ad_id",
+        "ad_name",
+        "impressions",
+        "reach",
+        "frequency",
+        "clicks",
+        "unique_clicks",
+        "spend",
+        "cpc",
+        "cpm",
+        "cpp",
+        "ctr",
+        "unique_ctr",
+        "actions",
+        "action_values",
+        "cost_per_action_type",
+        "cost_per_unique_click",
+        "objective",
+        "conversions",
+        "conversion_values",
+        "video_30_sec_watched_actions",
+        "video_p25_watched_actions",
+        "video_p50_watched_actions",
+        "video_p75_watched_actions",
+        "video_p100_watched_actions",
+    ])
+        .describe("Fields per row. Start with the defaults and trim if you want a lighter payload. See https://developers.facebook.com/docs/marketing-api/insights for the full list."),
+    date_preset: datePresetSchema.default("last_30d"),
+    time_range: timeRangeSchema.optional().describe("Overrides date_preset if supplied."),
+    breakdowns: z
+        .array(BREAKDOWN)
+        .optional()
+        .describe("Demographic/placement breakdowns. Multiple breakdowns multiply row count."),
+    action_breakdowns: z
+        .array(ACTION_BREAKDOWN)
+        .optional()
+        .describe("Split action/conversion metrics by action dimension."),
+    time_increment: z
+        .union([z.literal("monthly"), z.literal("all_days"), z.number().int().min(1).max(90)])
+        .optional()
+        .describe("Bucket rows by N days, 'monthly', or 'all_days' (single row per object)."),
+    filtering: z
+        .array(z.object({
+        field: z.string(),
+        operator: z.string(),
+        value: z.union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))]),
+    }))
+        .optional()
+        .describe("Advanced filters, e.g. { field: 'spend', operator: 'GREATER_THAN', value: 100 }."),
+    sort: z
+        .array(z.string())
+        .optional()
+        .describe("e.g. ['spend_descending'] or ['impressions_ascending']."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_get_insights",
+    title: "Get Marketing API insights (the workhorse)",
+    description: `Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.
+
+Returns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.
+
+Tips for the AI consuming this:
+- Default date_preset is last_30d. Override via date_preset or time_range.
+- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.
+- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.
+- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.
+
+Requires 'ads_read' token scope.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    if (input.object_id.startsWith("act_"))
+        assertAllowed("ad_account", input.object_id, ctx.config);
+    const params = {
+        level: input.level,
+        fields: input.fields.join(","),
+        limit: input.limit,
+        after: input.after,
+    };
+    if (input.time_range) {
+        params["time_range"] = JSON.stringify(input.time_range);
+    }
+    else {
+        params["date_preset"] = input.date_preset;
+    }
+    if (input.breakdowns?.length)
+        params["breakdowns"] = input.breakdowns.join(",");
+    if (input.action_breakdowns?.length)
+        params["action_breakdowns"] = input.action_breakdowns.join(",");
+    if (input.time_increment !== undefined)
+        params["time_increment"] = String(input.time_increment);
+    if (input.filtering?.length)
+        params["filtering"] = JSON.stringify(input.filtering);
+    if (input.sort?.length)
+        params["sort"] = input.sort.join(",");
+    return runList(ctx, { path: `${input.object_id}/insights`, params }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, {
+        object_id: input.object_id,
+        level: input.level,
+        date_preset: input.time_range ? undefined : input.date_preset,
+        time_range: input.time_range,
+        breakdowns: input.breakdowns,
+        action_breakdowns: input.action_breakdowns,
+    });
+}

package/dist/tools/ads/list-accounts.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    business_id: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<["owned", "client", "both"]>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    business_id: string;
+    scope: "owned" | "client" | "both";
+    after?: string | undefined;
+}, {
+    business_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    scope?: "owned" | "client" | "both" | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_list_accounts";
+    readonly title: "List ad accounts under a business";
+    readonly description: "Lists ad accounts the business owns (owned_ad_accounts) and/or has access to (client_ad_accounts).\n\nNeeds token scope 'ads_read' and the system user must have 'View performance' task on each account.\n\nReturns account_id (numeric), currency, timezone, status, balance, spend cap. Use 'act_<account_id>' when feeding downstream tools like meta_ads_get_insights.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        business_id: z.ZodString;
+        scope: z.ZodDefault<z.ZodEnum<["owned", "client", "both"]>>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        business_id: string;
+        sections: Record<string, unknown>[];
+    };
+}>;

package/dist/tools/ads/list-accounts.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    business_id: metaIdSchema.describe("Business Manager ID."),
+    scope: z
+        .enum(["owned", "client", "both"])
+        .default("both")
+        .describe("Which ad-account edge: owned_ad_accounts, client_ad_accounts, or both."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "account_id",
+        "name",
+        "currency",
+        "timezone_name",
+        "account_status",
+        "disable_reason",
+        "spend_cap",
+        "balance",
+        "amount_spent",
+        "created_time",
+    ])
+        .describe("Fields per ad account."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_list_accounts",
+    title: "List ad accounts under a business",
+    description: `Lists ad accounts the business owns (owned_ad_accounts) and/or has access to (client_ad_accounts).
+
+Needs token scope 'ads_read' and the system user must have 'View performance' task on each account.
+
+Returns account_id (numeric), currency, timezone, status, balance, spend cap. Use 'act_<account_id>' when feeding downstream tools like meta_ads_get_insights.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export async function handler(input, ctx) {
+    assertAllowed("business", input.business_id, ctx.config);
+    const edges = input.scope === "both" ? ["owned_ad_accounts", "client_ad_accounts"] : [`${input.scope}_ad_accounts`];
+    const sections = [];
+    for (const edge of edges) {
+        const r = await runList(ctx, { path: `${input.business_id}/${edge}`, params: { fields: input.fields.join(","), limit: input.limit, after: input.after } }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { edge });
+        sections.push(r.structuredContent ?? { edge, error: "no data" });
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ business_id: input.business_id, sections }, null, 2) }],
+        structuredContent: { business_id: input.business_id, sections },
+    };
+}

package/dist/tools/ads/list-ads.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    ad_account_id: z.ZodString;
+    adset_id: z.ZodOptional<z.ZodString>;
+    campaign_id: z.ZodOptional<z.ZodString>;
+    effective_status: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    ad_account_id: string;
+    after?: string | undefined;
+    effective_status?: string[] | undefined;
+    campaign_id?: string | undefined;
+    adset_id?: string | undefined;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    effective_status?: string[] | undefined;
+    campaign_id?: string | undefined;
+    adset_id?: string | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_list_ads";
+    readonly title: "List ads (account-, campaign-, or adset-scoped)";
+    readonly description: "Lists ads. Narrow by adset_id (preferred) or campaign_id. Each ad references a 'creative' ID — pass that to meta_ads_get_creative to fetch body, image, and CTA.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        ad_account_id: z.ZodString;
+        adset_id: z.ZodOptional<z.ZodString>;
+        campaign_id: z.ZodOptional<z.ZodString>;
+        effective_status: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/ads/list-ads.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { adAccountIdSchema, metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ad_account_id: adAccountIdSchema,
+    adset_id: metaIdSchema
+        .optional()
+        .describe("If set, lists ads under that ad set via /{adset_id}/ads."),
+    campaign_id: metaIdSchema
+        .optional()
+        .describe("If set (and adset_id is not), lists ads under that campaign."),
+    effective_status: z.array(z.string()).optional(),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "adset_id",
+        "campaign_id",
+        "effective_status",
+        "status",
+        "creative",
+        "preview_shareable_link",
+        "created_time",
+        "updated_time",
+    ])
+        .describe("Ad fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_list_ads",
+    title: "List ads (account-, campaign-, or adset-scoped)",
+    description: `Lists ads. Narrow by adset_id (preferred) or campaign_id. Each ad references a 'creative' ID — pass that to meta_ads_get_creative to fetch body, image, and CTA.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    assertAllowed("ad_account", input.ad_account_id, ctx.config);
+    const params = {
+        fields: input.fields.join(","),
+        limit: input.limit,
+        after: input.after,
+    };
+    if (input.effective_status)
+        params["effective_status"] = JSON.stringify(input.effective_status);
+    const path = input.adset_id
+        ? `${input.adset_id}/ads`
+        : input.campaign_id
+            ? `${input.campaign_id}/ads`
+            : `${input.ad_account_id}/ads`;
+    return runList(ctx, { path, params }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, {
+        ad_account_id: input.ad_account_id,
+        campaign_id: input.campaign_id,
+        adset_id: input.adset_id,
+    });
+}

package/dist/tools/ads/list-adsets.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    ad_account_id: z.ZodString;
+    campaign_id: z.ZodOptional<z.ZodString>;
+    effective_status: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    ad_account_id: string;
+    after?: string | undefined;
+    effective_status?: string[] | undefined;
+    campaign_id?: string | undefined;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    effective_status?: string[] | undefined;
+    campaign_id?: string | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_list_adsets";
+    readonly title: "List ad sets (account-wide or within a campaign)";
+    readonly description: "Lists ad sets. If campaign_id is set, restricts to that campaign. Includes budget, bid strategy, optimization goal, targeting, schedule.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        ad_account_id: z.ZodString;
+        campaign_id: z.ZodOptional<z.ZodString>;
+        effective_status: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/ads/list-adsets.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { adAccountIdSchema, metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ad_account_id: adAccountIdSchema,
+    campaign_id: metaIdSchema
+        .optional()
+        .describe("If provided, lists ad sets under a specific campaign via /{campaign_id}/adsets."),
+    effective_status: z.array(z.string()).optional().describe("Optional effective_status filter."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "campaign_id",
+        "effective_status",
+        "status",
+        "daily_budget",
+        "lifetime_budget",
+        "optimization_goal",
+        "billing_event",
+        "bid_strategy",
+        "bid_amount",
+        "targeting",
+        "start_time",
+        "end_time",
+        "created_time",
+        "updated_time",
+    ])
+        .describe("Ad-set fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_list_adsets",
+    title: "List ad sets (account-wide or within a campaign)",
+    description: `Lists ad sets. If campaign_id is set, restricts to that campaign. Includes budget, bid strategy, optimization goal, targeting, schedule.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    assertAllowed("ad_account", input.ad_account_id, ctx.config);
+    const params = {
+        fields: input.fields.join(","),
+        limit: input.limit,
+        after: input.after,
+    };
+    if (input.effective_status)
+        params["effective_status"] = JSON.stringify(input.effective_status);
+    const path = input.campaign_id ? `${input.campaign_id}/adsets` : `${input.ad_account_id}/adsets`;
+    return runList(ctx, { path, params }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { ad_account_id: input.ad_account_id, campaign_id: input.campaign_id });
+}

package/dist/tools/ads/list-campaigns.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    ad_account_id: z.ZodString;
+    effective_status: z.ZodOptional<z.ZodArray<z.ZodEnum<["ACTIVE", "PAUSED", "DELETED", "PENDING_REVIEW", "DISAPPROVED", "PREAPPROVED", "PENDING_BILLING_INFO", "CAMPAIGN_PAUSED", "ARCHIVED", "IN_PROCESS", "WITH_ISSUES"]>, "many">>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    ad_account_id: string;
+    after?: string | undefined;
+    effective_status?: ("ACTIVE" | "PAUSED" | "DELETED" | "PENDING_REVIEW" | "DISAPPROVED" | "PREAPPROVED" | "PENDING_BILLING_INFO" | "CAMPAIGN_PAUSED" | "ARCHIVED" | "IN_PROCESS" | "WITH_ISSUES")[] | undefined;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    effective_status?: ("ACTIVE" | "PAUSED" | "DELETED" | "PENDING_REVIEW" | "DISAPPROVED" | "PREAPPROVED" | "PENDING_BILLING_INFO" | "CAMPAIGN_PAUSED" | "ARCHIVED" | "IN_PROCESS" | "WITH_ISSUES")[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_list_campaigns";
+    readonly title: "List campaigns in an ad account";
+    readonly description: "Lists campaigns with status, objective, budget, and schedule. Use effective_status to filter only ACTIVE campaigns, for example. Pair with meta_ads_get_insights at level='campaign' for performance metrics.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        ad_account_id: z.ZodString;
+        effective_status: z.ZodOptional<z.ZodArray<z.ZodEnum<["ACTIVE", "PAUSED", "DELETED", "PENDING_REVIEW", "DISAPPROVED", "PREAPPROVED", "PENDING_BILLING_INFO", "CAMPAIGN_PAUSED", "ARCHIVED", "IN_PROCESS", "WITH_ISSUES"]>, "many">>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;