@omnisocials/mcp-server 1.20.0 → 1.20.1

package/build/client.d.ts

@@ -1,4 +1,4 @@
-import type { ApiResponse, MediaItem, PdfUploadResult, InboxConversation, InboxMessage } from "./types.js";
+import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, AudioSearchResult, BestTimesResult, HashtagSet, LocationSearchResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, InboxConversation, InboxMessage, Webhook } from "./types.js";
 export declare function fetchImageAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
@@ -100,6 +100,45 @@ export interface MastodonPostOptions {
 export interface MastodonPostOptionsUpdate {
     thread_parts?: MastodonThreadPartInput[] | null;
 }
+/**
+ * Request body for POST /posts/create. `createAndPublishPost` accepts the
+ * same shape minus `scheduled_at` (publishing is immediate).
+ */
+export interface CreatePostInput {
+    content: string | Record<string, string>;
+    channels?: string[];
+    scheduled_at?: string;
+    media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
+    media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
+    type?: string;
+    source?: string;
+    link_url?: string;
+    link_title?: string;
+    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>;
+    facebook?: Record<string, unknown>;
+    linkedin?: Record<string, unknown>;
+    linkedin_page?: Record<string, unknown>;
+    tiktok?: Record<string, unknown>;
+    x?: XPostOptions;
+    bluesky?: BlueskyPostOptions;
+    mastodon?: MastodonPostOptions;
+    google_business?: Record<string, unknown>;
+    hashtag_set?: string;
+    hashtag_placement?: "caption_append" | "first_comment";
+    hashtag_platforms?: string[];
+}
 export declare class OmniSocialsClient {
     private baseUrl;
     private apiKey;
@@ -109,81 +148,20 @@ export declare class OmniSocialsClient {
         status?: string;
         limit?: string;
         offset?: string;
-    }): Promise<ApiResponse<unknown>>;
-    getPost(id: string): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<ApiPost[]>>;
+    getPost(id: string): Promise<ApiResponse<ApiPost>>;
     getRecentPlatformPosts(params?: {
         limit?: string;
         platforms?: string;
-    }): Promise<ApiResponse<unknown>>;
-    createPost(data: {
-        content: string | Record<string, string>;
-        channels?: string[];
-        scheduled_at?: string;
-        media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
-        media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
-        type?: string;
-        source?: string;
-        link_url?: string;
-        link_title?: string;
-        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>;
-        facebook?: Record<string, unknown>;
-        linkedin?: Record<string, unknown>;
-        linkedin_page?: Record<string, unknown>;
-        tiktok?: Record<string, unknown>;
-        x?: XPostOptions;
-        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?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
-        media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
-        type?: string;
-        source?: string;
-        link_url?: string;
-        link_title?: string;
-        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>;
-        facebook?: Record<string, unknown>;
-        linkedin?: Record<string, unknown>;
-        linkedin_page?: Record<string, unknown>;
-        tiktok?: Record<string, unknown>;
-        x?: XPostOptions;
-        bluesky?: BlueskyPostOptions;
-        mastodon?: MastodonPostOptions;
-        google_business?: Record<string, unknown>;
-        hashtag_set?: string;
-        hashtag_placement?: "caption_append" | "first_comment";
-        hashtag_platforms?: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<RecentPlatformPost[]> & {
+        count?: number;
+        connected_platforms?: string[];
+        errors?: Record<string, string>;
+        note?: string;
+        current_date?: string;
+    }>;
+    createPost(data: CreatePostInput): Promise<ApiResponse<ApiPost>>;
+    createAndPublishPost(data: Omit<CreatePostInput, "scheduled_at">): Promise<ApiResponse<ApiPost>>;
     updatePost(id: string, data: {
         content?: string | Record<string, string>;
         scheduled_at?: string;
@@ -210,26 +188,26 @@ export declare class OmniSocialsClient {
         bluesky?: BlueskyPostOptionsUpdate;
         mastodon?: MastodonPostOptionsUpdate;
         google_business?: Record<string, unknown>;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<ApiPost>>;
     deletePost(id: string): Promise<ApiResponse<unknown>>;
-    publishPost(id: string): Promise<ApiResponse<unknown>>;
-    retryPost(id: string): Promise<ApiResponse<unknown>>;
-    searchLocations(query: string): Promise<ApiResponse<unknown>>;
+    publishPost(id: string): Promise<ApiResponse<PublishPostResult>>;
+    retryPost(id: string): Promise<ApiResponse<RetryPostResult>>;
+    searchLocations(query: string): Promise<LocationSearchResult>;
     validateLocation(id: string): Promise<ApiResponse<unknown>>;
-    searchInstagramAudio(query?: string, type?: "music" | "original_sound"): Promise<ApiResponse<unknown>>;
+    searchInstagramAudio(query?: string, type?: "music" | "original_sound"): Promise<AudioSearchResult>;
     listMedia(params?: {
         limit?: string;
         offset?: string;
         search?: string;
         folder_id?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaItem[]>>;
     uploadMedia(data: {
         url: string;
         filename?: string;
         name?: string;
         folder?: string;
     }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
-        compatibility?: unknown;
+        compatibility?: MediaCompatibility;
         message?: string;
     }>;
     uploadMediaFromBase64(data: {
@@ -239,7 +217,7 @@ export declare class OmniSocialsClient {
         name?: string;
         folder?: string;
     }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
-        compatibility?: unknown;
+        compatibility?: MediaCompatibility;
         message?: string;
     }>;
     /**
@@ -252,57 +230,73 @@ export declare class OmniSocialsClient {
         media_id?: string;
         size_bytes?: number;
         mime?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<MediaCheckResult>;
     deleteMedia(id: string): Promise<ApiResponse<unknown>>;
     updateMedia(id: string, data: {
         name?: string;
         folder_id?: string | null;
-    }): Promise<ApiResponse<unknown>>;
-    listFolders(): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaItem>>;
+    listFolders(): Promise<ApiResponse<MediaFolder[]>>;
     createFolder(data: {
         name: string;
         parent_id?: string;
-    }): Promise<ApiResponse<unknown>>;
-    listHashtagSets(): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<MediaFolder>>;
+    listHashtagSets(): Promise<ApiResponse<HashtagSet[]>>;
     createHashtagSet(data: {
         name: string;
         hashtags: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<HashtagSet>>;
     updateHashtagSet(id: string, data: {
         name?: string;
         hashtags?: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<HashtagSet>>;
     deleteHashtagSet(id: string): Promise<ApiResponse<unknown>>;
-    listAccounts(): Promise<ApiResponse<unknown>>;
-    getAccount(id: string): Promise<ApiResponse<unknown>>;
-    getPostAnalytics(postId: string): Promise<ApiResponse<unknown>>;
-    getPostsAnalytics(postIds: string[]): Promise<ApiResponse<unknown>>;
+    listAccounts(): Promise<ApiResponse<Account[]> & {
+        workspace_id?: number | string | null;
+        workspace_name?: string | null;
+        workspace_icon?: string | null;
+    }>;
+    getAccount(id: string): Promise<ApiResponse<Account>>;
+    getPostAnalytics(postId: string): Promise<ApiResponse<PostAnalytics>>;
+    getPostsAnalytics(postIds: string[]): Promise<ApiResponse<PostAnalytics[]>>;
     getAnalyticsOverview(params?: {
         period?: string;
         start_date?: string;
         end_date?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<AnalyticsOverview> & {
+        period?: string;
+        start_date?: string;
+        end_date?: string;
+        current_date?: string;
+    }>;
     getAccountAnalytics(params?: {
         platform?: string;
         date?: string;
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<AccountAnalyticsEntry[]> & {
+        date?: string;
+    }>;
     getBestTimes(params: {
         platform: string;
         timezone?: string;
-    }): Promise<ApiResponse<unknown>>;
-    listWebhooks(): Promise<ApiResponse<unknown>>;
+    }): Promise<BestTimesResult>;
+    listWebhooks(): Promise<ApiResponse<Webhook[]>>;
     createWebhook(data: {
         url: string;
         events: string[];
-    }): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<Webhook & {
+        secret: string;
+    }>>;
     deleteWebhook(id: string): Promise<ApiResponse<unknown>>;
-    getWebhook(id: string): Promise<ApiResponse<unknown>>;
+    getWebhook(id: string): Promise<ApiResponse<Webhook>>;
     updateWebhook(id: string, data: {
         url?: string;
         events?: string[];
         is_active?: boolean;
-    }): Promise<ApiResponse<unknown>>;
-    rotateWebhookSecret(id: string): Promise<ApiResponse<unknown>>;
+    }): Promise<ApiResponse<Webhook>>;
+    rotateWebhookSecret(id: string): Promise<ApiResponse<{
+        id: string;
+        secret: string;
+    }>>;
     listInboxConversations(params?: {
         platform?: string;
         type?: string;

package/build/client.js

@@ -201,6 +201,8 @@ export class OmniSocialsClient {
     // Recent posts fetched live from the connected platform APIs (including
     // content published outside OmniSocials). The fallback for brand-new
     // workspaces where listPosts is empty. Requires the analytics:read scope.
+    // `connected_platforms`/`errors`/`note`/`current_date` ride top-level on the
+    // envelope (backend/routes/api/v1/posts.js recent-platform route).
     async getRecentPlatformPosts(params) {
         return this.request("GET", "/posts/recent-platform", undefined, params);
     }
@@ -224,14 +226,17 @@ export class OmniSocialsClient {
     async retryPost(id) {
         return this.request("POST", `/posts/${id}/retry`);
     }
-    // Locations (Instagram place tagging)
+    // Locations (Instagram place tagging). NOT the standard envelope — see
+    // LocationSearchResult (degraded-path `error` is a plain string).
     async searchLocations(query) {
-        return this.request("GET", "/locations/search", undefined, { q: query });
+        return this.request("GET", "/locations/search", undefined, {
+            q: query,
+        });
     }
     async validateLocation(id) {
         return this.request("GET", "/locations/validate", undefined, { id });
     }
-    // Audio (Instagram Reel music)
+    // Audio (Instagram Reel music). Same nonstandard string-`error` envelope.
     async searchInstagramAudio(query, type) {
         const params = {};
         if (query)
@@ -262,6 +267,7 @@ export class OmniSocialsClient {
      * or `size_bytes` + `mime`.
      */
     async checkMediaCompatibility(data) {
+        // Nonstandard envelope: compatibility fields ride top-level, no `data`.
         return this.request("POST", "/media/check", data);
     }
     async deleteMedia(id) {
@@ -290,7 +296,9 @@ export class OmniSocialsClient {
     async deleteHashtagSet(id) {
         return this.request("DELETE", `/hashtag-sets/${id}`);
     }
-    // Accounts
+    // Accounts. Alongside `data`, the list response carries the workspace's
+    // identity top-level (backend/routes/api/v1/accounts.js) — the workspaces
+    // tool reads it to label multi-workspace setups.
     async listAccounts() {
         return this.request("GET", "/accounts");
     }
@@ -308,12 +316,18 @@ export class OmniSocialsClient {
             ids: postIds.join(","),
         });
     }
+    // The resolved range and today's date ride top-level on the envelope
+    // (backend/routes/api/v1/analytics.js overview route) so clients can render
+    // an accurate "as of <today>" line.
     async getAnalyticsOverview(params) {
         return this.request("GET", "/analytics/overview", undefined, params);
     }
+    // The resolved `date` rides top-level on the envelope.
     async getAccountAnalytics(params) {
         return this.request("GET", "/analytics/accounts", undefined, params);
     }
+    // Nonstandard envelope: the result object is returned top-level, no `data`
+    // (backend/routes/api/v1/analytics.js best-times route).
     async getBestTimes(params) {
         return this.request("GET", "/analytics/best-times", undefined, params);
     }
@@ -321,6 +335,7 @@ export class OmniSocialsClient {
     async listWebhooks() {
         return this.request("GET", "/webhooks");
     }
+    // The signing secret is only ever returned at creation time.
     async createWebhook(data) {
         return this.request("POST", "/webhooks", data);
     }
@@ -333,6 +348,8 @@ export class OmniSocialsClient {
     async updateWebhook(id, data) {
         return this.request("PATCH", `/webhooks/${id}`, data);
     }
+    // Returns only { id, secret } — not the full webhook
+    // (backend/routes/api/v1/webhooks.js rotate-secret route).
     async rotateWebhookSecret(id) {
         return this.request("POST", `/webhooks/${id}/rotate-secret`);
     }

package/build/tools/accounts.js

@@ -8,7 +8,7 @@ export function registerAccountTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const accounts = Array.isArray(result.data) ? result.data : result.data?.accounts || [];
+        const accounts = Array.isArray(result.data) ? result.data : [];
         if (!accounts.length) {
             return {
                 content: [{ type: "text", text: "No connected accounts found." }],
@@ -42,7 +42,7 @@ export function registerAccountTools(server, getClient) {
         // Fetch profile pictures
         const content = [];
         const imagePromises = accounts
-            .filter((a) => a.profile_picture)
+            .filter((a) => !!a.profile_picture)
             .slice(0, 6)
             .map(async (a) => {
             const img = await fetchImageAsBase64(a.profile_picture);

package/build/tools/analytics.js

@@ -17,7 +17,7 @@ export function registerAnalyticsTools(server, getClient) {
         // (thread posts publish as a chain), so we just total across platforms here.
         // The legacy flat shape (d.impressions / d.platform_stats) doesn't exist on
         // this endpoint and reading those keys returned "—" for every field.
-        const platforms = d?.platforms || {};
+        const platforms = d?.platforms ?? {};
         const platformEntries = Object.entries(platforms);
         if (platformEntries.length === 0) {
             return {
@@ -110,9 +110,9 @@ export function registerAnalyticsTools(server, getClient) {
         // API returns { data: [{ post_id, platforms: { <platform>: { metrics } } }] }.
         // Per-platform metrics are already thread-summed server-side; collapse each
         // post's per-platform metrics into totals, mirroring get_post_analytics.
-        const entries = result.data || [];
+        const entries = result.data ?? [];
         const rows = entries.map((entry) => {
-            const platforms = entry?.platforms || {};
+            const platforms = entry?.platforms ?? {};
             const platformEntries = Object.entries(platforms);
             let impressions = 0;
             let engagements = 0;
@@ -167,6 +167,11 @@ export function registerAnalyticsTools(server, getClient) {
             };
         }
         const d = result.data;
+        if (!d) {
+            return {
+                content: [{ type: "text", text: "No analytics overview data returned." }],
+            };
+        }
         const resolvedStart = result.start_date;
         const resolvedEnd = result.end_date;
         const currentDate = result.current_date;
@@ -189,8 +194,7 @@ export function registerAnalyticsTools(server, getClient) {
             md += `|----------|-------|-------------|-------------|----------|\n`;
             // Sort by impressions descending
             const sorted = Object.entries(d.platform_breakdown).sort((a, b) => (b[1].total_impressions || 0) - (a[1].total_impressions || 0));
-            for (const [platform, stats] of sorted) {
-                const s = stats;
+            for (const [platform, s] of sorted) {
                 const rate = s.engagement_rate !== undefined
                     ? `${s.engagement_rate.toFixed(2)}%`
                     : "—";
@@ -276,7 +280,10 @@ export function registerAnalyticsTools(server, getClient) {
             };
         }
         const d = result;
-        let md = `## Best times to post — ${capitalize(d.platform)} (${d.timezone})\n\n`;
+        // On success the service always returns platform/timezone; params is the
+        // typed fallback so the label never renders "undefined".
+        const platformLabel = capitalize(d.platform || params.platform);
+        let md = `## Best times to post — ${platformLabel} (${d.timezone})\n\n`;
         md += `**Top slots:**\n`;
         (d.recommendations || []).forEach((r, i) => {
             const extras = [];
@@ -309,10 +316,10 @@ export function registerAnalyticsTools(server, getClient) {
             md += `\n### Best hours per day (score 0-100)\n\n| Day | Best hours |\n|-----|------------|\n${dayRows.join("\n")}\n`;
         }
         if (d.basis === "defaults") {
-            md += `\n_Not enough posting history on ${capitalize(d.platform)} yet (${d.sample_size} analyzed post${d.sample_size === 1 ? "" : "s"}). These are cross-industry averages — publish ${d.posts_needed} more post${d.posts_needed === 1 ? "" : "s"} to unlock recommendations from this audience's own data._\n`;
+            md += `\n_Not enough posting history on ${platformLabel} yet (${d.sample_size} analyzed post${d.sample_size === 1 ? "" : "s"}). These are cross-industry averages — publish ${d.posts_needed} more post${d.posts_needed === 1 ? "" : "s"} to unlock recommendations from this audience's own data._\n`;
         }
         else {
-            md += `\n_Based on ${d.sample_size} ${capitalize(d.platform)} posts from the last ${d.window_days} days (metric: ${d.metric}, times in ${d.timezone})._\n`;
+            md += `\n_Based on ${d.sample_size} ${platformLabel} posts from the last ${d.window_days} days (metric: ${d.metric}, times in ${d.timezone})._\n`;
         }
         return {
             content: [{ type: "text", text: md }],

package/build/tools/hashtag-sets.js

@@ -7,7 +7,7 @@ export function registerHashtagSetTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const sets = Array.isArray(result.data) ? result.data : result.data?.data || [];
+        const sets = Array.isArray(result.data) ? result.data : [];
         if (!sets.length) {
             return {
                 content: [{ type: "text", text: "No hashtag sets yet. Create one with create_hashtag_set." }],
@@ -36,6 +36,11 @@ export function registerHashtagSetTools(server, getClient) {
             };
         }
         const s = result.data;
+        if (!s) {
+            return {
+                content: [{ type: "text", text: "Hashtag set created, but the API returned no details. List it with list_hashtag_sets." }],
+            };
+        }
         return {
             content: [{
                     type: "text",
@@ -55,6 +60,11 @@ export function registerHashtagSetTools(server, getClient) {
             };
         }
         const s = result.data;
+        if (!s) {
+            return {
+                content: [{ type: "text", text: "Hashtag set updated, but the API returned no details. List it with list_hashtag_sets." }],
+            };
+        }
         return {
             content: [{
                     type: "text",

package/build/tools/inbox.js

@@ -4,11 +4,12 @@ const PLATFORM_EMOJI = {
     instagram: "📸",
     facebook: "📘",
     linkedin: "💼",
+    x: "🐦",
 };
 export function registerInboxTools(server, getClient) {
-    server.tool("list_inbox_conversations", "List social inbox conversations (Instagram/Facebook DMs, comments, mentions, and LinkedIn company-page comments/mentions), newest activity first. Cursor-paginated: pass the returned cursor to get the next page.", {
+    server.tool("list_inbox_conversations", "List social inbox conversations (Instagram/Facebook DMs, comments, mentions, LinkedIn company-page comments/mentions, and X DMs where the workspace has opted into X DMs), newest activity first. Cursor-paginated: pass the returned cursor to get the next page.", {
         platform: z
-            .enum(["instagram", "facebook", "linkedin"])
+            .enum(["instagram", "facebook", "linkedin", "x"])
             .optional()
             .describe("Filter to one platform"),
         type: z
@@ -136,7 +137,7 @@ export function registerInboxTools(server, getClient) {
             ],
         };
     });
-    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, or LinkedIn. You can only reply to conversations that already exist. Direct-message replies must be within the platform's 24-hour messaging window. Each workspace can send up to 1,000 replies per day.", {
+    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, or X. You can only reply to conversations that already exist. Meta direct-message replies must be within the platform's 24-hour messaging window. X replies are DM-only and use 2 prepaid credits per send (X's API fee passed through at cost) — a 402 insufficient_credits error means the organisation needs to top up at https://app.omnisocials.com/credits; relay that link to the user rather than retrying. Each workspace can send up to 1,000 replies per day.", {
         conversation_id: z.string().describe("The conversation ID to reply to"),
         text: z.string().describe("The reply text (max 2000 characters)"),
     }, async ({ conversation_id, text }) => {

package/build/tools/media.js

@@ -13,7 +13,7 @@ export function registerMediaTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const items = Array.isArray(result.data) ? result.data : result.data?.media || [];
+        const items = Array.isArray(result.data) ? result.data : [];
         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.`
@@ -122,6 +122,11 @@ When the user provides an image in the conversation (not a URL), use base64_data
             return { content: [{ type: "text", text: md }] };
         }
         const m = result.data;
+        if (!m) {
+            return {
+                content: [{ type: "text", text: "Upload succeeded, but the API returned no media details. Find the file with list_media." }],
+            };
+        }
         const isProcessing = m.status === "processing";
         let md = isProcessing ? `## Media Processing\n\n` : `## Media Uploaded\n\n`;
         md += `| Field | Value |\n`;
@@ -170,7 +175,8 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
         const connected = r.connected_platforms || [];
         let md = `## Compatibility Check\n\n`;
         if (r.file) {
-            const sz = r.file.size_known ? formatBytes(r.file.size_bytes) : "unknown size";
+            // size_known implies size_bytes is a finite number (media.js check route).
+            const sz = r.file.size_known ? formatBytes(r.file.size_bytes ?? 0) : "unknown size";
             md += `File: ${sz}${r.file.mime ? ` · ${r.file.mime}` : ""}\n`;
         }
         md += `Connected platforms: ${connected.length ? connected.join(", ") : "none"}\n\n`;
@@ -204,6 +210,11 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
             };
         }
         const m = result.data;
+        if (!m) {
+            return {
+                content: [{ type: "text", text: "Media updated, but the API returned no details. Verify with list_media." }],
+            };
+        }
         return {
             content: [
                 {
@@ -218,7 +229,7 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
         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 || [];
+        const items = Array.isArray(result.data) ? result.data : [];
         if (!items.length) {
             return { content: [{ type: "text", text: "No folders yet. Create one with create_folder." }] };
         }
@@ -238,6 +249,11 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
             return { content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }] };
         }
         const f = result.data;
+        if (!f) {
+            return {
+                content: [{ type: "text", text: "Folder created, but the API returned no details. Verify with list_folders." }],
+            };
+        }
         return {
             content: [
                 {