@omnisocials/mcp-server 1.19.0 → 1.20.0

package/README.md

@@ -218,6 +218,11 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 
 ## Changelog
 
+### 1.20.0 (2026-08-04)
+
+- **Engagement rate now matches the dashboard:** `get_post_analytics` / `get_posts_analytics` previously summed likes + comments + shares only, dropping LinkedIn link clicks and X quotes/bookmarks from engagement. Both tools now use the same normalization as the dashboard and `get_analytics_overview`; rates are suppressed below 10 impressions and capped at 100%.
+- **Account metric semantics clarified:** LinkedIn account-level `impressions` on `get_account_analytics` are lifetime totals across all of the account's content (not a windowed count) — the tool now says so and renders each platform's scope `note`.
+
 ### 1.19.0 (2026-08-02)
 
 - **Alt text now reaches Instagram and LinkedIn:** per-media alt text (`{ url, alt }` / `{ id, alt }` entries) is also delivered to Instagram (image posts and carousel image slides — not Reels/Stories) and LinkedIn (images only — not video or documents), alongside Mastodon, Bluesky, X, and Pinterest.

package/build/index.js

@@ -29,7 +29,7 @@ const sessionState = { activeIndex: 0 };
 const getActiveClient = () => workspaceClients[sessionState.activeIndex].client;
 const server = new McpServer({
     name: "OmniSocials",
-    version: "1.19.0",
+    version: "1.20.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);

package/build/metrics.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Engagement / impressions normalizers — VENDORED COPY of the repo's
+ * `shared/analytics-metrics/index.js` (the single source of truth used by the
+ * backend, public API, remote MCP, and dashboard). This package publishes to
+ * npm standalone, so it can't require() across the monorepo — keep this file
+ * in sync with shared/analytics-metrics when the rules change there.
+ *
+ * WHY: the MCP tools used to compute engagement inline as
+ * likes+comments+shares, which silently dropped LinkedIn clicks and X
+ * quotes/bookmarks — so the same post showed a different engagement rate in
+ * MCP output than on the dashboard or /analytics/overview.
+ */
+export declare const MIN_IMPRESSIONS_FOR_ENGAGEMENT_RATE = 10;
+type Metrics = Record<string, unknown> | null | undefined;
+/** Total engagement (interaction count) for a post's metrics on a platform. */
+export declare function getEngagement(platform: string, metrics: Metrics): number;
+/** Best-available impressions ("how many times seen") for a post's metrics. */
+export declare function getImpressions(platform: string, metrics: Metrics): number;
+/**
+ * Engagement rate as a percentage (0-100), suppressed below the impression
+ * floor and capped at 100%.
+ */
+export declare function getEngagementRate(engagement: number, impressions: number): number;
+export {};

package/build/metrics.js

@@ -0,0 +1,111 @@
+/**
+ * Engagement / impressions normalizers — VENDORED COPY of the repo's
+ * `shared/analytics-metrics/index.js` (the single source of truth used by the
+ * backend, public API, remote MCP, and dashboard). This package publishes to
+ * npm standalone, so it can't require() across the monorepo — keep this file
+ * in sync with shared/analytics-metrics when the rules change there.
+ *
+ * WHY: the MCP tools used to compute engagement inline as
+ * likes+comments+shares, which silently dropped LinkedIn clicks and X
+ * quotes/bookmarks — so the same post showed a different engagement rate in
+ * MCP output than on the dashboard or /analytics/overview.
+ */
+// Minimum impressions before an engagement-rate percentage is meaningful.
+// Below this we suppress the rate rather than render a noisy ratio.
+export const MIN_IMPRESSIONS_FOR_ENGAGEMENT_RATE = 10;
+// Coerce anything (number, numeric string, null, undefined) to a finite number.
+const num = (v) => {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : 0;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+};
+/** Total engagement (interaction count) for a post's metrics on a platform. */
+export function getEngagement(platform, metrics) {
+    const m = metrics || {};
+    // Trust a precomputed engagement count when a fetcher already supplied one
+    // (Instagram total_interactions, TikTok/Threads/Pinterest sums, Google
+    // Business account engagement). Only when it's a real positive number —
+    // a stored 0 means "not computed" for the platforms that don't set it.
+    const pre = num(m.engagement);
+    if (pre > 0)
+        return pre;
+    const sum = (...keys) => keys.reduce((t, k) => t + num(m[k]), 0);
+    switch (platform) {
+        case "facebook":
+            // total_reactions already aggregates like/love/wow/...; fall back to the
+            // bare like count only when the aggregate is absent (never add both).
+            return (num(m.total_reactions) || num(m.likes)) + num(m.comments) + num(m.shares);
+        case "linkedin":
+        case "linkedin_page":
+            // LinkedIn's native engagement includes link clicks.
+            return sum("likes", "comments", "shares", "clicks");
+        case "youtube":
+            return sum("likes", "comments", "shares");
+        case "x":
+            // X's engagement total includes bookmarks (saves).
+            return sum("likes", "comments", "reposts", "quotes", "bookmarks");
+        case "threads":
+            // Threads stores replies (not comments) as the comment-equivalent.
+            return num(m.likes) + (num(m.comments) || num(m.replies)) + num(m.reposts) + num(m.quotes);
+        case "bluesky":
+            return sum("likes", "comments", "reposts", "quotes");
+        case "mastodon":
+            return sum("likes", "comments", "reposts");
+        case "reddit":
+            // likes == upvote score; shares == crossposts.
+            return sum("likes", "comments", "shares");
+        case "instagram":
+            return sum("likes", "comments", "saves", "shares");
+        case "tiktok":
+            return sum("likes", "comments", "shares");
+        case "pinterest":
+            return sum("saves", "pin_clicks", "outbound_clicks");
+        case "google_business":
+            // engagement is precomputed at account level; nothing to sum per post.
+            return pre;
+        default:
+            // Generic safe sum of common interaction fields for any future platform.
+            return sum("likes", "comments", "replies", "shares", "reposts", "quotes", "saves");
+    }
+}
+/** Best-available impressions ("how many times seen") for a post's metrics. */
+export function getImpressions(platform, metrics) {
+    const m = metrics || {};
+    switch (platform) {
+        case "instagram":
+            // Reels/video report `views` (play count) which is the true total-seen
+            // number and exceeds unique `reach`. Prefer it; fall back for old rows.
+            return num(m.views) || num(m.impressions) || num(m.reach);
+        case "facebook":
+            // Facebook exposes reach/impressions; video posts also report video_views.
+            return num(m.reach) || num(m.impressions) || num(m.video_views) || num(m.views);
+        case "linkedin":
+        case "linkedin_page":
+        case "pinterest":
+        case "google_business":
+            return num(m.impressions) || num(m.views) || num(m.reach);
+        case "youtube":
+        case "tiktok":
+        case "x":
+        case "threads":
+        case "bluesky":
+        case "mastodon":
+        case "reddit":
+        default:
+            return num(m.views) || num(m.impressions) || num(m.reach);
+    }
+}
+/**
+ * Engagement rate as a percentage (0-100), suppressed below the impression
+ * floor and capped at 100%.
+ */
+export function getEngagementRate(engagement, impressions) {
+    const imp = num(impressions);
+    if (imp < MIN_IMPRESSIONS_FOR_ENGAGEMENT_RATE)
+        return 0;
+    const rate = (num(engagement) / imp) * 100;
+    if (!Number.isFinite(rate) || rate < 0)
+        return 0;
+    return Math.min(rate, 100);
+}

package/build/tools/analytics.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatNumber, capitalize, metricRows, sortMetricLabels } from "../client.js";
+import { getEngagement, getImpressions, getEngagementRate, MIN_IMPRESSIONS_FOR_ENGAGEMENT_RATE, } from "../metrics.js";
 export function registerAnalyticsTools(server, getClient) {
     server.tool("get_post_analytics", "Get analytics/statistics for a specific published post. Renders every metric the platform reported — impressions, reach, views, saves, likes, comments, shares, clicks, engagements, and more — per platform.", {
         post_id: z.string().describe("The numeric OmniSocials post id (the `id` field from list_posts). NOT a platform post id such as a YouTube video id or tweet id."),
@@ -36,12 +37,14 @@ export function registerAnalyticsTools(server, getClient) {
         for (const [platform, entry] of platformEntries) {
             const m = entry?.metrics || {};
             const rows = metricRows(m);
-            const likes = Number(m.likes ?? m.favorites ?? m.reactions ?? 0);
-            const comments = Number(m.comments ?? m.replies ?? 0);
-            const shares = Number(m.shares ?? m.retweets ?? m.reposts ?? 0);
-            const engagements = m.engagement != null ? Number(m.engagement) : likes + comments + shares;
-            // Denominator for engagement rate: the broadest exposure count present.
-            const denom = Number(m.impressions ?? m.views ?? m.reach ?? 0);
+            // Engagement/impressions come from the shared normalizer (vendored in
+            // ../metrics.js) so the rate shown here matches the dashboard,
+            // /analytics/overview, and recent-platform. The previous inline
+            // likes+comments+shares sum silently dropped LinkedIn clicks and X
+            // quotes/bookmarks, so the same post showed a different engagement
+            // rate depending on the surface.
+            const engagements = getEngagement(platform, m);
+            const denom = getImpressions(platform, m);
             totalEngagements += engagements;
             totalDenom += denom;
             for (const [label, n] of rows) {
@@ -60,7 +63,11 @@ export function registerAnalyticsTools(server, getClient) {
         if (!totalsByLabel.has("Engagements"))
             totalOrder.push("Engagements");
         totalsByLabel.set("Engagements", totalEngagements);
-        const renderRate = (engagements, denom) => denom > 0 ? `| **Engagement Rate** | ${((engagements / denom) * 100).toFixed(2)}% |\n` : "";
+        // Suppressed below the shared impression floor (tiny denominators make
+        // noisy percentages), matching every other surface.
+        const renderRate = (engagements, denom) => denom >= MIN_IMPRESSIONS_FOR_ENGAGEMENT_RATE
+            ? `| **Engagement Rate** | ${getEngagementRate(engagements, denom).toFixed(2)}% |\n`
+            : "";
         let md = perPlatform.length === 1
             ? `## Post Analytics — ${capitalize(perPlatform[0].platform)}\n`
             : `## Post Analytics\n\n`;
@@ -112,18 +119,17 @@ export function registerAnalyticsTools(server, getClient) {
             let likes = 0;
             let comments = 0;
             let shares = 0;
-            for (const [, p] of platformEntries) {
+            for (const [name, p] of platformEntries) {
                 const m = p?.metrics || {};
-                // Broadest exposure count present, regardless of the platform's name
-                // for it (LinkedIn: impressions, TikTok/X/YouTube: views, IG: reach).
-                impressions += Number(m.impressions ?? m.views ?? m.reach ?? 0);
-                const l = Number(m.likes ?? m.favorites ?? m.reactions ?? 0);
-                const c = Number(m.comments ?? m.replies ?? 0);
-                const s = Number(m.shares ?? m.retweets ?? m.reposts ?? 0);
-                likes += l;
-                comments += c;
-                shares += s;
-                engagements += m.engagement != null ? Number(m.engagement) : l + c + s;
+                // Shared normalizer keeps these totals identical to get_post_analytics,
+                // the dashboard, and /analytics/overview (LinkedIn clicks and X
+                // quotes/bookmarks count toward engagement; the old inline sum dropped
+                // them). Likes/comments/shares stay as display columns only.
+                impressions += getImpressions(name, m);
+                engagements += getEngagement(name, m);
+                likes += Number(m.likes ?? m.favorites ?? m.reactions ?? 0);
+                comments += Number(m.comments ?? m.replies ?? 0);
+                shares += Number(m.shares ?? m.retweets ?? m.reposts ?? 0);
             }
             return {
                 post_id: entry.post_id,
@@ -195,7 +201,7 @@ export function registerAnalyticsTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("get_account_analytics", "Get account-level analytics (followers, subscribers, etc.) for connected social accounts.", {
+    server.tool("get_account_analytics", "Get account-level analytics (followers, subscribers, etc.) for connected social accounts. IMPORTANT metric semantics: account-level `impressions` for LinkedIn (profile and page) are LIFETIME cumulative totals across ALL of the account's content — including posts published outside OmniSocials — as of the snapshot date, NOT a daily or windowed count. They cannot be compared to a windowed export (e.g. LinkedIn's native 90-day analytics). Other platforms may not report account-level impressions at all. Each metrics object carries a `note` explaining its scope where semantics are non-obvious — always relay that note to the user.", {
         platform: z.string().optional().describe("Filter by platform (e.g., instagram, youtube)"),
         date: z.string().optional().describe("Date to get analytics for (YYYY-MM-DD, defaults to today)"),
     }, async (params) => {
@@ -221,6 +227,7 @@ export function registerAnalyticsTools(server, getClient) {
             const fb = b.metrics?.followers ?? 0;
             return fb - fa;
         });
+        const notes = [];
         for (const a of sorted) {
             const m = a.metrics || {};
             const followers = m.followers !== undefined
@@ -245,6 +252,14 @@ export function registerAnalyticsTools(server, getClient) {
                 details.push(`${formatNumber(m.subscribers)} subscribers`);
             }
             md += `| ${capitalize(a.platform)} | ${followers} | ${details.join(", ") || "—"} |\n`;
+            // Scope notes (e.g. "LinkedIn impressions are lifetime totals") must
+            // reach the user, or lifetime counters get read as windowed numbers.
+            if (typeof m.note === "string" && m.note) {
+                notes.push(`- **${capitalize(a.platform)}:** ${m.note}`);
+            }
+        }
+        if (notes.length) {
+            md += `\n${notes.join("\n")}\n`;
         }
         return {
             content: [{ type: "text", text: md }],

package/build/tools/posts.js

@@ -24,6 +24,30 @@ const mediaIdEntry = z.union([
         alt: z.string().max(1500).optional().describe(ALT_TEXT_DESCRIBE),
     }),
 ]).describe("Library media ID — a plain string, or { id, alt } to attach an accessibility description (alt text).");
+// Pinterest carousels cap at 5 images (Pinterest v5 `multiple_image_urls`);
+// videos are exempt — they publish as single video pins. Mirrors the
+// server-side create-time check in shared/post-validation with the identical
+// message; failing here just saves the agent an API round-trip. Only the
+// per-platform object form is checked — with a flat array this field alone
+// can't tell whether Pinterest is selected, so the server covers that case.
+const VIDEO_URL_RE = /\.(mp4|mov|webm|m4v|avi|mkv)(\?|$)/i;
+const pinterestImageCap = (value, ctx) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const entries = value.pinterest;
+    if (!Array.isArray(entries))
+        return;
+    const imageCount = entries.filter((entry) => {
+        const url = typeof entry === "string" ? entry : entry?.url;
+        return !(typeof url === "string" && VIDEO_URL_RE.test(url));
+    }).length;
+    if (imageCount > 5) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Pinterest carousel pins support a maximum of 5 images. Please remove some images and try again.",
+        });
+    }
+};
 // Reusable per-platform option objects for the "first comment" feature — text
 // auto-posted as a comment on the post right after it publishes (hashtags out
 // of the caption, "link in first comment", etc.). Only platforms with a
@@ -427,7 +451,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         media_urls: z.union([
             z.array(mediaUrlEntry),
             z.record(z.string(), z.array(mediaUrlEntry)),
-        ]).optional().describe("External image/video URLs — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...], pinterest: [...] }. Each entry is a plain URL string or { url, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). Max 10 total, each file ≤ 100 MB. When using per-platform format, 'default' is the fallback for selected platforms without their own key. Pass an empty array (e.g. facebook: []) to opt a platform out of media. For files over 100 MB (up to 1 GB): upload_media with method 'url' first, then pass the returned media id in `media`."),
+        ]).superRefine(pinterestImageCap).optional().describe("External image/video URLs — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...], pinterest: [...] }. Each entry is a plain URL string or { url, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). Max 10 total (Pinterest: max 5 images per carousel pin), each file ≤ 100 MB. When using per-platform format, 'default' is the fallback for selected platforms without their own key. Pass an empty array (e.g. facebook: []) to opt a platform out of media. For files over 100 MB (up to 1 GB): upload_media with method 'url' first, then pass the returned media id in `media`."),
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story' (Instagram/Facebook/Snapchat), 'reel' (Instagram/Facebook/YouTube/TikTok)"),
         link_url: z.string().optional().describe("URL to share as a rich preview card on platforms that support link-share posts (LinkedIn and Facebook). The URL renders as a tile with thumbnail / title / description instead of plain text. Ignored on platforms that don't support link shares, and ignored on posts that already have media attached (media wins)."),
         link_title: z.string().optional().describe("Optional title for the link-share preview. LinkedIn uses this when set; Facebook ignores it and fetches OG metadata server-side. Omit to let LinkedIn auto-fetch the page title."),
@@ -450,7 +474,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             link: z.string().optional().describe("Destination URL the pin clicks through to"),
             video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
             alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
+        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. Falls back to \"YouTube Short\" when omitted."),
             tags: z.array(z.string()).optional(),
@@ -608,7 +632,7 @@ Do NOT call without required media — it will fail.`, {
         media_urls: z.union([
             z.array(mediaUrlEntry),
             z.record(z.string(), z.array(mediaUrlEntry)),
-        ]).optional().describe("External image/video URLs — flat array or per-platform object. Each entry is a plain URL string or { url, alt } to attach alt text — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). Max 10 total, each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
+        ]).superRefine(pinterestImageCap).optional().describe("External image/video URLs — flat array or per-platform object. Each entry is a plain URL string or { url, alt } to attach alt text — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). Max 10 total (Pinterest: max 5 images per carousel pin), each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story', 'reel'"),
         location_id: z.string().optional().describe("Instagram only. Facebook Place ID of a single physical venue to tag the post's location. Applied to single-image and carousel Instagram feed posts. Use the `search_locations` tool to find a valid ID. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors (the 'Collab' feature). Works on image, carousel, and reel posts — NOT Stories. A leading '@' is stripped; usernames are case-insensitive. Private or non-existent usernames are rejected by Instagram at publish time. Ignored by other platforms."),
@@ -627,7 +651,7 @@ Do NOT call without required media — it will fail.`, {
             link: z.string().optional().describe("Destination URL the pin clicks through to"),
             video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
             alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
+        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube."),
             tags: z.array(z.string()).optional(),
@@ -737,7 +761,7 @@ Do NOT call without required media — it will fail.`, {
     });
     server.tool("update_post", `Update an existing post. Only draft and scheduled posts can be updated.
 
-**Per-platform options (\`youtube\`, \`pinterest\`, \`instagram\`, \`tiktok\`)** are accepted here, same shape as in \`create_post\`. Pass an object — never a JSON-encoded string. For YouTube Shorts, the **title** lives at \`youtube.title\`; the **video description** lives in \`content\` (or \`content.youtube\` for a per-platform override). They are not the same field — changing the caption does NOT rename the Short.
+**Per-platform options (\`youtube\`, \`pinterest\`, \`instagram\`, \`tiktok\`, \`google_business\`)** are accepted here, same shape as in \`create_post\`. Pass an object — never a JSON-encoded string. For YouTube Shorts, the **title** lives at \`youtube.title\`; the **video description** lives in \`content\` (or \`content.youtube\` for a per-platform override). They are not the same field — changing the caption does NOT rename the Short.
 
 **X threads**: To convert an existing draft into a chained X thread, pass \`x.thread_parts\` as a 2–25 entry array of \`{ text }\` objects (each ≤ 280 chars). Pass \`null\` to revert to single-tweet mode. Do NOT shove "1/", "2/" into \`content\` — that's a single tweet, not a thread.`, {
         id: z.string().describe("The post ID to update"),
@@ -751,7 +775,7 @@ Do NOT call without required media — it will fail.`, {
         media_urls: z.union([
             z.array(mediaUrlEntry),
             z.record(z.string(), z.array(mediaUrlEntry)),
-        ]).optional().describe("External URLs — flat array or per-platform object. Each entry is a plain URL string or { url, alt } to attach alt text — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). Max 10 total, each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
+        ]).superRefine(pinterestImageCap).optional().describe("External URLs — flat array or per-platform object. Each entry is a plain URL string or { url, alt } to attach alt text — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). Max 10 total (Pinterest: max 5 images per carousel pin), each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
         location_id: z.string().optional().describe("Instagram only. Facebook Place/Page ID to tag the post's location with. Send an empty string to clear an existing location tag. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors. Replaces the existing collaborator list. Send an empty array to clear collaborators. Works on image, carousel, and reel posts — NOT Stories. Ignored by other platforms."),
         user_tags: z.array(z.object({
@@ -776,7 +800,7 @@ Do NOT call without required media — it will fail.`, {
             link: z.string().optional().describe("Destination URL the pin clicks through to"),
             video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
             alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
+        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
         instagram: z.object({
             share_to_feed: z.boolean().optional(),
             thumbnail_type: z.enum(["from-video", "from-library"]).optional().describe("How the Reel cover is chosen: 'from-video' picks a frame at thumb_offset; 'from-library' uses the image at cover_url. get_post reads the chosen cover back."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnisocials/mcp-server",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "MCP server for OmniSocials API - manage social media posts, media, accounts, analytics, and webhooks",
   "type": "module",
   "main": "build/index.js",