@omnisocials/mcp-server 1.12.0 → 1.13.1

package/README.md

@@ -173,6 +173,17 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | `delete_webhook` | Delete a webhook |
 | `rotate_webhook_secret` | Rotate a webhook's signing secret |
 
+### Social Inbox (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_inbox_conversations` | List conversations — Instagram/Facebook DMs, comments, mentions, and LinkedIn company-page comments/mentions; filter by platform, type, or unread |
+| `get_inbox_conversation` | Get a conversation's full message history |
+| `mark_inbox_read` | Mark all incoming messages in a conversation as read |
+| `reply_to_inbox` | Reply to a DM, comment, or mention (existing conversations only) |
+
+Requires an API key with the opt-in `inbox:read` / `inbox:write` scopes — enable "Social Inbox access" when you create the key.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -196,6 +207,50 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 
 ## Changelog
 
+### 1.13.1
+
+- Docs-only republish to refresh the README on npmjs.com — the changelog below had drifted (it stopped at 1.5.0) and the Social Inbox tools were missing from the tool list. No code changes from 1.13.0.
+
+### 1.13.0
+
+- **Added: Social Inbox tools** — `list_inbox_conversations`, `get_inbox_conversation`, `mark_inbox_read`, `reply_to_inbox`. Read and reply to Instagram and Facebook DMs, comments, and mentions, plus LinkedIn company-page comments and mentions (LinkedIn has no API DMs). Cursor-paginated with platform/type/unread filters. Replies work only on existing conversations (no cold outreach); direct-message replies must be within the platform's 24-hour window, and each workspace can send up to 1,000 replies per day. Requires the opt-in `inbox:read` / `inbox:write` scopes (enable "Social Inbox access" when creating the key). Same tools on the companion server (`mcp.omnisocials.com`).
+
+### 1.12.0
+
+- **Added: Instagram Trial Reels** — `instagram.is_trial_reel` (plus `trial_graduation_strategy`) on `create_post` / `create_and_publish_post` / `update_post`; the reel is shown to non-followers first. Requires roughly 1,000+ followers and per-account eligibility.
+- **Added: reel music** — `instagram.audio_id` attaches licensed audio to a reel; the new `search_instagram_audio` tool finds tracks and returns their `audio_id`.
+- **Changed:** `update_post` Instagram options now MERGE into the stored options instead of replacing them, so updating one option no longer clears others.
+
+### 1.11.0
+
+- **Fixed:** `get_post_analytics` and `get_posts_analytics` now render every metric the platform reports (reach, saves, views, and more) instead of a fixed column set that silently dropped some.
+
+### 1.10.0
+
+- **Added:** `get_best_times` — best times to post for the workspace, per platform, from historical engagement.
+- **Added:** YouTube cover support plus media order and thumbnail fixes in `create_post` / `update_post`.
+
+### 1.9.0
+
+- Maintenance release aligned with a backend upload-media fix; existing clients benefit automatically once the backend deploys. No MCP tool changes.
+
+### 1.8.0
+
+- **Added:** `get_posts_analytics` — the latest per-platform metrics for up to 100 posts in a single (bulk) call.
+- **Added:** upload a PDF as a carousel via `upload_media` — rasterized into one slide per page (max 20); posts as a native swipeable document on LinkedIn and an image carousel elsewhere.
+
+### 1.7.1
+
+- **Changed:** clearer guidance for files over 100 MB — base64/direct uploads cap at 100 MB; for up to 1 GB pass a public `url` or use the Library UI. Also fixes a stray " B" in `list_media` size output.
+
+### 1.7.0
+
+- **Changed:** `switch_workspace` now switches by workspace **name** (id or list position also accepted); `list_workspaces` leads with names. Fixes posts landing in the wrong workspace when the list order changed.
+
+### 1.6.0
+
+- **Added:** media library names, search, and folders — `name` / `folder` on `upload_media`, `search` / `folder_id` on `list_media`, plus `update_media`, `list_folders`, and `create_folder`.
+
 ### 1.5.0
 
 - **Added:** Attach uploaded media to any tweet in an X thread. `x.thread_parts[]` now accepts `media_ids` (the same numeric Library IDs returned by `upload_media`) on any part, first tweet or reply, alongside the existing `media_urls`. Combined cap is 4 media per part. This makes graphic-led threads possible without self-hosting image URLs: for example a graphic on the first tweet and the signup link alone in a reply (which keeps the first tweet's reach). Companion server change: media attached to the parent post was previously dropped in thread mode and is now folded into the first tweet.

package/build/client.d.ts

@@ -1,4 +1,4 @@
-import type { ApiResponse, MediaItem, PdfUploadResult } from "./types.js";
+import type { ApiResponse, MediaItem, PdfUploadResult, InboxConversation, InboxMessage } from "./types.js";
 export declare function fetchImageAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
@@ -264,4 +264,21 @@ export declare class OmniSocialsClient {
         is_active?: boolean;
     }): Promise<ApiResponse<unknown>>;
     rotateWebhookSecret(id: string): Promise<ApiResponse<unknown>>;
+    listInboxConversations(params?: {
+        platform?: string;
+        type?: string;
+        unread?: string;
+        limit?: string;
+        cursor?: string;
+    }): Promise<ApiResponse<InboxConversation[]>>;
+    getInboxMessages(conversationId: string, params?: {
+        limit?: string;
+        cursor?: string;
+    }): Promise<ApiResponse<InboxMessage[]>>;
+    markInboxRead(conversationId: string): Promise<ApiResponse<unknown>>;
+    replyToInboxConversation(conversationId: string, data: {
+        text: string;
+        attachment_url?: string;
+        attachment_type?: string;
+    }): Promise<ApiResponse<InboxMessage>>;
 }

package/build/client.js

@@ -318,4 +318,18 @@ export class OmniSocialsClient {
     async rotateWebhookSecret(id) {
         return this.request("POST", `/webhooks/${id}/rotate-secret`);
     }
+    // Inbox — conversation ids can contain ":" and "()" (LinkedIn URNs), so any
+    // path segment built from one must be URL-encoded.
+    async listInboxConversations(params) {
+        return this.request("GET", "/inbox/conversations", undefined, params);
+    }
+    async getInboxMessages(conversationId, params) {
+        return this.request("GET", `/inbox/conversations/${encodeURIComponent(conversationId)}/messages`, undefined, params);
+    }
+    async markInboxRead(conversationId) {
+        return this.request("POST", `/inbox/conversations/${encodeURIComponent(conversationId)}/read`);
+    }
+    async replyToInboxConversation(conversationId, data) {
+        return this.request("POST", `/inbox/conversations/${encodeURIComponent(conversationId)}/reply`, data);
+    }
 }

package/build/index.js

@@ -8,6 +8,7 @@ import { registerMediaTools } from "./tools/media.js";
 import { registerAccountTools } from "./tools/accounts.js";
 import { registerAnalyticsTools } from "./tools/analytics.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
+import { registerInboxTools } from "./tools/inbox.js";
 import { registerWorkspaceTools } from "./tools/workspaces.js";
 const apiKeyEnv = process.env.OMNISOCIALS_API_KEY;
 if (!apiKeyEnv) {
@@ -27,7 +28,7 @@ const sessionState = { activeIndex: 0 };
 const getActiveClient = () => workspaceClients[sessionState.activeIndex].client;
 const server = new McpServer({
     name: "OmniSocials",
-    version: "1.12.0",
+    version: "1.13.1",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);
@@ -35,6 +36,7 @@ registerMediaTools(server, getActiveClient);
 registerAccountTools(server, getActiveClient);
 registerAnalyticsTools(server, getActiveClient);
 registerWebhookTools(server, getActiveClient);
+registerInboxTools(server, getActiveClient);
 registerWorkspaceTools(server, workspaceClients, sessionState);
 // Register prompts
 server.prompt("weekly-report", "Generate a weekly social media performance report", {}, async () => ({

package/build/tools/inbox.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OmniSocialsClient } from "../client.js";
+export declare function registerInboxTools(server: McpServer, getClient: () => OmniSocialsClient): void;

package/build/tools/inbox.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { formatDateTime } from "../client.js";
+const PLATFORM_EMOJI = {
+    instagram: "📸",
+    facebook: "📘",
+    linkedin: "💼",
+};
+export function registerInboxTools(server, getClient) {
+    server.tool("list_inbox_conversations", "List social inbox conversations (Instagram/Facebook DMs, comments, mentions, and LinkedIn company-page comments/mentions), newest activity first. Cursor-paginated: pass the returned cursor to get the next page.", {
+        platform: z
+            .enum(["instagram", "facebook", "linkedin"])
+            .optional()
+            .describe("Filter to one platform"),
+        type: z
+            .enum(["dm", "comment", "mention"])
+            .optional()
+            .describe("Filter to one conversation type"),
+        unread: z
+            .boolean()
+            .optional()
+            .describe("Only conversations with unread incoming messages"),
+        limit: z
+            .number()
+            .optional()
+            .describe("Max conversations per page (1-100, default 25)"),
+        cursor: z
+            .string()
+            .optional()
+            .describe("Pagination cursor from a previous response"),
+    }, async (params) => {
+        const query = {};
+        if (params.platform)
+            query.platform = params.platform;
+        if (params.type)
+            query.type = params.type;
+        if (params.unread !== undefined)
+            query.unread = String(params.unread);
+        if (params.limit !== undefined)
+            query.limit = String(params.limit);
+        if (params.cursor)
+            query.cursor = params.cursor;
+        const result = await getClient().listInboxConversations(query);
+        if (result.error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error (${result.error.code}): ${result.error.message}`,
+                    },
+                ],
+            };
+        }
+        const convos = result.data || [];
+        if (!convos.length) {
+            return {
+                content: [{ type: "text", text: "No conversations found." }],
+            };
+        }
+        let md = `## Inbox Conversations (${convos.length})\n\n`;
+        md += `| Platform | Type | From | Unread | Latest message | Conversation ID |\n`;
+        md += `|----------|------|------|--------|----------------|----------------|\n`;
+        for (const c of convos) {
+            const who = c.participant?.name || c.participant?.username || "Unknown";
+            const text = (c.last_message?.text || "").replace(/\n/g, " ").slice(0, 40);
+            md += `| ${PLATFORM_EMOJI[c.platform] || ""} ${c.platform} | ${c.type} | ${who} | ${c.unread_count || 0} | ${text} | \`${c.conversation_id}\` |\n`;
+        }
+        if (result.pagination?.next_cursor) {
+            md += `\n_More available — call list_inbox_conversations again with cursor "${result.pagination.next_cursor}"._`;
+        }
+        return { content: [{ type: "text", text: md }] };
+    });
+    server.tool("get_inbox_conversation", "Get the full message history of one inbox conversation, oldest first. Use the conversation_id from list_inbox_conversations.", {
+        conversation_id: z.string().describe("The conversation ID to fetch"),
+        limit: z
+            .number()
+            .optional()
+            .describe("Max messages per page (1-100, default 50)"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+    }, async ({ conversation_id, limit, cursor }) => {
+        const query = {};
+        if (limit !== undefined)
+            query.limit = String(limit);
+        if (cursor)
+            query.cursor = cursor;
+        const result = await getClient().getInboxMessages(conversation_id, query);
+        if (result.error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error (${result.error.code}): ${result.error.message}`,
+                    },
+                ],
+            };
+        }
+        const msgs = result.data || [];
+        if (!msgs.length) {
+            return {
+                content: [
+                    { type: "text", text: "No messages in this conversation." },
+                ],
+            };
+        }
+        let md = `## Conversation \`${conversation_id}\`\n\n`;
+        for (const m of msgs) {
+            const who = m.direction === "outgoing"
+                ? "→ You"
+                : `← ${m.sender?.name || m.sender?.username || "Them"}`;
+            md += `**${who}** _(${formatDateTime(m.timestamp)})_\n${m.text || ""}\n\n`;
+        }
+        if (result.pagination?.next_cursor) {
+            md += `_More messages — call again with cursor "${result.pagination.next_cursor}"._`;
+        }
+        return { content: [{ type: "text", text: md }] };
+    });
+    server.tool("mark_inbox_read", "Mark all incoming messages in a conversation as read.", {
+        conversation_id: z.string().describe("The conversation ID to mark read"),
+    }, async ({ conversation_id }) => {
+        const result = await getClient().markInboxRead(conversation_id);
+        if (result.error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error (${result.error.code}): ${result.error.message}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Marked ${result.marked_read ?? 0} message(s) as read in \`${conversation_id}\`.`,
+                },
+            ],
+        };
+    });
+    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, or LinkedIn. You can only reply to conversations that already exist. Direct-message replies must be within the platform's 24-hour messaging window. Each workspace can send up to 1,000 replies per day.", {
+        conversation_id: z.string().describe("The conversation ID to reply to"),
+        text: z.string().describe("The reply text (max 2000 characters)"),
+    }, async ({ conversation_id, text }) => {
+        const result = await getClient().replyToInboxConversation(conversation_id, {
+            text,
+        });
+        if (result.error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error (${result.error.code}): ${result.error.message}`,
+                    },
+                ],
+            };
+        }
+        const m = result.data;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Reply sent to \`${conversation_id}\`${m?.platform ? ` on ${m.platform}` : ""}.`,
+                },
+            ],
+        };
+    });
+}

package/build/tools/posts.js

@@ -885,7 +885,7 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
         });
         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` 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.", {
+    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. Output is a human-readable summary table PLUS a 'Structured data' JSON block carrying, for every post, the platform's own post id (the stable dedupe key), a permalink, the FULL untruncated caption, and exact-integer metrics — use that block when ingesting or storing native posts rather than the rounded/truncated table. Requires the analytics:read scope.", {
         limit: z
             .string()
             .optional()
@@ -938,6 +938,25 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
             });
         }
         md += `\nPosts showing "—" for engagement have no metrics available from that platform for historical posts; analyze their captions and formats instead.\n`;
+        // The table above is rounded + truncated for a human skim. Anything
+        // storing/ingesting these posts needs the raw fields: the platform's own
+        // post id (dedupe key), permalink, the FULL caption, and exact-integer
+        // metrics. Emit them as a machine-readable JSON block.
+        const records = posts.map((p) => ({
+            platform: p.platform,
+            id: p.id ?? null,
+            permalink: p.permalink ?? null,
+            text: p.text ?? "",
+            format: p.format ?? "post",
+            media_count: p.media_count ?? 1,
+            timestamp: p.timestamp ?? null,
+            image_url: p.image_url ?? null,
+            engagement: p.engagement ?? null,
+            impressions: p.impressions ?? null,
+            engagement_rate: p.engagement_rate ?? null,
+            metrics: p.metrics || {},
+        }));
+        md += `\n### Structured data\nFull records for storing/ingesting each post — exact-integer metrics, the platform's own post \`id\` (dedupe key), \`permalink\`, and the complete untruncated caption:\n\n\`\`\`json\n${JSON.stringify(records, null, 2)}\n\`\`\`\n`;
         return {
             content: [{ type: "text", text: md }],
         };

package/build/types.d.ts

@@ -4,6 +4,57 @@ export interface ApiResponse<T = unknown> {
         code: string;
         message: string;
     };
+    pagination?: {
+        next_cursor: string | null;
+        has_more: boolean;
+        limit: number;
+    };
+    conversation_id?: string;
+    marked_read?: number;
+}
+export interface InboxParticipant {
+    id: string;
+    name: string;
+    username: string;
+    profile_picture: string | null;
+}
+export interface InboxConversation {
+    conversation_id: string;
+    platform: "instagram" | "facebook" | "linkedin";
+    type: "dm" | "comment" | "mention";
+    participant: InboxParticipant;
+    unread_count: number;
+    last_message: {
+        id: string;
+        direction: "incoming" | "outgoing";
+        text: string;
+        timestamp: string;
+        is_read: boolean;
+    };
+    post: {
+        id: string | null;
+        caption: string | null;
+        thumbnail: string | null;
+    } | null;
+}
+export interface InboxMessage {
+    id: string;
+    conversation_id: string;
+    platform: string;
+    type: "dm" | "comment" | "mention";
+    direction: "incoming" | "outgoing";
+    text: string;
+    timestamp: string;
+    is_read: boolean;
+    is_replied: boolean;
+    reaction: string | null;
+    parent_comment_id: string | null;
+    sender: InboxParticipant;
+    post: {
+        id: string | null;
+        caption: string | null;
+        thumbnail: string | null;
+    } | null;
 }
 export interface Post {
     id: string;

package/package.json

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