@cashtokenai/meta-mcp-server 1.0.0

package/dist/tools/whatsapp/get-analytics.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { metaIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+const GRANULARITY = z.enum(["HALF_HOUR", "DAY", "MONTH"]);
+export const inputSchema = z
+    .object({
+    waba_id: metaIdSchema,
+    flavor: z
+        .enum(["analytics", "conversation_analytics"])
+        .default("conversation_analytics")
+        .describe("'analytics' = legacy message-count metric. 'conversation_analytics' = per-conversation pricing + category metrics (preferred)."),
+    start: z.number().int().describe("Unix timestamp (seconds) — window start."),
+    end: z.number().int().describe("Unix timestamp (seconds) — window end."),
+    granularity: GRANULARITY.default("DAY"),
+    phone_numbers: z
+        .array(z.string())
+        .optional()
+        .describe("Optional filter: list of display phone numbers ('+15551234567' form)."),
+    country_codes: z.array(z.string()).optional().describe("Optional filter: ISO country codes."),
+    conversation_categories: z
+        .array(z.string())
+        .optional()
+        .describe("AUTHENTICATION, MARKETING, SERVICE, UTILITY."),
+    dimensions: z
+        .array(z.string())
+        .default(["CONVERSATION_CATEGORY", "COUNTRY", "PHONE"])
+        .describe("Breakdown dimensions."),
+})
+    .strict();
+export const definition = {
+    name: "meta_whatsapp_get_analytics",
+    title: "Get WhatsApp Business analytics",
+    description: `Fetches WABA analytics — either the legacy 'analytics' field (message counts) or the richer 'conversation_analytics' (per-conversation pricing, categories: AUTHENTICATION/MARKETING/SERVICE/UTILITY).
+
+Pass start + end as Unix seconds. Use granularity DAY for most reports. Filter by phone_numbers, country_codes, or conversation_categories to narrow.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    const dims = input.dimensions.join(",");
+    let inner;
+    if (input.flavor === "conversation_analytics") {
+        const parts = [
+            `start(${input.start})`,
+            `end(${input.end})`,
+            `granularity(${input.granularity})`,
+            `dimensions([${dims}])`,
+        ];
+        if (input.phone_numbers?.length)
+            parts.push(`phone_numbers([${input.phone_numbers.join(",")}])`);
+        if (input.country_codes?.length)
+            parts.push(`country_codes([${input.country_codes.join(",")}])`);
+        if (input.conversation_categories?.length)
+            parts.push(`conversation_categories([${input.conversation_categories.join(",")}])`);
+        inner = `conversation_analytics.${parts.join(".")}`;
+    }
+    else {
+        const parts = [`start(${input.start})`, `end(${input.end})`, `granularity(${input.granularity})`];
+        if (input.phone_numbers?.length)
+            parts.push(`phone_numbers([${input.phone_numbers.join(",")}])`);
+        if (input.country_codes?.length)
+            parts.push(`country_codes([${input.country_codes.join(",")}])`);
+        inner = `analytics.${parts.join(".")}`;
+    }
+    return runGet(ctx, { path: input.waba_id, params: { fields: inner } }, { waba_id: input.waba_id, flavor: input.flavor });
+}

package/dist/tools/whatsapp/list-phone-numbers.d.ts

@@ -0,0 +1,41 @@
+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>;
+    waba_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    waba_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    after?: string | undefined;
+}, {
+    waba_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_whatsapp_list_phone_numbers";
+    readonly title: "List phone numbers under a WABA";
+    readonly description: "Lists the phone numbers attached to a WABA — display number, verified name, quality rating (GREEN/YELLOW/RED), messaging tier (throughput limits).";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        waba_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/whatsapp/list-phone-numbers.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    waba_id: metaIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "display_phone_number",
+        "verified_name",
+        "code_verification_status",
+        "quality_rating",
+        "platform_type",
+        "throughput",
+        "messaging_limit_tier",
+    ])
+        .describe("Phone number fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_whatsapp_list_phone_numbers",
+    title: "List phone numbers under a WABA",
+    description: `Lists the phone numbers attached to a WABA — display number, verified name, quality rating (GREEN/YELLOW/RED), messaging tier (throughput limits).`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runList(ctx, {
+        path: `${input.waba_id}/phone_numbers`,
+        params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { waba_id: input.waba_id });
+}

package/dist/tools/whatsapp/list-templates.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>;
+    waba_id: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<["APPROVED", "PENDING", "REJECTED", "DISABLED", "IN_APPEAL", "DELETED", "PAUSED"]>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    waba_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    status?: "PAUSED" | "DELETED" | "APPROVED" | "PENDING" | "REJECTED" | "DISABLED" | "IN_APPEAL" | undefined;
+    after?: string | undefined;
+}, {
+    waba_id: string;
+    fields?: string[] | undefined;
+    status?: "PAUSED" | "DELETED" | "APPROVED" | "PENDING" | "REJECTED" | "DISABLED" | "IN_APPEAL" | 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_whatsapp_list_templates";
+    readonly title: "List WhatsApp message templates";
+    readonly description: "Lists approved/pending/rejected message templates for a WABA. Read-only — does not send messages. Useful for spotting rejected templates and pre-flight checks.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        waba_id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<["APPROVED", "PENDING", "REJECTED", "DISABLED", "IN_APPEAL", "DELETED", "PAUSED"]>>;
+        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/whatsapp/list-templates.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    waba_id: metaIdSchema,
+    status: z
+        .enum(["APPROVED", "PENDING", "REJECTED", "DISABLED", "IN_APPEAL", "DELETED", "PAUSED"])
+        .optional()
+        .describe("Filter by template status."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "status",
+        "category",
+        "language",
+        "components",
+        "quality_score",
+        "rejected_reason",
+    ])
+        .describe("Template fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_whatsapp_list_templates",
+    title: "List WhatsApp message templates",
+    description: `Lists approved/pending/rejected message templates for a WABA. Read-only — does not send messages. Useful for spotting rejected templates and pre-flight checks.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runList(ctx, {
+        path: `${input.waba_id}/message_templates`,
+        params: {
+            fields: input.fields.join(","),
+            limit: input.limit,
+            after: input.after,
+            status: input.status,
+        },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { waba_id: input.waba_id });
+}

package/dist/tools/whatsapp/list-wabas.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_whatsapp_list_wabas";
+    readonly title: "List WhatsApp Business Accounts under a business";
+    readonly description: "Lists WhatsApp Business Accounts (WABAs). Needs WhatsApp Business Platform product on the app and 'whatsapp_business_management' token scope.";
+    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/whatsapp/list-wabas.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("both"),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "currency",
+        "timezone_id",
+        "business_verification_status",
+        "message_template_namespace",
+        "status",
+    ])
+        .describe("WABA fields."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_whatsapp_list_wabas",
+    title: "List WhatsApp Business Accounts under a business",
+    description: `Lists WhatsApp Business Accounts (WABAs). Needs WhatsApp Business Platform product on the app and 'whatsapp_business_management' token scope.`,
+    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_whatsapp_business_accounts", "client_whatsapp_business_accounts"]
+        : [`${input.scope}_whatsapp_business_accounts`];
+    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/types/meta.d.ts

@@ -0,0 +1,46 @@
+/** Shape of a Business owned/client asset edge. */
+export interface BusinessAsset {
+    id: string;
+    name?: string;
+    category?: string;
+    /** Only present for ad accounts. */
+    account_id?: string;
+    currency?: string;
+    timezone_name?: string;
+    username?: string;
+}
+export interface Business {
+    id: string;
+    name: string;
+    verification_status?: string;
+    primary_page?: {
+        id: string;
+        name?: string;
+    };
+    created_time?: string;
+    updated_time?: string;
+    timezone_id?: number;
+}
+export interface SystemUser {
+    id: string;
+    name: string;
+    role?: string;
+    finance_role?: string;
+    ip_role?: string;
+}
+export interface TokenDebug {
+    app_id?: string;
+    type?: string;
+    application?: string;
+    data_access_expires_at?: number;
+    expires_at?: number;
+    is_valid?: boolean;
+    issued_at?: number;
+    scopes?: string[];
+    granular_scopes?: {
+        scope: string;
+        target_ids?: string[];
+    }[];
+    user_id?: string;
+    profile_id?: string;
+}

package/dist/types/meta.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@cashtokenai/meta-mcp-server",
+  "description": "Read-only Model Context Protocol server for Meta Business Manager — Pages, Instagram, Ads insights, Pixels, Catalog, WhatsApp.",
+  "version": "1.0.0",
+  "author": "Stephen A.",
+  "license": "MIT",
+  "homepage": "https://github.com/feladeveloper/meta-mcp-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/feladeveloper/meta-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/feladeveloper/meta-mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "meta",
+    "facebook",
+    "instagram",
+    "marketing-api",
+    "ads",
+    "ads-insights",
+    "pixels",
+    "catalog",
+    "whatsapp",
+    "business-manager",
+    "read-only",
+    "ai-tools",
+    "claude"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "meta-business-manager-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "scripts": {
+    "build:clean": "rm -rf dist",
+    "build:compile": "tsc --project tsconfig.build.json",
+    "build:chmod": "chmod +x dist/index.js || true",
+    "build": "npm run build:clean && npm run build:compile && npm run build:chmod",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "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:invariants"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.2",
+    "axios": "^1.7.7",
+    "lru-cache": "^11.1.0",
+    "pino": "^9.5.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
+    "jest": "^30.0.0",
+    "ts-jest": "^29.2.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}