posterly-mcp-server 0.8.2 → 0.8.3

package/src/lib/api-client.ts

@@ -80,6 +80,37 @@ export interface InstagramPostSettings {
 
 export type PlatformPostSettings = Record<string, unknown>;
 
+export type CreatePostPayload = {
+  account_id?: string;
+  username?: string;
+  platform?: string;
+  caption: string;
+  scheduled_at?: string;
+  post_type?: string;
+  media_url?: string;
+  media_urls?: string[];
+  metadata?: Record<string, unknown>;
+  settings?: PlatformPostSettings;
+  reel_cover_url?: string;
+  reel_cover_method?: string;
+  reel_thumb_offset?: number;
+  workspace_id?: string;
+};
+
+export type CreatePostResponse = {
+  post: Post;
+  workspace: { id: string; name: string; is_personal: boolean; resolved_from: 'explicit' | 'account' | 'personal' };
+};
+
+export type BatchCreatePostsResponse = {
+  posts: Array<CreatePostResponse & { index: number; replayed: boolean }>;
+  errors: Array<{ index: number; status: number; error: string; validation_errors?: unknown }>;
+  total: number;
+  created: number;
+  replayed: number;
+  failed: number;
+};
+
 export interface Slot {
   time: string;
   local_time: string;
@@ -275,28 +306,14 @@ export class PosterlyClient {
     return this.request('GET', `/posts${qs ? `?${qs}` : ''}`);
   }
 
-  async createPost(data: {
-    account_id?: string;
-    username?: string;
-    platform?: string;
-    caption: string;
-    scheduled_at?: string;
-    post_type?: string;
-    media_url?: string;
-    media_urls?: string[];
-    metadata?: Record<string, unknown>;
-    settings?: PlatformPostSettings;
-    reel_cover_url?: string;
-    reel_cover_method?: string;
-    reel_thumb_offset?: number;
-    workspace_id?: string;
-  }): Promise<{
-    post: Post;
-    workspace: { id: string; name: string; is_personal: boolean; resolved_from: 'explicit' | 'account' | 'personal' };
-  }> {
+  async createPost(data: CreatePostPayload): Promise<CreatePostResponse> {
     return this.request('POST', '/posts', data);
   }
 
+  async createPostsBatch(data: { posts: CreatePostPayload[] }): Promise<BatchCreatePostsResponse> {
+    return this.request('POST', '/posts/batch', data);
+  }
+
   async getPost(id: number): Promise<{ post: Post }> {
     return this.request('GET', `/posts/${id}`);
   }

package/src/tools/create-post.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 
-const instagramSettingsSchema = z.object({
+export const instagramSettingsSchema = z.object({
   __type: z.enum(['instagram', 'instagram-standalone']).optional(),
   post_type: z.enum(['post', 'feed', 'story', 'reel', 'carousel']).optional(),
   is_trial_reel: z.boolean().optional(),
@@ -18,7 +18,7 @@ const instagramSettingsSchema = z.object({
   reel_thumb_offset: z.number().nonnegative().optional(),
 });
 
-const platformSettingsSchema = z.object({
+export const platformSettingsSchema = z.object({
   __type: z.string().optional(),
   post_type: z.string().optional(),
   content_type: z.string().optional(),
@@ -71,6 +71,88 @@ const platformSettingsSchema = z.object({
   langs: z.array(z.string()).optional(),
 }).passthrough();
 
+export const createPostInputSchema = z.object({
+  account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
+  username: z.string().optional().describe('Account username (alternative to account_id)'),
+  platform: z
+    .string()
+    .optional()
+    .describe('Platform name (required with username): instagram, twitter, linkedin, facebook, tiktok, threads, youtube, pinterest, google_business'),
+  caption: z.string().optional().describe('The post caption/text content. Ignored when `thread_posts` is provided.'),
+  scheduled_at: z
+    .string()
+    .optional()
+    .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
+  media_url: z.string().optional().describe('URL of media to attach (image or video). For threads, attaches to the lead post only.'),
+  media_urls: z
+    .array(z.string())
+    .optional()
+    .describe('Multiple media URLs for carousel posts'),
+  post_type: z
+    .string()
+    .optional()
+    .describe('Post type: text, image, video, carousel, reel, story. Auto-set to x_thread/threads_thread when `thread_posts` is provided.'),
+  thread_posts: z
+    .array(z.string())
+    .optional()
+    .describe('For X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.'),
+  instagram_settings: instagramSettingsSchema
+    .optional()
+    .describe('Instagram-specific settings: post_type (post/feed/story/reel/carousel), collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_thumb_offset.'),
+  platform_settings: platformSettingsSchema
+    .optional()
+    .describe('Platform-specific settings for the selected account. Use this for non-Instagram settings and prefer it over raw metadata.'),
+  workspace_id: z
+    .string()
+    .optional()
+    .describe('Workspace ID to assign the post to (from whoami). If omitted, uses the account\'s workspace or the caller\'s default workspace.'),
+});
+
+export type CreatePostInput = z.infer<typeof createPostInputSchema>;
+
+export function buildCreatePostPayload(input: CreatePostInput): Parameters<PosterlyClient['createPost']>[0] {
+  const { thread_posts, caption, post_type, instagram_settings, platform_settings, ...rest } = input;
+
+  if (thread_posts && thread_posts.length > 0) {
+    if (thread_posts.length < 2) {
+      throw new Error('thread_posts must contain at least 2 entries');
+    }
+    const platformHint = (input.platform || '').toLowerCase();
+    const isTwitter = platformHint === 'twitter' || platformHint === 'x';
+    const isThreads = platformHint === 'threads';
+    if (!isTwitter && !isThreads && !input.account_id) {
+      throw new Error(
+        'thread_posts requires `platform` to be "twitter" or "threads", or pass `account_id` for an X/Threads account.',
+      );
+    }
+    const arrayKey = isThreads ? 'threads_thread_posts' : 'x_thread_tweets';
+    const totalKey = isThreads ? 'threads_thread_total' : 'x_thread_total';
+    return {
+      ...rest,
+      platform: isTwitter ? 'twitter' : isThreads ? 'threads' : input.platform,
+      caption: thread_posts[0],
+      post_type: isThreads ? 'threads_thread' : 'x_thread',
+      metadata: {
+        [arrayKey]: thread_posts,
+        [totalKey]: thread_posts.length,
+      },
+    };
+  }
+
+  if (!caption) {
+    throw new Error('caption is required (or pass `thread_posts` for an X/Threads thread)');
+  }
+
+  return {
+    ...rest,
+    caption,
+    post_type,
+    ...(platform_settings || instagram_settings
+      ? { settings: { ...(instagram_settings ? { __type: 'instagram', ...instagram_settings } : {}), ...(platform_settings || {}) } }
+      : {}),
+  };
+}
+
 export const createPostTool = {
   name: 'create_post',
   description:
@@ -79,46 +161,11 @@ export const createPostTool = {
     '1. Call `whoami` at the start of any new session to confirm which workspace and user you are acting for.\n' +
     '2. Show the user a preview containing ALL of: account(s) and platform(s), final caption text, scheduled time (in the user\'s timezone), media attached (if any), and workspace name.\n' +
     '3. Get explicit confirmation from the user (e.g. "post it", "yes schedule that", "looks good") BEFORE calling this tool. Do NOT infer consent from earlier instructions like "post about X every Monday" — confirm each individual post or the entire batch.\n' +
-    '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole before calling create_post repeatedly.\n\n' +
+    '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole, then prefer `create_posts_batch` so they are created in one API request.\n\n' +
     'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace — pass workspace_id explicitly if the user has more than one workspace.\n\n' +
     'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.\n\n' +
     'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/playlist, LinkedIn document titles/mentions/video thumbnails, TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/link/title/video cover, GBP event/offer/CTA, X reply settings/polls, Threads reply controls/text attachments, Bluesky languages/alt text, and Instagram feed/story/reel/carousel/collaborators/first comments/trial Reels. `instagram_settings` remains as a backwards-compatible alias.',
-  inputSchema: z.object({
-    account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
-    username: z.string().optional().describe('Account username (alternative to account_id)'),
-    platform: z
-      .string()
-      .optional()
-      .describe('Platform name (required with username): instagram, twitter, linkedin, facebook, tiktok, threads, youtube, pinterest, google_business'),
-    caption: z.string().optional().describe('The post caption/text content. Ignored when `thread_posts` is provided.'),
-    scheduled_at: z
-      .string()
-      .optional()
-      .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
-    media_url: z.string().optional().describe('URL of media to attach (image or video). For threads, attaches to the lead post only.'),
-    media_urls: z
-      .array(z.string())
-      .optional()
-      .describe('Multiple media URLs for carousel posts'),
-    post_type: z
-      .string()
-      .optional()
-      .describe('Post type: text, image, video, carousel, reel, story. Auto-set to x_thread/threads_thread when `thread_posts` is provided.'),
-    thread_posts: z
-      .array(z.string())
-      .optional()
-      .describe('For X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.'),
-    instagram_settings: instagramSettingsSchema
-      .optional()
-      .describe('Instagram-specific settings: post_type (post/feed/story/reel/carousel), collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy, reel_cover_url, reel_thumb_offset.'),
-    platform_settings: platformSettingsSchema
-      .optional()
-      .describe('Platform-specific settings for the selected account. Use this for non-Instagram settings and prefer it over raw metadata.'),
-    workspace_id: z
-      .string()
-      .optional()
-      .describe('Workspace ID to assign the post to (from whoami). If omitted, uses the account\'s workspace or the caller\'s default workspace.'),
-  }),
+  inputSchema: createPostInputSchema,
 
   async execute(
     client: PosterlyClient,
@@ -137,46 +184,8 @@ export const createPostTool = {
       workspace_id?: string;
     }
   ) {
-    const { thread_posts, caption, post_type, instagram_settings, platform_settings, ...rest } = input;
-    let payload: Parameters<typeof client.createPost>[0];
-
-    if (thread_posts && thread_posts.length > 0) {
-      if (thread_posts.length < 2) {
-        throw new Error('thread_posts must contain at least 2 entries');
-      }
-      const platformHint = (input.platform || '').toLowerCase();
-      const isTwitter = platformHint === 'twitter' || platformHint === 'x';
-      const isThreads = platformHint === 'threads';
-      if (!isTwitter && !isThreads && !input.account_id) {
-        throw new Error(
-          'thread_posts requires `platform` to be "twitter" or "threads", or pass `account_id` for an X/Threads account.',
-        );
-      }
-      const arrayKey = isThreads ? 'threads_thread_posts' : 'x_thread_tweets';
-      const totalKey = isThreads ? 'threads_thread_total' : 'x_thread_total';
-      payload = {
-        ...rest,
-        platform: isTwitter ? 'twitter' : isThreads ? 'threads' : input.platform,
-        caption: thread_posts[0],
-        post_type: isThreads ? 'threads_thread' : 'x_thread',
-        metadata: {
-          [arrayKey]: thread_posts,
-          [totalKey]: thread_posts.length,
-        },
-      };
-    } else {
-      if (!caption) {
-        throw new Error('caption is required (or pass `thread_posts` for an X/Threads thread)');
-      }
-      payload = {
-        ...rest,
-        caption,
-        post_type,
-        ...(platform_settings || instagram_settings
-          ? { settings: { ...(instagram_settings ? { __type: 'instagram', ...instagram_settings } : {}), ...(platform_settings || {}) } }
-          : {}),
-      };
-    }
+    const payload = buildCreatePostPayload(input);
+    const { thread_posts, instagram_settings, platform_settings } = input;
 
     const result = await client.createPost(payload);
     const p = result.post as Record<string, any>;

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

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { buildCreatePostPayload, createPostInputSchema, type CreatePostInput } from './create-post.js';
+
+export const createPostsBatchTool = {
+  name: 'create_posts_batch',
+  description:
+    'Create 1-25 scheduled or immediate social posts in one API request. This is a DESTRUCTIVE WRITE that creates content on the user\'s real social accounts — once scheduled_at passes, posts may go public and cannot be un-posted.\n\n' +
+    'REQUIRED BEFORE CALLING:\n' +
+    '1. Call `whoami` at the start of any new session to confirm which workspace and user you are acting for.\n' +
+    '2. Show the user a preview of EVERY post: account/platform, final caption or thread text, scheduled time in their timezone, media, platform settings, and workspace.\n' +
+    '3. Get explicit confirmation for the whole batch before calling. Do not infer consent from an earlier content plan.\n\n' +
+    'Each item accepts the same fields as `create_post`, including `thread_posts`, `platform_settings`, `instagram_settings`, media URLs, and workspace_id. The endpoint may partially succeed; failed items are returned with their index.',
+  inputSchema: z.object({
+    posts: z
+      .array(createPostInputSchema)
+      .min(1)
+      .max(25)
+      .describe('Posts to create. Each item uses the same schema as create_post.'),
+  }),
+
+  async execute(client: PosterlyClient, input: { posts: CreatePostInput[] }) {
+    const payloads = input.posts.map((post) => buildCreatePostPayload(post));
+    const result = await client.createPostsBatch({ posts: payloads });
+
+    const lines = [
+      'Batch create completed.',
+      `• Total: ${result.total}`,
+      `• Created: ${result.created}`,
+      `• Replayed: ${result.replayed}`,
+      `• Failed: ${result.failed}`,
+    ];
+
+    for (const item of result.posts.slice(0, 25)) {
+      const post = item.post as Record<string, any>;
+      const when = post.scheduled_at ? new Date(post.scheduled_at).toLocaleString() : 'now';
+      lines.push(
+        `• [${item.index}] ID ${post.id} ${post.platform || 'unknown'} ${post.post_type || 'post'} ${post.status || 'created'} at ${when}${item.replayed ? ' (replayed)' : ''}`,
+      );
+    }
+
+    for (const error of result.errors.slice(0, 25)) {
+      lines.push(`• [${error.index}] ERROR ${error.status}: ${error.error}`);
+    }
+
+    return lines.join('\n');
+  },
+};