@praise25/meta-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CashToken Rewards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+# meta-mcp-server
+
+> **Read-only Model Context Protocol server for Meta Business Manager.** Plug-in for AI assistants ("ChatGPT for marketing insights") that surfaces Pages, Instagram Business, Marketing API ad insights, Pixels, Commerce catalogs, and WhatsApp Business data — all read-only by construction.
+
+[![Read-Only Verified](https://img.shields.io/badge/safety-read--only-success)](#read-only-by-construction)
+[![Governance: Cashtoken SDGP](https://img.shields.io/badge/governance-cashtoken%20sdgp-blue)](./governance/standards/sdgp-main.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+---
+
+## Why this exists
+
+CashToken Marketing operates several Pages, Instagram Business accounts, Meta ad accounts, Pixels and (in future) Catalogs / WhatsApp Business assets across the `Hodusoft` Business Manager. Insight retrieval today is fragmented across Business Suite UIs, Ads Manager exports, and ad-hoc Graph API calls. This MCP server consolidates **read-only** access into a single tool surface that any MCP-aware AI assistant can plug into — turning fragmented UIs into one conversational interface for the marketing team.
+
+---
+
+## Read-only by construction
+
+This server cannot write to Meta. Period. Four layers of defence:
+
+1. **HTTP interceptor** — every axios request passes through a guard that throws `ReadOnlyViolationError` if the method isn't `GET`, before the request leaves the process. ([`src/helpers/graph-client.ts`](./src/helpers/graph-client.ts))
+2. **No write API surface** — the `GraphClient` class exposes only `get()` and `getAllPages()`. No `post()`, `put()`, `patch()`, or `delete()` exist anywhere in `src/`.
+3. **All tools annotated** `readOnlyHint: true, destructiveHint: false` — MCP clients surface this to end users.
+4. **Belt-and-braces token scopes** (operator responsibility) — issue the system-user token with read-only scopes (`ads_read`, `pages_read_engagement`, `read_insights`, `instagram_basic`, `instagram_manage_insights`). Even if the server were compromised, the token itself cannot write. See [`ADR-20260421-Read-Only-HTTP-Enforcement.md`](./governance/project-docs/adr/ADR-20260421-Read-Only-HTTP-Enforcement.md).
+
+Verify any time:
+
+```bash
+npm run test:readonly
+```
+
+---
+
+## Tools (36)
+
+| Domain | Tools |
+|---|---|
+| **Discovery** (6) | `meta_token_inspect`, `meta_health_check`, `meta_graph_read`, `meta_business_list`, `meta_business_list_assets`, `meta_business_list_system_users` |
+| **Ads / Marketing API** (8) | `meta_ads_list_accounts`, `meta_ads_get_account`, `meta_ads_list_campaigns`, `meta_ads_list_adsets`, `meta_ads_list_ads`, `meta_ads_get_insights` ⭐, `meta_ads_get_creative`, `meta_ads_list_custom_audiences` |
+| **Pages** (7) | `meta_page_list`, `meta_page_get`, `meta_page_list_posts`, `meta_page_get_post_insights`, `meta_page_get_insights`, `meta_page_list_reviews`, `meta_page_list_videos` |
+| **Instagram** (5) | `meta_ig_list_accounts`, `meta_ig_get_account`, `meta_ig_list_media`, `meta_ig_get_media_insights`, `meta_ig_get_audience_demographics` |
+| **Pixels** (2) | `meta_pixel_list`, `meta_pixel_get_stats` |
+| **Catalog** (3) | `meta_catalog_list`, `meta_catalog_list_products`, `meta_catalog_get_diagnostics` |
+| **WhatsApp** (4) | `meta_whatsapp_list_wabas`, `meta_whatsapp_list_phone_numbers`, `meta_whatsapp_list_templates`, `meta_whatsapp_get_analytics` |
+| **Eagle's-eye** (1) | `meta_business_overview` ⭐⭐⭐ — single-call consolidated snapshot across the whole business |
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+git clone git@github.com:feladeveloper/meta-mcp-server.git
+cd meta-mcp-server
+npm install
+```
+
+### 2. Configure environment
+
+Copy `.env.example` → `.env` and fill in:
+
+```bash
+META_ACCESS_TOKEN=...        # System-user token (see Token Provisioning below)
+META_APP_SECRET=...          # App secret of the app that issued the token (Hodusoft app: 193481170220592)
+META_API_VERSION=v23.0
+META_CACHE_TTL_SECONDS=120
+META_MAX_AUTO_PAGES=5
+LOG_LEVEL=info
+```
+
+Optional allowlists (if set, the server refuses to operate on IDs outside the allowlist):
+
+```bash
+META_ALLOWED_BUSINESS_IDS=133767790806312
+META_ALLOWED_AD_ACCOUNT_IDS=act_146517954996436,...
+META_ALLOWED_PAGE_IDS=138368686823692,...
+META_ALLOWED_IG_USER_IDS=17841406467396631,...
+```
+
+### 3. Build and run
+
+```bash
+npm run build
+node dist/index.js   # stdio MCP server
+```
+
+Or in development:
+
+```bash
+npm run dev
+```
+
+For an MCP Inspector session against the built server:
+
+```bash
+npm run inspect
+```
+
+### 4. Wire into a client
+
+Example (Claude Desktop or any MCP client) — fetches the published package on demand via `npx`:
+
+```json
+{
+  "mcpServers": {
+    "meta": {
+      "command": "npx",
+      "args": ["-y", "@praise25/meta-mcp-server"],
+      "env": {
+        "META_ACCESS_TOKEN": "...",
+        "META_APP_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+For a global install (`npm install -g @praise25/meta-mcp-server`), use the bin directly:
+
+```json
+{
+  "mcpServers": {
+    "meta": {
+      "command": "meta-business-manager-mcp-server",
+      "env": {
+        "META_ACCESS_TOKEN": "...",
+        "META_APP_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+For local development against a clone of this repo:
+
+```json
+{
+  "mcpServers": {
+    "meta": {
+      "command": "node",
+      "args": ["/absolute/path/to/meta-mcp-server/dist/index.js"],
+      "env": {
+        "META_ACCESS_TOKEN": "...",
+        "META_APP_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+---
+
+## Token Provisioning (Cashtoken-specific)
+
+The system user `AI_Insights_Reader` (id `122093391782492654`) under the `Hodusoft` business (id `133767790806312`) is the canonical identity for this server. Procedure to issue / rotate its token:
+
+1. Business Settings → System Users → `AI_Insights_Reader` → **Generate New Token**
+2. Pick the **Hodusoft** app (id `193481170220592`)
+3. In the scope picker, untick everything, then tick:
+   - `business_management`, `ads_management` (Meta only exposes management here; server still blocks writes), `pages_read_engagement`, `pages_read_user_content`, `read_insights`, `instagram_basic`, `instagram_manage_insights`, `whatsapp_business_management`, `catalog_management`
+4. Copy the token (Meta only shows it once)
+5. Paste over `META_ACCESS_TOKEN` in `.env`
+6. Verify with `meta_health_check` and `meta_token_inspect`
+
+Token TTL is ~60 days. Set a calendar reminder; rotation procedure documented in [`/governance/project-docs/runbook.md`](./governance/project-docs/runbook.md).
+
+See also: [`ADR-20260421-System-User-Token-Pattern.md`](./governance/project-docs/adr/ADR-20260421-System-User-Token-Pattern.md).
+
+---
+
+## Repository layout
+
+```
+meta-mcp-server/
+├── CLAUDE.md                          # AI agent rules (governance)
+├── .cursorrules                       # Cursor agent rules
+├── .github/
+│   ├── copilot-instructions.md        # Copilot agent rules
+│   ├── ISSUE_TEMPLATE/
+│   └── workflows/                     # CI/CD (GitHub Actions, Sentinel status check)
+├── .claude/skills/                    # 23 governance skills (scaffolding, review, git-ops, …)
+├── .sentinelrc                        # Sentinel governance plugin config
+├── CHANGELOG.md                       # SemVer release history
+├── README.md
+├── governance/                        # Governance assets — see /governance/standards/
+│   ├── standards/                     # SDGP policies, coding standards
+│   ├── templates/                     # Doc templates (specs, ADRs, deviations, project docs)
+│   └── project-docs/                  # Project documents
+│       ├── 1-vision-doc.md
+│       ├── 2-brd.md
+│       ├── 3-prd.md
+│       ├── 5-tad.md
+│       ├── runbook.md
+│       ├── solution-doc-architecture.md
+│       ├── specs/                     # Feature specs
+│       ├── adr/                       # Architecture Decision Records
+│       └── deviations/                # Governance deviation logs
+├── src/                               # Implementation (see TAD)
+│   ├── index.ts                       # stdio entrypoint
+│   ├── server.ts                      # MCP server wiring
+│   ├── config.ts                      # env + allowlists
+│   ├── errors.ts                      # MetaError, ReadOnlyViolationError
+│   ├── logger.ts                      # pino, stderr only, redacts secrets
+│   ├── constants.ts
+│   ├── context.ts
+│   ├── helpers/
+│   │   ├── graph-client.ts            # GET-only axios client + retry + cache + appsecret_proof
+│   │   ├── cache.ts                   # LRU TTL cache
+│   │   ├── format.ts                  # JSON / Markdown response formatting
+│   │   └── schema.ts                  # Shared Zod shapes (pagination, date presets, IDs)
+│   ├── tools/                         # 36 tool implementations grouped by domain
+│   │   ├── token/  meta/  business/  ads/  pages/  instagram/  pixels/  catalog/  whatsapp/  overview/
+│   │   ├── shared.ts                  # runList / runGet / errorResult helpers
+│   │   └── register.ts                # Centralized tool registration
+│   └── types/
+└── tests/
+    └── read-only-guard.mjs            # Runtime proof that POST/PUT/PATCH/DELETE are blocked
+```
+
+---
+
+## Governance
+
+This project is initialized from the [`cashtokenrewards/project-governance-template`](https://github.com/cashtokenrewards/project-governance-template) and follows the **Software Development Governance Policy (SDGP)** in [`/governance/standards/sdgp-main.md`](./governance/standards/sdgp-main.md).
+
+**Three absolute rules:**
+1. No feature is built without an approved spec. ([`/governance/project-docs/specs/`](./governance/project-docs/specs/))
+2. No ADR is written without a parent feature spec. ([`/governance/project-docs/adr/`](./governance/project-docs/adr/))
+3. No implementation begins without the spec and all required ADRs approved.
+
+The current implementation (commit zero) was bootstrapped against an initial pass of governance docs:
+
+| Doc | Path |
+|---|---|
+| Vision | [`governance/project-docs/1-vision-doc.md`](./governance/project-docs/1-vision-doc.md) |
+| BRD | [`governance/project-docs/2-brd.md`](./governance/project-docs/2-brd.md) |
+| PRD | [`governance/project-docs/3-prd.md`](./governance/project-docs/3-prd.md) |
+| TAD | [`governance/project-docs/5-tad.md`](./governance/project-docs/5-tad.md) |
+| Runbook | [`governance/project-docs/runbook.md`](./governance/project-docs/runbook.md) |
+| Specs | [`governance/project-docs/specs/`](./governance/project-docs/specs/) |
+| ADRs | [`governance/project-docs/adr/`](./governance/project-docs/adr/) |
+| Deviations | [`governance/project-docs/deviations/`](./governance/project-docs/deviations/) |
+
+**Branch model:** Gitflow. `main` (production), `dev` (integration). Short-lived branches: `feature-`, `fix-`, `release-`, `hotfix-`, `docs-`. All merges `--no-ff`. See [`/governance/standards/sdgp-main.md`](./governance/standards/sdgp-main.md) §7.4.
+
+**AI agent rules:** [`CLAUDE.md`](./CLAUDE.md), [`.cursorrules`](./.cursorrules), [`.github/copilot-instructions.md`](./.github/copilot-instructions.md). Sentinel keeps these in sync with the central governance config.
+
+---
+
+## Sentinel
+
+This repository is tracked by the [Sentinel governance plugin](https://github.com/feladeveloper/sentinel-claude-plugin). Configuration lives at [`.sentinelrc`](./.sentinelrc). On any clone:
+
+```bash
+export SENTINEL_GITHUB_TOKEN="ghp_..."     # Personal access token with repo:read
+sentinel sync                               # Pull latest org-level governance into CLAUDE.md
+```
+
+`/sentinel-sync` and `/sentinel-status` slash commands are also available inside Claude Code once the plugin is installed.
+
+---
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `npm run build` | Clean + compile TypeScript → `dist/` |
+| `npm run dev` | Run with `tsx` (no build step) |
+| `npm run start` | Run built `dist/index.js` |
+| `npm run inspect` | Build + open MCP Inspector |
+| `npm run check:types` | `tsc --noEmit` |
+| `npm run test:readonly` | Build + runtime proof that POST/PUT/PATCH/DELETE are blocked by the Graph client |
+| `npm test` | (placeholder for jest suite — see [`SPEC-07-eval-suite.md`](./governance/project-docs/specs/) when added) |
+
+---
+
+## Status
+
+| Aspect | State |
+|---|---|
+| Implementation | **v0.1.0 — bootstrapped, 36 tools, build clean, read-only guard verified** |
+| Governance docs | Initial pass — Vision / BRD / PRD / TAD / Runbook / 3 ADRs / 1 deviation drafted |
+| App-level (Meta) | Hodusoft app in **development tier** for Marketing API. Standard Access via App Review pending. |
+| Asset coverage | All 3 Pages discoverable; 1 Page (CashToken) currently assigned to AI_Insights_Reader; 5 ad accounts visible; 3 Pixels visible; 1 IG (cashtokenhq) discovered via Page link |
+| Open scopes | `read_insights`, `instagram_manage_insights`, `whatsapp_business_management`, `catalog_management` may need to be added to the Hodusoft app before they appear in the token picker |
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export interface Config {
+    accessToken: string;
+    appSecret: string | undefined;
+    apiVersion: string;
+    httpTimeoutMs: number;
+    cacheTtlSeconds: number;
+    maxAutoPages: number;
+    allowedBusinessIds: Set<string> | null;
+    allowedAdAccountIds: Set<string> | null;
+    allowedPageIds: Set<string> | null;
+    allowedIgUserIds: Set<string> | null;
+    logLevel: string;
+}
+export declare function loadConfig(): Config;
+export declare function assertAllowed(kind: "business" | "ad_account" | "page" | "ig_user", id: string, config: Config): void;

package/dist/config.js

@@ -0,0 +1,46 @@
+import { DEFAULT_API_VERSION } from "./constants.js";
+function parseAllowlist(raw) {
+    if (!raw || !raw.trim())
+        return null;
+    const items = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return items.length ? new Set(items) : null;
+}
+function parseNumber(raw, fallback) {
+    if (raw == null || raw === "")
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function loadConfig() {
+    const accessToken = process.env.META_ACCESS_TOKEN?.trim();
+    if (!accessToken) {
+        throw new Error("META_ACCESS_TOKEN is required. Set it in the environment or .env file.");
+    }
+    return {
+        accessToken,
+        appSecret: process.env.META_APP_SECRET?.trim() || undefined,
+        apiVersion: process.env.META_API_VERSION?.trim() || DEFAULT_API_VERSION,
+        httpTimeoutMs: parseNumber(process.env.META_HTTP_TIMEOUT_MS, 30_000),
+        cacheTtlSeconds: parseNumber(process.env.META_CACHE_TTL_SECONDS, 120),
+        maxAutoPages: parseNumber(process.env.META_MAX_AUTO_PAGES, 5),
+        allowedBusinessIds: parseAllowlist(process.env.META_ALLOWED_BUSINESS_IDS),
+        allowedAdAccountIds: parseAllowlist(process.env.META_ALLOWED_AD_ACCOUNT_IDS),
+        allowedPageIds: parseAllowlist(process.env.META_ALLOWED_PAGE_IDS),
+        allowedIgUserIds: parseAllowlist(process.env.META_ALLOWED_IG_USER_IDS),
+        logLevel: process.env.LOG_LEVEL?.trim() || "info",
+    };
+}
+export function assertAllowed(kind, id, config) {
+    const allowlist = {
+        business: config.allowedBusinessIds,
+        ad_account: config.allowedAdAccountIds,
+        page: config.allowedPageIds,
+        ig_user: config.allowedIgUserIds,
+    }[kind];
+    if (allowlist && !allowlist.has(id)) {
+        throw new Error(`${kind} '${id}' is not in the configured META_ALLOWED_${kind.toUpperCase()}_IDS allowlist.`);
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,21 @@
+export declare const GRAPH_BASE_URL = "https://graph.facebook.com";
+export declare const DEFAULT_API_VERSION = "v23.0";
+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 META_ERROR_CODES: {
+    readonly UNKNOWN: 1;
+    readonly SERVICE_TEMPORARILY_UNAVAILABLE: 2;
+    readonly APPLICATION_LIMIT_REACHED: 4;
+    readonly USER_REQUEST_LIMIT_REACHED: 17;
+    readonly PAGE_LIMIT_REACHED: 32;
+    readonly AD_ACCOUNT_THROTTLED: 613;
+    readonly INVALID_ACCESS_TOKEN: 190;
+    readonly PERMISSION_DENIED: 10;
+    readonly REQUIRES_REVIEW_PERMISSION: 200;
+};
+export declare const RETRYABLE_META_CODES: Set<number>;
+export declare const MAX_RETRIES = 3;
+export declare const BASE_RETRY_DELAY_MS = 1000;

package/dist/constants.js

@@ -0,0 +1,28 @@
+export const GRAPH_BASE_URL = "https://graph.facebook.com";
+export const DEFAULT_API_VERSION = "v23.0";
+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 META_ERROR_CODES = {
+    UNKNOWN: 1,
+    SERVICE_TEMPORARILY_UNAVAILABLE: 2,
+    APPLICATION_LIMIT_REACHED: 4,
+    USER_REQUEST_LIMIT_REACHED: 17,
+    PAGE_LIMIT_REACHED: 32,
+    AD_ACCOUNT_THROTTLED: 613,
+    INVALID_ACCESS_TOKEN: 190,
+    PERMISSION_DENIED: 10,
+    REQUIRES_REVIEW_PERMISSION: 200,
+};
+export const RETRYABLE_META_CODES = new Set([
+    META_ERROR_CODES.UNKNOWN,
+    META_ERROR_CODES.SERVICE_TEMPORARILY_UNAVAILABLE,
+    META_ERROR_CODES.APPLICATION_LIMIT_REACHED,
+    META_ERROR_CODES.USER_REQUEST_LIMIT_REACHED,
+    META_ERROR_CODES.PAGE_LIMIT_REACHED,
+    META_ERROR_CODES.AD_ACCOUNT_THROTTLED,
+]);
+export const MAX_RETRIES = 3;
+export const BASE_RETRY_DELAY_MS = 1000;

package/dist/context.d.ts

@@ -0,0 +1,9 @@
+import type { Config } from "./config.js";
+import { GraphClient } from "./helpers/graph-client.js";
+import type { Logger } from "./logger.js";
+export interface ToolContext {
+    config: Config;
+    graph: GraphClient;
+    logger: Logger;
+}
+export declare function createContext(config: Config, logger: Logger): ToolContext;

package/dist/context.js

@@ -0,0 +1,8 @@
+import { GraphClient } from "./helpers/graph-client.js";
+export function createContext(config, logger) {
+    return {
+        config,
+        graph: new GraphClient(config, logger),
+        logger,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+export interface MetaApiError {
+    message: string;
+    type?: string;
+    code?: number;
+    error_subcode?: number;
+    fbtrace_id?: string;
+    error_user_title?: string;
+    error_user_msg?: string;
+}
+export declare class MetaError extends Error {
+    readonly code: number | undefined;
+    readonly subcode: number | undefined;
+    readonly fbtraceId: string | undefined;
+    readonly type: string | undefined;
+    readonly httpStatus: number | undefined;
+    readonly retryable: boolean;
+    readonly hint: string;
+    constructor(message: string, opts?: {
+        code?: number;
+        subcode?: number;
+        fbtraceId?: string;
+        type?: string;
+        httpStatus?: number;
+        hint?: string;
+    });
+    toJSON(): {
+        error: string;
+        message: string;
+        code: number | undefined;
+        subcode: number | undefined;
+        type: string | undefined;
+        fbtrace_id: string | undefined;
+        http_status: number | undefined;
+        retryable: boolean;
+        hint: string;
+    };
+}
+export declare function normalizeAxiosError(err: unknown): MetaError;
+export declare class ReadOnlyViolationError extends Error {
+    constructor(method: string, url: string);
+}

package/dist/errors.js

@@ -0,0 +1,90 @@
+import { RETRYABLE_META_CODES } from "./constants.js";
+export class MetaError extends Error {
+    code;
+    subcode;
+    fbtraceId;
+    type;
+    httpStatus;
+    retryable;
+    hint;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "MetaError";
+        this.code = opts.code;
+        this.subcode = opts.subcode;
+        this.fbtraceId = opts.fbtraceId;
+        this.type = opts.type;
+        this.httpStatus = opts.httpStatus;
+        this.retryable = opts.code != null && RETRYABLE_META_CODES.has(opts.code);
+        this.hint = opts.hint ?? deriveHint(opts.code, opts.subcode, opts.httpStatus);
+    }
+    toJSON() {
+        return {
+            error: "MetaError",
+            message: this.message,
+            code: this.code,
+            subcode: this.subcode,
+            type: this.type,
+            fbtrace_id: this.fbtraceId,
+            http_status: this.httpStatus,
+            retryable: this.retryable,
+            hint: this.hint,
+        };
+    }
+}
+function deriveHint(code, subcode, httpStatus) {
+    if (code === 190) {
+        if (subcode === 463)
+            return "Access token has expired. Generate a new system-user token.";
+        if (subcode === 467)
+            return "Access token is invalid. Re-issue from Business Settings → System Users.";
+        return "Access token error. Check META_ACCESS_TOKEN is valid and tied to the correct app.";
+    }
+    if (code === 10 || code === 200) {
+        return "Permission denied. Verify the system user is assigned to the target asset and that the app has the required permissions (e.g. ads_read, pages_read_engagement).";
+    }
+    if (code === 4 || code === 17 || code === 32) {
+        return "Rate-limited by Meta. Retry with backoff or narrow the query (shorter date range, fewer breakdowns).";
+    }
+    if (code === 613) {
+        return "Ad account throttled. Reduce insight query complexity or wait before retrying.";
+    }
+    if (code === 100) {
+        return "Invalid parameter. Check field names, ID format (ad accounts need 'act_' prefix), and date presets.";
+    }
+    if (httpStatus === 404) {
+        return "Resource not found. Check the ID and that it is assigned to the configured system user.";
+    }
+    if (httpStatus === 403) {
+        return "Forbidden. The token lacks access to this asset — assign it via Business Settings.";
+    }
+    return "See https://developers.facebook.com/docs/graph-api/guides/error-handling/ for troubleshooting.";
+}
+export function normalizeAxiosError(err) {
+    const axiosErr = err;
+    if (axiosErr?.isAxiosError) {
+        const apiErr = axiosErr.response?.data?.error;
+        if (apiErr) {
+            return new MetaError(apiErr.message, {
+                code: apiErr.code,
+                subcode: apiErr.error_subcode,
+                fbtraceId: apiErr.fbtrace_id,
+                type: apiErr.type,
+                httpStatus: axiosErr.response?.status,
+            });
+        }
+        const status = axiosErr.response?.status;
+        return new MetaError(axiosErr.message || "HTTP request failed", {
+            httpStatus: status,
+        });
+    }
+    if (err instanceof Error)
+        return new MetaError(err.message);
+    return new MetaError(String(err));
+}
+export class ReadOnlyViolationError extends Error {
+    constructor(method, url) {
+        super(`Refusing ${method} ${url}: this MCP server is read-only. Only GET requests are permitted by the Graph client.`);
+        this.name = "ReadOnlyViolationError";
+    }
+}

package/dist/helpers/cache.d.ts

@@ -0,0 +1,6 @@
+export interface GraphCache {
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown): void;
+    clear(): void;
+}
+export declare function createCache(ttlSeconds: number): GraphCache;

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,
+    };
+}