@praise25/meta-mcp-server 0.1.1 → 0.1.5

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

@@ -1,9 +1,12 @@
 import { z } from "zod";
 import { metaIdSchema } from "../../helpers/schema.js";
-import { runGet } from "../shared.js";
+import { errorResult, runGetAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
-    post_id: metaIdSchema.describe("Post ID (format '{page_id}_{post_id}' or shortform)."),
+    post_id: metaIdSchema.describe("Post ID. Meta uses the '{page_id}_{post_id}' format — pass it in full so the server can resolve the parent Page's access token automatically."),
+    page_id: metaIdSchema
+        .optional()
+        .describe("Optional explicit Page ID. Use when the post_id is not in the '{page_id}_{post_id}' form (rare)."),
     metrics: z
         .array(z.string())
         .default([
@@ -18,18 +21,26 @@ export const inputSchema = z
         "post_video_views_unique",
         "post_video_avg_time_watched",
     ])
-        .describe("Post-level insight metrics. See https://developers.facebook.com/docs/graph-api/reference/v23.0/insights"),
+        .describe("Post-level insight metrics. See https://developers.facebook.com/docs/graph-api/reference/v23.0/insights. Requires 'read_insights' scope. Note: Meta will reject the call if any single metric is invalid for the post type — narrow the list if you see (#100)."),
 })
     .strict();
 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. Requires 'read_insights' scope.`,
+    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 },
 };
 export async function handler(input, ctx) {
-    return runGet(ctx, {
+    // Resolve the parent Page id either from an explicit input or from the
+    // '{page_id}_{post_id}' prefix of the post_id.
+    const parentPageId = input.page_id ?? input.post_id.split("_")[0];
+    if (!/^\d+$/.test(parentPageId)) {
+        return errorResult(new Error(`Could not infer parent Page ID from post_id '${input.post_id}'. Pass page_id explicitly.`));
+    }
+    return runGetAsPage(ctx, parentPageId, {
         path: `${input.post_id}/insights`,
         params: { metric: input.metrics.join(",") },
     });

package/dist/tools/pages/list-posts.d.ts

@@ -20,9 +20,9 @@ export declare const inputSchema: z.ZodObject<{
     after?: string | undefined;
 }, {
     page_id: string;
+    fields?: string[] | undefined;
     since?: string | undefined;
     until?: string | undefined;
-    fields?: string[] | undefined;
     limit?: number | undefined;
     after?: string | undefined;
     auto_paginate?: boolean | undefined;

package/dist/tools/pages/list-posts.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assertAllowed } from "../../config.js";
 import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
-import { runList } from "../shared.js";
+import { runListAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
     page_id: metaIdSchema,
@@ -14,21 +14,25 @@ export const inputSchema = z
     fields: z
         .array(z.string())
         .default([
+        // Note: 'subattachments' is deprecated as of Graph API v3.3+ for
+        // aggregate field expansion (#12 deprecate_post_aggregated_fields_for_attachement).
+        // Removed from default. Likewise 'is_published' and 'type' are
+        // deprecated for some post kinds — kept out of the default to keep
+        // the call shape valid across all post types. Re-add via the fields
+        // input if you need them and have verified the call still passes.
         "id",
         "message",
         "created_time",
         "updated_time",
         "permalink_url",
         "status_type",
-        "type",
-        "is_published",
         "from",
-        "attachments{media_type,title,url,subattachments}",
+        "attachments{media_type,title,url}",
         "reactions.summary(true).limit(0)",
         "shares",
         "comments.summary(true).limit(0)",
     ])
-        .describe("Post fields. Default includes reaction + comment counts via summary."),
+        .describe("Post fields. Default includes reaction + comment counts via summary. 'subattachments', 'is_published' and 'type' are excluded by default — Meta deprecated them on certain post types and including them rejects the whole call."),
     ...paginationShape,
 })
     .strict();
@@ -41,7 +45,9 @@ export const definition = {
 };
 export async function handler(input, ctx) {
     assertAllowed("page", input.page_id, ctx.config);
-    return runList(ctx, {
+    // Page-level edges (/posts, /published_posts, /feed) require a Page access
+    // token, not the system-user token. runListAsPage resolves it first.
+    return runListAsPage(ctx, input.page_id, {
         path: `${input.page_id}/${input.edge}`,
         params: {
             fields: input.fields.join(","),

package/dist/tools/pages/list-reviews.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assertAllowed } from "../../config.js";
 import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
-import { runList } from "../shared.js";
+import { runListAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
     page_id: metaIdSchema,
@@ -30,7 +30,7 @@ export const definition = {
 };
 export async function handler(input, ctx) {
     assertAllowed("page", input.page_id, ctx.config);
-    return runList(ctx, {
+    return runListAsPage(ctx, input.page_id, {
         path: `${input.page_id}/ratings`,
         params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
     }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { page_id: input.page_id });

package/dist/tools/pages/list-videos.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assertAllowed } from "../../config.js";
 import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
-import { runList } from "../shared.js";
+import { runListAsPage } from "../shared.js";
 export const inputSchema = z
     .object({
     page_id: metaIdSchema,
@@ -33,7 +33,7 @@ export const definition = {
 };
 export async function handler(input, ctx) {
     assertAllowed("page", input.page_id, ctx.config);
-    return runList(ctx, {
+    return runListAsPage(ctx, input.page_id, {
         path: `${input.page_id}/videos`,
         params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
     }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { page_id: input.page_id });

package/dist/tools/pixels/list.js

@@ -8,17 +8,20 @@ export const inputSchema = z
     fields: z
         .array(z.string())
         .default([
+        // 'code' (the pixel's JS snippet) and 'owner_ad_account' both require
+        // ads_management on the *owning* ad account, not just the business.
+        // Reading them with a system-user token that wasn't granted that
+        // task fails the whole list with (#200). We omit them from the
+        // defaults so the list stays useful; callers can re-add explicitly.
         "id",
         "name",
-        "code",
         "is_created_by_business",
         "is_unavailable",
         "last_fired_time",
         "creation_time",
-        "owner_ad_account",
         "owner_business",
     ])
-        .describe("Pixel fields."),
+        .describe("Pixel fields. 'code' and 'owner_ad_account' are NOT in the default — they require ads_management on the owning ad account. Re-add them only when the system user has that task on every pixel's owner account."),
     ...paginationShape,
 })
     .strict();

package/dist/tools/shared.d.ts

@@ -18,3 +18,13 @@ export declare function runList<T>(ctx: ToolContext, opts: GraphGetOptions, pag:
 /** Run a single read and return a tool result. */
 export declare function runGet<T>(ctx: ToolContext, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;
 export declare function errorResult(err: unknown): ToolTextResult;
+/**
+ * Resolves a Page access token for `pageId`, then runs `runList` with it as
+ * the access-token override. Page-level edges (`/{page_id}/posts`,
+ * `/{page_id}/insights`, `/{page_id}/ratings`, `/{page_id}/videos`,
+ * `/{post_id}/insights`) require a Page access token rather than the
+ * configured system-user token.
+ */
+export declare function runListAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, pag: ListRunOpts, extra?: Record<string, unknown>): Promise<ToolTextResult>;
+/** Same as runGet but resolves and uses the Page access token first. */
+export declare function runGetAsPage<T>(ctx: ToolContext, pageId: string, opts: GraphGetOptions, extra?: Record<string, unknown>): Promise<ToolTextResult>;

package/dist/tools/shared.js

@@ -53,3 +53,29 @@ export function errorResult(err) {
         retryable: e.retryable,
     });
 }
+/**
+ * Resolves a Page access token for `pageId`, then runs `runList` with it as
+ * the access-token override. Page-level edges (`/{page_id}/posts`,
+ * `/{page_id}/insights`, `/{page_id}/ratings`, `/{page_id}/videos`,
+ * `/{post_id}/insights`) require a Page access token rather than the
+ * configured system-user token.
+ */
+export async function runListAsPage(ctx, pageId, opts, pag, extra = {}) {
+    try {
+        const pageToken = await ctx.graph.getPageAccessToken(pageId);
+        return runList(ctx, { ...opts, accessTokenOverride: pageToken }, pag, extra);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+/** Same as runGet but resolves and uses the Page access token first. */
+export async function runGetAsPage(ctx, pageId, opts, extra = {}) {
+    try {
+        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: {

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/dist/tools/whatsapp/list-templates.d.ts

@@ -16,8 +16,8 @@ export declare const inputSchema: z.ZodObject<{
     after?: string | undefined;
 }, {
     waba_id: string;
-    status?: "PAUSED" | "DELETED" | "APPROVED" | "PENDING" | "REJECTED" | "DISABLED" | "IN_APPEAL" | undefined;
     fields?: string[] | undefined;
+    status?: "PAUSED" | "DELETED" | "APPROVED" | "PENDING" | "REJECTED" | "DISABLED" | "IN_APPEAL" | undefined;
     limit?: number | undefined;
     after?: string | undefined;
     auto_paginate?: boolean | undefined;

package/package.json

@@ -1,76 +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.1",
-  "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": "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.5",
+  "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"
+  }
+}