posterly-mcp-server 0.48.4 → 0.49.0

package/dist/tools/manage-webhook.d.ts

@@ -28,20 +28,20 @@ export declare const manageWebhookTool: {
     }, "strip", z.ZodTypeAny, {
         action: "update" | "delete" | "test";
         webhook_id: string;
+        workspace_id?: string | null | undefined;
         description?: string | null | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | null | undefined;
         url?: string | undefined;
         is_active?: boolean | undefined;
         events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
     }, {
         action: "update" | "delete" | "test";
         webhook_id: string;
+        workspace_id?: string | null | undefined;
         description?: string | null | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | null | undefined;
         url?: string | undefined;
         is_active?: boolean | undefined;
         events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
@@ -59,16 +59,16 @@ export declare const manageWebhookTool: {
         }, "strip", z.ZodTypeAny, {
             confirm: true;
             webhook_id: string;
-            description?: string | null | undefined;
             workspace_id?: string | null | undefined;
+            description?: string | null | undefined;
             url?: string | undefined;
             is_active?: boolean | undefined;
             events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
         }, {
             confirm: true;
             webhook_id: string;
-            description?: string | null | undefined;
             workspace_id?: string | null | undefined;
+            description?: string | null | undefined;
             url?: string | undefined;
             is_active?: boolean | undefined;
             events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;

package/dist/tools/validate-post.d.ts

@@ -653,9 +653,9 @@ export declare const validatePostInputSchema: import("zod").ZodObject<{
     workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
 }, "strip", import("zod").ZodTypeAny, {
     platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-    username?: string | undefined;
-    workspace_id?: string | undefined;
     account_id?: string | undefined;
+    workspace_id?: string | undefined;
+    username?: string | undefined;
     caption?: string | undefined;
     scheduled_at?: string | undefined;
     media_url?: string | undefined;
@@ -854,9 +854,9 @@ export declare const validatePostInputSchema: import("zod").ZodObject<{
     }, import("zod").ZodTypeAny, "passthrough"> | undefined;
 }, {
     platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-    username?: string | undefined;
-    workspace_id?: string | undefined;
     account_id?: string | undefined;
+    workspace_id?: string | undefined;
+    username?: string | undefined;
     caption?: string | undefined;
     scheduled_at?: string | undefined;
     media_url?: string | undefined;
@@ -1711,9 +1711,9 @@ export declare const validatePostTool: {
         workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
     }, "strip", import("zod").ZodTypeAny, {
         platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-        username?: string | undefined;
-        workspace_id?: string | undefined;
         account_id?: string | undefined;
+        workspace_id?: string | undefined;
+        username?: string | undefined;
         caption?: string | undefined;
         scheduled_at?: string | undefined;
         media_url?: string | undefined;
@@ -1912,9 +1912,9 @@ export declare const validatePostTool: {
         }, import("zod").ZodTypeAny, "passthrough"> | undefined;
     }, {
         platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-        username?: string | undefined;
-        workspace_id?: string | undefined;
         account_id?: string | undefined;
+        workspace_id?: string | undefined;
+        username?: string | undefined;
         caption?: string | undefined;
         scheduled_at?: string | undefined;
         media_url?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.48.4",
+  "version": "0.49.0",
   "mcpName": "io.github.awpthorp/posterly",
   "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.awpthorp/posterly",
   "title": "posterly",
   "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
-  "version": "0.48.4",
+  "version": "0.49.0",
   "websiteUrl": "https://www.poster.ly/mcp",
   "repository": {
     "url": "https://github.com/awpthorp/posterly",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "posterly-mcp-server",
-      "version": "0.48.4",
+      "version": "0.49.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -24,6 +24,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';
@@ -108,6 +110,8 @@ const STDIO_TOOLS: ToolModule[] = [
   deleteApiKeyTool,
   listWorkspaceMembersTool,
   manageWorkspaceMemberTool,
+  listPublishingPausesTool,
+  managePublishingPauseTool,
   getCreditsTool,
   getSubscriptionTool,
   cancelSubscriptionTool,

package/src/lib/api-client.ts

@@ -176,6 +176,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 {
@@ -216,6 +221,63 @@ export interface Post {
   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 }>;
+}
+
+function postFilterParams(params?: ListPostsParams): URLSearchParams {
+  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 interface InstagramPostSettings {
   __type?: 'instagram' | 'instagram-standalone';
   post_type?: 'post' | 'feed' | 'story' | 'reel' | 'carousel';
@@ -469,6 +531,54 @@ export type WorkspaceMemberConfirmFields = {
   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[];
@@ -882,8 +992,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 {
@@ -902,6 +1016,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 {
@@ -1290,6 +1409,7 @@ export class PosterlyClient {
     method: string,
     path: string,
     body?: unknown,
+    options?: { acceptConfirmationPreview?: boolean },
   ): Promise<T> {
     this.requireApiKey();
 
@@ -1322,6 +1442,11 @@ export class PosterlyClient {
 
     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 as T;
+      }
       throw new Error(formatApiError(res, err));
     }
 
@@ -1411,6 +1536,30 @@ export class PosterlyClient {
     return this.request('DELETE', `${path}${qs ? `?${qs}` : ''}`);
   }
 
+  async getPublishingPause(params?: { workspace_id?: string }): Promise<PublishingPauseState> {
+    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: {
+    action: 'pause' | 'resume';
+    brand_id?: string;
+    workspace_id?: string;
+    confirm?: boolean;
+  }): Promise<PublishingPauseChangeResponse> {
+    return this.request('POST', '/publishing-pause', data, { acceptConfirmationPreview: true });
+  }
+
+  async publishMissedPausedPosts(data: {
+    post_ids: number[];
+    workspace_id?: string;
+    confirm: true;
+  }): Promise<PublishMissedResponse> {
+    return this.request('POST', '/publishing-pause/publish-missed', data);
+  }
+
   async getSubscription(): Promise<SubscriptionSummaryResponse> {
     return this.request('GET', '/subscription');
   }
@@ -1569,11 +1718,13 @@ export class PosterlyClient {
     account_id?: string | number;
     status?: 'pending' | 'scheduled' | 'dismissed';
     limit?: number;
+    offset?: number;
   }): Promise<PostSuggestionsResponse> {
     const searchParams = new URLSearchParams();
     if (params?.account_id) searchParams.set('account_id', String(params.account_id));
     if (params?.status) 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}` : ''}`);
   }
@@ -1582,32 +1733,26 @@ export class PosterlyClient {
     return this.request('POST', `/suggestions/${encodeURIComponent(id)}/dismiss`, {});
   }
 
-  async listPosts(params?: {
-    status?: string;
-    platform?: string;
-    account_id?: string;
+  async 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 }> {
-    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);
+    order?: 'asc' | 'desc';
+  }): Promise<ListPostsResponse> {
+    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: ListPostsParams): Promise<PostCountsResponse> {
+    const qs = postFilterParams(params).toString();
+    return this.request('GET', `/posts/counts${qs ? `?${qs}` : ''}`);
+  }
+
   async createPost(data: CreatePostPayload): Promise<CreatePostResponse> {
     return this.request('POST', '/posts', data);
   }
@@ -1975,6 +2120,7 @@ export class PosterlyClient {
     since?: string;
     type?: 'all' | 'activity' | 'publish';
     limit?: number;
+    offset?: number;
   }): Promise<ActivityResponse> {
     const searchParams = new URLSearchParams();
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
@@ -1982,17 +2128,20 @@ export class PosterlyClient {
     if (params?.since) searchParams.set('since', params.since);
     if (params?.type) 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}` : ''}`);
   }
 
   async getUpdates(params?: {
     limit?: number;
+    offset?: number;
     since?: string;
     include_content?: boolean;
   }): Promise<UpdatesResponse> {
     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) searchParams.set('include_content', 'true');
     const qs = searchParams.toString();
@@ -2115,6 +2264,7 @@ export class PosterlyClient {
 
   async listMedia(params?: {
     limit?: number;
+    offset?: number;
     dropSessionId?: string;
   }): Promise<{
     media: Array<{
@@ -2128,9 +2278,14 @@ export class PosterlyClient {
       drop_session_id: string | null;
     }>;
     total: number;
+    limit?: number;
+    offset?: number;
+    has_more?: boolean;
+    next_offset?: number | null;
   }> {
     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();
     return this.request('GET', `/media${qs ? `?${qs}` : ''}`);

package/src/lib/format.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;
 
@@ -244,3 +244,203 @@ function isInCurrentMonth(value?: string | null): boolean {
   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: {
+  noun: string;
+  tool: string;
+  offset?: number | null;
+  count: number;
+  total?: number | null;
+  hasMore: boolean;
+  nextOffset?: number | null;
+}): string {
+  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}).**`;
+}
+
+// ---------------------------------------------------------------------------
+// list_posts: shared by the npm package and the hosted endpoint
+// (lib/mcp/http-tools.ts imports these), so both surfaces print the same
+// completeness line and the same times for the same response.
+// ---------------------------------------------------------------------------
+
+export type PostListRange = PostsRangeEcho;
+export type PostListPage = ListPostsResponse;
+export type { PostCountsResponse };
+
+function zonedParts(value: string | Date, timeZone: string): Record<string, string> {
+  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: string | null | undefined, timeZone: string): string {
+  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: string): string {
+  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: string, timeZone: string): boolean {
+  const p = zonedParts(value, timeZone);
+  return p.hour === '00' && p.minute === '00' && p.second === '00';
+}
+
+function zonedDay(value: string | Date, timeZone: string): string {
+  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: PostListRange): string {
+  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: Post): string {
+  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: PostListPage,
+  options: { timeZone: string; dashboardUrl?: string },
+): string {
+  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: PostCountsResponse): string {
+  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/src/lib/version.ts

@@ -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';