@praise25/meta-mcp-server 0.1.1 → 0.1.5

package/dist/errors.js

@@ -16,7 +16,7 @@ export class MetaError extends Error {
         this.type = opts.type;
         this.httpStatus = opts.httpStatus;
         this.retryable = opts.code != null && RETRYABLE_META_CODES.has(opts.code);
-        this.hint = opts.hint ?? deriveHint(opts.code, opts.subcode, opts.httpStatus);
+        this.hint = opts.hint ?? deriveHint(opts.code, opts.subcode, opts.httpStatus, message);
     }
     toJSON() {
         return {
@@ -32,7 +32,7 @@ export class MetaError extends Error {
         };
     }
 }
-function deriveHint(code, subcode, httpStatus) {
+function deriveHint(code, subcode, httpStatus, message) {
     if (code === 190) {
         if (subcode === 463)
             return "Access token has expired. Generate a new system-user token.";
@@ -40,8 +40,29 @@ function deriveHint(code, subcode, httpStatus) {
             return "Access token is invalid. Re-issue from Business Settings → System Users.";
         return "Access token error. Check META_ACCESS_TOKEN is valid and tied to the correct app.";
     }
-    if (code === 10 || code === 200) {
-        return "Permission denied. Verify the system user is assigned to the target asset and that the app has the required permissions (e.g. ads_read, pages_read_engagement).";
+    if (code === 10) {
+        // Code 10 splits into two distinct operator actions, distinguishable by the
+        // exact Meta error message — surface the right one so AI consumers can
+        // direct the user accurately.
+        if (message && /Application does not have permission/i.test(message)) {
+            return "App-level permission missing. The configured app needs Standard Access via Meta App Review for the relevant permission (e.g. instagram_manage_insights, ads_management). Request via App Review → Permissions and Features in the app dashboard. While in development tier, only developer/admin users on the app can read this data.";
+        }
+        if (message && /Page Public Content Access/i.test(message)) {
+            return "App needs the 'Page Public Content Access' feature, granted via Meta App Review. Until approved, pages_read_engagement on Pages outside the app's developer/test set will fail. Path: App Dashboard → App Review → Features.";
+        }
+        return "App-level permission denied (code 10). Either the configured app lacks the required permission/feature in App Review, or the system user is not assigned to the target asset with the right task in Business Settings.";
+    }
+    if (code === 200) {
+        if (message && /pages_read_user_content/i.test(message)) {
+            return "Token lacks 'pages_read_user_content'. Regenerate the system-user token in Business Settings → System Users → Generate New Token, ticking that scope.";
+        }
+        if (message && /This application has not been approved/i.test(message)) {
+            return "App not approved for this product. Add the relevant Product (e.g. WhatsApp Business Platform, Commerce / Catalog Management) to the app in https://developers.facebook.com/apps and complete its onboarding.";
+        }
+        return "Permission denied. Verify the system user is assigned to the target asset (Business Settings → System Users → Add Assets) with the right task, and the token has the matching scope.";
+    }
+    if (code === 283) {
+        return "Token lacks the scope needed for this Page action (typically pages_read_user_content for reviews, or pages_read_engagement for posts). Regenerate the token with the required scope ticked.";
     }
     if (code === 4 || code === 17 || code === 32) {
         return "Rate-limited by Meta. Retry with backoff or narrow the query (shorter date range, fewer breakdowns).";
@@ -49,7 +70,16 @@ function deriveHint(code, subcode, httpStatus) {
     if (code === 613) {
         return "Ad account throttled. Reduce insight query complexity or wait before retrying.";
     }
+    if (code === 210) {
+        return "This endpoint requires a Page access token, not the system-user token. The Page tools resolve this automatically — if you see this from meta_graph_read, fetch the token via GET /{page_id}?fields=access_token first.";
+    }
+    if (code === 12) {
+        return "Field deprecated by Meta. Remove the deprecated field from the `fields` array. Common offender: 'subattachments' inside attachments expansion (deprecated in v3.3+).";
+    }
     if (code === 100) {
+        if (message && /must be a valid insights metric/i.test(message)) {
+            return "Either one of the supplied metrics is invalid for this Page/period combination, OR the token lacks 'read_insights' (Meta returns this misleading error in both cases). Check the token has read_insights via meta_token_inspect, then narrow your metrics list to a known-valid subset.";
+        }
         return "Invalid parameter. Check field names, ID format (ad accounts need 'act_' prefix), and date presets.";
     }
     if (httpStatus === 404) {

package/dist/helpers/graph-client.d.ts

@@ -9,6 +9,16 @@ export interface GraphGetOptions {
     noCache?: boolean;
     /** Override the API version for this call. */
     apiVersion?: string;
+    /**
+     * Use a Page-specific access token instead of the configured system-user
+     * token for this request. Required for Page-level edges like /{page_id}/posts,
+     * /{page_id}/insights, /{page_id}/ratings, /{page_id}/videos and for post-
+     * insights endpoints. Use `getPageAccessToken(pageId)` to fetch one.
+     *
+     * `appsecret_proof` is recomputed against this token so the cryptographic
+     * binding to the app remains intact.
+     */
+    accessTokenOverride?: string;
 }
 export interface GraphPagedResponse<T = unknown> {
     data: T[];
@@ -33,10 +43,24 @@ export declare class GraphClient {
     private readonly logger;
     private readonly http;
     private readonly cache;
+    private readonly pageTokens;
     private lastRateLimit;
     constructor(config: Config, logger: Logger);
     get rateLimit(): GraphRateLimitHeaders;
     clearCache(): void;
+    /**
+     * Resolve the Page access token for a Page id. Cached process-locally for
+     * the lifetime of the GraphClient (Page tokens don't expire as fast as
+     * user tokens, and this avoids paying the round-trip cost on every Page
+     * call). Page-level Graph edges (`/posts`, `/ratings`, `/videos`,
+     * `/insights`, `/{post_id}/insights`) require a Page access token rather
+     * than the configured system-user token; without it Meta returns
+     * `(#210) A page access token is required`.
+     *
+     * Requires the configured system user to be assigned to the Page with
+     * at least the "View performance" or "Analyze Page" task.
+     */
+    getPageAccessToken(pageId: string): Promise<string>;
     get<T = GraphPagedResponse>(opts: GraphGetOptions): Promise<T>;
     /**
      * Follow `paging.next` cursors and concatenate `data` arrays up to maxPages.

package/dist/helpers/graph-client.js

@@ -8,6 +8,7 @@ export class GraphClient {
     logger;
     http;
     cache;
+    pageTokens = new Map();
     lastRateLimit = {};
     constructor(config, logger) {
         this.config = config;
@@ -36,12 +37,46 @@ export class GraphClient {
     }
     clearCache() {
         this.cache.clear();
+        this.pageTokens.clear();
+    }
+    /**
+     * Resolve the Page access token for a Page id. Cached process-locally for
+     * the lifetime of the GraphClient (Page tokens don't expire as fast as
+     * user tokens, and this avoids paying the round-trip cost on every Page
+     * call). Page-level Graph edges (`/posts`, `/ratings`, `/videos`,
+     * `/insights`, `/{post_id}/insights`) require a Page access token rather
+     * than the configured system-user token; without it Meta returns
+     * `(#210) A page access token is required`.
+     *
+     * Requires the configured system user to be assigned to the Page with
+     * at least the "View performance" or "Analyze Page" task.
+     */
+    async getPageAccessToken(pageId) {
+        if (!pageId)
+            throw new MetaError("getPageAccessToken: pageId is required");
+        const cached = this.pageTokens.get(pageId);
+        if (cached)
+            return cached;
+        const resp = await this.get({
+            path: pageId,
+            params: { fields: "access_token,id,name" },
+            // Don't cache via the URL+params LRU because the value is sensitive and
+            // we want to keep the per-page Map as the single source of truth.
+            noCache: true,
+        });
+        if (!resp.access_token) {
+            throw new MetaError(`Page ${pageId} did not return an access_token. The system user may not be assigned to this Page or lacks the required task.`, {
+                hint: "In Business Settings → System Users → AI_Insights_Reader → Add Assets, assign this Page with at least 'View performance' or 'Analyze Page' tasks.",
+            });
+        }
+        this.pageTokens.set(pageId, resp.access_token);
+        return resp.access_token;
     }
     async get(opts) {
         const version = opts.apiVersion ?? this.config.apiVersion;
         const path = opts.path.replace(/^\/+/, "");
         const url = `/${version}/${path}`;
-        const params = this.buildParams(opts.params);
+        const params = this.buildParams(opts.params, opts.accessTokenOverride);
         const cacheKey = this.cacheKeyFor(url, params);
         if (!opts.noCache) {
             const cached = this.cache.get(cacheKey);
@@ -71,7 +106,12 @@ export class GraphClient {
                 collected.push(...page.data);
             nextAfter = page.paging?.cursors?.after;
             if (page.paging?.next && pages < cap) {
-                currentOpts = this.optsFromNextUrl(page.paging.next);
+                // Propagate the original accessTokenOverride to subsequent pages —
+                // optsFromNextUrl strips access_token from the URL but the override
+                // (if any) must continue to be applied.
+                const next = this.optsFromNextUrl(page.paging.next);
+                next.accessTokenOverride = opts.accessTokenOverride;
+                currentOpts = next;
             }
             else {
                 currentOpts = null;
@@ -92,24 +132,26 @@ export class GraphClient {
         }
         return { path, params, apiVersion: version };
     }
-    buildParams(params) {
+    buildParams(params, accessTokenOverride) {
         const out = {};
         for (const [k, v] of Object.entries(params ?? {})) {
             if (v === undefined || v === null)
                 continue;
             out[k] = v;
         }
-        out.access_token = this.config.accessToken;
+        const token = accessTokenOverride ?? this.config.accessToken;
+        out.access_token = token;
         if (this.config.appSecret) {
-            out.appsecret_proof = this.appsecretProof();
+            out.appsecret_proof = this.appsecretProof(token);
         }
         return out;
     }
-    appsecretProof() {
-        // appsecret_proof = HMAC-SHA256(access_token, app_secret)
+    appsecretProof(token) {
+        // appsecret_proof = HMAC-SHA256(access_token, app_secret).
+        // Recompute against whichever token is in use (system-user OR Page).
         return crypto
             .createHmac("sha256", this.config.appSecret)
-            .update(this.config.accessToken)
+            .update(token ?? this.config.accessToken)
             .digest("hex");
     }
     cacheKeyFor(url, params) {

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

@@ -58,8 +58,8 @@ export declare const inputSchema: z.ZodObject<{
     }[] | undefined;
 }, {
     object_id: string;
-    sort?: string[] | undefined;
     fields?: string[] | undefined;
+    sort?: string[] | undefined;
     limit?: number | undefined;
     after?: string | undefined;
     auto_paginate?: boolean | undefined;

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

@@ -101,16 +101,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ads_get_insights",
     title: "Get Marketing API insights (the workhorse)",
-    description: `Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.
-
-Returns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.
-
-Tips for the AI consuming this:
-- Default date_preset is last_30d. Override via date_preset or time_range.
-- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.
-- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.
-- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.
-
+    description: `Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.
+
+Returns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.
+
+Tips for the AI consuming this:
+- Default date_preset is last_30d. Override via date_preset or time_range.
+- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.
+- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.
+- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.
+
 Requires 'ads_read' token scope.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/tools/ads/list-accounts.js

@@ -31,10 +31,10 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ads_list_accounts",
     title: "List ad accounts under a business",
-    description: `Lists ad accounts the business owns (owned_ad_accounts) and/or has access to (client_ad_accounts).
-
-Needs token scope 'ads_read' and the system user must have 'View performance' task on each account.
-
+    description: `Lists ad accounts the business owns (owned_ad_accounts) and/or has access to (client_ad_accounts).
+
+Needs token scope 'ads_read' and the system user must have 'View performance' task on each account.
+
 Returns account_id (numeric), currency, timezone, status, balance, spend cap. Use 'act_<account_id>' when feeding downstream tools like meta_ads_get_insights.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/business/list-assets.js

@@ -34,16 +34,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_list_assets",
     title: "List assets assigned to a Business Manager",
-    description: `For a given business_id, enumerates the business assets the token can see in one call:
-- Ad accounts (owned + optionally client)
-- Facebook Pages (owned + optionally client)
-- Instagram Business accounts
-- Meta Pixels
-- Product catalogs
-- WhatsApp Business accounts (WABAs)
-
-Each section is fetched as a separate Graph call. Failures on individual sections do not abort the others — the response reports per-section success/error so the assistant can work around partial failures.
-
+    description: `For a given business_id, enumerates the business assets the token can see in one call:
+- Ad accounts (owned + optionally client)
+- Facebook Pages (owned + optionally client)
+- Instagram Business accounts
+- Meta Pixels
+- Product catalogs
+- WhatsApp Business accounts (WABAs)
+
+Each section is fetched as a separate Graph call. Failures on individual sections do not abort the others — the response reports per-section success/error so the assistant can work around partial failures.
+
 Use this to discover IDs for downstream insight tools.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/business/list-businesses.js

@@ -23,10 +23,10 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_list",
     title: "List Meta businesses visible to the token",
-    description: `Lists every Business Manager the configured access token can see — via GET /me/businesses.
-
-Typical usage: call this once at the start of a session to discover available business IDs, then pass the chosen ID to meta_business_list_assets / meta_business_list_system_users.
-
+    description: `Lists every Business Manager the configured access token can see — via GET /me/businesses.
+
+Typical usage: call this once at the start of a session to discover available business IDs, then pass the chosen ID to meta_business_list_assets / meta_business_list_system_users.
+
 Respects META_ALLOWED_BUSINESS_IDS: if set, filters the response to that allowlist.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/business/list-system-users.js

@@ -16,10 +16,10 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_list_system_users",
     title: "List system users attached to a business",
-    description: `Lists the system-user (server/software) identities under a Business Manager.
-
-System users are non-human identities used for API access. This tool helps diagnose which identity owns the token in use (cross-reference with meta_token_inspect).
-
+    description: `Lists the system-user (server/software) identities under a Business Manager.
+
+System users are non-human identities used for API access. This tool helps diagnose which identity owns the token in use (cross-reference with meta_token_inspect).
+
 Reads /{business_id}/system_users.`,
     inputSchema: inputSchema.shape,
     annotations: {

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

@@ -16,8 +16,8 @@ export declare const inputSchema: z.ZodObject<{
     after?: string | undefined;
 }, {
     catalog_id: string;
-    filter?: string | undefined;
     fields?: string[] | undefined;
+    filter?: string | undefined;
     limit?: number | undefined;
     after?: string | undefined;
     auto_paginate?: boolean | undefined;

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

@@ -23,7 +23,7 @@ export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {
     readonly name: "meta_ig_get_audience_demographics";
     readonly title: "Get IG audience demographics";
-    readonly description: "Reads demographic breakdown of an IG Business account's followers, engaged audience, or reached audience. Use breakdown='age'|'gender'|'country'|'city' to slice.\n\nRequires 'instagram_manage_insights'. Only IG Business accounts with at least 100 followers return data — below that threshold Meta returns empty results for privacy.";
+    readonly description: "Reads demographic breakdown of an IG Business account's followers, engaged audience, or reached audience. Use breakdown='age'|'gender'|'country'|'city' to slice.\n\n**Requirements (in order of frequency-of-failure):**\n1. Token has 'instagram_manage_insights' scope.\n2. The Hodusoft app must be approved for **Standard Access** on `instagram_manage_insights` via Meta App Review. In development tier, Meta returns `(#10) Application does not have permission for this action` on this endpoint specifically — even if the scope is on the token.\n3. The IG Business account must have ≥ 100 followers (Meta hides smaller accounts' demographics for privacy).\n\nIf you see code (#10), it's almost always #2. Track the App Review request and surface the gap to the operator; this tool is functioning correctly when it returns that error.";
     readonly inputSchema: {
         ig_user_id: z.ZodString;
         metric: z.ZodDefault<z.ZodEnum<["follower_demographics", "engaged_audience_demographics", "reached_audience_demographics"]>>;

package/dist/tools/instagram/get-audience-demographics.js

@@ -26,9 +26,14 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ig_get_audience_demographics",
     title: "Get IG audience demographics",
-    description: `Reads demographic breakdown of an IG Business account's followers, engaged audience, or reached audience. Use breakdown='age'|'gender'|'country'|'city' to slice.
-
-Requires 'instagram_manage_insights'. Only IG Business accounts with at least 100 followers return data — below that threshold Meta returns empty results for privacy.`,
+    description: `Reads demographic breakdown of an IG Business account's followers, engaged audience, or reached audience. Use breakdown='age'|'gender'|'country'|'city' to slice.
+
+**Requirements (in order of frequency-of-failure):**
+1. Token has 'instagram_manage_insights' scope.
+2. The Hodusoft app must be approved for **Standard Access** on \`instagram_manage_insights\` via Meta App Review. In development tier, Meta returns \`(#10) Application does not have permission for this action\` on this endpoint specifically — even if the scope is on the token.
+3. The IG Business account must have ≥ 100 followers (Meta hides smaller accounts' demographics for privacy).
+
+If you see code (#10), it's almost always #2. Track the App Review request and surface the gap to the operator; this tool is functioning correctly when it returns that error.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 };

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

@@ -14,7 +14,7 @@ export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {
     readonly name: "meta_ig_get_media_insights";
     readonly title: "Get Instagram media insights";
-    readonly description: "Per-media metrics: reach, impressions, saves, likes, comments, shares, profile visits, follows-from-post. Requires 'instagram_manage_insights' scope.\n\nDifferent media types support different metric sets:\n- IMAGE/CAROUSEL_ALBUM: impressions, reach, saved, likes, comments, shares, profile_visits\n- VIDEO (Reels): plays, reach, likes, comments, shares, saved, total_interactions\n- STORY: impressions, reach, replies, exits, taps_forward, taps_back (use meta_ig_get_story_insights-style metrics)\n\nIf a metric is unsupported for the media type, Meta returns code 100 — retry with a narrower metric list.";
+    readonly description: "Per-media metrics: reach, views, saves, likes, comments, shares, total_interactions, profile_visits, follows.\n\n**Requirements (in order of frequency-of-failure):**\n1. Token has 'instagram_manage_insights' scope.\n2. **The configured app must be approved for Standard Access on `instagram_manage_insights` via Meta App Review.** In development tier, Meta returns `(#10) Application does not have permission for this action` for the IG insights endpoints — even if the scope is on the token. This applies to media insights AND audience demographics. Track the App Review request and surface this to the operator; this tool is functioning correctly when it returns that error.\n3. The IG account must be Business or Creator (not personal).\n\n**Metric / media-type compatibility (post v22 deprecations):**\n- IMAGE / CAROUSEL_ALBUM: reach, saved, likes, comments, shares, total_interactions, profile_visits\n- VIDEO / REELS: views, reach, likes, comments, shares, saved, total_interactions  ('impressions' is deprecated, use 'views')\n- STORY: views, reach, replies, navigation, profile_visits, follows  (impressions is deprecated; use views)\n\nIf you see code (#100) \"metric not supported for media type\", narrow the metrics list to the matching subset above. If you see code (#10), it's almost always App Review (#2 above).";
     readonly inputSchema: {
         media_id: z.ZodString;
         metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;

package/dist/tools/instagram/get-media-insights.js

@@ -7,31 +7,37 @@ export const inputSchema = z
     metrics: z
         .array(z.string())
         .default([
-        "impressions",
+        // v23-safe set covering Reels (the most common modern IG media type
+        // for marketing accounts). 'impressions' is deprecated for IG media
+        // in v22+; 'views' replaces it. See the description for media-type
+        // / metric compatibility.
         "reach",
-        "saved",
+        "views",
         "likes",
         "comments",
         "shares",
+        "saved",
         "total_interactions",
-        "profile_visits",
-        "follows",
-        "profile_activity",
     ])
-        .describe("IG media metrics. For Reels prefer 'plays, reach, likes, comments, shares, saved, total_interactions'. Some metrics are media_type-specific — if a metric isn't supported for the media type, Meta returns an error."),
+        .describe("IG media metrics. Defaults are v23-safe for Reels. For IMAGE/CAROUSEL_ALBUM you can drop 'views' and add 'profile_visits'. For STORY use ['views','reach','replies','navigation']. See the tool description for the full media-type/metric compatibility matrix."),
 })
     .strict();
 export const definition = {
     name: "meta_ig_get_media_insights",
     title: "Get Instagram media insights",
-    description: `Per-media metrics: reach, impressions, saves, likes, comments, shares, profile visits, follows-from-post. Requires 'instagram_manage_insights' scope.
-
-Different media types support different metric sets:
-- IMAGE/CAROUSEL_ALBUM: impressions, reach, saved, likes, comments, shares, profile_visits
-- VIDEO (Reels): plays, reach, likes, comments, shares, saved, total_interactions
-- STORY: impressions, reach, replies, exits, taps_forward, taps_back (use meta_ig_get_story_insights-style metrics)
-
-If a metric is unsupported for the media type, Meta returns code 100 — retry with a narrower metric list.`,
+    description: `Per-media metrics: reach, views, saves, likes, comments, shares, total_interactions, profile_visits, follows.
+
+**Requirements (in order of frequency-of-failure):**
+1. Token has 'instagram_manage_insights' scope.
+2. **The configured app must be approved for Standard Access on \`instagram_manage_insights\` via Meta App Review.** In development tier, Meta returns \`(#10) Application does not have permission for this action\` for the IG insights endpoints — even if the scope is on the token. This applies to media insights AND audience demographics. Track the App Review request and surface this to the operator; this tool is functioning correctly when it returns that error.
+3. The IG account must be Business or Creator (not personal).
+
+**Metric / media-type compatibility (post v22 deprecations):**
+- IMAGE / CAROUSEL_ALBUM: reach, saved, likes, comments, shares, total_interactions, profile_visits
+- VIDEO / REELS: views, reach, likes, comments, shares, saved, total_interactions  ('impressions' is deprecated, use 'views')
+- STORY: views, reach, replies, navigation, profile_visits, follows  (impressions is deprecated; use views)
+
+If you see code (#100) "metric not supported for media type", narrow the metrics list to the matching subset above. If you see code (#10), it's almost always App Review (#2 above).`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 };

package/dist/tools/instagram/list-accounts.js

@@ -10,8 +10,8 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ig_list_accounts",
     title: "List Instagram Business accounts reachable via Pages",
-    description: `Walks the Pages visible to the token (/me/assigned_pages) and, for each, resolves the linked Instagram Business account via 'instagram_business_account'. This is the modern discovery path — the /owned_instagram_accounts business edge is unreliable.
-
+    description: `Walks the Pages visible to the token (/me/assigned_pages) and, for each, resolves the linked Instagram Business account via 'instagram_business_account'. This is the modern discovery path — the /owned_instagram_accounts business edge is unreliable.
+
 Requires 'instagram_basic' scope on the token and 'Analyze Instagram account' task on each IG.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/tools/meta/graph-read.js

@@ -23,13 +23,13 @@ const FORBIDDEN_PARAMS = new Set(["access_token", "appsecret_proof"]);
 export const definition = {
     name: "meta_graph_read",
     title: "Arbitrary read-only Graph API call",
-    description: `Escape-hatch for arbitrary GET requests against the Meta Graph API.
-
-This tool exists so the assistant can reach fields and endpoints that do not yet have a dedicated tool wrapper — without ever sending a write. The underlying HTTP client is hard-wired to GET only; POST/PUT/DELETE are refused before the request leaves the process.
-
-Rules:
-- Do NOT include 'access_token' or 'appsecret_proof' in params — they are added automatically.
-- Do NOT prefix the path with the API version.
+    description: `Escape-hatch for arbitrary GET requests against the Meta Graph API.
+
+This tool exists so the assistant can reach fields and endpoints that do not yet have a dedicated tool wrapper — without ever sending a write. The underlying HTTP client is hard-wired to GET only; POST/PUT/DELETE are refused before the request leaves the process.
+
+Rules:
+- Do NOT include 'access_token' or 'appsecret_proof' in params — they are added automatically.
+- Do NOT prefix the path with the API version.
 - Prefer dedicated tools (meta_business_list_assets, meta_ads_get_insights, …) when they exist. Use this as a last resort.`,
     inputSchema: inputSchema.shape,
     annotations: {

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

@@ -19,16 +19,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_overview",
     title: "Eagle's-eye snapshot of a business",
-    description: `One-call consolidated read across the whole Meta surface for a business:
-
-- Identity (system user + token app)
-- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
-- Instagram Business accounts linked to those Pages (followers, media_count)
-- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
-- Pixels with last_fired_time (if include_pixels)
-- Catalogs with product counts (if include_catalogs)
-- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
-
+    description: `One-call consolidated read across the whole Meta surface for a business:
+
+- Identity (system user + token app)
+- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
+- Instagram Business accounts linked to those Pages (followers, media_count)
+- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
+- Pixels with last_fired_time (if include_pixels)
+- Catalogs with product counts (if include_catalogs)
+- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
+
 Each section has its own error isolation — one failing asset does not kill the report. Ideal as the opening call for any AI-driven marketing insights conversation.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -110,17 +110,22 @@ export async function handler(input, ctx) {
         wabas,
     ]);
     // Expand each page with linked IG + a small insights fetch.
+    // Page insights require the per-Page access token, so resolve it lazily.
     const pagesExpanded = pagesR.ok && pagesR.data.data
         ? await Promise.all(pagesR.data.data.map(async (p) => {
-            const [igR, insightsR] = await Promise.all([
-                ctx.graph
-                    .get({
-                    path: p.id,
-                    params: { fields: "instagram_business_account{id,username,name,followers_count,media_count}" },
-                })
-                    .then(ok)
-                    .catch(fail),
-                ctx.graph
+            const igR = await ctx.graph
+                .get({
+                path: p.id,
+                params: { fields: "instagram_business_account{id,username,name,followers_count,media_count}" },
+            })
+                .then(ok)
+                .catch(fail);
+            // Resolve Page access token for the insights call. If we can't,
+            // record a per-page error rather than blanking the whole report.
+            let insightsR;
+            try {
+                const pageToken = await ctx.graph.getPageAccessToken(p.id);
+                insightsR = await ctx.graph
                     .get({
                     path: `${p.id}/insights`,
                     params: {
@@ -128,10 +133,14 @@ export async function handler(input, ctx) {
                         metric: "page_impressions,page_post_engagements,page_fans,page_views_total",
                         date_preset: input.date_preset,
                     },
+                    accessTokenOverride: pageToken,
                 })
-                    .then(ok)
-                    .catch(fail),
-            ]);
+                    .then((d) => ok({ data: d.data }))
+                    .catch(fail);
+            }
+            catch (err) {
+                insightsR = fail(err);
+            }
             return {
                 id: p.id,
                 name: p.name,

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 { runGet } from "../shared.js";
+import { runGetAsPage } 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 runGet(ctx, {
+    return runGetAsPage(ctx, input.page_id, {
         path: `${input.page_id}/insights`,
         params: {
             metric: input.metrics.join(","),

package/dist/tools/pages/get-post-insights.d.ts

@@ -2,21 +2,25 @@ import { z } from "zod";
 import type { ToolContext } from "../../context.js";
 export declare const inputSchema: z.ZodObject<{
     post_id: z.ZodString;
+    page_id: z.ZodOptional<z.ZodString>;
     metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     post_id: string;
     metrics: string[];
+    page_id?: string | undefined;
 }, {
     post_id: string;
+    page_id?: string | undefined;
     metrics?: string[] | undefined;
 }>;
 export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {
     readonly name: "meta_page_get_post_insights";
     readonly title: "Get insights for a single Page post";
-    readonly description: "Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post. Requires 'read_insights' scope.";
+    readonly description: "Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post.\n\nUses 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.";
     readonly inputSchema: {
         post_id: z.ZodString;
+        page_id: z.ZodOptional<z.ZodString>;
         metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     };
     readonly annotations: {