@omnisocials/mcp-server 1.3.0 → 1.3.1

package/build/client.d.ts

@@ -9,6 +9,27 @@ export declare function formatDate(iso: string | null): string;
 export declare function formatDateTime(iso: string | null): string;
 export declare function truncate(str: string, len: number): string;
 export declare function capitalize(str: string): string;
+export interface XThreadPartInput {
+    /** Tweet text — ≤ 280 chars (the API enforces 280 even for X Premium). */
+    text: string;
+    /** Optional per-part media URLs (max 4). Overrides top-level media_urls.x. */
+    media_urls?: string[];
+}
+export interface XPostOptions {
+    reply_settings?: "" | "following" | "mentionedUsers";
+    paid_partnership?: boolean;
+    made_with_ai?: boolean;
+    /** Provide 2–25 parts to publish as a thread. Omit for a single tweet. */
+    thread_parts?: XThreadPartInput[];
+}
+/**
+ * Update-side variant: passing `thread_parts: null` explicitly clears the
+ * thread shape on the post (reverting to single-tweet mode). Passing
+ * `undefined` (omit it) leaves the existing thread untouched.
+ */
+export interface XPostOptionsUpdate extends Omit<XPostOptions, "thread_parts"> {
+    thread_parts?: XThreadPartInput[] | null;
+}
 export declare class OmniSocialsClient {
     private baseUrl;
     private apiKey;
@@ -32,7 +53,7 @@ export declare class OmniSocialsClient {
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
         tiktok?: Record<string, unknown>;
-        x?: Record<string, unknown>;
+        x?: XPostOptions;
     }): Promise<ApiResponse<unknown>>;
     createAndPublishPost(data: {
         content: string | Record<string, string>;
@@ -45,7 +66,7 @@ export declare class OmniSocialsClient {
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
         tiktok?: Record<string, unknown>;
-        x?: Record<string, unknown>;
+        x?: XPostOptions;
     }): Promise<ApiResponse<unknown>>;
     updatePost(id: string, data: {
         content?: string | Record<string, string>;
@@ -58,7 +79,7 @@ export declare class OmniSocialsClient {
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
         tiktok?: Record<string, unknown>;
-        x?: Record<string, unknown>;
+        x?: XPostOptionsUpdate;
     }): Promise<ApiResponse<unknown>>;
     deletePost(id: string): Promise<ApiResponse<unknown>>;
     publishPost(id: string): Promise<ApiResponse<unknown>>;

package/build/tools/posts.js

@@ -1,7 +1,25 @@
 import { z } from "zod";
 import { formatDateTime, truncate, capitalize } from "../client.js";
+// 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) {
+    if (!content)
+        return "(empty)";
+    if (typeof content === "string")
+        return content;
+    if (typeof content !== "object")
+        return "(empty)";
+    const entries = Object.entries(content).filter(([, v]) => typeof v === "string" && v);
+    if (!entries.length)
+        return "(empty)";
+    if (entries.length === 1)
+        return entries[0][1];
+    return entries
+        .map(([key, value]) => `**${key === "default" ? "Default (fallback)" : capitalize(key.replace(/_/g, " "))}**\n\n${value}`)
+        .join("\n\n---\n\n");
+}
 export function registerPostTools(server, getClient) {
-    server.tool("list_posts", "List all posts in the workspace. Optionally filter by status.", {
+    server.tool("list_posts", "List all posts in the workspace. Optionally filter by status. The content column shows a preview of the default caption; if a post has per-platform overrides (e.g. a custom X version), the preview is suffixed with *(per-platform)* — call `get_post` to see every variant.", {
         status: z.string().optional().describe("Filter by status: draft, scheduled, published, failed"),
         limit: z.string().optional().describe("Max results to return (default: 20)"),
         offset: z.string().optional().describe("Offset for pagination"),
@@ -24,10 +42,21 @@ export function registerPostTools(server, getClient) {
         md += `|---|---------|----------|--------|------|----|\n`;
         for (let i = 0; i < posts.length; i++) {
             const p = posts[i];
-            const rawContent = typeof p.content === "object" && p.content !== null
+            const isObj = typeof p.content === "object" && p.content !== null;
+            const rawContent = isObj
                 ? (p.content.default || Object.values(p.content).find((v) => typeof v === "string" && v) || "")
                 : (p.content || "");
-            const content = truncate(rawContent, 50);
+            const hasOverrides = isObj && Object.keys(p.content).filter((k) => k !== "default" && typeof p.content[k] === "string" && p.content[k]).length > 0;
+            const threadParts = Array.isArray(p.x?.thread_parts) ? p.x.thread_parts : [];
+            const isThread = threadParts.length >= 2;
+            let content;
+            if (isThread && !rawContent) {
+                const first = typeof threadParts[0]?.text === "string" ? threadParts[0].text : "";
+                content = truncate(first, 32) + ` *(X thread, ${threadParts.length} parts)*`;
+            }
+            else {
+                content = truncate(rawContent, hasOverrides ? 35 : 50) + (hasOverrides ? " *(per-platform)*" : "");
+            }
             const channels = (p.channels || []).join(", ");
             const status = capitalize(p.status || "—");
             const date = p.scheduled_at
@@ -41,7 +70,7 @@ export function registerPostTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("get_post", "Get details of a specific post by ID.", {
+    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.", {
         id: z.string().describe("The post ID"),
     }, async ({ id }) => {
         const result = await getClient().getPost(id);
@@ -71,7 +100,34 @@ export function registerPostTools(server, getClient) {
         if (p.media?.length) {
             md += `| **Media** | ${p.media.length} file(s) |\n`;
         }
-        md += `\n### Content\n\n${p.content || "(empty)"}`;
+        md += `\n### Content\n\n${renderContent(p.content)}`;
+        // 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
+            : [];
+        if (threadParts.length >= 2) {
+            md += `\n\n### X Thread (${threadParts.length} parts)\n\n`;
+            for (let i = 0; i < threadParts.length; i++) {
+                const part = threadParts[i] || {};
+                const text = typeof part.text === "string" ? part.text : "";
+                md += `**${i + 1}/${threadParts.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
+            : {};
+        const urlEntries = Object.entries(publishedUrls);
+        if (urlEntries.length) {
+            md += `\n\n### Published URLs\n\n`;
+            for (const [platform, url] of urlEntries) {
+                md += `- **${capitalize(platform.replace(/_/g, " "))}**: ${url}\n`;
+            }
+        }
         return {
             content: [{ type: "text", text: md }],
         };
@@ -80,6 +136,7 @@ export function registerPostTools(server, getClient) {
 
 IMPORTANT — Before calling this tool, make sure you have all required information from the user. If anything is missing, ASK the user before calling:
 
+0. **Workspace**: If the user has only one workspace, just use it (no need to ask). If the user has multiple workspaces and has NOT named one in their request, call list_workspaces and ask which workspace to post to before calling this tool. If the user has named a workspace, switch to it once and remember the choice for the rest of the conversation. Never silently pick a workspace when more than one exists. After a successful create/schedule, mention the workspace name in your reply to the user for clarity (e.g. "Scheduled to the Acme workspace for Tuesday 3pm").
 1. **Content/caption**: What text should the post have? If captions differ per platform, use one call with an object: { "default": "fallback text", "linkedin": "long version", "threads": "short version" }. Always prefer one call per topic.
 2. **Channels**: Which platforms to post to? Use list_accounts to show available options if needed.
 3. **Schedule**: When should it be published? (Or save as draft?)
@@ -94,6 +151,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - Pinterest: Which board? Any link to attach?
    - YouTube: Title, privacy status, tags?
    - TikTok: Privacy level?
+   - **X threads**: When the user asks for an X/Twitter "thread" (or anything that exceeds 280 chars on X), DO NOT cram it into \`content\` with "1/", "2/" prefixes. Instead pass \`x.thread_parts\` as an array of 2–25 \`{ text }\` objects (each ≤ 280 chars). The \`content\` field is then ignored for X. For a single tweet, omit \`thread_parts\` and use \`content\` normally.
 
 Do NOT call this tool without media when creating stories, reels, Instagram posts, TikTok posts, or Pinterest posts — it will fail.
 
@@ -140,6 +198,12 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         }).optional().describe("TikTok options"),
         x: z.object({
             reply_settings: z.enum(["", "following", "mentionedUsers"]).optional(),
+            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)"),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media URLs (max 4)"),
+            })).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. Per-part media_urls override top-level media for that specific tweet. For a single tweet, omit thread_parts and use content."),
         }).optional().describe("X (Twitter) options"),
     }, async (params) => {
         const result = await getClient().createPost({ ...params, source: "mcp" });
@@ -167,6 +231,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
 
 IMPORTANT — Before calling this tool, make sure you have all required information. If anything is missing, ASK the user first:
 
+0. **Workspace**: If the user has only one workspace, just use it (no need to ask). If the user has multiple workspaces and has NOT named one, call list_workspaces and ask before publishing. If the user has named a workspace, switch to it once and remember it. Never silently pick a workspace when more than one exists — published posts are public. After publishing, mention the workspace name in your reply (e.g. "Published to the Acme workspace LinkedIn Page").
 1. **Content/caption**: What text? If captions differ per platform, use one call with an object: { "default": "fallback", "linkedin": "long", "threads": "short" }.
 2. **Channels**: Which platforms? Use list_accounts if needed.
 3. **Media** (REQUIRED for some types — same rules as create_post):
@@ -175,6 +240,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - Instagram/TikTok posts: ALWAYS need at least one image or video.
    - Pinterest: ALWAYS need an image + board_id.
    - Ask the user which media to use. Use list_media to show options.
+4. **X threads**: When the user asks for an X/Twitter "thread" (or anything > 280 chars on X), pass \`x.thread_parts\` as a 2–25 entry array of \`{ text }\` objects. Do NOT split into "1/", "2/" inside \`content\` — that produces a single tweet, not a thread.
 
 Do NOT call without required media — it will fail.`, {
         content: z.union([z.string(), z.record(z.string(), z.string())]).describe("Post caption. String for same text on all channels, or object with platform keys for per-channel captions: { \"default\": \"fallback\", \"linkedin\": \"long version\", \"threads\": \"short version\" }. The \"default\" key is used for any selected channel without its own key."),
@@ -201,6 +267,15 @@ Do NOT call without required media — it will fail.`, {
         tiktok: z.object({
             privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
         }).optional().describe("TikTok options"),
+        x: z.object({
+            reply_settings: z.enum(["", "following", "mentionedUsers"]).optional(),
+            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)"),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media URLs (max 4)"),
+            })).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. Per-part media_urls override top-level media."),
+        }).optional().describe("X (Twitter) options"),
     }, async (params) => {
         const result = await getClient().createAndPublishPost({ ...params, source: "mcp" });
         if (result.error) {
@@ -221,7 +296,9 @@ Do NOT call without required media — it will fail.`, {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("update_post", "Update an existing post. Only draft and scheduled posts can be updated.", {
+    server.tool("update_post", `Update an existing post. Only draft and scheduled posts can be updated.
+
+**X threads**: To convert an existing draft into a chained X thread, pass \`x.thread_parts\` as a 2–25 entry array of \`{ text }\` objects (each ≤ 280 chars). Pass \`null\` to revert to single-tweet mode. Do NOT shove "1/", "2/" into \`content\` — that's a single tweet, not a thread.`, {
         id: z.string().describe("The post ID to update"),
         content: z.union([z.string(), z.record(z.string(), z.string())]).optional().describe("Updated post content. String or object with platform keys: { \"default\": \"fallback\", \"linkedin\": \"long\" }."),
         scheduled_at: z.string().optional().describe("Updated scheduled date (ISO 8601)"),
@@ -234,6 +311,15 @@ Do NOT call without required media — it will fail.`, {
             z.array(z.string()),
             z.record(z.string(), z.array(z.string())),
         ]).optional().describe("External URLs — flat array or per-platform object. Max 10 total. 'default' key is fallback for platforms without their own key. Empty array opts out."),
+        x: z.object({
+            reply_settings: z.enum(["", "following", "mentionedUsers"]).optional(),
+            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)"),
+                media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media URLs (max 4)"),
+            })).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, or `null` to revert to single-tweet mode."),
+        }).optional().describe("X (Twitter) options"),
     }, async ({ id, ...data }) => {
         const result = await getClient().updatePost(id, data);
         if (result.error) {

package/build/tools/workspaces.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export function registerWorkspaceTools(server, workspaceClients, sessionState) {
-    server.tool("list_workspaces", "List all workspaces available in this session. Each workspace corresponds to an API key provided at connection time. Shows which workspace is currently active.", {}, async () => {
+    server.tool("list_workspaces", "List all workspaces available in this session. Each workspace corresponds to an API key provided at connection time. Shows which workspace is currently active. Workspace selection rule: if only one workspace is available, just use it (no need to ask). If the user has named a workspace in their request (e.g. 'post to my Acme workspace'), proceed with that workspace and remember it for the rest of the conversation. If multiple workspaces exist and the user has NOT named one, call this tool, present the list, and ASK the user which one to use before posting, switching, or fetching analytics. After a successful action, mention the workspace name in your reply for clarity.", {}, async () => {
         const workspaces = await Promise.all(workspaceClients.map(async (wc, index) => {
             try {
                 const result = await wc.client.listAccounts();
@@ -39,7 +39,7 @@ export function registerWorkspaceTools(server, workspaceClients, sessionState) {
         md += `\nUse **switch_workspace** with the workspace number to change the active workspace.`;
         return { content: [{ type: "text", text: md }] };
     });
-    server.tool("switch_workspace", "Switch the active workspace. All subsequent tool calls (posts, media, analytics, etc.) will operate on the selected workspace. Use list_workspaces first to see available options.", {
+    server.tool("switch_workspace", "Switch the active workspace. All subsequent tool calls (posts, media, analytics, etc.) will operate on the selected workspace. Only call this when the user has explicitly named the target workspace, or after the user has picked one from list_workspaces. Never call switch_workspace silently when the user hasn't specified a workspace — ask first.", {
         workspace_number: z.string().describe("The workspace number from list_workspaces (1, 2, 3, etc.)"),
     }, async ({ workspace_number }) => {
         const index = parseInt(workspace_number, 10) - 1;

package/build/types.d.ts

@@ -14,6 +14,17 @@ export interface Post {
     channels: string[];
     media: string[];
     created_at: string;
+    x?: {
+        reply_settings?: string;
+        paid_partnership?: boolean;
+        made_with_ai?: boolean;
+        thread_parts?: Array<{
+            id?: string;
+            text: string;
+            media_urls?: string[];
+        }>;
+        [key: string]: unknown;
+    };
 }
 export interface MediaItem {
     id: string;

package/package.json

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