facebook-mcp-server 1.6.6

package/dist/errors.js

@@ -0,0 +1,87 @@
+/**
+ * Error mapping helpers — pure functions only, no IO.
+ *
+ * extractApiDetail() formats an FacebookApiError for human/agent consumption.
+ * suggestAction() maps (statusCode, detail) → an AGENT_ACTION hint string.
+ *
+ * These functions are pure and heavily unit-tested in errors.test.ts.
+ * Every hint string is a regression guard for a real bug discovered during
+ * live testing against the Facebook Graph API.
+ */
+import { FacebookApiError } from "./client.js";
+export function extractApiDetail(e) {
+    if (e instanceof FacebookApiError) {
+        const sub = e.errorSubcode ? ` (subcode: ${e.errorSubcode})` : "";
+        return `${e.errorType}: ${e.message}${sub}`;
+    }
+    return undefined;
+}
+export function suggestAction(toolName, statusCode, detail, errorMsg) {
+    const d = (detail || errorMsg || "").toLowerCase();
+    // Network-level errors
+    if (statusCode === undefined) {
+        if (d.includes("enotfound") || d.includes("dns"))
+            return "DNS_FAILURE: Cannot resolve graph.facebook.com. Check your internet connection.";
+        if (d.includes("timeout") || d.includes("abort"))
+            return "TIMEOUT: Request to Facebook timed out. Check your connection and retry.";
+        if (d.includes("econnrefused") || d.includes("econnreset"))
+            return "CONNECTION_FAILED: Cannot connect to Facebook. The service may be down. Retry in 30s.";
+        if (d.includes("fetch failed"))
+            return "NETWORK_ERROR: Network request failed. Check your internet connection and retry.";
+        return undefined;
+    }
+    // Token-invalidity errors can come back as 400 with an OAuthException.
+    // Match only explicit token-failure phrasing — NOT the bare word "oauth",
+    // because OAuthException is the generic error type for all Graph API failures.
+    if (d.includes("invalid oauth access token") ||
+        d.includes("access token has expired") ||
+        d.includes("session has expired") ||
+        d.includes("access token is invalid") ||
+        d.includes("cannot parse access token") ||
+        d.includes("malformed access token")) {
+        return "AUTH_FAILED: Access token is invalid or expired. Generate a new long-lived token via the Facebook Developer Console.";
+    }
+    switch (statusCode) {
+        case 400:
+            if ((d.includes("invalid") && d.includes("media")) ||
+                d.includes("photo or video can be accepted") ||
+                d.includes("2207052") ||
+                d.includes("2207027"))
+                return "INVALID_MEDIA: The media URL is invalid or inaccessible. Ensure the URL is publicly accessible, returns image/jpeg or image/png content-type, is not behind a redirect, and is not rate-limited by the host.";
+            if (d.includes("caption") || d.includes("too long"))
+                return "CAPTION_TOO_LONG: Caption exceeds 2200 characters. Shorten it and retry.";
+            if (d.includes("children") || d.includes("carousel"))
+                return "INVALID_CAROUSEL: Carousel requires 2-10 items. Check item count and media URLs.";
+            if (d.includes("hashtag"))
+                return "INVALID_HASHTAG: Hashtag search is limited to 30 unique hashtags per 7-day rolling window.";
+            return "INVALID_REQUEST: Check the error message and fix the input parameters.";
+        case 401:
+            return "AUTH_FAILED: Access token is invalid or expired. Generate a new long-lived token via the Facebook Developer Console.";
+        case 403:
+            if (d.includes("permission"))
+                return "PERMISSION_DENIED: Your token lacks the required permission. Check token permissions in Facebook Developer Console.";
+            if (d.includes("not approved") || d.includes("app not"))
+                return "APP_NOT_APPROVED: Your Facebook app needs approval for this permission. Submit for review in the App Dashboard.";
+            if (d.includes("business"))
+                return "BUSINESS_ACCOUNT_REQUIRED: This feature requires a Facebook Page linked to a Business account.";
+            return "FORBIDDEN: Facebook rejected this action. Check the error message for details.";
+        case 404: {
+            const t = toolName.toLowerCase();
+            if (t.includes("comment"))
+                return "COMMENT_NOT_FOUND: This comment may have been deleted. Skip it and move on.";
+            if (t.includes("post") || t.includes("insight"))
+                return "MEDIA_NOT_FOUND: This post may have been deleted or the ID is invalid. Skip it.";
+            if (t.includes("story"))
+                return "STORY_NOT_FOUND: Stories expire after 24 hours. This story is no longer available.";
+            return "NOT_FOUND: The requested resource does not exist. It may have been deleted.";
+        }
+        case 429:
+            return "RATE_LIMITED: Facebook rate limit hit after automatic retries. Wait 60s and retry, or switch to a different task.";
+        case 500:
+        case 502:
+        case 503:
+            return "SERVER_ERROR: Facebook is having issues. Wait 30s and retry once.";
+        default:
+            return undefined;
+    }
+}

package/dist/errors.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unit tests for error mapping helpers.
+ *
+ * Every test case here is a regression guard for a specific bug discovered
+ * during live testing against the real Facebook Graph API. Changing any of
+ * the asserted strings without updating the tool's error-handling docs is
+ * a contract break for agents consuming these responses.
+ */
+export {};

package/dist/errors.test.js

@@ -0,0 +1,162 @@
+/**
+ * Unit tests for error mapping helpers.
+ *
+ * Every test case here is a regression guard for a specific bug discovered
+ * during live testing against the real Facebook Graph API. Changing any of
+ * the asserted strings without updating the tool's error-handling docs is
+ * a contract break for agents consuming these responses.
+ */
+import { describe, it, expect } from "vitest";
+import { extractApiDetail, suggestAction } from "./errors.js";
+import { FacebookApiError } from "./client.js";
+describe("extractApiDetail", () => {
+    it("returns undefined for non-FacebookApiError values", () => {
+        expect(extractApiDetail(new Error("boom"))).toBeUndefined();
+        expect(extractApiDetail("string error")).toBeUndefined();
+        expect(extractApiDetail(null)).toBeUndefined();
+        expect(extractApiDetail(undefined)).toBeUndefined();
+    });
+    it("formats FacebookApiError without subcode", () => {
+        const err = new FacebookApiError(400, {
+            message: "Invalid OAuth access token - Cannot parse access token",
+            type: "OAuthException",
+            code: 190,
+        });
+        expect(extractApiDetail(err)).toBe("OAuthException: Invalid OAuth access token - Cannot parse access token");
+    });
+    it("formats FacebookApiError with subcode", () => {
+        const err = new FacebookApiError(400, {
+            message: "Media ID is not available",
+            type: "OAuthException",
+            code: 100,
+            error_subcode: 2207027,
+        });
+        expect(extractApiDetail(err)).toBe("OAuthException: Media ID is not available (subcode: 2207027)");
+    });
+});
+describe("suggestAction — network errors (no statusCode)", () => {
+    it("ENOTFOUND → DNS_FAILURE", () => {
+        const r = suggestAction("fb_get_page_insights", undefined, undefined, "getaddrinfo ENOTFOUND graph.facebook.com");
+        expect(r).toMatch(/^DNS_FAILURE:/);
+    });
+    it("timeout → TIMEOUT", () => {
+        expect(suggestAction("fb_get_comments", undefined, undefined, "The operation was aborted due to timeout")).toMatch(/^TIMEOUT:/);
+    });
+    it("ECONNREFUSED → CONNECTION_FAILED", () => {
+        expect(suggestAction("fb_get_comments", undefined, undefined, "connect ECONNREFUSED 31.13.84.4:443")).toMatch(/^CONNECTION_FAILED:/);
+    });
+    it("fetch failed → NETWORK_ERROR", () => {
+        expect(suggestAction("fb_get_comments", undefined, undefined, "fetch failed")).toMatch(/^NETWORK_ERROR:/);
+    });
+    it("unknown network error → undefined", () => {
+        expect(suggestAction("fb_get_comments", undefined, undefined, "something weird")).toBeUndefined();
+    });
+});
+describe("suggestAction — token errors (high priority for Bug #6)", () => {
+    it("'Invalid OAuth access token' → AUTH_FAILED", () => {
+        const r = suggestAction("fb_get_page_insights", 400, "OAuthException: Invalid OAuth access token - Cannot parse access token");
+        expect(r).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'Cannot parse access token' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "Cannot parse access token")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'access token has expired' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "Error validating access token: access token has expired")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'session has expired' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "The session has expired on Tuesday")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'malformed access token' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "Malformed access token")).toMatch(/^AUTH_FAILED:/);
+    });
+    // REGRESSION: generic OAuthException for metric errors must NOT be AUTH_FAILED
+    it("metric error mentioning OAuthException is NOT AUTH_FAILED", () => {
+        const metricErr = "OAuthException: (#100) metric[2] must be one of the following values: reach, follower_count, profile_views";
+        const r = suggestAction("fb_get_page_insights", 400, metricErr);
+        expect(r).not.toMatch(/^AUTH_FAILED:/);
+        expect(r).toMatch(/^INVALID_REQUEST:/);
+    });
+});
+describe("suggestAction — 400 media errors (regression guard for Bug #9)", () => {
+    it("'photo or video can be accepted' → INVALID_MEDIA", () => {
+        const r = suggestAction("fb_create_post", 400, "OAuthException: Only photo or video can be accepted as media type. (subcode: 2207052)");
+        expect(r).toMatch(/^INVALID_MEDIA:/);
+    });
+    it("subcode 2207052 → INVALID_MEDIA", () => {
+        expect(suggestAction("fb_create_post", 400, "Some error text (subcode: 2207052)")).toMatch(/^INVALID_MEDIA:/);
+    });
+    it("subcode 2207027 → INVALID_MEDIA", () => {
+        expect(suggestAction("fb_create_post", 400, "Media ID is not available (subcode: 2207027)")).toMatch(/^INVALID_MEDIA:/);
+    });
+    it("'invalid media URL' → INVALID_MEDIA", () => {
+        expect(suggestAction("fb_create_post", 400, "Invalid media URL provided")).toMatch(/^INVALID_MEDIA:/);
+    });
+});
+describe("suggestAction — other 400 branches", () => {
+    it("caption mention → CAPTION_TOO_LONG", () => {
+        expect(suggestAction("fb_create_post", 400, "Caption is too long")).toMatch(/^CAPTION_TOO_LONG:/);
+    });
+    it("'too long' → CAPTION_TOO_LONG", () => {
+        expect(suggestAction("fb_create_post", 400, "Value too long")).toMatch(/^CAPTION_TOO_LONG:/);
+    });
+    it("carousel children error → INVALID_CAROUSEL", () => {
+        expect(suggestAction("fb_create_post", 400, "Carousel children must be between 2 and 10")).toMatch(/^INVALID_CAROUSEL:/);
+    });
+    it("hashtag error → INVALID_HASHTAG", () => {
+        expect(suggestAction("fb_get_page_feed", 400, "Hashtag quota exceeded")).toMatch(/^INVALID_HASHTAG:/);
+    });
+    it("unmatched 400 → INVALID_REQUEST", () => {
+        expect(suggestAction("any", 400, "Unknown bad request reason")).toMatch(/^INVALID_REQUEST:/);
+    });
+});
+describe("suggestAction — 401/403/404", () => {
+    it("401 → AUTH_FAILED", () => {
+        expect(suggestAction("any", 401, "anything")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("403 with 'permission' → PERMISSION_DENIED", () => {
+        expect(suggestAction("any", 403, "You lack the required permission")).toMatch(/^PERMISSION_DENIED:/);
+    });
+    it("403 with 'not approved' → APP_NOT_APPROVED", () => {
+        expect(suggestAction("any", 403, "This feature is not approved for your app")).toMatch(/^APP_NOT_APPROVED:/);
+    });
+    it("403 with 'business' → BUSINESS_ACCOUNT_REQUIRED", () => {
+        expect(suggestAction("any", 403, "A business account is required")).toMatch(/^BUSINESS_ACCOUNT_REQUIRED:/);
+    });
+    it("403 unmatched → FORBIDDEN", () => {
+        expect(suggestAction("any", 403, "generic denial")).toMatch(/^FORBIDDEN:/);
+    });
+    it("404 comment tool → COMMENT_NOT_FOUND", () => {
+        expect(suggestAction("fb_reply_comment", 404, "not found")).toMatch(/^COMMENT_NOT_FOUND:/);
+    });
+    it("404 post tool (delete) → MEDIA_NOT_FOUND", () => {
+        expect(suggestAction("fb_delete_post", 404, "not found")).toMatch(/^MEDIA_NOT_FOUND:/);
+    });
+    it("404 insight tool → MEDIA_NOT_FOUND", () => {
+        expect(suggestAction("fb_get_post_insights", 404, "not found")).toMatch(/^MEDIA_NOT_FOUND:/);
+    });
+    // Story branch is inherited from the shared errors.ts but Facebook has no
+    // story tools in scope — kept as a future-proofing regression guard.
+    it("404 story tool → STORY_NOT_FOUND (future-proofing)", () => {
+        expect(suggestAction("some_story_tool", 404, "not found")).toMatch(/^STORY_NOT_FOUND:/);
+    });
+    it("404 generic tool → NOT_FOUND", () => {
+        expect(suggestAction("fb_misc_tool", 404, "not found")).toMatch(/^NOT_FOUND:/);
+    });
+});
+describe("suggestAction — 429 and 5xx", () => {
+    it("429 → RATE_LIMITED", () => {
+        expect(suggestAction("any", 429, "rate limited")).toMatch(/^RATE_LIMITED:/);
+    });
+    it("500 → SERVER_ERROR", () => {
+        expect(suggestAction("any", 500, "internal server error")).toMatch(/^SERVER_ERROR:/);
+    });
+    it("502 → SERVER_ERROR", () => {
+        expect(suggestAction("any", 502, "bad gateway")).toMatch(/^SERVER_ERROR:/);
+    });
+    it("503 → SERVER_ERROR", () => {
+        expect(suggestAction("any", 503, "service unavailable")).toMatch(/^SERVER_ERROR:/);
+    });
+    it("unknown status → undefined", () => {
+        expect(suggestAction("any", 418, "I'm a teapot")).toBeUndefined();
+    });
+});

package/dist/first-comment.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Regression tests for the #1995 first-comment partial-success contract (#1931).
+ *
+ * Facebook is the highest-value first-comment platform (FB suppresses
+ * link-in-body reach, so the link belongs in the first comment). If the post
+ * publishes but the comment fails, fb_create_post must report a partial failure
+ * carrying the live post id — never a clean success. postFirstComment is the
+ * isolated step the handler delegates to.
+ */
+export {};

package/dist/first-comment.test.js

@@ -0,0 +1,54 @@
+/**
+ * Regression tests for the #1995 first-comment partial-success contract (#1931).
+ *
+ * Facebook is the highest-value first-comment platform (FB suppresses
+ * link-in-body reach, so the link belongs in the first comment). If the post
+ * publishes but the comment fails, fb_create_post must report a partial failure
+ * carrying the live post id — never a clean success. postFirstComment is the
+ * isolated step the handler delegates to.
+ */
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { postFirstComment } from "./index.js";
+afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+});
+async function runWithTimers(p) {
+    await vi.runAllTimersAsync();
+    return p;
+}
+describe("postFirstComment — partial-success contract", () => {
+    it("returns the comment id when the comment posts", async () => {
+        vi.useFakeTimers();
+        const post = vi.fn().mockResolvedValue({ id: "comment-1" });
+        const client = { post };
+        const result = await runWithTimers(postFirstComment(client, "post-1", "Link in the comments 👇"));
+        expect(result).toEqual({ id: "comment-1" });
+        expect(post).toHaveBeenCalledWith("/post-1/comments", {
+            message: "Link in the comments 👇",
+        });
+    });
+    it("returns { error } (NOT a clean success) when the comment client throws", async () => {
+        vi.useFakeTimers();
+        const post = vi.fn().mockRejectedValue(new Error("graph boom"));
+        const client = { post };
+        const result = await runWithTimers(postFirstComment(client, "post-1", "hi"));
+        expect(result.error).toContain("graph boom");
+        expect(result.id).toBeUndefined();
+    });
+    it("is a no-op (no API call) when firstComment is blank", async () => {
+        const post = vi.fn();
+        const client = { post };
+        expect(await postFirstComment(client, "post-1", "  ")).toEqual({});
+        expect(await postFirstComment(client, "post-1", undefined)).toEqual({});
+        expect(post).not.toHaveBeenCalled();
+    });
+    it("caps the comment at Facebook's 2000-char limit", async () => {
+        vi.useFakeTimers();
+        const post = vi.fn().mockResolvedValue({ id: "c" });
+        const client = { post };
+        await runWithTimers(postFirstComment(client, "p", "y".repeat(4000)));
+        const sent = post.mock.calls[0][1];
+        expect(sent.message).toHaveLength(2000);
+    });
+});

package/dist/handlers.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Integration tests for tool handler bodies.
+ *
+ * Closes the coverage gap identified in the test audit: the 7 tool handlers
+ * in index.ts (their metric lists, field selectors, URL construction, response
+ * mapping, and sanitization wiring) were previously only covered by live
+ * manual testing. These tests reach the registered handler functions via the
+ * MCP server's internal registry (`_registeredTools[name].handler`) and
+ * invoke them directly with stubbed fetch.
+ *
+ * Each tool gets at least one happy-path test (correct URL + fields + response
+ * shape) and one error-path test (API error → structured error with action).
+ *
+ * Note: reaching into `_registeredTools` relies on an SDK internal. This is
+ * acceptable for tests because (a) SDK version is pinned, (b) a breaking
+ * change would fail immediately and loudly, and (c) it avoids a larger
+ * refactor of index.ts just for test plumbing.
+ */
+export {};