@omnisocials/mcp-server 1.0.3 → 1.1.0

package/README.md

@@ -130,6 +130,16 @@ Add to your `~/.codeium/windsurf/mcp_config.json`:
 | `OMNISOCIALS_API_KEY` | Yes | Your API key (`omsk_live_*` or `omsk_test_*`) |
 | `OMNISOCIALS_BASE_URL` | No | Custom API base URL (defaults to production) |
 
+## Alternative: Agent Skills
+
+For broader AI agent compatibility (works with Cursor, Windsurf, Codex, Gemini CLI, GitHub Copilot, and more), you can also use the OmniSocials Agent Skills package:
+
+```bash
+npx skills add OmniSocials/omnisocials-agent-skills
+```
+
+The agent-skills package uses a CLI + SKILL.md approach that works in any AI coding tool, not just MCP-compatible ones. See [omnisocials-agent-skills on GitHub](https://github.com/OmniSocials/omnisocials-agent-skills) for details.
+
 ## API Documentation
 
 Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)

package/build/client.d.ts

@@ -1,4 +1,14 @@
 import type { ApiResponse } from "./types.js";
+export declare function fetchImageAsBase64(url: string): Promise<{
+    data: string;
+    mimeType: string;
+} | null>;
+export declare function formatNumber(n: number): string;
+export declare function formatBytes(bytes: number): string;
+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 declare class OmniSocialsClient {
     private baseUrl;
     private apiKey;

package/build/client.js

@@ -1,3 +1,68 @@
+// ─── Image Helper ───────────────────────────────────────────────────────────
+export async function fetchImageAsBase64(url) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 3000);
+        const response = await fetch(url, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!response.ok)
+            return null;
+        const buffer = await response.arrayBuffer();
+        const base64 = Buffer.from(buffer).toString("base64");
+        const mimeType = response.headers.get("content-type") || "image/png";
+        return { data: base64, mimeType };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Formatting Helpers ─────────────────────────────────────────────────────
+export function formatNumber(n) {
+    if (n >= 1_000_000)
+        return (n / 1_000_000).toFixed(1).replace(/\.0$/, "") + "M";
+    if (n >= 1_000)
+        return (n / 1_000).toFixed(1).replace(/\.0$/, "") + "K";
+    return n.toString();
+}
+export function formatBytes(bytes) {
+    if (bytes >= 1_000_000)
+        return (bytes / 1_000_000).toFixed(1) + " MB";
+    if (bytes >= 1_000)
+        return (bytes / 1_000).toFixed(1) + " KB";
+    return bytes + " B";
+}
+export function formatDate(iso) {
+    if (!iso)
+        return "—";
+    const d = new Date(iso);
+    return d.toLocaleDateString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+    });
+}
+export function formatDateTime(iso) {
+    if (!iso)
+        return "—";
+    const d = new Date(iso);
+    return d.toLocaleDateString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        timeZoneName: "short",
+    });
+}
+export function truncate(str, len) {
+    if (!str)
+        return "";
+    const clean = str.replace(/\n/g, " ");
+    return clean.length > len ? clean.slice(0, len - 1) + "…" : clean;
+}
+export function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
 export class OmniSocialsClient {
     baseUrl;
     apiKey;

package/build/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
 import { OmniSocialsClient } from "./client.js";
 import { registerPostTools } from "./tools/posts.js";
 import { registerMediaTools } from "./tools/media.js";
@@ -25,6 +26,44 @@ registerMediaTools(server, client);
 registerAccountTools(server, client);
 registerAnalyticsTools(server, client);
 registerWebhookTools(server, client);
+// Register prompts
+server.prompt("weekly-report", "Generate a weekly social media performance report", {}, async () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: "Give me a comprehensive social media performance report for the last 7 days. Include:\n\n1. Analytics overview (impressions, engagements, engagement rate)\n2. Platform-by-platform breakdown\n3. Account analytics (follower counts)\n4. Key observations and recommendations\n\nUse the get_analytics_overview (period: 7d) and get_account_analytics tools to gather the data, then present it in a clear, well-formatted report.",
+            },
+        },
+    ],
+}));
+server.prompt("create-campaign", "Create a multi-platform social media campaign", {
+    topic: z.string().describe("What the campaign is about"),
+}, async ({ topic }) => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: `Help me create a social media campaign about: ${topic}\n\nPlease:\n1. First, list my connected accounts so we know which platforms are available\n2. Draft tailored content for each platform (respecting character limits and best practices)\n3. Suggest optimal scheduling times\n4. Ask me to review before creating any posts\n\nDon't create any posts until I've approved the content.`,
+            },
+        },
+    ],
+}));
+server.prompt("schedule-week", "Plan and schedule a week of social media content", {
+    theme: z.string().optional().describe("Optional theme or focus for the week's content"),
+}, async ({ theme }) => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: `Help me plan and schedule social media content for the upcoming week${theme ? ` with a focus on: ${theme}` : ""}.\n\nPlease:\n1. List my connected accounts\n2. Check what's already scheduled\n3. Suggest 5-7 posts spread across the week\n4. For each post, specify: content, platforms, suggested date/time\n5. Wait for my approval before creating any posts\n\nConsider platform best practices and vary content types.`,
+            },
+        },
+    ],
+}));
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

package/build/tools/accounts.js

@@ -1,17 +1,100 @@
 import { z } from "zod";
+import { fetchImageAsBase64, capitalize } from "../client.js";
 export function registerAccountTools(server, client) {
-    server.tool("list_accounts", "List all connected social media accounts in the workspace.", {}, async () => {
+    server.tool("list_accounts", "List all connected social media accounts in the workspace. Each account includes its platform, display name, channel ID (used for create_post), and supported content_types (post, story, reel). Pinterest accounts also include a `boards` array with `{id, name}` — use the board `id` as `board_id` when creating Pinterest posts. X accounts with Premium include `platform_details` with `subscription_type` (e.g. \"Premium\", \"PremiumPlus\"). Call this to help users pick which platforms to post to.", {}, async () => {
         const result = await client.listAccounts();
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const accounts = Array.isArray(result.data) ? result.data : result.data?.accounts || [];
+        if (!accounts.length) {
+            return {
+                content: [{ type: "text", text: "No connected accounts found." }],
+            };
+        }
+        // Build markdown table
+        let md = `## Connected Accounts (${accounts.length})\n\n`;
+        md += `| # | Platform | Account | Content Types | Channel ID |\n`;
+        md += `|---|----------|---------|---------------|------------|\n`;
+        for (let i = 0; i < accounts.length; i++) {
+            const a = accounts[i];
+            const name = a.username ? `@${a.username}` : a.display_name || "—";
+            const types = (a.content_types || []).join(", ");
+            const platform = capitalize(a.platform);
+            const sub = a.platform_details?.subscription_type && a.platform_details.subscription_type !== "None"
+                ? ` (${a.platform_details.subscription_type})`
+                : "";
+            md += `| ${i + 1} | ${platform}${sub} | ${name} | ${types} | \`${a.id}\` |\n`;
+        }
+        md += `\nUse the **Channel ID** as the \`channels\` parameter when creating posts.`;
+        // Fetch profile pictures
+        const content = [];
+        const imagePromises = accounts
+            .filter((a) => a.profile_picture)
+            .slice(0, 6)
+            .map(async (a) => {
+            const img = await fetchImageAsBase64(a.profile_picture);
+            return img ? { account: a, image: img } : null;
+        });
+        const images = (await Promise.all(imagePromises)).filter(Boolean);
+        for (const item of images) {
+            if (item) {
+                content.push({
+                    type: "image",
+                    data: item.image.data,
+                    mimeType: item.image.mimeType,
+                });
+            }
+        }
+        content.push({ type: "text", text: md });
+        return { content };
     });
     server.tool("get_account", "Get details of a specific connected social media account.", {
         id: z.string().describe("The account ID"),
     }, async ({ id }) => {
         const result = await client.getAccount(id);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const a = result.data;
+        if (!a) {
+            return {
+                content: [{ type: "text", text: "Account not found." }],
+            };
+        }
+        let md = `## ${capitalize(a.platform)} Account\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **Channel ID** | \`${a.id}\` |\n`;
+        md += `| **Platform** | ${capitalize(a.platform)} |\n`;
+        md += `| **Username** | ${a.username ? `@${a.username}` : "—"} |\n`;
+        md += `| **Display Name** | ${a.display_name || "—"} |\n`;
+        md += `| **Content Types** | ${(a.content_types || []).join(", ")} |\n`;
+        md += `| **Status** | ${a.status} |\n`;
+        md += `| **Connected** | ${a.connected_at ? new Date(a.connected_at).toLocaleDateString() : "—"} |\n`;
+        if (a.platform_details?.subscription_type) {
+            md += `| **Subscription** | ${a.platform_details.subscription_type} |\n`;
+        }
+        if (a.boards?.length) {
+            md += `\n### Pinterest Boards\n\n`;
+            md += `| Board Name | Board ID |\n`;
+            md += `|------------|----------|\n`;
+            for (const b of a.boards) {
+                md += `| ${b.name} | \`${b.id}\` |\n`;
+            }
+        }
+        const content = [];
+        if (a.profile_picture) {
+            const img = await fetchImageAsBase64(a.profile_picture);
+            if (img) {
+                content.push({ type: "image", data: img.data, mimeType: img.mimeType });
+            }
+        }
+        content.push({ type: "text", text: md });
+        return { content };
     });
 }

package/build/tools/analytics.js

@@ -1,11 +1,52 @@
 import { z } from "zod";
+import { formatNumber, capitalize } from "../client.js";
 export function registerAnalyticsTools(server, client) {
     server.tool("get_post_analytics", "Get analytics/statistics for a specific published post (impressions, engagements, likes, etc.).", {
         post_id: z.string().describe("The post ID to get analytics for"),
     }, async ({ post_id }) => {
         const result = await client.getPostAnalytics(post_id);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const d = result.data;
+        if (!d) {
+            return {
+                content: [{ type: "text", text: "No analytics found for this post." }],
+            };
+        }
+        let md = `## Post Analytics\n\n`;
+        md += `| Metric | Value |\n`;
+        md += `|--------|-------|\n`;
+        md += `| **Impressions** | ${formatNumber(d.impressions ?? 0)} |\n`;
+        md += `| **Engagements** | ${formatNumber(d.engagements ?? 0)} |\n`;
+        md += `| **Likes** | ${formatNumber(d.likes ?? 0)} |\n`;
+        md += `| **Comments** | ${formatNumber(d.comments ?? 0)} |\n`;
+        md += `| **Shares** | ${formatNumber(d.shares ?? 0)} |\n`;
+        if (d.impressions > 0) {
+            const rate = ((d.engagements ?? 0) / d.impressions * 100).toFixed(2);
+            md += `| **Engagement Rate** | ${rate}% |\n`;
+        }
+        if (d.platform_stats && Object.keys(d.platform_stats).length > 0) {
+            md += `\n### Per-Platform Breakdown\n\n`;
+            for (const [platform, stats] of Object.entries(d.platform_stats)) {
+                const s = stats;
+                md += `**${capitalize(platform)}:** `;
+                const parts = [];
+                if (s.impressions !== undefined)
+                    parts.push(`${formatNumber(s.impressions)} impressions`);
+                if (s.engagements !== undefined)
+                    parts.push(`${formatNumber(s.engagements)} engagements`);
+                if (s.likes !== undefined)
+                    parts.push(`${formatNumber(s.likes)} likes`);
+                if (s.comments !== undefined)
+                    parts.push(`${formatNumber(s.comments)} comments`);
+                md += parts.join(", ") + "\n\n";
+            }
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("get_analytics_overview", "Get an overview of analytics across all posts and accounts for a time period.", {
@@ -14,8 +55,37 @@ export function registerAnalyticsTools(server, client) {
         end_date: z.string().optional().describe("Custom end date (ISO 8601)"),
     }, async (params) => {
         const result = await client.getAnalyticsOverview(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const d = result.data;
+        const period = result.period || params.period || "30d";
+        let md = `## Analytics Overview (Last ${period})\n\n`;
+        md += `**${d.total_posts} posts** across **${d.total_platforms} platforms** | `;
+        md += `**${formatNumber(d.total_impressions)}** impressions | `;
+        md += `**${formatNumber(d.total_engagement)}** engagements | `;
+        md += `**${(d.average_engagement_rate ?? 0).toFixed(2)}%** avg engagement rate\n\n`;
+        if (d.top_performing_platform) {
+            md += `Top performing platform: **${capitalize(d.top_performing_platform)}**\n\n`;
+        }
+        if (d.platform_breakdown && Object.keys(d.platform_breakdown).length > 0) {
+            md += `### By Platform\n\n`;
+            md += `| Platform | Posts | Impressions | Engagements | Eng. Rate |\n`;
+            md += `|----------|-------|-------------|-------------|----------|\n`;
+            // Sort by impressions descending
+            const sorted = Object.entries(d.platform_breakdown).sort((a, b) => (b[1].total_impressions || 0) - (a[1].total_impressions || 0));
+            for (const [platform, stats] of sorted) {
+                const s = stats;
+                const rate = s.engagement_rate !== undefined
+                    ? `${s.engagement_rate.toFixed(2)}%`
+                    : "—";
+                md += `| ${capitalize(platform)} | ${s.posts} | ${formatNumber(s.total_impressions || 0)} | ${formatNumber(s.total_engagement || 0)} | ${rate} |\n`;
+            }
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("get_account_analytics", "Get account-level analytics (followers, subscribers, etc.) for connected social accounts.", {
@@ -23,8 +93,54 @@ export function registerAnalyticsTools(server, client) {
         date: z.string().optional().describe("Date to get analytics for (YYYY-MM-DD, defaults to today)"),
     }, async (params) => {
         const result = await client.getAccountAnalytics(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const accounts = result.data || [];
+        const date = result.date || params.date || "today";
+        if (!accounts.length) {
+            return {
+                content: [{ type: "text", text: "No account analytics found." }],
+            };
+        }
+        let md = `## Account Analytics (${date})\n\n`;
+        md += `| Platform | Followers | Details |\n`;
+        md += `|----------|-----------|---------|\n`;
+        // Sort by followers descending
+        const sorted = [...accounts].sort((a, b) => {
+            const fa = a.metrics?.followers ?? 0;
+            const fb = b.metrics?.followers ?? 0;
+            return fb - fa;
+        });
+        for (const a of sorted) {
+            const m = a.metrics || {};
+            const followers = m.followers !== undefined
+                ? formatNumber(m.followers)
+                : m.subscribers !== undefined
+                    ? `${formatNumber(m.subscribers)} subs`
+                    : "—";
+            const details = [];
+            if (m.posts !== undefined)
+                details.push(`${formatNumber(m.posts)} posts`);
+            if (m.following !== undefined)
+                details.push(`${formatNumber(m.following)} following`);
+            if (m.impressions !== undefined)
+                details.push(`${formatNumber(m.impressions)} impressions`);
+            if (m.engagement !== undefined)
+                details.push(`${formatNumber(m.engagement)} engagements`);
+            if (m.total_views !== undefined)
+                details.push(`${formatNumber(m.total_views)} views`);
+            if (m.total_videos !== undefined)
+                details.push(`${m.total_videos} videos`);
+            if (m.subscribers !== undefined && m.followers !== undefined) {
+                details.push(`${formatNumber(m.subscribers)} subscribers`);
+            }
+            md += `| ${capitalize(a.platform)} | ${followers} | ${details.join(", ") || "—"} |\n`;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
 }

package/build/tools/media.js

@@ -1,21 +1,68 @@
 import { z } from "zod";
+import { fetchImageAsBase64, formatBytes } from "../client.js";
 export function registerMediaTools(server, client) {
-    server.tool("list_media", "List all media files in the workspace.", {
+    server.tool("list_media", "List all media files in the workspace. Returns each file's ID, URL, type (image/video), and size. Use this to help users pick media for posts, stories, or reels. Media IDs or URLs from this list can be passed to create_post.", {
         limit: z.string().optional().describe("Max results to return"),
         offset: z.string().optional().describe("Offset for pagination"),
     }, async (params) => {
         const result = await client.listMedia(params);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const items = Array.isArray(result.data) ? result.data : result.data?.media || [];
+        if (!items.length) {
+            return {
+                content: [{ type: "text", text: "No media files found." }],
+            };
+        }
+        let md = `## Media Library (${items.length} files)\n\n`;
+        md += `| # | Type | Filename | Size | Media ID |\n`;
+        md += `|---|------|----------|------|----------|\n`;
+        for (let i = 0; i < items.length; i++) {
+            const m = items[i];
+            const type = m.type === "video" ? "Video" : "Image";
+            md += `| ${i + 1} | ${type} | ${m.filename || "—"} | ${formatBytes(m.size || 0)} | \`${m.id}\` |\n`;
+        }
+        md += `\nUse the **Media ID** with \`media_ids\` when creating posts.`;
+        // Fetch thumbnails for image files (max 4)
+        const content = [];
+        const imageItems = items.filter((m) => m.type !== "video" && m.url).slice(0, 4);
+        const imagePromises = imageItems.map(async (m) => {
+            const img = await fetchImageAsBase64(m.url);
+            return img ? { ...img, id: m.id } : null;
+        });
+        const images = (await Promise.all(imagePromises)).filter(Boolean);
+        for (const img of images) {
+            if (img) {
+                content.push({ type: "image", data: img.data, mimeType: img.mimeType });
+            }
+        }
+        content.push({ type: "text", text: md });
+        return { content };
     });
     server.tool("upload_media", "Upload media from a URL. The file will be downloaded and stored. Max 50MB.", {
         url: z.string().describe("Public URL of the media file to upload"),
         filename: z.string().optional().describe("Optional filename for the uploaded media"),
     }, async (params) => {
         const result = await client.uploadMedia(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const m = result.data;
+        let md = `## Media Uploaded\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **Media ID** | \`${m.id}\` |\n`;
+        md += `| **Type** | ${m.type || "—"} |\n`;
+        md += `| **Filename** | ${m.filename || "—"} |\n`;
+        md += `| **Size** | ${formatBytes(m.size || 0)} |\n`;
+        md += `\nUse this Media ID with \`media_ids\` when creating posts.`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("delete_media", "Delete a media file by ID.", {
@@ -23,7 +70,7 @@ export function registerMediaTools(server, client) {
     }, async ({ id }) => {
         const result = await client.deleteMedia(id);
         return {
-            content: [{ type: "text", text: result.error ? JSON.stringify(result.error) : "Media deleted successfully." }],
+            content: [{ type: "text", text: result.error ? `Error: ${result.error.message}` : "Media deleted successfully." }],
         };
     });
 }

package/build/tools/posts.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatDateTime, truncate, capitalize } from "../client.js";
 export function registerPostTools(server, client) {
     server.tool("list_posts", "List all posts in the workspace. Optionally filter by status.", {
         status: z.string().optional().describe("Filter by status: draft, scheduled, published, failed"),
@@ -6,19 +7,92 @@ export function registerPostTools(server, client) {
         offset: z.string().optional().describe("Offset for pagination"),
     }, async (params) => {
         const result = await client.listPosts(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const posts = Array.isArray(result.data) ? result.data : result.data?.posts || [];
+        if (!posts.length) {
+            return {
+                content: [{ type: "text", text: `No posts found${params.status ? ` with status "${params.status}"` : ""}.` }],
+            };
+        }
+        const statusLabel = params.status ? ` — ${capitalize(params.status)}` : "";
+        let md = `## Posts (${posts.length} results)${statusLabel}\n\n`;
+        md += `| # | Content | Channels | Status | Date | ID |\n`;
+        md += `|---|---------|----------|--------|------|----|\n`;
+        for (let i = 0; i < posts.length; i++) {
+            const p = posts[i];
+            const content = truncate(p.content || "", 50);
+            const channels = (p.channels || []).join(", ");
+            const status = capitalize(p.status || "—");
+            const date = p.scheduled_at
+                ? formatDateTime(p.scheduled_at)
+                : p.published_at
+                    ? formatDateTime(p.published_at)
+                    : formatDateTime(p.created_at);
+            md += `| ${i + 1} | ${content} | ${channels} | ${status} | ${date} | \`${p.id}\` |\n`;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("get_post", "Get details of a specific post by ID.", {
         id: z.string().describe("The post ID"),
     }, async ({ id }) => {
         const result = await client.getPost(id);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const p = result.data;
+        if (!p) {
+            return {
+                content: [{ type: "text", text: "Post not found." }],
+            };
+        }
+        let md = `## Post Details\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${p.id}\` |\n`;
+        md += `| **Status** | ${capitalize(p.status || "—")} |\n`;
+        md += `| **Type** | ${p.type || "post"} |\n`;
+        md += `| **Channels** | ${(p.channels || []).join(", ") || "—"} |\n`;
+        if (p.scheduled_at)
+            md += `| **Scheduled** | ${formatDateTime(p.scheduled_at)} |\n`;
+        if (p.published_at)
+            md += `| **Published** | ${formatDateTime(p.published_at)} |\n`;
+        md += `| **Created** | ${formatDateTime(p.created_at)} |\n`;
+        if (p.media?.length) {
+            md += `| **Media** | ${p.media.length} file(s) |\n`;
+        }
+        md += `\n### Content\n\n${p.content || "(empty)"}`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
-    server.tool("create_post", "Create a new social media post, story, or reel. Specify content, target channels, type, and optional platform-specific options.", {
+    server.tool("create_post", `Create a new social media post, story, or reel.
+
+IMPORTANT — Before calling this tool, make sure you have all required information from the user. If anything is missing, ASK the user before calling:
+
+1. **Content/caption**: What text should the post have?
+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?)
+4. **Media** (REQUIRED for some types):
+   - Stories: ALWAYS require an image or video. Ask the user which image/video to use. Use list_media to show their uploaded media, or ask for an external URL.
+   - Reels: ALWAYS require a video. Ask the user which video to use. Use list_media to find available videos.
+   - Instagram posts: ALWAYS require at least one image or video.
+   - TikTok posts: ALWAYS require at least one image or video.
+   - Pinterest posts: ALWAYS require an image AND a board_id.
+   - Other platforms (LinkedIn, X, Bluesky, etc.): Media is optional.
+5. **Platform-specific options** (ask only when relevant):
+   - Pinterest: Which board? Any link to attach?
+   - YouTube: Title, privacy status, tags?
+   - TikTok: Privacy level?
+
+Do NOT call this tool without media when creating stories, reels, Instagram posts, TikTok posts, or Pinterest posts — it will fail.`, {
         content: z.string().describe("The post content/caption text"),
         channels: z.array(z.string()).optional().describe("Array of channel IDs to post to"),
         scheduled_at: z.string().optional().describe("ISO 8601 date for scheduled publishing"),
@@ -29,7 +103,7 @@ export function registerPostTools(server, client) {
         media_urls: z.union([
             z.array(z.string()),
             z.record(z.string(), z.array(z.string())),
-        ]).optional().describe("External image/video URLs — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...], pinterest: [...] }. Max 10 total."),
+        ]).optional().describe("External image/video URLs — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...], pinterest: [...] }. Max 10 total. When using per-platform format, 'default' is the fallback for selected platforms without their own key. Pass an empty array (e.g. facebook: []) to opt a platform out of media."),
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story' (Instagram/Facebook/Snapchat), 'reel' (Instagram/Facebook/YouTube/TikTok)"),
         pinterest: z.object({
             board_id: z.string().optional(),
@@ -64,11 +138,40 @@ export function registerPostTools(server, client) {
         }).optional().describe("X (Twitter) options"),
     }, async (params) => {
         const result = await client.createPost(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const p = result.data;
+        let md = `## Post Created\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${p.id}\` |\n`;
+        md += `| **Status** | ${capitalize(p.status || "draft")} |\n`;
+        if (p.scheduled_at)
+            md += `| **Scheduled** | ${formatDateTime(p.scheduled_at)} |\n`;
+        if (p.channels?.length)
+            md += `| **Channels** | ${p.channels.join(", ")} |\n`;
+        md += `\n**Content:** ${truncate(p.content || "", 100)}`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
-    server.tool("create_and_publish_post", "Create a new post and publish it immediately to all selected platforms. No scheduling needed.", {
+    server.tool("create_and_publish_post", `Create a new post and publish it immediately (no scheduling).
+
+IMPORTANT — Before calling this tool, make sure you have all required information. If anything is missing, ASK the user first:
+
+1. **Content/caption**: What text?
+2. **Channels**: Which platforms? Use list_accounts if needed.
+3. **Media** (REQUIRED for some types — same rules as create_post):
+   - Stories: ALWAYS need an image or video.
+   - Reels: ALWAYS need a video.
+   - 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.
+
+Do NOT call without required media — it will fail.`, {
         content: z.string().describe("The post content/caption text"),
         channels: z.array(z.string()).optional().describe("Array of channel IDs to post to"),
         media_ids: z.union([
@@ -78,7 +181,7 @@ export function registerPostTools(server, client) {
         media_urls: z.union([
             z.array(z.string()),
             z.record(z.string(), z.array(z.string())),
-        ]).optional().describe("External image/video URLs — flat array or per-platform object. Max 10 total."),
+        ]).optional().describe("External image/video URLs — flat array or per-platform object. Max 10 total. 'default' key is fallback for platforms without their own key. Empty array opts out."),
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story', 'reel'"),
         pinterest: z.object({
             board_id: z.string().optional(),
@@ -95,8 +198,22 @@ export function registerPostTools(server, client) {
         }).optional().describe("TikTok options"),
     }, async (params) => {
         const result = await client.createAndPublishPost(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const p = result.data;
+        let md = `## Post Created & Publishing\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${p.id}\` |\n`;
+        md += `| **Status** | ${capitalize(p.status || "publishing")} |\n`;
+        if (p.channels?.length)
+            md += `| **Channels** | ${p.channels.join(", ")} |\n`;
+        md += `\n**Content:** ${truncate(p.content || "", 100)}`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("update_post", "Update an existing post. Only draft and scheduled posts can be updated.", {
@@ -111,11 +228,24 @@ export function registerPostTools(server, client) {
         media_urls: z.union([
             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."),
+        ]).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."),
     }, async ({ id, ...data }) => {
         const result = await client.updatePost(id, data);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const p = result.data;
+        let md = `## Post Updated\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${p.id}\` |\n`;
+        md += `| **Status** | ${capitalize(p.status || "—")} |\n`;
+        if (p.scheduled_at)
+            md += `| **Scheduled** | ${formatDateTime(p.scheduled_at)} |\n`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("delete_post", "Delete a post by ID. This action cannot be undone.", {
@@ -123,15 +253,28 @@ export function registerPostTools(server, client) {
     }, async ({ id }) => {
         const result = await client.deletePost(id);
         return {
-            content: [{ type: "text", text: result.error ? JSON.stringify(result.error) : "Post deleted successfully." }],
+            content: [{ type: "text", text: result.error ? `Error: ${result.error.message}` : "Post deleted successfully." }],
         };
     });
-    server.tool("publish_post", "Publish a draft or scheduled post immediately. The post will be queued for immediate publishing.", {
+    server.tool("publish_post", `Publish a draft or scheduled post immediately. The post will be queued for publishing.
+
+IMPORTANT: Before publishing, verify the post has all required media. If publishing a story or reel, ensure media was attached when the post was created/updated. If it's missing, use update_post to add media first, or inform the user.`, {
         id: z.string().describe("The post ID to publish"),
     }, async ({ id }) => {
         const result = await client.publishPost(id);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const p = result.data;
+        let md = `## Post Queued for Publishing\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${p.id}\` |\n`;
+        md += `| **Status** | ${capitalize(p.status || "publishing")} |\n`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
 }

package/build/tools/webhooks.js

@@ -1,9 +1,31 @@
 import { z } from "zod";
+import { formatDateTime } from "../client.js";
 export function registerWebhookTools(server, client) {
     server.tool("list_webhooks", "List all configured webhooks.", {}, async () => {
         const result = await client.listWebhooks();
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const webhooks = Array.isArray(result.data) ? result.data : result.data?.webhooks || [];
+        if (!webhooks.length) {
+            return {
+                content: [{ type: "text", text: "No webhooks configured." }],
+            };
+        }
+        let md = `## Webhooks (${webhooks.length})\n\n`;
+        md += `| # | URL | Events | Status | Last Triggered |\n`;
+        md += `|---|-----|--------|--------|----------------|\n`;
+        for (let i = 0; i < webhooks.length; i++) {
+            const w = webhooks[i];
+            const status = w.is_active ? "Active" : "Inactive";
+            const events = (w.events || []).join(", ");
+            const lastTriggered = w.last_triggered_at ? formatDateTime(w.last_triggered_at) : "Never";
+            md += `| ${i + 1} | ${w.url} | ${events} | ${status} | ${lastTriggered} |\n`;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("create_webhook", "Create a new webhook to receive event notifications. Available events: post.scheduled, post.published, post.failed", {
@@ -11,16 +33,49 @@ export function registerWebhookTools(server, client) {
         events: z.array(z.string()).describe("Events to subscribe to: post.scheduled, post.published, post.failed"),
     }, async (params) => {
         const result = await client.createWebhook(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const w = result.data;
+        let md = `## Webhook Created\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${w.id}\` |\n`;
+        md += `| **URL** | ${w.url} |\n`;
+        md += `| **Events** | ${(w.events || []).join(", ")} |\n`;
+        md += `| **Status** | ${w.is_active ? "Active" : "Inactive"} |\n`;
+        if (w.secret) {
+            md += `| **Secret** | \`${w.secret}\` |\n`;
+            md += `\n> **Save this secret** — it won't be shown again. Use it to verify webhook signatures.`;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("get_webhook", "Get details of a specific webhook by ID.", {
         id: z.string().describe("The webhook ID"),
     }, async ({ id }) => {
         const result = await client.getWebhook(id);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const w = result.data;
+        let md = `## Webhook Details\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${w.id}\` |\n`;
+        md += `| **URL** | ${w.url} |\n`;
+        md += `| **Events** | ${(w.events || []).join(", ")} |\n`;
+        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`;
+        md += `| **Created** | ${formatDateTime(w.created_at)} |\n`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("update_webhook", "Update a webhook's URL, events, or active status.", {
@@ -30,8 +85,21 @@ export function registerWebhookTools(server, client) {
         is_active: z.boolean().optional().describe("Enable or disable the webhook"),
     }, async ({ id, ...data }) => {
         const result = await client.updateWebhook(id, data);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const w = result.data;
+        let md = `## Webhook Updated\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${w.id}\` |\n`;
+        md += `| **URL** | ${w.url} |\n`;
+        md += `| **Events** | ${(w.events || []).join(", ")} |\n`;
+        md += `| **Status** | ${w.is_active ? "Active" : "Inactive"} |\n`;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
     server.tool("delete_webhook", "Delete a webhook by ID. You will stop receiving notifications at this URL.", {
@@ -39,15 +107,29 @@ export function registerWebhookTools(server, client) {
     }, async ({ id }) => {
         const result = await client.deleteWebhook(id);
         return {
-            content: [{ type: "text", text: result.error ? JSON.stringify(result.error) : "Webhook deleted successfully." }],
+            content: [{ type: "text", text: result.error ? `Error: ${result.error.message}` : "Webhook deleted successfully." }],
         };
     });
     server.tool("rotate_webhook_secret", "Rotate the signing secret for a webhook. The new secret will only be shown once.", {
         id: z.string().describe("The webhook ID"),
     }, async ({ id }) => {
         const result = await client.rotateWebhookSecret(id);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+            };
+        }
+        const w = result.data;
+        let md = `## Webhook Secret Rotated\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **ID** | \`${w.id}\` |\n`;
+        if (w.secret) {
+            md += `| **New Secret** | \`${w.secret}\` |\n`;
+            md += `\n> **Save this secret immediately** — it won't be shown again.`;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: md }],
         };
     });
 }

package/build/types.d.ts

@@ -27,8 +27,18 @@ export interface Account {
     id: string;
     platform: string;
     username: string;
+    display_name: string;
     profile_picture: string | null;
-    is_connected: boolean;
+    content_types: string[];
+    status: string;
+    connected_at: string | null;
+    boards?: {
+        id: string;
+        name: string;
+    }[];
+    platform_details?: {
+        subscription_type?: string;
+    };
 }
 export interface Webhook {
     id: string;

package/package.json

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