instagram-mcp-server 1.6.6

package/src/lib/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Public surface for non-MCP consumers.
+ */
+export * from "./insights.js";
+export { InstagramClient, InstagramApiError, createClient } from "../client.js";
+export type { Credentials, GraphApiError } from "../client.js";

package/src/lib/insights.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure SENSE/insights functions for the Instagram Graph API.
+ *
+ * Same pattern as Facebook's `lib/insights.ts` — single source of truth
+ * for both the MCP server's tool handlers and the web app's
+ * `platform-insights.ts` orchestrator (importing via `@instagram-mcp/lib`).
+ */
+import type { InstagramClient } from "../client.js";
+import { withRetry } from "../rate-limiter.js";
+
+// ---------------------------------------------------------------------------
+// ig_get_account_insights
+// ---------------------------------------------------------------------------
+
+export interface AccountInsightsArgs {
+  /** "day" | "week" | "days_28". Default: "day". */
+  period?: string;
+  /** Unix timestamp (string), inclusive. */
+  since?: string;
+  /** Unix timestamp (string), inclusive. */
+  until?: string;
+}
+
+export interface AccountInsightsResult {
+  period: string;
+  insights: unknown[];
+}
+
+const ACCOUNT_INSIGHTS_METRICS = "reach,profile_views,accounts_engaged";
+
+export async function fetchAccountInsights(
+  client: InstagramClient,
+  args: AccountInsightsArgs = {},
+): Promise<AccountInsightsResult> {
+  const params: Record<string, string> = {
+    metric: ACCOUNT_INSIGHTS_METRICS,
+    metric_type: "total_value",
+    period: args.period || "day",
+  };
+  if (args.since) params.since = args.since;
+  if (args.until) params.until = args.until;
+
+  const response = await withRetry(() =>
+    client.get<{ data: unknown[] }>(`/${client.accountId}/insights`, params),
+  );
+
+  return { insights: response.data, period: params.period };
+}
+
+// ---------------------------------------------------------------------------
+// ig_get_post_insights
+// ---------------------------------------------------------------------------
+
+export interface PostInsightsArgs {
+  mediaId: string;
+}
+
+export interface PostInsightsResult {
+  mediaId: string;
+  insights: unknown[];
+}
+
+const POST_INSIGHTS_METRICS =
+  "reach,likes,comments,shares,saved,total_interactions,views";
+
+export async function fetchPostInsights(
+  client: InstagramClient,
+  args: PostInsightsArgs,
+): Promise<PostInsightsResult> {
+  if (!args.mediaId.trim()) throw new Error("mediaId cannot be empty");
+  const response = await withRetry(() =>
+    client.get<{ data: unknown[] }>(`/${args.mediaId}/insights`, {
+      metric: POST_INSIGHTS_METRICS,
+    }),
+  );
+  return { mediaId: args.mediaId, insights: response.data };
+}
+
+// ---------------------------------------------------------------------------
+// ig_get_audience_demographics
+// ---------------------------------------------------------------------------
+
+export type DemographicsMetric =
+  | "follower_demographics"
+  | "engaged_audience_demographics"
+  | "reached_audience_demographics";
+
+export type DemographicsBreakdown = "age" | "city" | "country" | "gender";
+
+export interface AudienceDemographicsArgs {
+  metric?: DemographicsMetric;
+  breakdown?: DemographicsBreakdown;
+}
+
+export interface AudienceDemographicsResult {
+  demographics: unknown[];
+}
+
+export async function fetchAudienceDemographics(
+  client: InstagramClient,
+  args: AudienceDemographicsArgs = {},
+): Promise<AudienceDemographicsResult> {
+  const metric = args.metric || "follower_demographics";
+  const breakdown = args.breakdown || "country";
+
+  const response = await withRetry(() =>
+    client.get<{ data: unknown[] }>(`/${client.accountId}/insights`, {
+      metric,
+      period: "lifetime",
+      metric_type: "total_value",
+      breakdown,
+    }),
+  );
+
+  return { demographics: response.data };
+}
+
+// ---------------------------------------------------------------------------
+// Recent media list — derived helper used by the web orchestrator to compute
+// per-post averages without making a separate ig_get_post_insights call per
+// media. NOT exposed as an MCP tool today (the MCP server only fetches by
+// mediaId), but we keep it here for parity with Facebook's fetchPageFeed.
+// ---------------------------------------------------------------------------
+
+export interface RecentMediaArgs {
+  /** Default 10, max 100. */
+  limit?: number;
+}
+
+export interface IgMedia {
+  id: string;
+  mediaType?: string;
+  permalink?: string;
+  likeCount?: number;
+  commentsCount?: number;
+  reach?: number;
+  totalInteractions?: number;
+}
+
+export async function fetchRecentMedia(
+  client: InstagramClient,
+  args: RecentMediaArgs = {},
+): Promise<{ media: IgMedia[] }> {
+  const limit = Math.max(1, Math.min(args.limit || 10, 100));
+  const response = await withRetry(() =>
+    client.get<{
+      data: Array<{
+        id: string;
+        media_type?: string;
+        permalink?: string;
+        like_count?: number;
+        comments_count?: number;
+        insights?: {
+          data?: Array<{ name: string; values?: Array<{ value: number }> }>;
+        };
+      }>;
+    }>(`/${client.accountId}/media`, {
+      fields:
+        "id,media_type,permalink,like_count,comments_count," +
+        "insights.metric(reach,total_interactions)",
+      limit: String(limit),
+    }),
+  );
+
+  const media: IgMedia[] = (response.data || []).map((m) => {
+    const metricMap: Record<string, number> = {};
+    for (const x of m.insights?.data ?? []) {
+      metricMap[x.name] = x.values?.[0]?.value ?? 0;
+    }
+    return {
+      id: m.id,
+      mediaType: m.media_type,
+      permalink: m.permalink,
+      likeCount: m.like_count,
+      commentsCount: m.comments_count,
+      reach: metricMap.reach,
+      totalInteractions: metricMap.total_interactions,
+    };
+  });
+
+  return { media };
+}

package/src/rate-limiter.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  TokenBucket,
+  checkRateLimit,
+  PUBLISH_TOOL_NAMES,
+  withRetry,
+  __resetRateLimiter,
+} from "./rate-limiter.js";
+
+// Every test starts with an empty tenant bucket map so state from prior
+// tests (especially "exhaust the bucket" cases) doesn't leak.
+beforeEach(() => {
+  __resetRateLimiter();
+});
+
+describe("TokenBucket", () => {
+  it("allows consumption when tokens are available", () => {
+    const bucket = new TokenBucket({ maxTokens: 10, refillRate: 0.01 });
+    expect(bucket.tryConsume(1)).toBe(true);
+  });
+
+  it("rejects consumption when empty", () => {
+    const bucket = new TokenBucket({ maxTokens: 2, refillRate: 0.0001 });
+    expect(bucket.tryConsume(1)).toBe(true);
+    expect(bucket.tryConsume(1)).toBe(true);
+    expect(bucket.tryConsume(1)).toBe(false);
+  });
+
+  it("reports 0 wait when tokens available", () => {
+    const bucket = new TokenBucket({ maxTokens: 10, refillRate: 0.01 });
+    expect(bucket.msUntilAvailable(1)).toBe(0);
+  });
+
+  it("reports positive wait when empty", () => {
+    const bucket = new TokenBucket({ maxTokens: 1, refillRate: 0.001 });
+    bucket.tryConsume(1);
+    expect(bucket.msUntilAvailable(1)).toBeGreaterThan(0);
+  });
+
+  it("handles multi-token costs", () => {
+    const bucket = new TokenBucket({ maxTokens: 5, refillRate: 0.01 });
+    expect(bucket.tryConsume(3)).toBe(true);
+    expect(bucket.tryConsume(3)).toBe(false);
+    expect(bucket.tryConsume(2)).toBe(true);
+  });
+});
+
+describe("checkRateLimit", () => {
+  it("allows reads under the limit", () => {
+    const result = checkRateLimit("ig_get_comments");
+    expect(result.allowed).toBe(true);
+  });
+
+  it("allows publish under the limit", () => {
+    const result = checkRateLimit("ig_publish_photo");
+    expect(result.allowed).toBe(true);
+  });
+});
+
+describe("PUBLISH_TOOL_NAMES", () => {
+  it("contains all publish tools", () => {
+    expect(PUBLISH_TOOL_NAMES.has("ig_publish_photo")).toBe(true);
+    expect(PUBLISH_TOOL_NAMES.has("ig_publish_carousel")).toBe(true);
+    expect(PUBLISH_TOOL_NAMES.has("ig_publish_reel")).toBe(true);
+  });
+
+  it("does not contain SENSE tools", () => {
+    expect(PUBLISH_TOOL_NAMES.has("ig_get_comments")).toBe(false);
+    expect(PUBLISH_TOOL_NAMES.has("ig_get_account_insights")).toBe(false);
+  });
+
+  it("does not contain non-publish ACT tools", () => {
+    expect(PUBLISH_TOOL_NAMES.has("ig_reply_comment")).toBe(false);
+    expect(PUBLISH_TOOL_NAMES.has("ig_delete_comment")).toBe(false);
+  });
+});
+
+describe("checkRateLimit — per-tenant isolation", () => {
+  it("two different tenants have independent buckets", () => {
+    // Consume 10 tokens from tenant A
+    for (let i = 0; i < 10; i++) {
+      const r = checkRateLimit("ig_get_comments", "account_A");
+      expect(r.allowed).toBe(true);
+    }
+    // Tenant B should still have a full bucket — unaffected by A
+    const rB = checkRateLimit("ig_get_comments", "account_B");
+    expect(rB.allowed).toBe(true);
+  });
+
+  it("exhausting one tenant's publish bucket doesn't affect another", () => {
+    // ig_publish_photo has 25 tokens/day; burn all of them on tenant A
+    for (let i = 0; i < 25; i++) {
+      const r = checkRateLimit("ig_publish_photo", "tenant_exhaust");
+      expect(r.allowed).toBe(true);
+    }
+    // 26th call from tenant A should be blocked
+    const over = checkRateLimit("ig_publish_photo", "tenant_exhaust");
+    expect(over.allowed).toBe(false);
+
+    // But a fresh tenant should still be allowed
+    const fresh = checkRateLimit("ig_publish_photo", "tenant_fresh");
+    expect(fresh.allowed).toBe(true);
+  });
+
+  it("same tenantKey shares the same bucket across calls", () => {
+    for (let i = 0; i < 25; i++) {
+      checkRateLimit("ig_publish_carousel", "same_key");
+    }
+    // 26th call on the same key must be blocked
+    const r = checkRateLimit("ig_publish_carousel", "same_key");
+    expect(r.allowed).toBe(false);
+  });
+
+  it("undefined tenantKey uses the shared default bucket", () => {
+    // Consuming with no tenantKey should hit the default bucket
+    for (let i = 0; i < 25; i++) {
+      checkRateLimit("ig_publish_reel");
+    }
+    const r = checkRateLimit("ig_publish_reel");
+    expect(r.allowed).toBe(false);
+
+    // Meanwhile a named tenant should still have its own full bucket
+    const named = checkRateLimit("ig_publish_reel", "still_fresh");
+    expect(named.allowed).toBe(true);
+  });
+
+  it("reads from one tenant do not drain another tenant's global bucket", () => {
+    // Burn 100 read calls on tenant A (half the global bucket)
+    for (let i = 0; i < 100; i++) {
+      checkRateLimit("ig_get_comments", "reader_A");
+    }
+    // Tenant B should still have its full 200-token bucket — 150 consecutive
+    // read calls must all succeed. If B shared A's depleted bucket, the
+    // 101st total read (or thereabouts) would be blocked.
+    let allowedCount = 0;
+    for (let i = 0; i < 150; i++) {
+      const r = checkRateLimit("ig_get_comments", "reader_B");
+      if (r.allowed) allowedCount++;
+    }
+    expect(allowedCount).toBe(150);
+  });
+});
+
+describe("withRetry", () => {
+  it("succeeds on first try without retrying", async () => {
+    const fn = vi.fn().mockResolvedValue("ok");
+    const result = await withRetry(fn);
+    expect(result).toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws non-429 errors immediately", async () => {
+    const err = new Error("not found");
+    const fn = vi.fn().mockRejectedValue(err);
+    await expect(withRetry(fn)).rejects.toThrow("not found");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries on 429 status errors", { timeout: 10_000 }, async () => {
+    const rate429 = Object.assign(new Error("rate limit"), { status: 429 });
+    const fn = vi.fn().mockRejectedValueOnce(rate429).mockResolvedValue("ok");
+    const result = await withRetry(fn);
+    expect(result).toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries on Graph API code 4 errors", { timeout: 10_000 }, async () => {
+    const graphErr = Object.assign(new Error("too many calls"), { code: 4 });
+    const fn = vi.fn().mockRejectedValueOnce(graphErr).mockResolvedValue("ok");
+    const result = await withRetry(fn);
+    expect(result).toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it(
+    "gives up after max retries on persistent 429s",
+    { timeout: 30_000 },
+    async () => {
+      const rate429 = Object.assign(new Error("rate limit"), { status: 429 });
+      const fn = vi.fn().mockRejectedValue(rate429);
+      await expect(withRetry(fn)).rejects.toThrow("rate limit");
+      expect(fn).toHaveBeenCalledTimes(4); // initial + 3 retries
+    },
+  );
+});

package/src/rate-limiter.ts

@@ -0,0 +1,257 @@
+/**
+ * Token-bucket rate limiter for Instagram Graph API.
+ *
+ * Instagram Graph API rate limits are per **Business Account**, not per app.
+ * This limiter keys buckets by the caller's `tenantKey` (the IG Business
+ * Account 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 (photo / carousel / reel 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
+ */
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const MAX_WAIT_MS = 60_000;
+const MAX_429_RETRIES = 3;
+const TENANT_TTL_MS = 4 * 60 * 60 * 1000; // 4h matches client cache TTL
+
+export class TokenBucket {
+  private tokens: number;
+  private lastRefill: number;
+  private readonly maxTokens: number;
+  private readonly refillRate: number; // tokens per ms
+
+  constructor(config: { maxTokens: number; refillRate: number }) {
+    this.maxTokens = config.maxTokens;
+    this.refillRate = config.refillRate;
+    this.tokens = config.maxTokens;
+    this.lastRefill = Date.now();
+  }
+
+  tryConsume(cost = 1): boolean {
+    this.refill();
+    if (this.tokens >= cost) {
+      this.tokens -= cost;
+      return true;
+    }
+    return false;
+  }
+
+  msUntilAvailable(cost = 1): number {
+    this.refill();
+    if (this.tokens >= cost) return 0;
+    const deficit = cost - this.tokens;
+    return Math.ceil(deficit / this.refillRate);
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    const newTokens = elapsed * this.refillRate;
+    this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+    this.lastRefill = now;
+  }
+}
+
+// --- Per-tenant bucket storage ---
+
+interface TenantBuckets {
+  global: TokenBucket;
+  publish: TokenBucket;
+  lastAccessed: number;
+}
+
+const tenantBuckets = new Map<string, TenantBuckets>();
+const DEFAULT_TENANT_KEY = "__default__";
+
+function newBucketPair(): TenantBuckets {
+  return {
+    global: new TokenBucket({
+      maxTokens: 200,
+      refillRate: 200 / ONE_HOUR_MS,
+    }),
+    publish: new TokenBucket({
+      maxTokens: 25,
+      refillRate: 25 / ONE_DAY_MS,
+    }),
+    lastAccessed: Date.now(),
+  };
+}
+
+/**
+ * Get (or lazily create) the bucket pair for a tenant. Evicts stale entries
+ * on every call so long-running multi-tenant servers don't leak memory.
+ */
+function getBuckets(tenantKey: string | undefined): TenantBuckets {
+  const key = tenantKey || DEFAULT_TENANT_KEY;
+  const now = Date.now();
+
+  // Evict stale entries (except __default__ which is always kept)
+  for (const [k, v] of tenantBuckets) {
+    if (k !== DEFAULT_TENANT_KEY && now - v.lastAccessed > TENANT_TTL_MS) {
+      tenantBuckets.delete(k);
+    }
+  }
+
+  let entry = tenantBuckets.get(key);
+  if (!entry) {
+    entry = newBucketPair();
+    tenantBuckets.set(key, entry);
+  } else {
+    entry.lastAccessed = now;
+  }
+  return entry;
+}
+
+/**
+ * Test-only: wipe all tenant buckets. Used by unit tests to isolate cases.
+ */
+export function __resetRateLimiter(): void {
+  tenantBuckets.clear();
+}
+
+// --- Publish tool detection ---
+
+export const PUBLISH_TOOL_NAMES = new Set([
+  "ig_publish_photo",
+  "ig_publish_carousel",
+  "ig_publish_reel",
+]);
+
+/**
+ * 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 IG Business Account id).
+ *                    If omitted, uses a shared default bucket — fine for
+ *                    single-tenant / env-based usage.
+ * @param overrideCost Cost to consume (default 1)
+ */
+export function checkRateLimit(
+  toolName?: string,
+  tenantKey?: string,
+  overrideCost?: number,
+): { allowed: true } | { allowed: false; retryAfterMs: number } {
+  const { global, publish } = getBuckets(tenantKey);
+  const isPublish = toolName ? PUBLISH_TOOL_NAMES.has(toolName) : false;
+  const cost = overrideCost ?? 1;
+
+  // Peek global bucket
+  const globalWait = global.msUntilAvailable(cost);
+  if (globalWait > 0) return { allowed: false, retryAfterMs: globalWait };
+
+  if (isPublish) {
+    const publishWait = publish.msUntilAvailable(cost);
+    if (publishWait > 0) return { allowed: false, retryAfterMs: publishWait };
+
+    // Consume both
+    global.tryConsume(cost);
+    publish.tryConsume(cost);
+    return { allowed: true };
+  }
+
+  // Read path: consume global only
+  if (!global.tryConsume(cost)) {
+    return {
+      allowed: false,
+      retryAfterMs: global.msUntilAvailable(cost),
+    };
+  }
+  return { allowed: true };
+}
+
+/**
+ * Pre-flight rate limit check. Waits up to 60s if bucket is near-empty.
+ * Returns DEFER guidance if wait would exceed 60s.
+ */
+export async function waitForRateLimit(
+  toolName?: string,
+  tenantKey?: string,
+  overrideCost?: number,
+): Promise<{ allowed: true } | { allowed: false; retryAfterMs: number }> {
+  const check = checkRateLimit(toolName, tenantKey, overrideCost);
+  if (check.allowed) return check;
+
+  if (check.retryAfterMs <= MAX_WAIT_MS) {
+    await sleep(check.retryAfterMs);
+    return checkRateLimit(toolName, tenantKey, overrideCost);
+  }
+
+  return check;
+}
+
+/**
+ * Retry a function with exponential backoff on HTTP 429 errors.
+ * Also parses Retry-After header when available.
+ */
+export async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
+  for (let attempt = 0; attempt <= MAX_429_RETRIES; attempt++) {
+    try {
+      return await fn();
+    } catch (e: unknown) {
+      const is429 = isRateLimitError(e);
+      if (!is429 || attempt === MAX_429_RETRIES) throw e;
+
+      // Honor Retry-After header if present
+      const retryAfter = extractRetryAfter(e);
+      const backoffMs = retryAfter ?? 2000 * Math.pow(2, attempt);
+
+      console.error(
+        `[rate-limit] Instagram 429 — backing off ${backoffMs / 1000}s (attempt ${attempt + 1}/${MAX_429_RETRIES})...`,
+      );
+      await sleep(backoffMs);
+    }
+  }
+  throw new Error("Unreachable");
+}
+
+function isRateLimitError(e: unknown): boolean {
+  if (typeof e !== "object" || e === null) return false;
+  const obj = e as Record<string, unknown>;
+
+  // Graph API error format: { error: { code: 4, ... } } or HTTP 429
+  if (obj.status === 429) return true;
+  if (typeof obj.code === "number" && (obj.code === 4 || obj.code === 32))
+    return true;
+
+  // Nested error object
+  if (typeof obj.error === "object" && obj.error !== null) {
+    const inner = obj.error as Record<string, unknown>;
+    if (inner.code === 4 || inner.code === 32) return true;
+  }
+
+  if (e instanceof Error) {
+    const msg = e.message.toLowerCase();
+    if (msg.includes("429") || msg.includes("rate limit")) return true;
+  }
+
+  return false;
+}
+
+function extractRetryAfter(e: unknown): number | null {
+  if (typeof e !== "object" || e === null) return null;
+  const obj = e as Record<string, unknown>;
+
+  // Check for retryAfter in error metadata
+  if (typeof obj.retryAfter === "number") return obj.retryAfter * 1000;
+  if (typeof obj.retryAfterMs === "number") return obj.retryAfterMs;
+
+  return null;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}