@praise25/meta-mcp-server 0.1.0 → 0.1.2

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

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/helpers/validate.d.ts

@@ -0,0 +1,26 @@
+import { z, type ZodTypeAny } from "zod";
+import { type ToolTextResult } from "./format.js";
+/** Walk an arbitrary value and collect any string leaves that look like placeholders. */
+export declare function findPlaceholders(value: unknown, path?: (string | number)[]): {
+    path: (string | number)[];
+    value: string;
+}[];
+/**
+ * Defence-in-depth input validator. Wraps a Zod object schema and:
+ *   1. Detects placeholder strings (e.g. literal "<YOUR_PAGE_ID>") with a
+ *      friendly tool error explaining the AI must substitute real values.
+ *   2. Runs full Zod validation including refinements (regex, min/max, etc.).
+ *   3. Returns a structured ToolError on failure rather than throwing,
+ *      so the AI gets actionable feedback instead of an opaque crash.
+ *
+ * Why this exists: some MCP gateways forward inputs to handlers without
+ * enforcing per-property Zod refinements. Without this guard, a placeholder
+ * like "act_<YOUR_PAGE_ID>" would reach Meta's API and waste a round trip.
+ */
+export declare function validateInput<T extends ZodTypeAny>(schema: T, args: unknown): {
+    ok: true;
+    data: z.infer<T>;
+} | {
+    ok: false;
+    error: ToolTextResult;
+};

package/dist/helpers/validate.js

@@ -0,0 +1,82 @@
+import { toolError } from "./format.js";
+/**
+ * Heuristics for spotting placeholder strings the AI may pass without
+ * substituting a real value:
+ *   - Anything wrapped in angle brackets, e.g. "<YOUR_PAGE_ID>", "<id>"
+ *   - Strings starting with `YOUR_`, `MY_`, `EXAMPLE_`
+ *   - Strings ending with `_HERE`, `_PLACEHOLDER`
+ *   - The literal strings "string", "id", "number" (when inside a regex slot)
+ */
+const PLACEHOLDER_PATTERNS = [
+    /<[^>]{1,80}>/,
+    /^YOUR[_\s-]/i,
+    /^MY[_\s-]/i,
+    /^EXAMPLE[_\s-]/i,
+    /[_\s-]HERE$/i,
+    /[_\s-]PLACEHOLDER$/i,
+    /^TODO$/i,
+    /^FIXME$/i,
+];
+/** Walk an arbitrary value and collect any string leaves that look like placeholders. */
+export function findPlaceholders(value, path = []) {
+    const hits = [];
+    if (value == null)
+        return hits;
+    if (typeof value === "string") {
+        if (PLACEHOLDER_PATTERNS.some((rx) => rx.test(value))) {
+            hits.push({ path, value });
+        }
+        return hits;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => hits.push(...findPlaceholders(v, [...path, i])));
+        return hits;
+    }
+    if (typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            hits.push(...findPlaceholders(v, [...path, k]));
+        }
+    }
+    return hits;
+}
+function formatPath(p) {
+    return p.length ? p.join(".") : "(root)";
+}
+/**
+ * Defence-in-depth input validator. Wraps a Zod object schema and:
+ *   1. Detects placeholder strings (e.g. literal "<YOUR_PAGE_ID>") with a
+ *      friendly tool error explaining the AI must substitute real values.
+ *   2. Runs full Zod validation including refinements (regex, min/max, etc.).
+ *   3. Returns a structured ToolError on failure rather than throwing,
+ *      so the AI gets actionable feedback instead of an opaque crash.
+ *
+ * Why this exists: some MCP gateways forward inputs to handlers without
+ * enforcing per-property Zod refinements. Without this guard, a placeholder
+ * like "act_<YOUR_PAGE_ID>" would reach Meta's API and waste a round trip.
+ */
+export function validateInput(schema, args) {
+    const placeholders = findPlaceholders(args);
+    if (placeholders.length > 0) {
+        const summary = placeholders
+            .map((p) => `${formatPath(p.path)} = ${JSON.stringify(p.value)}`)
+            .join("; ");
+        return {
+            ok: false,
+            error: toolError(`Input contains placeholder values that were not substituted: ${summary}`, `Replace placeholders with real IDs / values before retrying. Examples for this server: business_id "133767790806312"; ad_account_id "act_146517954996436"; page_id "138368686823692". If you don't know the correct ID, call meta_business_list_assets first to discover available assets.`, { placeholders }),
+        };
+    }
+    const parsed = schema.safeParse(args);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((iss) => ({
+            path: formatPath(iss.path),
+            message: iss.message,
+            code: iss.code,
+        }));
+        const summary = issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+        return {
+            ok: false,
+            error: toolError(`Invalid input: ${summary}`, `Each parameter has its own format requirement (regex, enum, min/max). See the tool's inputSchema description for the exact expectations.`, { issues }),
+        };
+    }
+    return { ok: true, data: parsed.data };
+}

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

@@ -28,7 +28,12 @@ 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.
 
-Requires 'instagram_manage_insights'. Only IG Business accounts with at least 100 followers return data — below that threshold Meta returns empty results for privacy.`,
+**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/overview/business-overview.js

@@ -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: {

package/dist/tools/pages/get-post-insights.js

@@ -1,9 +1,12 @@
 import { z } from "zod";
 import { metaIdSchema } from "../../helpers/schema.js";
-import { runGet } from "../shared.js";
+import { errorResult, runGetAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
-    post_id: metaIdSchema.describe("Post ID (format '{page_id}_{post_id}' or shortform)."),
+    post_id: metaIdSchema.describe("Post ID. Meta uses the '{page_id}_{post_id}' format — pass it in full so the server can resolve the parent Page's access token automatically."),
+    page_id: metaIdSchema
+        .optional()
+        .describe("Optional explicit Page ID. Use when the post_id is not in the '{page_id}_{post_id}' form (rare)."),
     metrics: z
         .array(z.string())
         .default([
@@ -18,18 +21,26 @@ export const inputSchema = z
         "post_video_views_unique",
         "post_video_avg_time_watched",
     ])
-        .describe("Post-level insight metrics. See https://developers.facebook.com/docs/graph-api/reference/v23.0/insights"),
+        .describe("Post-level insight metrics. See https://developers.facebook.com/docs/graph-api/reference/v23.0/insights. Requires 'read_insights' scope. Note: Meta will reject the call if any single metric is invalid for the post type — narrow the list if you see (#100)."),
 })
     .strict();
 export const definition = {
     name: "meta_page_get_post_insights",
     title: "Get insights for a single Page post",
-    description: `Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post. Requires 'read_insights' scope.`,
+    description: `Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post.
+
+Uses the parent Page's access token (auto-resolved from the '{page_id}_{post_id}' prefix; pass page_id explicitly if your post_id isn't in that form). Requires the system user to be assigned to the Page with 'View performance' or 'Analyze Page' tasks, plus 'read_insights' scope on the token.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 };
 export async function handler(input, ctx) {
-    return runGet(ctx, {
+    // Resolve the parent Page id either from an explicit input or from the
+    // '{page_id}_{post_id}' prefix of the post_id.
+    const parentPageId = input.page_id ?? input.post_id.split("_")[0];
+    if (!/^\d+$/.test(parentPageId)) {
+        return errorResult(new Error(`Could not infer parent Page ID from post_id '${input.post_id}'. Pass page_id explicitly.`));
+    }
+    return runGetAsPage(ctx, parentPageId, {
         path: `${input.post_id}/insights`,
         params: { metric: input.metrics.join(",") },
     });

package/dist/tools/pages/list-posts.d.ts

@@ -20,9 +20,9 @@ export declare const inputSchema: z.ZodObject<{
     after?: string | undefined;
 }, {
     page_id: string;
+    fields?: string[] | undefined;
     since?: string | undefined;
     until?: string | undefined;
-    fields?: string[] | undefined;
     limit?: number | undefined;
     after?: string | undefined;
     auto_paginate?: boolean | undefined;

package/dist/tools/pages/list-posts.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assertAllowed } from "../../config.js";
 import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
-import { runList } from "../shared.js";
+import { runListAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
     page_id: metaIdSchema,
@@ -14,21 +14,25 @@ export const inputSchema = z
     fields: z
         .array(z.string())
         .default([
+        // Note: 'subattachments' is deprecated as of Graph API v3.3+ for
+        // aggregate field expansion (#12 deprecate_post_aggregated_fields_for_attachement).
+        // Removed from default. Likewise 'is_published' and 'type' are
+        // deprecated for some post kinds — kept out of the default to keep
+        // the call shape valid across all post types. Re-add via the fields
+        // input if you need them and have verified the call still passes.
         "id",
         "message",
         "created_time",
         "updated_time",
         "permalink_url",
         "status_type",
-        "type",
-        "is_published",
         "from",
-        "attachments{media_type,title,url,subattachments}",
+        "attachments{media_type,title,url}",
         "reactions.summary(true).limit(0)",
         "shares",
         "comments.summary(true).limit(0)",
     ])
-        .describe("Post fields. Default includes reaction + comment counts via summary."),
+        .describe("Post fields. Default includes reaction + comment counts via summary. 'subattachments', 'is_published' and 'type' are excluded by default — Meta deprecated them on certain post types and including them rejects the whole call."),
     ...paginationShape,
 })
     .strict();
@@ -41,7 +45,9 @@ export const definition = {
 };
 export async function handler(input, ctx) {
     assertAllowed("page", input.page_id, ctx.config);
-    return runList(ctx, {
+    // Page-level edges (/posts, /published_posts, /feed) require a Page access
+    // token, not the system-user token. runListAsPage resolves it first.
+    return runListAsPage(ctx, input.page_id, {
         path: `${input.page_id}/${input.edge}`,
         params: {
             fields: input.fields.join(","),

package/dist/tools/pages/list-reviews.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assertAllowed } from "../../config.js";
 import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
-import { runList } from "../shared.js";
+import { runListAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
     page_id: metaIdSchema,
@@ -30,7 +30,7 @@ export const definition = {
 };
 export async function handler(input, ctx) {
     assertAllowed("page", input.page_id, ctx.config);
-    return runList(ctx, {
+    return runListAsPage(ctx, input.page_id, {
         path: `${input.page_id}/ratings`,
         params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
     }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { page_id: input.page_id });

package/dist/tools/pages/list-videos.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assertAllowed } from "../../config.js";
 import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
-import { runList } from "../shared.js";
+import { runListAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
     page_id: metaIdSchema,
@@ -33,7 +33,7 @@ export const definition = {
 };
 export async function handler(input, ctx) {
     assertAllowed("page", input.page_id, ctx.config);
-    return runList(ctx, {
+    return runListAsPage(ctx, input.page_id, {
         path: `${input.page_id}/videos`,
         params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
     }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { page_id: input.page_id });

package/dist/tools/pixels/list.js

@@ -8,17 +8,20 @@ export const inputSchema = z
     fields: z
         .array(z.string())
         .default([
+        // 'code' (the pixel's JS snippet) and 'owner_ad_account' both require
+        // ads_management on the *owning* ad account, not just the business.
+        // Reading them with a system-user token that wasn't granted that
+        // task fails the whole list with (#200). We omit them from the
+        // defaults so the list stays useful; callers can re-add explicitly.
         "id",
         "name",
-        "code",
         "is_created_by_business",
         "is_unavailable",
         "last_fired_time",
         "creation_time",
-        "owner_ad_account",
         "owner_business",
     ])
-        .describe("Pixel fields."),
+        .describe("Pixel fields. 'code' and 'owner_ad_account' are NOT in the default — they require ads_management on the owning ad account. Re-add them only when the system user has that task on every pixel's owner account."),
     ...paginationShape,
 })
     .strict();

package/dist/tools/register.js

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import { validateInput } from "../helpers/validate.js";
 // Token + meta
 import * as tokenInspect from "./token/inspect.js";
 import * as tokenHealth from "./token/health.js";
@@ -74,7 +76,16 @@ export function registerTools(server, ctx) {
             inputSchema: mod.definition.inputSchema,
             annotations: mod.definition.annotations,
         }, (async (args) => {
-            return mod.handler(args, ctx);
+            // Defense in depth: re-validate at the handler boundary even if the
+            // SDK / MCP gateway already did. Some gateways forward inputs without
+            // enforcing per-property Zod refinements (e.g. regex on ad_account_id),
+            // which would otherwise let placeholder strings like "act_<YOUR_PAGE_ID>"
+            // reach Meta. See ADR-20260429-Handler-Input-Validation.md.
+            const validated = validateInput(mod.inputSchema ?? z.object(mod.definition.inputSchema), args);
+            if (!validated.ok) {
+                return validated.error;
+            }
+            return mod.handler(validated.data, ctx);
         }));
         names.push(mod.definition.name);
     }

package/dist/tools/shared.d.ts

@@ -18,3 +18,13 @@ export declare function runList<T>(ctx: ToolContext, opts: GraphGetOptions, pag:
 /** Run a single read and return a tool result. */
 export declare function runGet<T>(ctx: ToolContext, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
 export declare function errorResult(err: unknown): ToolTextResult;
+/**
+ * Resolves a Page access token for `pageId`, then runs `runList` with it as
+ * the access-token override. Page-level edges (`/{page_id}/posts`,
+ * `/{page_id}/insights`, `/{page_id}/ratings`, `/{page_id}/videos`,
+ * `/{post_id}/insights`) require a Page access token rather than the
+ * configured system-user token.
+ */
+export declare function runListAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, pag: ListRunOpts, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/** Same as runGet but resolves and uses the Page access token first. */
+export declare function runGetAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;

package/dist/tools/shared.js

@@ -53,3 +53,29 @@ export function errorResult(err) {
         retryable: e.retryable,
     });
 }
+/**
+ * Resolves a Page access token for `pageId`, then runs `runList` with it as
+ * the access-token override. Page-level edges (`/{page_id}/posts`,
+ * `/{page_id}/insights`, `/{page_id}/ratings`, `/{page_id}/videos`,
+ * `/{post_id}/insights`) require a Page access token rather than the
+ * configured system-user token.
+ */
+export async function runListAsPage(ctx, pageId, opts, pag, extra = {}) {
+    try {
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runList(ctx, { ...opts, accessTokenOverride: pageToken }, pag, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+/** Same as runGet but resolves and uses the Page access token first. */
+export async function runGetAsPage(ctx, pageId, opts, extra = {}) {
+    try {
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runGet(ctx, { ...opts, accessTokenOverride: pageToken }, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}

package/dist/tools/whatsapp/list-templates.d.ts

@@ -16,8 +16,8 @@ export declare const inputSchema: z.ZodObject<{
     after?: string | undefined;
 }, {
     waba_id: string;
-    status?: "PAUSED" | "DELETED" | "APPROVED" | "PENDING" | "REJECTED" | "DISABLED" | "IN_APPEAL" | undefined;
     fields?: string[] | undefined;
+    status?: "PAUSED" | "DELETED" | "APPROVED" | "PENDING" | "REJECTED" | "DISABLED" | "IN_APPEAL" | undefined;
     limit?: number | undefined;
     after?: string | undefined;
     auto_paginate?: boolean | undefined;

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.0",
+  "version": "0.1.2",
   "author": "Stephen A.",
   "license": "MIT",
   "homepage": "https://github.com/feladeveloper/meta-mcp-server#readme",
@@ -52,8 +52,11 @@
     "inspect": "npm run build && npx @modelcontextprotocol/inspector dist/index.js",
     "check:types": "tsc --noEmit --project tsconfig.json",
     "test:readonly": "npm run build && node tests/read-only-guard.mjs",
+    "test:placeholder": "npm run build && node tests/placeholder-rejection.mjs",
+    "test:invariants": "npm run test:readonly && npm run test:placeholder",
+    "test:scenarios": "npm run build && node tests/scenarios.mjs",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "prepublishOnly": "npm run check:types && npm run test:readonly"
+    "prepublishOnly": "npm run check:types && npm run test:invariants"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.2",