@omnisocials/mcp-server 1.7.1 → 1.9.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

@@ -1,4 +1,4 @@
-import type { ApiResponse } from "./types.js";
+import type { ApiResponse, MediaItem, PdfUploadResult } from "./types.js";
 export declare function fetchImageAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
@@ -32,6 +32,44 @@ export interface XPostOptions {
 export interface XPostOptionsUpdate extends Omit<XPostOptions, "thread_parts"> {
     thread_parts?: XThreadPartInput[] | null;
 }
+export interface BlueskyThreadPartInput {
+    /** Post text — ≤ 300 characters (counted as graphemes; one emoji = 1). */
+    text: string;
+    /** Optional per-part media as Library IDs from upload_media (max 4). */
+    media_ids?: string[];
+    /** Optional per-part media as external URLs (max 4). */
+    media_urls?: string[];
+}
+export interface BlueskyPostOptions {
+    /** Provide 2–25 parts to publish as a thread. Omit for a single post. */
+    thread_parts?: BlueskyThreadPartInput[];
+}
+/**
+ * Update-side variant: `thread_parts: null` clears the thread (revert to a
+ * single post); `undefined` leaves the existing thread untouched.
+ */
+export interface BlueskyPostOptionsUpdate {
+    thread_parts?: BlueskyThreadPartInput[] | null;
+}
+export interface MastodonThreadPartInput {
+    /** Status text — ≤ 500 characters by default (some instances allow more). */
+    text: string;
+    /** Optional per-part media as Library IDs from upload_media (max 4). */
+    media_ids?: string[];
+    /** Optional per-part media as external URLs (max 4). */
+    media_urls?: string[];
+}
+export interface MastodonPostOptions {
+    /** Provide 2–25 parts to publish as a thread. Omit for a single status. */
+    thread_parts?: MastodonThreadPartInput[];
+}
+/**
+ * Update-side variant: `thread_parts: null` clears the thread (revert to a
+ * single status); `undefined` leaves the existing thread untouched.
+ */
+export interface MastodonPostOptionsUpdate {
+    thread_parts?: MastodonThreadPartInput[] | null;
+}
 export declare class OmniSocialsClient {
     private baseUrl;
     private apiKey;
@@ -43,6 +81,10 @@ export declare class OmniSocialsClient {
         offset?: string;
     }): Promise<ApiResponse<unknown>>;
     getPost(id: string): Promise<ApiResponse<unknown>>;
+    getRecentPlatformPosts(params?: {
+        limit?: string;
+        platforms?: string;
+    }): Promise<ApiResponse<unknown>>;
     createPost(data: {
         content: string | Record<string, string>;
         channels?: string[];
@@ -66,8 +108,13 @@ export declare class OmniSocialsClient {
         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>;
     }): Promise<ApiResponse<unknown>>;
     createAndPublishPost(data: {
@@ -92,8 +139,13 @@ export declare class OmniSocialsClient {
         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>;
     }): Promise<ApiResponse<unknown>>;
     updatePost(id: string, data: {
@@ -114,8 +166,13 @@ export declare class OmniSocialsClient {
         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?: XPostOptionsUpdate;
+        bluesky?: BlueskyPostOptionsUpdate;
+        mastodon?: MastodonPostOptionsUpdate;
         google_business?: Record<string, unknown>;
     }): Promise<ApiResponse<unknown>>;
     deletePost(id: string): Promise<ApiResponse<unknown>>;
@@ -133,14 +190,20 @@ export declare class OmniSocialsClient {
         filename?: string;
         name?: string;
         folder?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
+        compatibility?: unknown;
+        message?: string;
+    }>;
     uploadMediaFromBase64(data: {
         data: string;
         mime_type: string;
         filename?: string;
         name?: string;
         folder?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
+        compatibility?: unknown;
+        message?: string;
+    }>;
     /**
      * Preflight a file's compatibility with the workspace's connected platforms
      * BEFORE uploading. Provide one of: a public `url`, an existing `media_id`,
@@ -165,6 +228,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

@@ -135,6 +135,12 @@ export class OmniSocialsClient {
     async getPost(id) {
         return this.request("GET", `/posts/${id}`);
     }
+    // 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.
+    async getRecentPlatformPosts(params) {
+        return this.request("GET", "/posts/recent-platform", undefined, params);
+    }
     async createPost(data) {
         return this.request("POST", "/posts/create", data);
     }
@@ -161,10 +167,13 @@ export class OmniSocialsClient {
     async listMedia(params) {
         return this.request("GET", "/media", undefined, params);
     }
+    // Videos up to 1 GB: the API streams files >100 MB in the background and
+    // responds with the item in `processing` state. A PDF is split into image
+    // slides and the response carries the extra PdfUploadResult fields (`slides`,
+    // `media_ids`, `pdf`) alongside `data` (the first slide). Every response also
+    // includes a `compatibility` block listing connected platforms that would
+    // reject the file.
     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) {
@@ -202,6 +211,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.1",
+    version: "1.9.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);

package/build/tools/analytics.js

@@ -12,9 +12,10 @@ export function registerAnalyticsTools(server, getClient) {
         }
         const d = result.data;
         // API returns { post_id, platforms: { <platform>: { metrics: {...} } } }.
-        // Aggregate the per-platform metrics into totals; the legacy flat shape
-        // (d.impressions / d.platform_stats) doesn't exist on this endpoint and
-        // reading those keys returned "—" for every field.
+        // Each platform's metrics are already summed across thread parts server-side
+        // (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 platformEntries = Object.entries(platforms);
         if (platformEntries.length === 0) {
@@ -65,6 +66,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 } } }] }.
+        // 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 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

@@ -55,7 +55,9 @@ 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). 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, and PDF.
+
+PDF = carousel: upload a PDF (as a 'url' or as base64_data with mime_type "application/pdf") and it is split into one image slide per page (max 20 pages). The response lists a Media ID for every slide — pass ALL of them, in order, as media_ids to create_post to post the deck as a carousel. On LinkedIn the slides post as a native swipeable DOCUMENT; on Instagram, TikTok, Threads and Pinterest as an image carousel. This is the way to let a user post an existing slide deck (Canva/PowerPoint/Figma exported to PDF) as a carousel.
 
 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.
 
@@ -64,9 +66,9 @@ Large videos (over 100 MB) are processed in the background: the response comes b
 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."),
-        base64_data: z.string().optional().describe("Base64-encoded file data. Use when the user provides an image directly in chat rather than a URL."),
-        mime_type: z.string().optional().describe("MIME type of the file (e.g. 'image/jpeg', 'image/png'). Required when using base64_data."),
+        url: z.string().optional().describe("Public URL of the media file to upload (image, video, or PDF). Use this OR base64_data, not both."),
+        base64_data: z.string().optional().describe("Base64-encoded file data. Use when the user provides an image or PDF directly in chat rather than a URL."),
+        mime_type: z.string().optional().describe("MIME type of the file (e.g. 'image/jpeg', 'image/png', 'application/pdf'). Required when using base64_data."),
         filename: z.string().optional().describe("Optional filename for the uploaded media"),
         name: z.string().optional().describe('Human-readable label so you can find this asset by name later instead of re-uploading it, e.g. "pp-play5get50". Strongly recommended on every upload.'),
         folder: z.string().optional().describe('Optional folder name to file this asset under (created at the top level if it does not exist), e.g. "win-graphics". See list_folders.'),
@@ -94,8 +96,32 @@ When the user provides an image in the conversation (not a URL), use base64_data
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const m = result.data;
         const compatibility = result.compatibility;
+        // PDF upload: the server split it into image slides. Surface every slide
+        // id and tell the model to pass them ALL to create_post as one carousel.
+        const mediaIds = result.media_ids;
+        const slides = result.slides;
+        const pdf = result.pdf;
+        if (Array.isArray(mediaIds) && mediaIds.length && Array.isArray(slides)) {
+            let md = `## PDF Uploaded as Carousel\n\n`;
+            md += `Split into **${mediaIds.length} image ${mediaIds.length === 1 ? "slide" : "slides"}**`;
+            if (pdf?.truncated) {
+                md += ` (first ${pdf.rendered_pages} of ${pdf.total_pages} pages — max 20)`;
+            }
+            md += `.\n\n`;
+            md += `| # | Slide Media ID |\n|---|----------------|\n`;
+            slides.forEach((s, i) => {
+                md += `| ${i + 1} | \`${s.id}\` |\n`;
+            });
+            md += `\n**Pass ALL of these to \`create_post\` as \`media_ids\`, in this order**, to post the deck as a carousel:\n\n`;
+            md += `\`\`\`\nmedia_ids: [${mediaIds.map((id) => `"${id}"`).join(", ")}]\n\`\`\`\n\n`;
+            md += `On LinkedIn this posts as a swipeable **document** carousel; on Instagram, TikTok, Threads and Pinterest as an **image** carousel. Platforms that do not support carousels use the first slide.`;
+            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 posting.`;
+            }
+            return { content: [{ type: "text", text: md }] };
+        }
+        const m = result.data;
         const isProcessing = m.status === "processing";
         let md = isProcessing ? `## Media Processing\n\n` : `## Media Uploaded\n\n`;
         md += `| Field | Value |\n`;

package/build/tools/posts.js

@@ -1,5 +1,40 @@
 import { z } from "zod";
-import { formatDateTime, truncate, capitalize } from "../client.js";
+import { formatDateTime, truncate, capitalize, formatNumber } 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
+// sanctioned comment API. Facebook/LinkedIn have no other API options today,
+// so these objects exist solely to carry `first_comment`.
+const FACEBOOK_OPTIONS = z
+    .object({
+    first_comment: z
+        .string()
+        .max(8000)
+        .optional()
+        .describe("Text auto-posted as the first comment on the Facebook post right after it publishes. Page posts only (the API cannot comment on personal-profile posts). Not posted for Stories."),
+})
+    .optional()
+    .describe("Facebook options");
+const LINKEDIN_OPTIONS = z
+    .object({
+    first_comment: z
+        .string()
+        .max(1250)
+        .optional()
+        .describe("Text auto-posted as the first comment on the LinkedIn Profile post right after it publishes. Common for 'link in first comment' to avoid the in-caption link reach penalty."),
+})
+    .optional()
+    .describe("LinkedIn Profile options");
+const LINKEDIN_PAGE_OPTIONS = z
+    .object({
+    first_comment: z
+        .string()
+        .max(1250)
+        .optional()
+        .describe("Text auto-posted as the first comment on the LinkedIn Company Page post right after it publishes."),
+})
+    .optional()
+    .describe("LinkedIn Company Page options");
 // Render full content for get_post — preserves per-platform overrides so Claude
 // can see custom captions (e.g. a shorter X version) instead of only `default`.
 function renderContent(content) {
@@ -43,6 +78,11 @@ function displayDate(p) {
 // or jump to a published post. Drafts and scheduled posts open in the editor
 // at /create-post/:id; published posts open in the details view at /posts/:id.
 function postAppUrl(p) {
+    // Prefer the server-provided app_url — it's built from the environment's
+    // client URL, so it's correct on staging/production. Fall back to a
+    // hardcoded production URL for older API responses that don't return it.
+    if (typeof p?.app_url === "string" && p.app_url)
+        return p.app_url;
     const id = p?.id;
     if (!id)
         return null;
@@ -152,6 +192,40 @@ export function registerPostTools(server, getClient) {
                 md += `\n`;
             }
         }
+        // Bluesky thread: when present, the canonical post text lives here, not in `content`.
+        const bskyThreadParts = Array.isArray(p.bluesky?.thread_parts)
+            ? p.bluesky.thread_parts
+            : [];
+        if (bskyThreadParts.length >= 2) {
+            md += `\n\n### Bluesky Thread (${bskyThreadParts.length} parts)\n\n`;
+            for (let i = 0; i < bskyThreadParts.length; i++) {
+                const part = bskyThreadParts[i] || {};
+                const text = typeof part.text === "string" ? part.text : "";
+                md += `**${i + 1}/${bskyThreadParts.length}.** ${text}\n`;
+                if (Array.isArray(part.media_urls) && part.media_urls.length) {
+                    for (const url of part.media_urls)
+                        md += `  - ${url}\n`;
+                }
+                md += `\n`;
+            }
+        }
+        // Mastodon thread: when present, the canonical status text lives here, not in `content`.
+        const mastoThreadParts = Array.isArray(p.mastodon?.thread_parts)
+            ? p.mastodon.thread_parts
+            : [];
+        if (mastoThreadParts.length >= 2) {
+            md += `\n\n### Mastodon Thread (${mastoThreadParts.length} parts)\n\n`;
+            for (let i = 0; i < mastoThreadParts.length; i++) {
+                const part = mastoThreadParts[i] || {};
+                const text = typeof part.text === "string" ? part.text : "";
+                md += `**${i + 1}/${mastoThreadParts.length}.** ${text}\n`;
+                if (Array.isArray(part.media_urls) && part.media_urls.length) {
+                    for (const url of part.media_urls)
+                        md += `  - ${url}\n`;
+                }
+                md += `\n`;
+            }
+        }
         const publishedUrls = (p.published_urls && typeof p.published_urls === "object" && !Array.isArray(p.published_urls))
             ? p.published_urls
             : {};
@@ -162,6 +236,23 @@ export function registerPostTools(server, getClient) {
                 md += `- **${capitalize(platform.replace(/_/g, " "))}**: ${url}\n`;
             }
         }
+        // First comments: nested under each platform object by the API. Show the
+        // configured text plus, once published, the outcome (posted/failed/skipped).
+        const firstCommentPlatforms = ["instagram", "facebook", "linkedin", "linkedin_page", "youtube"];
+        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())
+                continue;
+            const result = opts.first_comment_result;
+            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)}`);
+        }
+        if (firstCommentRows.length) {
+            md += `\n\n### First Comments\n\n${firstCommentRows.join("\n")}\n`;
+        }
         return {
             content: [{ type: "text", text: md }],
         };
@@ -250,13 +341,18 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             made_for_kids: z.boolean().optional(),
             notify_subscribers: z.boolean().optional(),
             contains_synthetic_media: z.boolean().optional(),
+            first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled."),
         }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
         instagram: z.object({
             share_to_feed: z.boolean().optional(),
             thumbnail_type: z.enum(["from-video", "from-library"]).optional(),
             thumb_offset: z.number().optional(),
             cover_url: z.string().optional(),
-        }).optional().describe("Instagram Reel options"),
+            first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Common for keeping hashtags out of the caption. Not posted for Stories."),
+        }).optional().describe("Instagram options"),
+        facebook: FACEBOOK_OPTIONS,
+        linkedin: LINKEDIN_OPTIONS,
+        linkedin_page: LINKEDIN_PAGE_OPTIONS,
         tiktok: z.object({
             privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
             disable_comment: z.boolean().optional(),
@@ -271,11 +367,25 @@ 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."),
         }).optional().describe("X (Twitter) options"),
+        bluesky: z.object({
+            thread_parts: z.array(z.object({
+                text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
+                media_ids: z.array(z.string()).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images."),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images."),
+            })).min(2).max(25).optional().describe("Publish as a chained Bluesky thread instead of a single post. Provide 2–25 parts; each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids (from upload_media) or media_urls — a part is one video OR up to 4 images. Links, mentions and hashtags are made clickable automatically. For a single post, omit thread_parts and use content."),
+        }).optional().describe("Bluesky options"),
+        mastodon: z.object({
+            thread_parts: z.array(z.object({
+                text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
+                media_ids: z.array(z.string()).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4)."),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-status media as external URLs (max 4)."),
+            })).min(2).max(25).optional().describe("Publish as a chained Mastodon thread instead of a single status. Provide 2–25 parts; each is posted in order as a native reply to the previous status (in_reply_to_id). Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part. For a single status, omit thread_parts and use content."),
+        }).optional().describe("Mastodon options"),
         google_business: z.object({
             topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional().describe("Local post type. Defaults to STANDARD. ALERT is reserved by Google and not exposed."),
             cta: z.object({
@@ -394,7 +504,14 @@ Do NOT call without required media — it will fail.`, {
             title: z.string().optional().describe("Short title shown on YouTube."),
             tags: z.array(z.string()).optional(),
             privacy_status: z.enum(["public", "private", "unlisted"]).optional(),
+            first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled."),
         }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
+        instagram: z.object({
+            first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Common for keeping hashtags out of the caption. Not posted for Stories."),
+        }).optional().describe("Instagram options"),
+        facebook: FACEBOOK_OPTIONS,
+        linkedin: LINKEDIN_OPTIONS,
+        linkedin_page: LINKEDIN_PAGE_OPTIONS,
         tiktok: z.object({
             privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
         }).optional().describe("TikTok options"),
@@ -403,11 +520,25 @@ 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."),
         }).optional().describe("X (Twitter) options"),
+        bluesky: z.object({
+            thread_parts: z.array(z.object({
+                text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
+                media_ids: z.array(z.string()).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images."),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images."),
+            })).min(2).max(25).optional().describe("Publish as a chained Bluesky thread (2–25 parts). Each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids or media_urls — one video OR up to 4 images per part. Links, mentions and hashtags are made clickable automatically."),
+        }).optional().describe("Bluesky options"),
+        mastodon: z.object({
+            thread_parts: z.array(z.object({
+                text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
+                media_ids: z.array(z.string()).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4)."),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-status media as external URLs (max 4)."),
+            })).min(2).max(25).optional().describe("Publish as a chained Mastodon thread (2–25 parts). Each is posted in order as a native reply (in_reply_to_id). Attach media to any part via media_ids or media_urls — max 4 per part."),
+        }).optional().describe("Mastodon options"),
         google_business: z.object({
             topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional(),
             cta: z.object({
@@ -493,6 +624,7 @@ Do NOT call without required media — it will fail.`, {
             made_for_kids: z.boolean().optional(),
             notify_subscribers: z.boolean().optional(),
             contains_synthetic_media: z.boolean().optional(),
+            first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled. Pass an empty string to clear a previously set first comment."),
         }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
         pinterest: z.object({
             board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
@@ -506,7 +638,11 @@ Do NOT call without required media — it will fail.`, {
             thumbnail_type: z.enum(["from-video", "from-library"]).optional(),
             thumb_offset: z.number().optional(),
             cover_url: z.string().optional(),
-        }).optional().describe("Instagram Reel options"),
+            first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Pass an empty string to clear a previously set first comment."),
+        }).optional().describe("Instagram options"),
+        facebook: FACEBOOK_OPTIONS,
+        linkedin: LINKEDIN_OPTIONS,
+        linkedin_page: LINKEDIN_PAGE_OPTIONS,
         tiktok: z.object({
             privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
             disable_comment: z.boolean().optional(),
@@ -521,11 +657,25 @@ 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."),
         }).optional().describe("X (Twitter) options"),
+        bluesky: z.object({
+            thread_parts: z.array(z.object({
+                text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
+                media_ids: z.array(z.string()).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images."),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images."),
+            })).min(2).max(25).nullable().optional().describe("Replace the Bluesky 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; one video OR up to 4 images per part), or `null` to revert to single-post mode."),
+        }).optional().describe("Bluesky options"),
+        mastodon: z.object({
+            thread_parts: z.array(z.object({
+                text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
+                media_ids: z.array(z.string()).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4)."),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-status media as external URLs (max 4)."),
+            })).min(2).max(25).nullable().optional().describe("Replace the Mastodon 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-status mode."),
+        }).optional().describe("Mastodon options"),
         google_business: z.object({
             topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional(),
             cta: z.object({
@@ -625,4 +775,56 @@ 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.", {
+        limit: z
+            .string()
+            .optional()
+            .describe("Max posts per connected platform (1-50, default 25)."),
+        platforms: z
+            .string()
+            .optional()
+            .describe('Optional comma-separated platform filter, e.g. "instagram,tiktok". Defaults to every connected platform.'),
+    }, async (params) => {
+        const result = await getClient().getRecentPlatformPosts(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const posts = result.data || [];
+        const connected = result.connected_platforms || [];
+        const errors = result.errors || {};
+        const errEntries = Object.entries(errors);
+        const clean = (s) => String(s || "").replace(/[|\n\r]+/g, " ").trim();
+        if (!posts.length) {
+            const note = result.note || "No recent platform posts found.";
+            const errLines = errEntries.map(([p, m]) => `- ${capitalize(p)}: ${m}`).join("\n");
+            return {
+                content: [{ type: "text", text: `${note}${errLines ? `\n\nFetch errors:\n${errLines}` : ""}` }],
+            };
+        }
+        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`;
+        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) : "—";
+            const date = p.timestamp ? formatDateTime(p.timestamp) : "—";
+            md += `| ${i + 1} | ${capitalize(p.platform)} | ${p.format || "post"} | ${content} | ${eng} | ${imp} | ${date} |\n`;
+        });
+        if (result.note)
+            md += `\n${result.note}\n`;
+        if (errEntries.length) {
+            md += `\n**Fetch errors:**\n`;
+            errEntries.forEach(([pl, m]) => {
+                md += `- ${capitalize(pl)}: ${m}\n`;
+            });
+        }
+        md += `\nPosts showing "—" for engagement have no metrics available from that platform for historical posts; analyze their captions and formats instead.\n`;
+        return {
+            content: [{ type: "text", text: md }],
+        };
+    });
 }

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

@@ -37,11 +37,32 @@ export interface Post {
 export interface MediaItem {
     id: string;
     url: string;
+    thumbnail_url?: string | null;
     type: string;
+    name?: string | null;
     filename: string;
-    size: number;
+    folder_id?: string | null;
+    size: string;
+    status?: string;
     created_at: string;
 }
+/**
+ * Extra top-level fields returned by /media/upload* when the uploaded file is a
+ * PDF. A PDF is rasterized into one image slide per page (max 20): `data`
+ * mirrors the first slide (back-compat), while `slides` + `media_ids` carry the
+ * whole carousel in page order. Pass ALL of `media_ids` to create_post. On
+ * LinkedIn the slides post as a native swipeable document; elsewhere as an
+ * image carousel.
+ */
+export interface PdfUploadResult {
+    slides: MediaItem[];
+    media_ids: string[];
+    pdf: {
+        total_pages: number;
+        rendered_pages: number;
+        truncated: boolean;
+    };
+}
 export interface Account {
     id: string;
     platform: string;
@@ -74,6 +95,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 {
@@ -82,12 +109,14 @@ export interface AnalyticsOverview {
     total_engagements: number;
     period: string;
 }
+export interface PostAnalyticsPlatformEntry {
+    platform: string;
+    platform_post_id: string;
+    metrics: Record<string, number | string>;
+    thread_parts: number;
+    collected_at: string;
+}
 export interface PostAnalytics {
     post_id: string;
-    impressions: number;
-    engagements: number;
-    likes: number;
-    comments: number;
-    shares: number;
-    platform_stats: Record<string, unknown>;
+    platforms: Record<string, PostAnalyticsPlatformEntry>;
 }

package/package.json

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