@omnisocials/mcp-server 1.3.7 → 1.3.8

package/README.md

@@ -191,6 +191,11 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 
 ## Changelog
 
+### 1.3.8
+
+- **Fixed:** Pinterest pins created via `create_post` / `create_and_publish_post` / `update_post` now publish with title, link, video cover, and alt text. Companion server fix — the API was storing those fields under unprefixed keys while the publisher read them under `pinterest_*` prefixes, so pins published with no metadata even when the agent passed it. Existing clients on 1.3.7 benefit automatically once the backend deploys.
+- **Added:** `pinterest.video_cover` and `pinterest.alt_text` to the tool schemas. `alt_text` improves accessibility + Pinterest's discoverability for visually impaired users; `video_cover` sets a custom cover image for video pins (otherwise Pinterest uses a 1s video keyframe).
+
 ### 1.3.7
 
 - **Fixed:** `update_post` now accepts per-platform options (`youtube`, `pinterest`, `instagram`, `tiktok`) — same shape as `create_post`. Previously these were missing from the `update_post` schema, so agents that tried to rename a scheduled YouTube Short via `youtube.title` had the field silently stripped before it reached the server. Renaming a Short, changing privacy, adjusting a Pinterest board, etc. on an existing draft now work.

package/build/tools/accounts.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { fetchImageAsBase64, capitalize } from "../client.js";
 export function registerAccountTools(server, getClient) {
-    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\"). LinkedIn appears as two independent platforms: `linkedin` for a personal profile and `linkedin_page` for a company page. A workspace can have both connected at the same time and post to each separately. Call this to help users pick which platforms to post to.", {}, 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), supported content_types (post, story, reel), and `needs_reconnect` (true when the OAuth token has been revoked/expired and the user must reconnect before posts can succeed; also reflected in `status` as `needs_reconnect` instead of `active`). Pinterest accounts 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\"). LinkedIn appears as two independent platforms: `linkedin` for a personal profile and `linkedin_page` for a company page. A workspace can have both connected at the same time and post to each separately. Call this to help users pick which platforms to post to.", {}, async () => {
         const result = await getClient().listAccounts();
         if (result.error) {
             return {
@@ -16,8 +16,8 @@ export function registerAccountTools(server, getClient) {
         }
         // Build markdown table
         let md = `## Connected Accounts (${accounts.length})\n\n`;
-        md += `| # | Platform | Account | Content Types | Channel ID |\n`;
-        md += `|---|----------|---------|---------------|------------|\n`;
+        md += `| # | Platform | Account | Content Types | Channel ID | Status |\n`;
+        md += `|---|----------|---------|---------------|------------|--------|\n`;
         for (let i = 0; i < accounts.length; i++) {
             const a = accounts[i];
             const name = a.username ? `@${a.username}` : a.display_name || "—";
@@ -26,7 +26,16 @@ export function registerAccountTools(server, getClient) {
             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`;
+            const statusCell = a.needs_reconnect
+                ? `⚠️ needs_reconnect`
+                : "active";
+            md += `| ${i + 1} | ${platform}${sub} | ${name} | ${types} | \`${a.id}\` | ${statusCell} |\n`;
+        }
+        const reconnects = accounts.filter((a) => a.needs_reconnect);
+        if (reconnects.length) {
+            md += `\n⚠️ ${reconnects.length} account(s) need reconnecting before posting will succeed: ${reconnects
+                .map((a) => capitalize(a.platform))
+                .join(", ")}. Ask the user to reconnect in OmniSocials (Settings → Organisation → Workspaces).\n`;
         }
         md += `\nUse the **Channel ID** as the \`channels\` parameter when creating posts.`;
         // Fetch profile pictures
@@ -74,7 +83,10 @@ export function registerAccountTools(server, getClient) {
         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 += `| **Status** | ${a.needs_reconnect ? "⚠️ needs_reconnect" : a.status} |\n`;
+        if (a.needs_reconnect && a.reauth_reason) {
+            md += `| **Reconnect reason** | ${a.reauth_reason} |\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`;

package/build/tools/analytics.js

@@ -11,48 +11,64 @@ export function registerAnalyticsTools(server, getClient) {
             };
         }
         const d = result.data;
-        if (!d) {
+        // 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.
+        const platforms = d?.platforms || {};
+        const platformEntries = Object.entries(platforms);
+        if (platformEntries.length === 0) {
             return {
-                content: [{ type: "text", text: "No analytics found for this post." }],
+                content: [{
+                        type: "text",
+                        text: "No analytics collected yet for this post. Stats are fetched periodically after publishing; check back in a few hours, or verify the post finished publishing successfully.",
+                    }],
             };
         }
+        const totals = { impressions: 0, engagements: 0, likes: 0, comments: 0, shares: 0 };
+        const perPlatform = [];
+        for (const [platform, entry] of platformEntries) {
+            const m = entry?.metrics || {};
+            const impressions = 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 engagements = m.engagement != null ? Number(m.engagement) : likes + comments + shares;
+            totals.impressions += impressions;
+            totals.engagements += engagements;
+            totals.likes += likes;
+            totals.comments += comments;
+            totals.shares += shares;
+            perPlatform.push({ platform, impressions, engagements, likes, comments, shares });
+        }
         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 += `| **Impressions** | ${formatNumber(totals.impressions)} |\n`;
+        md += `| **Engagements** | ${formatNumber(totals.engagements)} |\n`;
+        md += `| **Likes** | ${formatNumber(totals.likes)} |\n`;
+        md += `| **Comments** | ${formatNumber(totals.comments)} |\n`;
+        md += `| **Shares** | ${formatNumber(totals.shares)} |\n`;
+        if (totals.impressions > 0) {
+            const rate = ((totals.engagements / totals.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";
-            }
+        md += `\n### Per-Platform Breakdown\n\n`;
+        md += `| Platform | Impressions | Engagements | Likes | Comments | Shares |\n`;
+        md += `|----------|-------------|-------------|-------|----------|--------|\n`;
+        for (const p of perPlatform) {
+            md += `| ${capitalize(p.platform)} | ${formatNumber(p.impressions)} | ${formatNumber(p.engagements)} | ${formatNumber(p.likes)} | ${formatNumber(p.comments)} | ${formatNumber(p.shares)} |\n`;
         }
         return {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("get_analytics_overview", "Get an overview of analytics across all posts and accounts for a time period.", {
-        period: z.string().optional().describe("Time period: 7d, 30d, 90d (default: 30d)"),
-        start_date: z.string().optional().describe("Custom start date (ISO 8601)"),
-        end_date: z.string().optional().describe("Custom end date (ISO 8601)"),
+    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).'),
+        end_date: z.string().optional().describe('Custom end date. Same formats as start_date; "YYYY-MM" expands to the last day of the month.'),
     }, async (params) => {
         const result = await getClient().getAnalyticsOverview(params);
         if (result.error) {
@@ -61,8 +77,15 @@ export function registerAnalyticsTools(server, getClient) {
             };
         }
         const d = result.data;
-        const period = result.period || params.period || "30d";
-        let md = `## Analytics Overview (Last ${period})\n\n`;
+        const resolvedStart = result.start_date;
+        const resolvedEnd = result.end_date;
+        const currentDate = result.current_date;
+        const periodLabel = resolvedStart && resolvedEnd
+            ? `${resolvedStart} → ${resolvedEnd}`
+            : result.period || params.period || "30d";
+        let md = `## Analytics Overview (${periodLabel})\n\n`;
+        if (currentDate)
+            md += `_Today: ${currentDate}_\n\n`;
         md += `**${d.total_posts} posts** across **${d.total_platforms} platforms** | `;
         md += `**${formatNumber(d.total_impressions)}** impressions | `;
         md += `**${formatNumber(d.total_engagement)}** engagements | `;

package/build/tools/posts.js

@@ -211,9 +211,11 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         ]).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(),
-            title: z.string().optional(),
-            link: z.string().optional(),
+            board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
+            title: z.string().optional().describe("Pin title (max 100 characters)"),
+            link: z.string().optional().describe("Destination URL the pin clicks through to"),
+            video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
+            alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
         }).optional().describe("Pinterest-specific options"),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. Falls back to \"YouTube Short\" when omitted."),
@@ -324,9 +326,11 @@ Do NOT call without required media — it will fail.`, {
         ]).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(),
-            title: z.string().optional(),
-            link: z.string().optional(),
+            board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
+            title: z.string().optional().describe("Pin title (max 100 characters)"),
+            link: z.string().optional().describe("Destination URL the pin clicks through to"),
+            video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
+            alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
         }).optional().describe("Pinterest-specific options"),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube."),
@@ -403,9 +407,11 @@ Do NOT call without required media — it will fail.`, {
             contains_synthetic_media: z.boolean().optional(),
         }).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(),
-            title: z.string().optional(),
-            link: z.string().optional(),
+            board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
+            title: z.string().optional().describe("Pin title (max 100 characters)"),
+            link: z.string().optional().describe("Destination URL the pin clicks through to"),
+            video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
+            alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
         }).optional().describe("Pinterest-specific options"),
         instagram: z.object({
             share_to_feed: z.boolean().optional(),

package/build/types.d.ts

@@ -41,7 +41,15 @@ export interface Account {
     display_name: string;
     profile_picture: string | null;
     content_types: string[];
-    status: string;
+    /**
+     * "active" while the OAuth token is healthy. Flips to "needs_reconnect"
+     * when the platform has revoked/expired the token — posts to this account
+     * will fail until the user reconnects.
+     */
+    status: "active" | "needs_reconnect" | string;
+    needs_reconnect: boolean;
+    /** Short reason from the platform; only present when needs_reconnect is true. */
+    reauth_reason?: string | null;
     connected_at: string | null;
     boards?: {
         id: string;

package/package.json

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