@cashtokenai/meta-mcp-server 1.0.0

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

@@ -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: "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>;
+        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,189 @@
+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: `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 },
+};
+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/get-insights.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    page_id: z.ZodString;
+    metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    period: z.ZodDefault<z.ZodEnum<["day", "week", "days_28", "lifetime", "total_over_range"]>>;
+    since: z.ZodOptional<z.ZodString>;
+    until: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    page_id: string;
+    metrics: string[];
+    period: "day" | "week" | "days_28" | "lifetime" | "total_over_range";
+    since?: string | undefined;
+    until?: string | undefined;
+}, {
+    page_id: string;
+    since?: string | undefined;
+    until?: string | undefined;
+    metrics?: string[] | undefined;
+    period?: "day" | "week" | "days_28" | "lifetime" | "total_over_range" | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_page_get_insights";
+    readonly title: "Get Page-level insights";
+    readonly description: "Reads Page-level metrics: impressions, reach, engagements, fan growth, page views, video views. Requires 'read_insights' scope. Pick the right period per metric — many accept only 'day' or 'days_28'.";
+    readonly inputSchema: {
+        page_id: z.ZodString;
+        metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        period: z.ZodDefault<z.ZodEnum<["day", "week", "days_28", "lifetime", "total_over_range"]>>;
+        since: z.ZodOptional<z.ZodString>;
+        until: z.ZodOptional<z.ZodString>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;