@praise25/meta-mcp-server 0.1.10 → 0.1.11

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.10";
+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.10";
+export const SERVER_VERSION = "0.1.11";
 export const META_ERROR_CODES = {
     UNKNOWN: 1,
     SERVICE_TEMPORARILY_UNAVAILABLE: 2,

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

@@ -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")
@@ -28,12 +32,14 @@ export const definition = {
     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).
+USE FOR: "audience demographics", "age / gender / country / city breakdown of my followers", "who follows me", "audience profile".
 
-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.`,
+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 },
 };
@@ -43,6 +49,7 @@ export async function handler(input, 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/overview/content-report.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@praise25/meta-mcp-server",
   "description": "Read-only Model Context Protocol server for Meta Business Manager — Pages, Instagram, Ads insights, Pixels, Catalog, WhatsApp.",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "author": "Stephen A.",
   "license": "MIT",
   "homepage": "https://github.com/feladeveloper/meta-mcp-server#readme",