@praise25/meta-mcp-server 0.1.2 → 0.1.6

package/LICENSE

@@ -1,21 +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.
+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

@@ -1,292 +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).
+# 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/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.2";
+export declare const SERVER_VERSION = "0.1.4";
 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.2";
+export const SERVER_VERSION = "0.1.4";
 export const META_ERROR_CODES = {
     UNKNOWN: 1,
     SERVICE_TEMPORARILY_UNAVAILABLE: 2,

package/dist/errors.js

@@ -16,7 +16,7 @@ export class MetaError extends Error {
         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);
+        this.hint = opts.hint ?? deriveHint(opts.code, opts.subcode, opts.httpStatus, message);
     }
     toJSON() {
         return {
@@ -32,7 +32,7 @@ export class MetaError extends Error {
         };
     }
 }
-function deriveHint(code, subcode, httpStatus) {
+function deriveHint(code, subcode, httpStatus, message) {
     if (code === 190) {
         if (subcode === 463)
             return "Access token has expired. Generate a new system-user token.";
@@ -40,8 +40,29 @@ function deriveHint(code, subcode, httpStatus) {
             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 === 10) {
+        // Code 10 splits into two distinct operator actions, distinguishable by the
+        // exact Meta error message — surface the right one so AI consumers can
+        // direct the user accurately.
+        if (message && /Application does not have permission/i.test(message)) {
+            return "App-level permission missing. The configured app needs Standard Access via Meta App Review for the relevant permission (e.g. instagram_manage_insights, ads_management). Request via App Review → Permissions and Features in the app dashboard. While in development tier, only developer/admin users on the app can read this data.";
+        }
+        if (message && /Page Public Content Access/i.test(message)) {
+            return "App needs the 'Page Public Content Access' feature, granted via Meta App Review. Until approved, pages_read_engagement on Pages outside the app's developer/test set will fail. Path: App Dashboard → App Review → Features.";
+        }
+        return "App-level permission denied (code 10). Either the configured app lacks the required permission/feature in App Review, or the system user is not assigned to the target asset with the right task in Business Settings.";
+    }
+    if (code === 200) {
+        if (message && /pages_read_user_content/i.test(message)) {
+            return "Token lacks 'pages_read_user_content'. Regenerate the system-user token in Business Settings → System Users → Generate New Token, ticking that scope.";
+        }
+        if (message && /This application has not been approved/i.test(message)) {
+            return "App not approved for this product. Add the relevant Product (e.g. WhatsApp Business Platform, Commerce / Catalog Management) to the app in https://developers.facebook.com/apps and complete its onboarding.";
+        }
+        return "Permission denied. Verify the system user is assigned to the target asset (Business Settings → System Users → Add Assets) with the right task, and the token has the matching scope.";
+    }
+    if (code === 283) {
+        return "Token lacks the scope needed for this Page action (typically pages_read_user_content for reviews, or pages_read_engagement for posts). Regenerate the token with the required scope ticked.";
     }
     if (code === 4 || code === 17 || code === 32) {
         return "Rate-limited by Meta. Retry with backoff or narrow the query (shorter date range, fewer breakdowns).";
@@ -49,7 +70,16 @@ function deriveHint(code, subcode, httpStatus) {
     if (code === 613) {
         return "Ad account throttled. Reduce insight query complexity or wait before retrying.";
     }
+    if (code === 210) {
+        return "This endpoint requires a Page access token, not the system-user token. The Page tools resolve this automatically — if you see this from meta_graph_read, fetch the token via GET /{page_id}?fields=access_token first.";
+    }
+    if (code === 12) {
+        return "Field deprecated by Meta. Remove the deprecated field from the `fields` array. Common offender: 'subattachments' inside attachments expansion (deprecated in v3.3+).";
+    }
     if (code === 100) {
+        if (message && /must be a valid insights metric/i.test(message)) {
+            return "Either one of the supplied metrics is invalid for this Page/period combination, OR the token lacks 'read_insights' (Meta returns this misleading error in both cases). Check the token has read_insights via meta_token_inspect, then narrow your metrics list to a known-valid subset.";
+        }
         return "Invalid parameter. Check field names, ID format (ad accounts need 'act_' prefix), and date presets.";
     }
     if (httpStatus === 404) {

package/dist/tools/ads/get-insights.js

@@ -101,16 +101,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ads_get_insights",
     title: "Get Marketing API insights (the workhorse)",
-    description: `Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.
-
-Returns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.
-
-Tips for the AI consuming this:
-- Default date_preset is last_30d. Override via date_preset or time_range.
-- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.
-- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.
-- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.
-
+    description: `Fetch Marketing API insights for any ad object: ad account ('act_<id>'), campaign, ad set, or ad.
+
+Returns spend, impressions, clicks, CPC/CPM/CTR, reach, frequency, actions (conversions), and video metrics — with optional demographic / placement / device breakdowns.
+
+Tips for the AI consuming this:
+- Default date_preset is last_30d. Override via date_preset or time_range.
+- Set level to 'ad' and breakdowns=['publisher_platform','platform_position'] to see which placements convert.
+- Use action_breakdowns=['action_type'] to split purchases vs. add_to_cart vs. lead.
+- If you get code 613 or 17, you hit rate limits — narrow the date range or drop breakdowns.
+
 Requires 'ads_read' token scope.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/tools/ads/list-accounts.js

@@ -31,10 +31,10 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ads_list_accounts",
     title: "List ad accounts under a business",
-    description: `Lists ad accounts the business owns (owned_ad_accounts) and/or has access to (client_ad_accounts).
-
-Needs token scope 'ads_read' and the system user must have 'View performance' task on each account.
-
+    description: `Lists ad accounts the business owns (owned_ad_accounts) and/or has access to (client_ad_accounts).
+
+Needs token scope 'ads_read' and the system user must have 'View performance' task on each account.
+
 Returns account_id (numeric), currency, timezone, status, balance, spend cap. Use 'act_<account_id>' when feeding downstream tools like meta_ads_get_insights.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/business/list-assets.js

@@ -34,16 +34,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_list_assets",
     title: "List assets assigned to a Business Manager",
-    description: `For a given business_id, enumerates the business assets the token can see in one call:
-- Ad accounts (owned + optionally client)
-- Facebook Pages (owned + optionally client)
-- Instagram Business accounts
-- Meta Pixels
-- Product catalogs
-- WhatsApp Business accounts (WABAs)
-
-Each section is fetched as a separate Graph call. Failures on individual sections do not abort the others — the response reports per-section success/error so the assistant can work around partial failures.
-
+    description: `For a given business_id, enumerates the business assets the token can see in one call:
+- Ad accounts (owned + optionally client)
+- Facebook Pages (owned + optionally client)
+- Instagram Business accounts
+- Meta Pixels
+- Product catalogs
+- WhatsApp Business accounts (WABAs)
+
+Each section is fetched as a separate Graph call. Failures on individual sections do not abort the others — the response reports per-section success/error so the assistant can work around partial failures.
+
 Use this to discover IDs for downstream insight tools.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/business/list-businesses.js

@@ -23,10 +23,10 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_list",
     title: "List Meta businesses visible to the token",
-    description: `Lists every Business Manager the configured access token can see — via GET /me/businesses.
-
-Typical usage: call this once at the start of a session to discover available business IDs, then pass the chosen ID to meta_business_list_assets / meta_business_list_system_users.
-
+    description: `Lists every Business Manager the configured access token can see — via GET /me/businesses.
+
+Typical usage: call this once at the start of a session to discover available business IDs, then pass the chosen ID to meta_business_list_assets / meta_business_list_system_users.
+
 Respects META_ALLOWED_BUSINESS_IDS: if set, filters the response to that allowlist.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/business/list-system-users.js

@@ -16,10 +16,10 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_list_system_users",
     title: "List system users attached to a business",
-    description: `Lists the system-user (server/software) identities under a Business Manager.
-
-System users are non-human identities used for API access. This tool helps diagnose which identity owns the token in use (cross-reference with meta_token_inspect).
-
+    description: `Lists the system-user (server/software) identities under a Business Manager.
+
+System users are non-human identities used for API access. This tool helps diagnose which identity owns the token in use (cross-reference with meta_token_inspect).
+
 Reads /{business_id}/system_users.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/instagram/get-audience-demographics.js

@@ -26,13 +26,13 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ig_get_audience_demographics",
     title: "Get IG audience demographics",
-    description: `Reads demographic breakdown of an IG Business account's followers, engaged audience, or reached audience. Use breakdown='age'|'gender'|'country'|'city' to slice.
-
-**Requirements (in order of frequency-of-failure):**
-1. Token has 'instagram_manage_insights' scope.
-2. The Hodusoft app must be approved for **Standard Access** on \`instagram_manage_insights\` via Meta App Review. In development tier, Meta returns \`(#10) Application does not have permission for this action\` on this endpoint specifically — even if the scope is on the token.
-3. The IG Business account must have ≥ 100 followers (Meta hides smaller accounts' demographics for privacy).
-
+    description: `Reads demographic breakdown of an IG Business account's followers, engaged audience, or reached audience. Use breakdown='age'|'gender'|'country'|'city' to slice.
+
+**Requirements (in order of frequency-of-failure):**
+1. Token has 'instagram_manage_insights' scope.
+2. The Hodusoft app must be approved for **Standard Access** on \`instagram_manage_insights\` via Meta App Review. In development tier, Meta returns \`(#10) Application does not have permission for this action\` on this endpoint specifically — even if the scope is on the token.
+3. The IG Business account must have ≥ 100 followers (Meta hides smaller accounts' demographics for privacy).
+
 If you see code (#10), it's almost always #2. Track the App Review request and surface the gap to the operator; this tool is functioning correctly when it returns that error.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/tools/instagram/get-media-insights.d.ts

@@ -14,7 +14,7 @@ export type Input = z.infer<typeof inputSchema>;
 export declare const definition: {
     readonly name: "meta_ig_get_media_insights";
     readonly title: "Get Instagram media insights";
-    readonly description: "Per-media metrics: reach, impressions, saves, likes, comments, shares, profile visits, follows-from-post. Requires 'instagram_manage_insights' scope.\n\nDifferent media types support different metric sets:\n- IMAGE/CAROUSEL_ALBUM: impressions, reach, saved, likes, comments, shares, profile_visits\n- VIDEO (Reels): plays, reach, likes, comments, shares, saved, total_interactions\n- STORY: impressions, reach, replies, exits, taps_forward, taps_back (use meta_ig_get_story_insights-style metrics)\n\nIf a metric is unsupported for the media type, Meta returns code 100 — retry with a narrower metric list.";
+    readonly description: "Per-media metrics: reach, views, saves, likes, comments, shares, total_interactions, profile_visits, follows.\n\n**Requirements (in order of frequency-of-failure):**\n1. Token has 'instagram_manage_insights' scope.\n2. **The configured app must be approved for Standard Access on `instagram_manage_insights` via Meta App Review.** In development tier, Meta returns `(#10) Application does not have permission for this action` for the IG insights endpoints — even if the scope is on the token. This applies to media insights AND audience demographics. Track the App Review request and surface this to the operator; this tool is functioning correctly when it returns that error.\n3. The IG account must be Business or Creator (not personal).\n\n**Metric / media-type compatibility (post v22 deprecations):**\n- IMAGE / CAROUSEL_ALBUM: reach, saved, likes, comments, shares, total_interactions, profile_visits\n- VIDEO / REELS: views, reach, likes, comments, shares, saved, total_interactions  ('impressions' is deprecated, use 'views')\n- STORY: views, reach, replies, navigation, profile_visits, follows  (impressions is deprecated; use views)\n\nIf you see code (#100) \"metric not supported for media type\", narrow the metrics list to the matching subset above. If you see code (#10), it's almost always App Review (#2 above).";
     readonly inputSchema: {
         media_id: z.ZodString;
         metrics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;

package/dist/tools/instagram/get-media-insights.js

@@ -7,31 +7,37 @@ export const inputSchema = z
     metrics: z
         .array(z.string())
         .default([
-        "impressions",
+        // v23-safe set covering Reels (the most common modern IG media type
+        // for marketing accounts). 'impressions' is deprecated for IG media
+        // in v22+; 'views' replaces it. See the description for media-type
+        // / metric compatibility.
         "reach",
-        "saved",
+        "views",
         "likes",
         "comments",
         "shares",
+        "saved",
         "total_interactions",
-        "profile_visits",
-        "follows",
-        "profile_activity",
     ])
-        .describe("IG media metrics. For Reels prefer 'plays, reach, likes, comments, shares, saved, total_interactions'. Some metrics are media_type-specific — if a metric isn't supported for the media type, Meta returns an error."),
+        .describe("IG media metrics. Defaults are v23-safe for Reels. For IMAGE/CAROUSEL_ALBUM you can drop 'views' and add 'profile_visits'. For STORY use ['views','reach','replies','navigation']. See the tool description for the full media-type/metric compatibility matrix."),
 })
     .strict();
 export const definition = {
     name: "meta_ig_get_media_insights",
     title: "Get Instagram media insights",
-    description: `Per-media metrics: reach, impressions, saves, likes, comments, shares, profile visits, follows-from-post. Requires 'instagram_manage_insights' scope.
-
-Different media types support different metric sets:
-- IMAGE/CAROUSEL_ALBUM: impressions, reach, saved, likes, comments, shares, profile_visits
-- VIDEO (Reels): plays, reach, likes, comments, shares, saved, total_interactions
-- STORY: impressions, reach, replies, exits, taps_forward, taps_back (use meta_ig_get_story_insights-style metrics)
-
-If a metric is unsupported for the media type, Meta returns code 100 — retry with a narrower metric list.`,
+    description: `Per-media metrics: reach, views, saves, likes, comments, shares, total_interactions, profile_visits, follows.
+
+**Requirements (in order of frequency-of-failure):**
+1. Token has 'instagram_manage_insights' scope.
+2. **The configured app must be approved for Standard Access on \`instagram_manage_insights\` via Meta App Review.** In development tier, Meta returns \`(#10) Application does not have permission for this action\` for the IG insights endpoints — even if the scope is on the token. This applies to media insights AND audience demographics. Track the App Review request and surface this to the operator; this tool is functioning correctly when it returns that error.
+3. The IG account must be Business or Creator (not personal).
+
+**Metric / media-type compatibility (post v22 deprecations):**
+- IMAGE / CAROUSEL_ALBUM: reach, saved, likes, comments, shares, total_interactions, profile_visits
+- VIDEO / REELS: views, reach, likes, comments, shares, saved, total_interactions  ('impressions' is deprecated, use 'views')
+- STORY: views, reach, replies, navigation, profile_visits, follows  (impressions is deprecated; use views)
+
+If you see code (#100) "metric not supported for media type", narrow the metrics list to the matching subset above. If you see code (#10), it's almost always App Review (#2 above).`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 };

package/dist/tools/instagram/list-accounts.js

@@ -10,8 +10,8 @@ export const inputSchema = z
 export const definition = {
     name: "meta_ig_list_accounts",
     title: "List Instagram Business accounts reachable via Pages",
-    description: `Walks the Pages visible to the token (/me/assigned_pages) and, for each, resolves the linked Instagram Business account via 'instagram_business_account'. This is the modern discovery path — the /owned_instagram_accounts business edge is unreliable.
-
+    description: `Walks the Pages visible to the token (/me/assigned_pages) and, for each, resolves the linked Instagram Business account via 'instagram_business_account'. This is the modern discovery path — the /owned_instagram_accounts business edge is unreliable.
+
 Requires 'instagram_basic' scope on the token and 'Analyze Instagram account' task on each IG.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/tools/meta/graph-read.js

@@ -23,13 +23,13 @@ const FORBIDDEN_PARAMS = new Set(["access_token", "appsecret_proof"]);
 export const definition = {
     name: "meta_graph_read",
     title: "Arbitrary read-only Graph API call",
-    description: `Escape-hatch for arbitrary GET requests against the Meta Graph API.
-
-This tool exists so the assistant can reach fields and endpoints that do not yet have a dedicated tool wrapper — without ever sending a write. The underlying HTTP client is hard-wired to GET only; POST/PUT/DELETE are refused before the request leaves the process.
-
-Rules:
-- Do NOT include 'access_token' or 'appsecret_proof' in params — they are added automatically.
-- Do NOT prefix the path with the API version.
+    description: `Escape-hatch for arbitrary GET requests against the Meta Graph API.
+
+This tool exists so the assistant can reach fields and endpoints that do not yet have a dedicated tool wrapper — without ever sending a write. The underlying HTTP client is hard-wired to GET only; POST/PUT/DELETE are refused before the request leaves the process.
+
+Rules:
+- Do NOT include 'access_token' or 'appsecret_proof' in params — they are added automatically.
+- Do NOT prefix the path with the API version.
 - Prefer dedicated tools (meta_business_list_assets, meta_ads_get_insights, …) when they exist. Use this as a last resort.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/overview/business-overview.js

@@ -19,16 +19,16 @@ export const inputSchema = z
 export const definition = {
     name: "meta_business_overview",
     title: "Eagle's-eye snapshot of a business",
-    description: `One-call consolidated read across the whole Meta surface for a business:
-
-- Identity (system user + token app)
-- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
-- Instagram Business accounts linked to those Pages (followers, media_count)
-- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
-- Pixels with last_fired_time (if include_pixels)
-- Catalogs with product counts (if include_catalogs)
-- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
-
+    description: `One-call consolidated read across the whole Meta surface for a business:
+
+- Identity (system user + token app)
+- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
+- Instagram Business accounts linked to those Pages (followers, media_count)
+- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
+- Pixels with last_fired_time (if include_pixels)
+- Catalogs with product counts (if include_catalogs)
+- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
+
 Each section has its own error isolation — one failing asset does not kill the report. Ideal as the opening call for any AI-driven marketing insights conversation.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/tools/pages/get-post-insights.js

@@ -27,8 +27,8 @@ export const inputSchema = z
 export const definition = {
     name: "meta_page_get_post_insights",
     title: "Get insights for a single Page post",
-    description: `Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post.
-
+    description: `Reads impressions, unique reach, paid vs. organic split, engaged users, click counts, reactions-by-type, and video view metrics for a single post.
+
 Uses the parent Page's access token (auto-resolved from the '{page_id}_{post_id}' prefix; pass page_id explicitly if your post_id isn't in that form). Requires the system user to be assigned to the Page with 'View performance' or 'Analyze Page' tasks, plus 'read_insights' scope on the token.`,
     inputSchema: inputSchema.shape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/tools/token/health.js

@@ -5,12 +5,12 @@ export const inputSchema = z.object({}).strict();
 export const definition = {
     name: "meta_health_check",
     title: "Meta MCP health check",
-    description: `End-to-end reachability probe:
-- Confirms the Graph API is reachable.
-- Confirms the configured token resolves to a valid identity (via /me).
-- Surfaces the latest rate-limit header snapshot from the Graph client.
-- Lists which allowlists are active (business / ad account / page / IG user).
-
+    description: `End-to-end reachability probe:
+- Confirms the Graph API is reachable.
+- Confirms the configured token resolves to a valid identity (via /me).
+- Surfaces the latest rate-limit header snapshot from the Graph client.
+- Lists which allowlists are active (business / ad account / page / IG user).
+
 Use when a session starts, or when diagnosing why other tools are returning errors.`,
     inputSchema: inputSchema.shape,
     annotations: {

package/dist/tools/token/inspect.js

@@ -10,17 +10,17 @@ export const inputSchema = z
 export const definition = {
     name: "meta_token_inspect",
     title: "Inspect Meta access token",
-    description: `Decodes the configured META_ACCESS_TOKEN via Graph API /debug_token.
-
-Returns:
-- app_id + application name
-- token type (system-user / user / page)
-- is_valid
-- expires_at + data_access_expires_at (unix seconds; 0 = never expires)
-- scopes + granular_scopes (per-asset targeting)
-
-Use this first when troubleshooting — almost every other tool failure traces back to a missing scope or an asset not assigned to the token.
-
+    description: `Decodes the configured META_ACCESS_TOKEN via Graph API /debug_token.
+
+Returns:
+- app_id + application name
+- token type (system-user / user / page)
+- is_valid
+- expires_at + data_access_expires_at (unix seconds; 0 = never expires)
+- scopes + granular_scopes (per-asset targeting)
+
+Use this first when troubleshooting — almost every other tool failure traces back to a missing scope or an asset not assigned to the token.
+
 Never logs the token itself.`,
     inputSchema: inputSchema.shape,
     annotations: {

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

@@ -30,8 +30,8 @@ export const inputSchema = z
 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).
-
+    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 },

package/package.json

@@ -1,77 +1,77 @@
-{
-  "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.2",
-  "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"
-  }
-}
+{
+  "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.6",
+  "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"
+  }
+}