@praise25/meta-mcp-server 0.1.8 → 0.1.10

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 = [];

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>;

package/dist/tools/shared.js

@@ -1,5 +1,24 @@
+/**
+ * Shared helpers used across domain tools — keeps each tool file focused on
+ * its endpoint instead of re-implementing boilerplate.
+ */
+import { insightsCreds } from "../config.js";
 import { MetaError } from "../errors.js";
 import { jsonBlock, toolError, toolResult } from "../helpers/format.js";
+/**
+ * If a secondary "insights app" is configured, returns the token + app-secret
+ * overrides to route this call through it; otherwise returns an empty object
+ * (call uses the primary app). Insight endpoints (IG media/audience, Page/post
+ * insights) need this because Meta forbids combining the Marketing-API use
+ * case with Instagram-content / Pages-everything on a single app — so insights
+ * frequently live on a second app. See config.ts `insightsCreds`.
+ */
+function insightsOverrides(ctx) {
+    const creds = insightsCreds(ctx.config);
+    if (!creds)
+        return {};
+    return { accessTokenOverride: creds.token, appSecretOverride: creds.appSecret };
+}
 /**
  * Fetch one page or auto-paginate, normalize into a structured list payload,
  * and translate errors. Use for simple `GET /{id}/{edge}` style tools.
@@ -43,6 +62,16 @@ export async function runGet(ctx, opts, extra = {}) {
         return errorResult(err);
     }
 }
+/**
+ * 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 async function runGetViaInsightsApp(ctx, opts, extra = {}) {
+    return runGet(ctx, { ...opts, ...insightsOverrides(ctx) }, extra);
+}
 export function errorResult(err) {
     const e = err instanceof MetaError ? err : new MetaError(err.message);
     return toolError(e.message, e.hint, {
@@ -79,3 +108,30 @@ export async function runGetAsPage(ctx, pageId, opts, extra = {}) {
         return errorResult(err);
     }
 }
+/**
+ * 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 async function runGetAsPageViaInsightsApp(ctx, pageId, opts, extra = {}) {
+    try {
+        const creds = insightsCreds(ctx.config);
+        if (creds) {
+            const pageToken = await ctx.graph.getPageAccessToken(pageId, {
+                token: creds.token,
+                appSecret: creds.appSecret,
+            });
+            return runGet(ctx, { ...opts, accessTokenOverride: pageToken, appSecretOverride: creds.appSecret }, extra);
+        }
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runGet(ctx, { ...opts, accessTokenOverride: pageToken }, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}

package/dist/tools/token/health.js

@@ -5,12 +5,12 @@ export const inputSchema = z.object({}).strict();
 export const definition = {
     name: "meta_health_check",
     title: "Meta MCP health check",
-    description: `End-to-end reachability probe:
-- Confirms the Graph API is reachable.
-- Confirms the configured token resolves to a valid identity (via /me).
-- Surfaces the latest rate-limit header snapshot from the Graph client.
-- Lists which allowlists are active (business / ad account / page / IG user).
-
+    description: `End-to-end reachability probe:
+- Confirms the Graph API is reachable.
+- Confirms the configured token resolves to a valid identity (via /me).
+- Surfaces the latest rate-limit header snapshot from the Graph client.
+- Lists which allowlists are active (business / ad account / page / IG user).
+
 Use when a session starts, or when diagnosing why other tools are returning errors.`,
     inputSchema: inputSchema.shape,
     annotations: {
@@ -34,6 +34,8 @@ export async function handler(_input, ctx) {
             identity: me,
             api_version: ctx.config.apiVersion,
             appsecret_proof_enabled: Boolean(ctx.config.appSecret),
+            insights_app_configured: Boolean(ctx.config.insightsAccessToken),
+            insights_app_appsecret_proof_enabled: Boolean(ctx.config.insightsAppSecret),
             rate_limit: ctx.graph.rateLimit,
             allowlists: {
                 businesses: ctx.config.allowedBusinessIds ? [...ctx.config.allowedBusinessIds] : null,

package/dist/tools/token/inspect.js

@@ -10,17 +10,17 @@ export const inputSchema = z
 export const definition = {
     name: "meta_token_inspect",
     title: "Inspect Meta access token",
-    description: `Decodes the configured META_ACCESS_TOKEN via Graph API /debug_token.
-
-Returns:
-- app_id + application name
-- token type (system-user / user / page)
-- is_valid
-- expires_at + data_access_expires_at (unix seconds; 0 = never expires)
-- scopes + granular_scopes (per-asset targeting)
-
-Use this first when troubleshooting — almost every other tool failure traces back to a missing scope or an asset not assigned to the token.
-
+    description: `Decodes the configured META_ACCESS_TOKEN via Graph API /debug_token.
+
+Returns:
+- app_id + application name
+- token type (system-user / user / page)
+- is_valid
+- expires_at + data_access_expires_at (unix seconds; 0 = never expires)
+- scopes + granular_scopes (per-asset targeting)
+
+Use this first when troubleshooting — almost every other tool failure traces back to a missing scope or an asset not assigned to the token.
+
 Never logs the token itself.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/whatsapp/get-analytics.js

@@ -30,8 +30,8 @@ export const inputSchema = z
 export const definition = {
     name: "meta_whatsapp_get_analytics",
     title: "Get WhatsApp Business analytics",
-    description: `Fetches WABA analytics — either the legacy 'analytics' field (message counts) or the richer 'conversation_analytics' (per-conversation pricing, categories: AUTHENTICATION/MARKETING/SERVICE/UTILITY).
-
+    description: `Fetches WABA analytics — either the legacy 'analytics' field (message counts) or the richer 'conversation_analytics' (per-conversation pricing, categories: AUTHENTICATION/MARKETING/SERVICE/UTILITY).
+
 Pass start + end as Unix seconds. Use granularity DAY for most reports. Filter by phone_numbers, country_codes, or conversation_categories to narrow.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },