@omnisocials/mcp-server 1.10.0 → 1.12.0

package/build/client.d.ts

@@ -9,6 +9,14 @@ export declare function formatDate(iso: string | null): string;
 export declare function formatDateTime(iso: string | null): string;
 export declare function truncate(value: unknown, len: number): string;
 export declare function capitalize(str: string): string;
+export declare function sortMetricLabels(labels: string[]): string[];
+/**
+ * Flatten a raw per-platform metrics object into ordered [label, value] rows,
+ * keeping every numeric counter the platform reported. Strings (note, title,
+ * cover_image_url, …) are skipped; `plays` is a legacy always-0 Instagram
+ * back-compat key so a zero there is noise, not data.
+ */
+export declare function metricRows(m: Record<string, unknown> | null | undefined): Array<[string, number]>;
 export interface XThreadPartInput {
     /** Tweet text — ≤ 280 chars (the API enforces 280 even for X Premium). */
     text: string;
@@ -179,6 +187,7 @@ export declare class OmniSocialsClient {
     publishPost(id: string): Promise<ApiResponse<unknown>>;
     searchLocations(query: string): Promise<ApiResponse<unknown>>;
     validateLocation(id: string): Promise<ApiResponse<unknown>>;
+    searchInstagramAudio(query?: string, type?: "music" | "original_sound"): Promise<ApiResponse<unknown>>;
     listMedia(params?: {
         limit?: string;
         offset?: string;

package/build/client.js

@@ -89,6 +89,69 @@ export function truncate(value, len) {
 export function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
+// ─── Metric Rendering ───────────────────────────────────────────────────────
+// Canonical render order + labels for per-platform metric objects. Any numeric
+// key the API returns that isn't listed here still renders (prettified from
+// snake_case) so no metric is ever silently dropped — reach/saves/views went
+// missing for months because the old renderers used a fixed column set.
+const METRIC_LABELS = [
+    ["impressions", "Impressions"],
+    ["reach", "Reach"],
+    ["views", "Views"],
+    ["likes", "Likes"],
+    ["comments", "Comments"],
+    ["shares", "Shares"],
+    ["saves", "Saves"],
+    ["clicks", "Clicks"],
+    ["reposts", "Reposts"],
+    ["quotes", "Quotes"],
+    ["bookmarks", "Bookmarks"],
+    ["replies", "Replies"],
+    ["reactions", "Reactions"],
+    ["total_reactions", "Total reactions"],
+    ["favorites", "Favorites"],
+    ["plays", "Plays"],
+    ["engagement", "Engagements"],
+];
+// Context keys that ride along in stored metrics — not counters.
+const NON_COUNTER_KEYS = new Set(["create_time"]);
+/** Canonical position of a metric label — for sorting totals rows collected
+ * across platforms back into METRIC_LABELS order (unknown labels sink). */
+const LABEL_ORDER = new Map(METRIC_LABELS.map(([, label], i) => [label, i]));
+export function sortMetricLabels(labels) {
+    return [...labels].sort((a, b) => (LABEL_ORDER.get(a) ?? 999) - (LABEL_ORDER.get(b) ?? 999));
+}
+/**
+ * Flatten a raw per-platform metrics object into ordered [label, value] rows,
+ * keeping every numeric counter the platform reported. Strings (note, title,
+ * cover_image_url, …) are skipped; `plays` is a legacy always-0 Instagram
+ * back-compat key so a zero there is noise, not data.
+ */
+export function metricRows(m) {
+    const rows = [];
+    const seen = new Set();
+    for (const [key, label] of METRIC_LABELS) {
+        const v = m?.[key];
+        if (v === undefined || v === null)
+            continue;
+        const n = Number(v);
+        if (!Number.isFinite(n))
+            continue;
+        seen.add(key);
+        if (key === "plays" && n === 0)
+            continue;
+        rows.push([label, n]);
+    }
+    for (const [key, v] of Object.entries(m || {})) {
+        if (seen.has(key) || NON_COUNTER_KEYS.has(key))
+            continue;
+        const n = Number(v);
+        if (!Number.isFinite(n))
+            continue;
+        rows.push([capitalize(key.replace(/_/g, " ")), n]);
+    }
+    return rows;
+}
 export class OmniSocialsClient {
     baseUrl;
     apiKey;
@@ -163,6 +226,15 @@ export class OmniSocialsClient {
     async validateLocation(id) {
         return this.request("GET", "/locations/validate", undefined, { id });
     }
+    // Audio (Instagram Reel music)
+    async searchInstagramAudio(query, type) {
+        const params = {};
+        if (query)
+            params.q = query;
+        if (type)
+            params.type = type;
+        return this.request("GET", "/audio/search", undefined, params);
+    }
     // Media
     async listMedia(params) {
         return this.request("GET", "/media", undefined, params);

package/build/index.js

@@ -27,7 +27,7 @@ const sessionState = { activeIndex: 0 };
 const getActiveClient = () => workspaceClients[sessionState.activeIndex].client;
 const server = new McpServer({
     name: "OmniSocials",
-    version: "1.10.0",
+    version: "1.12.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);

package/build/tools/analytics.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { formatNumber, capitalize } from "../client.js";
+import { formatNumber, capitalize, metricRows, sortMetricLabels } from "../client.js";
 export function registerAnalyticsTools(server, getClient) {
-    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post (impressions, engagements, likes, etc.).", {
+    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post. Renders every metric the platform reported — impressions, reach, views, saves, likes, comments, shares, clicks, engagements, and more — per platform.", {
         post_id: z.string().describe("The numeric OmniSocials post id (the `id` field from list_posts). NOT a platform post id such as a YouTube video id or tweet id."),
     }, async ({ post_id }) => {
         const result = await getClient().getPostAnalytics(post_id);
@@ -26,41 +26,62 @@ export function registerAnalyticsTools(server, getClient) {
                     }],
             };
         }
-        const totals = { impressions: 0, engagements: 0, likes: 0, comments: 0, shares: 0 };
+        // Every numeric metric the platform reported is rendered via metricRows —
+        // a fixed column set here is how reach/saves/views silently vanished.
         const perPlatform = [];
+        const totalOrder = [];
+        const totalsByLabel = new Map();
+        let totalEngagements = 0;
+        let totalDenom = 0;
         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 rows = metricRows(m);
             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 });
+            // Denominator for engagement rate: the broadest exposure count present.
+            const denom = Number(m.impressions ?? m.views ?? m.reach ?? 0);
+            totalEngagements += engagements;
+            totalDenom += denom;
+            for (const [label, n] of rows) {
+                if (!totalsByLabel.has(label))
+                    totalOrder.push(label);
+                totalsByLabel.set(label, (totalsByLabel.get(label) || 0) + n);
+            }
+            perPlatform.push({
+                platform,
+                rows,
+                engagements,
+                denom,
+                note: typeof m.note === "string" ? m.note : undefined,
+            });
         }
-        let md = `## Post Analytics\n\n`;
-        md += `| Metric | Value |\n`;
-        md += `|--------|-------|\n`;
-        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 (!totalsByLabel.has("Engagements"))
+            totalOrder.push("Engagements");
+        totalsByLabel.set("Engagements", totalEngagements);
+        const renderRate = (engagements, denom) => denom > 0 ? `| **Engagement Rate** | ${((engagements / denom) * 100).toFixed(2)}% |\n` : "";
+        let md = perPlatform.length === 1
+            ? `## Post Analytics — ${capitalize(perPlatform[0].platform)}\n`
+            : `## Post Analytics\n\n`;
+        if (perPlatform.length > 1) {
+            md += `| Metric | Value |\n|--------|-------|\n`;
+            for (const label of sortMetricLabels(totalOrder)) {
+                md += `| **${label}** | ${formatNumber(totalsByLabel.get(label) || 0)} |\n`;
+            }
+            md += renderRate(totalEngagements, totalDenom);
+            md += `\n### Per-Platform Breakdown\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`;
+            if (perPlatform.length > 1)
+                md += `\n#### ${capitalize(p.platform)}\n`;
+            md += `\n| Metric | Value |\n|--------|-------|\n`;
+            for (const [label, n] of p.rows) {
+                md += `| **${label}** | ${formatNumber(n)} |\n`;
+            }
+            md += renderRate(p.engagements, p.denom);
+            if (p.note)
+                md += `\n_${p.note}_\n`;
         }
         return {
             content: [{ type: "text", text: md }],
@@ -88,17 +109,21 @@ export function registerAnalyticsTools(server, getClient) {
             const platformEntries = Object.entries(platforms);
             let impressions = 0;
             let engagements = 0;
-            for (const [platform, p] of platformEntries) {
+            let likes = 0;
+            let comments = 0;
+            let shares = 0;
+            for (const [, p] of platformEntries) {
                 const m = p?.metrics || {};
-                const imp = platform === "instagram"
-                    ? Number(m.reach ?? m.impressions ?? 0)
-                    : Number(m.views ?? m.impressions ?? 0);
-                const likes = Number(m.likes ?? m.favorites ?? m.reactions ?? 0);
-                const comments = Number(m.comments ?? m.replies ?? 0);
-                const shares = Number(m.shares ?? m.retweets ?? m.reposts ?? 0);
-                const eng = m.engagement != null ? Number(m.engagement) : likes + comments + shares;
-                impressions += imp;
-                engagements += eng;
+                // Broadest exposure count present, regardless of the platform's name
+                // for it (LinkedIn: impressions, TikTok/X/YouTube: views, IG: reach).
+                impressions += Number(m.impressions ?? m.views ?? m.reach ?? 0);
+                const l = Number(m.likes ?? m.favorites ?? m.reactions ?? 0);
+                const c = Number(m.comments ?? m.replies ?? 0);
+                const s = Number(m.shares ?? m.retweets ?? m.reposts ?? 0);
+                likes += l;
+                comments += c;
+                shares += s;
+                engagements += m.engagement != null ? Number(m.engagement) : l + c + s;
             }
             return {
                 post_id: entry.post_id,
@@ -106,16 +131,20 @@ export function registerAnalyticsTools(server, getClient) {
                 platformNames: platformEntries.map(([name]) => capitalize(name)).join(", "),
                 impressions,
                 engagements,
+                likes,
+                comments,
+                shares,
             };
         });
         const withData = rows.filter((r) => r.platformCount > 0).length;
         let md = `## Posts Analytics (${rows.length} posts, ${withData} with collected stats)\n\n`;
-        md += `| Post ID | Platforms | Impressions | Engagements |\n`;
-        md += `|---------|-----------|-------------|-------------|\n`;
+        md += `| Post ID | Platforms | Impressions | Engagements | Likes | Comments | Shares |\n`;
+        md += `|---------|-----------|-------------|-------------|-------|----------|--------|\n`;
         for (const r of rows) {
-            md += `| ${r.post_id} | ${r.platformNames || "—"} | ${r.platformCount ? formatNumber(r.impressions) : "—"} | ${r.platformCount ? formatNumber(r.engagements) : "—"} |\n`;
+            const c = (n) => (r.platformCount ? formatNumber(n) : "—");
+            md += `| ${r.post_id} | ${r.platformNames || "—"} | ${c(r.impressions)} | ${c(r.engagements)} | ${c(r.likes)} | ${c(r.comments)} | ${c(r.shares)} |\n`;
         }
-        md += `\nPosts showing "—" have no analytics collected yet. Stats are fetched periodically after publishing; check back in a few hours.\n`;
+        md += `\nPosts showing "—" have no analytics collected yet. Stats are fetched periodically after publishing; check back in a few hours. Use get_post_analytics on a single post for the full per-platform metric set (reach, views, saves, clicks, …).\n`;
         return {
             content: [{ type: "text", text: md }],
         };

package/build/tools/posts.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { formatDateTime, truncate, capitalize, formatNumber } from "../client.js";
+import { formatDateTime, truncate, capitalize, formatNumber, metricRows } from "../client.js";
 // Reusable per-platform option objects for the "first comment" feature — text
 // auto-posted as a comment on the post right after it publishes (hashtags out
 // of the caption, "link in first comment", etc.). Only platforms with a
@@ -140,7 +140,7 @@ export function registerPostTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("get_post", "Get details of a specific post by ID — content, channels, media (with URLs), first comment, Instagram collaborators/user tags/location, dates and live URLs, enough to fully verify a scheduled post without opening the dashboard. 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.", {
+    server.tool("get_post", "Get details of a specific post by ID — content, channels, media (with URLs), first comment, Instagram collaborators/user tags/location/Trial Reel state, dates and live URLs, enough to fully verify a scheduled post without opening the dashboard. 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);
@@ -290,6 +290,16 @@ export function registerPostTools(server, getClient) {
         if (firstCommentRows.length) {
             md += `\n\n### First Comments\n\n${firstCommentRows.join("\n")}\n`;
         }
+        // Trial Reel state: nested under the instagram options object by the
+        // API. Only rendered when enabled, so batch-scheduled Trial Reels can be
+        // verified without opening the dashboard.
+        const igOpts = p.instagram;
+        if (igOpts && typeof igOpts === "object" && igOpts.is_trial_reel === true) {
+            const strategy = igOpts.trial_graduation_strategy === "SS_PERFORMANCE"
+                ? "automatic (Instagram shares it with followers if it performs well)"
+                : "manual (graduate it yourself in the Instagram app)";
+            md += `\n\n**Instagram Trial Reel:** enabled — shown to non-followers first; graduation: ${strategy}\n`;
+        }
         return {
             content: [{ type: "text", text: md }],
         };
@@ -385,7 +395,12 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             thumbnail_type: z.enum(["from-video", "from-library"]).optional(),
             thumb_offset: z.number().optional(),
             cover_url: z.string().optional(),
+            audio_id: z.string().optional().describe("Reels only. Licensed music track to attach — a numeric audio ID from search_instagram_audio. Requires a Facebook account connected to the workspace whose Page links this Instagram account."),
+            audio_volume: z.number().int().min(0).max(100).optional().describe("Volume of the attached music track, 0-100 (default 100). Only used with audio_id."),
+            video_volume: z.number().int().min(0).max(100).optional().describe("Volume of the video's own audio, 0-100 (default 100). Set 0 for a music-only Reel. Only used with audio_id."),
             first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Common for keeping hashtags out of the caption. Not posted for Stories."),
+            is_trial_reel: z.boolean().optional().describe("Publish the reel as an Instagram Trial Reel — shown to non-followers first to test performance before (optionally) graduating to everyone. ONLY set this when the user explicitly asks for a Trial Reel; never enable it by default. NOT available on every account: Instagram requires roughly 1,000+ followers and enables the feature per account (the user sees a 'Trial' toggle when creating a reel in the Instagram app). Ineligible accounts fail at publish time with a clear per-platform error. Reels only."),
+            trial_graduation_strategy: z.enum(["MANUAL", "SS_PERFORMANCE"]).optional().describe("How a Trial Reel graduates to all followers. MANUAL (default): the user decides in the Instagram app. SS_PERFORMANCE: Instagram shares it with followers automatically if it performs well. Only used with is_trial_reel."),
         }).optional().describe("Instagram options"),
         facebook: FACEBOOK_OPTIONS,
         linkedin: LINKEDIN_OPTIONS,
@@ -393,10 +408,12 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         tiktok: z.object({
             privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
             disable_comment: z.boolean().optional(),
-            disable_duet: z.boolean().optional(),
-            disable_stitch: z.boolean().optional(),
-            is_aigc: z.boolean().optional(),
-            brand_content_toggle: z.boolean().optional(),
+            disable_duet: z.boolean().optional().describe("Reels only. Disable Duet on the video."),
+            disable_stitch: z.boolean().optional().describe("Reels only. Disable Stitch on the video."),
+            video_cover_timestamp_ms: z.number().optional().describe("Reels only. Timestamp (ms) of the video frame to use as the cover."),
+            is_aigc: z.boolean().optional().describe("Mark as AI-generated content."),
+            brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
+            brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
             auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
         }).optional().describe("TikTok options"),
         x: z.object({
@@ -544,13 +561,26 @@ Do NOT call without required media — it will fail.`, {
             first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled."),
         }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
         instagram: z.object({
+            audio_id: z.string().optional().describe("Reels only. Licensed music track to attach — a numeric audio ID from search_instagram_audio. Requires a Facebook account connected to the workspace whose Page links this Instagram account."),
+            audio_volume: z.number().int().min(0).max(100).optional().describe("Volume of the attached music track, 0-100 (default 100). Only used with audio_id."),
+            video_volume: z.number().int().min(0).max(100).optional().describe("Volume of the video's own audio, 0-100 (default 100). Set 0 for a music-only Reel. Only used with audio_id."),
             first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Common for keeping hashtags out of the caption. Not posted for Stories."),
+            is_trial_reel: z.boolean().optional().describe("Publish the reel as an Instagram Trial Reel — shown to non-followers first to test performance before (optionally) graduating to everyone. ONLY set this when the user explicitly asks for a Trial Reel; never enable it by default. NOT available on every account: Instagram requires roughly 1,000+ followers and enables the feature per account (the user sees a 'Trial' toggle when creating a reel in the Instagram app). Ineligible accounts fail at publish time with a clear per-platform error. Reels only."),
+            trial_graduation_strategy: z.enum(["MANUAL", "SS_PERFORMANCE"]).optional().describe("How a Trial Reel graduates to all followers. MANUAL (default): the user decides in the Instagram app. SS_PERFORMANCE: Instagram shares it with followers automatically if it performs well. Only used with is_trial_reel."),
         }).optional().describe("Instagram options"),
         facebook: FACEBOOK_OPTIONS,
         linkedin: LINKEDIN_OPTIONS,
         linkedin_page: LINKEDIN_PAGE_OPTIONS,
         tiktok: z.object({
             privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
+            disable_comment: z.boolean().optional(),
+            disable_duet: z.boolean().optional().describe("Reels only. Disable Duet on the video."),
+            disable_stitch: z.boolean().optional().describe("Reels only. Disable Stitch on the video."),
+            video_cover_timestamp_ms: z.number().optional().describe("Reels only. Timestamp (ms) of the video frame to use as the cover."),
+            is_aigc: z.boolean().optional().describe("Mark as AI-generated content."),
+            brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
+            brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
+            auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
         }).optional().describe("TikTok options"),
         x: z.object({
             reply_settings: z.enum(["", "following", "mentionedUsers"]).optional(),
@@ -675,18 +705,25 @@ Do NOT call without required media — it will fail.`, {
             thumbnail_type: z.enum(["from-video", "from-library"]).optional(),
             thumb_offset: z.number().optional(),
             cover_url: z.string().optional(),
+            audio_id: z.string().optional().describe("Reels only. Licensed music track to attach — a numeric audio ID from search_instagram_audio. Requires a Facebook account connected to the workspace whose Page links this Instagram account."),
+            audio_volume: z.number().int().min(0).max(100).optional().describe("Volume of the attached music track, 0-100 (default 100). Only used with audio_id."),
+            video_volume: z.number().int().min(0).max(100).optional().describe("Volume of the video's own audio, 0-100 (default 100). Set 0 for a music-only Reel. Only used with audio_id."),
             first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Pass an empty string to clear a previously set first comment."),
-        }).optional().describe("Instagram options"),
+            is_trial_reel: z.boolean().optional().describe("Publish the reel as an Instagram Trial Reel — shown to non-followers first to test performance before (optionally) graduating to everyone. ONLY set this when the user explicitly asks for a Trial Reel; never enable it by default. NOT available on every account: Instagram requires roughly 1,000+ followers and enables the feature per account. Ineligible accounts fail at publish time with a clear per-platform error. Reels only. Pass false to turn a Trial Reel back into a regular reel."),
+            trial_graduation_strategy: z.enum(["MANUAL", "SS_PERFORMANCE"]).optional().describe("How a Trial Reel graduates to all followers. MANUAL (default): the user decides in the Instagram app. SS_PERFORMANCE: Instagram shares it with followers automatically if it performs well. Only used with is_trial_reel."),
+        }).optional().describe("Instagram options. MERGED into the post's stored options: omitted keys keep their current value (updating one option cannot clear a Trial Reel flag or reel music configured elsewhere)."),
         facebook: FACEBOOK_OPTIONS,
         linkedin: LINKEDIN_OPTIONS,
         linkedin_page: LINKEDIN_PAGE_OPTIONS,
         tiktok: z.object({
             privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
             disable_comment: z.boolean().optional(),
-            disable_duet: z.boolean().optional(),
-            disable_stitch: z.boolean().optional(),
-            is_aigc: z.boolean().optional(),
-            brand_content_toggle: z.boolean().optional(),
+            disable_duet: z.boolean().optional().describe("Reels only. Disable Duet on the video."),
+            disable_stitch: z.boolean().optional().describe("Reels only. Disable Stitch on the video."),
+            video_cover_timestamp_ms: z.number().optional().describe("Reels only. Timestamp (ms) of the video frame to use as the cover."),
+            is_aigc: z.boolean().optional().describe("Mark as AI-generated content."),
+            brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
+            brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
             auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
         }).optional().describe("TikTok options"),
         x: z.object({
@@ -812,7 +849,43 @@ Notes:
         });
         return { content: [{ type: "text", text: md }] };
     });
-    server.tool("get_recent_platform_posts", "Fetch the user's most recent posts straight from their connected platform APIs (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), INCLUDING content published outside OmniSocials. Use this when list_posts is empty — e.g. a brand-new workspace that has not published through OmniSocials yet — so you can still analyze the user's real content. Each post includes normalized `engagement` and `impressions` so you can rank across platforms (Instagram posts include 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); LinkedIn, Threads, Pinterest, and Google Business return captions only. Fetched live, so expect a few seconds of latency. Requires the analytics:read scope.", {
+    server.tool("search_instagram_audio", `Search Instagram's licensed music catalog for a track to attach to a REEL. Use this whenever the user wants to post a reel WITH music/a song/a sound (e.g. "post this reel with trending audio", "add that song to it").
+
+Flow: call with a song/artist/keyword (or NO query for currently trending audio) → present the options → once the user picks, pass that result's \`audio_id\` as \`instagram.audio_id\` on create_post / create_and_publish_post / update_post. Optionally mix with \`instagram.audio_volume\` / \`instagram.video_volume\` (0-100; set video_volume 0 to fully replace the video's own sound). Instagram Reels only — feed posts, carousels, and Stories can't take music via the API (Meta limitation).
+
+Notes: only tracks Meta licenses for third-party publishing appear, so the selection can differ from the Instagram app. Requires the workspace to have a Facebook account connected whose Page is linked to this Instagram account — if results say Facebook is needed, tell the user to connect it under Settings → Organisation → Workspaces.`, {
+        query: z
+            .string()
+            .optional()
+            .describe("Song title, artist, or keyword. OMIT for currently trending audio."),
+        type: z
+            .enum(["music", "original_sound"])
+            .optional()
+            .describe("Catalog to search: licensed music (default) or original sounds created by Instagram users."),
+    }, async ({ query, type }) => {
+        const result = await getClient().searchInstagramAudio(query, type);
+        const tracks = result?.data || [];
+        if (!tracks.length) {
+            const why = result?.error ||
+                (query
+                    ? `No tracks found for "${query}". Try another title or artist — only music licensed for third-party publishing appears here.`
+                    : "No trending audio available right now.");
+            return { content: [{ type: "text", text: why }] };
+        }
+        const fmtDuration = (ms) => {
+            if (!ms)
+                return "—";
+            const s = Math.round(ms / 1000);
+            return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+        };
+        let md = `## ${query ? `Audio matching "${query}"` : "Trending audio"}\n\nAsk the user which track, then pass its ID as \`instagram.audio_id\` (reels only):\n\n`;
+        md += `| # | Title | Artist | Length | audio_id |\n|---|-------|--------|--------|----------|\n`;
+        tracks.forEach((t, i) => {
+            md += `| ${i + 1} | ${t.title || "—"} | ${t.artist || t.ig_username || "—"} | ${fmtDuration(t.duration_ms)} | \`${t.audio_id}\` |\n`;
+        });
+        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.", {
         limit: z
             .string()
             .optional()
@@ -841,15 +914,20 @@ Notes:
             };
         }
         let md = `## Recent platform posts (${posts.length} across ${connected.length} platform${connected.length === 1 ? "" : "s"})\n\n`;
-        md += `| # | Platform | Format | Content | Engagement | Impressions | Date |\n`;
-        md += `|---|----------|--------|---------|------------|-------------|------|\n`;
+        md += `| # | Platform | Format | Content | Engagement | Metrics | Date |\n`;
+        md += `|---|----------|--------|---------|------------|---------|------|\n`;
         posts.forEach((p, i) => {
             const hasMetrics = p.metrics && Object.keys(p.metrics).length > 0;
             const content = truncate(clean(p.text), 45) || "*(no caption)*";
             const eng = hasMetrics ? formatNumber(p.engagement || 0) : "—";
-            const imp = hasMetrics ? formatNumber(p.impressions || 0) : "—";
+            // Every counter the platform reported, compact: "1.4K views · 12 saves".
+            // Engagement has its own column, so skip its row here.
+            const detail = metricRows(p.metrics)
+                .filter(([label]) => label !== "Engagements")
+                .map(([label, n]) => `${formatNumber(n)} ${label.toLowerCase()}`)
+                .join(" · ");
             const date = p.timestamp ? formatDateTime(p.timestamp) : "—";
-            md += `| ${i + 1} | ${capitalize(p.platform)} | ${p.format || "post"} | ${content} | ${eng} | ${imp} | ${date} |\n`;
+            md += `| ${i + 1} | ${capitalize(p.platform)} | ${p.format || "post"} | ${content} | ${eng} | ${detail || "—"} | ${date} |\n`;
         });
         if (result.note)
             md += `\n${result.note}\n`;

package/package.json

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