@praise25/meta-mcp-server 0.1.0 → 0.1.1

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

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/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/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.1",
   "author": "Stephen A.",
   "license": "MIT",
   "homepage": "https://github.com/feladeveloper/meta-mcp-server#readme",
@@ -52,8 +52,10 @@
     "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": "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",