facebook-mcp-server 1.6.6

package/dist/tools.test.js

@@ -0,0 +1,150 @@
+/**
+ * Integration tests for tool-handler helpers.
+ *
+ * Tests the building blocks every tool uses:
+ *   - safeHandler        — wraps every tool, formats errors
+ *   - resolveCredentials — env-vs-args precedence
+ *
+ * Full per-tool happy/error path tests would require spinning up the whole
+ * McpServer and sending JSON-RPC messages; instead we unit-test the shared
+ * helpers each tool depends on, which covers the surface area that actually
+ * breaks during Graph API changes.
+ *
+ * Note: Facebook publishes are synchronous (no container flow), so there is
+ * no pollContainerStatus helper to test.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { safeHandler, resolveCredentials } from "./index.js";
+import { FacebookApiError } from "./client.js";
+// Silence the console.error logging from safeHandler during tests
+beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => { });
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+});
+describe("resolveCredentials", () => {
+    // resolveCredentials reads DEFAULT_* constants captured at import time.
+    // We can't mutate them mid-test, but we can verify args-vs-env precedence
+    // by controlling args. The env-only path is covered by the "args missing"
+    // case returning whatever env happens to contain at import time.
+    it("returns null when both args and env are missing", () => {
+        // If env is set at import, this test is a no-op, so guard with a stub
+        if (!process.env.FACEBOOK_ACCESS_TOKEN || !process.env.FACEBOOK_PAGE_ID) {
+            expect(resolveCredentials({})).toBeNull();
+        }
+    });
+    it("returns provided args when both are supplied", () => {
+        const r = resolveCredentials({
+            accessToken: "tok_from_args",
+            pageId: "page_from_args",
+        });
+        expect(r).toEqual({
+            accessToken: "tok_from_args",
+            pageId: "page_from_args",
+        });
+    });
+    it("args-provided values take precedence over env defaults", () => {
+        // Even if env vars are set (from .env or shell), explicit args win
+        const r = resolveCredentials({
+            accessToken: "override_token",
+            pageId: "override_account",
+        });
+        expect(r?.accessToken).toBe("override_token");
+        expect(r?.pageId).toBe("override_account");
+    });
+    it("partial args fall through to env (or null if env missing)", () => {
+        // Only pageId supplied, accessToken must come from env
+        const r = resolveCredentials({ pageId: "page_only" });
+        if (process.env.FACEBOOK_ACCESS_TOKEN) {
+            expect(r?.pageId).toBe("page_only");
+            expect(r?.accessToken).toBe(process.env.FACEBOOK_ACCESS_TOKEN);
+        }
+        else {
+            expect(r).toBeNull();
+        }
+    });
+});
+describe("safeHandler", () => {
+    it("passes through successful handler results", async () => {
+        const handler = safeHandler("test_tool", async () => ({
+            content: [{ type: "text", text: "success" }],
+        }));
+        const result = await handler({});
+        expect(result).toEqual({
+            content: [{ type: "text", text: "success" }],
+        });
+        expect(result.isError).toBeFalsy();
+    });
+    it("catches thrown Error and returns errorResult", async () => {
+        const handler = safeHandler("test_tool", async () => {
+            throw new Error("something broke");
+        });
+        const result = (await handler({}));
+        expect(result.isError).toBe(true);
+        const body = JSON.parse(result.content[0].text);
+        expect(body.error).toBe("API error");
+        expect(body.message).toContain("test_tool failed");
+        expect(body.message).toContain("something broke");
+    });
+    it("catches FacebookApiError with auth-failure detail and sets action=AUTH_FAILED", async () => {
+        const handler = safeHandler("fb_get_page_insights", async () => {
+            throw new FacebookApiError(400, {
+                message: "Invalid OAuth access token - Cannot parse access token",
+                type: "OAuthException",
+                code: 190,
+            });
+        });
+        const result = (await handler({}));
+        const body = JSON.parse(result.content[0].text);
+        expect(body.statusCode).toBe(400);
+        expect(body.action).toMatch(/^AUTH_FAILED:/);
+    });
+    it("catches metric-error (Bug #6 regression): does NOT set AUTH_FAILED", async () => {
+        const handler = safeHandler("fb_get_page_insights", async () => {
+            throw new FacebookApiError(400, {
+                message: "(#100) metric[2] must be one of the following values: reach, follower_count",
+                type: "OAuthException",
+                code: 100,
+            });
+        });
+        const result = (await handler({}));
+        const body = JSON.parse(result.content[0].text);
+        expect(body.action).not.toMatch(/^AUTH_FAILED:/);
+        expect(body.action).toMatch(/^INVALID_REQUEST:/);
+    });
+    it("catches media-type error (Bug #9 regression): maps subcode 2207052 to INVALID_MEDIA", async () => {
+        const handler = safeHandler("fb_create_post", async () => {
+            throw new FacebookApiError(400, {
+                message: "Only photo or video can be accepted as media type.",
+                type: "OAuthException",
+                code: 100,
+                error_subcode: 2207052,
+            });
+        });
+        const result = (await handler({}));
+        const body = JSON.parse(result.content[0].text);
+        expect(body.action).toMatch(/^INVALID_MEDIA:/);
+    });
+    it("catches non-Error throws (string) gracefully", async () => {
+        const handler = safeHandler("test_tool", async () => {
+            throw "string error";
+        });
+        const result = (await handler({}));
+        expect(result.isError).toBe(true);
+        const body = JSON.parse(result.content[0].text);
+        expect(body.message).toContain("string error");
+    });
+});
+describe("safeHandler — rate-limit error (429 long wait)", () => {
+    it("maps 429 to RATE_LIMITED action string", async () => {
+        const handler = safeHandler("fb_get_page_insights", async () => {
+            throw new FacebookApiError(429, { message: "too fast", type: "OAuthException", code: 4 }, 300);
+        });
+        const result = (await handler({}));
+        const body = JSON.parse(result.content[0].text);
+        expect(body.statusCode).toBe(429);
+        expect(body.action).toMatch(/^RATE_LIMITED:/);
+    });
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "facebook-mcp-server",
+  "version": "1.6.6",
+  "description": "Standalone Facebook Pages MCP Server — SENSE + ACT tools for the Graph API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "facebook-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "overrides": {
+    "fast-uri": "^3.1.2"
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Unit tests for the Graph API HTTP client.
+ *
+ * Uses vi.stubGlobal("fetch", ...) to stub network calls. Every test resets
+ * the stub in afterEach to prevent leakage. The most important test here is
+ * the one asserting GRAPH_API_BASE points at graph.facebook.com — it's a
+ * regression guard ensuring the correct API base URL is used.
+ */
+
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import {
+  createClient,
+  FacebookApiError,
+  FacebookClient,
+  type Credentials,
+} from "./client.js";
+
+// Reach into the module's source to read the base URL constant.
+// We assert on actual request URLs below, which is the real contract.
+
+const creds: Credentials = {
+  accessToken: "EAALtest123",
+  pageId: "548545275018321",
+};
+
+type FetchMock = ReturnType<typeof vi.fn<typeof fetch>>;
+
+function mockFetchOk(body: unknown, init: ResponseInit = {}): FetchMock {
+  return vi.fn<typeof fetch>(
+    async () =>
+      new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+        ...init,
+      }),
+  );
+}
+
+function mockFetchError(
+  status: number,
+  body: unknown,
+  headers: Record<string, string> = {},
+): FetchMock {
+  return vi.fn<typeof fetch>(
+    async () =>
+      new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", ...headers },
+      }),
+  );
+}
+
+describe("FacebookClient — URL construction", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("GET builds URL against graph.facebook.com/v21.0 (REGRESSION: Bug #1)", async () => {
+    const fetchMock = mockFetchOk({ data: [] });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new FacebookClient(creds);
+    await client.get("/548545275018321/insights");
+
+    const [url] = fetchMock.mock.calls[0];
+    expect(url.toString()).toMatch(
+      /^https:\/\/graph\.facebook\.com\/v21\.0\/548545275018321\/insights\?/,
+    );
+  });
+
+  it("GET puts access_token and extra params in query string", async () => {
+    const fetchMock = mockFetchOk({ data: [] });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new FacebookClient(creds);
+    await client.get("/548545275018321/insights", {
+      metric: "reach,profile_views",
+      period: "day",
+    });
+
+    const url = fetchMock.mock.calls[0][0] as URL;
+    expect(url.searchParams.get("access_token")).toBe("EAALtest123");
+    expect(url.searchParams.get("metric")).toBe("reach,profile_views");
+    expect(url.searchParams.get("period")).toBe("day");
+  });
+
+  it("POST sends JSON body with correct Content-Type", async () => {
+    const fetchMock = mockFetchOk({ id: "new_media_id" });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new FacebookClient(creds);
+    await client.post("/548545275018321/media", {
+      image_url: "https://example.com/test.jpg",
+      caption: "hello",
+    });
+
+    const [, init] = fetchMock.mock.calls[0];
+    expect(init?.method).toBe("POST");
+    const headers = init?.headers as Record<string, string>;
+    expect(headers["Content-Type"]).toBe("application/json");
+    expect(JSON.parse(init?.body as string)).toEqual({
+      image_url: "https://example.com/test.jpg",
+      caption: "hello",
+    });
+  });
+
+  it("POST includes access_token in query even when body is present", async () => {
+    const fetchMock = mockFetchOk({ id: "x" });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new FacebookClient(creds);
+    await client.post("/548545275018321/media_publish", {
+      creation_id: "abc",
+    });
+
+    const url = fetchMock.mock.calls[0][0] as URL;
+    expect(url.searchParams.get("access_token")).toBe("EAALtest123");
+  });
+
+  it("DELETE sends DELETE method", async () => {
+    const fetchMock = mockFetchOk({ success: true });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new FacebookClient(creds);
+    await client.delete("/comment_id_123");
+
+    const [, init] = fetchMock.mock.calls[0];
+    expect(init?.method).toBe("DELETE");
+  });
+});
+
+describe("FacebookClient — error handling", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("parses Graph API error into FacebookApiError with status/code/subcode", async () => {
+    vi.stubGlobal(
+      "fetch",
+      mockFetchError(400, {
+        error: {
+          message: "Invalid OAuth access token",
+          type: "OAuthException",
+          code: 190,
+          error_subcode: 460,
+          fbtrace_id: "abc123",
+        },
+      }),
+    );
+
+    const client = new FacebookClient(creds);
+    await expect(client.get("/me")).rejects.toMatchObject({
+      name: "FacebookApiError",
+      status: 400,
+      code: 190,
+      errorSubcode: 460,
+      errorType: "OAuthException",
+      message: "Invalid OAuth access token",
+    });
+  });
+
+  it("wraps non-JSON HTML error responses in FacebookApiError", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response("<html>502 Bad Gateway</html>", {
+          status: 502,
+          headers: { "content-type": "text/html" },
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new FacebookClient(creds);
+    await expect(client.get("/me")).rejects.toMatchObject({
+      status: 502,
+      errorType: "ParseError",
+    });
+  });
+
+  it("passes through Retry-After header as retryAfter", async () => {
+    vi.stubGlobal(
+      "fetch",
+      mockFetchError(
+        429,
+        {
+          error: {
+            message: "Rate limited",
+            type: "OAuthException",
+            code: 4,
+          },
+        },
+        { "Retry-After": "90" },
+      ),
+    );
+
+    const client = new FacebookClient(creds);
+    try {
+      await client.get("/me");
+      expect.fail("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(FacebookApiError);
+      expect((e as FacebookApiError).retryAfter).toBe(90);
+    }
+  });
+
+  it("wraps non-GraphAPI JSON error shapes in UnknownError", async () => {
+    vi.stubGlobal("fetch", mockFetchError(500, { something: "weird" }));
+
+    const client = new FacebookClient(creds);
+    await expect(client.get("/me")).rejects.toMatchObject({
+      status: 500,
+      errorType: "UnknownError",
+    });
+  });
+});
+
+describe("createClient — caching", () => {
+  beforeEach(() => {
+    // Clear module state between tests by re-requiring isn't straightforward
+    // in ESM. Instead we rely on the fact that each cache key includes the
+    // full token+account pair — using unique tokens per test keeps them
+    // isolated.
+  });
+
+  it("returns the same instance for identical credentials", () => {
+    const a = createClient({ accessToken: "tok_same", pageId: "page_1" });
+    const b = createClient({ accessToken: "tok_same", pageId: "page_1" });
+    expect(a).toBe(b);
+  });
+
+  it("returns different instances for different tokens", () => {
+    const a = createClient({ accessToken: "tok_A_unique", pageId: "page_x" });
+    const b = createClient({ accessToken: "tok_B_unique", pageId: "page_x" });
+    expect(a).not.toBe(b);
+  });
+
+  it("returns different instances for different account IDs", () => {
+    const a = createClient({ accessToken: "tok_shared", pageId: "page_1_u" });
+    const b = createClient({ accessToken: "tok_shared", pageId: "page_2_u" });
+    expect(a).not.toBe(b);
+  });
+
+  it("returned clients carry the provided creds", () => {
+    const client = createClient({
+      accessToken: "tok_readback",
+      pageId: "page_readback",
+    });
+    expect(client.accessToken).toBe("tok_readback");
+    expect(client.pageId).toBe("page_readback");
+  });
+});
+
+describe("FacebookApiError — shape", () => {
+  it("carries all graph-api error fields", () => {
+    const err = new FacebookApiError(
+      400,
+      {
+        message: "boom",
+        type: "OAuthException",
+        code: 100,
+        error_subcode: 2207052,
+      },
+      30,
+    );
+
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("FacebookApiError");
+    expect(err.status).toBe(400);
+    expect(err.code).toBe(100);
+    expect(err.errorSubcode).toBe(2207052);
+    expect(err.errorType).toBe("OAuthException");
+    expect(err.retryAfter).toBe(30);
+    expect(err.message).toBe("boom");
+  });
+
+  it("allows undefined subcode and retryAfter", () => {
+    const err = new FacebookApiError(500, {
+      message: "server error",
+      type: "InternalError",
+      code: 1,
+    });
+    expect(err.errorSubcode).toBeUndefined();
+    expect(err.retryAfter).toBeUndefined();
+  });
+});

package/src/client.ts

@@ -0,0 +1,204 @@
+/**
+ * Facebook Graph API client.
+ *
+ * Raw fetch wrapper against https://graph.facebook.com/v21.0/.
+ * No SDK — keeps dependencies minimal (Occam's Razor).
+ * Client instances are cached by credential hash.
+ */
+
+import { createHash } from "node:crypto";
+
+const GRAPH_API_BASE = "https://graph.facebook.com/v21.0";
+const CLIENT_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+export interface Credentials {
+  accessToken: string;
+  pageId: string;
+}
+
+interface CachedClient {
+  client: FacebookClient;
+  createdAt: number;
+}
+
+const clientCache = new Map<string, CachedClient>();
+
+function credentialHash(creds: Credentials): string {
+  const raw = `${creds.accessToken}:${creds.pageId}`;
+  return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+
+/**
+ * Get or create a cached Facebook client.
+ */
+export function createClient(creds: Credentials): FacebookClient {
+  const key = credentialHash(creds);
+  const now = Date.now();
+
+  // Evict stale entries on every call
+  for (const [k, v] of clientCache) {
+    if (now - v.createdAt >= CLIENT_TTL_MS) {
+      clientCache.delete(k);
+    }
+  }
+
+  const cached = clientCache.get(key);
+  if (cached) return cached.client;
+
+  const client = new FacebookClient(creds);
+  clientCache.set(key, { client, createdAt: now });
+  return client;
+}
+
+/**
+ * Graph API error format from Facebook.
+ */
+export interface GraphApiError {
+  error: {
+    message: string;
+    type: string;
+    code: number;
+    error_subcode?: number;
+    fbtrace_id?: string;
+  };
+}
+
+function isGraphApiError(body: unknown): body is GraphApiError {
+  return (
+    typeof body === "object" &&
+    body !== null &&
+    "error" in body &&
+    typeof (body as GraphApiError).error === "object" &&
+    typeof (body as GraphApiError).error.message === "string"
+  );
+}
+
+/**
+ * Error thrown for Graph API failures. Carries structured error data
+ * for suggestAction() to inspect.
+ */
+export class FacebookApiError extends Error {
+  readonly status: number;
+  readonly code: number;
+  readonly errorSubcode?: number;
+  readonly errorType: string;
+  readonly retryAfter?: number;
+
+  constructor(
+    status: number,
+    apiError: GraphApiError["error"],
+    retryAfter?: number,
+  ) {
+    super(apiError.message);
+    this.name = "FacebookApiError";
+    this.status = status;
+    this.code = apiError.code;
+    this.errorSubcode = apiError.error_subcode;
+    this.errorType = apiError.type;
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class FacebookClient {
+  readonly accessToken: string;
+  readonly pageId: string;
+
+  constructor(creds: Credentials) {
+    this.accessToken = creds.accessToken;
+    this.pageId = creds.pageId;
+  }
+
+  /**
+   * Make a GET request to the Graph API.
+   */
+  async get<T = unknown>(
+    path: string,
+    params?: Record<string, string>,
+  ): Promise<T> {
+    const url = new URL(`${GRAPH_API_BASE}${path}`);
+    url.searchParams.set("access_token", this.accessToken);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+      }
+    }
+
+    const res = await fetch(url, {
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    return this.handleResponse<T>(res);
+  }
+
+  /**
+   * Make a POST request to the Graph API.
+   */
+  async post<T = unknown>(
+    path: string,
+    body?: Record<string, unknown>,
+  ): Promise<T> {
+    const url = new URL(`${GRAPH_API_BASE}${path}`);
+    url.searchParams.set("access_token", this.accessToken);
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    return this.handleResponse<T>(res);
+  }
+
+  /**
+   * Make a DELETE request to the Graph API.
+   */
+  async delete<T = unknown>(path: string): Promise<T> {
+    const url = new URL(`${GRAPH_API_BASE}${path}`);
+    url.searchParams.set("access_token", this.accessToken);
+
+    const res = await fetch(url, {
+      method: "DELETE",
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    return this.handleResponse<T>(res);
+  }
+
+  private async handleResponse<T>(res: Response): Promise<T> {
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      // Non-JSON response (HTML error page during outage, empty body, etc.)
+      throw new FacebookApiError(res.status, {
+        message: `HTTP ${res.status}: Response is not valid JSON (likely an outage or proxy error)`,
+        type: "ParseError",
+        code: res.status,
+      });
+    }
+
+    if (!res.ok) {
+      const retryAfterHeader = res.headers.get("Retry-After");
+      const seconds = retryAfterHeader ? parseInt(retryAfterHeader, 10) : NaN;
+      const retryAfter = !isNaN(seconds) ? seconds : undefined;
+
+      if (isGraphApiError(body)) {
+        throw new FacebookApiError(res.status, body.error, retryAfter);
+      }
+
+      // Non-standard error response — wrap in a generic error
+      throw new FacebookApiError(
+        res.status,
+        {
+          message: `HTTP ${res.status}: ${JSON.stringify(body)}`,
+          type: "UnknownError",
+          code: res.status,
+        },
+        retryAfter,
+      );
+    }
+
+    return body as T;
+  }
+}