@praise25/meta-mcp-server 0.1.8 → 0.1.11

package/dist/tools/shared.js

@@ -1,5 +1,24 @@
+/**
+ * Shared helpers used across domain tools — keeps each tool file focused on
+ * its endpoint instead of re-implementing boilerplate.
+ */
+import { insightsCreds } from "../config.js";
 import { MetaError } from "../errors.js";
 import { jsonBlock, toolError, toolResult } from "../helpers/format.js";
+/**
+ * If a secondary "insights app" is configured, returns the token + app-secret
+ * overrides to route this call through it; otherwise returns an empty object
+ * (call uses the primary app). Insight endpoints (IG media/audience, Page/post
+ * insights) need this because Meta forbids combining the Marketing-API use
+ * case with Instagram-content / Pages-everything on a single app — so insights
+ * frequently live on a second app. See config.ts `insightsCreds`.
+ */
+function insightsOverrides(ctx) {
+    const creds = insightsCreds(ctx.config);
+    if (!creds)
+        return {};
+    return { accessTokenOverride: creds.token, appSecretOverride: creds.appSecret };
+}
 /**
  * Fetch one page or auto-paginate, normalize into a structured list payload,
  * and translate errors. Use for simple `GET /{id}/{edge}` style tools.
@@ -43,6 +62,16 @@ export async function runGet(ctx, opts, extra = {}) {
         return errorResult(err);
     }
 }
+/**
+ * Like runGet, but routes through the secondary insights-app token + secret
+ * when one is configured (META_INSIGHTS_ACCESS_TOKEN). Use for direct
+ * `/{id}/insights` reads that require a permission (e.g.
+ * instagram_manage_insights) the primary ads app cannot host. Falls back to
+ * the primary token transparently when no insights app is configured.
+ */
+export async function runGetViaInsightsApp(ctx, opts, extra = {}) {
+    return runGet(ctx, { ...opts, ...insightsOverrides(ctx) }, extra);
+}
 export function errorResult(err) {
     const e = err instanceof MetaError ? err : new MetaError(err.message);
     return toolError(e.message, e.hint, {
@@ -79,3 +108,30 @@ export async function runGetAsPage(ctx, pageId, opts, extra = {}) {
         return errorResult(err);
     }
 }
+/**
+ * Page-insights variant of runGetAsPage. When a secondary insights app is
+ * configured (the app holding the Pages "read_insights" use case), the Page
+ * access token is derived from the *insights* app's token and the call's
+ * appsecret_proof uses the insights app secret. Falls back to the primary
+ * app's Page token when no insights app is configured.
+ *
+ * Use for /{page_id}/insights and /{post_id}/insights, which need
+ * `read_insights` — a permission the Marketing-API primary app cannot host.
+ */
+export async function runGetAsPageViaInsightsApp(ctx, pageId, opts, extra = {}) {
+    try {
+        const creds = insightsCreds(ctx.config);
+        if (creds) {
+            const pageToken = await ctx.graph.getPageAccessToken(pageId, {
+                token: creds.token,
+                appSecret: creds.appSecret,
+            });
+            return runGet(ctx, { ...opts, accessTokenOverride: pageToken, appSecretOverride: creds.appSecret }, extra);
+        }
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runGet(ctx, { ...opts, accessTokenOverride: pageToken }, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}

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: {
@@ -34,6 +34,8 @@ export async function handler(_input, ctx) {
             identity: me,
             api_version: ctx.config.apiVersion,
             appsecret_proof_enabled: Boolean(ctx.config.appSecret),
+            insights_app_configured: Boolean(ctx.config.insightsAccessToken),
+            insights_app_appsecret_proof_enabled: Boolean(ctx.config.insightsAppSecret),
             rate_limit: ctx.graph.rateLimit,
             allowlists: {
                 businesses: ctx.config.allowedBusinessIds ? [...ctx.config.allowedBusinessIds] : null,

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.8",
-  "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.11",
+  "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"
+  }
+}