@cashtokenai/meta-mcp-server 1.0.0

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[];
+    ad_account_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    campaign_id?: string | undefined;
+    adset_id?: string | undefined;
+    after?: string | undefined;
+    effective_status?: string[] | undefined;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+    campaign_id?: string | undefined;
+    adset_id?: string | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    effective_status?: 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[];
+    ad_account_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    campaign_id?: string | undefined;
+    after?: string | undefined;
+    effective_status?: string[] | undefined;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+    campaign_id?: string | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    effective_status?: 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[];
+    ad_account_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    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>;

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

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { adAccountIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ad_account_id: adAccountIdSchema,
+    effective_status: z
+        .array(z.enum([
+        "ACTIVE",
+        "PAUSED",
+        "DELETED",
+        "PENDING_REVIEW",
+        "DISAPPROVED",
+        "PREAPPROVED",
+        "PENDING_BILLING_INFO",
+        "CAMPAIGN_PAUSED",
+        "ARCHIVED",
+        "IN_PROCESS",
+        "WITH_ISSUES",
+    ]))
+        .optional()
+        .describe("Filter by effective_status. Omit to list all."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "objective",
+        "effective_status",
+        "status",
+        "daily_budget",
+        "lifetime_budget",
+        "budget_remaining",
+        "buying_type",
+        "special_ad_categories",
+        "start_time",
+        "stop_time",
+        "created_time",
+        "updated_time",
+    ])
+        .describe("Campaign fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_list_campaigns",
+    title: "List campaigns in an ad account",
+    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.`,
+    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);
+    }
+    return runList(ctx, { path: `${input.ad_account_id}/campaigns`, params }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { ad_account_id: input.ad_account_id });
+}

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

@@ -0,0 +1,41 @@
+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;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    ad_account_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    after?: string | undefined;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_list_custom_audiences";
+    readonly title: "List custom audiences (metadata only)";
+    readonly description: "Lists custom audiences attached to an ad account — names, subtype (CUSTOM, WEBSITE, LOOKALIKE, …), approximate size buckets, delivery status, data source. No member-level data is exposed.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        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/list-custom-audiences.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { adAccountIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ad_account_id: adAccountIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "description",
+        "subtype",
+        "approximate_count_lower_bound",
+        "approximate_count_upper_bound",
+        "delivery_status",
+        "operation_status",
+        "data_source",
+        "retention_days",
+        "time_created",
+        "time_updated",
+    ])
+        .describe("Metadata fields. No PII/member data is returned by this endpoint."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_list_custom_audiences",
+    title: "List custom audiences (metadata only)",
+    description: `Lists custom audiences attached to an ad account — names, subtype (CUSTOM, WEBSITE, LOOKALIKE, …), approximate size buckets, delivery status, data source. No member-level data is exposed.`,
+    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 runList(ctx, {
+        path: `${input.ad_account_id}/customaudiences`,
+        params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { ad_account_id: input.ad_account_id });
+}

package/dist/tools/business/list-assets.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    business_id: z.ZodString;
+    kinds: z.ZodDefault<z.ZodArray<z.ZodEnum<["ad_accounts", "pages", "instagram_accounts", "pixels", "product_catalogs", "whatsapp_business_accounts"]>, "many">>;
+    include_client: z.ZodDefault<z.ZodBoolean>;
+    per_kind_limit: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    business_id: string;
+    kinds: ("pages" | "ad_accounts" | "instagram_accounts" | "pixels" | "product_catalogs" | "whatsapp_business_accounts")[];
+    include_client: boolean;
+    per_kind_limit: number;
+}, {
+    business_id: string;
+    kinds?: ("pages" | "ad_accounts" | "instagram_accounts" | "pixels" | "product_catalogs" | "whatsapp_business_accounts")[] | undefined;
+    include_client?: boolean | undefined;
+    per_kind_limit?: number | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_business_list_assets";
+    readonly title: "List assets assigned to a Business Manager";
+    readonly description: "For a given business_id, enumerates the business assets the token can see in one call:\n- Ad accounts (owned + optionally client)\n- Facebook Pages (owned + optionally client)\n- Instagram Business accounts\n- Meta Pixels\n- Product catalogs\n- WhatsApp Business accounts (WABAs)\n\nEach section is fetched as a separate Graph call. Failures on individual sections do not abort the others — the response reports per-section success/error so the assistant can work around partial failures.\n\nUse this to discover IDs for downstream insight tools.";
+    readonly inputSchema: {
+        business_id: z.ZodString;
+        kinds: z.ZodDefault<z.ZodArray<z.ZodEnum<["ad_accounts", "pages", "instagram_accounts", "pixels", "product_catalogs", "whatsapp_business_accounts"]>, "many">>;
+        include_client: z.ZodDefault<z.ZodBoolean>;
+        per_kind_limit: z.ZodDefault<z.ZodNumber>;
+    };
+    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/business/list-assets.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolResult } from "../../helpers/format.js";
+import { metaIdSchema } from "../../helpers/schema.js";
+const ASSET_KINDS = [
+    "ad_accounts",
+    "pages",
+    "instagram_accounts",
+    "pixels",
+    "product_catalogs",
+    "whatsapp_business_accounts",
+];
+export const inputSchema = z
+    .object({
+    business_id: metaIdSchema.describe("Business Manager ID (from meta_business_list)."),
+    kinds: z
+        .array(z.enum(ASSET_KINDS))
+        .default([...ASSET_KINDS])
+        .describe("Which asset edges to enumerate. Default: all."),
+    include_client: z
+        .boolean()
+        .default(false)
+        .describe("Also fetch client_* edges (assets the business has access to but does not own)."),
+    per_kind_limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .default(50)
+        .describe("Page size per asset kind."),
+})
+    .strict();
+export const definition = {
+    name: "meta_business_list_assets",
+    title: "List assets assigned to a Business Manager",
+    description: `For a given business_id, enumerates the business assets the token can see in one call:
+- Ad accounts (owned + optionally client)
+- Facebook Pages (owned + optionally client)
+- Instagram Business accounts
+- Meta Pixels
+- Product catalogs
+- WhatsApp Business accounts (WABAs)
+
+Each section is fetched as a separate Graph call. Failures on individual sections do not abort the others — the response reports per-section success/error so the assistant can work around partial failures.
+
+Use this to discover IDs for downstream insight tools.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+const FIELDS = {
+    ad_accounts: "id,account_id,name,currency,timezone_name,account_status",
+    pages: "id,name,category,tasks,access_token",
+    instagram_accounts: "id,username",
+    pixels: "id,name,last_fired_time,is_unavailable",
+    product_catalogs: "id,name,vertical,product_count",
+    whatsapp_business_accounts: "id,name,currency,timezone_id",
+};
+const EDGE_NAME = {
+    ad_accounts: { owned: "owned_ad_accounts", client: "client_ad_accounts" },
+    pages: { owned: "owned_pages", client: "client_pages" },
+    // Graph exposes `owned_instagram_accounts` on the Business node but not a
+    // `client_instagram_accounts` edge. IG accounts linked to a Page are also
+    // discoverable via `GET /{page_id}?fields=instagram_business_account`.
+    instagram_accounts: { owned: "owned_instagram_accounts", client: null },
+    pixels: { owned: "owned_pixels", client: null },
+    product_catalogs: { owned: "owned_product_catalogs", client: "client_product_catalogs" },
+    whatsapp_business_accounts: { owned: "owned_whatsapp_business_accounts", client: "client_whatsapp_business_accounts" },
+};
+export async function handler(input, ctx) {
+    assertAllowed("business", input.business_id, ctx.config);
+    const scopes = input.include_client ? ["owned", "client"] : ["owned"];
+    const sections = {};
+    await Promise.all(input.kinds.flatMap((kind) => scopes.map(async (scope) => {
+        const edge = EDGE_NAME[kind][scope];
+        if (!edge)
+            return;
+        const section = (sections[kind] ??= []);
+        try {
+            const page = await ctx.graph.get({
+                path: `${input.business_id}/${edge}`,
+                params: { fields: FIELDS[kind], limit: input.per_kind_limit },
+            });
+            section.push({ scope, items: Array.isArray(page.data) ? page.data : [] });
+        }
+        catch (err) {
+            const e = err instanceof MetaError ? err : new MetaError(err.message);
+            section.push({ scope, error: e.message, hint: e.hint });
+        }
+    })));
+    // Fallback IG discovery: walk the surviving Pages and look up
+    // `instagram_business_account`. Meta increasingly hides IG behind the Page
+    // link rather than the Business node.
+    if (input.kinds.includes("instagram_accounts")) {
+        const pageSection = sections.pages ?? [];
+        const pageItems = pageSection.flatMap((s) => s.items ?? []);
+        const igFromPages = [];
+        await Promise.all(pageItems.map(async (p) => {
+            try {
+                const data = await ctx.graph.get({
+                    path: p.id,
+                    params: { fields: "id,name,instagram_business_account{id,username,name}" },
+                });
+                if (data.instagram_business_account) {
+                    igFromPages.push({
+                        id: data.instagram_business_account.id,
+                        name: data.instagram_business_account.name,
+                        username: data.instagram_business_account.username,
+                        category: `via page ${data.id} (${data.name ?? ""})`.trim(),
+                    });
+                }
+            }
+            catch {
+                /* non-fatal per-page */
+            }
+        }));
+        if (igFromPages.length > 0) {
+            (sections.instagram_accounts ??= []).push({
+                scope: "via_page",
+                items: igFromPages,
+                source: "page.instagram_business_account",
+            });
+        }
+    }
+    const structured = {
+        business_id: input.business_id,
+        scopes,
+        assets: sections,
+    };
+    return toolResult(structured, jsonBlock(structured));
+}

package/dist/tools/business/list-businesses.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    after?: string | undefined;
+}, {
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_business_list";
+    readonly title: "List Meta businesses visible to the token";
+    readonly description: "Lists every Business Manager the configured access token can see — via GET /me/businesses.\n\nTypical usage: call this once at the start of a session to discover available business IDs, then pass the chosen ID to meta_business_list_assets / meta_business_list_system_users.\n\nRespects META_ALLOWED_BUSINESS_IDS: if set, filters the response to that allowlist.";
+    readonly inputSchema: {
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    };
+    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>;