@omnisocials/mcp-server 1.9.0 → 1.10.0

package/build/client.d.ts

@@ -238,6 +238,10 @@ export declare class OmniSocialsClient {
         platform?: string;
         date?: string;
     }): Promise<ApiResponse<unknown>>;
+    getBestTimes(params: {
+        platform: string;
+        timezone?: string;
+    }): Promise<ApiResponse<unknown>>;
     listWebhooks(): Promise<ApiResponse<unknown>>;
     createWebhook(data: {
         url: string;

package/build/client.js

@@ -224,6 +224,9 @@ export class OmniSocialsClient {
     async getAccountAnalytics(params) {
         return this.request("GET", "/analytics/accounts", undefined, params);
     }
+    async getBestTimes(params) {
+        return this.request("GET", "/analytics/best-times", undefined, params);
+    }
     // Webhooks
     async listWebhooks() {
         return this.request("GET", "/webhooks");

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

package/build/tools/analytics.js

@@ -221,4 +221,57 @@ 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.", {
+        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) => {
+        const result = await getClient().getBestTimes(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const d = result;
+        let md = `## Best times to post — ${capitalize(d.platform)} (${d.timezone})\n\n`;
+        md += `**Top slots:**\n`;
+        (d.recommendations || []).forEach((r, i) => {
+            const extras = [];
+            if (r.typical_engagement)
+                extras.push(`~${formatNumber(r.typical_engagement)} typical engagement`);
+            if (r.n)
+                extras.push(`${r.n} posts`);
+            md += `${i + 1}. **${capitalize(r.day)} ${r.time}** (score ${r.score}${extras.length ? `, ${extras.join(", ")}` : ""})\n`;
+        });
+        // Per-day compact breakdown: up to 2 best hours per day, in week order.
+        const byDay = new Map();
+        for (const cell of d.grid || []) {
+            if (!byDay.has(cell.day))
+                byDay.set(cell.day, []);
+            byDay.get(cell.day).push(cell);
+        }
+        const weekOrder = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+        const dayRows = weekOrder
+            .filter((day) => byDay.has(day))
+            .map((day) => {
+            const top = byDay
+                .get(day)
+                .sort((a, b) => b.score - a.score)
+                .slice(0, 2)
+                .map((c) => `${String(c.hour).padStart(2, "0")}:00 (${c.score})`)
+                .join(", ");
+            return `| ${capitalize(day)} | ${top} |`;
+        });
+        if (dayRows.length) {
+            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`;
+        }
+        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`;
+        }
+        return {
+            content: [{ type: "text", text: md }],
+        };
+    });
 }

package/build/tools/posts.js

@@ -140,7 +140,7 @@ export function registerPostTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("get_post", "Get details of a specific post by ID. When a post has per-platform caption overrides (e.g. a shorter X version alongside the default), every variant is rendered as its own labeled block under `### Content` so you can see exactly what each platform will publish. X threads are rendered under `### X Thread` with each tweet labeled in publish order — read this to see the full chained tweet text, since thread-only posts have no caption in `content`. After publishing, includes `published_urls` — a map of platform → live URL for each platform that successfully posted (e.g. facebook, instagram, linkedin, x). Useful for polling: when a post's status is `published`, read `published_urls` to surface the live links.", {
+    server.tool("get_post", "Get details of a specific post by ID — content, channels, media (with URLs), first comment, Instagram collaborators/user tags/location, dates and live URLs, enough to fully verify a scheduled post without opening the dashboard. When a post has per-platform caption overrides (e.g. a shorter X version alongside the default), every variant is rendered as its own labeled block under `### Content` so you can see exactly what each platform will publish. X threads are rendered under `### X Thread` with each tweet labeled in publish order — read this to see the full chained tweet text, since thread-only posts have no caption in `content`. After publishing, includes `published_urls` — a map of platform → live URL for each platform that successfully posted (e.g. facebook, instagram, linkedin, x). Useful for polling: when a post's status is `published`, read `published_urls` to surface the live links.", {
         id: z.string().describe("The post ID"),
     }, async ({ id }) => {
         const result = await getClient().getPost(id);
@@ -171,10 +171,45 @@ export function registerPostTools(server, getClient) {
         md += `| **Created** | ${formatDateTime(p.created_at)} |\n`;
         if (appUrl)
             md += `| **Open in OmniSocials** | ${appUrl} |\n`;
-        if (p.media?.length) {
-            md += `| **Media** | ${p.media.length} file(s) |\n`;
+        // Media can be a flat array (same set everywhere) or a per-platform
+        // object ({ default: [...], instagram: [...] }). The old `p.media.length`
+        // check silently dropped the object shape (`.length` is undefined).
+        const mediaGroups = Array.isArray(p.media)
+            ? (p.media.length ? [["all", p.media]] : [])
+            : Object.entries(p.media || {}).filter((e) => Array.isArray(e[1]) && e[1].length > 0);
+        const mediaUrlOf = (m) => (typeof m === "string" ? m : m?.url) || null;
+        const uniqueMediaUrls = new Set(mediaGroups.flatMap(([, items]) => items.map(mediaUrlOf).filter(Boolean)));
+        if (uniqueMediaUrls.size) {
+            md += `| **Media** | ${uniqueMediaUrls.size} file(s) |\n`;
+        }
+        // Instagram extras, echoed top-level by the API to mirror create_post.
+        if (p.location_id)
+            md += `| **IG location** | \`${p.location_id}\` |\n`;
+        if (Array.isArray(p.collaborators) && p.collaborators.length) {
+            md += `| **IG collaborators** | ${p.collaborators.map((c) => `@${c}`).join(", ")} |\n`;
+        }
+        if (Array.isArray(p.user_tags) && p.user_tags.length) {
+            md += `| **IG user tags** | ${p.user_tags
+                .map((t) => `@${typeof t === "string" ? t : t?.username || "?"}`)
+                .join(", ")} |\n`;
         }
         md += `\n### Content\n\n${renderContent(p.content)}`;
+        // Media URLs — so a caller can verify exactly what's attached (and in
+        // what order) without opening the dashboard.
+        if (mediaGroups.length) {
+            md += `\n\n### Media\n\n`;
+            const flat = mediaGroups.length === 1 && mediaGroups[0][0] === "all";
+            for (const [group, items] of mediaGroups) {
+                if (!flat) {
+                    md += `**${group === "default" ? "Default (all platforms)" : capitalize(group.replace(/_/g, " "))}**\n`;
+                }
+                items.forEach((m, i) => {
+                    md += `${i + 1}. ${mediaUrlOf(m) || "*(no url)*"}\n`;
+                });
+                md += `\n`;
+            }
+            md = md.trimEnd();
+        }
         // X thread: when present, the canonical tweet text lives here, not in `content`.
         const threadParts = Array.isArray(p.x?.thread_parts)
             ? p.x.thread_parts
@@ -242,13 +277,15 @@ export function registerPostTools(server, getClient) {
         const firstCommentRows = [];
         for (const platform of firstCommentPlatforms) {
             const opts = p[platform];
-            const text = opts && typeof opts === "object" ? opts.first_comment : undefined;
-            if (typeof text !== "string" || !text.trim())
+            if (!opts || typeof opts !== "object")
                 continue;
+            const text = typeof opts.first_comment === "string" ? opts.first_comment.trim() : "";
             const result = opts.first_comment_result;
+            if (!text && !result)
+                continue;
             const status = result && typeof result === "object" ? result.status : undefined;
             const statusLabel = status ? ` — _${status}${result?.error ? `: ${result.error}` : ""}_` : "";
-            firstCommentRows.push(`- **${capitalize(platform.replace(/_/g, " "))}**${statusLabel}: ${truncate(text, 200)}`);
+            firstCommentRows.push(`- **${capitalize(platform.replace(/_/g, " "))}**${statusLabel}: ${text ? truncate(text, 200) : "*(none)*"}`);
         }
         if (firstCommentRows.length) {
             md += `\n\n### First Comments\n\n${firstCommentRows.join("\n")}\n`;
@@ -775,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. 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` 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.", {
         limit: z
             .string()
             .optional()

package/package.json

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