@omnisocials/mcp-server 1.24.0 → 1.27.0

package/build/client.d.ts

@@ -9,6 +9,9 @@ export declare function formatDate(iso: string | null): string;
 export declare function formatDateTime(iso: string | null): string;
 export declare function truncate(value: unknown, len: number): string;
 export declare function capitalize(str: string): string;
+/** Breakdown objects (reactions by type, traffic sources, ...) rendered as
+ * "Label: a 12, b 3" lines under the metric table. */
+export declare function metricBreakdownRows(m: Record<string, unknown> | null | undefined): Array<[string, string]>;
 export declare function sortMetricLabels(labels: string[]): string[];
 /**
  * Flatten a raw per-platform metrics object into ordered [label, value] rows,

package/build/client.js

@@ -107,14 +107,60 @@ const METRIC_LABELS = [
     ["quotes", "Quotes"],
     ["bookmarks", "Bookmarks"],
     ["replies", "Replies"],
-    ["reactions", "Reactions"],
     ["total_reactions", "Total reactions"],
     ["favorites", "Favorites"],
     ["plays", "Plays"],
     ["engagement", "Engagements"],
+    ["link_clicks", "Link clicks"],
+    ["profile_visits", "Profile visits"],
+    ["follows", "Follows from post"],
+    ["pin_clicks", "Pin clicks"],
+    ["outbound_clicks", "Outbound clicks"],
+    ["video_views", "Video views"],
+    ["engaged_views", "Engaged views"],
+    ["avg_watch_time", "Avg. watch time (s)"],
+    ["total_watch_time", "Total watch time (s)"],
+    ["watch_time_percentage", "Watched (%)"],
+    ["completion_rate", "Completion rate (%)"],
+    ["skip_rate", "Skip rate (%)"],
+    ["replays", "Replays"],
+    ["subscribers_gained", "Subscribers gained"],
+    ["subscribers_lost", "Subscribers lost"],
+    ["duration", "Duration (s)"],
 ];
-// Context keys that ride along in stored metrics — not counters.
-const NON_COUNTER_KEYS = new Set(["create_time"]);
+// Context keys that ride along in stored metrics, not counters.
+const NON_COUNTER_KEYS = new Set(["create_time", "story_slide_index"]);
+/** Breakdown objects (reactions by type, traffic sources, ...) rendered as
+ * "Label: a 12, b 3" lines under the metric table. */
+export function metricBreakdownRows(m) {
+    const LABELS = {
+        reactions: "Reactions by type",
+        clicks_breakdown: "Clicks by type",
+        profile_activity_breakdown: "Profile actions",
+        navigation_breakdown: "Story navigation",
+        completion_analysis: "Story completion",
+        traffic_sources: "Traffic sources",
+        impression_sources: "Where it was seen",
+        audience_types: "Viewer types",
+        audience_countries: "Top countries",
+        impressions_breakdown: "Impressions by surface",
+        online_followers: "Followers online by hour (UTC)",
+    };
+    const rows = [];
+    for (const [key, label] of Object.entries(LABELS)) {
+        const v = m?.[key];
+        if (!v || typeof v !== "object" || Array.isArray(v))
+            continue;
+        const parts = Object.entries(v)
+            .filter(([, n]) => Number.isFinite(Number(n)))
+            .sort((a, b) => Number(b[1]) - Number(a[1]))
+            .slice(0, 8)
+            .map(([k, n]) => `${k.replace(/_/g, " ")} ${Number(n) <= 1 && key.endsWith("_sources") ? `${Math.round(Number(n) * 100)}%` : formatNumber(Number(n))}`);
+        if (parts.length)
+            rows.push([label, parts.join(", ")]);
+    }
+    return rows;
+}
 /** Canonical position of a metric label — for sorting totals rows collected
  * across platforms back into METRIC_LABELS order (unknown labels sink). */
 const LABEL_ORDER = new Map(METRIC_LABELS.map(([, label], i) => [label, i]));

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.24.0",
+    version: "1.27.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);

package/build/metrics.d.ts

@@ -16,6 +16,8 @@ type Metrics = Record<string, unknown> | null | undefined;
 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;
+/** Unique accounts reached, when the platform reports it (0 otherwise). */
+export declare function getReach(platform: string, metrics: Metrics): number;
 /**
  * Engagement rate as a percentage (0-100), suppressed below the impression
  * floor and capped at 100%.

package/build/metrics.js

@@ -43,24 +43,33 @@ export function getEngagement(platform, metrics) {
         case "youtube":
             return sum("likes", "comments", "shares");
         case "x":
-            // X's engagement total includes bookmarks (saves).
+            // X's engagement total includes bookmarks (saves). A native
+            // non_public_metrics.engagements value, when stored, wins above.
             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);
+            return (num(m.likes) +
+                (num(m.comments) || num(m.replies)) +
+                num(m.reposts) +
+                num(m.quotes) +
+                num(m.shares));
         case "bluesky":
-            return sum("likes", "comments", "reposts", "quotes");
+            return sum("likes", "comments", "reposts", "quotes", "bookmarks");
         case "mastodon":
-            return sum("likes", "comments", "reposts");
+            return sum("likes", "comments", "reposts", "quotes");
         case "reddit":
             // likes == upvote score; shares == crossposts.
             return sum("likes", "comments", "shares");
         case "instagram":
-            return sum("likes", "comments", "saves", "shares");
+            // Stories carry total_interactions (replies, shares, profile taps)
+            // instead of likes/comments; use it when present.
+            return num(m.total_interactions) || sum("likes", "comments", "saves", "shares");
         case "tiktok":
-            return sum("likes", "comments", "shares");
+            // favorites == saves on TikTok (Business API only).
+            return sum("likes", "comments", "shares", "favorites");
         case "pinterest":
-            return sum("saves", "pin_clicks", "outbound_clicks");
+            // likes == TOTAL_REACTIONS, comments == TOTAL_COMMENTS.
+            return sum("saves", "pin_clicks", "outbound_clicks", "likes", "comments");
         case "google_business":
             // engagement is precomputed at account level; nothing to sum per post.
             return pre;
@@ -78,8 +87,9 @@ export function getImpressions(platform, metrics) {
             // 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);
+            // views == post_media_view (total), reach == unique viewers. Prefer the
+            // total like every other platform; video posts also report video_views.
+            return num(m.views) || num(m.video_views) || num(m.impressions) || num(m.reach);
         case "linkedin":
         case "linkedin_page":
         case "pinterest":
@@ -96,6 +106,11 @@ export function getImpressions(platform, metrics) {
             return num(m.views) || num(m.impressions) || num(m.reach);
     }
 }
+/** Unique accounts reached, when the platform reports it (0 otherwise). */
+export function getReach(platform, metrics) {
+    const m = metrics || {};
+    return num(m.reach) || num(m.unique_impressions) || num(m.members_reached);
+}
 /**
  * Engagement rate as a percentage (0-100), suppressed below the impression
  * floor and capped at 100%.

package/build/tools/analytics.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { formatNumber, capitalize, metricRows, sortMetricLabels } from "../client.js";
+import { formatNumber, capitalize, metricRows, metricBreakdownRows, 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.", {
+    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. TikTok videos also carry average_time_watched, full_video_watched_rate, total_time_watched, favorites and reach when the workspace enabled TikTok comments (Business API authorization).", {
         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."),
     }, async ({ post_id }) => {
         const result = await getClient().getPostAnalytics(post_id);
@@ -55,9 +55,11 @@ export function registerAnalyticsTools(server, getClient) {
             perPlatform.push({
                 platform,
                 rows,
+                breakdowns: metricBreakdownRows(m),
                 engagements,
                 denom,
                 note: typeof m.note === "string" ? m.note : undefined,
+                storySlides: Array.isArray(entry?.story_slides) ? entry.story_slides : undefined,
             });
         }
         if (!totalsByLabel.has("Engagements"))
@@ -87,8 +89,24 @@ export function registerAnalyticsTools(server, getClient) {
                 md += `| **${label}** | ${formatNumber(n)} |\n`;
             }
             md += renderRate(p.engagements, p.denom);
+            for (const [label, text] of p.breakdowns) {
+                md += `| **${label}** | ${text} |\n`;
+            }
             if (p.note)
                 md += `\n_${p.note}_\n`;
+            // Multi-slide stories: the platform table above is the sum; show each
+            // slide on its own so the user can see which slide held attention.
+            if (p.storySlides && p.storySlides.length > 1) {
+                md += `\n_${p.storySlides.length} story slides (totals above are the sum):_\n`;
+                for (const slide of p.storySlides) {
+                    const sm = slide.metrics || {};
+                    const slideRows = metricRows(sm);
+                    md += `\n**Story ${slide.index + 1}**\n\n| Metric | Value |\n|--------|-------|\n`;
+                    for (const [label, n] of slideRows) {
+                        md += `| **${label}** | ${formatNumber(n)} |\n`;
+                    }
+                }
+            }
         }
         return {
             content: [{ type: "text", text: md }],
@@ -127,7 +145,7 @@ export function registerAnalyticsTools(server, getClient) {
                 // 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);
+                likes += (Number(m.likes ?? m.favorites ?? 0) || 0);
                 comments += Number(m.comments ?? m.replies ?? 0);
                 shares += Number(m.shares ?? m.retweets ?? m.reposts ?? 0);
             }
@@ -205,7 +223,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. 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.", {
+    server.tool("get_account_analytics", "Get account-level analytics for connected social accounts: followers, following, posts, and the day values the platform reports for the snapshot date (impressions/views, reach, engagement, profile_views, link_clicks, follows_gained, follows_lost, Google Business calls/direction_requests/website_clicks/average_rating/review_count, Pinterest monthly_views). Rows with day values carry `period: \"daily\"`. Audience objects appear when available: `demographics` (+ demographics_unit) and `online_followers` (UTC hour to followers online). Metric semantics: LinkedIn profile rows keep a lifetime total under `impressions_lifetime` and `period: \"lifetime\"` when no daily breakdown is served. A missing key means the platform does not report it. 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) => {
@@ -240,21 +258,43 @@ export function registerAnalyticsTools(server, getClient) {
                     ? `${formatNumber(m.subscribers)} subs`
                     : "—";
             const details = [];
-            if (m.posts !== undefined)
-                details.push(`${formatNumber(m.posts)} posts`);
-            if (m.following !== undefined)
-                details.push(`${formatNumber(m.following)} following`);
-            if (m.impressions !== undefined)
-                details.push(`${formatNumber(m.impressions)} impressions`);
-            if (m.engagement !== undefined)
-                details.push(`${formatNumber(m.engagement)} engagements`);
-            if (m.total_views !== undefined)
-                details.push(`${formatNumber(m.total_views)} views`);
-            if (m.total_videos !== undefined)
-                details.push(`${m.total_videos} videos`);
+            const ACCOUNT_DETAIL_KEYS = [
+                ["posts", "posts"],
+                ["following", "following"],
+                ["impressions", "views"],
+                ["reach", "reach"],
+                ["engagement", "engagements"],
+                ["profile_views", "profile views"],
+                ["link_clicks", "link clicks"],
+                ["follows_gained", "new followers"],
+                ["follows_lost", "lost followers"],
+                ["accounts_engaged", "accounts engaged"],
+                ["video_views", "video views"],
+                ["watch_time_minutes", "min watched"],
+                ["monthly_views", "monthly views"],
+                ["total_views", "lifetime views"],
+                ["total_videos", "videos"],
+                ["listed", "listed"],
+                ["average_rating", "rating"],
+                ["review_count", "reviews"],
+                ["calls", "calls"],
+                ["direction_requests", "direction requests"],
+                ["website_clicks", "website clicks"],
+                ["bookings", "bookings"],
+                ["mentions", "mentions"],
+            ];
+            for (const [key, label] of ACCOUNT_DETAIL_KEYS) {
+                const v = m[key];
+                if (v === undefined || v === null || !Number.isFinite(Number(v)))
+                    continue;
+                details.push(`${key === "average_rating" ? Number(v).toFixed(1) : formatNumber(Number(v))} ${label}`);
+            }
             if (m.subscribers !== undefined && m.followers !== undefined) {
                 details.push(`${formatNumber(m.subscribers)} subscribers`);
             }
+            if (typeof m.period === "string") {
+                details.push(`(${m.period})`);
+            }
             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.
@@ -269,7 +309,7 @@ export function registerAnalyticsTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("get_best_times", "Get recommended posting times (day + hour) for one platform, computed from the workspace's own posting history: publish time × engagement of every post published there, recency-weighted and outlier-damped, bucketed in the user's timezone. Returns the top 3 recommended slots plus a per-day breakdown. When the workspace has fewer than 15 analyzed posts on the platform, industry-average defaults are returned instead (`basis: defaults`) with how many more posts unlock personalized recommendations — tell the user that so the numbers aren't mistaken for their own audience data. Use this before scheduling when the user asks 'when should I post?' or hasn't specified a time. Requires the analytics:read scope.", {
+    server.tool("get_best_times", "Get recommended posting times (day + hour) for one platform, computed from the workspace's own posting history: publish time × engagement of every post published there, recency-weighted and outlier-damped, bucketed in the user's timezone, and blended with when the account's followers are online when the platform provides that (Instagram, TikTok Business; `basis: own_data_and_audience`, response carries `audience_online`). Returns the top 3 recommended slots plus a per-day breakdown. When the workspace has fewer than 15 analyzed posts on the platform, the audience-online profile alone is used (`basis: audience`) or industry-average defaults are returned (`basis: defaults`) with how many more posts unlock personalized recommendations — tell the user that so the numbers aren't mistaken for their own audience data. Use this before scheduling when the user asks 'when should I post?' or hasn't specified a time. Requires the analytics:read scope.", {
         platform: z.string().describe("Platform identifier, e.g. instagram, tiktok, linkedin, linkedin_page, x, facebook, youtube, pinterest, threads, bluesky, mastodon, google_business"),
         timezone: z.string().optional().describe("IANA timezone for the buckets (e.g. Europe/Amsterdam). Defaults to the account's timezone."),
     }, async (params) => {
@@ -318,6 +358,12 @@ export function registerAnalyticsTools(server, getClient) {
         if (d.basis === "defaults") {
             md += `\n_Not enough posting history on ${platformLabel} yet (${d.sample_size} analyzed post${d.sample_size === 1 ? "" : "s"}). These are cross-industry averages — publish ${d.posts_needed} more post${d.posts_needed === 1 ? "" : "s"} to unlock recommendations from this audience's own data._\n`;
         }
+        else if (d.basis === "audience") {
+            md += `\n_Not enough posting history on ${platformLabel} yet (${d.sample_size} analyzed post${d.sample_size === 1 ? "" : "s"}), so these times come from when this account's followers are online. Publish ${d.posts_needed} more post${d.posts_needed === 1 ? "" : "s"} to blend in your own results._\n`;
+        }
+        else if (d.basis === "own_data_and_audience") {
+            md += `\n_Based on ${d.sample_size} ${platformLabel} posts from the last ${d.window_days} days, blended with when this account's followers are online (metric: ${d.metric}, times in ${d.timezone})._\n`;
+        }
         else {
             md += `\n_Based on ${d.sample_size} ${platformLabel} posts from the last ${d.window_days} days (metric: ${d.metric}, times in ${d.timezone})._\n`;
         }

package/build/tools/posts.js

@@ -131,6 +131,11 @@ const TIKTOK_OPTIONS = z.object({
     brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
     brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
     auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
+    first_comment: z
+        .string()
+        .max(150)
+        .optional()
+        .describe("Text auto-posted as the first comment on the TikTok video right after it publishes (max 150 characters). Requires the workspace's TikTok comments authorization ('Enable comments' on the TikTok channel card); without it first_comment_result is failed with an explanatory error. The video must be public with comments allowed. If TikTok returns the final video id a few minutes after publish, the comment posts automatically once it resolves (first_comment_result.pending is true meanwhile). On update_post pass an empty string to clear it."),
 }).optional().describe("TikTok options");
 const PINTEREST_OPTIONS = z.object({
     board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
@@ -245,7 +250,7 @@ function postAppUrl(p) {
 }
 export function registerPostTools(server, getClient) {
     server.tool("list_posts", "List all posts in the workspace. Optionally filter by status. The content column shows a preview of the default caption; if a post has per-platform overrides (e.g. a custom X version), the preview is suffixed with *(per-platform)* — call `get_post` to see every variant.", {
-        status: z.string().optional().describe("Filter by status: draft, scheduled, published, failed"),
+        status: z.string().optional().describe("Filter by status: draft, in_approval, scheduled, posting, published, failed, warning. in_approval = waiting for a reviewer in an approval workflow."),
         limit: z.string().optional().describe("Max results to return (default: 20)"),
         offset: z.string().optional().describe("Offset for pagination"),
     }, async (params) => {
@@ -450,6 +455,23 @@ export function registerPostTools(server, getClient) {
                 md += `- **${capitalize(platform.replace(/_/g, " "))}**: ${url}\n`;
             }
         }
+        // Multi-slide stories: one story per slide on the platform. Show every
+        // slide's own URL in publish order (published_urls only has slide 1).
+        const storySlides = (p.story_slides && typeof p.story_slides === "object" && !Array.isArray(p.story_slides))
+            ? p.story_slides
+            : {};
+        const slideEntries = Object.entries(storySlides).filter(([, list]) => Array.isArray(list) && list.length > 0);
+        if (slideEntries.length) {
+            md += `\n\n### Story Slides\n\n`;
+            for (const [platform, list] of slideEntries) {
+                md += `**${capitalize(platform.replace(/_/g, " "))}** (${list.length} slide${list.length === 1 ? "" : "s"})\n`;
+                list.forEach((slide, i) => {
+                    const n = (typeof slide.index === "number" ? slide.index : i) + 1;
+                    md += `- Slide ${n}${slide.media_type ? ` (${slide.media_type})` : ""}: ${slide.url || slide.native_post_id || "(no url)"}\n`;
+                });
+                md += `\n`;
+            }
+        }
         // Per-platform publish errors (status failed/warning). Point at
         // retry_post — only the failed platforms are re-published.
         const postErrors = (p.errors && typeof p.errors === "object" && !Array.isArray(p.errors))
@@ -467,7 +489,7 @@ export function registerPostTools(server, getClient) {
         }
         // First comments: nested under each platform object by the API. Show the
         // configured text plus, once published, the outcome (posted/failed/skipped).
-        const firstCommentPlatforms = ["instagram", "facebook", "linkedin", "linkedin_page", "youtube"];
+        const firstCommentPlatforms = ["instagram", "facebook", "linkedin", "linkedin_page", "youtube", "tiktok"];
         const firstCommentRows = [];
         for (const platform of firstCommentPlatforms) {
             const opts = p[platform];
@@ -535,7 +557,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
 2. **Channels**: Which platforms to post to? Use list_accounts to show available options if needed.
 3. **Schedule**: When should it be published? (Or save as draft?)
 4. **Media** (REQUIRED for some types):
-   - Stories: ALWAYS require an image or video. Ask the user which image/video to use. Use list_media to show their uploaded media, or ask for an external URL.
+   - Stories: ALWAYS require an image or video. A story takes 1 to 10 media items: EACH item is one slide and publishes as its own story on Instagram/Facebook, in the order given (more than 10 returns 400). Ask the user which media to use and in what order. Use list_media to show their uploaded media, or ask for external URLs. Story videos are max 60s per slide.
    - Reels: ALWAYS require a video (MP4/MOV) — NOT an image. Passing an image to a Reel returns a 400 validation_error. To share an image, use post_type "Post" instead. Ask the user which video to use; use list_media to find available videos.
    - Instagram posts: ALWAYS require at least one image or video.
    - TikTok posts: ALWAYS require at least one image or video.
@@ -580,7 +602,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             z.array(mediaUrlEntry),
             z.record(z.string(), z.array(mediaUrlEntry)),
         ]).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)"),
+        type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story' (Instagram/Facebook/Snapchat; 1 to 10 media items, each one a slide published in order), '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."),
         link_description: z.string().optional().describe("Optional description for the link-share preview. LinkedIn uses this when set; Facebook auto-fetches the OG description."),
@@ -589,7 +611,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         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. Invited users get an invite in the Instagram app; once they accept, the post also appears on their profile and feed. A leading '@' is stripped; usernames are case-insensitive. Private or non-existent usernames are rejected by Instagram at publish time with a clear error. Ignored by other platforms."),
         user_tags: z.array(USER_TAG_ENTRY).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
         hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. The set's tags are merged in ONCE at create time — tags already in a caption are skipped, and Instagram's 30-hashtag cap returns a clear hashtag_limit_exceeded error. When the user says 'add my usual hashtags', check list_hashtag_sets first."),
-        hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("Where the set's tags land. caption_append (default): appended to each target caption after a blank line. first_comment: posted as the auto first comment on Instagram/Facebook/LinkedIn/LinkedIn Page/YouTube (appended after any explicit first_comment); platforms without a comment API fall back to caption_append. Stories always use captions."),
+        hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("Where the set's tags land. caption_append (default): appended to each target caption after a blank line. first_comment: posted as the auto first comment on Instagram/Facebook/LinkedIn/LinkedIn Page/YouTube/TikTok (TikTok only when the workspace enabled TikTok comments) (appended after any explicit first_comment); platforms without a comment API fall back to caption_append. Stories always use captions."),
         hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to (e.g. [\"instagram\", \"tiktok\"]). Defaults to all selected channels."),
         pinterest: PINTEREST_OPTIONS,
         youtube: z.object({
@@ -702,7 +724,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
 1. **Content/caption**: What text? If captions differ per platform, use one call with an object: { "default": "fallback", "linkedin": "long", "threads": "short" }.
 2. **Channels**: Which platforms? Use list_accounts if needed.
 3. **Media** (REQUIRED for some types — same rules as create_post):
-   - Stories: ALWAYS need an image or video.
+   - Stories: ALWAYS need an image or video. Up to 10 media items; each one is a slide, published as its own story in order.
    - Reels: ALWAYS need a video (MP4/MOV), NOT an image — passing an image returns a 400 validation_error. Use post_type "Post" to share an image.
    - Instagram/TikTok posts: ALWAYS need at least one image or video.
    - Pinterest: ALWAYS need an image + board_id.
@@ -724,7 +746,7 @@ Do NOT call without required media — it will fail.`, {
             z.array(mediaUrlEntry),
             z.record(z.string(), z.array(mediaUrlEntry)),
         ]).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'"),
+        type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story' (1 to 10 media items, each one a slide published in order), '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."),
         user_tags: z.array(USER_TAG_ENTRY).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
@@ -824,7 +846,7 @@ Do NOT call without required media — it will fail.`, {
 **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"),
         content: z.union([z.string(), z.record(z.string(), z.string())]).optional().describe("Updated post caption / body text. For YouTube Shorts this becomes the video description, NOT the title — to rename the Short, use `youtube.title`. String or object with platform keys: { \"default\": \"fallback\", \"linkedin\": \"long\" }."),
-        scheduled_at: z.string().optional().describe("Updated scheduled date (ISO 8601)"),
+        scheduled_at: z.string().optional().describe("Updated scheduled date (ISO 8601, must be in the future). A draft becomes scheduled. A post waiting for approval keeps its in_approval status; only its time moves."),
         channels: z.array(z.string()).optional().describe("Updated channel IDs. Bare platform name or composite `\"<workspace_id>_<platform>\"`; always source from list_accounts for this API key (unknown or mismatched workspace prefixes are rejected as unknown accounts). Note: `linkedin` (personal profile) and `linkedin_page` (company page) are independent channels."),
         media_ids: z.union([
             z.array(mediaIdEntry),
@@ -1039,7 +1061,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. 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 for most platforms, so expect a few seconds of latency; X results may come from a snapshot up to 24h old (X bills per returned post) — the snapshot refreshes right after the user publishes to X through OmniSocials. 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; TikTok: average_time_watched/full_video_watched_rate/total_time_watched/favorites/reach when the workspace enabled TikTok comments). 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 for most platforms, so expect a few seconds of latency; X results may come from a snapshot up to 24h old (X bills per returned post) — the snapshot refreshes right after the user publishes to X through OmniSocials. 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()

package/build/types.d.ts

@@ -103,6 +103,17 @@ export interface ApiInstagramOptionsOut extends ApiPlatformOptionsOut {
     thumb_offset?: number | string;
     cover_url?: string;
 }
+export interface ApiStorySlide {
+    /** Zero-based slide position. */
+    index?: number;
+    /** The slide's story id on the platform. */
+    native_post_id?: string;
+    /** Story URL (valid for 24 hours). */
+    url?: string | null;
+    media_url?: string | null;
+    media_type?: "image" | "video" | string | null;
+    published_at?: string | null;
+}
 export interface ApiPost {
     id: string;
     /** DB "posted" is mapped to "published" by the serializer. */
@@ -130,6 +141,9 @@ export interface ApiPost {
     app_url?: string;
     /** platform → live URL for each platform that successfully published. */
     published_urls?: Record<string, string>;
+    /** Stories only, after publishing: every slide per platform in publish
+     * order. `published_urls` keeps only the first slide's URL. */
+    story_slides?: Record<string, ApiStorySlide[]>;
     /** Set on a retry post: the original failed post's id. */
     retry_of?: string;
     /** Set on the original post: ids of its retry posts. */
@@ -447,18 +461,32 @@ export interface BestTimesResult {
     metric?: string;
     window_days?: number;
     sample_size?: number;
-    basis?: "own_data" | "defaults";
+    basis?: "own_data" | "own_data_and_audience" | "audience" | "defaults";
+    /** Hour (0-23, response timezone) -> followers online. */
+    audience_online?: Record<string, number>;
+    audience_online_date?: string;
     posts_needed?: number;
     /** Absent on the defaults basis. */
     grid?: BestTimeGridCell[];
     recommendations?: BestTimeRecommendation[];
 }
+export interface PostAnalyticsStorySlide {
+    /** Zero-based slide position. */
+    index: number;
+    /** The slide's own story id on the platform. */
+    platform_post_id: string;
+    metrics: Record<string, number | string>;
+    collected_at: string;
+}
 export interface PostAnalyticsPlatformEntry {
     platform: string;
     platform_post_id: string;
     metrics: Record<string, number | string>;
     thread_parts: number;
     collected_at: string;
+    /** Multi-slide stories only: per-slide metrics in publish order (the
+     * parent `metrics` is the sum across slides). */
+    story_slides?: PostAnalyticsStorySlide[];
 }
 export interface PostAnalytics {
     post_id: string;

package/package.json

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