@omnisocials/mcp-server 1.10.0 → 1.11.0

package/build/client.d.ts

@@ -9,6 +9,14 @@ 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;
+export declare function sortMetricLabels(labels: string[]): string[];
+/**
+ * Flatten a raw per-platform metrics object into ordered [label, value] rows,
+ * keeping every numeric counter the platform reported. Strings (note, title,
+ * cover_image_url, …) are skipped; `plays` is a legacy always-0 Instagram
+ * back-compat key so a zero there is noise, not data.
+ */
+export declare function metricRows(m: Record<string, unknown> | null | undefined): Array<[string, number]>;
 export interface XThreadPartInput {
     /** Tweet text — ≤ 280 chars (the API enforces 280 even for X Premium). */
     text: string;

package/build/client.js

@@ -89,6 +89,69 @@ export function truncate(value, len) {
 export function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
+// ─── Metric Rendering ───────────────────────────────────────────────────────
+// Canonical render order + labels for per-platform metric objects. Any numeric
+// key the API returns that isn't listed here still renders (prettified from
+// snake_case) so no metric is ever silently dropped — reach/saves/views went
+// missing for months because the old renderers used a fixed column set.
+const METRIC_LABELS = [
+    ["impressions", "Impressions"],
+    ["reach", "Reach"],
+    ["views", "Views"],
+    ["likes", "Likes"],
+    ["comments", "Comments"],
+    ["shares", "Shares"],
+    ["saves", "Saves"],
+    ["clicks", "Clicks"],
+    ["reposts", "Reposts"],
+    ["quotes", "Quotes"],
+    ["bookmarks", "Bookmarks"],
+    ["replies", "Replies"],
+    ["reactions", "Reactions"],
+    ["total_reactions", "Total reactions"],
+    ["favorites", "Favorites"],
+    ["plays", "Plays"],
+    ["engagement", "Engagements"],
+];
+// Context keys that ride along in stored metrics — not counters.
+const NON_COUNTER_KEYS = new Set(["create_time"]);
+/** 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]));
+export function sortMetricLabels(labels) {
+    return [...labels].sort((a, b) => (LABEL_ORDER.get(a) ?? 999) - (LABEL_ORDER.get(b) ?? 999));
+}
+/**
+ * Flatten a raw per-platform metrics object into ordered [label, value] rows,
+ * keeping every numeric counter the platform reported. Strings (note, title,
+ * cover_image_url, …) are skipped; `plays` is a legacy always-0 Instagram
+ * back-compat key so a zero there is noise, not data.
+ */
+export function metricRows(m) {
+    const rows = [];
+    const seen = new Set();
+    for (const [key, label] of METRIC_LABELS) {
+        const v = m?.[key];
+        if (v === undefined || v === null)
+            continue;
+        const n = Number(v);
+        if (!Number.isFinite(n))
+            continue;
+        seen.add(key);
+        if (key === "plays" && n === 0)
+            continue;
+        rows.push([label, n]);
+    }
+    for (const [key, v] of Object.entries(m || {})) {
+        if (seen.has(key) || NON_COUNTER_KEYS.has(key))
+            continue;
+        const n = Number(v);
+        if (!Number.isFinite(n))
+            continue;
+        rows.push([capitalize(key.replace(/_/g, " ")), n]);
+    }
+    return rows;
+}
 export class OmniSocialsClient {
     baseUrl;
     apiKey;

package/build/index.js

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

package/build/tools/analytics.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { formatNumber, capitalize } from "../client.js";
+import { formatNumber, capitalize, metricRows, sortMetricLabels } from "../client.js";
 export function registerAnalyticsTools(server, getClient) {
-    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post (impressions, engagements, likes, etc.).", {
+    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."),
     }, async ({ post_id }) => {
         const result = await getClient().getPostAnalytics(post_id);
@@ -26,41 +26,62 @@ export function registerAnalyticsTools(server, getClient) {
                     }],
             };
         }
-        const totals = { impressions: 0, engagements: 0, likes: 0, comments: 0, shares: 0 };
+        // Every numeric metric the platform reported is rendered via metricRows —
+        // a fixed column set here is how reach/saves/views silently vanished.
         const perPlatform = [];
+        const totalOrder = [];
+        const totalsByLabel = new Map();
+        let totalEngagements = 0;
+        let totalDenom = 0;
         for (const [platform, entry] of platformEntries) {
             const m = entry?.metrics || {};
-            const impressions = platform === "instagram"
-                ? Number(m.reach ?? m.impressions ?? 0)
-                : Number(m.views ?? m.impressions ?? 0);
+            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;
-            totals.impressions += impressions;
-            totals.engagements += engagements;
-            totals.likes += likes;
-            totals.comments += comments;
-            totals.shares += shares;
-            perPlatform.push({ platform, impressions, engagements, likes, comments, shares });
+            // Denominator for engagement rate: the broadest exposure count present.
+            const denom = Number(m.impressions ?? m.views ?? m.reach ?? 0);
+            totalEngagements += engagements;
+            totalDenom += denom;
+            for (const [label, n] of rows) {
+                if (!totalsByLabel.has(label))
+                    totalOrder.push(label);
+                totalsByLabel.set(label, (totalsByLabel.get(label) || 0) + n);
+            }
+            perPlatform.push({
+                platform,
+                rows,
+                engagements,
+                denom,
+                note: typeof m.note === "string" ? m.note : undefined,
+            });
         }
-        let md = `## Post Analytics\n\n`;
-        md += `| Metric | Value |\n`;
-        md += `|--------|-------|\n`;
-        md += `| **Impressions** | ${formatNumber(totals.impressions)} |\n`;
-        md += `| **Engagements** | ${formatNumber(totals.engagements)} |\n`;
-        md += `| **Likes** | ${formatNumber(totals.likes)} |\n`;
-        md += `| **Comments** | ${formatNumber(totals.comments)} |\n`;
-        md += `| **Shares** | ${formatNumber(totals.shares)} |\n`;
-        if (totals.impressions > 0) {
-            const rate = ((totals.engagements / totals.impressions) * 100).toFixed(2);
-            md += `| **Engagement Rate** | ${rate}% |\n`;
+        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` : "";
+        let md = perPlatform.length === 1
+            ? `## Post Analytics — ${capitalize(perPlatform[0].platform)}\n`
+            : `## Post Analytics\n\n`;
+        if (perPlatform.length > 1) {
+            md += `| Metric | Value |\n|--------|-------|\n`;
+            for (const label of sortMetricLabels(totalOrder)) {
+                md += `| **${label}** | ${formatNumber(totalsByLabel.get(label) || 0)} |\n`;
+            }
+            md += renderRate(totalEngagements, totalDenom);
+            md += `\n### Per-Platform Breakdown\n`;
         }
-        md += `\n### Per-Platform Breakdown\n\n`;
-        md += `| Platform | Impressions | Engagements | Likes | Comments | Shares |\n`;
-        md += `|----------|-------------|-------------|-------|----------|--------|\n`;
         for (const p of perPlatform) {
-            md += `| ${capitalize(p.platform)} | ${formatNumber(p.impressions)} | ${formatNumber(p.engagements)} | ${formatNumber(p.likes)} | ${formatNumber(p.comments)} | ${formatNumber(p.shares)} |\n`;
+            if (perPlatform.length > 1)
+                md += `\n#### ${capitalize(p.platform)}\n`;
+            md += `\n| Metric | Value |\n|--------|-------|\n`;
+            for (const [label, n] of p.rows) {
+                md += `| **${label}** | ${formatNumber(n)} |\n`;
+            }
+            md += renderRate(p.engagements, p.denom);
+            if (p.note)
+                md += `\n_${p.note}_\n`;
         }
         return {
             content: [{ type: "text", text: md }],
@@ -88,17 +109,21 @@ export function registerAnalyticsTools(server, getClient) {
             const platformEntries = Object.entries(platforms);
             let impressions = 0;
             let engagements = 0;
-            for (const [platform, p] of platformEntries) {
+            let likes = 0;
+            let comments = 0;
+            let shares = 0;
+            for (const [, p] of platformEntries) {
                 const m = p?.metrics || {};
-                const imp = platform === "instagram"
-                    ? Number(m.reach ?? m.impressions ?? 0)
-                    : Number(m.views ?? m.impressions ?? 0);
-                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 eng = m.engagement != null ? Number(m.engagement) : likes + comments + shares;
-                impressions += imp;
-                engagements += eng;
+                // 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;
             }
             return {
                 post_id: entry.post_id,
@@ -106,16 +131,20 @@ export function registerAnalyticsTools(server, getClient) {
                 platformNames: platformEntries.map(([name]) => capitalize(name)).join(", "),
                 impressions,
                 engagements,
+                likes,
+                comments,
+                shares,
             };
         });
         const withData = rows.filter((r) => r.platformCount > 0).length;
         let md = `## Posts Analytics (${rows.length} posts, ${withData} with collected stats)\n\n`;
-        md += `| Post ID | Platforms | Impressions | Engagements |\n`;
-        md += `|---------|-----------|-------------|-------------|\n`;
+        md += `| Post ID | Platforms | Impressions | Engagements | Likes | Comments | Shares |\n`;
+        md += `|---------|-----------|-------------|-------------|-------|----------|--------|\n`;
         for (const r of rows) {
-            md += `| ${r.post_id} | ${r.platformNames || "—"} | ${r.platformCount ? formatNumber(r.impressions) : "—"} | ${r.platformCount ? formatNumber(r.engagements) : "—"} |\n`;
+            const c = (n) => (r.platformCount ? formatNumber(n) : "—");
+            md += `| ${r.post_id} | ${r.platformNames || "—"} | ${c(r.impressions)} | ${c(r.engagements)} | ${c(r.likes)} | ${c(r.comments)} | ${c(r.shares)} |\n`;
         }
-        md += `\nPosts showing "—" have no analytics collected yet. Stats are fetched periodically after publishing; check back in a few hours.\n`;
+        md += `\nPosts showing "—" have no analytics collected yet. Stats are fetched periodically after publishing; check back in a few hours. Use get_post_analytics on a single post for the full per-platform metric set (reach, views, saves, clicks, …).\n`;
         return {
             content: [{ type: "text", text: md }],
         };

package/build/tools/posts.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { formatDateTime, truncate, capitalize, formatNumber } from "../client.js";
+import { formatDateTime, truncate, capitalize, formatNumber, metricRows } from "../client.js";
 // Reusable per-platform option objects for the "first comment" feature — text
 // auto-posted as a comment on the post right after it publishes (hashtags out
 // of the caption, "link in first comment", etc.). Only platforms with a
@@ -812,7 +812,7 @@ Notes:
         });
         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` and `impressions` so you can rank across platforms (Instagram posts include 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); LinkedIn, Threads, Pinterest, and Google Business return captions only. Fetched live, so expect a few seconds of latency. Requires the analytics:read scope.", {
+    server.tool("get_recent_platform_posts", "Fetch the user's most recent posts straight from their connected platform APIs (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), INCLUDING content published outside OmniSocials. Use this when list_posts is empty — e.g. a brand-new workspace that has not published through OmniSocials yet — so you can still analyze the user's real content. Each post includes normalized `engagement` plus every raw metric the platform reported (Instagram: reach/views/saves/shares from per-post insights). Metrics only appear where the platform exposes them for historical posts (X, TikTok, Bluesky, Mastodon, Instagram, Facebook, YouTube); Threads, Pinterest, and Google Business return captions only. LinkedIn personal profiles can't be listed live (LinkedIn grants apps no such permission), so their results are posts published through OmniSocials with their latest collected stats. Fetched live, so expect a few seconds of latency. Requires the analytics:read scope.", {
         limit: z
             .string()
             .optional()
@@ -841,15 +841,20 @@ Notes:
             };
         }
         let md = `## Recent platform posts (${posts.length} across ${connected.length} platform${connected.length === 1 ? "" : "s"})\n\n`;
-        md += `| # | Platform | Format | Content | Engagement | Impressions | Date |\n`;
-        md += `|---|----------|--------|---------|------------|-------------|------|\n`;
+        md += `| # | Platform | Format | Content | Engagement | Metrics | Date |\n`;
+        md += `|---|----------|--------|---------|------------|---------|------|\n`;
         posts.forEach((p, i) => {
             const hasMetrics = p.metrics && Object.keys(p.metrics).length > 0;
             const content = truncate(clean(p.text), 45) || "*(no caption)*";
             const eng = hasMetrics ? formatNumber(p.engagement || 0) : "—";
-            const imp = hasMetrics ? formatNumber(p.impressions || 0) : "—";
+            // Every counter the platform reported, compact: "1.4K views · 12 saves".
+            // Engagement has its own column, so skip its row here.
+            const detail = metricRows(p.metrics)
+                .filter(([label]) => label !== "Engagements")
+                .map(([label, n]) => `${formatNumber(n)} ${label.toLowerCase()}`)
+                .join(" · ");
             const date = p.timestamp ? formatDateTime(p.timestamp) : "—";
-            md += `| ${i + 1} | ${capitalize(p.platform)} | ${p.format || "post"} | ${content} | ${eng} | ${imp} | ${date} |\n`;
+            md += `| ${i + 1} | ${capitalize(p.platform)} | ${p.format || "post"} | ${content} | ${eng} | ${detail || "—"} | ${date} |\n`;
         });
         if (result.note)
             md += `\n${result.note}\n`;

package/package.json

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