@cashtokenai/meta-mcp-server 1.0.0

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

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolError, toolResult } from "../../helpers/format.js";
+import { paginationShape } from "../../helpers/schema.js";
+export const inputSchema = z
+    .object({
+    ...paginationShape,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "verification_status",
+        "primary_page",
+        "created_time",
+        "updated_time",
+        "timezone_id",
+    ])
+        .describe("Fields to request on each business."),
+})
+    .strict();
+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.
+
+Respects META_ALLOWED_BUSINESS_IDS: if set, filters the response to that allowlist.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export async function handler(input, ctx) {
+    try {
+        const params = {
+            fields: input.fields.join(","),
+            limit: input.limit,
+            after: input.after,
+        };
+        const opts = { path: "me/businesses", params };
+        const { data, pages, nextAfter } = input.auto_paginate
+            ? await ctx.graph.getAllPages(opts)
+            : await singlePage(ctx, opts);
+        const allowlist = ctx.config.allowedBusinessIds;
+        const filtered = allowlist ? data.filter((b) => allowlist.has(b.id)) : data;
+        // Sanity-check that whatever survived the allowlist is allowed.
+        for (const b of filtered)
+            assertAllowed("business", b.id, ctx.config);
+        const structured = {
+            count: filtered.length,
+            pages_fetched: pages,
+            next_after: nextAfter,
+            businesses: filtered,
+            filtered_by_allowlist: Boolean(allowlist),
+        };
+        return toolResult(structured, jsonBlock(structured));
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        return toolError(e.message, e.hint, {
+            code: e.code,
+            subcode: e.subcode,
+            fbtrace_id: e.fbtraceId,
+            http_status: e.httpStatus,
+        });
+    }
+}
+async function singlePage(ctx, opts) {
+    const page = await ctx.graph.get(opts);
+    return {
+        data: Array.isArray(page.data) ? page.data : [],
+        pages: 1,
+        nextAfter: page.paging?.cursors?.after,
+    };
+}

package/dist/tools/business/list-system-users.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    business_id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    business_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    after?: string | undefined;
+}, {
+    business_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_business_list_system_users";
+    readonly title: "List system users attached to a business";
+    readonly description: "Lists the system-user (server/software) identities under a Business Manager.\n\nSystem 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).\n\nReads /{business_id}/system_users.";
+    readonly inputSchema: {
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        business_id: z.ZodString;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

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

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolError, toolResult } from "../../helpers/format.js";
+import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
+export const inputSchema = z
+    .object({
+    business_id: metaIdSchema.describe("Business Manager ID."),
+    ...paginationShape,
+    fields: z
+        .array(z.string())
+        .default(["id", "name", "role", "finance_role", "ip_role"])
+        .describe("Fields to return for each system user."),
+})
+    .strict();
+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).
+
+Reads /{business_id}/system_users.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export async function handler(input, ctx) {
+    assertAllowed("business", input.business_id, ctx.config);
+    try {
+        const opts = {
+            path: `${input.business_id}/system_users`,
+            params: {
+                fields: input.fields.join(","),
+                limit: input.limit,
+                after: input.after,
+            },
+        };
+        if (input.auto_paginate) {
+            const { data, pages, nextAfter } = await ctx.graph.getAllPages(opts);
+            const structured = {
+                business_id: input.business_id,
+                count: data.length,
+                pages_fetched: pages,
+                next_after: nextAfter,
+                system_users: data,
+            };
+            return toolResult(structured, jsonBlock(structured));
+        }
+        const page = await ctx.graph.get(opts);
+        const structured = {
+            business_id: input.business_id,
+            count: Array.isArray(page.data) ? page.data.length : 0,
+            pages_fetched: 1,
+            next_after: page.paging?.cursors?.after,
+            system_users: page.data ?? [],
+        };
+        return toolResult(structured, jsonBlock(structured));
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        return toolError(e.message, e.hint, {
+            code: e.code,
+            subcode: e.subcode,
+            fbtrace_id: e.fbtraceId,
+            http_status: e.httpStatus,
+        });
+    }
+}

package/dist/tools/catalog/get-diagnostics.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    catalog_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    catalog_id: string;
+}, {
+    catalog_id: string;
+    fields?: string[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_catalog_get_diagnostics";
+    readonly title: "Get catalog diagnostics";
+    readonly description: "Surfaces catalog issues: disapproved items, missing required fields, GTIN problems, image errors. Pair with meta_catalog_list_products to see affected items.";
+    readonly inputSchema: {
+        catalog_id: z.ZodString;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/catalog/get-diagnostics.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { metaIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+export const inputSchema = z
+    .object({
+    catalog_id: metaIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "diagnostics{severity,type,title,description,affected_items,affected_channels}",
+        "product_count",
+        "feed_count",
+    ])
+        .describe("Diagnostics fields. Meta surfaces issues like missing images, disapproved items, incomplete GTIN, etc."),
+})
+    .strict();
+export const definition = {
+    name: "meta_catalog_get_diagnostics",
+    title: "Get catalog diagnostics",
+    description: `Surfaces catalog issues: disapproved items, missing required fields, GTIN problems, image errors. Pair with meta_catalog_list_products to see affected items.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runGet(ctx, { path: input.catalog_id, params: { fields: input.fields.join(",") } });
+}

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

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    catalog_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    filter: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    catalog_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    filter?: string | undefined;
+    after?: string | undefined;
+}, {
+    catalog_id: string;
+    fields?: string[] | undefined;
+    filter?: string | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_catalog_list_products";
+    readonly title: "List products in a catalog";
+    readonly description: "Lists products with name, retailer_id, price, availability, review_status. Filter by availability/category via the 'filter' param (raw JSON string per Meta spec).";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        catalog_id: z.ZodString;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        filter: z.ZodOptional<z.ZodString>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/catalog/list-products.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    catalog_id: metaIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "retailer_id",
+        "name",
+        "description",
+        "price",
+        "currency",
+        "availability",
+        "condition",
+        "brand",
+        "category",
+        "url",
+        "image_url",
+        "review_status",
+    ])
+        .describe("Product fields."),
+    filter: z
+        .string()
+        .optional()
+        .describe("JSON filter string, e.g. '{\"availability\":{\"eq\":\"out of stock\"}}'"),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_catalog_list_products",
+    title: "List products in a catalog",
+    description: `Lists products with name, retailer_id, price, availability, review_status. Filter by availability/category via the 'filter' param (raw JSON string per Meta spec).`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runList(ctx, {
+        path: `${input.catalog_id}/products`,
+        params: {
+            fields: input.fields.join(","),
+            limit: input.limit,
+            after: input.after,
+            filter: input.filter,
+        },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { catalog_id: input.catalog_id });
+}

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

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    business_id: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<["owned", "client", "both"]>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    business_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    scope: "owned" | "client" | "both";
+    after?: string | undefined;
+}, {
+    business_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+    scope?: "owned" | "client" | "both" | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_catalog_list";
+    readonly title: "List commerce catalogs under a business";
+    readonly description: "Lists product catalogs. Needs the Commerce / Catalog Management product added to the app and 'catalog_management' on the token.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        business_id: z.ZodString;
+        scope: z.ZodDefault<z.ZodEnum<["owned", "client", "both"]>>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        business_id: string;
+        sections: Record<string, unknown>[];
+    };
+}>;

package/dist/tools/catalog/list.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    business_id: metaIdSchema,
+    scope: z.enum(["owned", "client", "both"]).default("owned"),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "vertical",
+        "product_count",
+        "business",
+        "is_catalog_segment",
+        "feed_count",
+    ])
+        .describe("Catalog fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_catalog_list",
+    title: "List commerce catalogs under a business",
+    description: `Lists product catalogs. Needs the Commerce / Catalog Management product added to the app and 'catalog_management' on the token.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    assertAllowed("business", input.business_id, ctx.config);
+    const edges = input.scope === "both"
+        ? ["owned_product_catalogs", "client_product_catalogs"]
+        : [`${input.scope}_product_catalogs`];
+    const sections = [];
+    for (const edge of edges) {
+        const r = await runList(ctx, {
+            path: `${input.business_id}/${edge}`,
+            params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
+        }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { edge });
+        sections.push(r.structuredContent ?? { edge, error: "no data" });
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ business_id: input.business_id, sections }, null, 2) }],
+        structuredContent: { business_id: input.business_id, sections },
+    };
+}

package/dist/tools/instagram/get-account.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    ig_user_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    ig_user_id: string;
+}, {
+    ig_user_id: string;
+    fields?: string[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ig_get_account";
+    readonly title: "Get Instagram Business account profile";
+    readonly description: "Reads username, name, bio, website, follower/following counts, media_count, profile picture for an IG Business account.";
+    readonly inputSchema: {
+        ig_user_id: z.ZodString;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/instagram/get-account.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { metaIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ig_user_id: metaIdSchema.describe("Instagram Business Account ID (from meta_ig_list_accounts)."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "username",
+        "name",
+        "biography",
+        "website",
+        "followers_count",
+        "follows_count",
+        "media_count",
+        "profile_picture_url",
+    ])
+        .describe("IG account profile fields."),
+})
+    .strict();
+export const definition = {
+    name: "meta_ig_get_account",
+    title: "Get Instagram Business account profile",
+    description: `Reads username, name, bio, website, follower/following counts, media_count, profile picture for an IG Business account.`,
+    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, { path: input.ig_user_id, params: { fields: input.fields.join(",") } });
+}

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

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    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"]>>;
+}, "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;
+}>;
+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\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: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

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

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { metaIdSchema } from "../../helpers/schema.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
+    .object({
+    ig_user_id: metaIdSchema,
+    metric: z
+        .enum([
+        "follower_demographics",
+        "engaged_audience_demographics",
+        "reached_audience_demographics",
+    ])
+        .default("follower_demographics")
+        .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")
+        .describe("Required for demographics metrics."),
+})
+    .strict();
+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.
+
+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 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.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    media_id: z.ZodString;
+    metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    media_id: string;
+    metrics: string[];
+}, {
+    media_id: string;
+    metrics?: string[] | undefined;
+}>;
+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, 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">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;