@praise25/meta-mcp-server 0.1.8 → 0.1.11

package/dist/config.d.ts

@@ -1,6 +1,17 @@
 export interface Config {
     accessToken: string;
     appSecret: string | undefined;
+    /**
+     * Optional secondary "insights app" credentials. Meta's app-type rules
+     * forbid combining the Marketing-API use case with the Instagram-content /
+     * Pages-everything use cases on a single app. When insights endpoints
+     * (IG media/audience insights, Page/post insights) live on a *different*
+     * Meta app than the primary (ads) app, set these so those specific calls
+     * route through the second app's token + secret. Leave unset to use the
+     * primary token for everything (single-app deployments).
+     */
+    insightsAccessToken: string | undefined;
+    insightsAppSecret: string | undefined;
     apiVersion: string;
     httpTimeoutMs: number;
     cacheTtlSeconds: number;
@@ -11,5 +22,18 @@ export interface Config {
     allowedIgUserIds: Set<string> | null;
     logLevel: string;
 }
+/**
+ * Credentials for a single Meta app: an access token plus the app secret used
+ * to compute the request's `appsecret_proof`. Returned by `insightsCreds()`.
+ */
+export interface AppCreds {
+    token: string;
+    appSecret: string | undefined;
+}
+/**
+ * Returns the secondary insights-app credentials when configured, otherwise
+ * null. Insight tools call this; null means "fall back to the primary token".
+ */
+export declare function insightsCreds(config: Config): AppCreds | null;
 export declare function loadConfig(): Config;
 export declare function assertAllowed(kind: "business" | "ad_account" | "page" | "ig_user", id: string, config: Config): void;

package/dist/config.js

@@ -1,4 +1,16 @@
 import { DEFAULT_API_VERSION } from "./constants.js";
+/**
+ * Returns the secondary insights-app credentials when configured, otherwise
+ * null. Insight tools call this; null means "fall back to the primary token".
+ */
+export function insightsCreds(config) {
+    if (!config.insightsAccessToken)
+        return null;
+    return {
+        token: config.insightsAccessToken,
+        appSecret: config.insightsAppSecret,
+    };
+}
 function parseAllowlist(raw) {
     if (!raw || !raw.trim())
         return null;
@@ -22,6 +34,8 @@ export function loadConfig() {
     return {
         accessToken,
         appSecret: process.env.META_APP_SECRET?.trim() || undefined,
+        insightsAccessToken: process.env.META_INSIGHTS_ACCESS_TOKEN?.trim() || undefined,
+        insightsAppSecret: process.env.META_INSIGHTS_APP_SECRET?.trim() || undefined,
         apiVersion: process.env.META_API_VERSION?.trim() || DEFAULT_API_VERSION,
         httpTimeoutMs: parseNumber(process.env.META_HTTP_TIMEOUT_MS, 30_000),
         cacheTtlSeconds: parseNumber(process.env.META_CACHE_TTL_SECONDS, 120),

package/dist/constants.d.ts

@@ -4,7 +4,7 @@ export declare const CHARACTER_LIMIT = 25000;
 export declare const DEFAULT_PAGE_LIMIT = 25;
 export declare const MAX_PAGE_LIMIT = 500;
 export declare const SERVER_NAME = "meta-business-manager-mcp-server";
-export declare const SERVER_VERSION = "0.1.8";
+export declare const SERVER_VERSION = "0.1.11";
 export declare const META_ERROR_CODES: {
     readonly UNKNOWN: 1;
     readonly SERVICE_TEMPORARILY_UNAVAILABLE: 2;

package/dist/constants.js

@@ -4,7 +4,7 @@ export const CHARACTER_LIMIT = 25_000;
 export const DEFAULT_PAGE_LIMIT = 25;
 export const MAX_PAGE_LIMIT = 500;
 export const SERVER_NAME = "meta-business-manager-mcp-server";
-export const SERVER_VERSION = "0.1.8";
+export const SERVER_VERSION = "0.1.11";
 export const META_ERROR_CODES = {
     UNKNOWN: 1,
     SERVICE_TEMPORARILY_UNAVAILABLE: 2,

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

@@ -19,6 +19,13 @@ export interface GraphGetOptions {
      * binding to the app remains intact.
      */
     accessTokenOverride?: string;
+    /**
+     * Override the app secret used to compute `appsecret_proof` for this call.
+     * Required when `accessTokenOverride` is a token issued by a *different*
+     * Meta app (e.g. the secondary "insights app"), because the proof must be
+     * HMAC(token, that app's secret). Defaults to the primary app secret.
+     */
+    appSecretOverride?: string;
 }
 export interface GraphPagedResponse<T = unknown> {
     data: T[];
@@ -60,7 +67,10 @@ export declare class GraphClient {
      * 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>;
+    getPageAccessToken(pageId: string, creds?: {
+        token: string;
+        appSecret: string | undefined;
+    }): 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

@@ -51,10 +51,13 @@ export class GraphClient {
      * Requires the configured system user to be assigned to the Page with
      * at least the "View performance" or "Analyze Page" task.
      */
-    async getPageAccessToken(pageId) {
+    async getPageAccessToken(pageId, creds) {
         if (!pageId)
             throw new MetaError("getPageAccessToken: pageId is required");
-        const cached = this.pageTokens.get(pageId);
+        // Cache key namespaces by the issuing app so a Page token derived from the
+        // primary app and one derived from the secondary insights app never collide.
+        const cacheKey = creds ? `insights:${pageId}` : pageId;
+        const cached = this.pageTokens.get(cacheKey);
         if (cached)
             return cached;
         const resp = await this.get({
@@ -63,20 +66,22 @@ export class GraphClient {
             // 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,
+            accessTokenOverride: creds?.token,
+            appSecretOverride: creds?.appSecret,
         });
         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);
+        this.pageTokens.set(cacheKey, 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, opts.accessTokenOverride);
+        const params = this.buildParams(opts.params, opts.accessTokenOverride, opts.appSecretOverride);
         const cacheKey = this.cacheKeyFor(url, params);
         if (!opts.noCache) {
             const cached = this.cache.get(cacheKey);
@@ -106,11 +111,12 @@ export class GraphClient {
                 collected.push(...page.data);
             nextAfter = page.paging?.cursors?.after;
             if (page.paging?.next && pages < cap) {
-                // Propagate the original accessTokenOverride to subsequent pages —
-                // optsFromNextUrl strips access_token from the URL but the override
-                // (if any) must continue to be applied.
+                // Propagate the original token + app-secret overrides to subsequent
+                // pages — optsFromNextUrl strips credentials from the URL but the
+                // overrides (if any) must continue to be applied.
                 const next = this.optsFromNextUrl(page.paging.next);
                 next.accessTokenOverride = opts.accessTokenOverride;
+                next.appSecretOverride = opts.appSecretOverride;
                 currentOpts = next;
             }
             else {
@@ -132,7 +138,7 @@ export class GraphClient {
         }
         return { path, params, apiVersion: version };
     }
-    buildParams(params, accessTokenOverride) {
+    buildParams(params, accessTokenOverride, appSecretOverride) {
         const out = {};
         for (const [k, v] of Object.entries(params ?? {})) {
             if (v === undefined || v === null)
@@ -140,19 +146,21 @@ export class GraphClient {
             out[k] = v;
         }
         const token = accessTokenOverride ?? this.config.accessToken;
+        // The app secret must match the app that ISSUED the token. For a
+        // secondary-app token, the caller passes appSecretOverride; otherwise we
+        // fall back to the primary app secret.
+        const appSecret = appSecretOverride ?? this.config.appSecret;
         out.access_token = token;
-        if (this.config.appSecret) {
-            out.appsecret_proof = this.appsecretProof(token);
+        if (appSecret) {
+            out.appsecret_proof = this.appsecretProof(token, appSecret);
         }
         return out;
     }
-    appsecretProof(token) {
+    appsecretProof(token, appSecret) {
         // 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(token ?? this.config.accessToken)
-            .digest("hex");
+        // Recompute against whichever (token, app-secret) pair is in use —
+        // primary system-user token, Page token, or a secondary-app token.
+        return crypto.createHmac("sha256", appSecret).update(token).digest("hex");
     }
     cacheKeyFor(url, params) {
         const { access_token: _at, appsecret_proof: _ap, ...rest } = params;

package/dist/server.js

@@ -2,11 +2,31 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createContext } from "./context.js";
 import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
 import { registerTools } from "./tools/register.js";
+/**
+ * Server-level routing guidance surfaced to MCP clients via the SDK's
+ * `instructions` field. Gateways that inject server instructions into the
+ * model's system prompt use this to pick the right tool without the user
+ * having to fine-tune their phrasing. Keep it short, imperative, and focused
+ * on the question-classes users actually ask.
+ */
+const SERVER_INSTRUCTIONS = `This server exposes READ-ONLY Meta Business Manager analytics (Facebook Pages, Instagram, ads, pixels, catalog, WhatsApp).
+
+TOOL ROUTING — pick the broadest matching tool and CALL IT. Never tell the user to rephrase, and never ask for IDs the server can discover itself:
+
+- "How is my marketing doing / give me an overview / snapshot" → meta_business_overview (no business_id needed; it auto-discovers).
+- "How did my LATEST / most recent post do" → meta_latest_posts_summary.
+- "How many posts in the last week / this month, by type, performance comparison, content report, trend" → meta_content_report (takes a date window).
+- "Audience demographics / age / gender / country / city breakdown" → meta_ig_get_audience_demographics.
+- "Ad spend / campaign performance / CTR / CPC / ROAS / which ad/campaign" → meta_ads_get_insights (level=account|campaign|adset|ad, with breakdowns).
+- "What assets / pages / accounts do I have" → meta_business_list_assets.
+- Unsure which asset ID to use → call a discovery/report tool first (they auto-discover); do NOT guess placeholder IDs.
+
+If a tool returns a (#10)/(#200) permission error, relay its 'hint' to the user verbatim — it names the exact Meta App Review or scope action needed. Prefer the report/overview tools (one call) over chaining several low-level tools.`;
 export function buildServer(config, logger) {
     const server = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION,
-    });
+    }, { instructions: SERVER_INSTRUCTIONS });
     const ctx = createContext(config, logger);
     const toolNames = registerTools(server, ctx);
     logger.info({ tools: toolNames, count: toolNames.length }, "tools registered");

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

@@ -82,7 +82,7 @@ export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {
     readonly name: "meta_ads_get_insights";
     readonly title: "Get Marketing API insights (the workhorse)";
-    readonly description: "Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.\n\nReturns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.\n\nTips for the AI consuming this:\n- Default date_preset is last_30d. Override via date_preset or time_range.\n- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.\n- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.\n- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.\n\nRequires 'ads_read' token scope.";
+    readonly description: "Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.\n\nUSE FOR ad/paid questions: \"how much did I spend\", \"ad spend last 7/30 days\", \"campaign performance\", \"which campaign/ad performed best\", \"CTR / CPC / CPM / ROAS / cost per result\", \"conversions from ads\", \"ad performance comparison\", \"spend by placement / age / gender / country\". This is PAID-ads analytics. For organic post/content performance use meta_content_report; for the latest organic post use meta_latest_posts_summary.\n\nReturns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.\n\nTips for the AI consuming this:\n- Default date_preset is last_30d. Override via date_preset or time_range.\n- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.\n- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.\n- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.\n\nRequires 'ads_read' token scope.";
     readonly inputSchema: {
         limit: z.ZodDefault<z.ZodNumber>;
         after: z.ZodOptional<z.ZodString>;

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

@@ -101,16 +101,18 @@ 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.
+
+USE FOR ad/paid questions: "how much did I spend", "ad spend last 7/30 days", "campaign performance", "which campaign/ad performed best", "CTR / CPC / CPM / ROAS / cost per result", "conversions from ads", "ad performance comparison", "spend by placement / age / gender / country". This is PAID-ads analytics. For organic post/content performance use meta_content_report; for the latest organic post use meta_latest_posts_summary.
+
+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/instagram/get-audience-demographics.d.ts

@@ -5,16 +5,19 @@ export declare const inputSchema: z.ZodObject<{
     metric: z.ZodDefault<z.ZodEnum<["follower_demographics", "engaged_audience_demographics", "reached_audience_demographics"]>>;
     breakdown: z.ZodDefault<z.ZodEnum<["age", "gender", "country", "city", "audience_city"]>>;
     metric_type: z.ZodDefault<z.ZodEnum<["total_value", "time_series"]>>;
+    period: z.ZodDefault<z.ZodEnum<["lifetime", "day"]>>;
     timeframe: z.ZodDefault<z.ZodEnum<["last_14_days", "last_30_days", "last_90_days", "prev_month", "this_month", "this_week"]>>;
 }, "strict", z.ZodTypeAny, {
     ig_user_id: string;
     metric: "follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics";
+    period: "day" | "lifetime";
     breakdown: "age" | "gender" | "country" | "city" | "audience_city";
     metric_type: "total_value" | "time_series";
     timeframe: "this_month" | "last_14_days" | "last_30_days" | "last_90_days" | "prev_month" | "this_week";
 }, {
     ig_user_id: string;
     metric?: "follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics" | undefined;
+    period?: "day" | "lifetime" | undefined;
     breakdown?: "age" | "gender" | "country" | "city" | "audience_city" | undefined;
     metric_type?: "total_value" | "time_series" | undefined;
     timeframe?: "this_month" | "last_14_days" | "last_30_days" | "last_90_days" | "prev_month" | "this_week" | undefined;
@@ -23,12 +26,13 @@ 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\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 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\nUSE FOR: \"audience demographics\", \"age / gender / country / city breakdown of my followers\", \"who follows me\", \"audience profile\".\n\nRequirements:\n1. Token has 'instagram_manage_insights' scope (the insights app / META_INSIGHTS_* token).\n2. The IG Business account must have ≥ 100 followers — below that Meta returns empty for privacy.\n3. Meta requires period='lifetime' for demographics metrics (sent automatically by this tool).\n\nIf you see '(#10) Application does not have permission', the configured app lacks instagram_manage_insights — relay the hint. If you see '(#100) period is required', upgrade the server (fixed in v0.1.11+).";
     readonly inputSchema: {
         ig_user_id: z.ZodString;
         metric: z.ZodDefault<z.ZodEnum<["follower_demographics", "engaged_audience_demographics", "reached_audience_demographics"]>>;
         breakdown: z.ZodDefault<z.ZodEnum<["age", "gender", "country", "city", "audience_city"]>>;
         metric_type: z.ZodDefault<z.ZodEnum<["total_value", "time_series"]>>;
+        period: z.ZodDefault<z.ZodEnum<["lifetime", "day"]>>;
         timeframe: z.ZodDefault<z.ZodEnum<["last_14_days", "last_30_days", "last_90_days", "prev_month", "this_month", "this_week"]>>;
     };
     readonly annotations: {

package/dist/tools/instagram/get-audience-demographics.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 { runGetViaInsightsApp } from "../shared.js";
 const METRIC_TYPE = z.enum(["total_value", "time_series"]);
 const BREAKDOWN = z.enum(["age", "gender", "country", "city", "audience_city"]);
 export const inputSchema = z
@@ -17,6 +17,10 @@ export const inputSchema = z
         .describe("Which audience cohort."),
     breakdown: BREAKDOWN.default("age").describe("Demographic dimension."),
     metric_type: METRIC_TYPE.default("total_value"),
+    period: z
+        .enum(["lifetime", "day"])
+        .default("lifetime")
+        .describe("Required by Meta for demographics metrics — almost always 'lifetime'. Omitting it triggers '(#100) The parameter period is required'."),
     timeframe: z
         .enum(["last_14_days", "last_30_days", "last_90_days", "prev_month", "this_month", "this_week"])
         .default("last_30_days")
@@ -26,23 +30,26 @@ 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.
-
-**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.`,
+    description: `Reads demographic breakdown of an IG Business account's followers, engaged audience, or reached audience. Use breakdown='age'|'gender'|'country'|'city' to slice.
+
+USE FOR: "audience demographics", "age / gender / country / city breakdown of my followers", "who follows me", "audience profile".
+
+Requirements:
+1. Token has 'instagram_manage_insights' scope (the insights app / META_INSIGHTS_* token).
+2. The IG Business account must have ≥ 100 followers — below that Meta returns empty for privacy.
+3. Meta requires period='lifetime' for demographics metrics (sent automatically by this tool).
+
+If you see '(#10) Application does not have permission', the configured app lacks instagram_manage_insights — relay the hint. If you see '(#100) period is required', upgrade the server (fixed in v0.1.11+).`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 };
 export async function handler(input, ctx) {
     assertAllowed("ig_user", input.ig_user_id, ctx.config);
-    return runGet(ctx, {
+    return runGetViaInsightsApp(ctx, {
         path: `${input.ig_user_id}/insights`,
         params: {
             metric: input.metric,
+            period: input.period,
             breakdown: input.breakdown,
             metric_type: input.metric_type,
             timeframe: input.timeframe,

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { metaIdSchema } from "../../helpers/schema.js";
-import { runGet } from "../shared.js";
+import { runGetViaInsightsApp } from "../shared.js";
 export const inputSchema = z
     .object({
     media_id: metaIdSchema.describe("IG media ID."),
@@ -25,24 +25,24 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ig_get_media_insights",
     title: "Get Instagram media insights",
-    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)
-
+    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 },
 };
 export async function handler(input, ctx) {
-    return runGet(ctx, {
+    return runGetViaInsightsApp(ctx, {
         path: `${input.media_id}/insights`,
         params: { metric: input.metrics.join(",") },
     });

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

@@ -21,16 +21,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_overview",
     title: "Eagle's-eye snapshot of a business",
-    description: `One-call consolidated read across the whole Meta surface for a business:
-
-- Identity (system user + token app)
-- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
-- Instagram Business accounts linked to those Pages (followers, media_count)
-- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
-- Pixels with last_fired_time (if include_pixels)
-- Catalogs with product counts (if include_catalogs)
-- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
-
+    description: `One-call consolidated read across the whole Meta surface for a business:
+
+- Identity (system user + token app)
+- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
+- Instagram Business accounts linked to those Pages (followers, media_count)
+- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
+- Pixels with last_fired_time (if include_pixels)
+- Catalogs with product counts (if include_catalogs)
+- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
+
 Each section has its own error isolation — one failing asset does not kill the report. Ideal as the opening call for any AI-driven marketing insights conversation.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },