@praise25/meta-mcp-server 0.1.7 → 0.1.10

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."),
@@ -19,16 +21,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_overview",
     title: "Eagle's-eye snapshot of a business",
-    description: `One-call consolidated read across the whole Meta surface for a business:
-
-- Identity (system user + token app)
-- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
-- Instagram Business accounts linked to those Pages (followers, media_count)
-- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
-- Pixels with last_fired_time (if include_pixels)
-- Catalogs with product counts (if include_catalogs)
-- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
-
+    description: `One-call consolidated read across the whole Meta surface for a business:
+
+- Identity (system user + token app)
+- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
+- Instagram Business accounts linked to those Pages (followers, media_count)
+- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
+- Pixels with last_fired_time (if include_pixels)
+- Catalogs with product counts (if include_catalogs)
+- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
+
 Each 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.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -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/content-report.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    date_preset: z.ZodDefault<z.ZodEnum<["last_7d", "last_14d", "last_28d", "last_30d", "last_90d"]>>;
+    since: z.ZodOptional<z.ZodString>;
+    until: z.ZodOptional<z.ZodString>;
+    include_facebook: z.ZodDefault<z.ZodBoolean>;
+    include_instagram: z.ZodDefault<z.ZodBoolean>;
+    include_insights: z.ZodDefault<z.ZodBoolean>;
+    insights_top_n: z.ZodDefault<z.ZodNumber>;
+    max_pages: z.ZodDefault<z.ZodNumber>;
+    max_posts_per_account: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    date_preset: "last_7d" | "last_14d" | "last_28d" | "last_30d" | "last_90d";
+    max_pages: number;
+    include_instagram: boolean;
+    include_facebook: boolean;
+    include_insights: boolean;
+    insights_top_n: number;
+    max_posts_per_account: number;
+    since?: string | undefined;
+    until?: string | undefined;
+}, {
+    since?: string | undefined;
+    until?: string | undefined;
+    date_preset?: "last_7d" | "last_14d" | "last_28d" | "last_30d" | "last_90d" | undefined;
+    max_pages?: number | undefined;
+    include_instagram?: boolean | undefined;
+    include_facebook?: boolean | undefined;
+    include_insights?: boolean | undefined;
+    insights_top_n?: number | undefined;
+    max_posts_per_account?: number | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_content_report";
+    readonly title: "Content report: how many posts over a period, by type, with engagement & comparison";
+    readonly description: "One-call content-performance report over a TIME WINDOW (default last 7 days / this week) across all Facebook Pages and Instagram accounts.\n\nUSE FOR questions like:\n- \"How many posts have gone up in the last week / 7 days / this month?\"\n- \"Classify my posts by type (photo / video / reel / carousel).\"\n- \"Compare Facebook vs Instagram content performance.\"\n- \"Which post type drives the most engagement?\"\n- \"Give me a weekly content report / performance comparison.\"\n\nNOT FOR: a single most-recent post → use meta_latest_posts_summary. A whole-business snapshot (ads + pages + pixels) → use meta_business_overview. Audience age/gender/country demographics → use meta_ig_get_audience_demographics (account-level, not per-post).\n\nReturns, in one call:\n- Total post count in the window, per platform (Facebook / Instagram)\n- Breakdown by post type (photo, video, reel, carousel, link, status) with count + total/avg engagement per type\n- Top posts by engagement\n- A Facebook-vs-Instagram comparison block ready for the AI to narrate\n- Optional per-post reach/views (include_insights=true)\n\nEngagement counts (likes, comments, shares, reactions) are ALWAYS included — they come free with the post list. Reach/views/impressions need include_insights=true (one extra call per post, capped).\n\nWalks /me/assigned_pages → Page published_posts in the window, and the linked Instagram accounts → media filtered to the window. Per-section error isolation: one failing account never blanks the report.";
+    readonly inputSchema: {
+        date_preset: z.ZodDefault<z.ZodEnum<["last_7d", "last_14d", "last_28d", "last_30d", "last_90d"]>>;
+        since: z.ZodOptional<z.ZodString>;
+        until: z.ZodOptional<z.ZodString>;
+        include_facebook: z.ZodDefault<z.ZodBoolean>;
+        include_instagram: z.ZodDefault<z.ZodBoolean>;
+        include_insights: z.ZodDefault<z.ZodBoolean>;
+        insights_top_n: z.ZodDefault<z.ZodNumber>;
+        max_pages: z.ZodDefault<z.ZodNumber>;
+        max_posts_per_account: z.ZodDefault<z.ZodNumber>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/overview/content-report.js

@@ -0,0 +1,318 @@
+import { z } from "zod";
+import { insightsCreds } from "../../config.js";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolResult } from "../../helpers/format.js";
+/**
+ * Window presets → number of days back from now. Kept friendly so the AI can
+ * pass the same vocabulary users type ("last 7 days", "this week").
+ */
+const WINDOW_DAYS = {
+    last_7d: 7,
+    last_14d: 14,
+    last_28d: 28,
+    last_30d: 30,
+    last_90d: 90,
+};
+export const inputSchema = z
+    .object({
+    date_preset: z
+        .enum(["last_7d", "last_14d", "last_28d", "last_30d", "last_90d"])
+        .default("last_7d")
+        .describe("Time window for the report. 'last_7d' = the last 7 days / this week (default). Overridden by since/until if those are supplied."),
+    since: z
+        .string()
+        .optional()
+        .describe("Explicit window start, ISO date e.g. '2026-05-01'. Overrides date_preset."),
+    until: z
+        .string()
+        .optional()
+        .describe("Explicit window end, ISO date e.g. '2026-05-31'. Defaults to now."),
+    include_facebook: z.boolean().default(true).describe("Include Facebook Page posts."),
+    include_instagram: z.boolean().default(true).describe("Include Instagram media."),
+    include_insights: z
+        .boolean()
+        .default(false)
+        .describe("Also fetch per-post reach/views/impressions for the top posts (capped by insights_top_n). Off by default because it costs one Graph call per post; engagement counts (likes/comments/shares/reactions) are ALWAYS included for free regardless."),
+    insights_top_n: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .default(5)
+        .describe("When include_insights=true, how many top-engagement posts per platform to fetch insights for."),
+    max_pages: z.number().int().min(1).max(20).default(10).describe("Cap on Pages walked."),
+    max_posts_per_account: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .default(100)
+        .describe("Cap on posts fetched per account before classifying."),
+})
+    .strict();
+export const definition = {
+    name: "meta_content_report",
+    title: "Content report: how many posts over a period, by type, with engagement & comparison",
+    description: `One-call content-performance report over a TIME WINDOW (default last 7 days / this week) across all Facebook Pages and Instagram accounts.
+
+USE FOR questions like:
+- "How many posts have gone up in the last week / 7 days / this month?"
+- "Classify my posts by type (photo / video / reel / carousel)."
+- "Compare Facebook vs Instagram content performance."
+- "Which post type drives the most engagement?"
+- "Give me a weekly content report / performance comparison."
+
+NOT FOR: a single most-recent post → use meta_latest_posts_summary. A whole-business snapshot (ads + pages + pixels) → use meta_business_overview. Audience age/gender/country demographics → use meta_ig_get_audience_demographics (account-level, not per-post).
+
+Returns, in one call:
+- Total post count in the window, per platform (Facebook / Instagram)
+- Breakdown by post type (photo, video, reel, carousel, link, status) with count + total/avg engagement per type
+- Top posts by engagement
+- A Facebook-vs-Instagram comparison block ready for the AI to narrate
+- Optional per-post reach/views (include_insights=true)
+
+Engagement counts (likes, comments, shares, reactions) are ALWAYS included — they come free with the post list. Reach/views/impressions need include_insights=true (one extra call per post, capped).
+
+Walks /me/assigned_pages → Page published_posts in the window, and the linked Instagram accounts → media filtered to the window. Per-section error isolation: one failing account never blanks the report.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+/** Normalize a Facebook post into a type + engagement total. */
+function classifyFacebook(post) {
+    const statusType = String(post.status_type ?? "");
+    const attachments = post.attachments;
+    const mediaType = attachments?.data?.[0]?.media_type ?? "";
+    let type = "status";
+    if (mediaType === "photo" || statusType === "added_photos")
+        type = "photo";
+    else if (mediaType === "video" || statusType === "added_video")
+        type = "video";
+    else if (mediaType === "album")
+        type = "carousel";
+    else if (mediaType === "link" || statusType === "shared_story")
+        type = "link";
+    else if (statusType === "mobile_status_update")
+        type = "status";
+    const reactions = post.reactions?.summary?.total_count ?? 0;
+    const comments = post.comments?.summary?.total_count ?? 0;
+    const shares = post.shares?.count ?? 0;
+    const breakdown = { reactions, comments, shares };
+    return { type, engagement: reactions + comments + shares, breakdown };
+}
+/** Normalize an Instagram media into a type + engagement total. */
+function classifyInstagram(media) {
+    const mediaType = String(media.media_type ?? "");
+    const productType = String(media.media_product_type ?? "");
+    let type = "image";
+    if (productType === "REELS")
+        type = "reel";
+    else if (mediaType === "VIDEO")
+        type = "video";
+    else if (mediaType === "CAROUSEL_ALBUM")
+        type = "carousel";
+    else if (mediaType === "IMAGE")
+        type = "image";
+    const likes = Number(media.like_count ?? 0);
+    const comments = Number(media.comments_count ?? 0);
+    const breakdown = { likes, comments };
+    return { type, engagement: likes + comments, breakdown };
+}
+function aggregate(posts) {
+    const byType = {};
+    let totalEngagement = 0;
+    for (const p of posts) {
+        (byType[p.type] ??= { count: 0, engagement: 0 });
+        byType[p.type].count += 1;
+        byType[p.type].engagement += p.engagement;
+        totalEngagement += p.engagement;
+    }
+    const byTypeOut = Object.fromEntries(Object.entries(byType).map(([t, v]) => [
+        t,
+        { count: v.count, total_engagement: v.engagement, avg_engagement: Math.round((v.engagement / v.count) * 10) / 10 },
+    ]));
+    return {
+        total_posts: posts.length,
+        total_engagement: totalEngagement,
+        avg_engagement_per_post: posts.length ? Math.round((totalEngagement / posts.length) * 10) / 10 : 0,
+        by_type: byTypeOut,
+    };
+}
+export async function handler(input, ctx) {
+    const started = Date.now();
+    const now = new Date();
+    const untilDate = input.until ? new Date(input.until) : now;
+    const sinceDate = input.since
+        ? new Date(input.since)
+        : new Date(untilDate.getTime() - (WINDOW_DAYS[input.date_preset] ?? 7) * 86_400_000);
+    const sinceUnix = Math.floor(sinceDate.getTime() / 1000);
+    const untilUnix = Math.floor(untilDate.getTime() / 1000);
+    const igCreds = insightsCreds(ctx.config);
+    const igOverride = igCreds ? { accessTokenOverride: igCreds.token, appSecretOverride: igCreds.appSecret } : {};
+    const posts = [];
+    const errors = {};
+    // Discover Pages.
+    let pages = [];
+    try {
+        const resp = await ctx.graph.get({
+            path: "me/assigned_pages",
+            params: { fields: "id,name", limit: input.max_pages },
+        });
+        pages = Array.isArray(resp.data) ? resp.data : [];
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        errors["assigned_pages"] = { error: e.message, hint: e.hint };
+    }
+    // Facebook posts in window.
+    if (input.include_facebook) {
+        for (const p of pages) {
+            try {
+                const pageToken = await ctx.graph.getPageAccessToken(p.id);
+                const { data } = await ctx.graph.getAllPages({
+                    path: `${p.id}/published_posts`,
+                    params: {
+                        fields: "id,message,created_time,permalink_url,status_type,attachments{media_type},reactions.summary(true).limit(0),comments.summary(true).limit(0),shares",
+                        since: String(sinceUnix),
+                        until: String(untilUnix),
+                        limit: 50,
+                    },
+                    accessTokenOverride: pageToken,
+                }, Math.ceil(input.max_posts_per_account / 50));
+                for (const post of data.slice(0, input.max_posts_per_account)) {
+                    const c = classifyFacebook(post);
+                    posts.push({
+                        platform: "facebook",
+                        owner: p.name ?? p.id,
+                        owner_id: p.id,
+                        post_id: String(post.id),
+                        type: c.type,
+                        created: String(post.created_time ?? ""),
+                        permalink: post.permalink_url,
+                        caption: post.message?.slice(0, 140),
+                        engagement: c.engagement,
+                        engagement_breakdown: c.breakdown,
+                    });
+                }
+            }
+            catch (err) {
+                const e = err instanceof MetaError ? err : new MetaError(err.message);
+                errors[`fb:${p.id}`] = { error: e.message, hint: e.hint };
+            }
+        }
+    }
+    // Instagram media in window (no native since/until — paginate then filter by timestamp).
+    if (input.include_instagram) {
+        for (const p of pages) {
+            let ig;
+            try {
+                const d = await ctx.graph.get({
+                    path: p.id,
+                    params: { fields: "instagram_business_account{id,username}" },
+                    ...igOverride,
+                });
+                ig = d.instagram_business_account;
+            }
+            catch {
+                /* page may have no IG; skip silently */
+            }
+            if (!ig)
+                continue;
+            try {
+                const { data } = await ctx.graph.getAllPages({
+                    path: `${ig.id}/media`,
+                    params: {
+                        fields: "id,media_type,media_product_type,caption,permalink,timestamp,like_count,comments_count",
+                        limit: 50,
+                    },
+                    ...igOverride,
+                }, Math.ceil(input.max_posts_per_account / 50));
+                for (const media of data) {
+                    const ts = Math.floor(new Date(String(media.timestamp)).getTime() / 1000);
+                    if (ts < sinceUnix || ts > untilUnix)
+                        continue; // window filter
+                    const c = classifyInstagram(media);
+                    posts.push({
+                        platform: "instagram",
+                        owner: ig.username ? `@${ig.username}` : ig.id,
+                        owner_id: ig.id,
+                        post_id: String(media.id),
+                        type: c.type,
+                        created: String(media.timestamp ?? ""),
+                        permalink: media.permalink,
+                        caption: media.caption?.slice(0, 140),
+                        engagement: c.engagement,
+                        engagement_breakdown: c.breakdown,
+                    });
+                }
+            }
+            catch (err) {
+                const e = err instanceof MetaError ? err : new MetaError(err.message);
+                errors[`ig:${ig.id}`] = { error: e.message, hint: e.hint };
+            }
+        }
+    }
+    // Optional per-post insights for the top-N by engagement per platform.
+    if (input.include_insights && posts.length > 0) {
+        const topByPlatform = (plat) => posts
+            .filter((p) => p.platform === plat)
+            .sort((a, b) => b.engagement - a.engagement)
+            .slice(0, input.insights_top_n);
+        const targets = [...topByPlatform("facebook"), ...topByPlatform("instagram")];
+        await Promise.all(targets.map(async (p) => {
+            try {
+                if (p.platform === "instagram") {
+                    const r = await ctx.graph.get({
+                        path: `${p.post_id}/insights`,
+                        params: { metric: "reach,views,total_interactions,saved,shares" },
+                        ...igOverride,
+                    });
+                    p.insights = { data: r.data ?? [] };
+                }
+                else {
+                    const parentPageId = p.owner_id;
+                    const creds = insightsCreds(ctx.config);
+                    const pageToken = await ctx.graph.getPageAccessToken(parentPageId, creds ? { token: creds.token, appSecret: creds.appSecret } : undefined);
+                    const r = await ctx.graph.get({
+                        path: `${p.post_id}/insights`,
+                        params: { metric: "post_impressions,post_impressions_unique,post_engaged_users" },
+                        accessTokenOverride: pageToken,
+                        appSecretOverride: creds?.appSecret,
+                    });
+                    p.insights = { data: r.data ?? [] };
+                }
+            }
+            catch (err) {
+                const e = err instanceof MetaError ? err : new MetaError(err.message);
+                p.insights = { error: e.message };
+            }
+        }));
+    }
+    const fbPosts = posts.filter((p) => p.platform === "facebook");
+    const igPosts = posts.filter((p) => p.platform === "instagram");
+    const topOverall = [...posts].sort((a, b) => b.engagement - a.engagement).slice(0, 10);
+    const structured = {
+        window: {
+            preset: input.since || input.until ? "custom" : input.date_preset,
+            since: sinceDate.toISOString(),
+            until: untilDate.toISOString(),
+        },
+        generated_at: now.toISOString(),
+        latency_ms: Date.now() - started,
+        totals: {
+            all_posts: posts.length,
+            facebook: aggregate(fbPosts),
+            instagram: aggregate(igPosts),
+        },
+        comparison: {
+            facebook_posts: fbPosts.length,
+            instagram_posts: igPosts.length,
+            facebook_total_engagement: fbPosts.reduce((s, p) => s + p.engagement, 0),
+            instagram_total_engagement: igPosts.reduce((s, p) => s + p.engagement, 0),
+            note: "Engagement = reactions+comments+shares (FB) / likes+comments (IG). For audience age/gender/country demographics, call meta_ig_get_audience_demographics (account-level).",
+        },
+        top_posts: topOverall,
+        posts,
+        errors: Object.keys(errors).length ? errors : null,
+    };
+    return toolResult(structured, jsonBlock(structured));
+}

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

@@ -23,7 +23,7 @@ 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 description: "Single-call summary of the SINGLE most-recent post on each Facebook Page and Instagram account, with its engagement + insights.\n\nUSE FOR (latest / most-recent only):\n- \"How did my latest post perform?\"\n- \"What's the engagement on my most recent post on each account?\"\n- \"Show me the newest post on each platform.\"\n\nNOT FOR: a date range or \"how many posts this week/month\" or content comparison over a period → use meta_content_report (it takes a time window). A whole-business snapshot incl. ads/pixels → use meta_business_overview. Audience age/gender/country → use meta_ig_get_audience_demographics.\n\nInternally walks /me/assigned_pages → each Page's latest published post + optional insights → each linked Instagram account's latest media + optional insights. Auto-discovers all Page/IG IDs — the caller never supplies them. Per-section error isolation so one failure doesn't blank the result.";
     readonly inputSchema: {
         include_instagram: z.ZodDefault<z.ZodBoolean>;
         include_facebook: z.ZodDefault<z.ZodBoolean>;

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

@@ -31,22 +31,16 @@ export const inputSchema = z
 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.`,
+    description: `Single-call summary of the SINGLE most-recent post on each Facebook Page and Instagram account, with its engagement + insights.
+
+USE FOR (latest / most-recent only):
+- "How did my latest post perform?"
+- "What's the engagement on my most recent post on each account?"
+- "Show me the newest post on each platform."
+
+NOT FOR: a date range or "how many posts this week/month" or content comparison over a period → use meta_content_report (it takes a time window). A whole-business snapshot incl. ads/pixels → use meta_business_overview. Audience age/gender/country → use meta_ig_get_audience_demographics.
+
+Internally walks /me/assigned_pages → each Page's latest published post + optional insights → each linked Instagram account's latest media + optional insights. Auto-discovers all Page/IG IDs — the caller never supplies them. Per-section error isolation so one failure doesn't blank the result.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 };

package/dist/tools/pages/get-insights.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assertAllowed } from "../../config.js";
 import { metaIdSchema } from "../../helpers/schema.js";
-import { runGetAsPage } from "../shared.js";
+import { runGetAsPageViaInsightsApp } from "../shared.js";
 const PERIOD = z.enum(["day", "week", "days_28", "lifetime", "total_over_range"]);
 export const inputSchema = z
     .object({
@@ -37,7 +37,7 @@ export const definition = {
 };
 export async function handler(input, ctx) {
     assertAllowed("page", input.page_id, ctx.config);
-    return runGetAsPage(ctx, input.page_id, {
+    return runGetAsPageViaInsightsApp(ctx, input.page_id, {
         path: `${input.page_id}/insights`,
         params: {
             metric: input.metrics.join(","),

package/dist/tools/pages/get-post-insights.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { metaIdSchema } from "../../helpers/schema.js";
-import { errorResult, runGetAsPage } from "../shared.js";
+import { errorResult, runGetAsPageViaInsightsApp } from "../shared.js";
 export const inputSchema = z
     .object({
     post_id: metaIdSchema.describe("Post ID. Meta uses the '{page_id}_{post_id}' format — pass it in full so the server can resolve the parent Page's access token automatically."),
@@ -27,8 +27,8 @@ export const inputSchema = z
 export const definition = {
     name: "meta_page_get_post_insights",
     title: "Get insights for a single Page post",
-    description: `Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post.
-
+    description: `Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post.
+
 Uses the parent Page's access token (auto-resolved from the '{page_id}_{post_id}' prefix; pass page_id explicitly if your post_id isn't in that form). Requires the system user to be assigned to the Page with 'View performance' or 'Analyze Page' tasks, plus 'read_insights' scope on the token.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -40,7 +40,7 @@ export async function handler(input, ctx) {
     if (!/^\d+$/.test(parentPageId)) {
         return errorResult(new Error(`Could not infer parent Page ID from post_id '${input.post_id}'. Pass page_id explicitly.`));
     }
-    return runGetAsPage(ctx, parentPageId, {
+    return runGetAsPageViaInsightsApp(ctx, parentPageId, {
         path: `${input.post_id}/insights`,
         params: { metric: input.metrics.join(",") },
     });

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

@@ -32,7 +32,7 @@ export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {
     readonly name: "meta_page_list_posts";
     readonly title: "List Page posts";
-    readonly description: "Lists Page posts with attached counts (reactions, comments, shares). Use since/until for a date window. The ID returned for each post is the one meta_page_get_post_insights expects.";
+    readonly description: "Lists raw Facebook Page posts for ONE page, with reaction/comment/share counts. Supports since/until for a date window and returns post IDs for meta_page_get_post_insights.\n\nUSE FOR: drilling into a single specific Page's post list, or when you already have the page_id. For a cross-account content report (\"how many posts this week across all my accounts, by type, with comparison\") prefer meta_content_report — it walks every Page + Instagram account and classifies/aggregates automatically, no page_id needed.";
     readonly inputSchema: {
         limit: z.ZodDefault<z.ZodNumber>;
         after: z.ZodOptional<z.ZodString>;

package/dist/tools/pages/list-posts.js

@@ -39,7 +39,9 @@ export const inputSchema = z
 export const definition = {
     name: "meta_page_list_posts",
     title: "List Page posts",
-    description: `Lists Page posts with attached counts (reactions, comments, shares). Use since/until for a date window. The ID returned for each post is the one meta_page_get_post_insights expects.`,
+    description: `Lists raw Facebook Page posts for ONE page, with reaction/comment/share counts. Supports since/until for a date window and returns post IDs for meta_page_get_post_insights.
+
+USE FOR: drilling into a single specific Page's post list, or when you already have the page_id. For a cross-account content report ("how many posts this week across all my accounts, by type, with comparison") prefer meta_content_report — it walks every Page + Instagram account and classifies/aggregates automatically, no page_id needed.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 };

package/dist/tools/register.js

@@ -46,6 +46,7 @@ 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,
@@ -65,8 +66,8 @@ const TOOLS = [
     catalogList, catalogListProducts, catalogGetDiagnostics,
     // WhatsApp (4)
     whatsappListWabas, whatsappListPhoneNumbers, whatsappListTemplates, whatsappGetAnalytics,
-    // Overview (2)
-    businessOverview, latestPostsSummary,
+    // Overview (3)
+    businessOverview, latestPostsSummary, contentReport,
 ].map((m) => m);
 export function registerTools(server, ctx) {
     const names = [];