posterly-mcp-server 0.48.1 → 0.48.3

package/README.md

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

@@ -237,6 +237,10 @@ export type CreatePostResponse = {
         is_personal: boolean;
         resolved_from: 'explicit' | 'account' | 'personal';
     };
+    warnings?: Array<{
+        code: string;
+        message: string;
+    }>;
 };
 export type ValidatePostResponse = {
     dry_run: true;
@@ -551,6 +555,17 @@ export interface Slot {
     time: string;
     local_time: string;
 }
+export type SuggestedSlotBasis = 'yours' | 'platform' | 'default';
+export interface SuggestedSlot extends Slot {
+    basis: SuggestedSlotBasis;
+    reason: string;
+}
+export interface SuggestedSlotsResponse {
+    timezone: string;
+    basis: SuggestedSlotBasis;
+    basis_label: string;
+    slots: SuggestedSlot[];
+}
 export interface Workspace {
     id: string;
     name: string;
@@ -1360,6 +1375,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/version.d.ts

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

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

package/dist/tools/create-post.js

@@ -382,6 +382,12 @@ export const createPostTool = {
         if (ws) {
             lines.push(`• Workspace: ${ws.name} (${ws.id}) - resolved from ${ws.resolved_from}`);
         }
+        if (result.warnings && result.warnings.length > 0) {
+            lines.push('• Warnings:');
+            for (const warning of result.warnings) {
+                lines.push(`  - ${warning.message || warning.code}`);
+            }
+        }
         lines.push('', 'Next step for the AI agent: tell the user the post is in posterly, share the dashboard link above, then ask whether they want to create another post, adjust this one, or connect another account.');
         return lines.join('\n');
     },

package/dist/tools/create-posts-batch.js

@@ -54,6 +54,12 @@ export const createPostsBatchTool = {
         for (const error of result.errors.slice(0, 25)) {
             lines.push(`• [${error.index}] ERROR ${error.status}: ${error.error}`);
         }
+        for (const item of result.posts.slice(0, 25)) {
+            const warnings = item.warnings || [];
+            for (const warning of warnings) {
+                lines.push(`• [${item.index}] WARNING ${warning.message || warning.code}`);
+            }
+        }
         lines.push('', 'Next step for the AI agent: tell the user which posts were created, share the dashboard link above, and ask whether they want to review the queue, adjust anything, or create the next post.');
         return lines.join('\n');
     },

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';
+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 reason per slot.',
     inputSchema: z.object({
         account_ids: z
             .array(z.string())
@@ -17,13 +22,45 @@ 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', 'Why'], slots.map((slot, index) => [
+                    index + 1,
+                    slot.local_time,
+                    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.1",
+  "version": "0.48.3",
   "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.1",
+  "version": "0.48.3",
   "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.1",
+      "version": "0.48.3",
       "transport": {
         "type": "stdio"
       },

package/src/lib/api-client.ts

@@ -269,6 +269,7 @@ export type CreatePostPayload = {
 export type CreatePostResponse = {
   post: Post;
   workspace: { id: string; name: string; is_personal: boolean; resolved_from: 'explicit' | 'account' | 'personal' };
+  warnings?: Array<{ code: string; message: string }>;
 };
 
 export type ValidatePostResponse = {
@@ -605,6 +606,20 @@ export interface Slot {
   local_time: string;
 }
 
+export type SuggestedSlotBasis = 'yours' | 'platform' | 'default';
+
+export interface SuggestedSlot extends Slot {
+  basis: SuggestedSlotBasis;
+  reason: string;
+}
+
+export interface SuggestedSlotsResponse {
+  timezone: string;
+  basis: SuggestedSlotBasis;
+  basis_label: string;
+  slots: SuggestedSlot[];
+}
+
 export interface Workspace {
   id: string;
   name: string;
@@ -1787,6 +1802,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/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.1';
+export const POSTERLY_MCP_VERSION = '0.48.3';

package/src/tools/create-post.ts

@@ -415,6 +415,12 @@ export const createPostTool = {
     if (ws) {
       lines.push(`• Workspace: ${ws.name} (${ws.id}) - resolved from ${ws.resolved_from}`);
     }
+    if (result.warnings && result.warnings.length > 0) {
+      lines.push('• Warnings:');
+      for (const warning of result.warnings) {
+        lines.push(`  - ${warning.message || warning.code}`);
+      }
+    }
     lines.push(
       '',
       'Next step for the AI agent: tell the user the post is in posterly, share the dashboard link above, then ask whether they want to create another post, adjust this one, or connect another account.',

package/src/tools/create-posts-batch.ts

@@ -63,6 +63,13 @@ export const createPostsBatchTool = {
       lines.push(`• [${error.index}] ERROR ${error.status}: ${error.error}`);
     }
 
+    for (const item of result.posts.slice(0, 25)) {
+      const warnings = item.warnings || [];
+      for (const warning of warnings) {
+        lines.push(`• [${item.index}] WARNING ${warning.message || warning.code}`);
+      }
+    }
+
     lines.push(
       '',
       'Next step for the AI agent: tell the user which posts were created, share the dashboard link above, and ask whether they want to review the queue, adjust anything, or create the next post.',

package/src/tools/find-slot.ts

@@ -2,10 +2,16 @@ import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { formatDate, mdEmpty, mdTable, mdTitle } 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 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,41 @@ 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', 'Why'],
+          slots.map((slot, index) => [
+            index + 1,
+            slot.local_time,
+            slot.reason || 'n/a',
+          ]),
+        ),
+      ].join('\n\n');
+    }
+
     const slots = await client.findAvailableSlots(input);
 
     if (slots.length === 0) {