@cashtokenai/meta-mcp-server 1.0.0

package/dist/helpers/cache.js

@@ -0,0 +1,28 @@
+import { LRUCache } from "lru-cache";
+class NoopCache {
+    get() {
+        return undefined;
+    }
+    set() {
+        /* noop */
+    }
+    clear() {
+        /* noop */
+    }
+}
+export function createCache(ttlSeconds) {
+    if (ttlSeconds <= 0)
+        return new NoopCache();
+    const cache = new LRUCache({
+        max: 500,
+        ttl: ttlSeconds * 1000,
+    });
+    return {
+        get: (k) => cache.get(k),
+        set: (k, v) => {
+            if (v != null && typeof v === "object")
+                cache.set(k, v);
+        },
+        clear: () => cache.clear(),
+    };
+}

package/dist/helpers/format.d.ts

@@ -0,0 +1,17 @@
+export declare enum ResponseFormat {
+    MARKDOWN = "markdown",
+    JSON = "json"
+}
+export interface ToolTextResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    [k: string]: unknown;
+}
+export declare function jsonBlock(data: unknown): string;
+export declare function truncate(text: string, limit?: number): string;
+export declare function toolResult(structured: Record<string, unknown>, text: string): ToolTextResult;
+export declare function toolError(message: string, hint?: string, extra?: Record<string, unknown>): ToolTextResult;

package/dist/helpers/format.js

@@ -0,0 +1,28 @@
+import { CHARACTER_LIMIT } from "../constants.js";
+export var ResponseFormat;
+(function (ResponseFormat) {
+    ResponseFormat["MARKDOWN"] = "markdown";
+    ResponseFormat["JSON"] = "json";
+})(ResponseFormat || (ResponseFormat = {}));
+export function jsonBlock(data) {
+    return JSON.stringify(data, null, 2);
+}
+export function truncate(text, limit = CHARACTER_LIMIT) {
+    if (text.length <= limit)
+        return text;
+    return `${text.slice(0, limit)}\n\n…[truncated — response exceeded ${limit} characters. Use filters or pagination to narrow results.]`;
+}
+export function toolResult(structured, text) {
+    return {
+        content: [{ type: "text", text: truncate(text) }],
+        structuredContent: structured,
+    };
+}
+export function toolError(message, hint, extra) {
+    const payload = { error: true, message, hint, ...extra };
+    return {
+        content: [{ type: "text", text: jsonBlock(payload) }],
+        structuredContent: payload,
+        isError: true,
+    };
+}

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

@@ -0,0 +1,90 @@
+import type { Config } from "../config.js";
+import type { Logger } from "../logger.js";
+export interface GraphGetOptions {
+    /** Path segments after the API version, e.g. "me/businesses" or "act_123/insights". */
+    path: string;
+    /** Query-string params. `access_token` and `appsecret_proof` are added automatically. */
+    params?: Record<string, string | number | boolean | undefined>;
+    /** Skip cache for this request. */
+    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;
+    /**
+     * 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[];
+    paging?: {
+        cursors?: {
+            before?: string;
+            after?: string;
+        };
+        next?: string;
+        previous?: string;
+    };
+    /** Some endpoints (e.g. /me) return a scalar — preserved on the response object. */
+    [extra: string]: unknown;
+}
+export interface GraphRateLimitHeaders {
+    businessUseCase?: string;
+    adAccountUsage?: string;
+    appUsage?: string;
+}
+export declare class GraphClient {
+    private readonly config;
+    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, 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.
+     * Returns the combined data plus the final cursor so callers can resume.
+     */
+    getAllPages<TItem = unknown>(opts: GraphGetOptions, maxPages?: number): Promise<{
+        data: TItem[];
+        pages: number;
+        nextAfter: string | undefined;
+    }>;
+    private optsFromNextUrl;
+    private buildParams;
+    private appsecretProof;
+    private cacheKeyFor;
+    private requestWithRetry;
+    private captureRateLimit;
+}

package/dist/helpers/graph-client.js

@@ -0,0 +1,219 @@
+import axios from "axios";
+import crypto from "node:crypto";
+import { BASE_RETRY_DELAY_MS, GRAPH_BASE_URL, MAX_RETRIES, } from "../constants.js";
+import { MetaError, ReadOnlyViolationError, normalizeAxiosError } from "../errors.js";
+import { createCache } from "./cache.js";
+export class GraphClient {
+    config;
+    logger;
+    http;
+    cache;
+    pageTokens = new Map();
+    lastRateLimit = {};
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+        this.http = axios.create({
+            baseURL: GRAPH_BASE_URL,
+            timeout: config.httpTimeoutMs,
+            headers: { Accept: "application/json" },
+            // Never follow redirects to non-GET — defence in depth even though we only GET.
+            maxRedirects: 3,
+            validateStatus: () => true, // handle status manually
+        });
+        this.cache = createCache(config.cacheTtlSeconds);
+        // Hard read-only guard — defence in depth. Catches misuse if new code ever
+        // calls http.post/patch/delete directly.
+        this.http.interceptors.request.use((cfg) => {
+            const method = (cfg.method ?? "get").toUpperCase();
+            if (method !== "GET") {
+                throw new ReadOnlyViolationError(method, cfg.url ?? "");
+            }
+            return cfg;
+        });
+    }
+    get rateLimit() {
+        return { ...this.lastRateLimit };
+    }
+    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, creds) {
+        if (!pageId)
+            throw new MetaError("getPageAccessToken: pageId is required");
+        // 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({
+            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,
+            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(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, opts.appSecretOverride);
+        const cacheKey = this.cacheKeyFor(url, params);
+        if (!opts.noCache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached)
+                return cached;
+        }
+        const result = await this.requestWithRetry({ method: "GET", url, params });
+        if (!opts.noCache) {
+            this.cache.set(cacheKey, result);
+        }
+        return result;
+    }
+    /**
+     * Follow `paging.next` cursors and concatenate `data` arrays up to maxPages.
+     * Returns the combined data plus the final cursor so callers can resume.
+     */
+    async getAllPages(opts, maxPages) {
+        const cap = maxPages ?? this.config.maxAutoPages;
+        const collected = [];
+        let pages = 0;
+        let nextAfter;
+        let currentOpts = opts;
+        while (currentOpts && pages < cap) {
+            const page = await this.get(currentOpts);
+            pages += 1;
+            if (Array.isArray(page.data))
+                collected.push(...page.data);
+            nextAfter = page.paging?.cursors?.after;
+            if (page.paging?.next && pages < cap) {
+                // 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 {
+                currentOpts = null;
+            }
+        }
+        return { data: collected, pages, nextAfter };
+    }
+    optsFromNextUrl(nextUrl) {
+        const u = new URL(nextUrl);
+        const segments = u.pathname.replace(/^\/+/, "").split("/");
+        const version = segments.shift() ?? this.config.apiVersion;
+        const path = segments.join("/");
+        const params = {};
+        for (const [k, v] of u.searchParams.entries()) {
+            if (k === "access_token" || k === "appsecret_proof")
+                continue;
+            params[k] = v;
+        }
+        return { path, params, apiVersion: version };
+    }
+    buildParams(params, accessTokenOverride, appSecretOverride) {
+        const out = {};
+        for (const [k, v] of Object.entries(params ?? {})) {
+            if (v === undefined || v === null)
+                continue;
+            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 (appSecret) {
+            out.appsecret_proof = this.appsecretProof(token, appSecret);
+        }
+        return out;
+    }
+    appsecretProof(token, appSecret) {
+        // appsecret_proof = HMAC-SHA256(access_token, app_secret).
+        // 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;
+        const ordered = Object.keys(rest)
+            .sort()
+            .map((k) => `${k}=${rest[k]}`)
+            .join("&");
+        return `${url}?${ordered}`;
+    }
+    async requestWithRetry(cfg) {
+        let lastError = null;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                const response = await this.http.request(cfg);
+                this.captureRateLimit(response.headers);
+                if (response.status >= 200 && response.status < 300) {
+                    return response.data;
+                }
+                // Non-2xx: construct as if axios threw.
+                lastError = normalizeAxiosError({
+                    isAxiosError: true,
+                    response,
+                    message: `HTTP ${response.status}`,
+                    config: cfg,
+                });
+            }
+            catch (err) {
+                if (err instanceof ReadOnlyViolationError)
+                    throw err;
+                lastError = normalizeAxiosError(err);
+            }
+            if (!lastError.retryable || attempt === MAX_RETRIES - 1) {
+                throw lastError;
+            }
+            const delay = BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+            this.logger.warn({ code: lastError.code, attempt, delay_ms: delay }, "meta api retrying after error");
+            await sleep(delay);
+        }
+        // Unreachable, but TypeScript needs it.
+        throw lastError ?? new MetaError("Unknown request failure");
+    }
+    captureRateLimit(headers) {
+        const get = (k) => {
+            const v = headers[k] ?? headers[k.toLowerCase()];
+            return typeof v === "string" ? v : undefined;
+        };
+        this.lastRateLimit = {
+            businessUseCase: get("x-business-use-case-usage"),
+            adAccountUsage: get("x-ad-account-usage"),
+            appUsage: get("x-app-usage"),
+        };
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/helpers/schema.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { ResponseFormat } from "./format.js";
+/**
+ * Canonical pagination input shared across list-style tools.
+ * - `limit`: items per page (capped)
+ * - `after`: opaque Graph cursor to resume from
+ * - `auto_paginate`: if true, follow `paging.next` up to max_pages
+ */
+export declare const paginationShape: {
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+};
+export declare const responseFormatShape: {
+    response_format: z.ZodDefault<z.ZodNativeEnum<typeof ResponseFormat>>;
+};
+/** Meta's expected ID shapes. Loose on purpose — Graph accepts numeric or prefixed forms. */
+export declare const metaIdSchema: z.ZodString;
+export declare const adAccountIdSchema: z.ZodString;
+export declare const datePresetSchema: z.ZodEnum<["today", "yesterday", "this_month", "last_month", "this_quarter", "maximum", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "last_week_mon_sun", "last_week_sun_sat", "last_quarter", "last_year", "this_week_mon_today", "this_week_sun_today", "this_year"]>;
+export declare const timeRangeSchema: z.ZodObject<{
+    since: z.ZodString;
+    until: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    since: string;
+    until: string;
+}, {
+    since: string;
+    until: string;
+}>;

package/dist/helpers/schema.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { ResponseFormat } from "./format.js";
+/**
+ * Canonical pagination input shared across list-style tools.
+ * - `limit`: items per page (capped)
+ * - `after`: opaque Graph cursor to resume from
+ * - `auto_paginate`: if true, follow `paging.next` up to max_pages
+ */
+export const paginationShape = {
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .default(25)
+        .describe("Items per page (1-500). Meta may cap lower for some endpoints."),
+    after: z
+        .string()
+        .optional()
+        .describe("Opaque Graph `paging.cursors.after` value from a previous response."),
+    auto_paginate: z
+        .boolean()
+        .default(false)
+        .describe("If true, follow `paging.next` up to META_MAX_AUTO_PAGES and return the concatenated data."),
+};
+export const responseFormatShape = {
+    response_format: z
+        .nativeEnum(ResponseFormat)
+        .default(ResponseFormat.JSON)
+        .describe("Output format: 'json' for machine-readable, 'markdown' for human-readable."),
+};
+/** Meta's expected ID shapes. Loose on purpose — Graph accepts numeric or prefixed forms. */
+export const metaIdSchema = z
+    .string()
+    .min(1)
+    .describe("Meta object ID. Numeric ID or prefixed form (e.g. ad accounts use 'act_<digits>').");
+export const adAccountIdSchema = z
+    .string()
+    .regex(/^act_\d+$/, "Ad account ID must start with 'act_' (e.g. 'act_1234567890').")
+    .describe("Ad account ID in the 'act_<digits>' form.");
+export const datePresetSchema = z
+    .enum([
+    "today",
+    "yesterday",
+    "this_month",
+    "last_month",
+    "this_quarter",
+    "maximum",
+    "last_3d",
+    "last_7d",
+    "last_14d",
+    "last_28d",
+    "last_30d",
+    "last_90d",
+    "last_week_mon_sun",
+    "last_week_sun_sat",
+    "last_quarter",
+    "last_year",
+    "this_week_mon_today",
+    "this_week_sun_today",
+    "this_year",
+])
+    .describe("Meta date preset. See Marketing API insights docs for the full set.");
+export const timeRangeSchema = z
+    .object({
+    since: z.string().describe("ISO date, e.g. '2026-01-01'."),
+    until: z.string().describe("ISO date, e.g. '2026-01-31'."),
+})
+    .describe("Explicit date range. Overrides date_preset when both are supplied.");

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,125 @@
+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)";
+}
+/**
+ * Per-field recovery hints: when the AI passes a placeholder for a specific
+ * field, tell it the *exact* discovery tool that produces the right ID. This
+ * turns "I need your IG account ID" (which the AI then asks the user) into
+ * "call meta_ig_list_accounts (no args) to discover IG accounts" (which the
+ * AI can do autonomously).
+ *
+ * Each entry returns a single-sentence next-step the AI should execute.
+ */
+const FIELD_RECOVERY = {
+    business_id: "Call `meta_business_list` (no args) to discover Business Manager IDs. The configured business is `133767790806312` (Hodusoft) — use that directly if you already know.",
+    ad_account_id: "Call `meta_ads_list_accounts business_id=133767790806312` to discover ad accounts. Returns IDs in the `act_<digits>` form (e.g. `act_146517954996436`).",
+    page_id: "Call `meta_page_list` (no args, defaults to source='assigned') to discover Pages assigned to the configured token.",
+    ig_user_id: "Call `meta_ig_list_accounts` (no args) to discover Instagram Business accounts linked to your Pages. No parameters required.",
+    pixel_id: "Call `meta_pixel_list business_id=133767790806312` to discover pixels.",
+    catalog_id: "Call `meta_catalog_list business_id=133767790806312 scope='owned'` to discover catalogs.",
+    waba_id: "Call `meta_whatsapp_list_wabas business_id=133767790806312` to discover WhatsApp Business Accounts.",
+    media_id: "Call `meta_ig_list_media ig_user_id=<ig_id>` to discover media. Use `meta_ig_list_accounts` first if you don't have ig_id.",
+    creative_id: "Call `meta_ads_list_ads ad_account_id=act_<id>` to discover creatives. Each ad's `creative.id` is the value you want.",
+    campaign_id: "Call `meta_ads_list_campaigns ad_account_id=act_<id>` to discover campaign IDs.",
+    adset_id: "Call `meta_ads_list_adsets ad_account_id=act_<id>` to discover ad-set IDs.",
+    post_id: "Call `meta_page_list_posts page_id=<page_id>` to discover post IDs. Post IDs use the `{page_id}_{post_id}` format.",
+    object_id: "Pass an ad account (`act_<digits>`), campaign, ad-set, or ad ID. Use `meta_business_overview business_id=133767790806312` to discover all of these in one call.",
+};
+/** Build a numbered recovery action list keyed off the placeholder field names. */
+function buildRecoveryActions(placeholders) {
+    const fields = new Set();
+    for (const p of placeholders) {
+        const top = p.path[0];
+        if (typeof top === "string")
+            fields.add(top);
+    }
+    const lines = [];
+    for (const f of fields) {
+        const recovery = FIELD_RECOVERY[f];
+        if (recovery)
+            lines.push(`• ${f}: ${recovery}`);
+    }
+    if (lines.length === 0) {
+        return "Replace the placeholder values with real IDs. If you don't know the IDs, call `meta_business_overview business_id=133767790806312` first to discover everything in one call.";
+    }
+    return `DO NOT ask the user for these IDs — the server can discover them for you. Replace each placeholder by first calling the corresponding discovery tool:\n${lines.join("\n")}\n\nShortcut: a single call to \`meta_business_overview business_id=133767790806312\` returns all Pages, IG accounts, ad accounts, pixels, catalogs, and WABAs at once. Prefer that when several placeholders appear together.`;
+}
+/**
+ * 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}`, buildRecoveryActions(placeholders), { placeholders, recovery_actions: buildRecoveryActions(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/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createLogger } from "./logger.js";
+import { buildServer } from "./server.js";
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        process.stderr.write(`[meta-mcp] configuration error: ${err.message}\n`);
+        process.exit(1);
+    }
+    const logger = createLogger(config.logLevel);
+    logger.info({ api_version: config.apiVersion, appsecret_proof: Boolean(config.appSecret) }, "starting meta-business-manager-mcp-server");
+    const { server } = buildServer(config, logger);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("stdio transport connected");
+    const shutdown = async (signal) => {
+        logger.info({ signal }, "shutting down");
+        try {
+            await server.close();
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
+main().catch((err) => {
+    process.stderr.write(`[meta-mcp] fatal: ${err.stack ?? err}\n`);
+    process.exit(1);
+});