@praise25/meta-mcp-server 0.1.0

package/dist/tools/pages/list-reviews.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>;
+    page_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    page_id: string;
+    after?: string | undefined;
+}, {
+    page_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_page_list_reviews";
+    readonly title: "List Page ratings / reviews";
+    readonly description: "Lists ratings and reviews (where the Page supports recommendations). Requires 'pages_read_user_content' scope. Useful for sentiment analysis and customer-experience reporting.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        page_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/pages/list-reviews.js

@@ -0,0 +1,37 @@
+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({
+    page_id: metaIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "created_time",
+        "reviewer",
+        "rating",
+        "recommendation_type",
+        "review_text",
+        "has_rating",
+        "has_review",
+        "open_graph_story",
+    ])
+        .describe("Review fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_page_list_reviews",
+    title: "List Page ratings / reviews",
+    description: `Lists ratings and reviews (where the Page supports recommendations). Requires 'pages_read_user_content' scope. Useful for sentiment analysis and customer-experience reporting.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    assertAllowed("page", input.page_id, ctx.config);
+    return runList(ctx, {
+        path: `${input.page_id}/ratings`,
+        params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { page_id: input.page_id });
+}

package/dist/tools/pages/list-videos.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>;
+    page_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    page_id: string;
+    after?: string | undefined;
+}, {
+    page_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_page_list_videos";
+    readonly title: "List Page videos";
+    readonly description: "Lists videos uploaded to a Page (including live broadcasts). Pair with meta_page_get_post_insights on the owning post for video-view analytics, or drill into individual video IDs for per-video metrics.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        page_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/pages/list-videos.js

@@ -0,0 +1,40 @@
+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({
+    page_id: metaIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "title",
+        "description",
+        "created_time",
+        "updated_time",
+        "length",
+        "permalink_url",
+        "source",
+        "status",
+        "views",
+        "live_status",
+    ])
+        .describe("Video fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_page_list_videos",
+    title: "List Page videos",
+    description: `Lists videos uploaded to a Page (including live broadcasts). Pair with meta_page_get_post_insights on the owning post for video-view analytics, or drill into individual video IDs for per-video metrics.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    assertAllowed("page", input.page_id, ctx.config);
+    return runList(ctx, {
+        path: `${input.page_id}/videos`,
+        params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { page_id: input.page_id });
+}

package/dist/tools/pages/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>;
+    source: z.ZodDefault<z.ZodEnum<["assigned", "accounts"]>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    limit: number;
+    auto_paginate: boolean;
+    source: "assigned" | "accounts";
+    after?: string | undefined;
+}, {
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    source?: "assigned" | "accounts" | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_page_list";
+    readonly title: "List Pages visible to the token";
+    readonly description: "Lists Facebook Pages this token/system-user can read. 'assigned' is the modern path for system users; 'accounts' is the classic /me/accounts edge (works for regular users).";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        source: z.ZodDefault<z.ZodEnum<["assigned", "accounts"]>>;
+        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/pages/list.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    source: z
+        .enum(["assigned", "accounts"])
+        .default("assigned")
+        .describe("'assigned' → /me/assigned_pages (system-user-specific). 'accounts' → /me/accounts (classic Pages edge)."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "category",
+        "category_list",
+        "about",
+        "fan_count",
+        "followers_count",
+        "verification_status",
+        "link",
+        "website",
+        "tasks",
+    ])
+        .describe("Page fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_page_list",
+    title: "List Pages visible to the token",
+    description: `Lists Facebook Pages this token/system-user can read. 'assigned' is the modern path for system users; 'accounts' is the classic /me/accounts edge (works for regular users).`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    const path = input.source === "assigned" ? "me/assigned_pages" : "me/accounts";
+    return runList(ctx, { path, params: { fields: input.fields.join(","), limit: input.limit, after: input.after } }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { source: input.source });
+}

package/dist/tools/pixels/get-stats.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    pixel_id: z.ZodString;
+    aggregation: z.ZodDefault<z.ZodEnum<["event", "browser_type", "device_os", "event_source", "url"]>>;
+    start_time: z.ZodOptional<z.ZodString>;
+    end_time: z.ZodOptional<z.ZodString>;
+    event: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    pixel_id: string;
+    aggregation: "url" | "event" | "browser_type" | "device_os" | "event_source";
+    start_time?: string | undefined;
+    end_time?: string | undefined;
+    event?: string | undefined;
+}, {
+    pixel_id: string;
+    start_time?: string | undefined;
+    end_time?: string | undefined;
+    event?: string | undefined;
+    aggregation?: "url" | "event" | "browser_type" | "device_os" | "event_source" | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_pixel_get_stats";
+    readonly title: "Get pixel event stats";
+    readonly description: "Reads aggregated pixel event counts via /{pixel_id}/stats. Use aggregation='event' to see which events are firing, 'device_os' or 'browser_type' to profile traffic, 'url' to see top-firing pages. Useful for spotting CAPI drop-off versus browser events.";
+    readonly inputSchema: {
+        pixel_id: z.ZodString;
+        aggregation: z.ZodDefault<z.ZodEnum<["event", "browser_type", "device_os", "event_source", "url"]>>;
+        start_time: z.ZodOptional<z.ZodString>;
+        end_time: z.ZodOptional<z.ZodString>;
+        event: z.ZodOptional<z.ZodString>;
+    };
+    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/get-stats.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { metaIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+const AGGREGATION = z.enum(["event", "browser_type", "device_os", "event_source", "url"]);
+export const inputSchema = z
+    .object({
+    pixel_id: metaIdSchema,
+    aggregation: AGGREGATION.default("event").describe("How to slice the stats."),
+    start_time: z.string().optional().describe("ISO date / Unix timestamp — start of window."),
+    end_time: z.string().optional().describe("ISO date / Unix timestamp — end of window."),
+    event: z
+        .string()
+        .optional()
+        .describe("Filter to one event name, e.g. 'Purchase', 'AddToCart'."),
+})
+    .strict();
+export const definition = {
+    name: "meta_pixel_get_stats",
+    title: "Get pixel event stats",
+    description: `Reads aggregated pixel event counts via /{pixel_id}/stats. Use aggregation='event' to see which events are firing, 'device_os' or 'browser_type' to profile traffic, 'url' to see top-firing pages. Useful for spotting CAPI drop-off versus browser events.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runGet(ctx, {
+        path: `${input.pixel_id}/stats`,
+        params: {
+            aggregation: input.aggregation,
+            start_time: input.start_time,
+            end_time: input.end_time,
+            event: input.event,
+        },
+    });
+}

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[];
+    limit: number;
+    auto_paginate: boolean;
+    business_id: string;
+    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,38 @@
+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([
+        "id",
+        "name",
+        "code",
+        "is_created_by_business",
+        "is_unavailable",
+        "last_fired_time",
+        "creation_time",
+        "owner_ad_account",
+        "owner_business",
+    ])
+        .describe("Pixel fields."),
+    ...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,82 @@
+// 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";
+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 (1)
+    businessOverview,
+].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) => {
+            return mod.handler(args, ctx);
+        }));
+        names.push(mod.definition.name);
+    }
+    return names;
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared helpers used across domain tools — keeps each tool file focused on
+ * its endpoint instead of re-implementing boilerplate.
+ */
+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>;
+export declare function errorResult(err: unknown): ToolTextResult;

package/dist/tools/shared.js

@@ -0,0 +1,55 @@
+import { MetaError } from "../errors.js";
+import { jsonBlock, toolError, toolResult } from "../helpers/format.js";
+/**
+ * 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);
+    }
+}
+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,
+    });
+}

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- 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.";
+    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,59 @@
+import { z } from "zod";
+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:
+- 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.`,
+    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,
+            latency_ms: Date.now() - started,
+            identity: me,
+            api_version: ctx.config.apiVersion,
+            appsecret_proof_enabled: Boolean(ctx.config.appSecret),
+            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,
+        });
+    }
+}