instagram-mcp-server 1.6.6

package/src/client.ts

@@ -0,0 +1,204 @@
+/**
+ * Instagram Graph API client.
+ *
+ * Raw fetch wrapper against https://graph.instagram.com/v22.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;
+  accountId: string;
+}
+
+interface CachedClient {
+  client: InstagramClient;
+  createdAt: number;
+}
+
+const clientCache = new Map<string, CachedClient>();
+
+function credentialHash(creds: Credentials): string {
+  const raw = `${creds.accessToken}:${creds.accountId}`;
+  return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+
+/**
+ * Get or create a cached Instagram client.
+ */
+export function createClient(creds: Credentials): InstagramClient {
+  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 InstagramClient(creds);
+  clientCache.set(key, { client, createdAt: now });
+  return client;
+}
+
+/**
+ * Graph API error format from Facebook/Instagram.
+ */
+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 InstagramApiError 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 = "InstagramApiError";
+    this.status = status;
+    this.code = apiError.code;
+    this.errorSubcode = apiError.error_subcode;
+    this.errorType = apiError.type;
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class InstagramClient {
+  readonly accessToken: string;
+  readonly accountId: string;
+
+  constructor(creds: Credentials) {
+    this.accessToken = creds.accessToken;
+    this.accountId = creds.accountId;
+  }
+
+  /**
+   * 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 InstagramApiError(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 InstagramApiError(res.status, body.error, retryAfter);
+      }
+
+      // Non-standard error response — wrap in a generic error
+      throw new InstagramApiError(
+        res.status,
+        {
+          message: `HTTP ${res.status}: ${JSON.stringify(body)}`,
+          type: "UnknownError",
+          code: res.status,
+        },
+        retryAfter,
+      );
+    }
+
+    return body as T;
+  }
+}

package/src/errors.test.ts

@@ -0,0 +1,299 @@
+/**
+ * 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 Instagram 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 { InstagramApiError } from "./client.js";
+
+describe("extractApiDetail", () => {
+  it("returns undefined for non-InstagramApiError values", () => {
+    expect(extractApiDetail(new Error("boom"))).toBeUndefined();
+    expect(extractApiDetail("string error")).toBeUndefined();
+    expect(extractApiDetail(null)).toBeUndefined();
+    expect(extractApiDetail(undefined)).toBeUndefined();
+  });
+
+  it("formats InstagramApiError without subcode", () => {
+    const err = new InstagramApiError(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 InstagramApiError with subcode", () => {
+    const err = new InstagramApiError(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(
+      "ig_get_account_insights",
+      undefined,
+      undefined,
+      "getaddrinfo ENOTFOUND graph.facebook.com",
+    );
+    expect(r).toMatch(/^DNS_FAILURE:/);
+  });
+
+  it("timeout → TIMEOUT", () => {
+    expect(
+      suggestAction(
+        "ig_get_comments",
+        undefined,
+        undefined,
+        "The operation was aborted due to timeout",
+      ),
+    ).toMatch(/^TIMEOUT:/);
+  });
+
+  it("ECONNREFUSED → CONNECTION_FAILED", () => {
+    expect(
+      suggestAction(
+        "ig_get_comments",
+        undefined,
+        undefined,
+        "connect ECONNREFUSED 31.13.84.4:443",
+      ),
+    ).toMatch(/^CONNECTION_FAILED:/);
+  });
+
+  it("fetch failed → NETWORK_ERROR", () => {
+    expect(
+      suggestAction("ig_get_comments", undefined, undefined, "fetch failed"),
+    ).toMatch(/^NETWORK_ERROR:/);
+  });
+
+  it("unknown network error → undefined", () => {
+    expect(
+      suggestAction("ig_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(
+      "ig_get_account_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("ig_get_stories_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(
+      "ig_publish_photo",
+      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(
+        "ig_publish_carousel",
+        400,
+        "Some error text (subcode: 2207052)",
+      ),
+    ).toMatch(/^INVALID_MEDIA:/);
+  });
+
+  it("subcode 2207027 → INVALID_MEDIA", () => {
+    expect(
+      suggestAction(
+        "ig_publish_photo",
+        400,
+        "Media ID is not available (subcode: 2207027)",
+      ),
+    ).toMatch(/^INVALID_MEDIA:/);
+  });
+
+  it("'invalid media URL' → INVALID_MEDIA", () => {
+    expect(
+      suggestAction("ig_publish_photo", 400, "Invalid media URL provided"),
+    ).toMatch(/^INVALID_MEDIA:/);
+  });
+});
+
+describe("suggestAction — other 400 branches", () => {
+  it("caption mention → CAPTION_TOO_LONG", () => {
+    expect(
+      suggestAction("ig_publish_photo", 400, "Caption is too long"),
+    ).toMatch(/^CAPTION_TOO_LONG:/);
+  });
+
+  it("'too long' → CAPTION_TOO_LONG", () => {
+    expect(suggestAction("ig_publish_photo", 400, "Value too long")).toMatch(
+      /^CAPTION_TOO_LONG:/,
+    );
+  });
+
+  it("carousel children error → INVALID_CAROUSEL", () => {
+    expect(
+      suggestAction(
+        "ig_publish_carousel",
+        400,
+        "Carousel children must be between 2 and 10",
+      ),
+    ).toMatch(/^INVALID_CAROUSEL:/);
+  });
+
+  it("hashtag error → INVALID_HASHTAG", () => {
+    expect(
+      suggestAction("ig_get_hashtag_search", 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("ig_delete_comment", 404, "not found")).toMatch(
+      /^COMMENT_NOT_FOUND:/,
+    );
+  });
+
+  it("404 insight tool → MEDIA_NOT_FOUND", () => {
+    expect(suggestAction("ig_get_post_insights", 404, "not found")).toMatch(
+      /^MEDIA_NOT_FOUND:/,
+    );
+  });
+
+  it("404 story tool → STORY_NOT_FOUND", () => {
+    // Tool name must include 'story' AND NOT 'insight' / 'post' / 'comment'
+    // (those are checked first). ig_story_publish is a hypothetical example.
+    expect(suggestAction("ig_story_fetch", 404, "not found")).toMatch(
+      /^STORY_NOT_FOUND:/,
+    );
+  });
+
+  // Real-world: ig_get_stories_insights contains both 'story' and 'insight',
+  // and 'insight' is checked first → MEDIA_NOT_FOUND (documented quirk).
+  it("404 ig_get_stories_insights → MEDIA_NOT_FOUND (insight wins)", () => {
+    expect(suggestAction("ig_get_stories_insights", 404, "not found")).toMatch(
+      /^MEDIA_NOT_FOUND:/,
+    );
+  });
+
+  it("404 generic tool → NOT_FOUND", () => {
+    expect(suggestAction("ig_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/src/errors.ts

@@ -0,0 +1,108 @@
+/**
+ * Error mapping helpers — pure functions only, no IO.
+ *
+ * extractApiDetail() formats an InstagramApiError 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 Instagram Graph API.
+ */
+
+import { InstagramApiError } from "./client.js";
+
+export function extractApiDetail(e: unknown): string | undefined {
+  if (e instanceof InstagramApiError) {
+    const sub = e.errorSubcode ? ` (subcode: ${e.errorSubcode})` : "";
+    return `${e.errorType}: ${e.message}${sub}`;
+  }
+  return undefined;
+}
+
+export function suggestAction(
+  toolName: string,
+  statusCode: number | undefined,
+  detail: string | undefined,
+  errorMsg?: string,
+): string | undefined {
+  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 Instagram timed out. Check your connection and retry.";
+    if (d.includes("econnrefused") || d.includes("econnreset"))
+      return "CONNECTION_FAILED: Cannot connect to Instagram. 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 an Instagram Business or Creator account linked to a Facebook Page.";
+      return "FORBIDDEN: Instagram 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: Instagram 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: Instagram is having issues. Wait 30s and retry once.";
+
+    default:
+      return undefined;
+  }
+}

package/src/first-comment.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Regression tests for the #1995 first-comment partial-success contract (#1931).
+ *
+ * The whole point of first-comment publishing is "no lying success": if the
+ * media publishes but the follow-up comment fails, the handler must surface a
+ * partial failure — never a clean success. postFirstComment is the isolated
+ * step the three publish handlers (photo/carousel/reel) all delegate to, so a
+ * test here guards every IG publish path against the silent-swallow regression.
+ */
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { postFirstComment } from "./index.js";
+import type { InstagramClient } from "./client.js";
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+/** Drive the helper to completion, flushing its 3-5s natural-appearance delay. */
+async function runWithTimers<T>(p: Promise<T>): Promise<T> {
+  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 } as unknown as InstagramClient;
+
+    const result = await runWithTimers(
+      postFirstComment(client, "media-1", "Great thread →"),
+    );
+
+    expect(result).toEqual({ id: "comment-1" });
+    expect(post).toHaveBeenCalledWith("/media-1/comments", {
+      message: "Great thread →",
+    });
+  });
+
+  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 } as unknown as InstagramClient;
+
+    const result = await runWithTimers(
+      postFirstComment(client, "media-1", "hi"),
+    );
+
+    // The media is already live; the failure must surface, never be swallowed.
+    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 } as unknown as InstagramClient;
+
+    expect(await postFirstComment(client, "media-1", "   ")).toEqual({});
+    expect(await postFirstComment(client, "media-1", undefined)).toEqual({});
+    expect(post).not.toHaveBeenCalled();
+  });
+
+  it("caps the comment at Instagram's 2200-char limit", async () => {
+    vi.useFakeTimers();
+    const post = vi.fn().mockResolvedValue({ id: "c" });
+    const client = { post } as unknown as InstagramClient;
+
+    await runWithTimers(postFirstComment(client, "m", "y".repeat(4000)));
+
+    const sent = post.mock.calls[0][1] as { message: string };
+    expect(sent.message).toHaveLength(2200);
+  });
+});