facebook-mcp-server 1.6.6

package/dist/index.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * Standalone Facebook Pages MCP Server
+ *
+ * Dual-purpose SENSE + ACT server for the Facebook Graph API (Pages).
+ * Facebook publishes are synchronous — one POST to /{page-id}/feed
+ * (or /photos, /videos) returns the new post ID directly.
+ *
+ * Tools:
+ *   SENSE: fb_get_page_insights, fb_get_post_insights, fb_get_comments,
+ *          fb_get_page_feed
+ *   ACT:   fb_create_post, fb_reply_comment, fb_delete_post
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { textResult, errorResult, senseResult } from "./response.js";
+import { createClient, FacebookApiError, } from "./client.js";
+import { waitForRateLimit, withRetry } from "./rate-limiter.js";
+import { sanitize } from "./sanitize.js";
+import { extractApiDetail, suggestAction } from "./errors.js";
+import { buildCreatePostRequest } from "./create-post.js";
+import { fetchPageInsights, fetchPostInsights, fetchPageFeed, } from "./lib/insights.js";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+// --- Env-based defaults ---
+const DEFAULT_ACCESS_TOKEN = process.env.FACEBOOK_ACCESS_TOKEN;
+const DEFAULT_PAGE_ID = process.env.FACEBOOK_PAGE_ID;
+// --- Credential resolution ---
+const credentialFields = {
+    accessToken: z
+        .string()
+        .optional()
+        .describe("Facebook Page access token. Falls back to FACEBOOK_ACCESS_TOKEN env var."),
+    pageId: z
+        .string()
+        .optional()
+        .describe("Facebook Page ID (the numeric id of the page you admin). Falls back to FACEBOOK_PAGE_ID env var."),
+};
+export function resolveCredentials(args) {
+    const accessToken = args.accessToken || DEFAULT_ACCESS_TOKEN;
+    const pageId = args.pageId || DEFAULT_PAGE_ID;
+    if (!accessToken || !pageId)
+        return null;
+    return { accessToken, pageId };
+}
+export async function getClient(args, toolName) {
+    const creds = resolveCredentials(args);
+    if (!creds) {
+        return {
+            ok: false,
+            error: errorResult("Missing credentials", "Provide accessToken + pageId as arguments, or set FACEBOOK_ACCESS_TOKEN and FACEBOOK_PAGE_ID env vars."),
+        };
+    }
+    // Pre-flight rate limit check (per-tenant, keyed by pageId)
+    const limit = await waitForRateLimit(toolName, creds.pageId);
+    if (!limit.allowed) {
+        const retryAfterSeconds = Math.ceil(limit.retryAfterMs / 1000);
+        return {
+            ok: false,
+            error: errorResult("Rate limited", `Facebook API rate limit reached. Wait ${retryAfterSeconds}s then retry.`, {
+                retryAfterSeconds,
+                action: retryAfterSeconds <= 120
+                    ? `RETRY_AFTER_WAIT: Sleep ${retryAfterSeconds}s then retry this tool call.`
+                    : `DEFER: Rate limit cooldown is ${retryAfterSeconds}s. Switch to a different task.`,
+            }),
+        };
+    }
+    try {
+        const client = createClient(creds);
+        return { ok: true, client };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : "Unknown error";
+        return {
+            ok: false,
+            error: errorResult("Client error", `Failed to create Facebook client: ${msg}`),
+        };
+    }
+}
+// --- Error handling ---
+export function safeHandler(toolName, handler) {
+    return async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (e) {
+            try {
+                const msg = e instanceof Error ? e.message : String(e);
+                const detail = extractApiDetail(e);
+                const statusCode = e instanceof FacebookApiError ? e.status : undefined;
+                const action = suggestAction(toolName, statusCode, detail, msg);
+                console.error(`[${toolName}] Error: ${msg}${detail ? ` — ${detail}` : ""}`);
+                return errorResult("API error", `${toolName} failed: ${detail || msg}`, {
+                    ...(statusCode !== undefined && { statusCode }),
+                    ...(detail && detail !== msg && { rawError: msg }),
+                    ...(action && { action }),
+                });
+            }
+            catch (formatErr) {
+                const fallback = e instanceof Error ? e.message : "Unknown error";
+                const fmtMsg = formatErr instanceof Error ? formatErr.message : String(formatErr);
+                console.error(`[${toolName}] Error (fallback): ${fallback} — error formatting also failed: ${fmtMsg}`);
+                return errorResult("API error", `${toolName} failed: ${fallback}`);
+            }
+        }
+    };
+}
+// --- Server Setup ---
+const server = new McpServer({
+    name: "facebook-mcp-server",
+    version,
+});
+// =====================
+// SENSE Tools (read)
+// =====================
+server.registerTool("fb_get_page_insights", {
+    description: "Get Facebook Page insights: impressions, reach, post engagements, and follower count over a period.",
+    inputSchema: {
+        ...credentialFields,
+        period: z
+            .enum(["day", "week", "days_28"])
+            .optional()
+            .describe('Aggregation period (default: "day")'),
+        since: z
+            .string()
+            .optional()
+            .describe("Start date as Unix timestamp (e.g., '1700000000')"),
+        until: z.string().optional().describe("End date as Unix timestamp"),
+    },
+}, safeHandler("fb_get_page_insights", async (args) => {
+    const result = await getClient(args, "fb_get_page_insights");
+    if (!result.ok)
+        return result.error;
+    const { client } = result;
+    const data = await fetchPageInsights(client, {
+        period: args.period,
+        since: args.since,
+        until: args.until,
+    });
+    return senseResult(data, "Facebook");
+}));
+server.registerTool("fb_get_post_insights", {
+    description: "Get engagement metrics for a specific Facebook post: impressions, engaged users, clicks, and reactions.",
+    inputSchema: {
+        ...credentialFields,
+        postId: z
+            .string()
+            .describe("Facebook post ID (format: {page-id}_{post-id} or just post id)"),
+    },
+}, safeHandler("fb_get_post_insights", async (args) => {
+    if (!args.postId.trim())
+        return errorResult("Invalid input", "postId cannot be empty");
+    const result = await getClient(args, "fb_get_post_insights");
+    if (!result.ok)
+        return result.error;
+    const { client } = result;
+    const data = await fetchPostInsights(client, { postId: args.postId });
+    return senseResult(data, "Facebook");
+}));
+server.registerTool("fb_get_comments", {
+    description: "Get comments on a Facebook post. Returns comment text, author name, and timestamps. Content is sanitized for safe agent consumption.",
+    inputSchema: {
+        ...credentialFields,
+        postId: z.string().describe("Facebook post ID"),
+        limit: z
+            .number()
+            .optional()
+            .describe("Number of comments (default: 25, max: 100)"),
+        after: z.string().optional().describe("Pagination cursor"),
+    },
+}, safeHandler("fb_get_comments", async (args) => {
+    if (!args.postId.trim())
+        return errorResult("Invalid input", "postId cannot be empty");
+    const result = await getClient(args, "fb_get_comments");
+    if (!result.ok)
+        return result.error;
+    const { client } = result;
+    const params = {
+        fields: "id,message,from{id,name},created_time,like_count,comment_count",
+        limit: String(Math.min(args.limit || 25, 100)),
+    };
+    if (args.after)
+        params.after = args.after;
+    const response = await withRetry(() => client.get(`/${args.postId}/comments`, params));
+    // Sanitize user-generated content
+    const comments = (response.data || []).map((c) => ({
+        id: c.id,
+        message: sanitize(c.message || ""),
+        author: c.from
+            ? { id: c.from.id, name: sanitize(c.from.name) }
+            : undefined,
+        createdTime: c.created_time,
+        likeCount: c.like_count ?? 0,
+        replyCount: c.comment_count ?? 0,
+    }));
+    return senseResult({
+        postId: args.postId,
+        comments,
+        count: comments.length,
+        nextCursor: response.paging?.cursors?.after,
+    }, "Facebook");
+}));
+server.registerTool("fb_get_page_feed", {
+    description: "Get the Facebook Page's own feed (posts you've published). Returns post id, message, type, timestamp, shares, and permalink.",
+    inputSchema: {
+        ...credentialFields,
+        limit: z
+            .number()
+            .optional()
+            .describe("Number of posts to fetch (default: 25, max: 100)"),
+        after: z.string().optional().describe("Pagination cursor"),
+    },
+}, safeHandler("fb_get_page_feed", async (args) => {
+    const result = await getClient(args, "fb_get_page_feed");
+    if (!result.ok)
+        return result.error;
+    const { client } = result;
+    const data = await fetchPageFeed(client, {
+        limit: args.limit,
+        after: args.after,
+    });
+    return senseResult(data, "Facebook");
+}));
+// =====================
+// ACT Tools (write)
+// =====================
+/**
+ * Optionally post a top-level comment on a just-created Facebook post (#1995).
+ * Returns { id } on success, { error } on failure, {} if no firstComment given.
+ * Mirrors the LinkedIn first-comment contract: 3-5s random delay, 2000 char cap.
+ */
+export async function postFirstComment(client, postId, firstComment) {
+    const trimmed = firstComment?.trim();
+    if (!trimmed)
+        return {};
+    const commentText = trimmed.slice(0, 2000);
+    try {
+        const delayMs = 3000 + Math.random() * 2000;
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        const commentResponse = await withRetry(() => client.post(`/${postId}/comments`, {
+            message: commentText,
+        }));
+        return { id: commentResponse.id };
+    }
+    catch (e) {
+        const errMsg = e instanceof Error ? e.message : String(e);
+        console.error(`[fb_create_post] First comment failed: ${errMsg}`);
+        return { error: errMsg };
+    }
+}
+server.registerTool("fb_create_post", {
+    description: "Create a Facebook Page post. Supports text, link, photo, or video. Photos and videos must have publicly accessible HTTPS URLs. Returns the new post ID. Publishing is synchronous — no container flow.",
+    inputSchema: {
+        ...credentialFields,
+        message: z
+            .string()
+            .optional()
+            .describe("Post text. Required for text-only posts, optional for photo/video/link."),
+        link: z
+            .string()
+            .optional()
+            .describe("URL to share as a link preview. Mutually exclusive with imageUrl/videoUrl."),
+        imageUrl: z
+            .string()
+            .optional()
+            .describe("Publicly accessible image URL for a photo post. Mutually exclusive with link/videoUrl."),
+        videoUrl: z
+            .string()
+            .optional()
+            .describe("Publicly accessible video URL for a video post. Mutually exclusive with link/imageUrl."),
+        published: z
+            .boolean()
+            .optional()
+            .describe("Whether to publish immediately (default: true). Set false to create an unpublished draft."),
+        firstComment: z
+            .string()
+            .optional()
+            .describe("Optional follow-up comment posted ~a few seconds after the post for engagement (max 2000 chars). " +
+            "Facebook suppresses link-in-body reach so first-comment is the canonical place for a link/CTA. " +
+            "The comment is posted by the authenticated Page. Omit or leave blank to skip."),
+    },
+}, safeHandler("fb_create_post", async (args) => {
+    const validation = buildCreatePostRequest(args);
+    if (!validation.ok) {
+        return errorResult(validation.error, validation.message, {
+            ...(validation.action && { action: validation.action }),
+        });
+    }
+    const result = await getClient(args, "fb_create_post");
+    if (!result.ok)
+        return result.error;
+    const { client } = result;
+    const endpoint = validation.endpoint(client.pageId);
+    const response = await withRetry(() => client.post(endpoint, validation.body));
+    // Photos/videos return { id, post_id } where post_id is the feed-level id
+    const postId = response.post_id || response.id;
+    // First comment (if provided). Partial-success: post is already live, so a
+    // comment failure must surface explicitly — never a clean success (#1931).
+    const fc = await postFirstComment(client, postId, args.firstComment);
+    if (fc.error) {
+        return errorResult("Partial failure", `Post created (${postId}) but first comment failed: ${fc.error}. Use fb_reply_comment to retry.`, { id: postId, mediaId: response.id, type: validation.type });
+    }
+    return textResult({
+        id: postId,
+        mediaId: response.id,
+        type: validation.type,
+        ...(fc.id && { firstCommentId: fc.id }),
+        message: fc.id
+            ? "Post created with first comment"
+            : "Post created successfully",
+    });
+}));
+server.registerTool("fb_reply_comment", {
+    description: "Reply to a comment on a Facebook post.",
+    inputSchema: {
+        ...credentialFields,
+        commentId: z.string().describe("ID of the comment to reply to"),
+        message: z.string().describe("Reply text"),
+    },
+}, safeHandler("fb_reply_comment", async (args) => {
+    if (!args.commentId.trim())
+        return errorResult("Invalid input", "commentId cannot be empty");
+    if (!args.message.trim())
+        return errorResult("Invalid input", "message cannot be empty");
+    const result = await getClient(args, "fb_reply_comment");
+    if (!result.ok)
+        return result.error;
+    const { client } = result;
+    const response = await withRetry(() => client.post(`/${args.commentId}/comments`, {
+        message: args.message,
+    }));
+    return textResult({
+        id: response.id,
+        parentCommentId: args.commentId,
+        message: "Reply posted successfully",
+    });
+}));
+server.registerTool("fb_delete_post", {
+    description: "Delete a Facebook Page post you published. The post ID must belong to the authenticated Page.",
+    inputSchema: {
+        ...credentialFields,
+        postId: z.string().describe("ID of the post to delete"),
+    },
+}, safeHandler("fb_delete_post", async (args) => {
+    if (!args.postId.trim())
+        return errorResult("Invalid input", "postId cannot be empty");
+    const result = await getClient(args, "fb_delete_post");
+    if (!result.ok)
+        return result.error;
+    const { client } = result;
+    await withRetry(() => client.delete(`/${args.postId}`));
+    return textResult({
+        postId: args.postId,
+        message: "Post deleted successfully",
+    });
+}));
+// --- Start ---
+export { server };
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Facebook MCP Server running on stdio");
+}
+// Only start the stdio transport when invoked directly, not when imported
+// by test files. Compares import.meta.url to the script entrypoint.
+const isDirectRun = process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (isDirectRun) {
+    main().catch((e) => {
+        console.error("Fatal:", e);
+        process.exit(1);
+    });
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface for programmatic (non-MCP) consumers.
+ *
+ * Import from `facebook-mcp-server/lib` to use the insights functions and
+ * Graph API client directly without spinning up the MCP server.
+ */
+export * from "./insights.js";
+export { FacebookClient, FacebookApiError, createClient } from "../client.js";
+export type { Credentials, GraphApiError } from "../client.js";

package/dist/lib/index.js

@@ -0,0 +1,8 @@
+/**
+ * Public surface for programmatic (non-MCP) consumers.
+ *
+ * Import from `facebook-mcp-server/lib` to use the insights functions and
+ * Graph API client directly without spinning up the MCP server.
+ */
+export * from "./insights.js";
+export { FacebookClient, FacebookApiError, createClient } from "../client.js";

package/dist/lib/insights.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure SENSE/insights functions for the Facebook Graph API.
+ *
+ * Used by:
+ *   1. The MCP server's tool handlers (wrapped in `senseResult` for MCP protocol).
+ *   2. Any programmatic consumer importing from `facebook-mcp-server/lib`.
+ */
+import type { FacebookClient } from "../client.js";
+export interface PageInsightsArgs {
+    /** "day" | "week" | "days_28". Default: "day". */
+    period?: string;
+    /** Unix timestamp (string), inclusive. */
+    since?: string;
+    /** Unix timestamp (string), inclusive. */
+    until?: string;
+}
+export interface PageInsightsResult {
+    /** Period echoed back from the request. */
+    period: string;
+    /** Raw Graph API insights array — one element per metric. */
+    insights: unknown[];
+}
+export declare function fetchPageInsights(client: FacebookClient, args?: PageInsightsArgs): Promise<PageInsightsResult>;
+export interface PostInsightsArgs {
+    /** Facebook post ID, e.g. `{page-id}_{post-id}` or just post id. */
+    postId: string;
+}
+export interface PostInsightsResult {
+    postId: string;
+    insights: unknown[];
+}
+export declare function fetchPostInsights(client: FacebookClient, args: PostInsightsArgs): Promise<PostInsightsResult>;
+export interface PageFeedArgs {
+    /** Default 25, max 100. */
+    limit?: number;
+    /** Pagination cursor. */
+    after?: string;
+}
+export interface FeedPost {
+    id: string;
+    message: string;
+    createdTime: string;
+    permalinkUrl?: string;
+    shareCount: number;
+    statusType?: string;
+    story?: string;
+}
+export interface PageFeedResult {
+    posts: FeedPost[];
+    count: number;
+    nextCursor?: string;
+}
+export declare function fetchPageFeed(client: FacebookClient, args?: PageFeedArgs): Promise<PageFeedResult>;

package/dist/lib/insights.js

@@ -0,0 +1,47 @@
+import { withRetry } from "../rate-limiter.js";
+import { sanitize } from "../sanitize.js";
+const PAGE_INSIGHTS_METRICS = "page_impressions_unique,page_post_engagements,page_views_total,page_follows";
+export async function fetchPageInsights(client, args = {}) {
+    const params = {
+        metric: PAGE_INSIGHTS_METRICS,
+        period: args.period || "day",
+    };
+    if (args.since)
+        params.since = args.since;
+    if (args.until)
+        params.until = args.until;
+    const response = await withRetry(() => client.get(`/${client.pageId}/insights`, params));
+    return { insights: response.data, period: params.period };
+}
+const POST_INSIGHTS_METRICS = "post_impressions_unique,post_clicks,post_reactions_by_type_total";
+export async function fetchPostInsights(client, args) {
+    if (!args.postId.trim())
+        throw new Error("postId cannot be empty");
+    const response = await withRetry(() => client.get(`/${args.postId}/insights`, {
+        metric: POST_INSIGHTS_METRICS,
+    }));
+    return { postId: args.postId, insights: response.data };
+}
+export async function fetchPageFeed(client, args = {}) {
+    const params = {
+        fields: "id,message,created_time,permalink_url,shares,status_type,story",
+        limit: String(Math.min(args.limit || 25, 100)),
+    };
+    if (args.after)
+        params.after = args.after;
+    const response = await withRetry(() => client.get(`/${client.pageId}/feed`, params));
+    const posts = (response.data || []).map((p) => ({
+        id: p.id,
+        message: sanitize(p.message || ""),
+        createdTime: p.created_time,
+        permalinkUrl: p.permalink_url,
+        shareCount: p.shares?.count ?? 0,
+        statusType: p.status_type,
+        story: p.story ? sanitize(p.story) : undefined,
+    }));
+    return {
+        posts,
+        count: posts.length,
+        nextCursor: response.paging?.cursors?.after,
+    };
+}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Token-bucket rate limiter for Facebook Graph API.
+ *
+ * Facebook Graph API rate limits are per **Page**, not per app. This limiter
+ * keys buckets by the caller's `tenantKey` (the page id) so that one
+ * dashboard user posting aggressively cannot exhaust another user's quota.
+ *
+ * Each tenant gets an independent pair of buckets:
+ *   - globalBucket:  200 tokens / 1 hour  (all API calls)
+ *   - publishBucket:  25 tokens / 24 hours (fb_create_post only)
+ *
+ * When `tenantKey` is undefined (single-tenant / env-based usage), all calls
+ * share a single default bucket pair under the sentinel key "__default__".
+ *
+ * Stale tenant entries are evicted after 4h of inactivity on every call to
+ * keep memory bounded for long-running multi-tenant servers.
+ *
+ * Also provides:
+ *   - waitForRateLimit(): pre-flight check with optional wait
+ *   - withRetry(): exponential backoff on server-side 429s
+ */
+export declare class TokenBucket {
+    private tokens;
+    private lastRefill;
+    private readonly maxTokens;
+    private readonly refillRate;
+    constructor(config: {
+        maxTokens: number;
+        refillRate: number;
+    });
+    tryConsume(cost?: number): boolean;
+    msUntilAvailable(cost?: number): number;
+    private refill;
+}
+/**
+ * Test-only: wipe all tenant buckets. Used by unit tests to isolate cases.
+ */
+export declare function __resetRateLimiter(): void;
+export declare const PUBLISH_TOOL_NAMES: Set<string>;
+/**
+ * Check rate limits and consume tokens.
+ * Peek-then-consume: check all relevant buckets before consuming any.
+ *
+ * @param toolName    Tool being invoked (used to detect publish cost)
+ * @param tenantKey   Per-tenant key (typically the Facebook Page id). If
+ *                    omitted, uses a shared default bucket — fine for
+ *                    single-tenant / env-based usage.
+ * @param overrideCost Cost to consume (default 1)
+ */
+export declare function checkRateLimit(toolName?: string, tenantKey?: string, overrideCost?: number): {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterMs: number;
+};
+/**
+ * Pre-flight rate limit check. Waits up to 60s if bucket is near-empty.
+ * Returns DEFER guidance if wait would exceed 60s.
+ */
+export declare function waitForRateLimit(toolName?: string, tenantKey?: string, overrideCost?: number): Promise<{
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterMs: number;
+}>;
+/**
+ * Retry a function with exponential backoff on HTTP 429 errors.
+ * Also parses Retry-After header when available.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>): Promise<T>;
+export declare function sleep(ms: number): Promise<void>;