@cashtokenai/meta-mcp-server 1.0.0

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+import pino from "pino";
+export declare function createLogger(level: string): pino.Logger<never, boolean>;
+export type Logger = ReturnType<typeof createLogger>;

package/dist/logger.js

@@ -0,0 +1,18 @@
+import pino from "pino";
+export function createLogger(level) {
+    return pino({
+        name: "meta-mcp",
+        level,
+        redact: {
+            paths: [
+                "access_token",
+                "*.access_token",
+                "params.access_token",
+                "headers.authorization",
+                "appsecret_proof",
+                "*.appsecret_proof",
+            ],
+            censor: "[redacted]",
+        },
+    }, pino.destination(2));
+}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Config } from "./config.js";
+import type { Logger } from "./logger.js";
+export declare function buildServer(config: Config, logger: Logger): {
+    server: McpServer;
+    ctx: import("./context.js").ToolContext;
+};

package/dist/server.js

@@ -0,0 +1,34 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createContext } from "./context.js";
+import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+import { registerTools } from "./tools/register.js";
+/**
+ * Server-level routing guidance surfaced to MCP clients via the SDK's
+ * `instructions` field. Gateways that inject server instructions into the
+ * model's system prompt use this to pick the right tool without the user
+ * having to fine-tune their phrasing. Keep it short, imperative, and focused
+ * on the question-classes users actually ask.
+ */
+const SERVER_INSTRUCTIONS = `This server exposes READ-ONLY Meta Business Manager analytics (Facebook Pages, Instagram, ads, pixels, catalog, WhatsApp).
+
+TOOL ROUTING — pick the broadest matching tool and CALL IT. Never tell the user to rephrase, and never ask for IDs the server can discover itself:
+
+- "How is my marketing doing / give me an overview / snapshot" → meta_business_overview (no business_id needed; it auto-discovers).
+- "How did my LATEST / most recent post do" → meta_latest_posts_summary.
+- "How many posts in the last week / this month, by type, performance comparison, content report, trend" → meta_content_report (takes a date window).
+- "Audience demographics / age / gender / country / city breakdown" → meta_ig_get_audience_demographics.
+- "Ad spend / campaign performance / CTR / CPC / ROAS / which ad/campaign" → meta_ads_get_insights (level=account|campaign|adset|ad, with breakdowns).
+- "What assets / pages / accounts do I have" → meta_business_list_assets.
+- Unsure which asset ID to use → call a discovery/report tool first (they auto-discover); do NOT guess placeholder IDs.
+
+If a tool returns a (#10)/(#200) permission error, relay its 'hint' to the user verbatim — it names the exact Meta App Review or scope action needed. Prefer the report/overview tools (one call) over chaining several low-level tools.`;
+export function buildServer(config, logger) {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, { instructions: SERVER_INSTRUCTIONS });
+    const ctx = createContext(config, logger);
+    const toolNames = registerTools(server, ctx);
+    logger.info({ tools: toolNames, count: toolNames.length }, "tools registered");
+    return { server, ctx };
+}

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    ad_account_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    ad_account_id: string;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_get_account";
+    readonly title: "Get ad account details";
+    readonly description: "Reads account-level details for a single ad account: status, currency, spend cap, current balance, amount_spent lifetime, funding source, capabilities, business owner. Use to verify an account is active and has headroom before drilling into insights.";
+    readonly inputSchema: {
+        ad_account_id: z.ZodString;
+        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/get-account.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { adAccountIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ad_account_id: adAccountIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "account_id",
+        "name",
+        "currency",
+        "timezone_name",
+        "account_status",
+        "disable_reason",
+        "spend_cap",
+        "balance",
+        "amount_spent",
+        "funding_source_details",
+        "business",
+        "capabilities",
+        "age",
+        "created_time",
+    ])
+        .describe("Fields to return."),
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_get_account",
+    title: "Get ad account details",
+    description: `Reads account-level details for a single ad account: status, currency, spend cap, current balance, amount_spent lifetime, funding source, capabilities, business owner. Use to verify an account is active and has headroom before drilling into insights.`,
+    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);
+    return runGet(ctx, { path: input.ad_account_id, params: { fields: input.fields.join(",") } });
+}

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    creative_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    creative_id: string;
+}, {
+    creative_id: string;
+    fields?: string[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_get_creative";
+    readonly title: "Get ad creative details";
+    readonly description: "Reads ad creative body: headline, copy, image or video, CTA, link URL, attached object story. Use alongside insights to explain why a particular ad performed well.";
+    readonly inputSchema: {
+        creative_id: z.ZodString;
+        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/get-creative.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { metaIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+export const inputSchema = z
+    .object({
+    creative_id: metaIdSchema.describe("Creative ID (as returned by meta_ads_list_ads.creative.id)."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "title",
+        "body",
+        "object_story_id",
+        "object_type",
+        "image_url",
+        "thumbnail_url",
+        "video_id",
+        "call_to_action_type",
+        "link_url",
+        "effective_object_story_id",
+        "instagram_permalink_url",
+        "object_story_spec",
+    ])
+        .describe("Creative fields."),
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_get_creative",
+    title: "Get ad creative details",
+    description: `Reads ad creative body: headline, copy, image or video, CTA, link URL, attached object story. Use alongside insights to explain why a particular ad performed well.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runGet(ctx, { path: input.creative_id, params: { fields: input.fields.join(",") } });
+}

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[];
+    object_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    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;
+    fields?: string[] | undefined;
+    sort?: 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\nUSE FOR ad/paid questions: \"how much did I spend\", \"ad spend last 7/30 days\", \"campaign performance\", \"which campaign/ad performed best\", \"CTR / CPC / CPM / ROAS / cost per result\", \"conversions from ads\", \"ad performance comparison\", \"spend by placement / age / gender / country\". This is PAID-ads analytics. For organic post/content performance use meta_content_report; for the latest organic post use meta_latest_posts_summary.\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,153 @@
+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.
+
+USE FOR ad/paid questions: "how much did I spend", "ad spend last 7/30 days", "campaign performance", "which campaign/ad performed best", "CTR / CPC / CPM / ROAS / cost per result", "conversions from ads", "ad performance comparison", "spend by placement / age / gender / country". This is PAID-ads analytics. For organic post/content performance use meta_content_report; for the latest organic post use meta_latest_posts_summary.
+
+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[];
+    business_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    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 },
+    };
+}