@omnisocials/mcp-server 1.19.0 → 1.20.1

package/README.md

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

package/build/client.d.ts

@@ -1,4 +1,4 @@
-import type { ApiResponse, MediaItem, PdfUploadResult, InboxConversation, InboxMessage } from "./types.js";
+import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, AudioSearchResult, BestTimesResult, HashtagSet, LocationSearchResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, InboxConversation, InboxMessage, Webhook } from "./types.js";
 export declare function fetchImageAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
@@ -100,6 +100,45 @@ export interface MastodonPostOptions {
 export interface MastodonPostOptionsUpdate {
     thread_parts?: MastodonThreadPartInput[] | null;
 }
+/**
+ * Request body for POST /posts/create. `createAndPublishPost` accepts the
+ * same shape minus `scheduled_at` (publishing is immediate).
+ */
+export interface CreatePostInput {
+    content: string | Record<string, string>;
+    channels?: string[];
+    scheduled_at?: string;
+    media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
+    media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
+    type?: string;
+    source?: string;
+    link_url?: string;
+    link_title?: string;
+    link_description?: string;
+    link_thumbnail_url?: string;
+    location_id?: string;
+    collaborators?: string[];
+    user_tags?: Array<{
+        username: string;
+        x: number;
+        y: number;
+        image_index?: number;
+    }>;
+    pinterest?: Record<string, unknown>;
+    youtube?: Record<string, unknown>;
+    instagram?: Record<string, unknown>;
+    facebook?: Record<string, unknown>;
+    linkedin?: Record<string, unknown>;
+    linkedin_page?: Record<string, unknown>;
+    tiktok?: Record<string, unknown>;
+    x?: XPostOptions;
+    bluesky?: BlueskyPostOptions;
+    mastodon?: MastodonPostOptions;
+    google_business?: Record<string, unknown>;
+    hashtag_set?: string;
+    hashtag_placement?: "caption_append" | "first_comment";
+    hashtag_platforms?: string[];
+}
 export declare class OmniSocialsClient {
     private baseUrl;
     private apiKey;
@@ -109,81 +148,20 @@ export declare class OmniSocialsClient {
         status?: string;
         limit?: string;
         offset?: string;
-    }): Promise<ApiResponse<unknown>>;
-    getPost(id: string): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<ApiPost[]>>;
+    getPost(id: string): Promise<ApiResponse<ApiPost>>;
     getRecentPlatformPosts(params?: {
         limit?: string;
         platforms?: string;
-    }): Promise<ApiResponse<unknown>>;
-    createPost(data: {
-        content: string | Record<string, string>;
-        channels?: string[];
-        scheduled_at?: string;
-        media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
-        media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
-        type?: string;
-        source?: string;
-        link_url?: string;
-        link_title?: string;
-        link_description?: string;
-        link_thumbnail_url?: string;
-        location_id?: string;
-        collaborators?: string[];
-        user_tags?: Array<{
-            username: string;
-            x: number;
-            y: number;
-            image_index?: number;
-        }>;
-        pinterest?: Record<string, unknown>;
-        youtube?: Record<string, unknown>;
-        instagram?: Record<string, unknown>;
-        facebook?: Record<string, unknown>;
-        linkedin?: Record<string, unknown>;
-        linkedin_page?: Record<string, unknown>;
-        tiktok?: Record<string, unknown>;
-        x?: XPostOptions;
-        bluesky?: BlueskyPostOptions;
-        mastodon?: MastodonPostOptions;
-        google_business?: Record<string, unknown>;
-        hashtag_set?: string;
-        hashtag_placement?: "caption_append" | "first_comment";
-        hashtag_platforms?: string[];
-    }): Promise<ApiResponse<unknown>>;
-    createAndPublishPost(data: {
-        content: string | Record<string, string>;
-        channels?: string[];
-        media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
-        media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
-        type?: string;
-        source?: string;
-        link_url?: string;
-        link_title?: string;
-        link_description?: string;
-        link_thumbnail_url?: string;
-        location_id?: string;
-        collaborators?: string[];
-        user_tags?: Array<{
-            username: string;
-            x: number;
-            y: number;
-            image_index?: number;
-        }>;
-        pinterest?: Record<string, unknown>;
-        youtube?: Record<string, unknown>;
-        instagram?: Record<string, unknown>;
-        facebook?: Record<string, unknown>;
-        linkedin?: Record<string, unknown>;
-        linkedin_page?: Record<string, unknown>;
-        tiktok?: Record<string, unknown>;
-        x?: XPostOptions;
-        bluesky?: BlueskyPostOptions;
-        mastodon?: MastodonPostOptions;
-        google_business?: Record<string, unknown>;
-        hashtag_set?: string;
-        hashtag_placement?: "caption_append" | "first_comment";
-        hashtag_platforms?: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<RecentPlatformPost[]> & {
+        count?: number;
+        connected_platforms?: string[];
+        errors?: Record<string, string>;
+        note?: string;
+        current_date?: string;
+    }>;
+    createPost(data: CreatePostInput): Promise<ApiResponse<ApiPost>>;
+    createAndPublishPost(data: Omit<CreatePostInput, "scheduled_at">): Promise<ApiResponse<ApiPost>>;
     updatePost(id: string, data: {
         content?: string | Record<string, string>;
         scheduled_at?: string;
@@ -210,26 +188,26 @@ export declare class OmniSocialsClient {
         bluesky?: BlueskyPostOptionsUpdate;
         mastodon?: MastodonPostOptionsUpdate;
         google_business?: Record<string, unknown>;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<ApiPost>>;
     deletePost(id: string): Promise<ApiResponse<unknown>>;
-    publishPost(id: string): Promise<ApiResponse<unknown>>;
-    retryPost(id: string): Promise<ApiResponse<unknown>>;
-    searchLocations(query: string): Promise<ApiResponse<unknown>>;
+    publishPost(id: string): Promise<ApiResponse<PublishPostResult>>;
+    retryPost(id: string): Promise<ApiResponse<RetryPostResult>>;
+    searchLocations(query: string): Promise<LocationSearchResult>;
     validateLocation(id: string): Promise<ApiResponse<unknown>>;
-    searchInstagramAudio(query?: string, type?: "music" | "original_sound"): Promise<ApiResponse<unknown>>;
+    searchInstagramAudio(query?: string, type?: "music" | "original_sound"): Promise<AudioSearchResult>;
     listMedia(params?: {
         limit?: string;
         offset?: string;
         search?: string;
         folder_id?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaItem[]>>;
     uploadMedia(data: {
         url: string;
         filename?: string;
         name?: string;
         folder?: string;
     }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
-        compatibility?: unknown;
+        compatibility?: MediaCompatibility;
         message?: string;
     }>;
     uploadMediaFromBase64(data: {
@@ -239,7 +217,7 @@ export declare class OmniSocialsClient {
         name?: string;
         folder?: string;
     }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
-        compatibility?: unknown;
+        compatibility?: MediaCompatibility;
         message?: string;
     }>;
     /**
@@ -252,57 +230,73 @@ export declare class OmniSocialsClient {
         media_id?: string;
         size_bytes?: number;
         mime?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<MediaCheckResult>;
     deleteMedia(id: string): Promise<ApiResponse<unknown>>;
     updateMedia(id: string, data: {
         name?: string;
         folder_id?: string | null;
-    }): Promise<ApiResponse<unknown>>;
-    listFolders(): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaItem>>;
+    listFolders(): Promise<ApiResponse<MediaFolder[]>>;
     createFolder(data: {
         name: string;
         parent_id?: string;
-    }): Promise<ApiResponse<unknown>>;
-    listHashtagSets(): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaFolder>>;
+    listHashtagSets(): Promise<ApiResponse<HashtagSet[]>>;
     createHashtagSet(data: {
         name: string;
         hashtags: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<HashtagSet>>;
     updateHashtagSet(id: string, data: {
         name?: string;
         hashtags?: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<HashtagSet>>;
     deleteHashtagSet(id: string): Promise<ApiResponse<unknown>>;
-    listAccounts(): Promise<ApiResponse<unknown>>;
-    getAccount(id: string): Promise<ApiResponse<unknown>>;
-    getPostAnalytics(postId: string): Promise<ApiResponse<unknown>>;
-    getPostsAnalytics(postIds: string[]): Promise<ApiResponse<unknown>>;
+    listAccounts(): Promise<ApiResponse<Account[]> & {
+        workspace_id?: number | string | null;
+        workspace_name?: string | null;
+        workspace_icon?: string | null;
+    }>;
+    getAccount(id: string): Promise<ApiResponse<Account>>;
+    getPostAnalytics(postId: string): Promise<ApiResponse<PostAnalytics>>;
+    getPostsAnalytics(postIds: string[]): Promise<ApiResponse<PostAnalytics[]>>;
     getAnalyticsOverview(params?: {
         period?: string;
         start_date?: string;
         end_date?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<AnalyticsOverview> & {
+        period?: string;
+        start_date?: string;
+        end_date?: string;
+        current_date?: string;
+    }>;
     getAccountAnalytics(params?: {
         platform?: string;
         date?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<AccountAnalyticsEntry[]> & {
+        date?: string;
+    }>;
     getBestTimes(params: {
         platform: string;
         timezone?: string;
-    }): Promise<ApiResponse<unknown>>;
-    listWebhooks(): Promise<ApiResponse<unknown>>;
+    }): Promise<BestTimesResult>;
+    listWebhooks(): Promise<ApiResponse<Webhook[]>>;
     createWebhook(data: {
         url: string;
         events: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<Webhook & {
+        secret: string;
+    }>>;
     deleteWebhook(id: string): Promise<ApiResponse<unknown>>;
-    getWebhook(id: string): Promise<ApiResponse<unknown>>;
+    getWebhook(id: string): Promise<ApiResponse<Webhook>>;
     updateWebhook(id: string, data: {
         url?: string;
         events?: string[];
         is_active?: boolean;
-    }): Promise<ApiResponse<unknown>>;
-    rotateWebhookSecret(id: string): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<Webhook>>;
+    rotateWebhookSecret(id: string): Promise<ApiResponse<{
+        id: string;
+        secret: string;
+    }>>;
     listInboxConversations(params?: {
         platform?: string;
         type?: string;

package/build/client.js

@@ -201,6 +201,8 @@ export class OmniSocialsClient {
     // Recent posts fetched live from the connected platform APIs (including
     // content published outside OmniSocials). The fallback for brand-new
     // workspaces where listPosts is empty. Requires the analytics:read scope.
+    // `connected_platforms`/`errors`/`note`/`current_date` ride top-level on the
+    // envelope (backend/routes/api/v1/posts.js recent-platform route).
     async getRecentPlatformPosts(params) {
         return this.request("GET", "/posts/recent-platform", undefined, params);
     }
@@ -224,14 +226,17 @@ export class OmniSocialsClient {
     async retryPost(id) {
         return this.request("POST", `/posts/${id}/retry`);
     }
-    // Locations (Instagram place tagging)
+    // Locations (Instagram place tagging). NOT the standard envelope — see
+    // LocationSearchResult (degraded-path `error` is a plain string).
     async searchLocations(query) {
-        return this.request("GET", "/locations/search", undefined, { q: query });
+        return this.request("GET", "/locations/search", undefined, {
+            q: query,
+        });
     }
     async validateLocation(id) {
         return this.request("GET", "/locations/validate", undefined, { id });
     }
-    // Audio (Instagram Reel music)
+    // Audio (Instagram Reel music). Same nonstandard string-`error` envelope.
     async searchInstagramAudio(query, type) {
         const params = {};
         if (query)
@@ -262,6 +267,7 @@ export class OmniSocialsClient {
      * or `size_bytes` + `mime`.
      */
     async checkMediaCompatibility(data) {
+        // Nonstandard envelope: compatibility fields ride top-level, no `data`.
         return this.request("POST", "/media/check", data);
     }
     async deleteMedia(id) {
@@ -290,7 +296,9 @@ export class OmniSocialsClient {
     async deleteHashtagSet(id) {
         return this.request("DELETE", `/hashtag-sets/${id}`);
     }
-    // Accounts
+    // Accounts. Alongside `data`, the list response carries the workspace's
+    // identity top-level (backend/routes/api/v1/accounts.js) — the workspaces
+    // tool reads it to label multi-workspace setups.
     async listAccounts() {
         return this.request("GET", "/accounts");
     }
@@ -308,12 +316,18 @@ export class OmniSocialsClient {
             ids: postIds.join(","),
         });
     }
+    // The resolved range and today's date ride top-level on the envelope
+    // (backend/routes/api/v1/analytics.js overview route) so clients can render
+    // an accurate "as of <today>" line.
     async getAnalyticsOverview(params) {
         return this.request("GET", "/analytics/overview", undefined, params);
     }
+    // The resolved `date` rides top-level on the envelope.
     async getAccountAnalytics(params) {
         return this.request("GET", "/analytics/accounts", undefined, params);
     }
+    // Nonstandard envelope: the result object is returned top-level, no `data`
+    // (backend/routes/api/v1/analytics.js best-times route).
     async getBestTimes(params) {
         return this.request("GET", "/analytics/best-times", undefined, params);
     }
@@ -321,6 +335,7 @@ export class OmniSocialsClient {
     async listWebhooks() {
         return this.request("GET", "/webhooks");
     }
+    // The signing secret is only ever returned at creation time.
     async createWebhook(data) {
         return this.request("POST", "/webhooks", data);
     }
@@ -333,6 +348,8 @@ export class OmniSocialsClient {
     async updateWebhook(id, data) {
         return this.request("PATCH", `/webhooks/${id}`, data);
     }
+    // Returns only { id, secret } — not the full webhook
+    // (backend/routes/api/v1/webhooks.js rotate-secret route).
     async rotateWebhookSecret(id) {
         return this.request("POST", `/webhooks/${id}/rotate-secret`);
     }

package/build/index.js

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

package/build/metrics.d.ts

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

package/build/metrics.js

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

package/build/tools/accounts.js

@@ -8,7 +8,7 @@ export function registerAccountTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const accounts = Array.isArray(result.data) ? result.data : result.data?.accounts || [];
+        const accounts = Array.isArray(result.data) ? result.data : [];
         if (!accounts.length) {
             return {
                 content: [{ type: "text", text: "No connected accounts found." }],
@@ -42,7 +42,7 @@ export function registerAccountTools(server, getClient) {
         // Fetch profile pictures
         const content = [];
         const imagePromises = accounts
-            .filter((a) => a.profile_picture)
+            .filter((a) => !!a.profile_picture)
             .slice(0, 6)
             .map(async (a) => {
             const img = await fetchImageAsBase64(a.profile_picture);