@omnisocials/mcp-server 1.7.0 → 1.8.0

package/README.md

@@ -146,11 +146,12 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | `list_accounts` | List connected social media accounts |
 | `get_account` | Get account details |
 
-### Analytics (3 tools)
+### Analytics (4 tools)
 
 | Tool | Description |
 |------|-------------|
 | `get_post_analytics` | Get stats for a published post |
+| `get_posts_analytics` | Get stats for up to 100 posts in one call (bulk) |
 | `get_analytics_overview` | Overview analytics for a time period |
 | `get_account_analytics` | Account-level analytics (followers, etc.) |
 

package/build/client.d.ts

@@ -141,6 +141,17 @@ export declare class OmniSocialsClient {
         name?: string;
         folder?: string;
     }): Promise<ApiResponse<unknown>>;
+    /**
+     * Preflight a file's compatibility with the workspace's connected platforms
+     * BEFORE uploading. Provide one of: a public `url`, an existing `media_id`,
+     * or `size_bytes` + `mime`.
+     */
+    checkMediaCompatibility(data: {
+        url?: string;
+        media_id?: string;
+        size_bytes?: number;
+        mime?: string;
+    }): Promise<ApiResponse<unknown>>;
     deleteMedia(id: string): Promise<ApiResponse<unknown>>;
     updateMedia(id: string, data: {
         name?: string;
@@ -154,6 +165,7 @@ export declare class OmniSocialsClient {
     listAccounts(): Promise<ApiResponse<unknown>>;
     getAccount(id: string): Promise<ApiResponse<unknown>>;
     getPostAnalytics(postId: string): Promise<ApiResponse<unknown>>;
+    getPostsAnalytics(postIds: string[]): Promise<ApiResponse<unknown>>;
     getAnalyticsOverview(params?: {
         period?: string;
         start_date?: string;

package/build/client.js

@@ -162,11 +162,22 @@ export class OmniSocialsClient {
         return this.request("GET", "/media", undefined, params);
     }
     async uploadMedia(data) {
+        // Videos up to 1 GB: the API streams files >100 MB in the background and
+        // responds with the item in `processing` state. Includes a `compatibility`
+        // block listing connected platforms that would reject the file.
         return this.request("POST", "/media/upload-from-url", data);
     }
     async uploadMediaFromBase64(data) {
         return this.request("POST", "/media/upload-from-base64", data);
     }
+    /**
+     * Preflight a file's compatibility with the workspace's connected platforms
+     * BEFORE uploading. Provide one of: a public `url`, an existing `media_id`,
+     * or `size_bytes` + `mime`.
+     */
+    async checkMediaCompatibility(data) {
+        return this.request("POST", "/media/check", data);
+    }
     async deleteMedia(id) {
         return this.request("DELETE", `/media/${id}`);
     }
@@ -191,6 +202,13 @@ export class OmniSocialsClient {
     async getPostAnalytics(postId) {
         return this.request("GET", `/analytics/posts/${postId}`);
     }
+    // Batch version of getPostAnalytics — fetch up to 100 posts' latest
+    // per-platform metrics in one call instead of one request per post.
+    async getPostsAnalytics(postIds) {
+        return this.request("GET", "/analytics/posts", undefined, {
+            ids: postIds.join(","),
+        });
+    }
     async getAnalyticsOverview(params) {
         return this.request("GET", "/analytics/overview", undefined, params);
     }

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

package/build/tools/analytics.js

@@ -65,6 +65,60 @@ export function registerAnalyticsTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
+    server.tool("get_posts_analytics", "Get analytics for several published posts at once (up to 100). Returns each post's totalled impressions and engagements. Use this instead of calling get_post_analytics in a loop — it is one request rather than one per post.", {
+        post_ids: z
+            .array(z.string())
+            .min(1)
+            .max(100)
+            .describe("Numeric OmniSocials post ids (the `id` field from list_posts), up to 100. NOT platform post ids such as YouTube video ids or tweet ids."),
+    }, async ({ post_ids }) => {
+        const result = await getClient().getPostsAnalytics(post_ids);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        // API returns { data: [{ post_id, platforms: { <platform>: { metrics } } }] }.
+        // Collapse each post's per-platform metrics into totals, mirroring the
+        // aggregation used by get_post_analytics.
+        const entries = result.data || [];
+        const rows = entries.map((entry) => {
+            const platforms = entry?.platforms || {};
+            const platformEntries = Object.entries(platforms);
+            let impressions = 0;
+            let engagements = 0;
+            for (const [platform, 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;
+            }
+            return {
+                post_id: entry.post_id,
+                platformCount: platformEntries.length,
+                platformNames: platformEntries.map(([name]) => capitalize(name)).join(", "),
+                impressions,
+                engagements,
+            };
+        });
+        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`;
+        for (const r of rows) {
+            md += `| ${r.post_id} | ${r.platformNames || "—"} | ${r.platformCount ? formatNumber(r.impressions) : "—"} | ${r.platformCount ? formatNumber(r.engagements) : "—"} |\n`;
+        }
+        md += `\nPosts showing "—" have no analytics collected yet. Stats are fetched periodically after publishing; check back in a few hours.\n`;
+        return {
+            content: [{ type: "text", text: md }],
+        };
+    });
     server.tool("get_analytics_overview", "Get analytics overview with total posts, impressions, engagements, engagement rate, and per-platform breakdown. Use `period` for a rolling window (7d / 30d / 90d) or `start_date` + `end_date` for a custom range. The response echoes the resolved range and today's date — read those before assuming a year from training data (e.g. when the user says 'April', use the most recent April, not April from your training cutoff).", {
         period: z.string().optional().describe("Rolling window: 7d, 30d, 90d (default: 30d). Ignored if start_date/end_date are provided."),
         start_date: z.string().optional().describe('Custom start date. Accepts "YYYY-MM-DD" (e.g. "2026-04-01") or "YYYY-MM" month-shorthand (e.g. "2026-04" → first of the month).'),

package/build/tools/media.js

@@ -32,7 +32,7 @@ export function registerMediaTools(server, getClient) {
             const isVideo = rawType === "video" || rawType.startsWith("video/");
             const type = isVideo ? "Video" : "Image";
             const folder = m.folder_id ? `\`${m.folder_id}\`` : "—";
-            md += `| ${i + 1} | ${type} | ${m.name || m.filename || "—"} | ${folder} | ${formatBytes(m.size || 0)} | \`${m.id}\` |\n`;
+            md += `| ${i + 1} | ${type} | ${m.name || m.filename || "—"} | ${folder} | ${(m.size || "—")} | \`${m.id}\` |\n`;
         }
         md += `\nUse the **Media ID** with \`media_ids\` when creating posts. Rename or move a file with \`update_media\`. See folders with \`list_folders\`.`;
         // Fetch thumbnails for image files (max 4)
@@ -55,7 +55,13 @@ export function registerMediaTools(server, getClient) {
         content.push({ type: "text", text: md });
         return { content };
     });
-    server.tool("upload_media", `Upload media to the library. Accepts EITHER a public URL OR base64-encoded image data (e.g. when the user pastes an image directly in chat). Max 50MB. Supported: JPEG, PNG, GIF, WebP, MP4, MOV, AVI.
+    server.tool("upload_media", `Upload media to the library. Accepts EITHER a public URL OR base64-encoded image data (e.g. when the user pastes an image directly in chat). Supported: JPEG, PNG, GIF, WebP, MP4, MOV, AVI.
+
+Size limits: base64 and direct uploads are capped at 100 MB (and base64 inflates the request body, so the practical ceiling is ~75 MB). For anything larger — up to 1 GB — use ONE of: (a) pass a public 'url' and the server fetches it (handles up to 1 GB), or (b) have the user upload the file in the OmniSocials Library UI at https://app.omnisocials.com/library . IMPORTANT: if the user has a large LOCAL file (over ~100 MB) with no public URL, do NOT tell them to compress or shrink it — instead point them to the Library UI link above, which uploads files up to 1 GB directly.
+
+Large videos (over 100 MB) are processed in the background: the response comes back with status "processing" — the file is NOT usable in a post until its status is "ready". Re-check with list_media (search by the name you gave it) until its status is "ready".
+
+Compatibility: the response includes a "compatibility" summary of any CONNECTED platforms that would reject the file (e.g. too large for Instagram). If there are warnings, RELAY them to the user and ask whether to continue before using the media in a post — the file still uploads and can post to the platforms that DO accept it. To check BEFORE uploading, use check_media_compatibility first.
 
 When the user provides an image in the conversation (not a URL), use base64_data + mime_type to upload it directly.`, {
         url: z.string().optional().describe("Public URL of the media file to upload. Use this OR base64_data, not both."),
@@ -89,22 +95,72 @@ When the user provides an image in the conversation (not a URL), use base64_data
             };
         }
         const m = result.data;
-        let md = `## Media Uploaded\n\n`;
+        const compatibility = result.compatibility;
+        const isProcessing = m.status === "processing";
+        let md = isProcessing ? `## Media Processing\n\n` : `## Media Uploaded\n\n`;
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;
         md += `| **Media ID** | \`${m.id}\` |\n`;
         md += `| **Name** | ${m.name || m.filename || "—"} |\n`;
         md += `| **Type** | ${m.type || "—"} |\n`;
+        if (m.status)
+            md += `| **Status** | ${m.status} |\n`;
         if (m.folder_id)
             md += `| **Folder** | \`${m.folder_id}\` |\n`;
-        md += `| **Size** | ${formatBytes(m.size || 0)} |\n`;
+        md += `| **Size** | ${(m.size || "—")} |\n`;
         if (m.url)
             md += `| **URL** | ${m.url} |\n`;
-        md += `\nUse this Media ID with \`media_ids\` when creating posts (including inside \`x.thread_parts[].media_ids\`). The public URL above also works anywhere \`media_urls\` is accepted.`;
+        if (isProcessing) {
+            md += `\n⏳ This large video is still being processed. Re-check with list_media (search by its name) until its status is **ready** before using it in a post.`;
+        }
+        if (compatibility && compatibility.compatible === false && compatibility.summary) {
+            md += `\n\n⚠️ **${compatibility.summary}** It will still post to your other connected platforms. Ask the user whether to continue before adding it to a post.`;
+        }
+        md += `\n\nUse this Media ID with \`media_ids\` when creating posts (including inside \`x.thread_parts[].media_ids\`). The public URL above also works anywhere \`media_urls\` is accepted.`;
         return {
             content: [{ type: "text", text: md }],
         };
     });
+    server.tool("check_media_compatibility", `Check whether a video/image will be accepted by the platforms CONNECTED to this workspace, BEFORE uploading or posting. Use this when the user gives you a file (URL) so you can warn them upfront — e.g. "this 995 MB video won't post to Instagram (max 300 MB), continue?" — and confirm before uploading.
+
+Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an existing 'media_id', or explicit 'size_bytes' + 'mime'. Returns the connected platforms and any that would reject the file by size or format.`, {
+        url: z.string().optional().describe("Public URL of the file to check. Use this OR media_id OR size_bytes+mime."),
+        media_id: z.string().optional().describe("Id of an already-uploaded library item to check."),
+        size_bytes: z.number().optional().describe("File size in bytes (use with mime when you already know them)."),
+        mime: z.string().optional().describe("MIME type, e.g. 'video/mp4' (use with size_bytes)."),
+    }, async (params) => {
+        if (!params.url && !params.media_id && !(params.size_bytes && params.mime)) {
+            return {
+                content: [{ type: "text", text: "Error: Provide one of 'url', 'media_id', or 'size_bytes' + 'mime'." }],
+            };
+        }
+        const result = await getClient().checkMediaCompatibility(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const r = result;
+        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";
+            md += `File: ${sz}${r.file.mime ? ` · ${r.file.mime}` : ""}\n`;
+        }
+        md += `Connected platforms: ${connected.length ? connected.join(", ") : "none"}\n\n`;
+        if (r.compatible) {
+            md += `✅ This file posts to all your connected platforms.`;
+        }
+        else {
+            md += `⚠️ ${r.summary || "Some connected platforms would reject this file:"}\n\n`;
+            md += `| Platform | Why |\n|----------|-----|\n`;
+            for (const w of r.warnings || []) {
+                md += `| ${w.display_name} | ${(w.reasons || []).join(", ")} |\n`;
+            }
+            md += `\nAsk the user whether to continue. It will still post to the platforms not listed above.`;
+        }
+        return { content: [{ type: "text", text: md }] };
+    });
     server.tool("update_media", "Rename an existing media file or move it into a folder (so it's findable later instead of re-uploading it). Only the fields you pass are changed.", {
         id: z.string().describe("The media ID to update"),
         name: z.string().optional().describe('New human-readable label, e.g. "pp-play5get50". Pass an empty string to clear it.'),

package/build/tools/posts.js

@@ -271,7 +271,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             paid_partnership: z.boolean().optional().describe("Mark as paid partnership disclosure"),
             made_with_ai: z.boolean().optional().describe("Mark as AI-generated content"),
             thread_parts: z.array(z.object({
-                text: z.string().describe("Tweet text (≤ 280 chars)"),
+                text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
                 media_ids: z.array(z.string()).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Attach your uploaded graphics to any tweet in the thread."),
                 media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids)"),
             })).min(2).max(25).optional().describe("Publish as a chained X thread instead of a single tweet. Provide 2–25 parts; each is posted in order via in_reply_to_tweet_id. Attach media to any part (first tweet or reply) via media_ids (from upload_media) or media_urls — max 4 per part. For a single tweet, omit thread_parts and use content."),
@@ -403,7 +403,7 @@ Do NOT call without required media — it will fail.`, {
             paid_partnership: z.boolean().optional().describe("Mark as paid partnership disclosure"),
             made_with_ai: z.boolean().optional().describe("Mark as AI-generated content"),
             thread_parts: z.array(z.object({
-                text: z.string().describe("Tweet text (≤ 280 chars)"),
+                text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
                 media_ids: z.array(z.string()).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Attach your uploaded graphics to any tweet in the thread."),
                 media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids)"),
             })).min(2).max(25).optional().describe("Publish as a chained X thread (2–25 parts). Each is posted in order via in_reply_to_tweet_id. Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part."),
@@ -521,7 +521,7 @@ Do NOT call without required media — it will fail.`, {
             paid_partnership: z.boolean().optional(),
             made_with_ai: z.boolean().optional(),
             thread_parts: z.array(z.object({
-                text: z.string().describe("Tweet text (≤ 280 chars)"),
+                text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
                 media_ids: z.array(z.string()).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Attach your uploaded graphics to any tweet in the thread."),
                 media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids)"),
             })).min(2).max(25).nullable().optional().describe("Replace the X thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls, max 4 per part), or `null` to revert to single-tweet mode."),

package/build/tools/webhooks.js

@@ -73,6 +73,10 @@ export function registerWebhookTools(server, getClient) {
         md += `| **Status** | ${w.is_active ? "Active" : "Inactive"} |\n`;
         md += `| **Last Triggered** | ${w.last_triggered_at ? formatDateTime(w.last_triggered_at) : "Never"} |\n`;
         md += `| **Failure Count** | ${w.failure_count ?? 0} |\n`;
+        if (w.last_failure) {
+            const lf = w.last_failure;
+            md += `| **Last Failure** | ${formatDateTime(lf.at)} — ${lf.error} |\n`;
+        }
         md += `| **Created** | ${formatDateTime(w.created_at)} |\n`;
         return {
             content: [{ type: "text", text: md }],

package/build/types.d.ts

@@ -74,6 +74,12 @@ export interface Webhook {
     is_active: boolean;
     last_triggered_at: string | null;
     failure_count: number;
+    last_failure: {
+        at: string;
+        status: number | null;
+        error: string;
+        attempts: number;
+    } | null;
     created_at: string;
 }
 export interface AnalyticsOverview {

package/package.json

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