posterly-mcp-server 0.48.4 → 0.49.0

package/README.md

@@ -123,7 +123,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.48.4` exposes 62 tools covering 95 actions. The hosted HTTP endpoint exposes the same catalog minus the three signup tools: 59 tools covering 92 actions.
+`posterly-mcp-server@0.49.0` exposes 64 tools covering 100 actions. The hosted HTTP endpoint exposes the same catalog minus the three signup tools: 61 tools covering 97 actions.
 
 Many tools pick what to do with one parameter: `view` (reads), `action` (writes), or `type`. A few pick their mode from which parameters you pass (for example `update_post` with `status` changes the status instead of editing). Every tool description names all of its views and actions.
 
@@ -147,7 +147,6 @@ Accounts, posting, media, schedule, analytics, and support. What most assistants
 | `connect_account` | Connect with credentials |
 | `create_connect_session` | Start a connect session |
 | `trigger_platform_helper` | Run a platform helper |
-| `list_posts` | Posts |
 | `ask_support` | Ask support |
 | `find_available_slot` | Find a free slot |
 | `submit_agent_feedback` | Agent feedback |
@@ -197,6 +196,13 @@ Accounts, posting, media, schedule, analytics, and support. What most assistants
 | `accounts` | Brand accounts |
 | `profile` | Brand profile |
 
+**`list_posts`**: Posts
+
+| View | What it does |
+| --- | --- |
+| `list` (default) | Posts, one page at a time |
+| `counts` | Post counts by day, status, account, and brand |
+
 **`get_post`**: One post
 
 | View | What it does |
@@ -321,13 +327,14 @@ Google Business Profile reviews, media, and audits.
 
 ### Admin (`admin`)
 
-API keys, OAuth clients, webhooks, and workspace members.
+API keys, OAuth clients, webhooks, workspace members, and the publishing pause.
 
 | Tool | What it does |
 | --- | --- |
 | `create_api_key` | Create an API key |
 | `delete_api_key` | Revoke an API key |
 | `list_workspace_members` | Workspace members |
+| `list_publishing_pauses` | Publishing pause: whether the workspace or any brand is paused, and what you may do |
 | `list_oauth_clients` | OAuth clients |
 | `list_webhooks` | Webhooks |
 | `create_webhook` | Create a webhook |
@@ -340,6 +347,14 @@ API keys, OAuth clients, webhooks, and workspace members.
 | `update` | Change role or brands, or turn a teammate's API and AI access on or off (preview then confirm) |
 | `remove` | Remove a member or invite (preview then confirm) |
 
+**`manage_publishing_pause`**: Pause or resume publishing
+
+| Action | What it does |
+| --- | --- |
+| `pause` | Pause publishing for the workspace or one brand: call without `confirm` for a preview of what it holds, then `confirm: true` after the user agrees (publisher or higher) |
+| `resume` | Resume publishing: future posts are scheduled again, posts that missed their time stay paused and are listed (admin or higher) |
+| `publish_missed` | Publish missed posts now, with `confirm: true` after the user agrees (admin or higher) |
+
 **`manage_oauth_client`**: Manage an OAuth client
 
 | Action | What it does |

package/dist/index.js

@@ -21,6 +21,8 @@ import { createApiKeyTool } from './tools/create-api-key.js';
 import { deleteApiKeyTool } from './tools/delete-api-key.js';
 import { listWorkspaceMembersTool } from './tools/list-workspace-members.js';
 import { manageWorkspaceMemberTool } from './tools/manage-workspace-member.js';
+import { listPublishingPausesTool } from './tools/list-publishing-pauses.js';
+import { managePublishingPauseTool } from './tools/manage-publishing-pause.js';
 import { getCreditsTool } from './tools/get-credits.js';
 import { getSubscriptionTool } from './tools/get-subscription.js';
 import { cancelSubscriptionTool } from './tools/cancel-subscription.js';
@@ -89,6 +91,8 @@ const STDIO_TOOLS = [
     deleteApiKeyTool,
     listWorkspaceMembersTool,
     manageWorkspaceMemberTool,
+    listPublishingPausesTool,
+    managePublishingPauseTool,
     getCreditsTool,
     getSubscriptionTool,
     cancelSubscriptionTool,

package/dist/lib/api-client.d.ts

@@ -134,6 +134,11 @@ export interface PostSuggestion {
 }
 export interface PostSuggestionsResponse {
     suggestions: PostSuggestion[];
+    total?: number;
+    limit?: number;
+    offset?: number;
+    has_more?: boolean;
+    next_offset?: number | null;
 }
 export interface DismissSuggestionResponse {
     ok: boolean;
@@ -169,6 +174,59 @@ export interface Post {
     content_plan_id?: string | null;
     approval?: ApiPostApproval;
 }
+/** Filters shared by GET /posts and GET /posts/counts. */
+export interface ListPostsParams {
+    status?: string;
+    platform?: string;
+    account_id?: string;
+    workspace_id?: string;
+    approval_status?: string;
+    approval_waiting_on?: string;
+    brand_id?: string;
+    scheduled_from?: string;
+    scheduled_to?: string;
+    timezone?: string;
+}
+export interface PostsRangeEcho {
+    from: string | null;
+    to: string | null;
+    timezone: string;
+}
+export interface ListPostsResponse {
+    posts: Post[];
+    total: number;
+    limit?: number;
+    offset?: number;
+    has_more?: boolean;
+    next_offset?: number | null;
+    order?: 'asc' | 'desc';
+    range?: PostsRangeEcho | null;
+}
+export interface PostCountsResponse {
+    total: number;
+    counted: number;
+    truncated: boolean;
+    range: PostsRangeEcho | null;
+    by_day: Array<{
+        date: string;
+        count: number;
+    }>;
+    by_status: Array<{
+        status: string;
+        count: number;
+    }>;
+    by_account: Array<{
+        account_id: string | null;
+        platform: string | null;
+        username: string | null;
+        count: number;
+    }>;
+    by_brand: Array<{
+        brand_id: string | null;
+        name: string | null;
+        count: number;
+    }>;
+}
 export interface InstagramPostSettings {
     __type?: 'instagram' | 'instagram-standalone';
     post_type?: 'post' | 'feed' | 'story' | 'reel' | 'carousel';
@@ -425,6 +483,61 @@ export type WorkspaceMemberConfirmFields = {
     confirm?: boolean;
     preview_id?: string;
 };
+export type PublishingPauseState = {
+    workspace: {
+        id: string;
+        name: string | null;
+        paused: boolean;
+        paused_at: string | null;
+    };
+    brands: Array<{
+        id: string;
+        name: string | null;
+        paused: boolean;
+        paused_at: string;
+    }>;
+    viewer: {
+        role: string;
+        can_pause_workspace: boolean;
+        can_pause_brand: boolean;
+        can_resume: boolean;
+        can_publish_missed: boolean;
+    };
+};
+/**
+ * POST /publishing-pause. A pause without confirm: true changes nothing and
+ * answers 400 confirmation_required with a preview; the client returns that
+ * body (requires_confirmation: true) instead of throwing, so the tool can show
+ * it.
+ */
+export type PublishingPauseChangeResponse = {
+    ok?: boolean;
+    requires_confirmation?: boolean;
+    code?: string;
+    error?: string;
+    action?: 'pause' | 'resume';
+    scope?: 'workspace' | 'brand';
+    workspace_id?: string;
+    workspace_name?: string | null;
+    brand_id?: string | null;
+    brand_name?: string | null;
+    already_paused?: boolean;
+    scheduled_posts_to_hold?: number | null;
+    held_count?: number;
+    resumed_count?: number;
+    missed_count?: number;
+    missed_post_ids?: number[];
+    still_held_count?: number;
+    disconnected_count?: number;
+    failed_post_ids?: number[];
+    message?: string;
+};
+export type PublishMissedResponse = {
+    ok: boolean;
+    started: number;
+    skipped: number;
+    message?: string;
+};
 export type CreateApiKeyPayload = {
     name?: string;
     scopes?: ApiKeyScope[];
@@ -836,8 +949,12 @@ export interface ActivityItem {
 }
 export interface ActivityResponse {
     items: ActivityItem[];
+    /** Items on this page (kept for older clients); use has_more to tell whether more exist. */
     total: number;
     limit: number;
+    offset?: number;
+    has_more?: boolean;
+    next_offset?: number | null;
 }
 export interface UpdateEntry {
     slug: string;
@@ -854,6 +971,11 @@ export interface UpdateEntry {
 }
 export interface UpdatesResponse {
     updates: UpdateEntry[];
+    total?: number;
+    limit?: number;
+    offset?: number;
+    has_more?: boolean;
+    next_offset?: number | null;
 }
 export interface ApiWebhook {
     id: string;
@@ -1159,6 +1281,20 @@ export declare class PosterlyClient {
         member_id?: string;
         invite_id?: string;
     }, data: WorkspaceMemberConfirmFields): Promise<WorkspaceMemberChangeResponse>;
+    getPublishingPause(params?: {
+        workspace_id?: string;
+    }): Promise<PublishingPauseState>;
+    changePublishingPause(data: {
+        action: 'pause' | 'resume';
+        brand_id?: string;
+        workspace_id?: string;
+        confirm?: boolean;
+    }): Promise<PublishingPauseChangeResponse>;
+    publishMissedPausedPosts(data: {
+        post_ids: number[];
+        workspace_id?: string;
+        confirm: true;
+    }): Promise<PublishMissedResponse>;
     getSubscription(): Promise<SubscriptionSummaryResponse>;
     getCredits(): Promise<CreditsSummaryResponse>;
     cancelSubscription(data: CancelSubscriptionPayload): Promise<CancelSubscriptionResponse>;
@@ -1247,22 +1383,16 @@ export declare class PosterlyClient {
         account_id?: string | number;
         status?: 'pending' | 'scheduled' | 'dismissed';
         limit?: number;
+        offset?: number;
     }): Promise<PostSuggestionsResponse>;
     dismissSuggestion(id: string): Promise<DismissSuggestionResponse>;
-    listPosts(params?: {
-        status?: string;
-        platform?: string;
-        account_id?: string;
+    listPosts(params?: ListPostsParams & {
         limit?: number;
         offset?: number;
-        workspace_id?: string;
-        approval_status?: string;
-        approval_waiting_on?: string;
-        brand_id?: string;
-    }): Promise<{
-        posts: Post[];
-        total: number;
-    }>;
+        order?: 'asc' | 'desc';
+    }): Promise<ListPostsResponse>;
+    /** GET /posts/counts: exact totals per day, status, account, and brand for a scheduled range. */
+    countPosts(params: ListPostsParams): Promise<PostCountsResponse>;
     createPost(data: CreatePostPayload): Promise<CreatePostResponse>;
     validatePost(data: CreatePostPayload): Promise<ValidatePostResponse>;
     submitAgentFeedback(data: AgentFeedbackPayload): Promise<AgentFeedbackResponse>;
@@ -1474,9 +1604,11 @@ export declare class PosterlyClient {
         since?: string;
         type?: 'all' | 'activity' | 'publish';
         limit?: number;
+        offset?: number;
     }): Promise<ActivityResponse>;
     getUpdates(params?: {
         limit?: number;
+        offset?: number;
         since?: string;
         include_content?: boolean;
     }): Promise<UpdatesResponse>;
@@ -1555,6 +1687,7 @@ export declare class PosterlyClient {
     }>;
     listMedia(params?: {
         limit?: number;
+        offset?: number;
         dropSessionId?: string;
     }): Promise<{
         media: Array<{
@@ -1568,6 +1701,10 @@ export declare class PosterlyClient {
             drop_session_id: string | null;
         }>;
         total: number;
+        limit?: number;
+        offset?: number;
+        has_more?: boolean;
+        next_offset?: number | null;
     }>;
     uploadMedia(input: {
         filePath?: string;

package/dist/lib/api-client.js

@@ -36,6 +36,30 @@ export function setMcpClientNameResolver(resolver) {
 export function sanitizeClientHeaderValue(value) {
     return value.replace(/[^\x20-\x7e]/g, '').trim().slice(0, 200);
 }
+function postFilterParams(params) {
+    const searchParams = new URLSearchParams();
+    if (params?.status)
+        searchParams.set('status', params.status);
+    if (params?.platform)
+        searchParams.set('platform', params.platform);
+    if (params?.account_id)
+        searchParams.set('account_id', params.account_id);
+    if (params?.workspace_id)
+        searchParams.set('workspace_id', params.workspace_id);
+    if (params?.approval_status)
+        searchParams.set('approval_status', params.approval_status);
+    if (params?.approval_waiting_on)
+        searchParams.set('approval_waiting_on', params.approval_waiting_on);
+    if (params?.brand_id)
+        searchParams.set('brand_id', params.brand_id);
+    if (params?.scheduled_from)
+        searchParams.set('scheduled_from', params.scheduled_from);
+    if (params?.scheduled_to)
+        searchParams.set('scheduled_to', params.scheduled_to);
+    if (params?.timezone)
+        searchParams.set('timezone', params.timezone);
+    return searchParams;
+}
 export class PosterlyClient {
     baseUrl;
     apiKey;
@@ -116,7 +140,7 @@ export class PosterlyClient {
             throw new Error('posterly access is not installed yet. Use start_signup to begin paid setup, or set POSTERLY_API_KEY after signup.');
         }
     }
-    async request(method, path, body) {
+    async request(method, path, body, options) {
         this.requireApiKey();
         const url = `${this.baseUrl}/api/v1${path}`;
         const headers = {
@@ -144,6 +168,11 @@ export class PosterlyClient {
         const res = await fetch(url, init);
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: res.statusText }));
+            // A write that needs confirm: true answers 400 with a preview; callers
+            // that show previews get the body back instead of an error.
+            if (options?.acceptConfirmationPreview && res.status === 400 && err?.requires_confirmation === true) {
+                return err;
+            }
             throw new Error(formatApiError(res, err));
         }
         return res.json();
@@ -204,6 +233,19 @@ export class PosterlyClient {
         const qs = params.toString();
         return this.request('DELETE', `${path}${qs ? `?${qs}` : ''}`);
     }
+    async getPublishingPause(params) {
+        const query = new URLSearchParams();
+        if (params?.workspace_id)
+            query.set('workspace_id', params.workspace_id);
+        const qs = query.toString();
+        return this.request('GET', `/publishing-pause${qs ? `?${qs}` : ''}`);
+    }
+    async changePublishingPause(data) {
+        return this.request('POST', '/publishing-pause', data, { acceptConfirmationPreview: true });
+    }
+    async publishMissedPausedPosts(data) {
+        return this.request('POST', '/publishing-pause/publish-missed', data);
+    }
     async getSubscription() {
         return this.request('GET', '/subscription');
     }
@@ -318,6 +360,8 @@ export class PosterlyClient {
             searchParams.set('status', params.status);
         if (params?.limit)
             searchParams.set('limit', String(params.limit));
+        if (params?.offset)
+            searchParams.set('offset', String(params.offset));
         const qs = searchParams.toString();
         return this.request('GET', `/suggestions${qs ? `?${qs}` : ''}`);
     }
@@ -325,28 +369,21 @@ export class PosterlyClient {
         return this.request('POST', `/suggestions/${encodeURIComponent(id)}/dismiss`, {});
     }
     async listPosts(params) {
-        const searchParams = new URLSearchParams();
-        if (params?.status)
-            searchParams.set('status', params.status);
-        if (params?.platform)
-            searchParams.set('platform', params.platform);
-        if (params?.account_id)
-            searchParams.set('account_id', params.account_id);
+        const searchParams = postFilterParams(params);
         if (params?.limit)
             searchParams.set('limit', String(params.limit));
         if (params?.offset)
             searchParams.set('offset', String(params.offset));
-        if (params?.workspace_id)
-            searchParams.set('workspace_id', params.workspace_id);
-        if (params?.approval_status)
-            searchParams.set('approval_status', params.approval_status);
-        if (params?.approval_waiting_on)
-            searchParams.set('approval_waiting_on', params.approval_waiting_on);
-        if (params?.brand_id)
-            searchParams.set('brand_id', params.brand_id);
+        if (params?.order)
+            searchParams.set('order', params.order);
         const qs = searchParams.toString();
         return this.request('GET', `/posts${qs ? `?${qs}` : ''}`);
     }
+    /** GET /posts/counts: exact totals per day, status, account, and brand for a scheduled range. */
+    async countPosts(params) {
+        const qs = postFilterParams(params).toString();
+        return this.request('GET', `/posts/counts${qs ? `?${qs}` : ''}`);
+    }
     async createPost(data) {
         return this.request('POST', '/posts', data);
     }
@@ -563,6 +600,8 @@ export class PosterlyClient {
             searchParams.set('type', params.type);
         if (params?.limit)
             searchParams.set('limit', String(params.limit));
+        if (params?.offset)
+            searchParams.set('offset', String(params.offset));
         const qs = searchParams.toString();
         return this.request('GET', `/activity${qs ? `?${qs}` : ''}`);
     }
@@ -570,6 +609,8 @@ export class PosterlyClient {
         const searchParams = new URLSearchParams();
         if (params?.limit)
             searchParams.set('limit', String(params.limit));
+        if (params?.offset)
+            searchParams.set('offset', String(params.offset));
         if (params?.since)
             searchParams.set('since', params.since);
         if (params?.include_content)
@@ -643,6 +684,8 @@ export class PosterlyClient {
         const searchParams = new URLSearchParams();
         if (params?.limit)
             searchParams.set('limit', String(params.limit));
+        if (params?.offset)
+            searchParams.set('offset', String(params.offset));
         if (params?.dropSessionId)
             searchParams.set('drop_session_id', params.dropSessionId);
         const qs = searchParams.toString();

package/dist/lib/format.d.ts

@@ -1,4 +1,4 @@
-import type { Account, LearnedVoice, Post } from './api-client.js';
+import type { Account, LearnedVoice, ListPostsResponse, Post, PostCountsResponse, PostsRangeEcho } from './api-client.js';
 type CellValue = string | number | boolean | null | undefined;
 export declare const DASHBOARD_CALENDAR_URL: string;
 export declare const DASHBOARD_TABLE_URL: string;
@@ -41,4 +41,41 @@ export declare function compactText(value: string | null | undefined, maxLength?
 export declare function mdLearnedVoice(learned: LearnedVoice | null | undefined): string | null;
 export declare function statusLabel(status: string | null | undefined): string;
 export declare function code(value: CellValue): string;
-export {};
+/**
+ * The completeness line every paged list prints, so an agent always knows
+ * whether it has seen everything. Shared by the npm package and the hosted
+ * endpoint.
+ */
+export declare function formatPagingNote(input: {
+    noun: string;
+    tool: string;
+    offset?: number | null;
+    count: number;
+    total?: number | null;
+    hasMore: boolean;
+    nextOffset?: number | null;
+}): string;
+export type PostListRange = PostsRangeEcho;
+export type PostListPage = ListPostsResponse;
+export type { PostCountsResponse };
+/** "Wed, Oct 1, 2026, 09:00" in `timeZone`; the raw value when it is not a date. */
+export declare function formatDateTimeInZone(value: string | null | undefined, timeZone: string): string;
+/** "Wed, Oct 1, 2026" for a YYYY-MM-DD calendar day. */
+export declare function formatCalendarDay(day: string): string;
+/**
+ * The scheduled range in plain words. Whole days read as "Oct 1, 2026 to
+ * Oct 31, 2026" (the API's `to` is exclusive, so a midnight `to` ends the
+ * day before); anything else reads as "from X up to Y".
+ */
+export declare function formatPostRange(range: PostListRange): string;
+/**
+ * One page of list_posts. Always says whether every matching post is shown,
+ * and when it is not, exactly which offset to call next, so an agent never
+ * mistakes the first page for the whole schedule.
+ */
+export declare function formatPostListPage(data: PostListPage, options: {
+    timeZone: string;
+    dashboardUrl?: string;
+}): string;
+/** The counts view of list_posts: exact totals per day, status, account, and brand. */
+export declare function formatPostCounts(data: PostCountsResponse): string;

package/dist/lib/format.js

@@ -229,3 +229,161 @@ function isInCurrentMonth(value) {
     const now = new Date();
     return date.getFullYear() === now.getFullYear() && date.getMonth() === now.getMonth();
 }
+/**
+ * The completeness line every paged list prints, so an agent always knows
+ * whether it has seen everything. Shared by the npm package and the hosted
+ * endpoint.
+ */
+export function formatPagingNote(input) {
+    const offset = input.offset ?? 0;
+    const first = offset + 1;
+    const last = offset + input.count;
+    const ofTotal = typeof input.total === 'number' ? ` of ${input.total}` : '';
+    if (input.hasMore) {
+        const next = typeof input.nextOffset === 'number' ? input.nextOffset : last;
+        return `**Not complete: showing ${first}-${last}${ofTotal} ${input.noun}.** More available: call ${input.tool} again with the same filters and offset=${next}. Keep paging until this says complete before drawing any conclusion about totals.`;
+    }
+    if (offset === 0) {
+        return `**Complete: all ${typeof input.total === 'number' ? input.total : input.count} ${input.noun} are shown.**`;
+    }
+    return `**Complete: this is the last page (${input.noun} ${first}-${last}${ofTotal}).**`;
+}
+function zonedParts(value, timeZone) {
+    const date = typeof value === 'string' ? new Date(value) : value;
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        weekday: 'short',
+        month: 'short',
+        day: 'numeric',
+        year: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(date);
+    return Object.fromEntries(parts.map((part) => [part.type, part.value]));
+}
+/** "Wed, Oct 1, 2026, 09:00" in `timeZone`; the raw value when it is not a date. */
+export function formatDateTimeInZone(value, timeZone) {
+    if (!value)
+        return 'not scheduled';
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value;
+    const p = zonedParts(date, timeZone);
+    return `${p.weekday}, ${p.month} ${p.day}, ${p.year}, ${p.hour}:${p.minute}`;
+}
+/** "Wed, Oct 1, 2026" for a YYYY-MM-DD calendar day. */
+export function formatCalendarDay(day) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day);
+    if (!match)
+        return day;
+    const p = zonedParts(new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), 12)), 'UTC');
+    return `${p.weekday}, ${p.month} ${p.day}, ${p.year}`;
+}
+function isZonedMidnight(value, timeZone) {
+    const p = zonedParts(value, timeZone);
+    return p.hour === '00' && p.minute === '00' && p.second === '00';
+}
+function zonedDay(value, timeZone) {
+    const p = zonedParts(value, timeZone);
+    return `${p.month} ${p.day}, ${p.year}`;
+}
+/**
+ * The scheduled range in plain words. Whole days read as "Oct 1, 2026 to
+ * Oct 31, 2026" (the API's `to` is exclusive, so a midnight `to` ends the
+ * day before); anything else reads as "from X up to Y".
+ */
+export function formatPostRange(range) {
+    const tz = range.timezone;
+    if (range.from && range.to && isZonedMidnight(range.from, tz) && isZonedMidnight(range.to, tz)) {
+        const lastDay = new Date(Date.parse(range.to) - 1);
+        return `${zonedDay(range.from, tz)} to ${zonedDay(lastDay, tz)} (${tz})`;
+    }
+    const from = range.from ? `from ${formatDateTimeInZone(range.from, tz)}` : '';
+    const to = range.to ? `up to ${formatDateTimeInZone(range.to, tz)}` : '';
+    return `${[from, to].filter(Boolean).join(' ')} (${tz})`;
+}
+function approvalCell(post) {
+    if (!post.approval || post.approval.status === 'none')
+        return 'none';
+    return post.approval.waiting_on ? `${post.approval.status} (waiting on ${post.approval.waiting_on})` : post.approval.status;
+}
+/**
+ * One page of list_posts. Always says whether every matching post is shown,
+ * and when it is not, exactly which offset to call next, so an agent never
+ * mistakes the first page for the whole schedule.
+ */
+export function formatPostListPage(data, options) {
+    const posts = Array.isArray(data.posts) ? data.posts : [];
+    const total = typeof data.total === 'number' ? data.total : posts.length;
+    const offset = typeof data.offset === 'number' ? data.offset : 0;
+    const tz = options.timeZone;
+    const rangeLine = data.range ? `Scheduled ${formatPostRange(data.range)}` : '';
+    const orderLine = data.order === 'asc' ? 'oldest first' : 'newest first';
+    if (posts.length === 0) {
+        const detail = total > 0
+            ? `No posts on this page: offset ${offset} is past the last of the ${total} matching posts. Call again with a lower offset.`
+            : `No posts match these filters${data.range ? ` (${formatPostRange(data.range)})` : ''}. This is complete: there is nothing more to page through.`;
+        return [
+            mdTitle('No posts'),
+            detail,
+            '\n**Next step for the AI agent:** tell the user nothing matches that filter, then ask what they want to schedule next.',
+        ].join('\n');
+    }
+    const first = offset + 1;
+    const last = offset + posts.length;
+    const hasMore = typeof data.has_more === 'boolean' ? data.has_more : last < total;
+    const nextOffset = typeof data.next_offset === 'number' ? data.next_offset : last;
+    const completeness = hasMore
+        ? `**Not complete: showing ${first}-${last} of ${total} matching posts.** More available: call list_posts again with the same filters and offset=${nextOffset}. Keep paging until every post is shown before drawing any conclusion about totals, gaps, or how busy a day or client is. For "how many" questions, use view=counts.`
+        : first === 1
+            ? `**Complete: all ${total} matching posts are shown.**`
+            : `**Complete: this is the last page (posts ${first}-${last} of ${total}).**`;
+    const table = mdTable(['Status', 'Post ID', `Scheduled (${tz})`, 'Type', 'Account ID', 'Brand ID', 'Approval', 'Caption'], 
+    // The API post row carries account and brand IDs only (no joined names);
+    // list_accounts and list_brands, or view=counts, resolve them.
+    posts.map((post) => [
+        statusLabel(post.status),
+        code(String(post.id)),
+        formatDateTimeInZone(post.scheduled_at, tz),
+        post.post_type || 'post',
+        post.social_account_id != null ? String(post.social_account_id) : 'n/a',
+        post.brand_id || 'none',
+        approvalCell(post),
+        compactText(post.content, 80) || '(empty)',
+    ]));
+    return [
+        mdTitle(hasMore || first > 1 ? `Posts ${first}-${last} of ${total}` : `Posts (${total})`, [rangeLine, orderLine, `times in ${tz}`].filter(Boolean).join(' · ')),
+        table,
+        completeness,
+        options.dashboardUrl ? `View in posterly: ${options.dashboardUrl}` : '',
+    ].filter(Boolean).join('\n\n');
+}
+/** The counts view of list_posts: exact totals per day, status, account, and brand. */
+export function formatPostCounts(data) {
+    const range = data.range;
+    const days = Array.isArray(data.by_day) ? data.by_day : [];
+    const emptyDays = days.filter((day) => day.count === 0).map((day) => formatCalendarDay(day.date));
+    const sections = [
+        mdTitle(`Post counts: ${data.total} ${data.total === 1 ? 'post' : 'posts'}`, range ? formatPostRange(range) : undefined),
+        data.truncated
+            ? `**Partial grouping:** ${data.total} posts match, but only the first ${data.counted} were grouped below. The total is exact; narrow the range or filters for exact per-day numbers.`
+            : `**Complete:** every one of the ${data.total} matching posts is counted below.`,
+        mdSection('By day', mdTable(['Day', 'Posts'], days.map((day) => [formatCalendarDay(day.date), day.count]))),
+        // A truncated grouping only covers the earliest posts, so a day with a
+        // zero here may still have posts: never list "empty" days then.
+        days.length > 0 && !data.truncated ? `Days with no posts: ${emptyDays.length > 0 ? emptyDays.join('; ') : 'none'}.` : '',
+        data.truncated ? '_Per-day numbers above cover only the grouped posts, so a day showing 0 may still have posts. Narrow the range to check for empty days._' : '',
+        mdSection('By status', mdTable(['Status', 'Posts'], (data.by_status || []).map((row) => [statusLabel(row.status), row.count]))),
+        mdSection('By account', mdTable(['Account', 'Platform', 'Account ID', 'Posts'], (data.by_account || []).map((row) => [
+            row.username ? `@${row.username}` : row.account_id ? 'unknown account' : 'no account',
+            row.platform || 'n/a',
+            row.account_id ?? 'none',
+            row.count,
+        ]))),
+        mdSection('By brand', mdTable(['Brand', 'Brand ID', 'Posts'], (data.by_brand || []).map((row) => [row.name || (row.brand_id ? 'unknown brand' : 'no brand'), row.brand_id ?? 'none', row.count]))),
+        '**Next step for the AI agent:** these totals are exact for the filters above. To read the posts themselves, call list_posts with view=list and the same filters, paging with offset until every post is shown.',
+    ];
+    return sections.filter(Boolean).join('\n\n');
+}

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.48.4";
+export declare const POSTERLY_MCP_VERSION = "0.49.0";

package/dist/lib/version.js

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.48.4';
+export const POSTERLY_MCP_VERSION = '0.49.0';