@omnisocials/mcp-server 1.19.0 → 1.20.1

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."),
@@ -16,7 +17,7 @@ export function registerAnalyticsTools(server, getClient) {
         // (thread posts publish as a chain), so we just total across platforms here.
         // The legacy flat shape (d.impressions / d.platform_stats) doesn't exist on
         // this endpoint and reading those keys returned "—" for every field.
-        const platforms = d?.platforms || {};
+        const platforms = d?.platforms ?? {};
         const platformEntries = Object.entries(platforms);
         if (platformEntries.length === 0) {
             return {
@@ -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`;
@@ -103,27 +110,26 @@ export function registerAnalyticsTools(server, getClient) {
         // API returns { data: [{ post_id, platforms: { <platform>: { metrics } } }] }.
         // Per-platform metrics are already thread-summed server-side; collapse each
         // post's per-platform metrics into totals, mirroring get_post_analytics.
-        const entries = result.data || [];
+        const entries = result.data ?? [];
         const rows = entries.map((entry) => {
-            const platforms = entry?.platforms || {};
+            const platforms = entry?.platforms ?? {};
             const platformEntries = Object.entries(platforms);
             let impressions = 0;
             let engagements = 0;
             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,
@@ -161,6 +167,11 @@ export function registerAnalyticsTools(server, getClient) {
             };
         }
         const d = result.data;
+        if (!d) {
+            return {
+                content: [{ type: "text", text: "No analytics overview data returned." }],
+            };
+        }
         const resolvedStart = result.start_date;
         const resolvedEnd = result.end_date;
         const currentDate = result.current_date;
@@ -183,8 +194,7 @@ export function registerAnalyticsTools(server, getClient) {
             md += `|----------|-------|-------------|-------------|----------|\n`;
             // Sort by impressions descending
             const sorted = Object.entries(d.platform_breakdown).sort((a, b) => (b[1].total_impressions || 0) - (a[1].total_impressions || 0));
-            for (const [platform, stats] of sorted) {
-                const s = stats;
+            for (const [platform, s] of sorted) {
                 const rate = s.engagement_rate !== undefined
                     ? `${s.engagement_rate.toFixed(2)}%`
                     : "—";
@@ -195,7 +205,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 +231,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 +256,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 }],
@@ -261,7 +280,10 @@ export function registerAnalyticsTools(server, getClient) {
             };
         }
         const d = result;
-        let md = `## Best times to post — ${capitalize(d.platform)} (${d.timezone})\n\n`;
+        // On success the service always returns platform/timezone; params is the
+        // typed fallback so the label never renders "undefined".
+        const platformLabel = capitalize(d.platform || params.platform);
+        let md = `## Best times to post — ${platformLabel} (${d.timezone})\n\n`;
         md += `**Top slots:**\n`;
         (d.recommendations || []).forEach((r, i) => {
             const extras = [];
@@ -294,10 +316,10 @@ export function registerAnalyticsTools(server, getClient) {
             md += `\n### Best hours per day (score 0-100)\n\n| Day | Best hours |\n|-----|------------|\n${dayRows.join("\n")}\n`;
         }
         if (d.basis === "defaults") {
-            md += `\n_Not enough posting history on ${capitalize(d.platform)} 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`;
+            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 {
-            md += `\n_Based on ${d.sample_size} ${capitalize(d.platform)} posts from the last ${d.window_days} days (metric: ${d.metric}, times in ${d.timezone})._\n`;
+            md += `\n_Based on ${d.sample_size} ${platformLabel} posts from the last ${d.window_days} days (metric: ${d.metric}, times in ${d.timezone})._\n`;
         }
         return {
             content: [{ type: "text", text: md }],

package/build/tools/hashtag-sets.js

@@ -7,7 +7,7 @@ export function registerHashtagSetTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const sets = Array.isArray(result.data) ? result.data : result.data?.data || [];
+        const sets = Array.isArray(result.data) ? result.data : [];
         if (!sets.length) {
             return {
                 content: [{ type: "text", text: "No hashtag sets yet. Create one with create_hashtag_set." }],
@@ -36,6 +36,11 @@ export function registerHashtagSetTools(server, getClient) {
             };
         }
         const s = result.data;
+        if (!s) {
+            return {
+                content: [{ type: "text", text: "Hashtag set created, but the API returned no details. List it with list_hashtag_sets." }],
+            };
+        }
         return {
             content: [{
                     type: "text",
@@ -55,6 +60,11 @@ export function registerHashtagSetTools(server, getClient) {
             };
         }
         const s = result.data;
+        if (!s) {
+            return {
+                content: [{ type: "text", text: "Hashtag set updated, but the API returned no details. List it with list_hashtag_sets." }],
+            };
+        }
         return {
             content: [{
                     type: "text",

package/build/tools/inbox.js

@@ -4,11 +4,12 @@ const PLATFORM_EMOJI = {
     instagram: "📸",
     facebook: "📘",
     linkedin: "💼",
+    x: "🐦",
 };
 export function registerInboxTools(server, getClient) {
-    server.tool("list_inbox_conversations", "List social inbox conversations (Instagram/Facebook DMs, comments, mentions, and LinkedIn company-page comments/mentions), newest activity first. Cursor-paginated: pass the returned cursor to get the next page.", {
+    server.tool("list_inbox_conversations", "List social inbox conversations (Instagram/Facebook DMs, comments, mentions, LinkedIn company-page comments/mentions, and X DMs where the workspace has opted into X DMs), newest activity first. Cursor-paginated: pass the returned cursor to get the next page.", {
         platform: z
-            .enum(["instagram", "facebook", "linkedin"])
+            .enum(["instagram", "facebook", "linkedin", "x"])
             .optional()
             .describe("Filter to one platform"),
         type: z
@@ -136,7 +137,7 @@ export function registerInboxTools(server, getClient) {
             ],
         };
     });
-    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, or LinkedIn. You can only reply to conversations that already exist. Direct-message replies must be within the platform's 24-hour messaging window. Each workspace can send up to 1,000 replies per day.", {
+    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, or X. You can only reply to conversations that already exist. Meta direct-message replies must be within the platform's 24-hour messaging window. X replies are DM-only and use 2 prepaid credits per send (X's API fee passed through at cost) — a 402 insufficient_credits error means the organisation needs to top up at https://app.omnisocials.com/credits; relay that link to the user rather than retrying. Each workspace can send up to 1,000 replies per day.", {
         conversation_id: z.string().describe("The conversation ID to reply to"),
         text: z.string().describe("The reply text (max 2000 characters)"),
     }, async ({ conversation_id, text }) => {

package/build/tools/media.js

@@ -13,7 +13,7 @@ export function registerMediaTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const items = Array.isArray(result.data) ? result.data : result.data?.media || [];
+        const items = Array.isArray(result.data) ? result.data : [];
         if (!items.length) {
             const hint = params?.search
                 ? `No media found matching "${params.search}". It hasn't been uploaded yet — upload it (and pass a \`name\`) so it's findable next time.`
@@ -122,6 +122,11 @@ When the user provides an image in the conversation (not a URL), use base64_data
             return { content: [{ type: "text", text: md }] };
         }
         const m = result.data;
+        if (!m) {
+            return {
+                content: [{ type: "text", text: "Upload succeeded, but the API returned no media details. Find the file with list_media." }],
+            };
+        }
         const isProcessing = m.status === "processing";
         let md = isProcessing ? `## Media Processing\n\n` : `## Media Uploaded\n\n`;
         md += `| Field | Value |\n`;
@@ -170,7 +175,8 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
         const connected = r.connected_platforms || [];
         let md = `## Compatibility Check\n\n`;
         if (r.file) {
-            const sz = r.file.size_known ? formatBytes(r.file.size_bytes) : "unknown size";
+            // size_known implies size_bytes is a finite number (media.js check route).
+            const sz = r.file.size_known ? formatBytes(r.file.size_bytes ?? 0) : "unknown size";
             md += `File: ${sz}${r.file.mime ? ` · ${r.file.mime}` : ""}\n`;
         }
         md += `Connected platforms: ${connected.length ? connected.join(", ") : "none"}\n\n`;
@@ -204,6 +210,11 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
             };
         }
         const m = result.data;
+        if (!m) {
+            return {
+                content: [{ type: "text", text: "Media updated, but the API returned no details. Verify with list_media." }],
+            };
+        }
         return {
             content: [
                 {
@@ -218,7 +229,7 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
         if (result.error) {
             return { content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }] };
         }
-        const items = Array.isArray(result.data) ? result.data : result.data?.data || [];
+        const items = Array.isArray(result.data) ? result.data : [];
         if (!items.length) {
             return { content: [{ type: "text", text: "No folders yet. Create one with create_folder." }] };
         }
@@ -238,6 +249,11 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
             return { content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }] };
         }
         const f = result.data;
+        if (!f) {
+            return {
+                content: [{ type: "text", text: "Folder created, but the API returned no details. Verify with list_folders." }],
+            };
+        }
         return {
             content: [
                 {