facebook-mcp-server 1.6.6

package/src/create-post.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Unit tests for buildCreatePostRequest — the pure validation + routing
+ * helper backing fb_create_post.
+ *
+ * Each test is a regression guard for a specific branch of the tool's
+ * pre-flight logic. This closes the coverage gap identified in the Facebook
+ * MCP test audit: the 4 most FB-specific code paths (attachment routing,
+ * mutual-exclusion, caption length, empty-input) were previously only
+ * covered by live manual testing.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  buildCreatePostRequest,
+  FB_MESSAGE_MAX_LENGTH,
+} from "./create-post.js";
+
+describe("buildCreatePostRequest — validation", () => {
+  it("rejects empty input (no message, no attachment)", () => {
+    const r = buildCreatePostRequest({});
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toBe("Invalid input");
+      expect(r.message).toMatch(
+        /at least a message, link, imageUrl, or videoUrl/,
+      );
+    }
+  });
+
+  it("rejects when two attachment types are provided (link + imageUrl)", () => {
+    const r = buildCreatePostRequest({
+      message: "x",
+      link: "https://a.com",
+      imageUrl: "https://example.com/x.jpg",
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.message).toMatch(/Exactly one of link, imageUrl, or videoUrl/);
+      expect(r.action).toMatch(/^FIX_INPUT:/);
+    }
+  });
+
+  it("rejects when all three attachment types are provided", () => {
+    const r = buildCreatePostRequest({
+      link: "https://a.com",
+      imageUrl: "https://example.com/x.jpg",
+      videoUrl: "https://example.com/x.mp4",
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.action).toMatch(/^FIX_INPUT:/);
+    }
+  });
+
+  it("rejects message longer than Facebook's 63206 char limit", () => {
+    const r = buildCreatePostRequest({ message: "x".repeat(63207) });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.message).toMatch(/63207 chars, Facebook max is 63206/);
+      expect(r.action).toMatch(/^CAPTION_TOO_LONG:/);
+    }
+  });
+
+  it("accepts exactly 63206 chars (boundary condition)", () => {
+    const r = buildCreatePostRequest({
+      message: "x".repeat(FB_MESSAGE_MAX_LENGTH),
+    });
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe("buildCreatePostRequest — routing", () => {
+  it("routes text-only post to /{pageId}/feed with message", () => {
+    const r = buildCreatePostRequest({ message: "hello world" });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.type).toBe("text");
+      expect(r.endpoint("548545275018321")).toBe("/548545275018321/feed");
+      expect(r.body).toEqual({ message: "hello world" });
+    }
+  });
+
+  it("routes link post to /feed with link field", () => {
+    const r = buildCreatePostRequest({
+      message: "check this out",
+      link: "https://www.luminarylane.app",
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.type).toBe("link");
+      expect(r.endpoint("548545275018321")).toBe("/548545275018321/feed");
+      expect(r.body).toEqual({
+        message: "check this out",
+        link: "https://www.luminarylane.app",
+      });
+    }
+  });
+
+  it("routes link post WITHOUT message to /feed (message optional for link)", () => {
+    const r = buildCreatePostRequest({ link: "https://www.luminarylane.app" });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.type).toBe("link");
+      expect(r.body).toEqual({ link: "https://www.luminarylane.app" });
+      expect(r.body.message).toBeUndefined();
+    }
+  });
+
+  it("routes photo post to /{pageId}/photos with url (not link)", () => {
+    const r = buildCreatePostRequest({
+      message: "a cat",
+      imageUrl: "https://example.com/cat.jpg",
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.type).toBe("photo");
+      expect(r.endpoint("548545275018321")).toBe("/548545275018321/photos");
+      expect(r.body).toEqual({
+        message: "a cat",
+        url: "https://example.com/cat.jpg",
+      });
+      // Ensure we did NOT accidentally set the `link` field
+      expect(r.body.link).toBeUndefined();
+    }
+  });
+
+  it("routes photo post without caption", () => {
+    const r = buildCreatePostRequest({
+      imageUrl: "https://example.com/cat.jpg",
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.type).toBe("photo");
+      expect(r.body.message).toBeUndefined();
+      expect(r.body.url).toBe("https://example.com/cat.jpg");
+    }
+  });
+
+  it("routes video post to /{pageId}/videos with file_url", () => {
+    const r = buildCreatePostRequest({
+      message: "watch",
+      videoUrl: "https://example.com/clip.mp4",
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.type).toBe("video");
+      expect(r.endpoint("548545275018321")).toBe("/548545275018321/videos");
+      expect(r.body).toEqual({
+        message: "watch",
+        file_url: "https://example.com/clip.mp4",
+      });
+    }
+  });
+
+  it("passes published=false through to body when provided", () => {
+    const r = buildCreatePostRequest({
+      message: "draft",
+      published: false,
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.body.published).toBe(false);
+    }
+  });
+
+  it("does NOT set published when undefined (defaults to FB's true)", () => {
+    const r = buildCreatePostRequest({ message: "live" });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.body.published).toBeUndefined();
+      expect("published" in r.body).toBe(false);
+    }
+  });
+
+  it("does NOT set published when explicitly true (let FB default stand)", () => {
+    const r = buildCreatePostRequest({
+      message: "live",
+      published: true,
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.body.published).toBeUndefined();
+    }
+  });
+});
+
+describe("buildCreatePostRequest — endpoint is a pure function of pageId", () => {
+  it("endpoint builder returns different paths for different page ids", () => {
+    const r = buildCreatePostRequest({ message: "x" });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.endpoint("111")).toBe("/111/feed");
+      expect(r.endpoint("222")).toBe("/222/feed");
+    }
+  });
+});

package/src/create-post.ts

@@ -0,0 +1,118 @@
+/**
+ * Pure helpers for fb_create_post — validation + request shaping.
+ *
+ * Extracted from index.ts so the attachment-routing logic can be unit-tested
+ * without spinning up the MCP server or mocking HTTP. Every branch here has
+ * a test in create-post.test.ts.
+ */
+
+export interface CreatePostArgs {
+  message?: string;
+  link?: string;
+  imageUrl?: string;
+  videoUrl?: string;
+  published?: boolean;
+}
+
+export interface CreatePostValidationError {
+  ok: false;
+  error: string;
+  message: string;
+  action?: string;
+}
+
+export interface CreatePostRequest {
+  ok: true;
+  endpoint: (pageId: string) => string;
+  body: Record<string, unknown>;
+  type: "text" | "link" | "photo" | "video";
+}
+
+export type CreatePostResult = CreatePostValidationError | CreatePostRequest;
+
+// Facebook Page post hard cap per Meta docs.
+export const FB_MESSAGE_MAX_LENGTH = 63206;
+
+/**
+ * Validate fb_create_post arguments and return either a structured error
+ * or the request recipe (endpoint + body + content type) the tool should
+ * send to the Graph API.
+ *
+ * This function is pure — it has no side effects, does no IO, and does not
+ * depend on env vars or a client instance. The caller is responsible for
+ * substituting the real page id into `endpoint(pageId)` and actually
+ * dispatching the request.
+ */
+export function buildCreatePostRequest(args: CreatePostArgs): CreatePostResult {
+  const hasLink = !!args.link;
+  const hasImage = !!args.imageUrl;
+  const hasVideo = !!args.videoUrl;
+  const attachmentCount = [hasLink, hasImage, hasVideo].filter(Boolean).length;
+
+  // Rule 1: at most one attachment type
+  if (attachmentCount > 1) {
+    return {
+      ok: false,
+      error: "Invalid input",
+      message:
+        "Exactly one of link, imageUrl, or videoUrl may be provided (or none for text-only).",
+      action:
+        "FIX_INPUT: Pick a single attachment type per post. For multi-photo posts, fall back to calling fb_create_post once per photo.",
+    };
+  }
+
+  // Rule 2: must have SOMETHING
+  if (!args.message && attachmentCount === 0) {
+    return {
+      ok: false,
+      error: "Invalid input",
+      message:
+        "A post must have at least a message, link, imageUrl, or videoUrl.",
+    };
+  }
+
+  // Rule 3: message length
+  if (args.message && args.message.length > FB_MESSAGE_MAX_LENGTH) {
+    return {
+      ok: false,
+      error: "Invalid input",
+      message: `Message is ${args.message.length} chars, Facebook max is ${FB_MESSAGE_MAX_LENGTH}.`,
+      action: "CAPTION_TOO_LONG: Shorten the message and retry.",
+    };
+  }
+
+  // Build the request body
+  const body: Record<string, unknown> = {};
+  if (args.message) body.message = args.message;
+  if (args.published === false) body.published = false;
+
+  // Route to the correct endpoint based on attachment type
+  if (hasImage) {
+    body.url = args.imageUrl;
+    return {
+      ok: true,
+      endpoint: (pageId: string) => `/${pageId}/photos`,
+      body,
+      type: "photo",
+    };
+  }
+
+  if (hasVideo) {
+    body.file_url = args.videoUrl;
+    return {
+      ok: true,
+      endpoint: (pageId: string) => `/${pageId}/videos`,
+      body,
+      type: "video",
+    };
+  }
+
+  // Text-only OR link attachment — both go through /feed
+  if (hasLink) body.link = args.link;
+  return {
+    ok: true,
+    endpoint: (pageId: string) => `/${pageId}/feed`,
+    body,
+    type: hasLink ? "link" : "text",
+  };
+}

package/src/errors.test.ts

@@ -0,0 +1,297 @@
+/**
+ * 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();
+  });
+});