@omnisocials/mcp-server 1.34.1 → 1.35.0

package/build/client.d.ts

@@ -1,4 +1,4 @@
-import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, AudioSearchResult, BestTimesResult, HashtagSet, LocationSearchResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, ApprovePostResult, RejectPostResult, InboxConversation, InboxDeleteResult, InboxMessage, InboxNextUnanswered, Webhook } from "./types.js";
+import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, ApiVideoCover, AudioSearchResult, BestTimesResult, HashtagSet, LocationSearchResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, ApprovePostResult, RejectPostResult, InboxConversation, InboxDeleteResult, InboxMessage, InboxNextUnanswered, Webhook } from "./types.js";
 export declare function fetchImageAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
@@ -168,6 +168,8 @@ export interface CreatePostInput {
         y: number;
         image_index?: number;
     }>;
+    /** Video thumbnail: { type: "frame"|"custom", thumb_offset?, cover_url?, overrides? }. */
+    video_cover?: ApiVideoCover;
     pinterest?: Record<string, unknown>;
     youtube?: Record<string, unknown>;
     instagram?: Record<string, unknown>;
@@ -248,6 +250,7 @@ export declare class OmniSocialsClient {
             y: number;
             image_index?: number;
         }>;
+        video_cover?: ApiVideoCover | null;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;

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.34.1",
+    version: "1.35.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,8 +16,14 @@ 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;
+/** Unique accounts reached; null when the platform did not report it. */
+export declare function getReach(platform: string, metrics: Metrics): number | null;
+/** Post-level metrics a platform can never report: platform -> metric key -> reason. */
+export declare const UNSUPPORTED_POST_METRICS: Record<string, Record<string, string>>;
+/** Reason `metricKey` is unavailable on `platform`, or null when it is available. */
+export declare function unsupportedMetricReason(platform: string, metricKey: string): string | null;
+/** True when the platform can never report `metricKey`; a finite stored value overrides the map. */
+export declare function isMetricUnsupported(platform: string, metricKey: string, metrics?: Metrics): boolean;
 /**
  * Engagement rate as a percentage (0-100), suppressed below the impression
  * floor and capped at 100%.

package/build/metrics.js

@@ -106,10 +106,101 @@ 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). */
+// Finite number or null: a missing key stays "no data", never 0.
+const finiteOrNull = (v) => {
+    if (v === null || v === undefined || v === "")
+        return null;
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+/** Unique accounts reached; null when the platform did not report it. */
 export function getReach(platform, metrics) {
     const m = metrics || {};
-    return num(m.reach) || num(m.unique_impressions) || num(m.members_reached);
+    for (const key of ["reach", "unique_impressions", "members_reached"]) {
+        const v = finiteOrNull(m[key]);
+        if (v !== null)
+            return v;
+    }
+    return null;
+}
+/** Post-level metrics a platform can never report: platform -> metric key -> reason. */
+export const UNSUPPORTED_POST_METRICS = {
+    x: {
+        reach: "X does not report reach, only impressions.",
+    },
+    facebook: {
+        saves: "Facebook does not report saves.",
+    },
+    instagram: {
+        clicks: "Instagram reports link clicks for stories only (link sticker taps).",
+        link_clicks: "Instagram reports link clicks for stories only (link sticker taps).",
+    },
+    linkedin_page: {
+        link_clicks: "LinkedIn Pages report total clicks only, not link clicks separately.",
+        saves: "LinkedIn Pages do not report saves.",
+    },
+    threads: {
+        reach: "Threads does not report reach for posts.",
+        clicks: "Threads reports link clicks at account level only, not per post.",
+        link_clicks: "Threads reports link clicks at account level only, not per post.",
+        saves: "Threads does not report saves.",
+    },
+    youtube: {
+        reach: "YouTube does not report reach, only views.",
+        clicks: "YouTube does not report clicks.",
+        link_clicks: "YouTube does not report clicks.",
+        saves: "YouTube does not report saves.",
+    },
+    tiktok: {
+        clicks: "TikTok reports bio link clicks at account level only, not per video.",
+        link_clicks: "TikTok reports bio link clicks at account level only, not per video.",
+    },
+    pinterest: {
+        reach: "Pinterest does not report reach, only impressions.",
+        shares: "Pinterest does not report shares.",
+    },
+    bluesky: {
+        impressions: "Bluesky does not report impressions or views.",
+        reach: "Bluesky does not report reach.",
+        clicks: "Bluesky does not report clicks.",
+        link_clicks: "Bluesky does not report clicks.",
+        video_views: "Bluesky does not report video views.",
+        engagement_rate: "Engagement rate needs impressions, which Bluesky does not report.",
+    },
+    mastodon: {
+        impressions: "Mastodon does not report impressions or views.",
+        reach: "Mastodon does not report reach.",
+        clicks: "Mastodon does not report clicks.",
+        link_clicks: "Mastodon does not report clicks.",
+        saves: "Mastodon does not report saves.",
+        video_views: "Mastodon does not report video views.",
+        engagement_rate: "Engagement rate needs impressions, which Mastodon does not report.",
+    },
+    google_business: {
+        impressions: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        reach: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        likes: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        comments: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        shares: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        saves: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        clicks: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        link_clicks: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        video_views: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        engagement: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        engagement_rate: "Google discontinued per-post metrics for Business Profiles in 2023.",
+    },
+};
+/** Reason `metricKey` is unavailable on `platform`, or null when it is available. */
+export function unsupportedMetricReason(platform, metricKey) {
+    return UNSUPPORTED_POST_METRICS[platform]?.[metricKey] ?? null;
+}
+/** True when the platform can never report `metricKey`; a finite stored value overrides the map. */
+export function isMetricUnsupported(platform, metricKey, metrics) {
+    if (!unsupportedMetricReason(platform, metricKey))
+        return false;
+    if (metrics && finiteOrNull(metrics[metricKey]) !== null)
+        return false;
+    return true;
 }
 /**
  * Engagement rate as a percentage (0-100), suppressed below the impression

package/build/tools/analytics.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 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. 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).", {
+    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post. Renders every metric the platform reported per platform: impressions, reach, views, saves, likes, comments, shares, clicks, link_clicks, engagements, and more. A missing key means the platform does not report it: reach is absent (not 0) on X, Pinterest, YouTube, Threads, Bluesky and Mastodon; link_clicks (clicks on links in the post) exists for X posts under 30 days, LinkedIn profile, Facebook feed posts, Pinterest and Instagram stories, while clicks is the platform's broadest click count. 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."),
     }, { title: "Get Post Analytics", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ post_id }) => {
         const result = await getClient().getPostAnalytics(post_id);

package/build/tools/posts.js

@@ -60,9 +60,35 @@ const FACEBOOK_OPTIONS = z
         .max(8000)
         .optional()
         .describe("Text auto-posted as the first comment on the Facebook post right after it publishes. Page posts only (the API cannot comment on personal-profile posts). Not posted for Stories."),
+    thumbnail_type: z
+        .enum(["from-video", "from-library"])
+        .nullable()
+        .optional()
+        .describe("Video thumbnail for Facebook feed videos and reels: 'from-video' uses the frame at thumb_offset, 'from-library' uploads the image at cover_url. Applied after the video is live; a thumbnail failure never fails the post. On update_post, null removes the Facebook override."),
+    thumb_offset: z
+        .number()
+        .optional()
+        .describe("Frame timestamp in MILLISECONDS from the start of the video (e.g. 3000 = 0:03). Used with thumbnail_type 'from-video'."),
+    cover_url: z
+        .string()
+        .optional()
+        .describe("Custom thumbnail image URL (JPEG/PNG, max 10 MB). Used with thumbnail_type 'from-library'."),
 })
     .optional()
     .describe("Facebook options");
+const VIDEO_COVER_ENTRY = z.object({
+    type: z.enum(["frame", "custom"]).describe("'frame' uses the video frame at thumb_offset; 'custom' uploads the image at cover_url."),
+    thumb_offset: z.number().int().min(0).optional().describe("Milliseconds into the video (type 'frame'). 3000 = 0:03."),
+    cover_url: z.string().optional().describe("Public image URL, JPEG or PNG (type 'custom')."),
+});
+const VIDEO_COVER_OPTIONS = VIDEO_COVER_ENTRY.extend({
+    overrides: z
+        .record(z.string(), VIDEO_COVER_ENTRY.nullable())
+        .optional()
+        .describe("Per-platform overrides keyed by platform id (instagram, facebook, linkedin, linkedin_page, tiktok, pinterest, youtube). An override wins over the base cover for that platform."),
+})
+    .optional()
+    .describe("Video thumbnail for a post whose media is ONE video. Applied on Instagram (feed videos and reels), Facebook (feed videos and reels), LinkedIn Profile and Page, TikTok, Pinterest and YouTube Shorts. TikTok only takes a frame: a 'custom' cover is skipped there, so add a tiktok override with type 'frame' when the user wants a specific TikTok frame. The per-platform reel fields (instagram.thumb_offset / cover_url, tiktok.video_cover_timestamp_ms, pinterest.video_cover) keep working and win over the base cover for their platform. get_post reads it back as `video_cover`.");
 const LINKEDIN_OPTIONS = z
     .object({
     first_comment: z
@@ -601,6 +627,36 @@ export function registerPostTools(server, getClient) {
             optionRows.push(["Pinterest title", pin.title]);
         if (typeof pin.link === "string" && pin.link)
             optionRows.push(["Pinterest link", pin.link]);
+        // Cross-platform video cover (base + per-platform overrides).
+        const describeCover = (c) => {
+            if (!c || typeof c !== "object")
+                return null;
+            const entry = c;
+            if (entry.type === "frame") {
+                const ms = Number(entry.thumb_offset) || 0;
+                return `video frame at ${ms} ms (${(ms / 1000).toFixed(1)}s into the video)`;
+            }
+            if (entry.type === "custom" && typeof entry.cover_url === "string")
+                return `custom image ${entry.cover_url}`;
+            return null;
+        };
+        const vc = p.video_cover;
+        const baseCover = describeCover(vc);
+        if (baseCover)
+            optionRows.push(["Video cover", baseCover]);
+        const coverOverrides = vc && typeof vc === "object" ? vc.overrides : null;
+        if (coverOverrides && typeof coverOverrides === "object") {
+            for (const [platform, entry] of Object.entries(coverOverrides)) {
+                const text = describeCover(entry);
+                if (text)
+                    optionRows.push([`Video cover (${platform})`, text]);
+            }
+        }
+        const fbCoverMs = Number(p.facebook?.thumb_offset) || 0;
+        const fbCoverUrl = p.facebook?.cover_url;
+        if (!coverOverrides?.facebook && (fbCoverMs > 0 || typeof fbCoverUrl === "string")) {
+            optionRows.push(["Facebook cover", typeof fbCoverUrl === "string" ? `custom image ${fbCoverUrl}` : `video frame at ${fbCoverMs} ms`]);
+        }
         if (optionRows.length) {
             md += `\n\n### Platform Options\n\n| Option | Value |\n|--------|-------|\n`;
             for (const [k, v] of optionRows)
@@ -714,6 +770,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         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/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."),
+        video_cover: VIDEO_COVER_OPTIONS,
         pinterest: PINTEREST_OPTIONS,
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. Falls back to \"YouTube Short\" when omitted."),
@@ -871,6 +928,7 @@ Do NOT call without required media — it will fail.`, {
         hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. Tags are merged in once at create time; tags already in a caption are skipped."),
         hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("caption_append (default) appends tags to the captions; first_comment posts them as the auto first comment on comment-capable platforms (others fall back to caption)."),
         hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to. Defaults to all selected channels."),
+        video_cover: VIDEO_COVER_OPTIONS,
         pinterest: PINTEREST_OPTIONS,
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube."),
@@ -985,6 +1043,7 @@ Do NOT call without required media — it will fail.`, {
         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(USER_TAG_ENTRY).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). Replaces the existing tag list. Send an empty array to clear. For carousels set image_index per tag. Ignored by other platforms."),
+        video_cover: VIDEO_COVER_OPTIONS.nullable().describe("Replaces the stored video cover wholesale; pass null to remove it; omit to leave it untouched. facebook.thumbnail_type / thumb_offset / cover_url merge into overrides.facebook on their own."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. To change the Short's title on an existing draft, set this — do NOT use `content` (which is the description)."),
             tags: z.array(z.string()).optional(),

package/build/types.d.ts

@@ -138,6 +138,21 @@ export interface ApiInstagramOptionsOut extends ApiPlatformOptionsOut {
     thumb_offset?: number | string;
     cover_url?: string;
 }
+/** One video-cover choice: a frame offset or a custom image. */
+export interface ApiVideoCoverEntry {
+    type: "frame" | "custom";
+    /** Milliseconds into the video (type "frame"). */
+    thumb_offset?: number;
+    /** Public image URL (type "custom"). */
+    cover_url?: string;
+}
+/** Cross-platform video cover as stored on the post (`video_cover`). On
+ * input, a `null` override entry drops that platform's override; the API
+ * never echoes nulls back. */
+export interface ApiVideoCover extends ApiVideoCoverEntry {
+    /** Per-platform overrides keyed by platform id; an override wins for that platform. */
+    overrides?: Record<string, ApiVideoCoverEntry | null>;
+}
 export interface ApiStorySlide {
     /** Zero-based slide position. */
     index?: number;
@@ -179,6 +194,8 @@ export interface ApiPost {
     /** 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[]>;
+    /** Video thumbnail (base + per-platform overrides); null when none was chosen. */
+    video_cover?: ApiVideoCover | null;
     /** Set on a retry post: the original failed post's id. */
     retry_of?: string;
     /** Set on the original post: ids of its retry posts. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnisocials/mcp-server",
-  "version": "1.34.1",
+  "version": "1.35.0",
   "mcpName": "io.github.omnisocials/mcp-server",
   "description": "MCP server for OmniSocials API - manage social media posts, media, accounts, analytics, and webhooks",
   "type": "module",