posterly-mcp-server 0.48.2 → 0.48.4

package/README.md

@@ -123,7 +123,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.48.2` 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.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.
 
 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.
 

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

@@ -555,6 +555,29 @@ export interface Slot {
     time: string;
     local_time: string;
 }
+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;
     name: string;
@@ -1364,6 +1387,13 @@ export declare class PosterlyClient {
         count?: number;
         workspace_id?: string;
     }): Promise<Slot[]>;
+    /** Best times by engagement for the given accounts (GET /slots/suggested). */
+    findSuggestedSlots(params: {
+        account_ids: string[];
+        timezone?: string;
+        count?: number;
+        workspace_id?: string;
+    }): Promise<SuggestedSlotsResponse>;
     getAccountAnalytics(params: {
         account_id: number;
         from?: string;

package/dist/lib/api-client.js

@@ -452,6 +452,18 @@ export class PosterlyClient {
         const data = await this.request('GET', `/slots/next${qs ? `?${qs}` : ''}`);
         return data.slots;
     }
+    /** Best times by engagement for the given accounts (GET /slots/suggested). */
+    async findSuggestedSlots(params) {
+        const searchParams = new URLSearchParams();
+        searchParams.set('account_ids', params.account_ids.join(','));
+        if (params.timezone)
+            searchParams.set('timezone', params.timezone);
+        if (params.count)
+            searchParams.set('count', String(params.count));
+        if (params.workspace_id)
+            searchParams.set('workspace_id', params.workspace_id);
+        return this.request('GET', `/slots/suggested?${searchParams.toString()}`);
+    }
     async getAccountAnalytics(params) {
         const searchParams = new URLSearchParams();
         searchParams.set('account_id', String(params.account_id));

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.2";
+export declare const POSTERLY_MCP_VERSION = "0.48.4";

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

package/dist/tools/find-slot.d.ts

@@ -8,21 +8,25 @@ export declare const findSlotTool: {
         timezone: z.ZodOptional<z.ZodString>;
         count: z.ZodOptional<z.ZodNumber>;
         workspace_id: z.ZodOptional<z.ZodString>;
+        strategy: z.ZodOptional<z.ZodEnum<["next_free", "best_engagement"]>>;
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
         account_ids?: string[] | undefined;
         timezone?: string | undefined;
         count?: number | undefined;
+        strategy?: "next_free" | "best_engagement" | undefined;
     }, {
         workspace_id?: string | undefined;
         account_ids?: string[] | undefined;
         timezone?: string | undefined;
         count?: number | undefined;
+        strategy?: "next_free" | "best_engagement" | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         account_ids?: string[];
         timezone?: string;
         count?: number;
         workspace_id?: string;
+        strategy?: "next_free" | "best_engagement";
     }): Promise<string>;
 };

package/dist/tools/find-slot.js

@@ -1,8 +1,13 @@
 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',
+    default: 'Good default',
+};
 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.',
+    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())
@@ -17,13 +22,46 @@ export const findSlotTool = {
             .min(1)
             .max(10)
             .optional()
-            .describe('Number of slots to return (default 5, max 10)'),
+            .describe('Number of slots to return (max 10). Default 5 for next_free, 3 for best_engagement.'),
         workspace_id: z
             .string()
             .optional()
             .describe('Scope slot-finding to a single workspace (get IDs via whoami).'),
+        strategy: z
+            .enum(['next_free', 'best_engagement'])
+            .optional()
+            .describe('next_free (default): earliest free slots. best_engagement: best times by engagement (requires account_ids).'),
     }),
     async execute(client, input) {
+        if (input.strategy === 'best_engagement') {
+            const accountIds = (input.account_ids || []).filter(Boolean);
+            if (accountIds.length === 0) {
+                throw new Error('strategy "best_engagement" needs account_ids (get them from list_accounts).');
+            }
+            const result = await client.findSuggestedSlots({
+                account_ids: accountIds,
+                timezone: input.timezone,
+                count: input.count,
+                workspace_id: input.workspace_id,
+            });
+            const slots = Array.isArray(result.slots) ? result.slots : [];
+            if (slots.length === 0) {
+                return mdEmpty('suggested slots', 'No suggested slots are free in the next 7 days.');
+            }
+            const basis = result.basis_label || SUGGESTED_BASIS_LABELS[result.basis] || 'Good default';
+            return [
+                mdTitle(`Best times to post (${slots.length})`),
+                `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', 'Rating', 'Why'], slots.map((slot, index) => [
+                    index + 1,
+                    slot.local_time,
+                    starGlyphs(slot.stars, slot.basis === 'default'),
+                    slot.reason || 'n/a',
+                ])),
+            ].join('\n\n');
+        }
         const slots = await client.findAvailableSlots(input);
         if (slots.length === 0) {
             return mdEmpty('available slots', 'No available posting slots were found in the next 14 days.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.48.2",
+  "version": "0.48.4",
   "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.2",
+  "version": "0.48.4",
   "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.2",
+      "version": "0.48.4",
       "transport": {
         "type": "stdio"
       },

package/src/lib/api-client.ts

@@ -606,6 +606,33 @@ export interface Slot {
   local_time: string;
 }
 
+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;
   name: string;
@@ -1788,6 +1815,21 @@ export class PosterlyClient {
     return data.slots;
   }
 
+  /** Best times by engagement for the given accounts (GET /slots/suggested). */
+  async findSuggestedSlots(params: {
+    account_ids: string[];
+    timezone?: string;
+    count?: number;
+    workspace_id?: string;
+  }): Promise<SuggestedSlotsResponse> {
+    const searchParams = new URLSearchParams();
+    searchParams.set('account_ids', params.account_ids.join(','));
+    if (params.timezone) searchParams.set('timezone', params.timezone);
+    if (params.count) searchParams.set('count', String(params.count));
+    if (params.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    return this.request<SuggestedSlotsResponse>('GET', `/slots/suggested?${searchParams.toString()}`);
+  }
+
   async getAccountAnalytics(params: {
     account_id: number;
     from?: string;

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

package/src/tools/find-slot.ts

@@ -1,11 +1,17 @@
 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',
+  platform: 'Popular on this platform',
+  default: 'Good default',
+};
 
 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.',
+    '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())
@@ -20,11 +26,15 @@ export const findSlotTool = {
       .min(1)
       .max(10)
       .optional()
-      .describe('Number of slots to return (default 5, max 10)'),
+      .describe('Number of slots to return (max 10). Default 5 for next_free, 3 for best_engagement.'),
     workspace_id: z
       .string()
       .optional()
       .describe('Scope slot-finding to a single workspace (get IDs via whoami).'),
+    strategy: z
+      .enum(['next_free', 'best_engagement'])
+      .optional()
+      .describe('next_free (default): earliest free slots. best_engagement: best times by engagement (requires account_ids).'),
   }),
 
   async execute(
@@ -34,8 +44,42 @@ export const findSlotTool = {
       timezone?: string;
       count?: number;
       workspace_id?: string;
+      strategy?: 'next_free' | 'best_engagement';
     }
   ) {
+    if (input.strategy === 'best_engagement') {
+      const accountIds = (input.account_ids || []).filter(Boolean);
+      if (accountIds.length === 0) {
+        throw new Error('strategy "best_engagement" needs account_ids (get them from list_accounts).');
+      }
+      const result = await client.findSuggestedSlots({
+        account_ids: accountIds,
+        timezone: input.timezone,
+        count: input.count,
+        workspace_id: input.workspace_id,
+      });
+      const slots = Array.isArray(result.slots) ? result.slots : [];
+      if (slots.length === 0) {
+        return mdEmpty('suggested slots', 'No suggested slots are free in the next 7 days.');
+      }
+      const basis = result.basis_label || SUGGESTED_BASIS_LABELS[result.basis] || 'Good default';
+      return [
+        mdTitle(`Best times to post (${slots.length})`),
+        `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', 'Rating', 'Why'],
+          slots.map((slot, index) => [
+            index + 1,
+            slot.local_time,
+            starGlyphs(slot.stars, slot.basis === 'default'),
+            slot.reason || 'n/a',
+          ]),
+        ),
+      ].join('\n\n');
+    }
+
     const slots = await client.findAvailableSlots(input);
 
     if (slots.length === 0) {