@exileum/meta-mcp 6.0.0 → 7.0.0

package/README.md

@@ -90,7 +90,8 @@ The server validates these at startup. Malformed values for `INSTAGRAM_USER_ID`,
 - **Meta**: Token exchange/refresh/debug, webhook management
 - **2 resources**: Instagram profile, Threads profile
 - **2 prompts**: Cross-platform content publishing, analytics report
-- Rate limit tracking via `x-app-usage` header
+- Rate limit tracking via `x-app-usage` header — and **automatic client-side throttling** at 80% (1s slowdown) / 90% (5s backoff) so a burst of tool calls stays under Meta's per-app quota
+- **Automatic retry** for transient Meta API failures (HTTP `429`/`500`/`502`/`503`/`504`, network errors, `fetch` timeouts) with exponential backoff and `Retry-After` honoring; tunable via `MetaClient`'s `maxRetries` option (default 3, set to 0 to disable)
 - **Structured error responses** with `error_type` (`auth`, `validation`, `rate_limit`, `server`, `network`, `internal`), HTTP status, Meta API code/subcode/type, and a `remediation` hint where actionable — see [`CHANGELOG.md`](./CHANGELOG.md) for the JSON shape
 
 ## Tools
@@ -171,21 +172,22 @@ The server validates these at startup. Malformed values for `INSTAGRAM_USER_ID`,
 |------|-------------|
 | `ig_get_conversations` | List DM conversations |
 | `ig_get_messages` | Get messages in a conversation |
-| `ig_send_message` | Send a DM |
+| `ig_send_message` | Send a DM (optional `messaging_type` = `RESPONSE`/`UPDATE`/`MESSAGE_TAG` and `tag` = `HUMAN_AGENT` for the 7-day human-agent window) |
 | `ig_get_message` | Get message details |
 
-### Threads — Publishing (8)
+### Threads — Publishing (9)
 
 | Tool | Description |
 |------|-------------|
-| `threads_publish_text` | Publish a text post in a single API call (`auto_publish_text=true`, default; set `auto_publish=false` for the legacy two-step flow). Supports polls, GIFs, link attachments, topic tags, quote posts, spoiler flag, cross-share to IG Stories, geo-gating via `allowlisted_country_codes`, text attachments up to 10K chars with styling |
-| `threads_publish_image` | Publish an image post (supports alt_text, topic tags, spoiler flag, cross-share to IG Stories, geo-gating via `allowlisted_country_codes`) |
-| `threads_publish_video` | Publish a video post (supports alt_text, topic tags, spoiler flag, cross-share to IG Stories, geo-gating via `allowlisted_country_codes`) |
-| `threads_publish_carousel` | Publish a carousel (2-20 items, supports alt_text per item, cross-share to IG Stories, geo-gating via `allowlisted_country_codes` on the parent container) |
+| `threads_publish_text` | Publish a text post in a single API call (`auto_publish_text=true`, default; set `auto_publish=false` for the legacy two-step flow). Supports polls, GIFs, link attachments, topic tags, quote posts, spoiler flag, cross-share to IG Stories, geo-gating via `allowlisted_country_codes`, location tagging via `location_id`, text attachments up to 10K chars with styling |
+| `threads_publish_image` | Publish an image post (supports alt_text, topic tags, spoiler flag, cross-share to IG Stories, geo-gating via `allowlisted_country_codes`, location tagging via `location_id`) |
+| `threads_publish_video` | Publish a video post (supports alt_text, topic tags, spoiler flag, cross-share to IG Stories, geo-gating via `allowlisted_country_codes`, location tagging via `location_id`) |
+| `threads_publish_carousel` | Publish a carousel (2-20 items, supports alt_text per item, cross-share to IG Stories, geo-gating via `allowlisted_country_codes` and location tagging via `location_id` on the parent container) |
 | `threads_delete_post` | Delete a post (max 100/day) |
 | `threads_get_container_status` | Check container processing status (unpublished containers only) |
 | `threads_get_publishing_limit` | Check remaining publishing quota (250 posts/day) |
 | `threads_repost` | Repost an existing thread to your profile (requires `threads_content_publish`) |
+| `threads_search_locations` | Search Threads-supported locations by query (`q`) or coordinates (`latitude`+`longitude`) to obtain a `location_id` for the four `threads_publish_*` tools (requires `threads_location_tagging` permission) |
 
 ### Threads — Media & Search (3)
 
@@ -355,12 +357,12 @@ What to do:
 
 ### `error_type: "rate_limit"` — application or user quota exhausted
 
-Triggered by Meta API codes `4`, `17`, `32`, `341`, `613`, the business-use-case range `80001`–`80008`, or HTTP `429`. Includes any `OAuthException` with code `4` / `17` (these are surfaced as `error_type: "rate_limit"`, **not** `"auth"`, despite the type field).
+Triggered by Meta API codes `4`, `17`, `32`, `341`, `613`, the business-use-case range `80001`–`80008`, or HTTP `429`. Includes any `OAuthException` with code `4` / `17` (these are surfaced as `error_type: "rate_limit"`, **not** `"auth"`, despite the type field). `MetaClient` automatically retries HTTP `429` up to 3 times with exponential backoff and honors any `Retry-After` header — a `rate_limit` error reaching the caller means the retry budget was exhausted.
 
 What to do:
 
-1. Inspect the `_rateLimit` field on prior successful tool responses. `callCount`, `totalCpuTime`, and `totalTime` come from Meta's `x-app-usage` header; when `callCount` approaches `100` you are near the per-app threshold.
-2. Back off with exponential delay; reduce request volume; cache profile metadata between calls.
+1. Inspect the `_rateLimit` field on prior successful tool responses. `callCount`, `totalCpuTime`, and `totalTime` come from Meta's `x-app-usage` header; when any approaches `100` you are near the per-app threshold.
+2. meta-mcp already self-throttles once `max(callCount, totalCpuTime, totalTime)` crosses 80% (1s slowdown) or 90% (5s backoff) — see the `[meta-mcp] x-app-usage at N%…` lines on stderr. If you are still hitting `rate_limit` errors despite that, reduce request volume further and cache profile metadata between calls.
 3. Threads has hard daily quotas (250 publishes, 100 deletes) — query the remaining quota with `threads_get_publishing_limit` before bulk operations.
 
 ### `error_type: "validation"` — bad parameter, wrong ID, or unsupported field
@@ -375,8 +377,8 @@ Triggered by Meta API codes `100`, `200`, `803`, or any unmapped 4xx HTTP status
 
 ### Other categories
 
-- `error_type: "server"` (codes `1`, `2`, HTTP 5xx) — transient Meta outage; retry with exponential backoff. Check [metastatus.com](https://metastatus.com/) if it persists.
-- `error_type: "network"` — `fetch` timed out or failed before reaching Meta. Verify outbound connectivity and retry.
+- `error_type: "server"` (codes `1`, `2`, HTTP 5xx) — transient Meta outage. `MetaClient` already retried `500`/`502`/`503`/`504` up to 3 times with exponential backoff before surfacing this; check [metastatus.com](https://metastatus.com/) if it persists.
+- `error_type: "network"` — `fetch` timed out or failed before reaching Meta. `MetaClient` already retried thrown network errors up to 3 times; verify outbound connectivity if the error keeps reappearing.
 - `error_type: "internal"` — unexpected condition that did not map to a Meta error code. The `raw` field carries the sanitized original message; `access_token`, `client_secret`, and `input_token` values are scrubbed to `***` before reporting.
 
 ## API Stability

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkFpE,wBAAgB,mBAAmB,cAmClC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqCpE,wBAAgB,mBAAmB,cAmBlC"}

package/dist/index.js

@@ -4,27 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig } from "./config.js";
 import { MetaClient } from "./services/meta-client.js";
-// Meta platform tools
-import { registerMetaAuthTools } from "./tools/meta/auth.js";
-// Instagram tools
-import { registerIgPublishingTools } from "./tools/instagram/publishing.js";
-import { registerIgMediaTools } from "./tools/instagram/media.js";
-import { registerIgCommentTools } from "./tools/instagram/comments.js";
-import { registerIgProfileTools } from "./tools/instagram/profile.js";
-import { registerIgHashtagTools } from "./tools/instagram/hashtags.js";
-import { registerIgMentionTools } from "./tools/instagram/mentions.js";
-import { registerIgMessagingTools } from "./tools/instagram/messaging.js";
-// Threads tools
-import { registerThreadsPublishingTools } from "./tools/threads/publishing.js";
-import { registerThreadsMediaTools } from "./tools/threads/media.js";
-import { registerThreadsReplyTools } from "./tools/threads/replies.js";
-import { registerThreadsProfileTools } from "./tools/threads/profile.js";
-import { registerThreadsInsightTools } from "./tools/threads/insights.js";
-import { registerThreadsMentionsTools } from "./tools/threads/mentions.js";
-// Resources & Prompts
-import { registerInstagramResources } from "./resources/instagram.js";
-import { registerThreadsResources } from "./resources/threads.js";
-import { registerPrompts } from "./prompts/index.js";
+import { registerAll } from "./register-all.js";
 const require = createRequire(import.meta.url);
 const { version: SERVER_VERSION } = require("../package.json");
 const server = new McpServer({
@@ -40,26 +20,7 @@ catch (err) {
     process.exit(1);
 }
 const client = new MetaClient(config);
-// Register tools
-registerMetaAuthTools(server, client);
-registerIgPublishingTools(server, client);
-registerIgMediaTools(server, client);
-registerIgCommentTools(server, client);
-registerIgProfileTools(server, client);
-registerIgHashtagTools(server, client);
-registerIgMentionTools(server, client);
-registerIgMessagingTools(server, client);
-registerThreadsPublishingTools(server, client);
-registerThreadsMediaTools(server, client);
-registerThreadsReplyTools(server, client);
-registerThreadsProfileTools(server, client);
-registerThreadsInsightTools(server, client);
-registerThreadsMentionsTools(server, client);
-// Register resources
-registerInstagramResources(server, client);
-registerThreadsResources(server, client);
-// Register prompts
-registerPrompts(server);
+registerAll(server, client);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
@@ -83,23 +44,7 @@ export function createSandboxServer() {
         threadsUserId: "",
     };
     const mockClient = new MetaClient(mockConfig);
-    registerMetaAuthTools(sandbox, mockClient);
-    registerIgPublishingTools(sandbox, mockClient);
-    registerIgMediaTools(sandbox, mockClient);
-    registerIgCommentTools(sandbox, mockClient);
-    registerIgProfileTools(sandbox, mockClient);
-    registerIgHashtagTools(sandbox, mockClient);
-    registerIgMentionTools(sandbox, mockClient);
-    registerIgMessagingTools(sandbox, mockClient);
-    registerThreadsPublishingTools(sandbox, mockClient);
-    registerThreadsMediaTools(sandbox, mockClient);
-    registerThreadsReplyTools(sandbox, mockClient);
-    registerThreadsProfileTools(sandbox, mockClient);
-    registerThreadsInsightTools(sandbox, mockClient);
-    registerThreadsMentionsTools(sandbox, mockClient);
-    registerInstagramResources(sandbox, mockClient);
-    registerThreadsResources(sandbox, mockClient);
-    registerPrompts(sandbox);
+    registerAll(sandbox, mockClient);
     return sandbox;
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAc,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,cAAc;CACxB,CAAC,CAAC;AAEH,IAAI,MAAkB,CAAC;AACvB,IAAI,CAAC;IACH,MAAM,GAAG,UAAU,EAAE,CAAC;AACxB,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AACD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAEtC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,yBAAyB;AAEzB,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,IAAI,SAAS,CAAC;QAC5B,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,UAAU,GAAe;QAC7B,KAAK,EAAE,EAAE;QACT,SAAS,EAAE,EAAE;QACb,oBAAoB,EAAE,EAAE;QACxB,eAAe,EAAE,EAAE;QACnB,kBAAkB,EAAE,EAAE;QACtB,aAAa,EAAE,EAAE;KAClB,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IAE9C,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAEjC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/register-all.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MetaClient } from "./services/meta-client.js";
+export declare function registerAll(server: McpServer, client: MetaClient): void;
+//# sourceMappingURL=register-all.d.ts.map

package/dist/register-all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-all.d.ts","sourceRoot":"","sources":["../src/register-all.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AA2BvD,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAkBvE"}

package/dist/register-all.js

@@ -0,0 +1,41 @@
+// Meta platform tools
+import { registerMetaAuthTools } from "./tools/meta/auth.js";
+// Instagram tools
+import { registerIgPublishingTools } from "./tools/instagram/publishing.js";
+import { registerIgMediaTools } from "./tools/instagram/media.js";
+import { registerIgCommentTools } from "./tools/instagram/comments.js";
+import { registerIgProfileTools } from "./tools/instagram/profile.js";
+import { registerIgHashtagTools } from "./tools/instagram/hashtags.js";
+import { registerIgMentionTools } from "./tools/instagram/mentions.js";
+import { registerIgMessagingTools } from "./tools/instagram/messaging.js";
+// Threads tools
+import { registerThreadsPublishingTools } from "./tools/threads/publishing.js";
+import { registerThreadsMediaTools } from "./tools/threads/media.js";
+import { registerThreadsReplyTools } from "./tools/threads/replies.js";
+import { registerThreadsProfileTools } from "./tools/threads/profile.js";
+import { registerThreadsInsightTools } from "./tools/threads/insights.js";
+import { registerThreadsMentionsTools } from "./tools/threads/mentions.js";
+// Resources & Prompts
+import { registerInstagramResources } from "./resources/instagram.js";
+import { registerThreadsResources } from "./resources/threads.js";
+import { registerPrompts } from "./prompts/index.js";
+export function registerAll(server, client) {
+    registerMetaAuthTools(server, client);
+    registerIgPublishingTools(server, client);
+    registerIgMediaTools(server, client);
+    registerIgCommentTools(server, client);
+    registerIgProfileTools(server, client);
+    registerIgHashtagTools(server, client);
+    registerIgMentionTools(server, client);
+    registerIgMessagingTools(server, client);
+    registerThreadsPublishingTools(server, client);
+    registerThreadsMediaTools(server, client);
+    registerThreadsReplyTools(server, client);
+    registerThreadsProfileTools(server, client);
+    registerThreadsInsightTools(server, client);
+    registerThreadsMentionsTools(server, client);
+    registerInstagramResources(server, client);
+    registerThreadsResources(server, client);
+    registerPrompts(server);
+}
+//# sourceMappingURL=register-all.js.map

package/dist/register-all.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-all.js","sourceRoot":"","sources":["../src/register-all.ts"],"names":[],"mappings":"AAGA,sBAAsB;AACtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,kBAAkB;AAClB,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,gBAAgB;AAChB,OAAO,EAAE,8BAA8B,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E,sBAAsB;AACtB,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,UAAU,WAAW,CAAC,MAAiB,EAAE,MAAkB;IAC/D,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,8BAA8B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,4BAA4B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,0BAA0B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,eAAe,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC"}

package/dist/services/meta-client.d.ts

@@ -1,15 +1,62 @@
 import { MetaConfig } from "../config.js";
 export declare const DEFAULT_META_API_VERSION = "v25.0";
 export declare const DEFAULT_THREADS_API_VERSION = "v1.0";
+export declare const DEFAULT_MAX_RETRIES = 3;
+export declare const DEFAULT_RETRY_BASE_DELAY_MS = 1000;
+export declare const MAX_RETRY_DELAY_MS = 60000;
+/**
+ * Parse a `Retry-After` response header value (RFC 7231 §7.1.3) into
+ * milliseconds. Returns `undefined` for missing or unparseable values so the
+ * caller falls back to the exponential-backoff schedule. Past dates and
+ * negative seconds clamp to `0` to absorb server time skew.
+ */
+export declare function parseRetryAfter(value: string | null, nowMs: number): number | undefined;
+/**
+ * Exponential backoff `base * 2^attempt` with 0–25% jitter to spread
+ * concurrent clients and avoid thundering-herd reconnects. Capped at
+ * {@link MAX_RETRY_DELAY_MS}. `rand` is injectable for deterministic tests.
+ */
+export declare function computeBackoffDelay(attempt: number, baseDelayMs: number, rand?: () => number): number;
 export interface MetaClientOptions {
     metaApiVersion?: string;
     threadsApiVersion?: string;
+    /**
+     * Maximum number of retry attempts after the initial request fails with a
+     * transient error (HTTP 429/500/502/503/504 or a thrown network error).
+     * Total request count is `maxRetries + 1`. Set to `0` to disable retries
+     * entirely (matches pre-#61 behavior). Defaults to {@link DEFAULT_MAX_RETRIES}.
+     */
+    maxRetries?: number;
+    /**
+     * Base delay (ms) used by the exponential-backoff schedule between retries.
+     * Attempt N waits `baseDelayMs * 2^N` plus 0–25% jitter (capped at
+     * {@link MAX_RETRY_DELAY_MS}). Defaults to {@link DEFAULT_RETRY_BASE_DELAY_MS}.
+     * Tests pass `0` to make retries fire immediately without real waiting.
+     */
+    retryBaseDelayMs?: number;
+    /**
+     * @internal — testing-only seam, not part of the stable API. Injection point
+     * for the sleep primitive used between retries. Defaults to a
+     * `setTimeout`-backed `Promise`.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * @internal — testing-only seam, not part of the stable API. Injection point
+     * for the current-time source used when parsing the HTTP-date form of the
+     * `Retry-After` header. Defaults to `Date.now`.
+     */
+    now?: () => number;
 }
 export interface RateLimit {
     callCount?: number;
     totalCpuTime?: number;
     totalTime?: number;
 }
+export declare const RATE_LIMIT_SLOWDOWN_THRESHOLD = 80;
+export declare const RATE_LIMIT_BACKOFF_THRESHOLD = 90;
+export declare const RATE_LIMIT_SLOWDOWN_MS = 1000;
+export declare const RATE_LIMIT_BACKOFF_MS = 5000;
+export declare const RATE_LIMIT_SNAPSHOT_TTL_MS: number;
 export interface ClientResponse {
     data: Record<string, unknown>;
     rateLimit?: RateLimit;
@@ -54,8 +101,15 @@ export declare class MetaClient {
     private igBase;
     private fbBase;
     private threadsBase;
+    private lastRateLimit?;
+    private lastRateLimitAt?;
+    private maxRetries;
+    private retryBaseDelayMs;
+    private sleep;
+    private now;
     constructor(config: MetaConfig, options?: MetaClientOptions);
     private parseRateLimit;
+    private maybeThrottle;
     private appendFormParams;
     private request;
     ig(method: string, path: string, params?: FormParams, options?: RequestOptions): Promise<ClientResponse>;

package/dist/services/meta-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta-client.d.ts","sourceRoot":"","sources":["../../src/services/meta-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAa1C,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAChD,eAAO,MAAM,2BAA2B,SAAS,CAAC;AA8BlD,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;AAC1E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AA4BD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,iBAAiB;IAiB3D,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,gBAAgB;YAeV,OAAO;IAuFf,EAAE,CACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC;IAOpB,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC;IAOpB,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC;IAQ1B,0EAA0E;IACpE,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAUlE,sFAAsF;IAChF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAMhE,wEAAwE;IAClE,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAUvE,oFAAoF;IAC9E,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAMrE,oBAAoB;IACd,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAU7D,IAAI,QAAQ,IAAI,MAAM,CAKrB;IAED,IAAI,aAAa,IAAI,MAAM,CAK1B;CACF"}
+{"version":3,"file":"meta-client.d.ts","sourceRoot":"","sources":["../../src/services/meta-client.ts"],"names":[],"mappings":"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"}

package/dist/services/meta-client.js

@@ -16,6 +16,52 @@ const API_VERSION_PATTERN = /^v\d+\.\d+$/;
 // surface has no version segment; piping META_API_VERSION here would 404).
 const IG_TOKEN_BASE = "https://graph.instagram.com";
 const THREADS_TOKEN_BASE = "https://graph.threads.net";
+// Retry policy for transient Meta API failures (#61). 429 is the explicit
+// rate-limit signal; 502/503/504 are canonical gateway/availability errors;
+// 500 is included because Meta's infrastructure routinely returns transient
+// 500s during brief overloads alongside the more canonical 5xx codes. Every
+// other 4xx is a permanent caller-side error (auth, validation) and fails fast.
+const RETRYABLE_HTTP_STATUSES = new Set([429, 500, 502, 503, 504]);
+export const DEFAULT_MAX_RETRIES = 3;
+export const DEFAULT_RETRY_BASE_DELAY_MS = 1000;
+// Cap so a malformed `Retry-After: 999999` (≈11 days) can't hang a tool.
+export const MAX_RETRY_DELAY_MS = 60_000;
+/**
+ * Parse a `Retry-After` response header value (RFC 7231 §7.1.3) into
+ * milliseconds. Returns `undefined` for missing or unparseable values so the
+ * caller falls back to the exponential-backoff schedule. Past dates and
+ * negative seconds clamp to `0` to absorb server time skew.
+ */
+export function parseRetryAfter(value, nowMs) {
+    if (value === null)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        if (Number.isFinite(seconds))
+            return Math.max(0, seconds * 1000);
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - nowMs);
+    }
+    return undefined;
+}
+/**
+ * Exponential backoff `base * 2^attempt` with 0–25% jitter to spread
+ * concurrent clients and avoid thundering-herd reconnects. Capped at
+ * {@link MAX_RETRY_DELAY_MS}. `rand` is injectable for deterministic tests.
+ */
+export function computeBackoffDelay(attempt, baseDelayMs, rand = Math.random) {
+    const exponential = baseDelayMs * Math.pow(2, attempt);
+    const jitter = exponential * 0.25 * rand();
+    return Math.min(exponential + jitter, MAX_RETRY_DELAY_MS);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function resolveApiVersion(envName, fallback, explicit) {
     // Explicit MetaClientOptions value, if any, takes precedence over the env
     // var; both go through the same regex check + warn-fallback so a malformed
@@ -31,6 +77,17 @@ function resolveApiVersion(envName, fallback, explicit) {
     }
     return raw;
 }
+// Pre-request throttle thresholds — Meta throttles at 100% usage on any of
+// callCount / totalCpuTime / totalTime per
+// https://developers.facebook.com/docs/graph-api/overview/rate-limiting/,
+// so we back off well before the cliff.
+export const RATE_LIMIT_SLOWDOWN_THRESHOLD = 80;
+export const RATE_LIMIT_BACKOFF_THRESHOLD = 90;
+export const RATE_LIMIT_SLOWDOWN_MS = 1000;
+export const RATE_LIMIT_BACKOFF_MS = 5000;
+// Meta's rate-limit window is rolling 1h — discard the snapshot after that so
+// a long-idle client doesn't pay a spurious backoff on its first post-idle call.
+export const RATE_LIMIT_SNAPSHOT_TTL_MS = 60 * 60 * 1000;
 function parseMetaErrorBody(text) {
     if (!text)
         return undefined;
@@ -56,6 +113,12 @@ export class MetaClient {
     igBase;
     fbBase;
     threadsBase;
+    lastRateLimit;
+    lastRateLimitAt;
+    maxRetries;
+    retryBaseDelayMs;
+    sleep;
+    now;
     constructor(config, options) {
         this.config = config;
         const metaVersion = resolveApiVersion("META_API_VERSION", DEFAULT_META_API_VERSION, options?.metaApiVersion);
@@ -63,6 +126,18 @@ export class MetaClient {
         this.igBase = `https://graph.instagram.com/${metaVersion}`;
         this.fbBase = `https://graph.facebook.com/${metaVersion}`;
         this.threadsBase = `https://graph.threads.net/${threadsVersion}`;
+        // `Math.max(0, Infinity)` is `Infinity` (infinite loop) and `0 <= NaN` is
+        // `false` (loop body never runs); reject non-finite values and fall back.
+        const rawMaxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.maxRetries = Number.isFinite(rawMaxRetries)
+            ? Math.max(0, rawMaxRetries)
+            : DEFAULT_MAX_RETRIES;
+        const rawBaseDelay = options?.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+        this.retryBaseDelayMs = Number.isFinite(rawBaseDelay)
+            ? Math.max(0, rawBaseDelay)
+            : DEFAULT_RETRY_BASE_DELAY_MS;
+        this.sleep = options?.sleep ?? defaultSleep;
+        this.now = options?.now ?? Date.now;
     }
     parseRateLimit(headers) {
         const usage = headers.get("x-app-usage");
@@ -70,16 +145,54 @@ export class MetaClient {
             return undefined;
         try {
             const raw = JSON.parse(usage);
+            // `Number(undefined)` is NaN, `Number("92")` is 92 — coerce defensively
+            // so a future Meta API tweak (numbers shipped as strings) still produces
+            // a usable RateLimit instead of silently leaving fields `undefined`.
+            const num = (v) => {
+                if (v === undefined || v === null)
+                    return undefined;
+                const n = Number(v);
+                return Number.isFinite(n) ? n : undefined;
+            };
             return {
-                callCount: raw.call_count,
-                totalCpuTime: raw.total_cpu_time,
-                totalTime: raw.total_time,
+                callCount: num(raw.call_count),
+                totalCpuTime: num(raw.total_cpu_time),
+                totalTime: num(raw.total_time),
             };
         }
         catch {
             return undefined;
         }
     }
+    // Take `max(callCount, totalCpuTime, totalTime)` because Meta throttles on
+    // whichever quota hits 100% first. Concurrent calls at high usage both
+    // sleep their full delay and then fire together — acceptable for MCP's
+    // typically sequential call pattern, still safer than no throttling.
+    async maybeThrottle() {
+        const rl = this.lastRateLimit;
+        if (!rl)
+            return;
+        if (this.lastRateLimitAt !== undefined && Date.now() - this.lastRateLimitAt > RATE_LIMIT_SNAPSHOT_TTL_MS) {
+            this.lastRateLimit = undefined;
+            this.lastRateLimitAt = undefined;
+            return;
+        }
+        const max = Math.max(rl.callCount ?? 0, rl.totalCpuTime ?? 0, rl.totalTime ?? 0);
+        let delay;
+        if (max >= RATE_LIMIT_BACKOFF_THRESHOLD) {
+            delay = RATE_LIMIT_BACKOFF_MS;
+        }
+        else if (max >= RATE_LIMIT_SLOWDOWN_THRESHOLD) {
+            delay = RATE_LIMIT_SLOWDOWN_MS;
+        }
+        else {
+            return;
+        }
+        console.error(`[meta-mcp] x-app-usage at ${max}% (callCount=${rl.callCount ?? "?"}, ` +
+            `totalTime=${rl.totalTime ?? "?"}, totalCpuTime=${rl.totalCpuTime ?? "?"}); ` +
+            `delaying next request by ${delay}ms to stay under Meta's per-app quota.`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
     // Used for both form bodies (POST/PUT) and query strings (GET/DELETE) — every
     // entry ends up URL-encoded in `qs`. Skipping `""` must precede the typeof
     // check so the type narrowing below stays correct after the filter.
@@ -98,7 +211,6 @@ export class MetaClient {
     }
     async request(baseUrl, token, method, path, params, options) {
         let url = `${baseUrl}${path}`;
-        const init = { method, signal: AbortSignal.timeout(30_000) };
         const isWrite = method !== "GET" && method !== "DELETE";
         const useJson = isWrite && options?.jsonBody !== undefined;
         // `params` always lands in the URL query string (form body for POST/PUT,
@@ -113,61 +225,107 @@ export class MetaClient {
         qs.set("access_token", token);
         if (params)
             this.appendFormParams(qs, params);
+        // Body/headers are stable strings reusable across retry attempts; only
+        // `signal` must be fresh per attempt — sharing an exhausted
+        // `AbortSignal.timeout` would silently abort every subsequent retry.
+        const baseInit = { method };
         if (useJson) {
             url += (url.includes("?") ? "&" : "?") + qs.toString();
-            init.headers = { "Content-Type": "application/json" };
-            init.body = JSON.stringify(options.jsonBody);
+            baseInit.headers = { "Content-Type": "application/json" };
+            baseInit.body = JSON.stringify(options.jsonBody);
         }
         else if (isWrite) {
-            init.headers = { "Content-Type": "application/x-www-form-urlencoded" };
-            init.body = qs.toString();
+            baseInit.headers = { "Content-Type": "application/x-www-form-urlencoded" };
+            baseInit.body = qs.toString();
         }
         else {
             url += (url.includes("?") ? "&" : "?") + qs.toString();
         }
-        const res = await fetch(url, init);
-        if (!res.ok) {
-            const text = await res.text().catch(() => "");
-            const parsed = parseMetaErrorBody(text);
-            const detail = parsed?.message ?? text;
-            throw new MetaApiError({
-                message: `Meta API ${method} ${path} (${res.status}): ${detail}`,
-                httpStatus: res.status,
-                apiCode: parsed?.code,
-                apiSubcode: parsed?.subcode,
-                apiType: parsed?.type,
-                fbtraceId: parsed?.fbtraceId,
-                endpoint: path,
-                method,
-                body: text,
-            });
-        }
-        const rateLimit = this.parseRateLimit(res.headers);
-        const contentType = res.headers.get("content-type") || "";
-        if (contentType.includes("application/json")) {
-            const data = (await res.json());
-            if (data.error) {
-                const err = data.error;
-                const apiCode = typeof err.code === "number" ? err.code : undefined;
-                const apiSubcode = typeof err.error_subcode === "number" ? err.error_subcode : undefined;
-                const apiType = typeof err.type === "string" ? err.type : undefined;
-                const apiMessage = typeof err.message === "string" ? err.message : String(err.message ?? "");
-                const fbtraceId = typeof err.fbtrace_id === "string" ? err.fbtrace_id : undefined;
+        // Retry loop (#61): total request count is `maxRetries + 1`. `attempt` is
+        // 0-based — `attempt = 0` is the initial request, `attempt = N` is the Nth
+        // retry. `computeBackoffDelay(attempt, …)` therefore produces the correct
+        // 1s / 2s / 4s schedule on attempts 0 / 1 / 2 before retries 1 / 2 / 3.
+        // The trailing `throw` after the loop is for TS control-flow narrowing.
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            // Pre-request throttle from #60 — runs before every attempt so a retry
+            // after a 429 still consults the most recent x-app-usage snapshot.
+            await this.maybeThrottle();
+            // Arm the 30s abort timer *after* the throttle sleep so a backoff at
+            // high x-app-usage doesn't eat into the actual network window (#60 review).
+            const init = { ...baseInit, signal: AbortSignal.timeout(30_000) };
+            let res;
+            try {
+                res = await fetch(url, init);
+            }
+            catch (err) {
+                if (attempt < this.maxRetries) {
+                    await this.sleep(computeBackoffDelay(attempt, this.retryBaseDelayMs));
+                    continue;
+                }
+                throw err;
+            }
+            // Parse rate-limit on every response (a 429 still carries `x-app-usage`);
+            // header-less responses (OAuth token endpoints) leave state intact.
+            const rateLimit = this.parseRateLimit(res.headers);
+            if (rateLimit) {
+                this.lastRateLimit = rateLimit;
+                this.lastRateLimitAt = Date.now();
+            }
+            if (!res.ok &&
+                RETRYABLE_HTTP_STATUSES.has(res.status) &&
+                attempt < this.maxRetries) {
+                const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"), this.now());
+                const delay = retryAfterMs !== undefined
+                    ? Math.min(retryAfterMs, MAX_RETRY_DELAY_MS)
+                    : computeBackoffDelay(attempt, this.retryBaseDelayMs);
+                // Release the connection — `cancel()` rejects on already-consumed bodies.
+                res.body?.cancel().catch(() => { });
+                await this.sleep(delay);
+                continue;
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                const parsed = parseMetaErrorBody(text);
+                const detail = parsed?.message ?? text;
                 throw new MetaApiError({
-                    message: `Meta API error: ${apiMessage} (code ${apiCode ?? "?"})`,
-                    apiCode,
-                    apiSubcode,
-                    apiType,
-                    fbtraceId,
+                    message: `Meta API ${method} ${path} (${res.status}): ${detail}`,
+                    httpStatus: res.status,
+                    apiCode: parsed?.code,
+                    apiSubcode: parsed?.subcode,
+                    apiType: parsed?.type,
+                    fbtraceId: parsed?.fbtraceId,
                     endpoint: path,
                     method,
-                    body: JSON.stringify(err),
+                    body: text,
                 });
             }
-            return { data, rateLimit };
+            const contentType = res.headers.get("content-type") || "";
+            if (contentType.includes("application/json")) {
+                const data = (await res.json());
+                if (data.error) {
+                    const err = data.error;
+                    const apiCode = typeof err.code === "number" ? err.code : undefined;
+                    const apiSubcode = typeof err.error_subcode === "number" ? err.error_subcode : undefined;
+                    const apiType = typeof err.type === "string" ? err.type : undefined;
+                    const apiMessage = typeof err.message === "string" ? err.message : String(err.message ?? "");
+                    const fbtraceId = typeof err.fbtrace_id === "string" ? err.fbtrace_id : undefined;
+                    throw new MetaApiError({
+                        message: `Meta API error: ${apiMessage} (code ${apiCode ?? "?"})`,
+                        apiCode,
+                        apiSubcode,
+                        apiType,
+                        fbtraceId,
+                        endpoint: path,
+                        method,
+                        body: JSON.stringify(err),
+                    });
+                }
+                return { data, rateLimit };
+            }
+            const text = await res.text();
+            return { data: { raw: text, success: true }, rateLimit };
         }
-        const text = await res.text();
-        return { data: { raw: text, success: true }, rateLimit };
+        throw new Error("MetaClient: retry loop exited without resolution (unreachable)");
     }
     async ig(method, path, params, options) {
         if (!this.config.instagramAccessToken) {