@praise25/meta-mcp-server 0.1.8 → 0.1.11

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,344 @@
+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);
+                    // Meta deprecated the post_impressions* / post_engaged_users family
+                    // on the post /insights edge (v22+), and rejects the WHOLE call if
+                    // any single metric is invalid for the post type. So try
+                    // post-type-appropriate candidate sets in order and keep the first
+                    // that succeeds; the per-post engagement counts already display
+                    // regardless, so this is best-effort enrichment.
+                    const candidates = p.type === "video"
+                        ? [["post_video_views", "post_clicks"], ["post_video_views"], ["post_clicks"]]
+                        : [["post_clicks", "post_reactions_by_type_total"], ["post_clicks"]];
+                    let captured = false;
+                    let lastErr = "no metric set succeeded";
+                    for (const metrics of candidates) {
+                        try {
+                            const r = await ctx.graph.get({
+                                path: `${p.post_id}/insights`,
+                                params: { metric: metrics.join(",") },
+                                accessTokenOverride: pageToken,
+                                appSecretOverride: creds?.appSecret,
+                            });
+                            p.insights = { data: r.data ?? [] };
+                            captured = true;
+                            break;
+                        }
+                        catch (err) {
+                            lastErr = err instanceof MetaError ? err.message : err.message;
+                        }
+                    }
+                    if (!captured) {
+                        p.insights = {
+                            error: lastErr,
+                            note: "Facebook post-level reach via Insights API is best-effort; engagement counts above are authoritative.",
+                        };
+                    }
+                }
+            }
+            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 = [];

package/dist/tools/shared.d.ts

@@ -1,7 +1,3 @@
-/**
- * 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";
@@ -17,6 +13,14 @@ export interface ListRunOpts {
 export declare function runList<T>(ctx: ToolContext, opts: GraphGetOptions, pag: ListRunOpts, extra?: Record<string, unknown>): Promise<ToolTextResult>;
 /** Run a single read and return a tool result. */
 export declare function runGet<T>(ctx: ToolContext, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/**
+ * Like runGet, but routes through the secondary insights-app token + secret
+ * when one is configured (META_INSIGHTS_ACCESS_TOKEN). Use for direct
+ * `/{id}/insights` reads that require a permission (e.g.
+ * instagram_manage_insights) the primary ads app cannot host. Falls back to
+ * the primary token transparently when no insights app is configured.
+ */
+export declare function runGetViaInsightsApp<T>(ctx: ToolContext, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
 export declare function errorResult(err: unknown): ToolTextResult;
 /**
  * Resolves a Page access token for `pageId`, then runs `runList` with it as
@@ -28,3 +32,14 @@ export declare function errorResult(err: unknown): ToolTextResult;
 export declare function runListAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, pag: ListRunOpts, extra?: Record<string, unknown>): Promise<ToolTextResult>;
 /** Same as runGet but resolves and uses the Page access token first. */
 export declare function runGetAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/**
+ * Page-insights variant of runGetAsPage. When a secondary insights app is
+ * configured (the app holding the Pages "read_insights" use case), the Page
+ * access token is derived from the *insights* app's token and the call's
+ * appsecret_proof uses the insights app secret. Falls back to the primary
+ * app's Page token when no insights app is configured.
+ *
+ * Use for /{page_id}/insights and /{post_id}/insights, which need
+ * `read_insights` — a permission the Marketing-API primary app cannot host.
+ */
+export declare function runGetAsPageViaInsightsApp<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;