@praise25/meta-mcp-server 0.1.8 → 0.1.10

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).