@praise25/meta-mcp-server 0.1.6 → 0.1.8

package/dist/constants.d.ts

@@ -4,7 +4,7 @@ export declare const CHARACTER_LIMIT = 25000;
 export declare const DEFAULT_PAGE_LIMIT = 25;
 export declare const MAX_PAGE_LIMIT = 500;
 export declare const SERVER_NAME = "meta-business-manager-mcp-server";
-export declare const SERVER_VERSION = "0.1.4";
+export declare const SERVER_VERSION = "0.1.8";
 export declare const META_ERROR_CODES: {
     readonly UNKNOWN: 1;
     readonly SERVICE_TEMPORARILY_UNAVAILABLE: 2;

package/dist/constants.js

@@ -4,7 +4,7 @@ export const CHARACTER_LIMIT = 25_000;
 export const DEFAULT_PAGE_LIMIT = 25;
 export const MAX_PAGE_LIMIT = 500;
 export const SERVER_NAME = "meta-business-manager-mcp-server";
-export const SERVER_VERSION = "0.1.4";
+export const SERVER_VERSION = "0.1.8";
 export const META_ERROR_CODES = {
     UNKNOWN: 1,
     SERVICE_TEMPORARILY_UNAVAILABLE: 2,

package/dist/helpers/validate.js

@@ -42,6 +42,49 @@ export function findPlaceholders(value, path = []) {
 function formatPath(p) {
     return p.length ? p.join(".") : "(root)";
 }
+/**
+ * Per-field recovery hints: when the AI passes a placeholder for a specific
+ * field, tell it the *exact* discovery tool that produces the right ID. This
+ * turns "I need your IG account ID" (which the AI then asks the user) into
+ * "call meta_ig_list_accounts (no args) to discover IG accounts" (which the
+ * AI can do autonomously).
+ *
+ * Each entry returns a single-sentence next-step the AI should execute.
+ */
+const FIELD_RECOVERY = {
+    business_id: "Call `meta_business_list` (no args) to discover Business Manager IDs. The configured business is `133767790806312` (Hodusoft) — use that directly if you already know.",
+    ad_account_id: "Call `meta_ads_list_accounts business_id=133767790806312` to discover ad accounts. Returns IDs in the `act_<digits>` form (e.g. `act_146517954996436`).",
+    page_id: "Call `meta_page_list` (no args, defaults to source='assigned') to discover Pages assigned to the configured token.",
+    ig_user_id: "Call `meta_ig_list_accounts` (no args) to discover Instagram Business accounts linked to your Pages. No parameters required.",
+    pixel_id: "Call `meta_pixel_list business_id=133767790806312` to discover pixels.",
+    catalog_id: "Call `meta_catalog_list business_id=133767790806312 scope='owned'` to discover catalogs.",
+    waba_id: "Call `meta_whatsapp_list_wabas business_id=133767790806312` to discover WhatsApp Business Accounts.",
+    media_id: "Call `meta_ig_list_media ig_user_id=<ig_id>` to discover media. Use `meta_ig_list_accounts` first if you don't have ig_id.",
+    creative_id: "Call `meta_ads_list_ads ad_account_id=act_<id>` to discover creatives. Each ad's `creative.id` is the value you want.",
+    campaign_id: "Call `meta_ads_list_campaigns ad_account_id=act_<id>` to discover campaign IDs.",
+    adset_id: "Call `meta_ads_list_adsets ad_account_id=act_<id>` to discover ad-set IDs.",
+    post_id: "Call `meta_page_list_posts page_id=<page_id>` to discover post IDs. Post IDs use the `{page_id}_{post_id}` format.",
+    object_id: "Pass an ad account (`act_<digits>`), campaign, ad-set, or ad ID. Use `meta_business_overview business_id=133767790806312` to discover all of these in one call.",
+};
+/** Build a numbered recovery action list keyed off the placeholder field names. */
+function buildRecoveryActions(placeholders) {
+    const fields = new Set();
+    for (const p of placeholders) {
+        const top = p.path[0];
+        if (typeof top === "string")
+            fields.add(top);
+    }
+    const lines = [];
+    for (const f of fields) {
+        const recovery = FIELD_RECOVERY[f];
+        if (recovery)
+            lines.push(`• ${f}: ${recovery}`);
+    }
+    if (lines.length === 0) {
+        return "Replace the placeholder values with real IDs. If you don't know the IDs, call `meta_business_overview business_id=133767790806312` first to discover everything in one call.";
+    }
+    return `DO NOT ask the user for these IDs — the server can discover them for you. Replace each placeholder by first calling the corresponding discovery tool:\n${lines.join("\n")}\n\nShortcut: a single call to \`meta_business_overview business_id=133767790806312\` returns all Pages, IG accounts, ad accounts, pixels, catalogs, and WABAs at once. Prefer that when several placeholders appear together.`;
+}
 /**
  * Defence-in-depth input validator. Wraps a Zod object schema and:
  *   1. Detects placeholder strings (e.g. literal "<YOUR_PAGE_ID>") with a
@@ -62,7 +105,7 @@ export function validateInput(schema, args) {
             .join("; ");
         return {
             ok: false,
-            error: toolError(`Input contains placeholder values that were not substituted: ${summary}`, `Replace placeholders with real IDs / values before retrying. Examples for this server: business_id "133767790806312"; ad_account_id "act_146517954996436"; page_id "138368686823692". If you don't know the correct ID, call meta_business_list_assets first to discover available assets.`, { placeholders }),
+            error: toolError(`Input contains placeholder values that were not substituted: ${summary}`, buildRecoveryActions(placeholders), { placeholders, recovery_actions: buildRecoveryActions(placeholders) }),
         };
     }
     const parsed = schema.safeParse(args);

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

@@ -37,9 +37,9 @@ export declare const inputSchema: z.ZodObject<{
     sort: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    object_id: string;
     limit: number;
     auto_paginate: boolean;
-    object_id: string;
     level: "account" | "campaign" | "adset" | "ad";
     date_preset: "today" | "yesterday" | "this_month" | "last_month" | "this_quarter" | "maximum" | "last_3d" | "last_7d" | "last_14d" | "last_28d" | "last_30d" | "last_90d" | "last_week_mon_sun" | "last_week_sun_sat" | "last_quarter" | "last_year" | "this_week_mon_today" | "this_week_sun_today" | "this_year";
     sort?: string[] | undefined;

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

@@ -9,9 +9,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    business_id: string;
     limit: number;
     auto_paginate: boolean;
-    business_id: string;
     scope: "owned" | "client" | "both";
     after?: string | undefined;
 }, {

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

@@ -11,22 +11,22 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    ad_account_id: string;
     limit: number;
     auto_paginate: boolean;
-    ad_account_id: string;
-    after?: string | undefined;
-    effective_status?: string[] | undefined;
     campaign_id?: string | undefined;
     adset_id?: string | undefined;
+    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;
-    campaign_id?: string | undefined;
-    adset_id?: string | undefined;
 }>;
 export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {

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

@@ -10,20 +10,20 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    ad_account_id: string;
     limit: number;
     auto_paginate: boolean;
-    ad_account_id: string;
+    campaign_id?: string | undefined;
     after?: string | undefined;
     effective_status?: string[] | undefined;
-    campaign_id?: 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;
-    campaign_id?: string | undefined;
 }>;
 export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {

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

@@ -9,9 +9,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    ad_account_id: string;
     limit: number;
     auto_paginate: boolean;
-    ad_account_id: string;
     after?: string | undefined;
     effective_status?: ("ACTIVE" | "PAUSED" | "DELETED" | "PENDING_REVIEW" | "DISAPPROVED" | "PREAPPROVED" | "PENDING_BILLING_INFO" | "CAMPAIGN_PAUSED" | "ARCHIVED" | "IN_PROCESS" | "WITH_ISSUES")[] | undefined;
 }, {

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

@@ -8,9 +8,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    ad_account_id: string;
     limit: number;
     auto_paginate: boolean;
-    ad_account_id: string;
     after?: string | undefined;
 }, {
     ad_account_id: string;

package/dist/tools/business/list-system-users.d.ts

@@ -8,9 +8,9 @@ export declare const inputSchema: z.ZodObject<{
     business_id: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    business_id: string;
     limit: number;
     auto_paginate: boolean;
-    business_id: string;
     after?: string | undefined;
 }, {
     business_id: string;

package/dist/tools/catalog/list-products.d.ts

@@ -9,9 +9,9 @@ export declare const inputSchema: z.ZodObject<{
     filter: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    catalog_id: string;
     limit: number;
     auto_paginate: boolean;
-    catalog_id: string;
     filter?: string | undefined;
     after?: string | undefined;
 }, {

package/dist/tools/catalog/list.d.ts

@@ -9,9 +9,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    business_id: string;
     limit: number;
     auto_paginate: boolean;
-    business_id: string;
     scope: "owned" | "client" | "both";
     after?: string | undefined;
 }, {

package/dist/tools/instagram/get-audience-demographics.d.ts

@@ -7,8 +7,8 @@ export declare const inputSchema: z.ZodObject<{
     metric_type: z.ZodDefault<z.ZodEnum<["total_value", "time_series"]>>;
     timeframe: z.ZodDefault<z.ZodEnum<["last_14_days", "last_30_days", "last_90_days", "prev_month", "this_month", "this_week"]>>;
 }, "strict", z.ZodTypeAny, {
-    metric: "follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics";
     ig_user_id: string;
+    metric: "follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics";
     breakdown: "age" | "gender" | "country" | "city" | "audience_city";
     metric_type: "total_value" | "time_series";
     timeframe: "this_month" | "last_14_days" | "last_30_days" | "last_90_days" | "prev_month" | "this_week";

package/dist/tools/instagram/get-media-insights.d.ts

@@ -4,8 +4,8 @@ export declare const inputSchema: z.ZodObject<{
     media_id: z.ZodString;
     metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
-    metrics: string[];
     media_id: string;
+    metrics: string[];
 }, {
     media_id: string;
     metrics?: string[] | undefined;

package/dist/tools/instagram/list-media.d.ts

@@ -8,9 +8,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    ig_user_id: string;
     limit: number;
     auto_paginate: boolean;
-    ig_user_id: string;
     after?: string | undefined;
 }, {
     ig_user_id: string;

package/dist/tools/overview/business-overview.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import type { ToolContext } from "../../context.js";
 export declare const inputSchema: z.ZodObject<{
-    business_id: z.ZodString;
+    business_id: z.ZodOptional<z.ZodString>;
     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"]>>;
     include_pixels: z.ZodDefault<z.ZodBoolean>;
     include_catalogs: z.ZodDefault<z.ZodBoolean>;
@@ -9,15 +9,15 @@ export declare const inputSchema: z.ZodObject<{
     max_ad_accounts: z.ZodDefault<z.ZodNumber>;
     max_pages: z.ZodDefault<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
-    business_id: string;
     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";
     include_pixels: boolean;
     include_catalogs: boolean;
     include_whatsapp: boolean;
     max_ad_accounts: number;
     max_pages: number;
+    business_id?: string | undefined;
 }, {
-    business_id: string;
+    business_id?: string | 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;
     include_pixels?: boolean | undefined;
     include_catalogs?: boolean | undefined;
@@ -31,7 +31,7 @@ export declare const definition: {
     readonly title: "Eagle's-eye snapshot of a business";
     readonly description: "One-call consolidated read across the whole Meta surface for a business:\n\n- Identity (system user + token app)\n- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window\n- Instagram Business accounts linked to those Pages (followers, media_count)\n- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)\n- Pixels with last_fired_time (if include_pixels)\n- Catalogs with product counts (if include_catalogs)\n- WhatsApp Business Accounts + phone numbers (if include_whatsapp)\n\nEach section has its own error isolation — one failing asset does not kill the report. Ideal as the opening call for any AI-driven marketing insights conversation.";
     readonly inputSchema: {
-        business_id: z.ZodString;
+        business_id: z.ZodOptional<z.ZodString>;
         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"]>>;
         include_pixels: z.ZodDefault<z.ZodBoolean>;
         include_catalogs: z.ZodDefault<z.ZodBoolean>;

package/dist/tools/overview/business-overview.js

@@ -5,7 +5,9 @@ import { jsonBlock, toolResult } from "../../helpers/format.js";
 import { datePresetSchema, metaIdSchema } from "../../helpers/schema.js";
 export const inputSchema = z
     .object({
-    business_id: metaIdSchema.describe("Business Manager ID."),
+    business_id: metaIdSchema
+        .optional()
+        .describe("Business Manager ID. **Optional** — if omitted, the server auto-discovers via `META_ALLOWED_BUSINESS_IDS[0]` (if configured) or the first business returned by `/me/businesses`. Always prefer omitting this if you don't have the exact ID — do not guess a placeholder integer."),
     date_preset: datePresetSchema
         .default("last_30d")
         .describe("Date window used for ad account and page insights snapshots."),
@@ -41,8 +43,43 @@ function fail(err) {
     return { ok: false, error: e.message, hint: e.hint };
 }
 export async function handler(input, ctx) {
-    assertAllowed("business", input.business_id, ctx.config);
     const started = Date.now();
+    // Auto-discover business_id if not provided. Prefer the configured allowlist
+    // (deployment intent), fall back to /me/businesses. This makes the tool
+    // safe to call with no args — defeats AI-hallucinated-id failure modes.
+    let businessId = input.business_id;
+    let businessIdSource = "input";
+    if (!businessId) {
+        const allowed = ctx.config.allowedBusinessIds;
+        if (allowed && allowed.size > 0) {
+            businessId = allowed.values().next().value;
+            businessIdSource = "allowlist";
+        }
+        else {
+            try {
+                const list = await ctx.graph.get({
+                    path: "me/businesses",
+                    params: { fields: "id,name", limit: 1 },
+                });
+                const first = list.data?.[0];
+                if (first?.id) {
+                    businessId = first.id;
+                    businessIdSource = "discovered";
+                }
+            }
+            catch {
+                /* fall through — businessId remains undefined and structured response will surface the gap */
+            }
+        }
+    }
+    if (!businessId) {
+        return toolResult({
+            error: "no_business_id",
+            hint: "Could not determine business_id. Configure META_ALLOWED_BUSINESS_IDS in the server's environment, or pass business_id explicitly. /me/businesses returned no results for the configured token (this is normal for system-user tokens — they don't list businesses via that edge).",
+            suggestion: "Pass business_id directly. To discover it, an operator should run `meta_business_list_assets business_id=<known>` once with a known ID, or look up the business in Business Settings → Business Info.",
+        }, "{}");
+    }
+    assertAllowed("business", businessId, ctx.config);
     const token = ctx.graph.get({
         path: "debug_token",
         params: { input_token: ctx.config.accessToken },
@@ -60,14 +97,14 @@ export async function handler(input, ctx) {
         .catch(fail);
     const ownedAds = ctx.graph
         .get({
-        path: `${input.business_id}/owned_ad_accounts`,
+        path: `${businessId}/owned_ad_accounts`,
         params: { fields: "id,account_id,name,currency,account_status,amount_spent,balance,spend_cap", limit: input.max_ad_accounts },
     })
         .then(ok)
         .catch(fail);
     const clientAds = ctx.graph
         .get({
-        path: `${input.business_id}/client_ad_accounts`,
+        path: `${businessId}/client_ad_accounts`,
         params: { fields: "id,account_id,name,currency,account_status", limit: input.max_ad_accounts },
     })
         .then(ok)
@@ -75,7 +112,7 @@ export async function handler(input, ctx) {
     const pixels = input.include_pixels
         ? ctx.graph
             .get({
-            path: `${input.business_id}/owned_pixels`,
+            path: `${businessId}/owned_pixels`,
             params: { fields: "id,name,last_fired_time,is_unavailable", limit: 25 },
         })
             .then(ok)
@@ -84,7 +121,7 @@ export async function handler(input, ctx) {
     const catalogs = input.include_catalogs
         ? ctx.graph
             .get({
-            path: `${input.business_id}/owned_product_catalogs`,
+            path: `${businessId}/owned_product_catalogs`,
             params: { fields: "id,name,vertical,product_count", limit: 25 },
         })
             .then(ok)
@@ -93,7 +130,7 @@ export async function handler(input, ctx) {
     const wabas = input.include_whatsapp
         ? ctx.graph
             .get({
-            path: `${input.business_id}/owned_whatsapp_business_accounts`,
+            path: `${businessId}/owned_whatsapp_business_accounts`,
             params: { fields: "id,name,currency,status,business_verification_status", limit: 25 },
         })
             .then(ok)
@@ -180,7 +217,8 @@ export async function handler(input, ctx) {
         };
     }));
     const structured = {
-        business_id: input.business_id,
+        business_id: businessId,
+        business_id_source: businessIdSource,
         date_preset: input.date_preset,
         generated_at: new Date().toISOString(),
         latency_ms: Date.now() - started,

package/dist/tools/overview/latest-posts-summary.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    include_instagram: z.ZodDefault<z.ZodBoolean>;
+    include_facebook: z.ZodDefault<z.ZodBoolean>;
+    max_pages: z.ZodDefault<z.ZodNumber>;
+    include_post_insights: z.ZodDefault<z.ZodBoolean>;
+    include_media_insights: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    max_pages: number;
+    include_instagram: boolean;
+    include_facebook: boolean;
+    include_post_insights: boolean;
+    include_media_insights: boolean;
+}, {
+    max_pages?: number | undefined;
+    include_instagram?: boolean | undefined;
+    include_facebook?: boolean | undefined;
+    include_post_insights?: boolean | undefined;
+    include_media_insights?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_latest_posts_summary";
+    readonly title: "Latest post performance across every social account";
+    readonly description: "Workflow tool that answers \"how did my latest post on each social account perform?\" in a single call.\n\nInternally walks:\n1. /me/assigned_pages → every Facebook Page assigned to this token\n2. For each Page: latest published post + (optionally) its insights (impressions, reach, engaged_users, clicks)\n3. For each Page: linked instagram_business_account\n4. For each IG: latest media + (optionally) its insights (reach, views, likes, comments, shares, saved, total_interactions)\n\nReturns a unified array of '{platform, owner, latest_post, insights}' entries, plus a per-section error map so a single failure doesn't blank the report.\n\n**Use this as the FIRST tool call** when the user asks anything like:\n- \"How are my social media accounts performing?\"\n- \"What's the engagement on my latest posts?\"\n- \"How did my most recent content do?\"\n\nIt removes the need to discover Page / IG IDs separately, and avoids the N+1 sequence of meta_page_list → meta_page_list_posts → meta_page_get_post_insights × pages × posts.";
+    readonly inputSchema: {
+        include_instagram: z.ZodDefault<z.ZodBoolean>;
+        include_facebook: z.ZodDefault<z.ZodBoolean>;
+        max_pages: z.ZodDefault<z.ZodNumber>;
+        include_post_insights: z.ZodDefault<z.ZodBoolean>;
+        include_media_insights: 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>;

package/dist/tools/overview/latest-posts-summary.js

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolResult } from "../../helpers/format.js";
+export const inputSchema = z
+    .object({
+    include_instagram: z
+        .boolean()
+        .default(true)
+        .describe("Walk linked Instagram Business accounts via assigned Pages and include their latest media."),
+    include_facebook: z
+        .boolean()
+        .default(true)
+        .describe("Walk assigned Facebook Pages and include their latest post."),
+    max_pages: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .default(10)
+        .describe("Cap on Pages walked. Each Page is one extra Graph call to fetch latest post + insights."),
+    include_post_insights: z
+        .boolean()
+        .default(true)
+        .describe("Include per-post insights (impressions, reach, engaged users). Disable to halve the Graph calls."),
+    include_media_insights: z
+        .boolean()
+        .default(true)
+        .describe("Include per-IG-media insights (reach, views, likes). Disable if your app lacks instagram_manage_insights Standard Access."),
+})
+    .strict();
+export const definition = {
+    name: "meta_latest_posts_summary",
+    title: "Latest post performance across every social account",
+    description: `Workflow tool that answers "how did my latest post on each social account perform?" in a single call.
+
+Internally walks:
+1. /me/assigned_pages → every Facebook Page assigned to this token
+2. For each Page: latest published post + (optionally) its insights (impressions, reach, engaged_users, clicks)
+3. For each Page: linked instagram_business_account
+4. For each IG: latest media + (optionally) its insights (reach, views, likes, comments, shares, saved, total_interactions)
+
+Returns a unified array of '{platform, owner, latest_post, insights}' entries, plus a per-section error map so a single failure doesn't blank the report.
+
+**Use this as the FIRST tool call** when the user asks anything like:
+- "How are my social media accounts performing?"
+- "What's the engagement on my latest posts?"
+- "How did my most recent content do?"
+
+It removes the need to discover Page / IG IDs separately, and avoids the N+1 sequence of meta_page_list → meta_page_list_posts → meta_page_get_post_insights × pages × posts.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    const started = Date.now();
+    const entries = [];
+    const errors = {};
+    // Step 1: list assigned Pages (used by both Facebook and Instagram paths).
+    let pages = [];
+    try {
+        const pagesResp = await ctx.graph.get({
+            path: "me/assigned_pages",
+            params: { fields: "id,name", limit: input.max_pages },
+        });
+        pages = Array.isArray(pagesResp.data) ? pagesResp.data : [];
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        errors["assigned_pages"] = { error: e.message, hint: e.hint };
+    }
+    // Step 2: for each Page, fetch latest published post + insights (in parallel).
+    if (input.include_facebook && pages.length > 0) {
+        const fbResults = await Promise.all(pages.map(async (p) => {
+            try {
+                const pageToken = await ctx.graph.getPageAccessToken(p.id);
+                const postsPage = await ctx.graph.get({
+                    path: `${p.id}/published_posts`,
+                    params: {
+                        fields: "id,message,created_time,permalink_url,status_type,attachments{media_type,title,url},reactions.summary(true).limit(0),shares,comments.summary(true).limit(0)",
+                        limit: 1,
+                    },
+                    accessTokenOverride: pageToken,
+                });
+                const latest = postsPage.data?.[0] ?? null;
+                let insights = null;
+                if (latest && input.include_post_insights) {
+                    try {
+                        const insResp = await ctx.graph.get({
+                            path: `${latest.id}/insights`,
+                            params: {
+                                metric: "post_impressions,post_impressions_unique,post_engaged_users,post_clicks,post_reactions_by_type_total",
+                            },
+                            accessTokenOverride: pageToken,
+                        });
+                        insights = { data: insResp.data ?? [] };
+                    }
+                    catch (err) {
+                        const e = err instanceof MetaError ? err : new MetaError(err.message);
+                        insights = { error: e.message, hint: e.hint };
+                    }
+                }
+                return {
+                    platform: "facebook",
+                    page_id: p.id,
+                    page_name: p.name,
+                    latest_post: latest,
+                    insights,
+                };
+            }
+            catch (err) {
+                const e = err instanceof MetaError ? err : new MetaError(err.message);
+                return {
+                    platform: "facebook",
+                    page_id: p.id,
+                    page_name: p.name,
+                    latest_post: null,
+                    insights: { error: e.message, hint: e.hint },
+                };
+            }
+        }));
+        entries.push(...fbResults);
+    }
+    // Step 3: resolve IG via each Page, then fetch latest media + insights.
+    if (input.include_instagram && pages.length > 0) {
+        const igLinks = await Promise.all(pages.map(async (p) => {
+            try {
+                const d = await ctx.graph.get({
+                    path: p.id,
+                    params: { fields: "id,name,instagram_business_account{id,username,name}" },
+                });
+                return d.instagram_business_account
+                    ? { ig: d.instagram_business_account, sourcePage: p }
+                    : null;
+            }
+            catch {
+                return null;
+            }
+        }));
+        const igAccounts = igLinks.filter((x) => x !== null);
+        const igResults = await Promise.all(igAccounts.map(async (link) => {
+            try {
+                const mediaPage = await ctx.graph.get({
+                    path: `${link.ig.id}/media`,
+                    params: {
+                        fields: "id,media_type,media_product_type,caption,media_url,thumbnail_url,permalink,timestamp,like_count,comments_count",
+                        limit: 1,
+                    },
+                });
+                const latest = mediaPage.data?.[0] ?? null;
+                let insights = null;
+                if (latest && input.include_media_insights) {
+                    try {
+                        const insResp = await ctx.graph.get({
+                            path: `${latest.id}/insights`,
+                            params: { metric: "reach,views,likes,comments,shares,saved,total_interactions" },
+                        });
+                        insights = { data: insResp.data ?? [] };
+                    }
+                    catch (err) {
+                        const e = err instanceof MetaError ? err : new MetaError(err.message);
+                        insights = { error: e.message, hint: e.hint };
+                    }
+                }
+                return {
+                    platform: "instagram",
+                    ig_user_id: link.ig.id,
+                    ig_username: link.ig.username,
+                    page_id: link.sourcePage.id,
+                    page_name: link.sourcePage.name,
+                    latest_post: latest,
+                    insights,
+                };
+            }
+            catch (err) {
+                const e = err instanceof MetaError ? err : new MetaError(err.message);
+                return {
+                    platform: "instagram",
+                    ig_user_id: link.ig.id,
+                    ig_username: link.ig.username,
+                    latest_post: null,
+                    insights: { error: e.message, hint: e.hint },
+                };
+            }
+        }));
+        entries.push(...igResults);
+    }
+    const structured = {
+        generated_at: new Date().toISOString(),
+        latency_ms: Date.now() - started,
+        facebook_count: entries.filter((e) => e.platform === "facebook").length,
+        instagram_count: entries.filter((e) => e.platform === "instagram").length,
+        entries,
+        errors: Object.keys(errors).length > 0 ? errors : null,
+    };
+    return toolResult(structured, jsonBlock(structured));
+}

package/dist/tools/pages/list-posts.d.ts

@@ -11,10 +11,10 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    page_id: string;
     limit: number;
     auto_paginate: boolean;
     edge: "posts" | "published_posts" | "feed";
-    page_id: string;
     since?: string | undefined;
     until?: string | undefined;
     after?: string | undefined;

package/dist/tools/pages/list-reviews.d.ts

@@ -8,9 +8,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    page_id: string;
     limit: number;
     auto_paginate: boolean;
-    page_id: string;
     after?: string | undefined;
 }, {
     page_id: string;

package/dist/tools/pages/list-videos.d.ts

@@ -8,9 +8,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    page_id: string;
     limit: number;
     auto_paginate: boolean;
-    page_id: string;
     after?: string | undefined;
 }, {
     page_id: string;

package/dist/tools/pixels/list.d.ts

@@ -8,9 +8,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    business_id: string;
     limit: number;
     auto_paginate: boolean;
-    business_id: string;
     after?: string | undefined;
 }, {
     business_id: string;

package/dist/tools/register.js

@@ -45,6 +45,7 @@ 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";
 const TOOLS = [
     // Token + meta (3)
     tokenInspect, tokenHealth, graphRead,
@@ -64,8 +65,8 @@ const TOOLS = [
     catalogList, catalogListProducts, catalogGetDiagnostics,
     // WhatsApp (4)
     whatsappListWabas, whatsappListPhoneNumbers, whatsappListTemplates, whatsappGetAnalytics,
-    // Overview (1)
-    businessOverview,
+    // Overview (2)
+    businessOverview, latestPostsSummary,
 ].map((m) => m);
 export function registerTools(server, ctx) {
     const names = [];

package/dist/tools/whatsapp/list-phone-numbers.d.ts

@@ -8,9 +8,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    waba_id: string;
     limit: number;
     auto_paginate: boolean;
-    waba_id: string;
     after?: string | undefined;
 }, {
     waba_id: string;

package/dist/tools/whatsapp/list-templates.d.ts

@@ -9,9 +9,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    waba_id: string;
     limit: number;
     auto_paginate: boolean;
-    waba_id: string;
     status?: "PAUSED" | "DELETED" | "APPROVED" | "PENDING" | "REJECTED" | "DISABLED" | "IN_APPEAL" | undefined;
     after?: string | undefined;
 }, {

package/dist/tools/whatsapp/list-wabas.d.ts

@@ -9,9 +9,9 @@ export declare const inputSchema: z.ZodObject<{
     fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     fields: string[];
+    business_id: string;
     limit: number;
     auto_paginate: boolean;
-    business_id: string;
     scope: "owned" | "client" | "both";
     after?: string | undefined;
 }, {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@praise25/meta-mcp-server",
   "description": "Read-only Model Context Protocol server for Meta Business Manager — Pages, Instagram, Ads insights, Pixels, Catalog, WhatsApp.",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "author": "Stephen A.",
   "license": "MIT",
   "homepage": "https://github.com/feladeveloper/meta-mcp-server#readme",