@praise25/meta-mcp-server 0.1.0

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

@@ -0,0 +1,56 @@
+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;
+}
+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 lastRateLimit;
+    constructor(config: Config, logger: Logger);
+    get rateLimit(): GraphRateLimitHeaders;
+    clearCache(): void;
+    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,169 @@
+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;
+    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();
+    }
+    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 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) {
+                currentOpts = this.optsFromNextUrl(page.paging.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) {
+        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;
+        if (this.config.appSecret) {
+            out.appsecret_proof = this.appsecretProof();
+        }
+        return out;
+    }
+    appsecretProof() {
+        // appsecret_proof = HMAC-SHA256(access_token, app_secret)
+        return crypto
+            .createHmac("sha256", this.config.appSecret)
+            .update(this.config.accessToken)
+            .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/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);
+});

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+import pino from "pino";
+export declare function createLogger(level: string): pino.Logger<never, boolean>;
+export type Logger = ReturnType<typeof createLogger>;

package/dist/logger.js

@@ -0,0 +1,18 @@
+import pino from "pino";
+export function createLogger(level) {
+    return pino({
+        name: "meta-mcp",
+        level,
+        redact: {
+            paths: [
+                "access_token",
+                "*.access_token",
+                "params.access_token",
+                "headers.authorization",
+                "appsecret_proof",
+                "*.appsecret_proof",
+            ],
+            censor: "[redacted]",
+        },
+    }, pino.destination(2));
+}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Config } from "./config.js";
+import type { Logger } from "./logger.js";
+export declare function buildServer(config: Config, logger: Logger): {
+    server: McpServer;
+    ctx: import("./context.js").ToolContext;
+};

package/dist/server.js

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createContext } from "./context.js";
+import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+import { registerTools } from "./tools/register.js";
+export function buildServer(config, logger) {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    const ctx = createContext(config, logger);
+    const toolNames = registerTools(server, ctx);
+    logger.info({ tools: toolNames, count: toolNames.length }, "tools registered");
+    return { server, ctx };
+}

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    ad_account_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    ad_account_id: string;
+}, {
+    ad_account_id: string;
+    fields?: string[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_get_account";
+    readonly title: "Get ad account details";
+    readonly description: "Reads account-level details for a single ad account: status, currency, spend cap, current balance, amount_spent lifetime, funding source, capabilities, business owner. Use to verify an account is active and has headroom before drilling into insights.";
+    readonly inputSchema: {
+        ad_account_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/ads/get-account.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { adAccountIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ad_account_id: adAccountIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "account_id",
+        "name",
+        "currency",
+        "timezone_name",
+        "account_status",
+        "disable_reason",
+        "spend_cap",
+        "balance",
+        "amount_spent",
+        "funding_source_details",
+        "business",
+        "capabilities",
+        "age",
+        "created_time",
+    ])
+        .describe("Fields to return."),
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_get_account",
+    title: "Get ad account details",
+    description: `Reads account-level details for a single ad account: status, currency, spend cap, current balance, amount_spent lifetime, funding source, capabilities, business owner. Use to verify an account is active and has headroom before drilling into insights.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export async function handler(input, ctx) {
+    assertAllowed("ad_account", input.ad_account_id, ctx.config);
+    return runGet(ctx, { path: input.ad_account_id, params: { fields: input.fields.join(",") } });
+}

package/dist/tools/ads/get-creative.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    creative_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    creative_id: string;
+}, {
+    creative_id: string;
+    fields?: string[] | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ads_get_creative";
+    readonly title: "Get ad creative details";
+    readonly description: "Reads ad creative body: headline, copy, image or video, CTA, link URL, attached object story. Use alongside insights to explain why a particular ad performed well.";
+    readonly inputSchema: {
+        creative_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/ads/get-creative.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { metaIdSchema } from "../../helpers/schema.js";
+import { runGet } from "../shared.js";
+export const inputSchema = z
+    .object({
+    creative_id: metaIdSchema.describe("Creative ID (as returned by meta_ads_list_ads.creative.id)."),
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "name",
+        "title",
+        "body",
+        "object_story_id",
+        "object_type",
+        "image_url",
+        "thumbnail_url",
+        "video_id",
+        "call_to_action_type",
+        "link_url",
+        "effective_object_story_id",
+        "instagram_permalink_url",
+        "object_story_spec",
+    ])
+        .describe("Creative fields."),
+})
+    .strict();
+export const definition = {
+    name: "meta_ads_get_creative",
+    title: "Get ad creative details",
+    description: `Reads ad creative body: headline, copy, image or video, CTA, link URL, attached object story. Use alongside insights to explain why a particular ad performed well.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runGet(ctx, { path: input.creative_id, params: { fields: input.fields.join(",") } });
+}