@cashtokenai/meta-mcp-server 1.0.0

package/dist/tools/pixels/list.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>;
+    business_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    business_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    after?: string | undefined;
+}, {
+    business_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_pixel_list";
+    readonly title: "List Meta Pixels under a business";
+    readonly description: "Lists Meta (Facebook) Pixels owned by a business via /{business_id}/owned_pixels. Includes last_fired_time so you can spot stale pixels. Requires 'business_management' or Marketing API access.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        business_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/pixels/list.js

@@ -0,0 +1,41 @@
+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."),
+    fields: z
+        .array(z.string())
+        .default([
+        // 'code' (the pixel's JS snippet) and 'owner_ad_account' both require
+        // ads_management on the *owning* ad account, not just the business.
+        // Reading them with a system-user token that wasn't granted that
+        // task fails the whole list with (#200). We omit them from the
+        // defaults so the list stays useful; callers can re-add explicitly.
+        "id",
+        "name",
+        "is_created_by_business",
+        "is_unavailable",
+        "last_fired_time",
+        "creation_time",
+        "owner_business",
+    ])
+        .describe("Pixel fields. 'code' and 'owner_ad_account' are NOT in the default — they require ads_management on the owning ad account. Re-add them only when the system user has that task on every pixel's owner account."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_pixel_list",
+    title: "List Meta Pixels under a business",
+    description: `Lists Meta (Facebook) Pixels owned by a business via /{business_id}/owned_pixels. Includes last_fired_time so you can spot stale pixels. Requires 'business_management' or Marketing API access.`,
+    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);
+    return runList(ctx, {
+        path: `${input.business_id}/owned_pixels`,
+        params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { business_id: input.business_id });
+}

package/dist/tools/register.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolContext } from "../context.js";
+export declare function registerTools(server: McpServer, ctx: ToolContext): string[];

package/dist/tools/register.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { validateInput } from "../helpers/validate.js";
+// Token + meta
+import * as tokenInspect from "./token/inspect.js";
+import * as tokenHealth from "./token/health.js";
+import * as graphRead from "./meta/graph-read.js";
+// Business discovery
+import * as listBusinesses from "./business/list-businesses.js";
+import * as listAssets from "./business/list-assets.js";
+import * as listSystemUsers from "./business/list-system-users.js";
+// Ads (Marketing API)
+import * as adsListAccounts from "./ads/list-accounts.js";
+import * as adsGetAccount from "./ads/get-account.js";
+import * as adsListCampaigns from "./ads/list-campaigns.js";
+import * as adsListAdsets from "./ads/list-adsets.js";
+import * as adsListAds from "./ads/list-ads.js";
+import * as adsGetInsights from "./ads/get-insights.js";
+import * as adsGetCreative from "./ads/get-creative.js";
+import * as adsListCustomAudiences from "./ads/list-custom-audiences.js";
+// Pages
+import * as pageList from "./pages/list.js";
+import * as pageGet from "./pages/get.js";
+import * as pageListPosts from "./pages/list-posts.js";
+import * as pageGetPostInsights from "./pages/get-post-insights.js";
+import * as pageGetInsights from "./pages/get-insights.js";
+import * as pageListReviews from "./pages/list-reviews.js";
+import * as pageListVideos from "./pages/list-videos.js";
+// Instagram
+import * as igListAccounts from "./instagram/list-accounts.js";
+import * as igGetAccount from "./instagram/get-account.js";
+import * as igListMedia from "./instagram/list-media.js";
+import * as igGetMediaInsights from "./instagram/get-media-insights.js";
+import * as igGetAudienceDemographics from "./instagram/get-audience-demographics.js";
+// Pixels
+import * as pixelList from "./pixels/list.js";
+import * as pixelGetStats from "./pixels/get-stats.js";
+// Catalog
+import * as catalogList from "./catalog/list.js";
+import * as catalogListProducts from "./catalog/list-products.js";
+import * as catalogGetDiagnostics from "./catalog/get-diagnostics.js";
+// WhatsApp
+import * as whatsappListWabas from "./whatsapp/list-wabas.js";
+import * as whatsappListPhoneNumbers from "./whatsapp/list-phone-numbers.js";
+import * as whatsappListTemplates from "./whatsapp/list-templates.js";
+import * as whatsappGetAnalytics from "./whatsapp/get-analytics.js";
+// Overview
+import * as businessOverview from "./overview/business-overview.js";
+import * as latestPostsSummary from "./overview/latest-posts-summary.js";
+import * as contentReport from "./overview/content-report.js";
+const TOOLS = [
+    // Token + meta (3)
+    tokenInspect, tokenHealth, graphRead,
+    // Business discovery (3)
+    listBusinesses, listAssets, listSystemUsers,
+    // Ads (8)
+    adsListAccounts, adsGetAccount, adsListCampaigns, adsListAdsets, adsListAds,
+    adsGetInsights, adsGetCreative, adsListCustomAudiences,
+    // Pages (7)
+    pageList, pageGet, pageListPosts, pageGetPostInsights, pageGetInsights,
+    pageListReviews, pageListVideos,
+    // Instagram (5)
+    igListAccounts, igGetAccount, igListMedia, igGetMediaInsights, igGetAudienceDemographics,
+    // Pixels (2)
+    pixelList, pixelGetStats,
+    // Catalog (3)
+    catalogList, catalogListProducts, catalogGetDiagnostics,
+    // WhatsApp (4)
+    whatsappListWabas, whatsappListPhoneNumbers, whatsappListTemplates, whatsappGetAnalytics,
+    // Overview (3)
+    businessOverview, latestPostsSummary, contentReport,
+].map((m) => m);
+export function registerTools(server, ctx) {
+    const names = [];
+    for (const mod of TOOLS) {
+        server.registerTool(mod.definition.name, {
+            title: mod.definition.title,
+            description: mod.definition.description,
+            inputSchema: mod.definition.inputSchema,
+            annotations: mod.definition.annotations,
+        }, (async (args) => {
+            // Defense in depth: re-validate at the handler boundary even if the
+            // SDK / MCP gateway already did. Some gateways forward inputs without
+            // enforcing per-property Zod refinements (e.g. regex on ad_account_id),
+            // which would otherwise let placeholder strings like "act_<YOUR_PAGE_ID>"
+            // reach Meta. See ADR-20260429-Handler-Input-Validation.md.
+            const validated = validateInput(mod.inputSchema ?? z.object(mod.definition.inputSchema), args);
+            if (!validated.ok) {
+                return validated.error;
+            }
+            return mod.handler(validated.data, ctx);
+        }));
+        names.push(mod.definition.name);
+    }
+    return names;
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,45 @@
+import type { ToolContext } from "../context.js";
+import { type ToolTextResult } from "../helpers/format.js";
+import type { GraphGetOptions } from "../helpers/graph-client.js";
+export interface ListRunOpts {
+    auto_paginate?: boolean;
+    after?: string;
+    limit?: number;
+}
+/**
+ * Fetch one page or auto-paginate, normalize into a structured list payload,
+ * and translate errors. Use for simple `GET /{id}/{edge}` style tools.
+ */
+export declare function runList<T>(ctx: ToolContext, opts: GraphGetOptions, pag: ListRunOpts, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/** Run a single read and return a tool result. */
+export declare function runGet<T>(ctx: ToolContext, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/**
+ * Like runGet, but routes through the secondary insights-app token + secret
+ * when one is configured (META_INSIGHTS_ACCESS_TOKEN). Use for direct
+ * `/{id}/insights` reads that require a permission (e.g.
+ * instagram_manage_insights) the primary ads app cannot host. Falls back to
+ * the primary token transparently when no insights app is configured.
+ */
+export declare function runGetViaInsightsApp<T>(ctx: ToolContext, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+export declare function errorResult(err: unknown): ToolTextResult;
+/**
+ * Resolves a Page access token for `pageId`, then runs `runList` with it as
+ * the access-token override. Page-level edges (`/{page_id}/posts`,
+ * `/{page_id}/insights`, `/{page_id}/ratings`, `/{page_id}/videos`,
+ * `/{post_id}/insights`) require a Page access token rather than the
+ * configured system-user token.
+ */
+export declare function runListAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, pag: ListRunOpts, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/** Same as runGet but resolves and uses the Page access token first. */
+export declare function runGetAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/**
+ * Page-insights variant of runGetAsPage. When a secondary insights app is
+ * configured (the app holding the Pages "read_insights" use case), the Page
+ * access token is derived from the *insights* app's token and the call's
+ * appsecret_proof uses the insights app secret. Falls back to the primary
+ * app's Page token when no insights app is configured.
+ *
+ * Use for /{page_id}/insights and /{post_id}/insights, which need
+ * `read_insights` — a permission the Marketing-API primary app cannot host.
+ */
+export declare function runGetAsPageViaInsightsApp<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;

package/dist/tools/shared.js

@@ -0,0 +1,137 @@
+/**
+ * Shared helpers used across domain tools — keeps each tool file focused on
+ * its endpoint instead of re-implementing boilerplate.
+ */
+import { insightsCreds } from "../config.js";
+import { MetaError } from "../errors.js";
+import { jsonBlock, toolError, toolResult } from "../helpers/format.js";
+/**
+ * If a secondary "insights app" is configured, returns the token + app-secret
+ * overrides to route this call through it; otherwise returns an empty object
+ * (call uses the primary app). Insight endpoints (IG media/audience, Page/post
+ * insights) need this because Meta forbids combining the Marketing-API use
+ * case with Instagram-content / Pages-everything on a single app — so insights
+ * frequently live on a second app. See config.ts `insightsCreds`.
+ */
+function insightsOverrides(ctx) {
+    const creds = insightsCreds(ctx.config);
+    if (!creds)
+        return {};
+    return { accessTokenOverride: creds.token, appSecretOverride: creds.appSecret };
+}
+/**
+ * Fetch one page or auto-paginate, normalize into a structured list payload,
+ * and translate errors. Use for simple `GET /{id}/{edge}` style tools.
+ */
+export async function runList(ctx, opts, pag, extra = {}) {
+    try {
+        if (pag.auto_paginate) {
+            const { data, pages, nextAfter } = await ctx.graph.getAllPages(opts);
+            const structured = {
+                ...extra,
+                count: data.length,
+                pages_fetched: pages,
+                next_after: nextAfter,
+                items: data,
+            };
+            return toolResult(structured, jsonBlock(structured));
+        }
+        const page = await ctx.graph.get(opts);
+        const items = Array.isArray(page.data) ? page.data : [];
+        const structured = {
+            ...extra,
+            count: items.length,
+            pages_fetched: 1,
+            next_after: page.paging?.cursors?.after,
+            items,
+        };
+        return toolResult(structured, jsonBlock(structured));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+/** Run a single read and return a tool result. */
+export async function runGet(ctx, opts, extra = {}) {
+    try {
+        const data = await ctx.graph.get(opts);
+        const structured = { ...extra, data };
+        return toolResult(structured, jsonBlock(data));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+/**
+ * Like runGet, but routes through the secondary insights-app token + secret
+ * when one is configured (META_INSIGHTS_ACCESS_TOKEN). Use for direct
+ * `/{id}/insights` reads that require a permission (e.g.
+ * instagram_manage_insights) the primary ads app cannot host. Falls back to
+ * the primary token transparently when no insights app is configured.
+ */
+export async function runGetViaInsightsApp(ctx, opts, extra = {}) {
+    return runGet(ctx, { ...opts, ...insightsOverrides(ctx) }, extra);
+}
+export function errorResult(err) {
+    const e = err instanceof MetaError ? err : new MetaError(err.message);
+    return toolError(e.message, e.hint, {
+        code: e.code,
+        subcode: e.subcode,
+        fbtrace_id: e.fbtraceId,
+        http_status: e.httpStatus,
+        retryable: e.retryable,
+    });
+}
+/**
+ * Resolves a Page access token for `pageId`, then runs `runList` with it as
+ * the access-token override. Page-level edges (`/{page_id}/posts`,
+ * `/{page_id}/insights`, `/{page_id}/ratings`, `/{page_id}/videos`,
+ * `/{post_id}/insights`) require a Page access token rather than the
+ * configured system-user token.
+ */
+export async function runListAsPage(ctx, pageId, opts, pag, extra = {}) {
+    try {
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runList(ctx, { ...opts, accessTokenOverride: pageToken }, pag, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+/** Same as runGet but resolves and uses the Page access token first. */
+export async function runGetAsPage(ctx, pageId, opts, extra = {}) {
+    try {
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runGet(ctx, { ...opts, accessTokenOverride: pageToken }, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+/**
+ * Page-insights variant of runGetAsPage. When a secondary insights app is
+ * configured (the app holding the Pages "read_insights" use case), the Page
+ * access token is derived from the *insights* app's token and the call's
+ * appsecret_proof uses the insights app secret. Falls back to the primary
+ * app's Page token when no insights app is configured.
+ *
+ * Use for /{page_id}/insights and /{post_id}/insights, which need
+ * `read_insights` — a permission the Marketing-API primary app cannot host.
+ */
+export async function runGetAsPageViaInsightsApp(ctx, pageId, opts, extra = {}) {
+    try {
+        const creds = insightsCreds(ctx.config);
+        if (creds) {
+            const pageToken = await ctx.graph.getPageAccessToken(pageId, {
+                token: creds.token,
+                appSecret: creds.appSecret,
+            });
+            return runGet(ctx, { ...opts, accessTokenOverride: pageToken, appSecretOverride: creds.appSecret }, extra);
+        }
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runGet(ctx, { ...opts, accessTokenOverride: pageToken }, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}

package/dist/tools/token/health.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_health_check";
+    readonly title: "Meta MCP health check";
+    readonly description: "End-to-end reachability probe:\n- Reports the running server name + version (use this to confirm the gateway is on the latest published build — a stale npx cache is a common cause of \"missing\" tools).\n- Confirms the Graph API is reachable.\n- Confirms the configured token resolves to a valid identity (via /me).\n- Surfaces the latest rate-limit header snapshot from the Graph client.\n- Lists which allowlists are active (business / ad account / page / IG user).\n\nUse when a session starts, or when diagnosing why other tools are returning errors or appear to be missing.";
+    readonly inputSchema: {};
+    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/token/health.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { SERVER_NAME, SERVER_VERSION } from "../../constants.js";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolError, toolResult } from "../../helpers/format.js";
+export const inputSchema = z.object({}).strict();
+export const definition = {
+    name: "meta_health_check",
+    title: "Meta MCP health check",
+    description: `End-to-end reachability probe:
+- Reports the running server name + version (use this to confirm the gateway is on the latest published build — a stale npx cache is a common cause of "missing" tools).
+- Confirms the Graph API is reachable.
+- Confirms the configured token resolves to a valid identity (via /me).
+- Surfaces the latest rate-limit header snapshot from the Graph client.
+- Lists which allowlists are active (business / ad account / page / IG user).
+
+Use when a session starts, or when diagnosing why other tools are returning errors or appear to be missing.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export async function handler(_input, ctx) {
+    const started = Date.now();
+    try {
+        const me = await ctx.graph.get({
+            path: "me",
+            params: { fields: "id,name" },
+            noCache: true,
+        });
+        const structured = {
+            ok: true,
+            server_name: SERVER_NAME,
+            server_version: SERVER_VERSION,
+            latency_ms: Date.now() - started,
+            identity: me,
+            api_version: ctx.config.apiVersion,
+            appsecret_proof_enabled: Boolean(ctx.config.appSecret),
+            insights_app_configured: Boolean(ctx.config.insightsAccessToken),
+            insights_app_appsecret_proof_enabled: Boolean(ctx.config.insightsAppSecret),
+            rate_limit: ctx.graph.rateLimit,
+            allowlists: {
+                businesses: ctx.config.allowedBusinessIds ? [...ctx.config.allowedBusinessIds] : null,
+                ad_accounts: ctx.config.allowedAdAccountIds
+                    ? [...ctx.config.allowedAdAccountIds]
+                    : null,
+                pages: ctx.config.allowedPageIds ? [...ctx.config.allowedPageIds] : null,
+                ig_users: ctx.config.allowedIgUserIds ? [...ctx.config.allowedIgUserIds] : null,
+            },
+        };
+        return toolResult(structured, jsonBlock(structured));
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        return toolError(`Health check failed: ${e.message}`, e.hint, {
+            code: e.code,
+            subcode: e.subcode,
+            fbtrace_id: e.fbtraceId,
+            http_status: e.httpStatus,
+            latency_ms: Date.now() - started,
+        });
+    }
+}

package/dist/tools/token/inspect.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+import { ResponseFormat } from "../../helpers/format.js";
+export declare const inputSchema: z.ZodObject<{
+    response_format: z.ZodDefault<z.ZodNativeEnum<typeof ResponseFormat>>;
+}, "strict", z.ZodTypeAny, {
+    response_format: ResponseFormat;
+}, {
+    response_format?: ResponseFormat | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_token_inspect";
+    readonly title: "Inspect Meta access token";
+    readonly description: "Decodes the configured META_ACCESS_TOKEN via Graph API /debug_token.\n\nReturns:\n- app_id + application name\n- token type (system-user / user / page)\n- is_valid\n- expires_at + data_access_expires_at (unix seconds; 0 = never expires)\n- scopes + granular_scopes (per-asset targeting)\n\nUse this first when troubleshooting — almost every other tool failure traces back to a missing scope or an asset not assigned to the token.\n\nNever logs the token itself.";
+    readonly inputSchema: {
+        response_format: z.ZodDefault<z.ZodNativeEnum<typeof ResponseFormat>>;
+    };
+    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/token/inspect.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, ResponseFormat, toolError, toolResult } from "../../helpers/format.js";
+import { responseFormatShape } from "../../helpers/schema.js";
+export const inputSchema = z
+    .object({
+    ...responseFormatShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_token_inspect",
+    title: "Inspect Meta access token",
+    description: `Decodes the configured META_ACCESS_TOKEN via Graph API /debug_token.
+
+Returns:
+- app_id + application name
+- token type (system-user / user / page)
+- is_valid
+- expires_at + data_access_expires_at (unix seconds; 0 = never expires)
+- scopes + granular_scopes (per-asset targeting)
+
+Use this first when troubleshooting — almost every other tool failure traces back to a missing scope or an asset not assigned to the token.
+
+Never logs the token itself.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export async function handler(input, ctx) {
+    try {
+        const data = await ctx.graph.get({
+            path: "debug_token",
+            params: { input_token: ctx.config.accessToken },
+            noCache: true,
+        });
+        const debug = data.data ?? {};
+        const now = Math.floor(Date.now() / 1000);
+        const expiresIn = debug.expires_at && debug.expires_at > 0 ? debug.expires_at - now : null;
+        const dataAccessExpiresIn = debug.data_access_expires_at && debug.data_access_expires_at > 0
+            ? debug.data_access_expires_at - now
+            : null;
+        const structured = {
+            ...debug,
+            expires_in_seconds: expiresIn,
+            data_access_expires_in_seconds: dataAccessExpiresIn,
+            never_expires: debug.expires_at === 0,
+            app_secret_proof_enabled: Boolean(ctx.config.appSecret),
+        };
+        const text = input.response_format === ResponseFormat.MARKDOWN
+            ? renderMarkdown(structured)
+            : jsonBlock(structured);
+        return toolResult(structured, text);
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        return toolError(e.message, e.hint, {
+            code: e.code,
+            subcode: e.subcode,
+            fbtrace_id: e.fbtraceId,
+            http_status: e.httpStatus,
+        });
+    }
+}
+function renderMarkdown(d) {
+    const lines = ["# Meta Token Inspection", ""];
+    lines.push(`- **Valid**: ${d.is_valid ?? "unknown"}`);
+    lines.push(`- **App**: ${d.application ?? "?"} (${d.app_id ?? "?"})`);
+    if (d.type)
+        lines.push(`- **Type**: ${d.type}`);
+    if (d.user_id)
+        lines.push(`- **User / System User ID**: ${d.user_id}`);
+    lines.push(`- **Expires**: ${d.never_expires ? "never" : d.expires_in_seconds != null ? `in ${d.expires_in_seconds}s` : "unknown"}`);
+    lines.push(`- **appsecret_proof**: ${d.app_secret_proof_enabled ? "enabled" : "disabled (recommend enabling)"}`);
+    if (d.scopes?.length) {
+        lines.push("", "## Scopes", ...d.scopes.map((s) => `- ${s}`));
+    }
+    if (d.granular_scopes?.length) {
+        lines.push("", "## Granular scopes");
+        for (const g of d.granular_scopes) {
+            lines.push(`- **${g.scope}** → ${g.target_ids?.length ? g.target_ids.join(", ") : "all"}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/tools/whatsapp/get-analytics.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    waba_id: z.ZodString;
+    flavor: z.ZodDefault<z.ZodEnum<["analytics", "conversation_analytics"]>>;
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    granularity: z.ZodDefault<z.ZodEnum<["HALF_HOUR", "DAY", "MONTH"]>>;
+    phone_numbers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    country_codes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    conversation_categories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    dimensions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    waba_id: string;
+    flavor: "analytics" | "conversation_analytics";
+    start: number;
+    end: number;
+    granularity: "HALF_HOUR" | "DAY" | "MONTH";
+    dimensions: string[];
+    phone_numbers?: string[] | undefined;
+    country_codes?: string[] | undefined;
+    conversation_categories?: string[] | undefined;
+}, {
+    waba_id: string;
+    start: number;
+    end: number;
+    flavor?: "analytics" | "conversation_analytics" | undefined;
+    granularity?: "HALF_HOUR" | "DAY" | "MONTH" | undefined;
+    phone_numbers?: string[] | undefined;
+    country_codes?: string[] | undefined;
+    conversation_categories?: string[] | undefined;
+    dimensions?: string[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_whatsapp_get_analytics";
+    readonly title: "Get WhatsApp Business analytics";
+    readonly description: "Fetches WABA analytics — either the legacy 'analytics' field (message counts) or the richer 'conversation_analytics' (per-conversation pricing, categories: AUTHENTICATION/MARKETING/SERVICE/UTILITY).\n\nPass start + end as Unix seconds. Use granularity DAY for most reports. Filter by phone_numbers, country_codes, or conversation_categories to narrow.";
+    readonly inputSchema: {
+        waba_id: z.ZodString;
+        flavor: z.ZodDefault<z.ZodEnum<["analytics", "conversation_analytics"]>>;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        granularity: z.ZodDefault<z.ZodEnum<["HALF_HOUR", "DAY", "MONTH"]>>;
+        phone_numbers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        country_codes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        conversation_categories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        dimensions: 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>;