posterly-mcp-server 0.48.3 → 0.48.5

package/README.md

@@ -123,7 +123,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.48.3` 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.48.5` exposes 64 tools covering 99 actions. The hosted HTTP endpoint exposes the same catalog minus the three signup tools: 61 tools covering 96 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.
 
@@ -321,13 +321,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 +341,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

@@ -425,6 +425,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[];
@@ -559,12 +614,24 @@ export type SuggestedSlotBasis = 'yours' | 'platform' | 'default';
 export interface SuggestedSlot extends Slot {
     basis: SuggestedSlotBasis;
     reason: string;
+    /** 1-5; confidence-capped by basis (yours up to 5, platform up to 4, default up to 3). */
+    stars: number;
+    /** Tooltip text for `stars`, distinct from `reason`. */
+    star_reason: string;
+}
+export interface SuggestedTimesWeeklyRating {
+    stars: number;
+    basis: SuggestedSlotBasis;
+    reason: string;
+    estimated: boolean;
 }
 export interface SuggestedSlotsResponse {
     timezone: string;
     basis: SuggestedSlotBasis;
     basis_label: string;
     slots: SuggestedSlot[];
+    /** Only present when include=weekly_ratings was passed. */
+    weekly_ratings?: SuggestedTimesWeeklyRating[];
 }
 export interface Workspace {
     id: string;
@@ -1147,6 +1214,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>;

package/dist/lib/api-client.js

@@ -116,7 +116,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 +144,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 +209,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');
     }

package/dist/lib/format.d.ts

@@ -7,6 +7,13 @@ export declare function formatLocalDateTime(value?: string | null): string;
 export declare function dashboardUrlForPost(post: Pick<Post, 'id' | 'scheduled_at'>): string;
 export declare function dashboardUrlForPosts(): string;
 export declare function dashboardUrlForPostList(posts: Array<Pick<Post, 'scheduled_at'>>): string;
+/**
+ * Renders a 1-5 star rating as filled/empty glyphs, e.g. 4 -> "★★★★☆".
+ * Appends " (est.)" for a default-basis rating, matching the dashboard's
+ * "Estimated" badge, so a thin or absent data signal reads the same way on
+ * both surfaces.
+ */
+export declare function starGlyphs(stars: unknown, estimated?: boolean): string;
 export declare function truncateText(value: string | null | undefined, max?: number): string;
 export declare function formatAccountLabel(account: Account): string;
 export declare function formatConnectedAccounts(accounts?: Account[]): string;

package/dist/lib/format.js

@@ -25,6 +25,17 @@ export function dashboardUrlForPostList(posts) {
     }
     return DASHBOARD_TABLE_URL;
 }
+/**
+ * Renders a 1-5 star rating as filled/empty glyphs, e.g. 4 -> "★★★★☆".
+ * Appends " (est.)" for a default-basis rating, matching the dashboard's
+ * "Estimated" badge, so a thin or absent data signal reads the same way on
+ * both surfaces.
+ */
+export function starGlyphs(stars, estimated = false) {
+    const n = Math.max(0, Math.min(5, Math.round(Number(stars)) || 0));
+    const glyphs = '★'.repeat(n) + '☆'.repeat(5 - n);
+    return estimated ? `${glyphs} (est.)` : glyphs;
+}
 export function truncateText(value, max = 80) {
     const text = value?.trim() || '';
     if (!text)

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.48.3";
+export declare const POSTERLY_MCP_VERSION = "0.48.5";

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.3';
+export const POSTERLY_MCP_VERSION = '0.48.5';

package/dist/tools/find-slot.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { formatDate, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
+import { formatDate, mdEmpty, mdTable, mdTitle, starGlyphs } from '../lib/format.js';
 const SUGGESTED_BASIS_LABELS = {
     yours: 'Based on your posts',
     platform: 'Popular on this platform',
@@ -7,7 +7,7 @@ const SUGGESTED_BASIS_LABELS = {
 };
 export const findSlotTool = {
     name: 'find_available_slot',
-    description: 'Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours (8am-10pm in the given timezone). Returns up to 10 slots. IMPORTANT: pass a timezone explicitly - default is America/New_York and slots will be off if the user is elsewhere. Pass workspace_id to only avoid collisions with posts in that workspace. strategy "best_engagement" (needs account_ids) ranks the next 7 days by when these accounts get the most engagement, with a reason per slot.',
+    description: 'Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours (8am-10pm in the given timezone). Returns up to 10 slots. IMPORTANT: pass a timezone explicitly - default is America/New_York and slots will be off if the user is elsewhere. Pass workspace_id to only avoid collisions with posts in that workspace. strategy "best_engagement" (needs account_ids) ranks the next 7 days by when these accounts get the most engagement, with a 1-5 star rating and a reason per slot.',
     inputSchema: z.object({
         account_ids: z
             .array(z.string())
@@ -54,9 +54,10 @@ export const findSlotTool = {
                 `Basis: ${basis}${result.timezone ? ` (${result.timezone})` : ''}`,
                 // local_time already carries the date in the requested timezone, so
                 // no separate Date column (a machine-local date could disagree).
-                mdTable(['Option', 'Local time', 'Why'], slots.map((slot, index) => [
+                mdTable(['Option', 'Local time', 'Rating', 'Why'], slots.map((slot, index) => [
                     index + 1,
                     slot.local_time,
+                    starGlyphs(slot.stars, slot.basis === 'default'),
                     slot.reason || 'n/a',
                 ])),
             ].join('\n\n');

package/dist/tools/list-brands.d.ts

@@ -16,11 +16,11 @@ export declare const listBrandsTool: {
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
         brand_id?: string | undefined;
-        view?: "accounts" | "brands" | "brand" | "profile" | undefined;
+        view?: "brand" | "accounts" | "brands" | "profile" | undefined;
     }, {
         workspace_id?: string | undefined;
         brand_id?: string | undefined;
-        view?: "accounts" | "brands" | "brand" | "profile" | undefined;
+        view?: "brand" | "accounts" | "brands" | "profile" | undefined;
     }>;
     /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
     legacySchemas: {

package/dist/tools/list-publishing-pauses.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { PosterlyClient, PublishingPauseChangeResponse, PublishingPauseState, PublishMissedResponse } from '../lib/api-client.js';
+export declare function formatPublishingPauseState(data: PublishingPauseState): string;
+export declare function formatPublishingPauseChange(data: PublishingPauseChangeResponse): string;
+export declare function formatPublishMissed(data: PublishMissedResponse): string;
+export declare const listPublishingPausesTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        workspace_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        workspace_id?: string | undefined;
+    }, {
+        workspace_id?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        workspace_id?: string;
+    }): Promise<string>;
+};

package/dist/tools/list-publishing-pauses.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+// Plain-text output shared by list_publishing_pauses and
+// manage_publishing_pause. The hosted endpoint (lib/mcp/http-tools.ts) renders
+// the same text from the same API responses; scripts/test-publishing-pause-api.ts
+// checks the two surfaces match.
+function yesNo(value) {
+    return value ? 'yes' : 'no';
+}
+function idList(ids) {
+    return Array.isArray(ids) && ids.length > 0 ? ids.join(', ') : 'none';
+}
+function scopeText(data) {
+    if (data.scope === 'brand')
+        return `brand ${data.brand_name ? `${data.brand_name} ` : ''}(${data.brand_id})`;
+    return `the workspace ${data.workspace_name ? `${data.workspace_name} ` : ''}(${data.workspace_id})`;
+}
+export function formatPublishingPauseState(data) {
+    const workspace = data.workspace;
+    const brands = Array.isArray(data.brands) ? data.brands : [];
+    const viewer = data.viewer;
+    return [
+        `Publishing pause for ${workspace.name || 'this workspace'} (${workspace.id})`,
+        `Workspace: ${workspace.paused ? `paused since ${workspace.paused_at}` : 'publishing normally'}`,
+        brands.length > 0
+            ? ['Paused brands:', ...brands.map((brand) => `- ${brand.name || 'Unnamed brand'} (${brand.id}), paused since ${brand.paused_at}`)].join('\n')
+            : 'Paused brands: none',
+        `Your role: ${viewer.role}. Pause the workspace: ${yesNo(viewer.can_pause_workspace)}. Pause a brand: ${yesNo(viewer.can_pause_brand)}. Resume and publish missed posts: ${yesNo(viewer.can_resume)}.`,
+        'While paused, nothing in that scope publishes (scheduled posts are held, Post now is refused). Pause and resume with manage_publishing_pause.',
+    ].join('\n');
+}
+export function formatPublishingPauseChange(data) {
+    if (data.requires_confirmation) {
+        return [
+            'Preview only: nothing has changed yet.',
+            data.error || '',
+            `Scope: ${scopeText(data)}`,
+            `Scheduled posts to hold: ${typeof data.scheduled_posts_to_hold === 'number' ? data.scheduled_posts_to_hold : 'unknown'}`,
+            `Already paused: ${yesNo(data.already_paused)}`,
+            'Next step: show this to the user. Only after they agree, call manage_publishing_pause again with action=pause, the same fields, and confirm=true.',
+        ].filter(Boolean).join('\n');
+    }
+    if (data.action === 'pause') {
+        const failed = data.failed_post_ids || [];
+        return [
+            `Publishing paused for ${scopeText(data)}.`,
+            `Held posts: ${data.held_count ?? 0}`,
+            failed.length > 0 ? `Posts that could not be marked as held (the publish guard still holds them): ${idList(failed)}` : '',
+            data.message || '',
+        ].filter(Boolean).join('\n');
+    }
+    const missed = data.missed_post_ids || [];
+    const failed = data.failed_post_ids || [];
+    return [
+        `Publishing resumed for ${scopeText(data)}.`,
+        `Scheduled again: ${data.resumed_count ?? 0}`,
+        `Missed their time while paused (still paused): ${missed.length}${missed.length > 0 ? ` [post IDs: ${idList(missed)}]` : ''}`,
+        `Still held by another pause: ${data.still_held_count ?? 0}`,
+        (data.disconnected_count ?? 0) > 0 ? `Still paused because the account is disconnected: ${data.disconnected_count}` : '',
+        failed.length > 0 ? `Could not be released (try resume again): ${idList(failed)}` : '',
+        missed.length > 0
+            ? 'Next step: missed posts never publish on their own. Ask the user whether to publish them now (action=publish_missed with these post_ids and confirm=true) or reschedule them.'
+            : '',
+    ].filter(Boolean).join('\n');
+}
+export function formatPublishMissed(data) {
+    return [
+        `Missed posts: ${data.started} publishing now, ${data.skipped} skipped.`,
+        data.message || '',
+    ].filter(Boolean).join('\n');
+}
+export const listPublishingPausesTool = {
+    name: 'list_publishing_pauses',
+    description: 'Is publishing paused? Shows whether the workspace is paused, which brands are paused (only brands you can see), and whether you may pause, resume, or publish missed posts. Read-only. Change it with manage_publishing_pause.',
+    inputSchema: z.object({
+        workspace_id: z.string().optional().describe('Workspace ID from whoami. Defaults to your default workspace.'),
+    }),
+    async execute(client, input) {
+        const state = await client.getPublishingPause(input.workspace_id ? { workspace_id: input.workspace_id } : undefined);
+        return formatPublishingPauseState(state);
+    },
+};

package/dist/tools/manage-publishing-pause.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { type ToolContext } from '../lib/tool-runtime.js';
+type ManagePublishingPauseInput = {
+    action: 'pause' | 'resume' | 'publish_missed';
+    workspace_id?: string;
+    brand_id?: string;
+    post_ids?: number[];
+    confirm?: boolean;
+};
+export declare const managePublishingPauseTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        action: z.ZodEnum<["pause", "resume", "publish_missed"]>;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        brand_id: z.ZodOptional<z.ZodString>;
+        post_ids: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        confirm: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        action: "pause" | "resume" | "publish_missed";
+        confirm?: boolean | undefined;
+        workspace_id?: string | undefined;
+        brand_id?: string | undefined;
+        post_ids?: number[] | undefined;
+    }, {
+        action: "pause" | "resume" | "publish_missed";
+        confirm?: boolean | undefined;
+        workspace_id?: string | undefined;
+        brand_id?: string | undefined;
+        post_ids?: number[] | undefined;
+    }>;
+    execute(client: PosterlyClient, input: ManagePublishingPauseInput, ctx: ToolContext): Promise<string>;
+};
+export {};

package/dist/tools/manage-publishing-pause.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { validateArgs } from '../lib/tool-runtime.js';
+import { formatPublishingPauseChange, formatPublishMissed } from './list-publishing-pauses.js';
+/** Same wording as EMPTY_BRAND_ID_MESSAGE in lib/publish/publishing-pause-service.ts. */
+const EMPTY_BRAND_ID_MESSAGE = 'brand_id is empty; omit it to target the whole workspace.';
+export const managePublishingPauseTool = {
+    name: 'manage_publishing_pause',
+    description: 'Pause or resume publishing for a whole workspace or one brand (check it first with list_publishing_pauses). Only act when the user asks; never pause on your own initiative. action=pause (optional brand_id; leave it out for the whole workspace): holds every scheduled post in that scope and blocks Post now until an admin resumes. Call it first without confirm to get a preview (scope and how many scheduled posts it holds), show it to the user, and only after they agree call again with confirm=true. Publisher or higher; a seat limited to some brands can only pause those brands. action=resume (optional brand_id; admin or higher): future posts are scheduled again; posts whose time passed while paused stay paused and are listed as missed. Missed posts never publish on their own. action=publish_missed (post_ids from the resume, confirm=true after the user agrees; admin or higher): publishes those missed posts now.',
+    inputSchema: z.object({
+        action: z.enum(['pause', 'resume', 'publish_missed']).describe('pause, resume, or publish_missed.'),
+        workspace_id: z.string().optional().describe('Workspace ID from whoami. Defaults to your default workspace.'),
+        brand_id: z.string().optional().describe('pause and resume: a brand ID from list_brands. Leave it out (never empty) for the whole workspace.'),
+        post_ids: z.array(z.number().int().positive()).max(500).optional().describe('publish_missed: the missed post IDs a resume returned.'),
+        confirm: z.boolean().optional().describe('pause: leave out to get a preview; true only after the user agreed. publish_missed: true after the user agreed. resume: not needed.'),
+    }),
+    async execute(client, input, ctx) {
+        // A present but empty brand_id is refused, never read as the whole
+        // workspace (same rule and wording as the API and the hosted endpoint).
+        if ((input?.action === 'pause' || input?.action === 'resume') && input && Object.prototype.hasOwnProperty.call(input, 'brand_id')) {
+            const value = input.brand_id;
+            if (value === null || (typeof value === 'string' && value.trim() === ''))
+                throw new Error(EMPTY_BRAND_ID_MESSAGE);
+        }
+        const { mode, args } = validateArgs(ctx, 'manage_publishing_pause', input);
+        const call = args;
+        const workspace = call.workspace_id ? { workspace_id: call.workspace_id } : {};
+        if (mode === 'publish_missed') {
+            if (call.confirm !== true) {
+                throw new Error('Refusing to publish missed posts without confirm=true after explicit user confirmation.');
+            }
+            const result = await client.publishMissedPausedPosts({ ...workspace, post_ids: call.post_ids || [], confirm: true });
+            return formatPublishMissed(result);
+        }
+        const brand = call.brand_id ? { brand_id: call.brand_id } : {};
+        if (mode === 'pause') {
+            const result = await client.changePublishingPause({
+                action: 'pause',
+                ...workspace,
+                ...brand,
+                ...(call.confirm === true ? { confirm: true } : {}),
+            });
+            return formatPublishingPauseChange(result);
+        }
+        const result = await client.changePublishingPause({ action: 'resume', ...workspace, ...brand });
+        return formatPublishingPauseChange(result);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.48.3",
+  "version": "0.48.5",
   "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.3",
+  "version": "0.48.5",
   "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.3",
+      "version": "0.48.5",
       "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

@@ -469,6 +469,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[];
@@ -611,6 +659,17 @@ export type SuggestedSlotBasis = 'yours' | 'platform' | 'default';
 export interface SuggestedSlot extends Slot {
   basis: SuggestedSlotBasis;
   reason: string;
+  /** 1-5; confidence-capped by basis (yours up to 5, platform up to 4, default up to 3). */
+  stars: number;
+  /** Tooltip text for `stars`, distinct from `reason`. */
+  star_reason: string;
+}
+
+export interface SuggestedTimesWeeklyRating {
+  stars: number;
+  basis: SuggestedSlotBasis;
+  reason: string;
+  estimated: boolean;
 }
 
 export interface SuggestedSlotsResponse {
@@ -618,6 +677,8 @@ export interface SuggestedSlotsResponse {
   basis: SuggestedSlotBasis;
   basis_label: string;
   slots: SuggestedSlot[];
+  /** Only present when include=weekly_ratings was passed. */
+  weekly_ratings?: SuggestedTimesWeeklyRating[];
 }
 
 export interface Workspace {
@@ -1277,6 +1338,7 @@ export class PosterlyClient {
     method: string,
     path: string,
     body?: unknown,
+    options?: { acceptConfirmationPreview?: boolean },
   ): Promise<T> {
     this.requireApiKey();
 
@@ -1309,6 +1371,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));
     }
 
@@ -1398,6 +1465,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');
   }

package/src/lib/format.ts

@@ -33,6 +33,18 @@ export function dashboardUrlForPostList(posts: Array<Pick<Post, 'scheduled_at'>>
   return DASHBOARD_TABLE_URL;
 }
 
+/**
+ * Renders a 1-5 star rating as filled/empty glyphs, e.g. 4 -> "★★★★☆".
+ * Appends " (est.)" for a default-basis rating, matching the dashboard's
+ * "Estimated" badge, so a thin or absent data signal reads the same way on
+ * both surfaces.
+ */
+export function starGlyphs(stars: unknown, estimated = false): string {
+  const n = Math.max(0, Math.min(5, Math.round(Number(stars)) || 0));
+  const glyphs = '★'.repeat(n) + '☆'.repeat(5 - n);
+  return estimated ? `${glyphs} (est.)` : glyphs;
+}
+
 export function truncateText(value: string | null | undefined, max = 80): string {
   const text = value?.trim() || '';
   if (!text) return '(empty)';

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.3';
+export const POSTERLY_MCP_VERSION = '0.48.5';

package/src/tools/find-slot.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
-import { formatDate, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
+import { formatDate, mdEmpty, mdTable, mdTitle, starGlyphs } from '../lib/format.js';
 
 const SUGGESTED_BASIS_LABELS: Record<string, string> = {
   yours: 'Based on your posts',
@@ -11,7 +11,7 @@ const SUGGESTED_BASIS_LABELS: Record<string, string> = {
 export const findSlotTool = {
   name: 'find_available_slot',
   description:
-    'Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours (8am-10pm in the given timezone). Returns up to 10 slots. IMPORTANT: pass a timezone explicitly - default is America/New_York and slots will be off if the user is elsewhere. Pass workspace_id to only avoid collisions with posts in that workspace. strategy "best_engagement" (needs account_ids) ranks the next 7 days by when these accounts get the most engagement, with a reason per slot.',
+    'Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours (8am-10pm in the given timezone). Returns up to 10 slots. IMPORTANT: pass a timezone explicitly - default is America/New_York and slots will be off if the user is elsewhere. Pass workspace_id to only avoid collisions with posts in that workspace. strategy "best_engagement" (needs account_ids) ranks the next 7 days by when these accounts get the most engagement, with a 1-5 star rating and a reason per slot.',
   inputSchema: z.object({
     account_ids: z
       .array(z.string())
@@ -69,10 +69,11 @@ export const findSlotTool = {
         // local_time already carries the date in the requested timezone, so
         // no separate Date column (a machine-local date could disagree).
         mdTable(
-          ['Option', 'Local time', 'Why'],
+          ['Option', 'Local time', 'Rating', 'Why'],
           slots.map((slot, index) => [
             index + 1,
             slot.local_time,
+            starGlyphs(slot.stars, slot.basis === 'default'),
             slot.reason || 'n/a',
           ]),
         ),

package/src/tools/list-publishing-pauses.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import type {
+  PosterlyClient,
+  PublishingPauseChangeResponse,
+  PublishingPauseState,
+  PublishMissedResponse,
+} from '../lib/api-client.js';
+
+// Plain-text output shared by list_publishing_pauses and
+// manage_publishing_pause. The hosted endpoint (lib/mcp/http-tools.ts) renders
+// the same text from the same API responses; scripts/test-publishing-pause-api.ts
+// checks the two surfaces match.
+
+function yesNo(value: unknown): string {
+  return value ? 'yes' : 'no';
+}
+
+function idList(ids: number[] | undefined): string {
+  return Array.isArray(ids) && ids.length > 0 ? ids.join(', ') : 'none';
+}
+
+function scopeText(data: { scope?: string; workspace_id?: string; brand_id?: string | null; brand_name?: string | null; workspace_name?: string | null }): string {
+  if (data.scope === 'brand') return `brand ${data.brand_name ? `${data.brand_name} ` : ''}(${data.brand_id})`;
+  return `the workspace ${data.workspace_name ? `${data.workspace_name} ` : ''}(${data.workspace_id})`;
+}
+
+export function formatPublishingPauseState(data: PublishingPauseState): string {
+  const workspace = data.workspace;
+  const brands = Array.isArray(data.brands) ? data.brands : [];
+  const viewer = data.viewer;
+  return [
+    `Publishing pause for ${workspace.name || 'this workspace'} (${workspace.id})`,
+    `Workspace: ${workspace.paused ? `paused since ${workspace.paused_at}` : 'publishing normally'}`,
+    brands.length > 0
+      ? ['Paused brands:', ...brands.map((brand) => `- ${brand.name || 'Unnamed brand'} (${brand.id}), paused since ${brand.paused_at}`)].join('\n')
+      : 'Paused brands: none',
+    `Your role: ${viewer.role}. Pause the workspace: ${yesNo(viewer.can_pause_workspace)}. Pause a brand: ${yesNo(viewer.can_pause_brand)}. Resume and publish missed posts: ${yesNo(viewer.can_resume)}.`,
+    'While paused, nothing in that scope publishes (scheduled posts are held, Post now is refused). Pause and resume with manage_publishing_pause.',
+  ].join('\n');
+}
+
+export function formatPublishingPauseChange(data: PublishingPauseChangeResponse): string {
+  if (data.requires_confirmation) {
+    return [
+      'Preview only: nothing has changed yet.',
+      data.error || '',
+      `Scope: ${scopeText(data)}`,
+      `Scheduled posts to hold: ${typeof data.scheduled_posts_to_hold === 'number' ? data.scheduled_posts_to_hold : 'unknown'}`,
+      `Already paused: ${yesNo(data.already_paused)}`,
+      'Next step: show this to the user. Only after they agree, call manage_publishing_pause again with action=pause, the same fields, and confirm=true.',
+    ].filter(Boolean).join('\n');
+  }
+
+  if (data.action === 'pause') {
+    const failed = data.failed_post_ids || [];
+    return [
+      `Publishing paused for ${scopeText(data)}.`,
+      `Held posts: ${data.held_count ?? 0}`,
+      failed.length > 0 ? `Posts that could not be marked as held (the publish guard still holds them): ${idList(failed)}` : '',
+      data.message || '',
+    ].filter(Boolean).join('\n');
+  }
+
+  const missed = data.missed_post_ids || [];
+  const failed = data.failed_post_ids || [];
+  return [
+    `Publishing resumed for ${scopeText(data)}.`,
+    `Scheduled again: ${data.resumed_count ?? 0}`,
+    `Missed their time while paused (still paused): ${missed.length}${missed.length > 0 ? ` [post IDs: ${idList(missed)}]` : ''}`,
+    `Still held by another pause: ${data.still_held_count ?? 0}`,
+    (data.disconnected_count ?? 0) > 0 ? `Still paused because the account is disconnected: ${data.disconnected_count}` : '',
+    failed.length > 0 ? `Could not be released (try resume again): ${idList(failed)}` : '',
+    missed.length > 0
+      ? 'Next step: missed posts never publish on their own. Ask the user whether to publish them now (action=publish_missed with these post_ids and confirm=true) or reschedule them.'
+      : '',
+  ].filter(Boolean).join('\n');
+}
+
+export function formatPublishMissed(data: PublishMissedResponse): string {
+  return [
+    `Missed posts: ${data.started} publishing now, ${data.skipped} skipped.`,
+    data.message || '',
+  ].filter(Boolean).join('\n');
+}
+
+export const listPublishingPausesTool = {
+  name: 'list_publishing_pauses',
+  description:
+    'Is publishing paused? Shows whether the workspace is paused, which brands are paused (only brands you can see), and whether you may pause, resume, or publish missed posts. Read-only. Change it with manage_publishing_pause.',
+  inputSchema: z.object({
+    workspace_id: z.string().optional().describe('Workspace ID from whoami. Defaults to your default workspace.'),
+  }),
+
+  async execute(client: PosterlyClient, input: { workspace_id?: string }) {
+    const state = await client.getPublishingPause(input.workspace_id ? { workspace_id: input.workspace_id } : undefined);
+    return formatPublishingPauseState(state);
+  },
+};

package/src/tools/manage-publishing-pause.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+import { formatPublishingPauseChange, formatPublishMissed } from './list-publishing-pauses.js';
+
+/** Same wording as EMPTY_BRAND_ID_MESSAGE in lib/publish/publishing-pause-service.ts. */
+const EMPTY_BRAND_ID_MESSAGE = 'brand_id is empty; omit it to target the whole workspace.';
+
+type ManagePublishingPauseInput = {
+  action: 'pause' | 'resume' | 'publish_missed';
+  workspace_id?: string;
+  brand_id?: string;
+  post_ids?: number[];
+  confirm?: boolean;
+};
+
+export const managePublishingPauseTool = {
+  name: 'manage_publishing_pause',
+  description:
+    'Pause or resume publishing for a whole workspace or one brand (check it first with list_publishing_pauses). Only act when the user asks; never pause on your own initiative. action=pause (optional brand_id; leave it out for the whole workspace): holds every scheduled post in that scope and blocks Post now until an admin resumes. Call it first without confirm to get a preview (scope and how many scheduled posts it holds), show it to the user, and only after they agree call again with confirm=true. Publisher or higher; a seat limited to some brands can only pause those brands. action=resume (optional brand_id; admin or higher): future posts are scheduled again; posts whose time passed while paused stay paused and are listed as missed. Missed posts never publish on their own. action=publish_missed (post_ids from the resume, confirm=true after the user agrees; admin or higher): publishes those missed posts now.',
+  inputSchema: z.object({
+    action: z.enum(['pause', 'resume', 'publish_missed']).describe('pause, resume, or publish_missed.'),
+    workspace_id: z.string().optional().describe('Workspace ID from whoami. Defaults to your default workspace.'),
+    brand_id: z.string().optional().describe('pause and resume: a brand ID from list_brands. Leave it out (never empty) for the whole workspace.'),
+    post_ids: z.array(z.number().int().positive()).max(500).optional().describe('publish_missed: the missed post IDs a resume returned.'),
+    confirm: z.boolean().optional().describe('pause: leave out to get a preview; true only after the user agreed. publish_missed: true after the user agreed. resume: not needed.'),
+  }),
+
+  async execute(client: PosterlyClient, input: ManagePublishingPauseInput, ctx: ToolContext) {
+    // A present but empty brand_id is refused, never read as the whole
+    // workspace (same rule and wording as the API and the hosted endpoint).
+    if ((input?.action === 'pause' || input?.action === 'resume') && input && Object.prototype.hasOwnProperty.call(input, 'brand_id')) {
+      const value = (input as { brand_id?: unknown }).brand_id;
+      if (value === null || (typeof value === 'string' && value.trim() === '')) throw new Error(EMPTY_BRAND_ID_MESSAGE);
+    }
+    const { mode, args } = validateArgs(ctx, 'manage_publishing_pause', input);
+    const call = args as ManagePublishingPauseInput;
+    const workspace = call.workspace_id ? { workspace_id: call.workspace_id } : {};
+
+    if (mode === 'publish_missed') {
+      if (call.confirm !== true) {
+        throw new Error('Refusing to publish missed posts without confirm=true after explicit user confirmation.');
+      }
+      const result = await client.publishMissedPausedPosts({ ...workspace, post_ids: call.post_ids || [], confirm: true });
+      return formatPublishMissed(result);
+    }
+
+    const brand = call.brand_id ? { brand_id: call.brand_id } : {};
+    if (mode === 'pause') {
+      const result = await client.changePublishingPause({
+        action: 'pause',
+        ...workspace,
+        ...brand,
+        ...(call.confirm === true ? { confirm: true } : {}),
+      });
+      return formatPublishingPauseChange(result);
+    }
+
+    const result = await client.changePublishingPause({ action: 'resume', ...workspace, ...brand });
+    return formatPublishingPauseChange(result);
+  },
+};

package/tool-annotations.json

@@ -8,6 +8,8 @@
     "delete_api_key",
     "list_workspace_members",
     "manage_workspace_member",
+    "list_publishing_pauses",
+    "manage_publishing_pause",
     "list_accounts",
     "disconnect_account",
     "connect_account",
@@ -68,6 +70,7 @@
     "get_signup_session",
     "whoami",
     "list_workspace_members",
+    "list_publishing_pauses",
     "list_accounts",
     "list_oauth_clients",
     "list_platforms",
@@ -108,6 +111,7 @@
     "manage_comment",
     "manage_webhook",
     "cancel_subscription",
+    "manage_publishing_pause",
     "pause_subscription",
     "downgrade_subscription"
   ],
@@ -128,6 +132,7 @@
     "get_signup_session",
     "whoami",
     "manage_workspace_member",
+    "manage_publishing_pause",
     "list_accounts",
     "disconnect_account",
     "connect_account",

package/tool-registry.json

@@ -26,7 +26,7 @@
     },
     "admin": {
       "label": "Admin",
-      "description": "API keys, OAuth clients, webhooks, and workspace members."
+      "description": "API keys, OAuth clients, webhooks, workspace members, and the publishing pause."
     },
     "billing": {
       "label": "Billing",
@@ -175,6 +175,68 @@
         }
       }
     },
+    "list_publishing_pauses": {
+      "set": "admin",
+      "label": "Publishing pause",
+      "readOnly": true,
+      "destructive": false,
+      "idempotent": true,
+      "openWorld": false,
+      "confirm": "none"
+    },
+    "manage_publishing_pause": {
+      "set": "admin",
+      "label": "Pause or resume publishing",
+      "selector": "action",
+      "actions": {
+        "pause": {
+          "label": "Pause publishing",
+          "destructive": true,
+          "idempotent": true,
+          "openWorld": false,
+          "confirm": "confirm",
+          "params": {
+            "workspace_id": {
+              "type": "string"
+            },
+            "brand_id": {
+              "type": "string"
+            }
+          }
+        },
+        "resume": {
+          "label": "Resume publishing",
+          "destructive": false,
+          "idempotent": true,
+          "openWorld": false,
+          "confirm": "none",
+          "params": {
+            "workspace_id": {
+              "type": "string"
+            },
+            "brand_id": {
+              "type": "string"
+            }
+          }
+        },
+        "publish_missed": {
+          "label": "Publish missed posts now",
+          "destructive": false,
+          "idempotent": false,
+          "openWorld": true,
+          "confirm": "confirm",
+          "params": {
+            "workspace_id": {
+              "type": "string"
+            },
+            "post_ids": {
+              "type": "array",
+              "required": true
+            }
+          }
+        }
+      }
+    },
     "list_accounts": {
       "set": "core",
       "label": "Connected accounts",