@omnisocials/mcp-server 1.15.0 → 1.17.0

package/README.md

@@ -139,6 +139,17 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | `list_folders` | List the workspace's media folders |
 | `create_folder` | Create a media folder (optionally nested) |
 
+### Hashtag sets (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_hashtag_sets` | List the workspace's saved hashtag sets |
+| `create_hashtag_set` | Save a reusable, named group of hashtags (max 100 tags) |
+| `update_hashtag_set` | Rename a set and/or replace its tags |
+| `delete_hashtag_set` | Delete a set (existing posts keep their hashtags) |
+
+Apply a set when creating a post: `create_post` / `create_and_publish_post` accept `hashtag_set` (the set name), `hashtag_placement` (`caption_append` default, or `first_comment` to keep tags out of the caption where supported), and `hashtag_platforms` (subset of channels).
+
 ### Accounts (2 tools)
 
 | Tool | Description |
@@ -207,6 +218,16 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 
 ## Changelog
 
+### 1.17.0
+
+- **Per-media alt text (accessibility descriptions):** `media_urls` / `media_ids` entries now accept `{ url, alt }` / `{ id, alt }` objects everywhere, including thread parts. Delivered to Mastodon (media description), Bluesky (embed alt), X (photos/GIFs), and Pinterest (pin `alt_text` fallback). `get_post` reads alt text back.
+
+### 1.16.0
+
+- **Hashtag sets:** save reusable, named groups of hashtags per workspace and apply one to a new post in a single call. Four new tools: `list_hashtag_sets`, `create_hashtag_set`, `update_hashtag_set`, `delete_hashtag_set`.
+- `create_post` / `create_and_publish_post` accept `hashtag_set`, `hashtag_placement` (`caption_append` default, or `first_comment`), and `hashtag_platforms`. The set expands server-side once at create time — editing a set later never changes existing posts; duplicate tags are skipped; Instagram's 30-hashtag cap fails fast with `hashtag_limit_exceeded`.
+- Same tools on the companion server (`mcp.omnisocials.com`).
+
 ### 1.15.0
 
 - **Reel cover read-back:** `get_post` now renders the Instagram Reel cover selection (`thumbnail_type`, `thumb_offset` shown as ms and m:ss, `cover_url`), so a cover set through the API can be verified without opening the dashboard.

package/build/client.d.ts

@@ -17,13 +17,29 @@ export declare function sortMetricLabels(labels: string[]): string[];
  * back-compat key so a zero there is noise, not data.
  */
 export declare function metricRows(m: Record<string, unknown> | null | undefined): Array<[string, number]>;
+/** A `media_urls` entry — a plain external URL, or `{ url, alt }` to attach
+ * an accessibility description (alt text, max 1500 chars) to that file. */
+export type MediaUrlEntry = string | {
+    url: string;
+    alt?: string;
+};
+/** A `media_ids` entry — a plain Library media ID from upload_media, or
+ * `{ id, alt }` to attach an accessibility description (alt text, max 1500
+ * chars) to that file. */
+export type MediaIdEntry = string | {
+    id: string;
+    alt?: string;
+};
 export interface XThreadPartInput {
     /** Tweet text — ≤ 280 chars (the API enforces 280 even for X Premium). */
     text: string;
-    /** Optional per-part media as Library IDs from upload_media (max 4 combined with media_urls). */
-    media_ids?: string[];
-    /** Optional per-part media as external URLs (max 4 combined with media_ids). */
-    media_urls?: string[];
+    /** Optional per-part media as Library IDs from upload_media (max 4 combined
+     * with media_urls). Entries may be `{ id, alt }` to attach alt text (X
+     * applies it to photos/GIFs). */
+    media_ids?: MediaIdEntry[];
+    /** Optional per-part media as external URLs (max 4 combined with media_ids).
+     * Entries may be `{ url, alt }` to attach alt text (photos/GIFs only). */
+    media_urls?: MediaUrlEntry[];
 }
 export interface XPostOptions {
     reply_settings?: "" | "following" | "mentionedUsers";
@@ -43,10 +59,12 @@ export interface XPostOptionsUpdate extends Omit<XPostOptions, "thread_parts"> {
 export interface BlueskyThreadPartInput {
     /** Post text — ≤ 300 characters (counted as graphemes; one emoji = 1). */
     text: string;
-    /** Optional per-part media as Library IDs from upload_media (max 4). */
-    media_ids?: string[];
-    /** Optional per-part media as external URLs (max 4). */
-    media_urls?: string[];
+    /** Optional per-part media as Library IDs from upload_media (max 4).
+     * Entries may be `{ id, alt }` to set the image's embed alt on Bluesky. */
+    media_ids?: MediaIdEntry[];
+    /** Optional per-part media as external URLs (max 4). Entries may be
+     * `{ url, alt }` to set the image's embed alt on Bluesky. */
+    media_urls?: MediaUrlEntry[];
 }
 export interface BlueskyPostOptions {
     /** Provide 2–25 parts to publish as a thread. Omit for a single post. */
@@ -62,10 +80,14 @@ export interface BlueskyPostOptionsUpdate {
 export interface MastodonThreadPartInput {
     /** Status text — ≤ 500 characters by default (some instances allow more). */
     text: string;
-    /** Optional per-part media as Library IDs from upload_media (max 4). */
-    media_ids?: string[];
-    /** Optional per-part media as external URLs (max 4). */
-    media_urls?: string[];
+    /** Optional per-part media as Library IDs from upload_media (max 4).
+     * Entries may be `{ id, alt }` to set the media description — the Mastodon
+     * community strongly values alt text on images. */
+    media_ids?: MediaIdEntry[];
+    /** Optional per-part media as external URLs (max 4). Entries may be
+     * `{ url, alt }` to set the media description — the Mastodon community
+     * strongly values alt text on images. */
+    media_urls?: MediaUrlEntry[];
 }
 export interface MastodonPostOptions {
     /** Provide 2–25 parts to publish as a thread. Omit for a single status. */
@@ -97,8 +119,8 @@ export declare class OmniSocialsClient {
         content: string | Record<string, string>;
         channels?: string[];
         scheduled_at?: string;
-        media_ids?: string[] | Record<string, string[]>;
-        media_urls?: string[] | Record<string, string[]>;
+        media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
+        media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
         type?: string;
         source?: string;
         link_url?: string;
@@ -124,12 +146,15 @@ export declare class OmniSocialsClient {
         bluesky?: BlueskyPostOptions;
         mastodon?: MastodonPostOptions;
         google_business?: Record<string, unknown>;
+        hashtag_set?: string;
+        hashtag_placement?: "caption_append" | "first_comment";
+        hashtag_platforms?: string[];
     }): Promise<ApiResponse<unknown>>;
     createAndPublishPost(data: {
         content: string | Record<string, string>;
         channels?: string[];
-        media_ids?: string[] | Record<string, string[]>;
-        media_urls?: string[] | Record<string, string[]>;
+        media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
+        media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
         type?: string;
         source?: string;
         link_url?: string;
@@ -155,13 +180,16 @@ export declare class OmniSocialsClient {
         bluesky?: BlueskyPostOptions;
         mastodon?: MastodonPostOptions;
         google_business?: Record<string, unknown>;
+        hashtag_set?: string;
+        hashtag_placement?: "caption_append" | "first_comment";
+        hashtag_platforms?: string[];
     }): Promise<ApiResponse<unknown>>;
     updatePost(id: string, data: {
         content?: string | Record<string, string>;
         scheduled_at?: string;
         channels?: string[];
-        media_ids?: string[] | Record<string, string[]>;
-        media_urls?: string[] | Record<string, string[]>;
+        media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
+        media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
         type?: string;
         location_id?: string;
         collaborators?: string[];
@@ -234,6 +262,16 @@ export declare class OmniSocialsClient {
         name: string;
         parent_id?: string;
     }): Promise<ApiResponse<unknown>>;
+    listHashtagSets(): Promise<ApiResponse<unknown>>;
+    createHashtagSet(data: {
+        name: string;
+        hashtags: string[];
+    }): Promise<ApiResponse<unknown>>;
+    updateHashtagSet(id: string, data: {
+        name?: string;
+        hashtags?: string[];
+    }): Promise<ApiResponse<unknown>>;
+    deleteHashtagSet(id: string): Promise<ApiResponse<unknown>>;
     listAccounts(): Promise<ApiResponse<unknown>>;
     getAccount(id: string): Promise<ApiResponse<unknown>>;
     getPostAnalytics(postId: string): Promise<ApiResponse<unknown>>;

package/build/client.js

@@ -272,6 +272,19 @@ export class OmniSocialsClient {
     async createFolder(data) {
         return this.request("POST", "/folders", data);
     }
+    // Hashtag Sets
+    async listHashtagSets() {
+        return this.request("GET", "/hashtag-sets");
+    }
+    async createHashtagSet(data) {
+        return this.request("POST", "/hashtag-sets", data);
+    }
+    async updateHashtagSet(id, data) {
+        return this.request("PATCH", `/hashtag-sets/${id}`, data);
+    }
+    async deleteHashtagSet(id) {
+        return this.request("DELETE", `/hashtag-sets/${id}`);
+    }
     // Accounts
     async listAccounts() {
         return this.request("GET", "/accounts");

package/build/index.js

@@ -8,6 +8,7 @@ import { registerMediaTools } from "./tools/media.js";
 import { registerAccountTools } from "./tools/accounts.js";
 import { registerAnalyticsTools } from "./tools/analytics.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
+import { registerHashtagSetTools } from "./tools/hashtag-sets.js";
 import { registerInboxTools } from "./tools/inbox.js";
 import { registerWorkspaceTools } from "./tools/workspaces.js";
 const apiKeyEnv = process.env.OMNISOCIALS_API_KEY;
@@ -28,7 +29,7 @@ const sessionState = { activeIndex: 0 };
 const getActiveClient = () => workspaceClients[sessionState.activeIndex].client;
 const server = new McpServer({
     name: "OmniSocials",
-    version: "1.13.1",
+    version: "1.17.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);
@@ -36,6 +37,7 @@ registerMediaTools(server, getActiveClient);
 registerAccountTools(server, getActiveClient);
 registerAnalyticsTools(server, getActiveClient);
 registerWebhookTools(server, getActiveClient);
+registerHashtagSetTools(server, getActiveClient);
 registerInboxTools(server, getActiveClient);
 registerWorkspaceTools(server, workspaceClients, sessionState);
 // Register prompts

package/build/tools/hashtag-sets.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OmniSocialsClient } from "../client.js";
+export declare function registerHashtagSetTools(server: McpServer, getClient: () => OmniSocialsClient): void;

package/build/tools/hashtag-sets.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export function registerHashtagSetTools(server, getClient) {
+    server.tool("list_hashtag_sets", "List the saved hashtag sets in this workspace. Apply one to a new post by passing its name via create_post (hashtag_set) — the tags are appended to the captions or, with hashtag_placement='first_comment', posted as the auto first comment.", {}, async () => {
+        const result = await getClient().listHashtagSets();
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const sets = Array.isArray(result.data) ? result.data : result.data?.data || [];
+        if (!sets.length) {
+            return {
+                content: [{ type: "text", text: "No hashtag sets yet. Create one with create_hashtag_set." }],
+            };
+        }
+        let md = `## Hashtag Sets (${sets.length})\n\n`;
+        md += `| Set ID | Name | Tags | Preview |\n`;
+        md += `|--------|------|------|---------|\n`;
+        for (const s of sets) {
+            const preview = (s.preview || "").length > 80 ? `${s.preview.slice(0, 77)}…` : s.preview || "";
+            md += `| \`${s.id}\` | ${s.name} | ${s.hashtag_count} | ${preview} |\n`;
+        }
+        md += `\nApply a set with create_post (hashtag_set="<name>"). Edit with update_hashtag_set.`;
+        return {
+            content: [{ type: "text", text: md }],
+        };
+    });
+    server.tool("create_hashtag_set", "Save a reusable, named group of hashtags (e.g. 'Fitness Brand' -> #fitness #gym #workout). Tags may include or omit the leading '#'; they are deduped case-insensitively and kept in order (max 100). Then apply the set to any new post via create_post (hashtag_set).", {
+        name: z.string().describe("Set name, unique per workspace, e.g. 'Fitness Brand'"),
+        hashtags: z.array(z.string()).describe('Tags in order, with or without the leading "#", e.g. ["fitness", "#gym", "workout"]'),
+    }, async (params) => {
+        const result = await getClient().createHashtagSet(params);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const s = result.data;
+        return {
+            content: [{
+                    type: "text",
+                    text: `Created hashtag set \`${s.id}\` "${s.name}" (${s.hashtag_count} tags): ${s.preview}\n\nApply it with create_post (hashtag_set="${s.name}").`,
+                }],
+        };
+    });
+    server.tool("update_hashtag_set", "Rename a hashtag set and/or replace its tags. 'hashtags' replaces the FULL list — to add or remove tags, pass the complete new list (see list_hashtag_sets for the current tags). Posts that already used the set are unaffected.", {
+        set_id: z.string().describe("The hashtag set id (from list_hashtag_sets)"),
+        name: z.string().optional().describe("New name for the set"),
+        hashtags: z.array(z.string()).optional().describe("Full replacement tag list, in order"),
+    }, async ({ set_id, name, hashtags }) => {
+        const result = await getClient().updateHashtagSet(set_id, { name, hashtags });
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const s = result.data;
+        return {
+            content: [{
+                    type: "text",
+                    text: `Updated hashtag set \`${s.id}\` "${s.name}" (${s.hashtag_count} tags): ${s.preview}`,
+                }],
+        };
+    });
+    server.tool("delete_hashtag_set", "Delete a saved hashtag set. Posts that already used it keep their hashtags — the tags were merged into their captions at create time.", {
+        set_id: z.string().describe("The hashtag set id (from list_hashtag_sets)"),
+    }, async ({ set_id }) => {
+        const result = await getClient().deleteHashtagSet(set_id);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Deleted hashtag set \`${set_id}\`.` }],
+        };
+    });
+}

package/build/tools/media.js

@@ -142,7 +142,7 @@ When the user provides an image in the conversation (not a URL), use base64_data
         if (compatibility && compatibility.compatible === false && compatibility.summary) {
             md += `\n\n⚠️ **${compatibility.summary}** It will still post to your other connected platforms. Ask the user whether to continue before adding it to a post.`;
         }
-        md += `\n\nUse this Media ID with \`media_ids\` when creating posts (including inside \`x.thread_parts[].media_ids\`). The public URL above also works anywhere \`media_urls\` is accepted.`;
+        md += `\n\nUse this Media ID with \`media_ids\` when creating posts (including inside \`x.thread_parts[].media_ids\`). The public URL above also works anywhere \`media_urls\` is accepted. To attach alt text (an accessibility description), pass \`{ id: "<Media ID>", alt: "..." }\` instead of the bare ID — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest.`;
         return {
             content: [{ type: "text", text: md }],
         };

package/build/tools/posts.js

@@ -1,5 +1,27 @@
 import { z } from "zod";
 import { formatDateTime, truncate, capitalize, formatNumber, metricRows } from "../client.js";
+// Shared media entry schemas — every media list (flat arrays, per-platform
+// records, and x/bluesky/mastodon thread parts) accepts either a plain string
+// or an object carrying `alt`: an accessibility description (alt text, max
+// 1500 chars) for that file. Alt text is delivered to Mastodon (media
+// description — the community strongly values alt text), Bluesky (embed alt),
+// X (photos/GIFs only), and Pinterest (used as the pin alt_text when
+// pinterest.alt_text is not set); other platforms ignore it for now.
+const ALT_TEXT_DESCRIBE = "Accessibility description (alt text) for this file, max 1500 chars. Delivered to Mastodon (media description), Bluesky (embed alt), X (photos/GIFs only), and Pinterest (used as the pin alt_text when pinterest.alt_text is not set); other platforms ignore it.";
+const mediaUrlEntry = z.union([
+    z.string(),
+    z.object({
+        url: z.string().describe("External image/video URL."),
+        alt: z.string().max(1500).optional().describe(ALT_TEXT_DESCRIBE),
+    }),
+]).describe("External media URL — a plain string, or { url, alt } to attach an accessibility description (alt text).");
+const mediaIdEntry = z.union([
+    z.string(),
+    z.object({
+        id: z.string().describe("Library media ID from upload_media."),
+        alt: z.string().max(1500).optional().describe(ALT_TEXT_DESCRIBE),
+    }),
+]).describe("Library media ID — a plain string, or { id, alt } to attach an accessibility description (alt text).");
 // 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 +162,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/Trial Reel state/Reel cover (thumbnail_type + thumb_offset in ms), 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 + any per-media alt text), first comment, Instagram collaborators/user tags/location/Trial Reel state/Reel cover (thumbnail_type + thumb_offset in ms), 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);
@@ -204,7 +226,8 @@ export function registerPostTools(server, getClient) {
                     md += `**${group === "default" ? "Default (all platforms)" : capitalize(group.replace(/_/g, " "))}**\n`;
                 }
                 items.forEach((m, i) => {
-                    md += `${i + 1}. ${mediaUrlOf(m) || "*(no url)*"}\n`;
+                    const alt = typeof m?.alt === "string" && m.alt ? ` — alt: "${m.alt}"` : "";
+                    md += `${i + 1}. ${mediaUrlOf(m) || "*(no url)*"}${alt}\n`;
                 });
                 md += `\n`;
             }
@@ -221,8 +244,10 @@ export function registerPostTools(server, getClient) {
                 const text = typeof part.text === "string" ? part.text : "";
                 md += `**${i + 1}/${threadParts.length}.** ${text}\n`;
                 if (Array.isArray(part.media_urls) && part.media_urls.length) {
-                    for (const url of part.media_urls)
-                        md += `  - ${url}\n`;
+                    for (const entry of part.media_urls) {
+                        const alt = typeof entry === "object" && entry?.alt ? ` — alt: "${entry.alt}"` : "";
+                        md += `  - ${mediaUrlOf(entry) || "*(no url)*"}${alt}\n`;
+                    }
                 }
                 md += `\n`;
             }
@@ -238,8 +263,10 @@ export function registerPostTools(server, getClient) {
                 const text = typeof part.text === "string" ? part.text : "";
                 md += `**${i + 1}/${bskyThreadParts.length}.** ${text}\n`;
                 if (Array.isArray(part.media_urls) && part.media_urls.length) {
-                    for (const url of part.media_urls)
-                        md += `  - ${url}\n`;
+                    for (const entry of part.media_urls) {
+                        const alt = typeof entry === "object" && entry?.alt ? ` — alt: "${entry.alt}"` : "";
+                        md += `  - ${mediaUrlOf(entry) || "*(no url)*"}${alt}\n`;
+                    }
                 }
                 md += `\n`;
             }
@@ -255,8 +282,10 @@ export function registerPostTools(server, getClient) {
                 const text = typeof part.text === "string" ? part.text : "";
                 md += `**${i + 1}/${mastoThreadParts.length}.** ${text}\n`;
                 if (Array.isArray(part.media_urls) && part.media_urls.length) {
-                    for (const url of part.media_urls)
-                        md += `  - ${url}\n`;
+                    for (const entry of part.media_urls) {
+                        const alt = typeof entry === "object" && entry?.alt ? ` — alt: "${entry.alt}"` : "";
+                        md += `  - ${mediaUrlOf(entry) || "*(no url)*"}${alt}\n`;
+                    }
                 }
                 md += `\n`;
             }
@@ -367,13 +396,13 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         channels: z.array(z.string()).optional().describe("Array of channel IDs to post to. Get the available channel IDs from list_accounts. Each entry may be a bare platform name (e.g. `\"youtube\"`) or the composite `\"<workspace_id>_<platform>\"` form from list_accounts (e.g. `\"844008_youtube\"`); always source these from list_accounts for the API key in use — composite IDs with an unknown or mismatched workspace prefix are rejected as unknown accounts. Note: `linkedin` (personal profile) and `linkedin_page` (company page) are independent channels. A workspace can have both connected and post to each separately."),
         scheduled_at: z.string().optional().describe("ISO 8601 date for scheduled publishing"),
         media_ids: z.union([
-            z.array(z.string()),
-            z.record(z.string(), z.array(z.string())),
-        ]).optional().describe("Media IDs from upload — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...] }"),
+            z.array(mediaIdEntry),
+            z.record(z.string(), z.array(mediaIdEntry)),
+        ]).optional().describe("Media IDs from upload — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...] }. Each entry is a plain ID string or { id, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest."),
         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, each file ≤ 100 MB. 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. For files over 100 MB (up to 1 GB): upload_media with method 'url' first, then pass the returned media id in `media`."),
+            z.array(mediaUrlEntry),
+            z.record(z.string(), z.array(mediaUrlEntry)),
+        ]).optional().describe("External image/video URLs — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...], pinterest: [...] }. Each entry is a plain URL string or { url, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest. Max 10 total, each file ≤ 100 MB. 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. For files over 100 MB (up to 1 GB): upload_media with method 'url' first, then pass the returned media id in `media`."),
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story' (Instagram/Facebook/Snapchat), 'reel' (Instagram/Facebook/YouTube/TikTok)"),
         link_url: z.string().optional().describe("URL to share as a rich preview card on platforms that support link-share posts (LinkedIn and Facebook). The URL renders as a tile with thumbnail / title / description instead of plain text. Ignored on platforms that don't support link shares, and ignored on posts that already have media attached (media wins)."),
         link_title: z.string().optional().describe("Optional title for the link-share preview. LinkedIn uses this when set; Facebook ignores it and fetches OG metadata server-side. Omit to let LinkedIn auto-fetch the page title."),
@@ -387,6 +416,9 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             y: z.number().min(0).max(1).describe("Vertical position 0.0–1.0 from the photo's top edge."),
             image_index: z.number().int().min(0).optional().describe("0-based carousel slide this tag belongs to. Omit (or 0) for a single image."),
         })).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
+        hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. The set's tags are merged in ONCE at create time — tags already in a caption are skipped, and Instagram's 30-hashtag cap returns a clear hashtag_limit_exceeded error. When the user says 'add my usual hashtags', check list_hashtag_sets first."),
+        hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("Where the set's tags land. caption_append (default): appended to each target caption after a blank line. first_comment: posted as the auto first comment on Instagram/Facebook/LinkedIn/LinkedIn Page/YouTube (appended after any explicit first_comment); platforms without a comment API fall back to caption_append. Stories always use captions."),
+        hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to (e.g. [\"instagram\", \"tiktok\"]). Defaults to all selected channels."),
         pinterest: z.object({
             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). For carousel pins (2–5 images) this title applies to the whole pin, not individual slides."),
@@ -436,22 +468,22 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             made_with_ai: z.boolean().optional().describe("Mark as AI-generated content"),
             thread_parts: z.array(z.object({
                 text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Attach your uploaded graphics to any tweet in the thread."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids)"),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Each entry is a plain ID string or { id, alt } to attach alt text (X applies it to photos/GIFs). Attach your uploaded graphics to any tweet in the thread."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids). Each entry is a plain URL string or { url, alt } to attach alt text (X applies it to photos/GIFs)."),
             })).min(2).max(25).optional().describe("Publish as a chained X thread instead of a single tweet. Provide 2–25 parts; each is posted in order via in_reply_to_tweet_id. Attach media to any part (first tweet or reply) via media_ids (from upload_media) or media_urls — max 4 per part. For a single tweet, omit thread_parts and use content."),
         }).optional().describe("X (Twitter) options"),
         bluesky: z.object({
             thread_parts: z.array(z.object({
                 text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images."),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images. Each entry is a plain ID string or { id, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images. Each entry is a plain URL string or { url, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
             })).min(2).max(25).optional().describe("Publish as a chained Bluesky thread instead of a single post. Provide 2–25 parts; each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids (from upload_media) or media_urls — a part is one video OR up to 4 images. Links, mentions and hashtags are made clickable automatically. For a single post, omit thread_parts and use content."),
         }).optional().describe("Bluesky options"),
         mastodon: z.object({
             thread_parts: z.array(z.object({
                 text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4)."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-status media as external URLs (max 4)."),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4). Each entry is a plain ID string or { id, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-status media as external URLs (max 4). Each entry is a plain URL string or { url, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
             })).min(2).max(25).optional().describe("Publish as a chained Mastodon thread instead of a single status. Provide 2–25 parts; each is posted in order as a native reply to the previous status (in_reply_to_id). Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part. For a single status, omit thread_parts and use content."),
         }).optional().describe("Mastodon options"),
         google_business: z.object({
@@ -545,13 +577,13 @@ Do NOT call without required media — it will fail.`, {
         content: z.union([z.string(), z.record(z.string(), z.string())]).describe("Post caption. String for same text on all channels, or object with platform keys for per-channel captions: { \"default\": \"fallback\", \"linkedin\": \"long version\", \"threads\": \"short version\" }. The \"default\" key is used for any selected channel without its own key."),
         channels: z.array(z.string()).optional().describe("Array of channel IDs to post to. Get the available channel IDs from list_accounts. Each entry may be a bare platform name (e.g. `\"youtube\"`) or the composite `\"<workspace_id>_<platform>\"` form from list_accounts (e.g. `\"844008_youtube\"`); always source these from list_accounts for the API key in use — composite IDs with an unknown or mismatched workspace prefix are rejected as unknown accounts. Note: `linkedin` (personal profile) and `linkedin_page` (company page) are independent channels. A workspace can have both connected and post to each separately."),
         media_ids: z.union([
-            z.array(z.string()),
-            z.record(z.string(), z.array(z.string())),
-        ]).optional().describe("Media IDs from upload — flat array or per-platform object"),
+            z.array(mediaIdEntry),
+            z.record(z.string(), z.array(mediaIdEntry)),
+        ]).optional().describe("Media IDs from upload — flat array or per-platform object. Each entry is a plain ID string or { id, alt } to attach alt text — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest."),
         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, each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
+            z.array(mediaUrlEntry),
+            z.record(z.string(), z.array(mediaUrlEntry)),
+        ]).optional().describe("External image/video URLs — flat array or per-platform object. Each entry is a plain URL string or { url, alt } to attach alt text — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest. Max 10 total, each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). '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'"),
         location_id: z.string().optional().describe("Instagram only. Facebook Place ID of a single physical venue to tag the post's location. Applied to single-image and carousel Instagram feed posts. Use the `search_locations` tool to find a valid ID. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors (the 'Collab' feature). Works on image, carousel, and reel posts — NOT Stories. A leading '@' is stripped; usernames are case-insensitive. Private or non-existent usernames are rejected by Instagram at publish time. Ignored by other platforms."),
@@ -561,6 +593,9 @@ Do NOT call without required media — it will fail.`, {
             y: z.number().min(0).max(1).describe("Vertical position 0.0–1.0 from the photo's top edge."),
             image_index: z.number().int().min(0).optional().describe("0-based carousel slide this tag belongs to. Omit (or 0) for a single image."),
         })).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
+        hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. Tags are merged in once at create time; tags already in a caption are skipped."),
+        hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("caption_append (default) appends tags to the captions; first_comment posts them as the auto first comment on comment-capable platforms (others fall back to caption)."),
+        hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to. Defaults to all selected channels."),
         pinterest: z.object({
             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). For carousel pins (2–5 images) this title applies to the whole pin, not individual slides."),
@@ -605,22 +640,22 @@ Do NOT call without required media — it will fail.`, {
             made_with_ai: z.boolean().optional().describe("Mark as AI-generated content"),
             thread_parts: z.array(z.object({
                 text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Attach your uploaded graphics to any tweet in the thread."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids)"),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Each entry is a plain ID string or { id, alt } to attach alt text (X applies it to photos/GIFs). Attach your uploaded graphics to any tweet in the thread."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids). Each entry is a plain URL string or { url, alt } to attach alt text (X applies it to photos/GIFs)."),
             })).min(2).max(25).optional().describe("Publish as a chained X thread (2–25 parts). Each is posted in order via in_reply_to_tweet_id. Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part."),
         }).optional().describe("X (Twitter) options"),
         bluesky: z.object({
             thread_parts: z.array(z.object({
                 text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images."),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images. Each entry is a plain ID string or { id, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images. Each entry is a plain URL string or { url, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
             })).min(2).max(25).optional().describe("Publish as a chained Bluesky thread (2–25 parts). Each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids or media_urls — one video OR up to 4 images per part. Links, mentions and hashtags are made clickable automatically."),
         }).optional().describe("Bluesky options"),
         mastodon: z.object({
             thread_parts: z.array(z.object({
                 text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4)."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-status media as external URLs (max 4)."),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4). Each entry is a plain ID string or { id, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-status media as external URLs (max 4). Each entry is a plain URL string or { url, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
             })).min(2).max(25).optional().describe("Publish as a chained Mastodon thread (2–25 parts). Each is posted in order as a native reply (in_reply_to_id). Attach media to any part via media_ids or media_urls — max 4 per part."),
         }).optional().describe("Mastodon options"),
         google_business: z.object({
@@ -685,13 +720,13 @@ Do NOT call without required media — it will fail.`, {
         scheduled_at: z.string().optional().describe("Updated scheduled date (ISO 8601)"),
         channels: z.array(z.string()).optional().describe("Updated channel IDs. Bare platform name or composite `\"<workspace_id>_<platform>\"`; always source from list_accounts for this API key (unknown or mismatched workspace prefixes are rejected as unknown accounts). Note: `linkedin` (personal profile) and `linkedin_page` (company page) are independent channels."),
         media_ids: z.union([
-            z.array(z.string()),
-            z.record(z.string(), z.array(z.string())),
-        ]).optional().describe("Media IDs — flat array or per-platform object"),
+            z.array(mediaIdEntry),
+            z.record(z.string(), z.array(mediaIdEntry)),
+        ]).optional().describe("Media IDs — flat array or per-platform object. Each entry is a plain ID string or { id, alt } to attach alt text — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest."),
         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, each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
+            z.array(mediaUrlEntry),
+            z.record(z.string(), z.array(mediaUrlEntry)),
+        ]).optional().describe("External URLs — flat array or per-platform object. Each entry is a plain URL string or { url, alt } to attach alt text — delivered to Mastodon, Bluesky, X (photos/GIFs), and Pinterest. Max 10 total, each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
         location_id: z.string().optional().describe("Instagram only. Facebook Place/Page ID to tag the post's location with. Send an empty string to clear an existing location tag. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors. Replaces the existing collaborator list. Send an empty array to clear collaborators. Works on image, carousel, and reel posts — NOT Stories. Ignored by other platforms."),
         user_tags: z.array(z.object({
@@ -749,22 +784,22 @@ Do NOT call without required media — it will fail.`, {
             made_with_ai: z.boolean().optional(),
             thread_parts: z.array(z.object({
                 text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Attach your uploaded graphics to any tweet in the thread."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids)"),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Each entry is a plain ID string or { id, alt } to attach alt text (X applies it to photos/GIFs). Attach your uploaded graphics to any tweet in the thread."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids). Each entry is a plain URL string or { url, alt } to attach alt text (X applies it to photos/GIFs)."),
             })).min(2).max(25).nullable().optional().describe("Replace the X thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls, max 4 per part), or `null` to revert to single-tweet mode."),
         }).optional().describe("X (Twitter) options"),
         bluesky: z.object({
             thread_parts: z.array(z.object({
                 text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images."),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images. Each entry is a plain ID string or { id, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images. Each entry is a plain URL string or { url, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
             })).min(2).max(25).nullable().optional().describe("Replace the Bluesky thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls; one video OR up to 4 images per part), or `null` to revert to single-post mode."),
         }).optional().describe("Bluesky options"),
         mastodon: z.object({
             thread_parts: z.array(z.object({
                 text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
-                media_ids: z.array(z.string()).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4)."),
-                media_urls: z.array(z.string()).max(4).optional().describe("Per-status media as external URLs (max 4)."),
+                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4). Each entry is a plain ID string or { id, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
+                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-status media as external URLs (max 4). Each entry is a plain URL string or { url, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
             })).min(2).max(25).nullable().optional().describe("Replace the Mastodon thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls; max 4 per part), or `null` to revert to single-status mode."),
         }).optional().describe("Mastodon options"),
         google_business: z.object({

package/build/types.d.ts

@@ -80,7 +80,12 @@ export interface Post {
         thread_parts?: Array<{
             id?: string;
             text: string;
-            media_urls?: string[];
+            /** Entries are plain URLs, or { url, alt } when the media carries an
+             * accessibility description (alt text). */
+            media_urls?: Array<string | {
+                url: string;
+                alt?: string;
+            }>;
         }>;
         [key: string]: unknown;
     };
@@ -154,6 +159,17 @@ export interface Webhook {
     } | null;
     created_at: string;
 }
+export interface HashtagSet {
+    id: string;
+    name: string;
+    /** Ordered tags WITHOUT the leading '#' */
+    hashtags: string[];
+    hashtag_count: number;
+    /** The tags rendered as caption text, e.g. "#fitness #gym" */
+    preview: string;
+    created_at: string;
+    updated_at: string;
+}
 export interface AnalyticsOverview {
     total_posts: number;
     total_impressions: number;

package/package.json

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