@omnisocials/mcp-server 1.5.0 → 1.7.0

package/README.md

@@ -128,13 +128,16 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | `publish_post` | Publish a draft or scheduled post now |
 | `search_locations` | Find an Instagram location to tag (returns place IDs for `location_id`) |
 
-### Media (3 tools)
+### Media & folders (6 tools)
 
 | Tool | Description |
 |------|-------------|
-| `list_media` | List all media files |
-| `upload_media` | Upload media from a URL (max 50MB) |
+| `list_media` | List media files; filter by `search` (name) or `folder_id` |
+| `upload_media` | Upload media from a URL (max 50MB); set a `name` and a `folder` |
+| `update_media` | Rename a media file or move it to a folder |
 | `delete_media` | Delete a media file |
+| `list_folders` | List the workspace's media folders |
+| `create_folder` | Create a media folder (optionally nested) |
 
 ### Accounts (2 tools)
 
@@ -156,7 +159,7 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | Tool | Description |
 |------|-------------|
 | `list_workspaces` | List all workspaces available in this session |
-| `switch_workspace` | Switch the active workspace |
+| `switch_workspace` | Switch the active workspace **by name** (id or list number also accepted) |
 
 ### Webhooks (5 tools)
 

package/build/client.d.ts

@@ -56,6 +56,13 @@ export declare class OmniSocialsClient {
         link_description?: string;
         link_thumbnail_url?: string;
         location_id?: string;
+        collaborators?: string[];
+        user_tags?: Array<{
+            username: string;
+            x: number;
+            y: number;
+            image_index?: number;
+        }>;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
@@ -75,6 +82,13 @@ export declare class OmniSocialsClient {
         link_description?: string;
         link_thumbnail_url?: string;
         location_id?: string;
+        collaborators?: string[];
+        user_tags?: Array<{
+            username: string;
+            x: number;
+            y: number;
+            image_index?: number;
+        }>;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
@@ -90,6 +104,13 @@ export declare class OmniSocialsClient {
         media_urls?: string[] | Record<string, string[]>;
         type?: string;
         location_id?: string;
+        collaborators?: string[];
+        user_tags?: Array<{
+            username: string;
+            x: number;
+            y: number;
+            image_index?: number;
+        }>;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
@@ -104,17 +125,32 @@ export declare class OmniSocialsClient {
     listMedia(params?: {
         limit?: string;
         offset?: string;
+        search?: string;
+        folder_id?: string;
     }): Promise<ApiResponse<unknown>>;
     uploadMedia(data: {
         url: string;
         filename?: string;
+        name?: string;
+        folder?: string;
     }): Promise<ApiResponse<unknown>>;
     uploadMediaFromBase64(data: {
         data: string;
         mime_type: string;
         filename?: string;
+        name?: string;
+        folder?: string;
     }): Promise<ApiResponse<unknown>>;
     deleteMedia(id: string): Promise<ApiResponse<unknown>>;
+    updateMedia(id: string, data: {
+        name?: string;
+        folder_id?: string | null;
+    }): Promise<ApiResponse<unknown>>;
+    listFolders(): Promise<ApiResponse<unknown>>;
+    createFolder(data: {
+        name: string;
+        parent_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

@@ -170,6 +170,16 @@ export class OmniSocialsClient {
     async deleteMedia(id) {
         return this.request("DELETE", `/media/${id}`);
     }
+    async updateMedia(id, data) {
+        return this.request("PATCH", `/media/${id}`, data);
+    }
+    // Folders
+    async listFolders() {
+        return this.request("GET", "/folders");
+    }
+    async createFolder(data) {
+        return this.request("POST", "/folders", data);
+    }
     // Accounts
     async listAccounts() {
         return this.request("GET", "/accounts");

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.2.0",
+    version: "1.7.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);

package/build/tools/analytics.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { formatNumber, capitalize } 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.).", {
-        post_id: z.string().describe("The post ID to get analytics for"),
+        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);
         if (result.error) {

package/build/tools/media.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
 import { fetchImageAsBase64, formatBytes } from "../client.js";
 export function registerMediaTools(server, getClient) {
-    server.tool("list_media", "List all media files in the workspace. Returns each file's ID, URL, type (image/video), and size. Use this to help users pick media for posts, stories, or reels. Media IDs or URLs from this list can be passed to create_post.", {
+    server.tool("list_media", "List media files in the workspace. Returns each file's ID, name, folder, type (image/video), and size. To reuse an existing graphic, SEARCH for it by name here FIRST instead of re-uploading — re-uploading the same image creates duplicates. Media IDs from this list can be passed to create_post. Organize assets into folders with create_folder / list_folders.", {
         limit: z.string().optional().describe("Max results to return"),
         offset: z.string().optional().describe("Offset for pagination"),
+        search: z.string().optional().describe('Find a file by name or filename, e.g. "play5get50". Use this before uploading to check if the graphic already exists.'),
+        folder_id: z.string().optional().describe('Only return media in this folder id (from list_folders). Use "root" for unfiled items.'),
     }, async (params) => {
         const result = await getClient().listMedia(params);
         if (result.error) {
@@ -13,22 +15,26 @@ export function registerMediaTools(server, getClient) {
         }
         const items = Array.isArray(result.data) ? result.data : result.data?.media || [];
         if (!items.length) {
+            const hint = params?.search
+                ? `No media found matching "${params.search}". It hasn't been uploaded yet — upload it (and pass a \`name\`) so it's findable next time.`
+                : "No media files found.";
             return {
-                content: [{ type: "text", text: "No media files found." }],
+                content: [{ type: "text", text: hint }],
             };
         }
         let md = `## Media Library (${items.length} files)\n\n`;
-        md += `| # | Type | Filename | Size | Media ID |\n`;
-        md += `|---|------|----------|------|----------|\n`;
+        md += `| # | Type | Name | Folder | Size | Media ID |\n`;
+        md += `|---|------|------|--------|------|----------|\n`;
         for (let i = 0; i < items.length; i++) {
             const m = items[i];
             // `type` may be "video"/"image" (normalized) or a raw MIME like "video/mp4".
             const rawType = typeof m.type === "string" ? m.type : "";
             const isVideo = rawType === "video" || rawType.startsWith("video/");
             const type = isVideo ? "Video" : "Image";
-            md += `| ${i + 1} | ${type} | ${m.filename || "—"} | ${formatBytes(m.size || 0)} | \`${m.id}\` |\n`;
+            const folder = m.folder_id ? `\`${m.folder_id}\`` : "—";
+            md += `| ${i + 1} | ${type} | ${m.name || m.filename || "—"} | ${folder} | ${formatBytes(m.size || 0)} | \`${m.id}\` |\n`;
         }
-        md += `\nUse the **Media ID** with \`media_ids\` when creating posts.`;
+        md += `\nUse the **Media ID** with \`media_ids\` when creating posts. Rename or move a file with \`update_media\`. See folders with \`list_folders\`.`;
         // Fetch thumbnails for image files (max 4)
         const content = [];
         const imageItems = items.filter((m) => {
@@ -56,6 +62,8 @@ When the user provides an image in the conversation (not a URL), use base64_data
         base64_data: z.string().optional().describe("Base64-encoded file data. Use when the user provides an image directly in chat rather than a URL."),
         mime_type: z.string().optional().describe("MIME type of the file (e.g. 'image/jpeg', 'image/png'). Required when using base64_data."),
         filename: z.string().optional().describe("Optional filename for the uploaded media"),
+        name: z.string().optional().describe('Human-readable label so you can find this asset by name later instead of re-uploading it, e.g. "pp-play5get50". Strongly recommended on every upload.'),
+        folder: z.string().optional().describe('Optional folder name to file this asset under (created at the top level if it does not exist), e.g. "win-graphics". See list_folders.'),
     }, async (params) => {
         let result;
         if (params.base64_data && params.mime_type) {
@@ -63,10 +71,12 @@ When the user provides an image in the conversation (not a URL), use base64_data
                 data: params.base64_data,
                 mime_type: params.mime_type,
                 filename: params.filename,
+                name: params.name || params.filename,
+                folder: params.folder,
             });
         }
         else if (params.url) {
-            result = await getClient().uploadMedia({ url: params.url, filename: params.filename });
+            result = await getClient().uploadMedia({ url: params.url, filename: params.filename, name: params.name || params.filename, folder: params.folder });
         }
         else {
             return {
@@ -83,8 +93,10 @@ When the user provides an image in the conversation (not a URL), use base64_data
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;
         md += `| **Media ID** | \`${m.id}\` |\n`;
+        md += `| **Name** | ${m.name || m.filename || "—"} |\n`;
         md += `| **Type** | ${m.type || "—"} |\n`;
-        md += `| **Filename** | ${m.filename || "—"} |\n`;
+        if (m.folder_id)
+            md += `| **Folder** | \`${m.folder_id}\` |\n`;
         md += `| **Size** | ${formatBytes(m.size || 0)} |\n`;
         if (m.url)
             md += `| **URL** | ${m.url} |\n`;
@@ -93,12 +105,64 @@ When the user provides an image in the conversation (not a URL), use base64_data
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("delete_media", "Delete a media file by ID.", {
-        id: z.string().describe("The media ID to delete"),
-    }, async ({ id }) => {
-        const result = await getClient().deleteMedia(id);
+    server.tool("update_media", "Rename an existing media file or move it into a folder (so it's findable later instead of re-uploading it). Only the fields you pass are changed.", {
+        id: z.string().describe("The media ID to update"),
+        name: z.string().optional().describe('New human-readable label, e.g. "pp-play5get50". Pass an empty string to clear it.'),
+        folder_id: z.string().optional().describe('Move the file into this folder id (from list_folders). Pass an empty string to move it to the root ("All media").'),
+    }, async ({ id, name, folder_id }) => {
+        const body = {};
+        if (name !== undefined)
+            body.name = name;
+        if (folder_id !== undefined)
+            body.folder_id = folder_id === "" ? null : folder_id;
+        const result = await getClient().updateMedia(id, body);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const m = result.data;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated media \`${m.id}\`.\n\n| Field | Value |\n|-------|-------|\n| **Name** | ${m.name || "—"} |\n| **Folder** | ${m.folder_id ? `\`${m.folder_id}\`` : "root"} |`,
+                },
+            ],
+        };
+    });
+    server.tool("list_folders", "List the media-library folders in this workspace (Finder-style organization). Returns each folder's id, name, parent, and item count. Use a folder id with list_media (folder_id) or update_media (folder_id), or a folder name with upload_media (folder).", {}, async () => {
+        const result = await getClient().listFolders();
+        if (result.error) {
+            return { content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }] };
+        }
+        const items = Array.isArray(result.data) ? result.data : result.data?.data || [];
+        if (!items.length) {
+            return { content: [{ type: "text", text: "No folders yet. Create one with create_folder." }] };
+        }
+        let md = `## Folders (${items.length})\n\n`;
+        md += `| Folder ID | Name | Parent | Items |\n|-----------|------|--------|-------|\n`;
+        for (const f of items) {
+            md += `| \`${f.id}\` | ${f.name} | ${f.parent_id ? `\`${f.parent_id}\`` : "—"} | ${f.item_count ?? 0} |\n`;
+        }
+        return { content: [{ type: "text", text: md }] };
+    });
+    server.tool("create_folder", "Create a media-library folder. Use it to organize assets (e.g. a 'win-graphics' folder), then upload into it with upload_media (folder) or move files with update_media (folder_id).", {
+        name: z.string().describe("Folder name, e.g. 'win-graphics'"),
+        parent_id: z.string().optional().describe("Optional parent folder id to nest under (from list_folders). Omit for a top-level folder."),
+    }, async ({ name, parent_id }) => {
+        const result = await getClient().createFolder({ name, parent_id });
+        if (result.error) {
+            return { content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }] };
+        }
+        const f = result.data;
         return {
-            content: [{ type: "text", text: result.error ? `Error (${result.error.code}): ${result.error.message}` : "Media deleted successfully." }],
+            content: [
+                {
+                    type: "text",
+                    text: `Created folder \`${f.id}\` "${f.name}". Upload into it with upload_media (folder="${f.name}").`,
+                },
+            ],
         };
     });
 }

package/build/tools/posts.js

@@ -180,7 +180,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
 3. **Schedule**: When should it be published? (Or save as draft?)
 4. **Media** (REQUIRED for some types):
    - Stories: ALWAYS require an image or video. Ask the user which image/video to use. Use list_media to show their uploaded media, or ask for an external URL.
-   - Reels: ALWAYS require a video. Ask the user which video to use. Use list_media to find available videos.
+   - Reels: ALWAYS require a video (MP4/MOV) — NOT an image. Passing an image to a Reel returns a 400 validation_error. To share an image, use post_type "Post" instead. Ask the user which video to use; use list_media to find available videos.
    - Instagram posts: ALWAYS require at least one image or video.
    - TikTok posts: ALWAYS require at least one image or video.
    - Pinterest posts: ALWAYS require an image AND a board_id.
@@ -228,6 +228,13 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         link_description: z.string().optional().describe("Optional description for the link-share preview. LinkedIn uses this when set; Facebook auto-fetches the OG description."),
         link_thumbnail_url: z.string().optional().describe("Optional thumbnail image URL for the preview card. Reserved for future use — currently not yet applied to LinkedIn (would require uploading to LinkedIn's image API first)."),
         location_id: z.string().optional().describe("Instagram only. Facebook Place ID of a single physical venue (with a street address) to tag the post's location. Applied to single-image and carousel Instagram feed posts. To get a valid ID, call the `search_locations` tool with the place name and let the user pick. 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. Invited users get an invite in the Instagram app; once they accept, the post also appears on their profile and feed. A leading '@' is stripped; usernames are case-insensitive. Private or non-existent usernames are rejected by Instagram at publish time with a clear error. Ignored by other platforms."),
+        user_tags: z.array(z.object({
+            username: z.string().describe("Public Instagram username to tag. Leading '@' is stripped."),
+            x: z.number().min(0).max(1).describe("Horizontal position 0.0–1.0 from the photo's left edge."),
+            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."),
         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."),
@@ -257,6 +264,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             disable_stitch: z.boolean().optional(),
             is_aigc: z.boolean().optional(),
             brand_content_toggle: z.boolean().optional(),
+            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(),
@@ -346,7 +354,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
 2. **Channels**: Which platforms? Use list_accounts if needed.
 3. **Media** (REQUIRED for some types — same rules as create_post):
    - Stories: ALWAYS need an image or video.
-   - Reels: ALWAYS need a video.
+   - Reels: ALWAYS need a video (MP4/MOV), NOT an image — passing an image returns a 400 validation_error. Use post_type "Post" to share an image.
    - Instagram/TikTok posts: ALWAYS need at least one image or video.
    - Pinterest: ALWAYS need an image + board_id.
    - Ask the user which media to use. Use list_media to show options.
@@ -367,6 +375,14 @@ Do NOT call without required media — it will fail.`, {
             z.record(z.string(), z.array(z.string())),
         ]).optional().describe("External image/video URLs — flat array or per-platform object. Max 10 total. 'default' key is fallback for platforms without their own key. Empty array opts out."),
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story', 'reel'"),
+        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."),
+        user_tags: z.array(z.object({
+            username: z.string().describe("Public Instagram username to tag. Leading '@' is stripped."),
+            x: z.number().min(0).max(1).describe("Horizontal position 0.0–1.0 from the photo's left edge."),
+            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."),
         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."),
@@ -462,6 +478,13 @@ Do NOT call without required media — it will fail.`, {
             z.record(z.string(), z.array(z.string())),
         ]).optional().describe("External URLs — flat array or per-platform object. Max 10 total. 'default' key is fallback for platforms without their own key. Empty array opts out."),
         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({
+            username: z.string().describe("Public Instagram username to tag. Leading '@' is stripped."),
+            x: z.number().min(0).max(1).describe("Horizontal position 0.0–1.0 from the photo's left edge."),
+            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). Replaces the existing tag list. Send an empty array to clear. For carousels set image_index per tag. Ignored by other platforms."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. To change the Short's title on an existing draft, set this — do NOT use `content` (which is the description)."),
             tags: z.array(z.string()).optional(),
@@ -491,6 +514,7 @@ Do NOT call without required media — it will fail.`, {
             disable_stitch: z.boolean().optional(),
             is_aigc: z.boolean().optional(),
             brand_content_toggle: z.boolean().optional(),
+            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(),

package/build/tools/workspaces.js

@@ -1,25 +1,67 @@
 import { z } from "zod";
+/** Fetch each workspace's name + id so we can match a switch request to it. */
+async function describeWorkspaces(workspaceClients, sessionState) {
+    return Promise.all(workspaceClients.map(async (wc, index) => {
+        try {
+            const result = await wc.client.listAccounts();
+            return {
+                index,
+                workspace_id: result.workspace_id != null ? String(result.workspace_id) : null,
+                workspace_name: result.workspace_name || `Workspace ${index + 1}`,
+                accounts_count: Array.isArray(result.data) ? result.data.length : 0,
+                active: index === sessionState.activeIndex,
+            };
+        }
+        catch {
+            return {
+                index,
+                workspace_id: null,
+                workspace_name: `Workspace ${index + 1}`,
+                accounts_count: 0,
+                active: index === sessionState.activeIndex,
+            };
+        }
+    }));
+}
+/**
+ * Resolve a user-supplied workspace reference (name, id, or positional number)
+ * to an index. Order of precedence puts stable identity first so ordering can
+ * never send work to the wrong workspace:
+ *   1. exact name (case-insensitive)
+ *   2. exact workspace id
+ *   3. unique partial name match (case-insensitive)
+ *   4. positional number fallback (1-based) for back-compat
+ * Returns { index } on success, { ambiguous } when a name matches several, or
+ * { notFound: true }.
+ */
+function resolveWorkspaceIndex(entries, query) {
+    const q = String(query ?? "").trim();
+    if (!q)
+        return { notFound: true };
+    const qLower = q.toLowerCase();
+    const exactName = entries.filter((e) => e.workspace_name.toLowerCase() === qLower);
+    if (exactName.length === 1)
+        return { index: exactName[0].index };
+    if (exactName.length > 1)
+        return { ambiguous: exactName };
+    const byId = entries.filter((e) => e.workspace_id === q);
+    if (byId.length === 1)
+        return { index: byId[0].index };
+    const partial = entries.filter((e) => e.workspace_name.toLowerCase().includes(qLower));
+    if (partial.length === 1)
+        return { index: partial[0].index };
+    if (partial.length > 1)
+        return { ambiguous: partial };
+    if (/^\d+$/.test(q)) {
+        const idx = parseInt(q, 10) - 1;
+        if (idx >= 0 && idx < entries.length)
+            return { index: idx };
+    }
+    return { notFound: true };
+}
 export function registerWorkspaceTools(server, workspaceClients, sessionState) {
     server.tool("list_workspaces", "List all workspaces available in this session. Each workspace corresponds to an API key provided at connection time. Shows which workspace is currently active. Workspace selection rule: if only one workspace is available, just use it (no need to ask). If the user has named a workspace in their request (e.g. 'post to my Acme workspace'), proceed with that workspace and remember it for the rest of the conversation. If multiple workspaces exist and the user has NOT named one, call this tool, present the list, and ASK the user which one to use before posting, switching, or fetching analytics. After a successful action, mention the workspace name in your reply for clarity.", {}, async () => {
-        const workspaces = await Promise.all(workspaceClients.map(async (wc, index) => {
-            try {
-                const result = await wc.client.listAccounts();
-                return {
-                    index,
-                    workspace_name: result.workspace_name || `Workspace ${index + 1}`,
-                    active: index === sessionState.activeIndex,
-                    accounts_count: (Array.isArray(result.data) ? result.data : []).length,
-                };
-            }
-            catch {
-                return {
-                    index,
-                    workspace_name: `Workspace ${index + 1}`,
-                    active: index === sessionState.activeIndex,
-                    accounts_count: 0,
-                };
-            }
-        }));
+        const workspaces = await describeWorkspaces(workspaceClients, sessionState);
         if (workspaces.length === 1) {
             const ws = workspaces[0];
             return {
@@ -30,40 +72,48 @@ export function registerWorkspaceTools(server, workspaceClients, sessionState) {
             };
         }
         let md = `## Workspaces (${workspaces.length})\n\n`;
-        md += `| # | Workspace | Accounts | Status |\n`;
-        md += `|---|-----------|----------|--------|\n`;
+        md += `| Workspace | Accounts | Status |\n`;
+        md += `|-----------|----------|--------|\n`;
         for (const ws of workspaces) {
             const status = ws.active ? "**Active**" : "";
-            md += `| ${ws.index + 1} | ${ws.workspace_name} | ${ws.accounts_count} | ${status} |\n`;
+            md += `| ${ws.workspace_name} | ${ws.accounts_count} | ${status} |\n`;
         }
-        md += `\nUse **switch_workspace** with the workspace number to change the active workspace.`;
+        md += `\nUse **switch_workspace** with the workspace **name** to change the active workspace (e.g. \`switch_workspace workspace: "${workspaces[0].workspace_name}"\`).`;
         return { content: [{ type: "text", text: md }] };
     });
-    server.tool("switch_workspace", "Switch the active workspace. All subsequent tool calls (posts, media, analytics, etc.) will operate on the selected workspace. Only call this when the user has explicitly named the target workspace, or after the user has picked one from list_workspaces. Never call switch_workspace silently when the user hasn't specified a workspace — ask first.", {
-        workspace_number: z.string().describe("The workspace number from list_workspaces (1, 2, 3, etc.)"),
-    }, async ({ workspace_number }) => {
-        const index = parseInt(workspace_number, 10) - 1;
-        if (isNaN(index) || index < 0 || index >= workspaceClients.length) {
+    server.tool("switch_workspace", "Switch the active workspace by NAME. All subsequent tool calls (posts, media, analytics, etc.) will operate on the selected workspace. Pass the workspace name exactly as shown in list_workspaces (its id or list position also work, but the name is preferred and unambiguous). Only call this when the user has explicitly named the target workspace, or after the user has picked one from list_workspaces. Never call switch_workspace silently when the user hasn't specified a workspace - ask first.", {
+        workspace: z
+            .string()
+            .describe('The workspace to switch to: its name (preferred, e.g. "Daily Edge Sports"), or its id/list number.'),
+    }, async ({ workspace }) => {
+        const entries = await describeWorkspaces(workspaceClients, sessionState);
+        const resolved = resolveWorkspaceIndex(entries, workspace);
+        if ("ambiguous" in resolved) {
+            const names = resolved.ambiguous
+                .map((e) => `- ${e.workspace_name}${e.workspace_id ? ` (id ${e.workspace_id})` : ""}`)
+                .join("\n");
             return {
                 content: [{
                         type: "text",
-                        text: `Error: Invalid workspace number. Use list_workspaces to see available options (1-${workspaceClients.length}).`,
+                        text: `"${workspace}" matches more than one workspace:\n\n${names}\n\nPlease specify the exact name or id.`,
                     }],
             };
         }
-        sessionState.activeIndex = index;
-        const wc = workspaceClients[index];
-        let workspaceName = `Workspace ${index + 1}`;
-        try {
-            const result = await wc.client.listAccounts();
-            if (result.workspace_name)
-                workspaceName = result.workspace_name;
+        if ("notFound" in resolved) {
+            const avail = entries.map((e) => e.workspace_name).join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error: No workspace matches "${workspace}". Available workspaces: ${avail}. Use list_workspaces to see them.`,
+                    }],
+            };
         }
-        catch { }
+        sessionState.activeIndex = resolved.index;
+        const ws = entries[resolved.index];
         return {
             content: [{
                     type: "text",
-                    text: `Switched to **${workspaceName}**. All subsequent calls will use this workspace.`,
+                    text: `Switched to **${ws.workspace_name}**. All subsequent calls will use this workspace.`,
                 }],
         };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnisocials/mcp-server",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "MCP server for OmniSocials API - manage social media posts, media, accounts, analytics, and webhooks",
   "type": "module",
   "main": "build/index.js",
@@ -36,5 +36,10 @@
   "devDependencies": {
     "@types/node": "^25.3.3",
     "typescript": "^5.8.2"
+  },
+  "overrides": {
+    "zod": "4.4.0",
+    "fast-uri": "3.1.1",
+    "hono": "4.12.18"
   }
 }