@omnisocials/mcp-server 1.11.0 → 1.12.0

package/build/client.d.ts

@@ -187,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

@@ -226,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.11.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/posts.js

@@ -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,6 +849,42 @@ Notes:
         });
         return { content: [{ type: "text", text: md }] };
     });
+    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()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnisocials/mcp-server",
-  "version": "1.11.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",