@exileum/meta-mcp 4.0.0 → 6.0.0

package/README.md

@@ -64,11 +64,15 @@ npm run build
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `INSTAGRAM_ACCESS_TOKEN` | For Instagram | Instagram Graph API access token |
-| `INSTAGRAM_USER_ID` | For Instagram | Instagram Business/Creator account ID |
+| `INSTAGRAM_USER_ID` | For Instagram | Instagram Business/Creator account ID (numeric string, or `"me"` for the authenticated user) |
 | `THREADS_ACCESS_TOKEN` | For Threads | Threads API access token |
-| `THREADS_USER_ID` | For Threads | Threads user ID |
-| `META_APP_ID` | For token/webhook tools | Meta App ID |
+| `THREADS_USER_ID` | For Threads | Threads user ID (numeric string, or `"me"` for the authenticated user) |
+| `META_APP_ID` | For token/webhook tools | Meta App ID (numeric string) |
 | `META_APP_SECRET` | For token/webhook tools | Meta App Secret |
+| `META_API_VERSION` | Optional | Meta Graph API version for Instagram and Facebook endpoints — defaults to `v25.0` (verified 2026-05-06). Override only when Meta deprecates a version before meta-mcp ships a new release. Format: `vMAJOR.MINOR` (e.g., `v26.0`); malformed values fall back to the default with a stderr warning. OAuth token endpoints are unversioned and unaffected by this setting |
+| `THREADS_API_VERSION` | Optional | Threads API version — defaults to `v1.0` (verified 2026-05-06). Threads runs a separate single-major-version track and is not bumped in lockstep with the Graph API. Same `vMAJOR.MINOR` format and fallback behavior as `META_API_VERSION` |
+
+The server validates these at startup. Malformed values for `INSTAGRAM_USER_ID`, `THREADS_USER_ID`, or `META_APP_ID` cause the process to exit with `Invalid meta-mcp configuration: …`. Setting only one half of a credential pair (e.g., `INSTAGRAM_ACCESS_TOKEN` without `INSTAGRAM_USER_ID`) prints a stderr warning and continues; related tool invocations still fail at call time.
 
 ## Account Requirements
 
@@ -80,13 +84,14 @@ npm run build
 
 ## Features
 
-- **57 tools** across Instagram (33), Threads (18), and Meta platform (6)
+- **58 tools** across Instagram (33), Threads (19), and Meta platform (6)
 - **Instagram**: Publish photos/videos/reels/stories/carousels with alt text, manage comments, view insights, search hashtags, handle DMs, manage collaboration invites
 - **Threads**: Publish text/images/videos/carousels with polls, GIFs, topic tags, link attachments, alt text, spoiler flags; manage replies; search posts; delete posts; view insights
 - **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
+- **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
 
@@ -139,10 +144,10 @@ npm run build
 | Tool | Description |
 |------|-------------|
 | `ig_get_profile` | Get account profile info |
-| `ig_get_account_insights` | Get account-level analytics (views, reach, follower_count) |
+| `ig_get_account_insights` | Get account-level analytics (views, reach, follower_count). Optional `metric_type` (`total_value` or `time_series`) controls aggregation shape |
 | `ig_business_discovery` | Look up another business account |
 | `ig_get_collaboration_invites` | Get pending collaboration invites |
-| `ig_respond_collaboration_invite` | Accept or decline collaboration invites |
+| `ig_respond_collaboration_invite` | Accept/decline a collaboration invite by media_id |
 
 ### Instagram — Hashtags (4)
 
@@ -186,7 +191,7 @@ npm run build
 
 | Tool | Description |
 |------|-------------|
-| `threads_get_posts` | List published posts (includes topic_tag, poll, GIF fields) |
+| `threads_get_posts` | List published posts (includes topic_tag, poll, GIF fields; optional `fields` param to override the default field list) |
 | `threads_get_post` | Get post details |
 | `threads_search_posts` | Search public posts by keyword or tag (requires `threads_keyword_search` permission) |
 
@@ -205,12 +210,11 @@ npm run build
 |------|-------------|
 | `threads_get_mentions` | List posts where the user was @mentioned (requires `threads_manage_mentions`) |
 
-### Threads — Profile (2)
+### Threads — Profile (1)
 
 | Tool | Description |
 |------|-------------|
 | `threads_get_profile` | Get Threads profile info (includes `is_verified` and `is_eligible_for_geo_gating`) |
-| `threads_get_user_threads` | List user's threads |
 
 ### Threads — Insights (2)
 
@@ -223,8 +227,8 @@ npm run build
 
 | Resource URI | Description |
 |-------------|-------------|
-| `instagram://profile` | Instagram account profile data |
-| `threads://profile` | Threads account profile data (includes is_verified) |
+| `meta-mcp://instagram/profile` | Instagram account profile data |
+| `meta-mcp://threads/profile` | Threads account profile data (includes is_verified) |
 
 ## Prompts
 
@@ -282,7 +286,7 @@ Your **`META_APP_ID`** and **`META_APP_SECRET`** are in **App Settings -> Basic*
    https://threads.net/oauth/authorize
      ?client_id=YOUR_APP_ID
      &redirect_uri=YOUR_REDIRECT_URI
-     &scope=threads_basic,threads_content_publish,threads_manage_insights,threads_manage_replies,threads_read_replies,threads_share_to_instagram,threads_manage_mentions
+     &scope=threads_basic,threads_content_publish,threads_manage_insights,threads_manage_replies,threads_read_replies,threads_share_to_instagram,threads_manage_mentions,threads_keyword_search
      &response_type=code
    ```
    For local testing, use `https://localhost/` as redirect URI (configure in App Settings -> Threads API -> Redirect URIs).
@@ -329,10 +333,75 @@ Access tokens expire after ~60 days. Refresh before expiration (token must be at
 
 Check token status anytime with `meta_debug_token`.
 
+## Troubleshooting
+
+Tool failures return `isError: true` with a JSON body in `content[0].text` matching the envelope documented in [`CHANGELOG.md`](./CHANGELOG.md): `{ error: true, error_type, http_status, code, subcode, type, message, remediation, fbtrace_id, raw }`. The fastest path to a fix is to read `error_type` and the Meta API `code`, then jump to the matching subsection below. The full code reference is the [Meta Graph API error handling guide](https://developers.facebook.com/docs/graph-api/guides/error-handling/).
+
+### `error_type: "auth"` — expired, revoked, or under-scoped token
+
+Triggered by Meta API codes `190`, `10`, `102`, HTTP `401`, or `type: "OAuthException"`. Common messages:
+
+- `Error validating access token: Session has expired` — long-lived tokens expire ~60 days after issue.
+- `Application does not have permission for this action` — the token is missing a scope, or the account is not eligible (e.g., a **Personal** Instagram account on Graph API endpoints).
+
+What to do:
+
+1. Run `meta_debug_token` to inspect `expires_at`, `is_valid`, and `scopes`.
+2. If the token is **not yet expired** but at least 24h old, refresh in place with `meta_refresh_token` (`platform: "instagram"` or `"threads"`) — this extends the lifetime by another ~60 days. If the token is **already expired**, the refresh endpoint will reject it; regenerate a short-lived token from the Meta App dashboard and exchange it via `meta_exchange_token` (or run a full re-authorization for Threads).
+3. If scopes are missing, regenerate the token with the required permissions:
+   - **Instagram**: `instagram_business_basic` (always required) plus `instagram_business_content_publish`, `instagram_business_manage_comments`, `instagram_business_manage_messages` per feature.
+   - **Threads**: `threads_basic`, `threads_content_publish`, `threads_manage_insights`, `threads_manage_replies`, `threads_read_replies`, `threads_share_to_instagram`, `threads_manage_mentions`, `threads_keyword_search` per feature.
+4. If your Instagram account is **Personal**, switch to **Business** or **Creator** for free in the Instagram app (Settings → Account type and tools → Switch to professional account). The Graph API rejects Personal accounts.
+
+### `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).
+
+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.
+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
+
+Triggered by Meta API codes `100`, `200`, `803`, or any unmapped 4xx HTTP status. Common pitfalls:
+
+- **Wrong user ID format** — `INSTAGRAM_USER_ID` and `THREADS_USER_ID` must be the **numeric ID** returned by `GET /me?fields=user_id` (Instagram) or `GET /me?fields=id` (Threads), or the literal `"me"` for the authenticated user. The Instagram **username** is not accepted.
+- **`(#100) Messaging is not supported`** on `ig_send_message` / `ig_get_conversations` / `ig_get_messages` — the account does not have the messaging API enabled. Grant `instagram_business_manage_messages` on your token and ensure DMs are enabled in the Instagram app (Settings → Privacy → Messages).
+- **Deprecated publish endpoint** — `ig_publish_video` was retired by Meta on Nov 9, 2023; use `ig_publish_reel` for video posts. `ig_publish_story` is required for Stories.
+- **Mutually exclusive Threads attachments** — a `threads_publish_text` post can carry only one of `text_attachment`, `poll_options`, `link_attachment`, or `gif_attachment`; combining them is rejected at the schema level.
+- **Unsupported `metric` / `fields` for the resource** — see the per-tool Meta docs (`ig_get_media_insights` lists per-`media_type` valid metrics in its description).
+
+### 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: "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
+
+meta-mcp is consumed as an **MCP server runtime**, not as a library. The supported entry points are:
+
+- `npx @exileum/meta-mcp` (recommended for end users)
+- `node dist/index.js` (manual installation)
+
+The single programmatic export from the package root, `createSandboxServer(): McpServer`, exists for the [Smithery](https://smithery.ai) sandbox runner and is the only stable JavaScript/TypeScript API.
+
+**`zod` and other transitive runtime dependencies are internal** and not part of meta-mcp's public API. No `zod` symbols, types, or schemas flow through `dist/index.d.ts`, so `zod`'s version may change in any release — including major version bumps — without a corresponding meta-mcp major bump.
+
+**`@modelcontextprotocol/sdk` is the one exception**: `McpServer` (the return type of `createSandboxServer()`) is imported from that package, so a breaking change to `McpServer`'s public interface would also be a breaking change for meta-mcp's programmatic API. In practice the MCP SDK follows semver, so consumers can treat `@modelcontextprotocol/sdk` as an implicit peer dependency of the `createSandboxServer` export.
+
+Only the package root (`@exileum/meta-mcp`) is a supported import target. Deep imports into the published `dist/` tree (e.g. `@exileum/meta-mcp/dist/schemas.js`) are blocked by the `package.json` `exports` map for any spec-compliant resolver and are **not** part of the public API; they may be renamed, removed, or restructured in any release.
+
 ## Glama
 
 [![meta-mcp MCP server](https://glama.ai/mcp/servers/exileum/meta-mcp/badges/card.svg)](https://glama.ai/mcp/servers/exileum/meta-mcp)
 
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, project layout, the tool-registration recipe, testing, commit conventions, the CHANGELOG flow, and the CI gates. Bug reports and feature requests use the [issue templates](.github/ISSUE_TEMPLATE); pull requests use the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
+
 ## License
 
 [MIT](LICENSE)

package/dist/config.d.ts

@@ -1,10 +1,12 @@
-export interface MetaConfig {
-    appId: string;
-    appSecret: string;
-    instagramAccessToken: string;
-    instagramUserId: string;
-    threadsAccessToken: string;
-    threadsUserId: string;
-}
+import { z } from "zod";
+export declare const MetaConfigSchema: z.ZodObject<{
+    appId: z.ZodDefault<z.ZodString>;
+    appSecret: z.ZodDefault<z.ZodString>;
+    instagramAccessToken: z.ZodDefault<z.ZodString>;
+    instagramUserId: z.ZodDefault<z.ZodString>;
+    threadsAccessToken: z.ZodDefault<z.ZodString>;
+    threadsUserId: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type MetaConfig = z.infer<typeof MetaConfigSchema>;
 export declare function loadConfig(): MetaConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,UAAU,IAAI,UAAU,CASvC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB,eAAO,MAAM,gBAAgB;;;;;;;iBAO3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,wBAAgB,UAAU,IAAI,UAAU,CAiBvC"}

package/dist/config.js

@@ -1,11 +1,68 @@
+import { z } from "zod";
+// Regex `*` (zero-or-more) is intentional so the Zod `.default("")` for unset
+// vars passes validation; an empty string is treated as "absent" by warning
+// logic and by the lazy "X is not configured" runtime checks in MetaClient.
+const appIdSchema = z
+    .string()
+    .regex(/^\d*$/, "META_APP_ID must be a numeric string")
+    .default("");
+// User IDs accept either a numeric string or the literal "me" — Meta's
+// Graph/Threads APIs accept "me" as the authenticated-user alias on
+// `/{user-id}/...` paths (e.g., GET https://graph.threads.net/v1.0/me).
+const userIdSchema = (envName) => z
+    .string()
+    .regex(/^(me|\d*)$/, `${envName} must be a numeric string or "me"`)
+    .default("");
+export const MetaConfigSchema = z.object({
+    appId: appIdSchema,
+    appSecret: z.string().default(""),
+    instagramAccessToken: z.string().default(""),
+    instagramUserId: userIdSchema("INSTAGRAM_USER_ID"),
+    threadsAccessToken: z.string().default(""),
+    threadsUserId: userIdSchema("THREADS_USER_ID"),
+});
 export function loadConfig() {
-    return {
-        appId: process.env.META_APP_ID || "",
-        appSecret: process.env.META_APP_SECRET || "",
-        instagramAccessToken: process.env.INSTAGRAM_ACCESS_TOKEN || "",
-        instagramUserId: process.env.INSTAGRAM_USER_ID || "",
-        threadsAccessToken: process.env.THREADS_ACCESS_TOKEN || "",
-        threadsUserId: process.env.THREADS_USER_ID || "",
-    };
+    const result = MetaConfigSchema.safeParse({
+        appId: process.env.META_APP_ID,
+        appSecret: process.env.META_APP_SECRET,
+        instagramAccessToken: process.env.INSTAGRAM_ACCESS_TOKEN,
+        instagramUserId: process.env.INSTAGRAM_USER_ID,
+        threadsAccessToken: process.env.THREADS_ACCESS_TOKEN,
+        threadsUserId: process.env.THREADS_USER_ID,
+    });
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.message}`).join("\n");
+        throw new Error(`Invalid meta-mcp configuration:\n${issues}`);
+    }
+    warnIfMisconfigured(result.data);
+    return result.data;
+}
+function warnIfMisconfigured(config) {
+    const noCredentials = Object.values(config).every((v) => !v);
+    if (noCredentials) {
+        console.error("[meta-mcp] Warning: no credentials configured — every tool invocation will fail until you set INSTAGRAM_ACCESS_TOKEN, THREADS_ACCESS_TOKEN, or META_APP_ID/META_APP_SECRET.");
+    }
+    const pairs = [
+        [
+            !!config.instagramAccessToken,
+            !!config.instagramUserId,
+            "INSTAGRAM_ACCESS_TOKEN",
+            "INSTAGRAM_USER_ID",
+        ],
+        [
+            !!config.threadsAccessToken,
+            !!config.threadsUserId,
+            "THREADS_ACCESS_TOKEN",
+            "THREADS_USER_ID",
+        ],
+        [!!config.appId, !!config.appSecret, "META_APP_ID", "META_APP_SECRET"],
+    ];
+    for (const [hasA, hasB, aName, bName] of pairs) {
+        if (hasA === hasB)
+            continue;
+        const setName = hasA ? aName : bName;
+        const missingName = hasA ? bName : aName;
+        console.error(`[meta-mcp] Warning: ${setName} is set but ${missingName} is missing — related tools will fail at invocation time.`);
+    }
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE;QACpC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE;QAC5C,oBAAoB,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE;QAC9D,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE;QACpD,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE;QAC1D,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE;KACjD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

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;AA4EpE,wBAAgB,mBAAmB,cAmClC"}
+{"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"}

package/dist/index.js

@@ -31,7 +31,14 @@ const server = new McpServer({
     name: "meta-mcp",
     version: SERVER_VERSION,
 });
-const config = loadConfig();
+let config;
+try {
+    config = loadConfig();
+}
+catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
 const client = new MetaClient(config);
 // Register tools
 registerMetaAuthTools(server, client);

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":"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"}

package/dist/resources/instagram.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instagram.d.ts","sourceRoot":"","sources":["../../src/resources/instagram.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,QAoB/E"}
+{"version":3,"file":"instagram.d.ts","sourceRoot":"","sources":["../../src/resources/instagram.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGxD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,QAwB/E"}

package/dist/resources/instagram.js

@@ -1,17 +1,23 @@
+import { toMcpResourceError } from "../utils/errors.js";
 export function registerInstagramResources(server, client) {
-    server.resource("instagram-profile", "instagram://profile", { description: "Instagram Business/Creator account profile information", mimeType: "application/json" }, async () => {
-        const { data } = await client.ig("GET", `/${client.igUserId}`, {
-            fields: "id,name,username,biography,followers_count,follows_count,media_count,profile_picture_url,website",
-        });
-        return {
-            contents: [
-                {
-                    uri: "instagram://profile",
-                    mimeType: "application/json",
-                    text: JSON.stringify(data, null, 2),
-                },
-            ],
-        };
+    server.resource("instagram-profile", "meta-mcp://instagram/profile", { description: "Instagram Business/Creator account profile information", mimeType: "application/json" }, async () => {
+        try {
+            const { data } = await client.ig("GET", `/${client.igUserId}`, {
+                fields: "id,name,username,biography,followers_count,follows_count,media_count,profile_picture_url,website",
+            });
+            return {
+                contents: [
+                    {
+                        uri: "meta-mcp://instagram/profile",
+                        mimeType: "application/json",
+                        text: JSON.stringify(data, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw toMcpResourceError(error, "Get Instagram profile");
+        }
     });
 }
 //# sourceMappingURL=instagram.js.map

package/dist/resources/instagram.js.map

@@ -1 +1 @@
-{"version":3,"file":"instagram.js","sourceRoot":"","sources":["../../src/resources/instagram.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,0BAA0B,CAAC,MAAiB,EAAE,MAAkB;IAC9E,MAAM,CAAC,QAAQ,CACb,mBAAmB,EACnB,qBAAqB,EACrB,EAAE,WAAW,EAAE,wDAAwD,EAAE,QAAQ,EAAE,kBAAkB,EAAE,EACvG,KAAK,IAAI,EAAE;QACT,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE;YAC7D,MAAM,EAAE,kGAAkG;SAC3G,CAAC,CAAC;QACH,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,qBAAqB;oBAC1B,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;iBACpC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"instagram.js","sourceRoot":"","sources":["../../src/resources/instagram.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,UAAU,0BAA0B,CAAC,MAAiB,EAAE,MAAkB;IAC9E,MAAM,CAAC,QAAQ,CACb,mBAAmB,EACnB,8BAA8B,EAC9B,EAAE,WAAW,EAAE,wDAAwD,EAAE,QAAQ,EAAE,kBAAkB,EAAE,EACvG,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE;gBAC7D,MAAM,EAAE,kGAAkG;aAC3G,CAAC,CAAC;YACH,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,8BAA8B;wBACnC,QAAQ,EAAE,kBAAkB;wBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;qBACpC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/resources/threads.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"threads.d.ts","sourceRoot":"","sources":["../../src/resources/threads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,QAoB7E"}
+{"version":3,"file":"threads.d.ts","sourceRoot":"","sources":["../../src/resources/threads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGxD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,QAwB7E"}

package/dist/resources/threads.js

@@ -1,17 +1,23 @@
+import { toMcpResourceError } from "../utils/errors.js";
 export function registerThreadsResources(server, client) {
-    server.resource("threads-profile", "threads://profile", { description: "Threads user profile information", mimeType: "application/json" }, async () => {
-        const { data } = await client.threads("GET", `/${client.threadsUserId}`, {
-            fields: "id,username,name,threads_profile_picture_url,threads_biography,is_verified",
-        });
-        return {
-            contents: [
-                {
-                    uri: "threads://profile",
-                    mimeType: "application/json",
-                    text: JSON.stringify(data, null, 2),
-                },
-            ],
-        };
+    server.resource("threads-profile", "meta-mcp://threads/profile", { description: "Threads user profile information", mimeType: "application/json" }, async () => {
+        try {
+            const { data } = await client.threads("GET", `/${client.threadsUserId}`, {
+                fields: "id,username,name,threads_profile_picture_url,threads_biography,is_verified",
+            });
+            return {
+                contents: [
+                    {
+                        uri: "meta-mcp://threads/profile",
+                        mimeType: "application/json",
+                        text: JSON.stringify(data, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw toMcpResourceError(error, "Get Threads profile");
+        }
     });
 }
 //# sourceMappingURL=threads.js.map

package/dist/resources/threads.js.map

@@ -1 +1 @@
-{"version":3,"file":"threads.js","sourceRoot":"","sources":["../../src/resources/threads.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,MAAkB;IAC5E,MAAM,CAAC,QAAQ,CACb,iBAAiB,EACjB,mBAAmB,EACnB,EAAE,WAAW,EAAE,kCAAkC,EAAE,QAAQ,EAAE,kBAAkB,EAAE,EACjF,KAAK,IAAI,EAAE;QACT,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,aAAa,EAAE,EAAE;YACvE,MAAM,EAAE,4EAA4E;SACrF,CAAC,CAAC;QACH,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,mBAAmB;oBACxB,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;iBACpC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"threads.js","sourceRoot":"","sources":["../../src/resources/threads.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,MAAkB;IAC5E,MAAM,CAAC,QAAQ,CACb,iBAAiB,EACjB,4BAA4B,EAC5B,EAAE,WAAW,EAAE,kCAAkC,EAAE,QAAQ,EAAE,kBAAkB,EAAE,EACjF,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,aAAa,EAAE,EAAE;gBACvE,MAAM,EAAE,4EAA4E;aACrF,CAAC,CAAC;YACH,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,4BAA4B;wBACjC,QAAQ,EAAE,kBAAkB;wBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;qBACpC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,kBAAkB,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC;QACzD,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/schemas.d.ts

@@ -4,4 +4,18 @@ import { z } from "zod";
  * Use for all user-provided media and callback URLs to prevent SSRF and non-secure schemes.
  */
 export declare const httpsUrl: z.ZodString;
+/**
+ * Zod schema for Meta-issued resource IDs (media, comment, container, post,
+ * reply, conversation, message, hashtag). Use for any ID that gets interpolated
+ * into a URL path segment in MetaClient calls — rejects path-altering characters
+ * (`/`, `.`, `?`, `&`, `=`, whitespace) at schema parse time so a crafted value
+ * cannot rewrite the request path or inject query params. The `+` quantifier
+ * also enforces non-empty (callers chaining `.min(1)` is redundant).
+ *
+ * Real Meta IDs are numeric (e.g. `17889615324123`) or numeric-with-underscore
+ * for compound containers (e.g. `17841405822304914_17889615324123`); the
+ * `[a-zA-Z0-9_-]` set is intentionally broader to absorb future format changes
+ * while keeping path-traversal characters out.
+ */
+export declare const metaId: z.ZodString;
 //# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,QAAQ,aAGpB,CAAC"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,QAAQ,aAGpB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,aAGlB,CAAC"}

package/dist/schemas.js

@@ -4,4 +4,18 @@ import { z } from "zod";
  * Use for all user-provided media and callback URLs to prevent SSRF and non-secure schemes.
  */
 export const httpsUrl = z.string().url().refine((u) => u.toLowerCase().startsWith("https://"), { message: "URL must use HTTPS" });
+/**
+ * Zod schema for Meta-issued resource IDs (media, comment, container, post,
+ * reply, conversation, message, hashtag). Use for any ID that gets interpolated
+ * into a URL path segment in MetaClient calls — rejects path-altering characters
+ * (`/`, `.`, `?`, `&`, `=`, whitespace) at schema parse time so a crafted value
+ * cannot rewrite the request path or inject query params. The `+` quantifier
+ * also enforces non-empty (callers chaining `.min(1)` is redundant).
+ *
+ * Real Meta IDs are numeric (e.g. `17889615324123`) or numeric-with-underscore
+ * for compound containers (e.g. `17841405822304914_17889615324123`); the
+ * `[a-zA-Z0-9_-]` set is intentionally broader to absorb future format changes
+ * while keeping path-traversal characters out.
+ */
+export const metaId = z.string().regex(/^[a-zA-Z0-9_-]+$/, "ID must contain only letters, numbers, underscores, and hyphens");
 //# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,CAC7C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAC7C,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAClC,CAAC"}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,CAC7C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAC7C,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAClC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CACpC,kBAAkB,EAClB,iEAAiE,CAClE,CAAC"}

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

@@ -1,4 +1,10 @@
 import { MetaConfig } from "../config.js";
+export declare const DEFAULT_META_API_VERSION = "v25.0";
+export declare const DEFAULT_THREADS_API_VERSION = "v1.0";
+export interface MetaClientOptions {
+    metaApiVersion?: string;
+    threadsApiVersion?: string;
+}
 export interface RateLimit {
     callCount?: number;
     totalCpuTime?: number;
@@ -8,17 +14,53 @@ export interface ClientResponse {
     data: Record<string, unknown>;
     rateLimit?: RateLimit;
 }
+/**
+ * Allowed value types for form-encoded query string and request body parameters.
+ * Non-primitive values (arrays, objects) must be serialized by the caller (JSON.stringify, .join(",") etc.)
+ * before being assigned — the form-encoded path uses String(v) which produces "[object Object]" / "1,2,3"
+ * for objects/arrays and silently corrupts the request.
+ */
+export type FormParamValue = string | number | boolean | undefined | null;
+export type FormParams = Record<string, FormParamValue>;
 export interface RequestOptions {
-    json?: boolean;
+    /**
+     * Sends the value as an `application/json` request body instead of the default
+     * `application/x-www-form-urlencoded`. The `access_token` is moved to the query
+     * string (never embedded in the JSON body) and `params` must be omitted —
+     * combining them is rejected at runtime so callers don't accidentally route
+     * data into both transports.
+     *
+     * **When to use:** only when Meta's documentation explicitly requires
+     * `Content-Type: application/json` for the endpoint. Currently the
+     * Instagram Messaging Send API (`POST /{ig-user-id}/messages`, used by
+     * `ig_send_message`) is the only such endpoint — it accepts nested
+     * `recipient` / `message` objects that would be flattened to
+     * `[object Object]` if sent through the form path. See
+     * https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/messaging-api
+     *
+     * **When not to use:** every other Graph API endpoint (Threads publish,
+     * Instagram media/comments/collaboration, Meta App Subscriptions, etc.)
+     * accepts form-urlencoded with flat string/number/boolean parameters and
+     * works correctly through the default path. Nested objects required by the
+     * API (`poll_attachment`, `gif_attachment`, `text_attachment`, `user_tags`)
+     * must be `JSON.stringify`-ed by the caller into a single form field — the
+     * runtime guard in `appendFormParams` rejects raw objects/arrays so this
+     * convention is enforced (see #81). Audited in #104.
+     */
+    jsonBody?: Record<string, unknown>;
 }
 export declare class MetaClient {
     private config;
-    constructor(config: MetaConfig);
+    private igBase;
+    private fbBase;
+    private threadsBase;
+    constructor(config: MetaConfig, options?: MetaClientOptions);
     private parseRateLimit;
+    private appendFormParams;
     private request;
-    ig(method: string, path: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ClientResponse>;
-    threads(method: string, path: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ClientResponse>;
-    meta(method: string, path: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ClientResponse>;
+    ig(method: string, path: string, params?: FormParams, options?: RequestOptions): Promise<ClientResponse>;
+    threads(method: string, path: string, params?: FormParams, options?: RequestOptions): Promise<ClientResponse>;
+    meta(method: string, path: string, params?: FormParams, options?: RequestOptions): Promise<ClientResponse>;
     /** Exchange short-lived Instagram token for long-lived token (60 days) */
     igExchangeToken(shortToken: string): Promise<ClientResponse>;
     /** Refresh a long-lived Instagram token (must be at least 24h old and not expired) */

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;AAU1C,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,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAa;gBAEf,MAAM,EAAE,UAAU;IAI9B,OAAO,CAAC,cAAc;YAeR,OAAO;IA+Df,EAAE,CACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC;IAOpB,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC;IAOpB,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,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":"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"}