@omnisocials/mcp-server 1.18.0 → 1.20.0

package/README.md

@@ -218,6 +218,16 @@ 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.
+- **`duration_seconds` on `get_recent_platform_posts`:** video length in whole seconds where the platform's listing API reports it (currently TikTok and YouTube; `null` for images and platforms that don't expose it) — rendered as a Duration column (m:ss) in the summary table and included in the `Structured data` JSON block.
+
 ### 1.18.0
 
 - **`retry_post`:** retry the failed platforms of a `failed` or partially failed (`warning`) post on the same post — only failed platforms are re-published, succeeded ones never post twice. Async via the publishing queue; poll `get_post` for the outcome. Max 3 retries per platform. Backed by `POST /api/v1/posts/{id}/retry`.
@@ -226,7 +236,7 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 
 ### 1.17.0
 
-- **Per-media alt text (accessibility descriptions):** `media_urls` / `media_ids` entries now accept `{ url, alt }` / `{ id, alt }` objects everywhere, including thread parts. Delivered to Mastodon (media description), Bluesky (embed alt), X (photos/GIFs), and Pinterest (pin `alt_text` fallback). `get_post` reads alt text back.
+- **Per-media alt text (accessibility descriptions):** `media_urls` / `media_ids` entries now accept `{ url, alt }` / `{ id, alt }` objects everywhere, including thread parts. Delivered to Mastodon (media description), Bluesky (embed alt), X (media metadata, photos/GIFs only) and Pinterest (pin alt_text fallback). `get_post` reads alt text back.
 
 ### 1.16.0
 

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.18.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/media.js

@@ -142,7 +142,7 @@ When the user provides an image in the conversation (not a URL), use base64_data
         if (compatibility && compatibility.compatible === false && compatibility.summary) {
             md += `\n\n⚠️ **${compatibility.summary}** It will still post to your other connected platforms. Ask the user whether to continue before adding it to a post.`;
         }
-        md += `\n\nUse this Media ID with \`media_ids\` when creating posts (including inside \`x.thread_parts[].media_ids\`). The public URL above also works anywhere \`media_urls\` is accepted. To attach alt text (an accessibility description), pass \`{ id: "<Media ID>", alt: "..." }\` instead of the bare ID — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest.`;
+        md += `\n\nUse this Media ID with \`media_ids\` when creating posts (including inside \`x.thread_parts[].media_ids\`). The public URL above also works anywhere \`media_urls\` is accepted. To attach alt text (an accessibility description), pass \`{ id: "<Media ID>", alt: "..." }\` instead of the bare ID — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images).`;
         return {
             content: [{ type: "text", text: md }],
         };

package/build/tools/posts.js

@@ -5,9 +5,11 @@ import { formatDateTime, truncate, capitalize, formatNumber, metricRows } from "
 // or an object carrying `alt`: an accessibility description (alt text, max
 // 1500 chars) for that file. Alt text is delivered to Mastodon (media
 // description — the community strongly values alt text), Bluesky (embed alt),
-// X (photos/GIFs only), and Pinterest (used as the pin alt_text when
-// pinterest.alt_text is not set); other platforms ignore it for now.
-const ALT_TEXT_DESCRIBE = "Accessibility description (alt text) for this file, max 1500 chars. Delivered to Mastodon (media description), Bluesky (embed alt), X (photos/GIFs only), and Pinterest (used as the pin alt_text when pinterest.alt_text is not set); other platforms ignore it.";
+// X (media metadata, photos/GIFs only), Pinterest (pin alt_text fallback),
+// Instagram (images and carousel image slides — not Reels/Stories, capped at
+// 1000 chars) and LinkedIn (images only — not video or documents); other
+// platforms ignore it for now.
+const ALT_TEXT_DESCRIBE = "Accessibility description (alt text) for this file, max 1500 chars. Delivered to Mastodon (media description), Bluesky (embed alt), X (media metadata, photos/GIFs only), Pinterest (pin alt_text fallback), Instagram (images and carousel image slides — not Reels/Stories) and LinkedIn (images only — not video or documents). Other platforms ignore it.";
 const mediaUrlEntry = z.union([
     z.string(),
     z.object({
@@ -22,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
@@ -421,11 +447,11 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         media_ids: z.union([
             z.array(mediaIdEntry),
             z.record(z.string(), z.array(mediaIdEntry)),
-        ]).optional().describe("Media IDs from upload — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...] }. Each entry is a plain ID string or { id, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest."),
+        ]).optional().describe("Media IDs from upload — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...] }. Each entry is a plain ID string or { id, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images)."),
         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 (photos/GIFs), and Pinterest. 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."),
@@ -448,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(),
@@ -602,11 +628,11 @@ Do NOT call without required media — it will fail.`, {
         media_ids: z.union([
             z.array(mediaIdEntry),
             z.record(z.string(), z.array(mediaIdEntry)),
-        ]).optional().describe("Media IDs from upload — flat array or per-platform object. Each entry is a plain ID string or { id, alt } to attach alt text — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest."),
+        ]).optional().describe("Media IDs from upload — flat array or per-platform object. Each entry is a plain ID string or { id, alt } to attach alt text — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images)."),
         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 (photos/GIFs), and Pinterest. 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."),
@@ -625,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(),
@@ -735,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"),
@@ -745,11 +771,11 @@ Do NOT call without required media — it will fail.`, {
         media_ids: z.union([
             z.array(mediaIdEntry),
             z.record(z.string(), z.array(mediaIdEntry)),
-        ]).optional().describe("Media IDs — flat array or per-platform object. Each entry is a plain ID string or { id, alt } to attach alt text — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest."),
+        ]).optional().describe("Media IDs — flat array or per-platform object. Each entry is a plain ID string or { id, alt } to attach alt text — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images)."),
         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 (photos/GIFs), and Pinterest. 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({
@@ -774,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."),
@@ -985,7 +1011,7 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
         });
         return { content: [{ type: "text", text: md }] };
     });
-    server.tool("get_recent_platform_posts", "Fetch the user's most recent posts straight from their connected platform APIs (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), INCLUDING content published outside OmniSocials. Use this when list_posts is empty — e.g. a brand-new workspace that has not published through OmniSocials yet — so you can still analyze the user's real content. Each post includes normalized `engagement` plus every raw metric the platform reported (Instagram: reach/views/saves/shares from per-post insights). Metrics only appear where the platform exposes them for historical posts (X, TikTok, Bluesky, Mastodon, Instagram, Facebook, YouTube); Threads, Pinterest, and Google Business return captions only. LinkedIn personal profiles can't be listed live (LinkedIn grants apps no such permission), so their results are posts published through OmniSocials with their latest collected stats. Fetched live, so expect a few seconds of latency. Output is a human-readable summary table PLUS a 'Structured data' JSON block carrying, for every post, the platform's own post id (the stable dedupe key), a permalink, the FULL untruncated caption, and exact-integer metrics — use that block when ingesting or storing native posts rather than the rounded/truncated table. Requires the analytics:read scope.", {
+    server.tool("get_recent_platform_posts", "Fetch the user's most recent posts straight from their connected platform APIs (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), INCLUDING content published outside OmniSocials. Use this when list_posts is empty — e.g. a brand-new workspace that has not published through OmniSocials yet — so you can still analyze the user's real content. Each post includes normalized `engagement` plus every raw metric the platform reported (Instagram: reach/views/saves/shares from per-post insights). Metrics only appear where the platform exposes them for historical posts (X, TikTok, Bluesky, Mastodon, Instagram, Facebook, YouTube); Threads, Pinterest, and Google Business return captions only. Records also carry `duration_seconds` — the video length in whole seconds — where the platform's listing API reports it (currently TikTok and YouTube); null for images and platforms that don't expose it. LinkedIn personal profiles can't be listed live (LinkedIn grants apps no such permission), so their results are posts published through OmniSocials with their latest collected stats. Fetched live, so expect a few seconds of latency. Output is a human-readable summary table PLUS a 'Structured data' JSON block carrying, for every post, the platform's own post id (the stable dedupe key), a permalink, the FULL untruncated caption, and exact-integer metrics — use that block when ingesting or storing native posts rather than the rounded/truncated table. Requires the analytics:read scope.", {
         limit: z
             .string()
             .optional()
@@ -1006,6 +1032,14 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
         const errors = result.errors || {};
         const errEntries = Object.entries(errors);
         const clean = (s) => String(s || "").replace(/[|\n\r]+/g, " ").trim();
+        // Video length as m:ss (e.g. 95 → "1:35"); blank for images and
+        // platforms whose listing API reports no duration.
+        const fmtVideoDuration = (secs) => {
+            if (typeof secs !== "number" || !Number.isFinite(secs))
+                return "—";
+            const s = Math.round(secs);
+            return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+        };
         if (!posts.length) {
             const note = result.note || "No recent platform posts found.";
             const errLines = errEntries.map(([p, m]) => `- ${capitalize(p)}: ${m}`).join("\n");
@@ -1014,8 +1048,8 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
             };
         }
         let md = `## Recent platform posts (${posts.length} across ${connected.length} platform${connected.length === 1 ? "" : "s"})\n\n`;
-        md += `| # | Platform | Format | Content | Engagement | Metrics | Date |\n`;
-        md += `|---|----------|--------|---------|------------|---------|------|\n`;
+        md += `| # | Platform | Format | Duration | Content | Engagement | Metrics | Date |\n`;
+        md += `|---|----------|--------|----------|---------|------------|---------|------|\n`;
         posts.forEach((p, i) => {
             const hasMetrics = p.metrics && Object.keys(p.metrics).length > 0;
             const content = truncate(clean(p.text), 45) || "*(no caption)*";
@@ -1027,7 +1061,7 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
                 .map(([label, n]) => `${formatNumber(n)} ${label.toLowerCase()}`)
                 .join(" · ");
             const date = p.timestamp ? formatDateTime(p.timestamp) : "—";
-            md += `| ${i + 1} | ${capitalize(p.platform)} | ${p.format || "post"} | ${content} | ${eng} | ${detail || "—"} | ${date} |\n`;
+            md += `| ${i + 1} | ${capitalize(p.platform)} | ${p.format || "post"} | ${fmtVideoDuration(p.duration_seconds)} | ${content} | ${eng} | ${detail || "—"} | ${date} |\n`;
         });
         if (result.note)
             md += `\n${result.note}\n`;
@@ -1049,6 +1083,7 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
             text: p.text ?? "",
             format: p.format ?? "post",
             media_count: p.media_count ?? 1,
+            duration_seconds: p.duration_seconds ?? null,
             timestamp: p.timestamp ?? null,
             image_url: p.image_url ?? null,
             engagement: p.engagement ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnisocials/mcp-server",
-  "version": "1.18.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",