@omnisocials/mcp-server 1.3.8 → 1.4.0

package/README.md

@@ -126,6 +126,7 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | `update_post` | Update a draft or scheduled post |
 | `delete_post` | Delete a post |
 | `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)
 

package/build/client.d.ts

@@ -49,11 +49,17 @@ export declare class OmniSocialsClient {
         media_urls?: string[] | Record<string, string[]>;
         type?: string;
         source?: string;
+        link_url?: string;
+        link_title?: string;
+        link_description?: string;
+        link_thumbnail_url?: string;
+        location_id?: string;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
         tiktok?: Record<string, unknown>;
         x?: XPostOptions;
+        google_business?: Record<string, unknown>;
     }): Promise<ApiResponse<unknown>>;
     createAndPublishPost(data: {
         content: string | Record<string, string>;
@@ -62,11 +68,17 @@ export declare class OmniSocialsClient {
         media_urls?: string[] | Record<string, string[]>;
         type?: string;
         source?: string;
+        link_url?: string;
+        link_title?: string;
+        link_description?: string;
+        link_thumbnail_url?: string;
+        location_id?: string;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
         tiktok?: Record<string, unknown>;
         x?: XPostOptions;
+        google_business?: Record<string, unknown>;
     }): Promise<ApiResponse<unknown>>;
     updatePost(id: string, data: {
         content?: string | Record<string, string>;
@@ -75,14 +87,18 @@ export declare class OmniSocialsClient {
         media_ids?: string[] | Record<string, string[]>;
         media_urls?: string[] | Record<string, string[]>;
         type?: string;
+        location_id?: string;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
         tiktok?: Record<string, unknown>;
         x?: XPostOptionsUpdate;
+        google_business?: Record<string, unknown>;
     }): Promise<ApiResponse<unknown>>;
     deletePost(id: string): Promise<ApiResponse<unknown>>;
     publishPost(id: string): Promise<ApiResponse<unknown>>;
+    searchLocations(query: string): Promise<ApiResponse<unknown>>;
+    validateLocation(id: string): Promise<ApiResponse<unknown>>;
     listMedia(params?: {
         limit?: string;
         offset?: string;

package/build/client.js

@@ -150,6 +150,13 @@ export class OmniSocialsClient {
     async publishPost(id) {
         return this.request("POST", `/posts/${id}/publish`);
     }
+    // Locations (Instagram place tagging)
+    async searchLocations(query) {
+        return this.request("GET", "/locations/search", undefined, { q: query });
+    }
+    async validateLocation(id) {
+        return this.request("GET", "/locations/validate", undefined, { id });
+    }
     // Media
     async listMedia(params) {
         return this.request("GET", "/media", undefined, params);

package/build/tools/accounts.js

@@ -5,7 +5,7 @@ export function registerAccountTools(server, getClient) {
         const result = await getClient().listAccounts();
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const accounts = Array.isArray(result.data) ? result.data : result.data?.accounts || [];
@@ -23,8 +23,9 @@ export function registerAccountTools(server, getClient) {
             const name = a.username ? `@${a.username}` : a.display_name || "—";
             const types = (a.content_types || []).join(", ");
             const platform = capitalize(a.platform);
-            const sub = a.platform_details?.subscription_type && a.platform_details.subscription_type !== "None"
-                ? ` (${a.platform_details.subscription_type})`
+            const subType = a.platform_details?.subscription_type;
+            const sub = subType === "Premium" || subType === "PremiumPlus"
+                ? ` (${subType})`
                 : "";
             const statusCell = a.needs_reconnect
                 ? `⚠️ needs_reconnect`
@@ -66,7 +67,7 @@ export function registerAccountTools(server, getClient) {
         const result = await getClient().getAccount(id);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const a = result.data;
@@ -88,8 +89,9 @@ export function registerAccountTools(server, getClient) {
             md += `| **Reconnect reason** | ${a.reauth_reason} |\n`;
         }
         md += `| **Connected** | ${a.connected_at ? new Date(a.connected_at).toLocaleDateString() : "—"} |\n`;
-        if (a.platform_details?.subscription_type) {
-            md += `| **Subscription** | ${a.platform_details.subscription_type} |\n`;
+        const getSubType = a.platform_details?.subscription_type;
+        if (getSubType === "Premium" || getSubType === "PremiumPlus") {
+            md += `| **Subscription** | ${getSubType} |\n`;
         }
         if (a.boards?.length) {
             md += `\n### Pinterest Boards\n\n`;

package/build/tools/analytics.js

@@ -7,7 +7,7 @@ export function registerAnalyticsTools(server, getClient) {
         const result = await getClient().getPostAnalytics(post_id);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const d = result.data;
@@ -73,7 +73,7 @@ export function registerAnalyticsTools(server, getClient) {
         const result = await getClient().getAnalyticsOverview(params);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const d = result.data;
@@ -118,7 +118,7 @@ export function registerAnalyticsTools(server, getClient) {
         const result = await getClient().getAccountAnalytics(params);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const accounts = result.data || [];

package/build/tools/media.js

@@ -8,7 +8,7 @@ export function registerMediaTools(server, getClient) {
         const result = await getClient().listMedia(params);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const items = Array.isArray(result.data) ? result.data : result.data?.media || [];
@@ -75,7 +75,7 @@ When the user provides an image in the conversation (not a URL), use base64_data
         }
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const m = result.data;
@@ -96,7 +96,7 @@ When the user provides an image in the conversation (not a URL), use base64_data
     }, async ({ id }) => {
         const result = await getClient().deleteMedia(id);
         return {
-            content: [{ type: "text", text: result.error ? `Error: ${result.error.message}` : "Media deleted successfully." }],
+            content: [{ type: "text", text: result.error ? `Error (${result.error.code}): ${result.error.message}` : "Media deleted successfully." }],
         };
     });
 }

package/build/tools/posts.js

@@ -61,7 +61,7 @@ export function registerPostTools(server, getClient) {
         const result = await getClient().listPosts(params);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const posts = Array.isArray(result.data) ? result.data : result.data?.posts || [];
@@ -106,7 +106,7 @@ export function registerPostTools(server, getClient) {
         const result = await getClient().getPost(id);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const p = result.data;
@@ -185,6 +185,19 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - TikTok posts: ALWAYS require at least one image or video.
    - Pinterest posts: ALWAYS require an image AND a board_id.
    - Other platforms (LinkedIn, LinkedIn Page, X, Bluesky, etc.): Media is optional.
+
+   **Per-platform max media items (enforced at submit, returns 400 validation_error if exceeded):**
+   - Bluesky, X, Mastodon — max **4** items per post
+   - Instagram, Threads — max **10** items per carousel
+   - TikTok — max **35** photos per photo-post; cannot mix photos and videos in one post
+   - Pinterest carousel — 2–5 images, all same aspect ratio
+
+   **Per-platform video caps (duration + size, checked via ffprobe at submit — exceeding either returns a 400 validation_error stating the exact cap and the file's value, e.g. "X only allows videos up to 2min 20s — yours is 2min 35s. Trim the video or deselect X."):**
+   - X — **140s (2min 20s)** · **512MB** (X also can't mix a video with images in one tweet: a tweet is either 1 video OR up to 4 images)
+   - Bluesky 180s · Threads 5min · Instagram 15min · TikTok 10min · YouTube Short 3min · LinkedIn 10min · Pinterest 15min · Facebook Reel 90s
+   Pick a file within the cap up front; if the user's video is over, tell them the limit so they can trim it rather than retrying blindly.
+
+   When attaching more than these caps to a selected platform, EITHER trim the array OR move to a flat \`media_urls: [...]\` and let the user know which platform will be over the limit so they can split into multiple posts.
 5. **Platform-specific options** (ask only when relevant):
    - **Pinterest board (auto-default to first board)**: If Pinterest is in \`channels\` and \`pinterest.board_id\` is NOT provided, do NOT block on asking the user — and do NOT skip Pinterest. Instead:
      1. Call \`get_account\` on the Pinterest account ID — the response includes a \`Pinterest Boards\` table with each board's name and ID.
@@ -199,7 +212,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
 
 **When the user shares an image in chat but you cannot upload it** (e.g. no public URL available): save the post as a draft with the caption, then tell the user: "I saved your post as a draft in OmniSocials. Open it there to add your image and schedule it when ready." Include a link to https://app.omnisocials.com. Do NOT tell the user it's impossible — always save the draft so their caption isn't lost.`, {
         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. Note: `linkedin` (personal profile) and `linkedin_page` (company page) are independent channels. A workspace can have both connected and post to each separately."),
+        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()),
@@ -210,13 +223,18 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             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. When using per-platform format, 'default' is the fallback for selected platforms without their own key. Pass an empty array (e.g. facebook: []) to opt a platform out of media."),
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story' (Instagram/Facebook/Snapchat), 'reel' (Instagram/Facebook/YouTube/TikTok)"),
+        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."),
+        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."),
         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)"),
+            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."),
             link: z.string().optional().describe("Destination URL the pin clicks through to"),
             video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
             alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options"),
+        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. Falls back to \"YouTube Short\" when omitted."),
             tags: z.array(z.string()).optional(),
@@ -249,11 +267,32 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
                 media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media URLs (max 4)"),
             })).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. Per-part media_urls override top-level media for that specific tweet. For a single tweet, omit thread_parts and use content."),
         }).optional().describe("X (Twitter) options"),
+        google_business: z.object({
+            topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional().describe("Local post type. Defaults to STANDARD. ALERT is reserved by Google and not exposed."),
+            cta: z.object({
+                actionType: z.enum(["LEARN_MORE", "BOOK", "ORDER", "SHOP", "SIGN_UP", "CALL"]).describe("Button rendered under the caption. Phone numbers belong on a CALL button and links on a LEARN_MORE / BOOK / SHOP button — they're rejected if placed in the caption text."),
+                url: z.string().optional().describe("Required for every actionType except CALL. Must be http:// or https://. CALL uses the location's phone number from the business profile."),
+            }).optional().describe("Optional call-to-action button."),
+            event: z.object({
+                title: z.string().max(58).describe("Event title (max 58 chars)."),
+                schedule: z.object({
+                    startDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+                    startTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+                    endDate: z.object({ year: z.number(), month: z.number(), day: z.number() }).optional(),
+                    endTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+                }).optional().describe("Google's split date+time shape. startDate required; end (if present) must be ≥ start."),
+            }).optional().describe("Required when topic_type is EVENT."),
+            offer: z.object({
+                couponCode: z.string().max(58).optional(),
+                redeemOnlineUrl: z.string().optional().describe("Must be https://. http URLs are rejected."),
+                termsConditions: z.string().max(4000).optional(),
+            }).optional().describe("Required when topic_type is OFFER. Must include at least one of couponCode or redeemOnlineUrl."),
+        }).optional().describe("Google Business Profile options. Use to publish EVENT or OFFER posts, attach a CTA button, or both. Shape mirrors Google's LocalPost resource (see https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts#LocalPost).\n\nGoogle Business caption rules (enforced at scheduling — text that violates these will return a `validation_error` 400 before the post is saved):\n  • Phone numbers in the caption are rejected — use a CALL button instead.\n  • Inline URLs / bare domains / emails are rejected — use LEARN_MORE / BOOK / SHOP / SIGN_UP / ORDER buttons instead.\n  • Caption max 1500 characters.\n  • Media is optional (text-only posts are allowed). If attached: exactly one JPEG/PNG/WebP image (no video, no carousels).\n  • The workspace must have a Google Business location selected (Settings → Organisation → Workspaces → Google Business) before scheduling — otherwise returns a 400."),
     }, async (params) => {
         const result = await getClient().createPost({ ...params, source: "mcp" });
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const p = result.data;
@@ -310,12 +349,14 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - 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.
+   - **Max items per platform** (same caps as create_post — exceeding returns 400): Bluesky/X/Mastodon ≤4, Instagram/Threads ≤10, TikTok ≤35 photos with no photo/video mix, Pinterest carousel 2–5 same-ratio images.
+   - **Video duration/size caps** (ffprobe at submit — over either returns 400 validation_error with the exact cap + the file's value): X **140s/512MB** (no video+image mix in one tweet), Bluesky 180s, Threads 5min, Instagram 15min, TikTok 10min, YouTube Short 3min, LinkedIn 10min, Facebook Reel 90s.
 4. **Pinterest board (auto-default to first board)**: If Pinterest is in \`channels\` and \`pinterest.board_id\` is NOT provided, do NOT block on asking — and do NOT skip Pinterest. Call \`get_account\` on the Pinterest account, take the FIRST board from the returned boards list, and pass its \`id\` as \`pinterest.board_id\`. In your reply, mention which board you used (e.g. "Published to your 'Marketing' board on Pinterest — let me know if you'd prefer a different one.") so the user can redirect. If the user named a specific board in the request, match it (case-insensitive) against the list and use that one instead.
 5. **X threads**: When the user asks for an X/Twitter "thread" (or anything > 280 chars on X), pass \`x.thread_parts\` as a 2–25 entry array of \`{ text }\` objects. Do NOT split into "1/", "2/" inside \`content\` — that produces a single tweet, not a thread.
 
 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. Note: `linkedin` (personal profile) and `linkedin_page` (company page) are independent channels. A workspace can have both connected and post to each separately."),
+        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())),
@@ -327,11 +368,11 @@ Do NOT call without required media — it will fail.`, {
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story', 'reel'"),
         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)"),
+            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."),
             link: z.string().optional().describe("Destination URL the pin clicks through to"),
             video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
             alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options"),
+        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube."),
             tags: z.array(z.string()).optional(),
@@ -349,11 +390,32 @@ Do NOT call without required media — it will fail.`, {
                 media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media URLs (max 4)"),
             })).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. Per-part media_urls override top-level media."),
         }).optional().describe("X (Twitter) options"),
+        google_business: z.object({
+            topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional(),
+            cta: z.object({
+                actionType: z.enum(["LEARN_MORE", "BOOK", "ORDER", "SHOP", "SIGN_UP", "CALL"]),
+                url: z.string().optional(),
+            }).optional(),
+            event: z.object({
+                title: z.string().max(58),
+                schedule: z.object({
+                    startDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+                    startTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+                    endDate: z.object({ year: z.number(), month: z.number(), day: z.number() }).optional(),
+                    endTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+                }).optional(),
+            }).optional(),
+            offer: z.object({
+                couponCode: z.string().max(58).optional(),
+                redeemOnlineUrl: z.string().optional(),
+                termsConditions: z.string().max(4000).optional(),
+            }).optional(),
+        }).optional().describe("Google Business Profile options (STANDARD/EVENT/OFFER + optional CTA). Same shape as create_post.\n\nGoogle Business caption rules (enforced at scheduling — text that violates these returns a `validation_error` 400):\n  • No phone numbers in the caption — use a CALL button instead.\n  • No inline URLs / bare domains / emails — use LEARN_MORE / BOOK / SHOP / SIGN_UP / ORDER buttons.\n  • Caption max 1500 characters.\n  • Media is optional. If attached: exactly one JPEG/PNG/WebP image (no video, no carousels).\n  • Workspace must have a Google Business location selected before scheduling — otherwise returns a 400."),
     }, async (params) => {
         const result = await getClient().createAndPublishPost({ ...params, source: "mcp" });
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const p = result.data;
@@ -388,7 +450,7 @@ Do NOT call without required media — it will fail.`, {
         id: z.string().describe("The post ID to update"),
         content: z.union([z.string(), z.record(z.string(), z.string())]).optional().describe("Updated post caption / body text. For YouTube Shorts this becomes the video description, NOT the title — to rename the Short, use `youtube.title`. String or object with platform keys: { \"default\": \"fallback\", \"linkedin\": \"long\" }."),
         scheduled_at: z.string().optional().describe("Updated scheduled date (ISO 8601)"),
-        channels: z.array(z.string()).optional().describe("Updated channel IDs. Note: `linkedin` (personal profile) and `linkedin_page` (company page) are independent channels."),
+        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())),
@@ -397,6 +459,7 @@ Do NOT call without required media — it will fail.`, {
             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. '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."),
         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(),
@@ -408,11 +471,11 @@ Do NOT call without required media — it will fail.`, {
         }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
         pinterest: z.object({
             board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
-            title: z.string().optional().describe("Pin title (max 100 characters)"),
+            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."),
             link: z.string().optional().describe("Destination URL the pin clicks through to"),
             video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
             alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options"),
+        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
         instagram: z.object({
             share_to_feed: z.boolean().optional(),
             thumbnail_type: z.enum(["from-video", "from-library"]).optional(),
@@ -436,11 +499,32 @@ Do NOT call without required media — it will fail.`, {
                 media_urls: z.array(z.string()).max(4).optional().describe("Per-tweet media URLs (max 4)"),
             })).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, or `null` to revert to single-tweet mode."),
         }).optional().describe("X (Twitter) options"),
+        google_business: z.object({
+            topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional(),
+            cta: z.object({
+                actionType: z.enum(["LEARN_MORE", "BOOK", "ORDER", "SHOP", "SIGN_UP", "CALL"]),
+                url: z.string().optional(),
+            }).optional(),
+            event: z.object({
+                title: z.string().max(58),
+                schedule: z.object({
+                    startDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+                    startTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+                    endDate: z.object({ year: z.number(), month: z.number(), day: z.number() }).optional(),
+                    endTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+                }).optional(),
+            }).optional(),
+            offer: z.object({
+                couponCode: z.string().max(58).optional(),
+                redeemOnlineUrl: z.string().optional(),
+                termsConditions: z.string().max(4000).optional(),
+            }).optional(),
+        }).optional().describe("Google Business Profile options (STANDARD/EVENT/OFFER + optional CTA). Same shape as create_post.\n\nGoogle Business caption rules (enforced at scheduling — text that violates these returns a `validation_error` 400):\n  • No phone numbers in the caption — use a CALL button instead.\n  • No inline URLs / bare domains / emails — use LEARN_MORE / BOOK / SHOP / SIGN_UP / ORDER buttons.\n  • Caption max 1500 characters.\n  • Media is optional. If attached: exactly one JPEG/PNG/WebP image (no video, no carousels).\n  • Workspace must have a Google Business location selected before scheduling — otherwise returns a 400."),
     }, async ({ id, ...data }) => {
         const result = await getClient().updatePost(id, data);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const p = result.data;
@@ -464,7 +548,7 @@ Do NOT call without required media — it will fail.`, {
     }, async ({ id }) => {
         const result = await getClient().deletePost(id);
         return {
-            content: [{ type: "text", text: result.error ? `Error: ${result.error.message}` : "Post deleted successfully." }],
+            content: [{ type: "text", text: result.error ? `Error (${result.error.code}): ${result.error.message}` : "Post deleted successfully." }],
         };
     });
     server.tool("publish_post", `Publish a draft or scheduled post immediately. The post will be queued for publishing.
@@ -475,7 +559,7 @@ IMPORTANT: Before publishing, verify the post has all required media. If publish
         const result = await getClient().publishPost(id);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const p = result.data;
@@ -488,4 +572,30 @@ IMPORTANT: Before publishing, verify the post has all required media. If publish
             content: [{ type: "text", text: md }],
         };
     });
+    server.tool("search_locations", `Search for an Instagram location to tag on a post. Use this whenever the user wants to post WITH a place/location (e.g. "post this at my dealership", "tag the café"). It returns matching real venues with their addresses and a location ID.
+
+Flow: call this with the place name → present the options to the user → once they pick, pass that result's \`id\` as \`location_id\` on create_post / create_and_publish_post / update_post. Only Instagram supports location tagging.
+
+Notes:
+- Use a SPECIFIC venue name. Searching a broad brand ("Starbucks") returns individual store locations, not the brand page.
+- If the user already gives you a numeric Facebook Place ID, you can pass it straight to create_post as \`location_id\`; it's validated at publish time and an invalid one returns a clear error.
+- If results come back empty with a permission note, the workspace's Facebook app can't search arbitrary places — tell the user to use their own business Page's ID.`, {
+        query: z
+            .string()
+            .describe("Place name to search (min 2 chars) — a dealership, café, venue, etc."),
+    }, async ({ query }) => {
+        const result = await getClient().searchLocations(query);
+        const places = result?.data || [];
+        if (!places.length) {
+            const why = result?.error ||
+                `No taggable locations found for "${query}". Try a more specific venue name, or pass a known Facebook Place ID directly as location_id.`;
+            return { content: [{ type: "text", text: why }] };
+        }
+        let md = `## Locations matching "${query}"\n\nAsk the user which one, then use its ID as \`location_id\`:\n\n`;
+        md += `| # | Name | Address | location_id |\n|---|------|---------|-------------|\n`;
+        places.forEach((p, i) => {
+            md += `| ${i + 1} | ${p.name} | ${p.address || "—"} | \`${p.id}\` |\n`;
+        });
+        return { content: [{ type: "text", text: md }] };
+    });
 }

package/build/tools/webhooks.js

@@ -5,7 +5,7 @@ export function registerWebhookTools(server, getClient) {
         const result = await getClient().listWebhooks();
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const webhooks = Array.isArray(result.data) ? result.data : result.data?.webhooks || [];
@@ -35,7 +35,7 @@ export function registerWebhookTools(server, getClient) {
         const result = await getClient().createWebhook(params);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const w = result.data;
@@ -60,7 +60,7 @@ export function registerWebhookTools(server, getClient) {
         const result = await getClient().getWebhook(id);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const w = result.data;
@@ -87,7 +87,7 @@ export function registerWebhookTools(server, getClient) {
         const result = await getClient().updateWebhook(id, data);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const w = result.data;
@@ -107,7 +107,7 @@ export function registerWebhookTools(server, getClient) {
     }, async ({ id }) => {
         const result = await getClient().deleteWebhook(id);
         return {
-            content: [{ type: "text", text: result.error ? `Error: ${result.error.message}` : "Webhook deleted successfully." }],
+            content: [{ type: "text", text: result.error ? `Error (${result.error.code}): ${result.error.message}` : "Webhook deleted successfully." }],
         };
     });
     server.tool("rotate_webhook_secret", "Rotate the signing secret for a webhook. The new secret will only be shown once.", {
@@ -116,7 +116,7 @@ export function registerWebhookTools(server, getClient) {
         const result = await getClient().rotateWebhookSecret(id);
         if (result.error) {
             return {
-                content: [{ type: "text", text: `Error: ${result.error.message}` }],
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
         const w = result.data;

package/build/types.d.ts

@@ -14,6 +14,14 @@ export interface Post {
     channels: string[];
     media: string[];
     created_at: string;
+    /**
+     * Per-platform user-friendly error messages, keyed by platform identifier
+     * (facebook, instagram, linkedin, linkedin_page, youtube, tiktok, pinterest,
+     * x, threads, bluesky, mastodon, google_business). Populated when `status`
+     * is `failed` or `warning`. Only failed platforms appear. `null` while the
+     * post is still draft/scheduled/processing or every platform succeeded.
+     */
+    errors?: Record<string, string> | null;
     x?: {
         reply_settings?: string;
         paid_partnership?: boolean;

package/package.json

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