posterly-mcp-server 0.46.0 → 0.47.1

package/package.json

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

package/src/lib/api-client.ts

@@ -190,6 +190,7 @@ export interface ApiPostApproval {
   asset_status: ApiPostApprovalStatus;
   caption_status: ApiPostApprovalStatus;
   waiting_on: 'client' | 'team' | null;
+  pending_client_approval: boolean;
   requested_at: string | null;
   completed_at: string | null;
 }
@@ -227,6 +228,23 @@ export interface InstagramPostSettings {
   media_accessibility?: Array<{ index: number; asset_id?: string; source_url?: string; alt_text: string }>;
   reel_cover_url?: string;
   reel_thumb_offset?: number;
+  is_ai_generated?: boolean;
+  audio_id?: string;
+  caption_addon?: {
+    type?: 'none' | 'poll' | 'comment_prompt';
+    kind?: 'none' | 'poll' | 'comment_prompt';
+    options?: string[];
+    extended_duration?: boolean;
+  } | null;
+  poll_attachment?: {
+    option_a?: string;
+    option_b?: string;
+    option_c?: string;
+    option_d?: string;
+    options?: string[];
+  };
+  is_comment_prompt_used?: boolean;
+  is_poll_duration_extended?: boolean;
 }
 
 export type PlatformPostSettings = Record<string, unknown>;
@@ -1544,6 +1562,7 @@ export class PosterlyClient {
     offset?: number;
     workspace_id?: string;
     approval_status?: string;
+    approval_waiting_on?: string;
     brand_id?: string;
   }): Promise<{ posts: Post[]; total: number }> {
     const searchParams = new URLSearchParams();
@@ -1554,6 +1573,7 @@ export class PosterlyClient {
     if (params?.offset) searchParams.set('offset', String(params.offset));
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
     if (params?.approval_status) searchParams.set('approval_status', params.approval_status);
+    if (params?.approval_waiting_on) searchParams.set('approval_waiting_on', params.approval_waiting_on);
     if (params?.brand_id) searchParams.set('brand_id', params.brand_id);
 
     const qs = searchParams.toString();
@@ -1614,8 +1634,27 @@ export class PosterlyClient {
     return this.request('PATCH', `/posts/${id}`, data);
   }
 
-  async deletePost(id: number): Promise<{ deleted: boolean; id: number }> {
-    return this.request('DELETE', `/posts/${id}`);
+  async deletePost(
+    id: number,
+    options?: { confirmPublished?: boolean },
+  ): Promise<{ deleted: boolean; id: number; platform_delete?: string }> {
+    const qs = options?.confirmPublished ? '?confirm_published=true' : '';
+    return this.request('DELETE', `/posts/${id}${qs}`);
+  }
+
+  async setPostApproval(
+    id: number,
+    data: {
+      action: 'request' | 'approve' | 'request_changes' | 'reject';
+      axis?: 'asset' | 'caption';
+      note?: string;
+    },
+  ): Promise<Record<string, unknown>> {
+    return this.request('POST', `/posts/${id}/approval`, {
+      action: data.action,
+      ...(data.axis ? { axis: data.axis } : {}),
+      ...(data.note ? { note: data.note } : {}),
+    });
   }
 
   async updatePostStatus(

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

package/src/tools/create-post.ts

@@ -31,6 +31,31 @@ export const instagramSettingsSchema = z.object({
   reel_thumb_offset: z.number().nonnegative().optional(),
   is_ai_generated: z.boolean().optional().describe('Label the parent Instagram media container as AI-generated. For carousels, set on the parent only.'),
   audio_id: z.string().optional().describe('Licensed Instagram audio ID for Reels. Meta-linked Facebook Login accounts only.'),
+  caption_addon: z.union([
+    z.object({
+      type: z.enum(['none', 'poll', 'comment_prompt']).optional(),
+      kind: z.enum(['none', 'poll', 'comment_prompt']).optional(),
+      options: z.array(z.string()).max(4).optional(),
+      extended_duration: z.boolean().optional(),
+      poll_attachment: z.object({
+        option_a: z.string().optional(),
+        option_b: z.string().optional(),
+        option_c: z.string().optional(),
+        option_d: z.string().optional(),
+        options: z.array(z.string()).max(4).optional(),
+      }).optional(),
+    }),
+    z.null(),
+  ]).optional().describe('Optional Instagram caption add-on. type is none, poll, or comment_prompt. A poll needs 2 to 4 options of 1 to 25 characters (an emoji counts as one) and the caption is the question. A comment prompt uses the caption as the prompt. Facebook Login only. Not available on Stories. At most one add-on per post. Pass null or type none to clear it.'),
+  poll_attachment: z.object({
+    option_a: z.string().optional(),
+    option_b: z.string().optional(),
+    option_c: z.string().optional(),
+    option_d: z.string().optional(),
+    options: z.array(z.string()).max(4).optional(),
+  }).optional().describe('Instagram poll choices. option_a and option_b are required, option_c and option_d are optional, and option_d requires option_c. Mutually exclusive with a comment prompt. The caption is the question. Serialised JSON must be 200 characters or fewer.'),
+  is_comment_prompt_used: z.boolean().optional().describe('Set true to attach an Instagram comment prompt. The caption is the prompt. Mutually exclusive with a poll. Facebook Login only. Not available on Stories.'),
+  is_poll_duration_extended: z.boolean().optional().describe('Set true only together with a poll, to request the longer Instagram poll duration.'),
 });
 
 export const platformSettingsSchema = z.object({
@@ -124,6 +149,17 @@ export const platformSettingsSchema = z.object({
   paid_partnership: z.boolean().optional(), // X paid partnership
   is_ai_generated: z.boolean().optional(),
   audio_id: z.string().optional(),
+  caption_addon: z.union([
+    z.object({
+      type: z.enum(['none', 'poll', 'comment_prompt']).optional(),
+      options: z.array(z.string()).max(4).optional(),
+      extended_duration: z.boolean().optional(),
+    }),
+    z.null(),
+  ]).optional(),
+  poll_attachment: z.record(z.string(), z.unknown()).optional(),
+  is_comment_prompt_used: z.boolean().optional(),
+  is_poll_duration_extended: z.boolean().optional(),
   // tags (z.array of strings) also serve as Bluesky hidden discovery tags
   // AI-content disclosure (TikTok is_aigc, X made_with_ai, YouTube containsSyntheticMedia, Pinterest ai_disclosures)
   ai_generated: z.boolean().optional(),
@@ -314,7 +350,7 @@ export const createPostTool = {
     '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' +
     'MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media` with `url` first if you want to upload once and reuse the returned posterly URL across posts.\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/brandPartner, LinkedIn document titles/mentions/polls/content_call_to_action_label (including BUY_NOW and SHOP_NOW), TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/title/link/product_tags, GBP event/offer/CTA/recurrence, X reply settings/polls/paid_partnership, Threads reply controls/text attachments/ghost posts/spoilers/reply approvals/GIPHY, Telegram polls/buttons/video cover/live photo, Slack markdown/blocks, Mastodon visibility/quote/poll (media+poll allowed), and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels/is_ai_generated/audio_id. For Instagram, @username in caption is only a caption mention; `user_tags` creates native media tags and `collaborators` sends co-author invitations only when the selected Meta-linked account reports those capabilities. Call `list_platforms` with `view: "schema"` and the account ID first. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
+    'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/brandPartner, LinkedIn document titles/mentions/polls/content_call_to_action_label (including BUY_NOW and SHOP_NOW), TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/title/link/product_tags, GBP event/offer/CTA/recurrence, X reply settings/polls/paid_partnership, Threads reply controls/text attachments/ghost posts/spoilers/reply approvals/GIPHY, Telegram polls/buttons/video cover/live photo, Slack markdown/blocks, Mastodon visibility/quote/poll (media+poll allowed), and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels/is_ai_generated/audio_id/caption add-ons. Instagram caption add-ons (`caption_addon`, or `poll_attachment` / `is_comment_prompt_used`) need a Facebook Login account, a non-empty caption, and a feed photo, Reel, or carousel parent. Stories are rejected. A poll and a comment prompt cannot be combined. For Instagram, @username in caption is only a caption mention; `user_tags` creates native media tags and `collaborators` sends co-author invitations only when the selected Meta-linked account reports those capabilities. Call `list_platforms` with `view: "schema"` and the account ID first. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
     'TIKTOK MEDIA: TikTok supports a single video or a photo slideshow of 1 to 35 images, never multiple videos. Image media auto-detects as a slideshow, so you usually do not set post_type or media_type for photos and every image is posted. Pass `platform_settings.media_type: "PHOTO"` to force a slideshow explicitly.',
   inputSchema: createPostInputSchema,
 
@@ -363,6 +399,16 @@ export const createPostTool = {
     if (instagram_settings?.first_comment) {
       lines.push('• Instagram first comment: yes');
     }
+    const captionAddonType = instagram_settings?.caption_addon && typeof instagram_settings.caption_addon === 'object'
+      ? instagram_settings.caption_addon.type || instagram_settings.caption_addon.kind
+      : null;
+    if (captionAddonType && captionAddonType !== 'none') {
+      lines.push(`• Instagram caption add-on: ${captionAddonType}`);
+    } else if (instagram_settings?.is_comment_prompt_used) {
+      lines.push('• Instagram caption add-on: comment_prompt');
+    } else if (instagram_settings?.poll_attachment) {
+      lines.push('• Instagram caption add-on: poll');
+    }
     if (platform_settings) {
       lines.push('• Platform settings: yes');
     }

package/src/tools/delete-post.ts

@@ -6,6 +6,7 @@ import { previewThenConfirm, validateArgs, type ToolContext } from '../lib/tool-
 type DeletePostInput = {
   post_id?: number;
   group_id?: string;
+  confirm_published?: boolean;
   confirm?: boolean;
   preview_id?: string;
 };
@@ -13,10 +14,14 @@ type DeletePostInput = {
 export const deletePostTool = {
   name: 'delete_post',
   description:
-    'Delete posts. DESTRUCTIVE and IRREVERSIBLE: deleted posts and captions cannot be recovered, and published or currently publishing posts are never deleted. post_id: delete one scheduled or draft post; fetch it with `get_post` first, show the user what will be deleted (caption, account, scheduled time), and pass confirm=true only after explicit confirmation ("yes delete it", "remove it"). group_id: delete every draft, scheduled, failed, or paused post matching a caller-defined group_id, post_group_id, api_group_id, or release_id; preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id. Never delete several posts one by one without listing each and confirming the full list.',
+    'Delete posts. DESTRUCTIVE and IRREVERSIBLE: deleted posts and captions cannot be recovered. post_id: delete one post; fetch it with `get_post` first, show the user what will be deleted (caption, account, scheduled time), and pass confirm=true only after explicit confirmation ("yes delete it", "remove it"). A post that is currently publishing is never deleted. A published post is taken down only when the user also explicitly confirms the live removal and you pass confirm_published=true. Instagram and Facebook are attempted when the stored id and token allow it. Every other platform, or a live URL with no id, returns platform_delete_unsupported and the posterly row is kept. A published post with no live URL and no platform id is removed from posterly only. group_id: delete every draft, scheduled, failed, or paused post matching a caller-defined group_id, post_group_id, api_group_id, or release_id. A group delete never removes published posts. Preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id. Never delete several posts one by one without listing each and confirming the full list.',
   inputSchema: z.object({
     post_id: z.number().optional().describe('Delete this one post.'),
-    group_id: z.string().min(1).max(160).optional().describe('Delete every unpublished post in this group or release instead.'),
+    group_id: z.string().min(1).max(160).optional().describe('Delete every unpublished post in this group or release instead. Never deletes published posts.'),
+    confirm_published: z
+      .boolean()
+      .optional()
+      .describe('With post_id only. True only after the user explicitly confirms taking a live Instagram or Facebook post down. Without it, a published post is refused and kept.'),
     confirm: z
       .boolean()
       .optional()
@@ -44,7 +49,7 @@ export const deletePostTool = {
         // GET /api/v1/posts has no group filter, so the preview says in plain
         // words which posts match instead of listing them.
         describe: async () => [
-          `Deletes every draft, scheduled, failed, or paused post whose group_id, post_group_id, api_group_id, or release_id is ${code(args.group_id)}. Published posts are never deleted. This cannot be undone.`,
+          `Deletes every draft, scheduled, failed, or paused post whose group_id, post_group_id, api_group_id, or release_id is ${code(args.group_id)}. A group delete never removes published posts. This cannot be undone.`,
           'To see the posts first, call list_posts and check each post\'s group or release ID.',
         ].join('\n\n'),
         run: async () => {
@@ -53,17 +58,21 @@ export const deletePostTool = {
         },
       });
     }
-    return deleteOne(client, args as { post_id: number; confirm?: boolean });
+    return deleteOne(client, args as { post_id: number; confirm?: boolean; confirm_published?: boolean });
   },
 };
 
-async function deleteOne(client: PosterlyClient, input: { post_id: number; confirm?: boolean }): Promise<string> {
+async function deleteOne(
+  client: PosterlyClient,
+  input: { post_id: number; confirm?: boolean; confirm_published?: boolean },
+): Promise<string> {
   if (input.confirm !== true) {
     throw new Error('Refusing to delete post without confirm=true after explicit user confirmation.');
   }
-  const result = await client.deletePost(input.post_id);
+  const result = await client.deletePost(input.post_id, { confirmPublished: input.confirm_published === true });
+  const platformDelete = result.platform_delete ? ` Platform delete: ${result.platform_delete}.` : '';
   return [
-    `Post #${result.id} deleted successfully.`,
+    `Post #${result.id} deleted successfully.${platformDelete}`,
     'It has been removed from the posterly queue.',
     `View queue in posterly: ${dashboardUrlForPosts()}`,
     '',

package/src/tools/list-analytics.ts

@@ -29,7 +29,7 @@ type ListAnalyticsInput = {
 export const listAnalyticsTool = {
   name: 'list_analytics',
   description:
-    'Analytics for connected social accounts (Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads). view=accounts (account_id): daily snapshots and a period summary with platform-native display_metrics labels. view=posts (account_id): per-post likes, comments/replies, reach, impressions/views, saves, shares, reposts, quotes, plays, clicks, and watch time, most recent first, with limit/offset. view=insights: per-post feedback insights with a performance tier (great/good/mixed/poor), diagnosis, next action, and baseline, filtered by account_id, post_id, or checkpoint (1h, 6h, 24h, 72h, 7d); read-only, Pro plan or higher. presentation (accounts and posts): compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
+    'Analytics for connected social accounts (Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads). view=accounts (account_id): daily snapshots and a period summary with platform-native display_metrics labels. Google Business Profile account analytics includes Calls, Website clicks, and Directions along with Profile Views, Search Views, Maps Views, Customer Actions, and Posts. view=posts (account_id): per-post likes, comments/replies, reach, impressions/views, saves, shares, reposts, quotes, plays, clicks, and watch time, most recent first, with limit/offset. view=insights: per-post feedback insights with a performance tier (great/good/mixed/poor), diagnosis, next action, and baseline, filtered by account_id, post_id, or checkpoint (1h, 6h, 24h, 72h, 7d); read-only, Pro plan or higher. presentation (accounts and posts): compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
   inputSchema: z.object({
     view: z.enum(['accounts', 'posts', 'insights']).describe('accounts, posts, or insights.'),
     account_id: z
@@ -194,6 +194,9 @@ function accountMetricRows(summary: AccountAnalyticsSummary, platform: string):
       ['Search Views', formatNumber(metrics.search_views ?? summary.total_reach)],
       ['Maps Views', formatNumber(metrics.maps_views ?? summary.total_profile_views)],
       ['Customer Actions', formatNumber(metrics.customer_actions ?? summary.total_accounts_engaged)],
+      ['Calls', formatNumber(metrics.call_clicks ?? summary.total_call_clicks)],
+      ['Directions', formatNumber(metrics.direction_requests ?? summary.total_direction_requests)],
+      ['Website clicks', formatNumber(metrics.website_clicks ?? summary.total_website_clicks)],
       ['Posts', formatNumber(metrics.posts ?? summary.current_media_count)],
     ];
   }

package/src/tools/list-posts.ts

@@ -6,7 +6,7 @@ import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/
 export const listPostsTool = {
   name: 'list_posts',
   description:
-    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, or brand_id. Returns posts in your workspaces, teammates\' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to.',
+    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, approval_waiting_on, or brand_id. approval_waiting_on=client is the same queue as approval_status=pending_client. Each post includes approval.pending_client_approval. Returns posts in your workspaces, teammates\' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to.',
   inputSchema: z.object({
     status: z
       .string()
@@ -34,6 +34,10 @@ export const listPostsTool = {
       .enum(['none', 'pending_client', 'approved', 'changes_requested', 'rejected'])
       .optional()
       .describe('Filter by client review approval status. pending_client means the post is waiting on the client.'),
+    approval_waiting_on: z
+      .enum(['client', 'team'])
+      .optional()
+      .describe('client: approval_status pending_client. team: changes_requested or rejected. Conflicts with a non-overlapping approval_status.'),
     brand_id: z
       .string()
       .optional()
@@ -49,6 +53,7 @@ export const listPostsTool = {
       limit?: number;
       workspace_id?: string;
       approval_status?: string;
+      approval_waiting_on?: 'client' | 'team';
       brand_id?: string;
     }
   ) {

package/src/tools/update-post.ts

@@ -32,6 +32,31 @@ const instagramSettingsSchema = z.object({
   reel_thumb_offset: z.number().nonnegative().optional(),
   is_ai_generated: z.boolean().optional().describe('Label the parent Instagram media container as AI-generated. For carousels, set on the parent only.'),
   audio_id: z.string().optional().describe('Licensed Instagram audio ID for Reels. Meta-linked Facebook Login accounts only.'),
+  caption_addon: z.union([
+    z.object({
+      type: z.enum(['none', 'poll', 'comment_prompt']).optional(),
+      kind: z.enum(['none', 'poll', 'comment_prompt']).optional(),
+      options: z.array(z.string()).max(4).optional(),
+      extended_duration: z.boolean().optional(),
+      poll_attachment: z.object({
+        option_a: z.string().optional(),
+        option_b: z.string().optional(),
+        option_c: z.string().optional(),
+        option_d: z.string().optional(),
+        options: z.array(z.string()).max(4).optional(),
+      }).optional(),
+    }),
+    z.null(),
+  ]).optional().describe('Optional Instagram caption add-on. type is none, poll, or comment_prompt. A poll needs 2 to 4 options of 1 to 25 characters (an emoji counts as one) and the caption is the question. A comment prompt uses the caption as the prompt. Facebook Login only. Not available on Stories. At most one add-on per post. Pass null or type none to clear it.'),
+  poll_attachment: z.object({
+    option_a: z.string().optional(),
+    option_b: z.string().optional(),
+    option_c: z.string().optional(),
+    option_d: z.string().optional(),
+    options: z.array(z.string()).max(4).optional(),
+  }).optional().describe('Instagram poll choices. option_a and option_b are required, option_c and option_d are optional, and option_d requires option_c. Mutually exclusive with a comment prompt. The caption is the question. Serialised JSON must be 200 characters or fewer.'),
+  is_comment_prompt_used: z.boolean().optional().describe('Set true to attach an Instagram comment prompt. The caption is the prompt. Mutually exclusive with a poll. Facebook Login only. Not available on Stories.'),
+  is_poll_duration_extended: z.boolean().optional().describe('Set true only together with a poll, to request the longer Instagram poll duration.'),
 });
 
 const platformSettingsSchema = z.object({
@@ -108,6 +133,17 @@ const platformSettingsSchema = z.object({
   paid_partnership: z.boolean().optional(),
   is_ai_generated: z.boolean().optional(),
   audio_id: z.string().optional(),
+  caption_addon: z.union([
+    z.object({
+      type: z.enum(['none', 'poll', 'comment_prompt']).optional(),
+      options: z.array(z.string()).max(4).optional(),
+      extended_duration: z.boolean().optional(),
+    }),
+    z.null(),
+  ]).optional(),
+  poll_attachment: z.record(z.string(), z.unknown()).optional(),
+  is_comment_prompt_used: z.boolean().optional(),
+  is_poll_duration_extended: z.boolean().optional(),
   ai_generated: z.boolean().optional(),
 }).passthrough();
 
@@ -127,12 +163,15 @@ type UpdatePostInput = EditInput & {
   status?: 'scheduled' | 'paused' | 'draft';
   release_id?: string;
   group_id?: string;
+  approval_action?: 'request' | 'approve' | 'request_changes' | 'reject';
+  approval_axis?: 'asset' | 'caption';
+  approval_note?: string;
 };
 
 export const updatePostTool = {
   name: 'update_post',
   description:
-    'Change a scheduled or draft post. DESTRUCTIVE WRITE. Edit (default): caption, media, schedule, post_type, or settings; overwrites the existing post; cannot edit published or currently publishing posts; if a client has already approved the post, a caption edit reopens caption approval, a media or thumbnail edit reopens asset approval, and a reschedule, account change or settings change reopens both. status (scheduled, paused, or draft, with scheduled_at when scheduling a draft): pause, resume, or move back to draft; send it on its own. release_id (with optional group_id): set or repair external release/group IDs; send it on its own.\n\n' +
+    'Change a scheduled or draft post. DESTRUCTIVE WRITE. Edit (default): caption, media, schedule, post_type, or settings; overwrites the existing post; cannot edit published or currently publishing posts; if a client has already approved the post, a caption edit reopens caption approval, a media or thumbnail edit reopens asset approval, and a reschedule, account change or settings change reopens both. status (scheduled, paused, or draft, with scheduled_at when scheduling a draft): pause, resume, or move back to draft; send it on its own. release_id (with optional group_id): set or repair external release/group IDs; send it on its own. approval_action (request, approve, request_changes, or reject): change client approval. Only a workspace owner or admin may do this. The actor is the API key user, never a brand guest. request emails the brand reviewers. approve, request_changes, and reject are team-side decisions. request_changes needs approval_note. Optional approval_axis is asset or caption; omit it for both. Send approval_action on its own.\n\n' +
     'REQUIRED BEFORE CALLING: Show the user a side-by-side of the CURRENT post (caption, scheduled time, media, status) and the PROPOSED change, and get explicit confirmation ("yes update it", "apply those changes") before calling. Do not auto-edit posts based on a general instruction - each change needs its own confirmation.',
   inputSchema: z.object({
     post_id: z.number().describe('The post ID to update'),
@@ -170,6 +209,18 @@ export const updatePostTool = {
       .optional()
       .describe('Set an external release ID instead of editing the post. Send with post_id and optional group_id only.'),
     group_id: z.string().min(1).max(160).optional().describe('With release_id only: an external group/campaign ID.'),
+    approval_action: z
+      .enum(['request', 'approve', 'request_changes', 'reject'])
+      .optional()
+      .describe('Change client approval instead of editing the post. Owner or admin only. The actor is the API key user, never a brand guest. Send on its own.'),
+    approval_axis: z
+      .enum(['asset', 'caption'])
+      .optional()
+      .describe('With approval_action approve, request_changes, or reject: which axis to decide. Omit for both. Not allowed with request.'),
+    approval_note: z
+      .string()
+      .optional()
+      .describe('Note stored with the approval change. Required for request_changes.'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation of the proposed change.'),
   }),
 
@@ -193,6 +244,15 @@ export const updatePostTool = {
     const { mode, args } = validateArgs(ctx, 'update_post', input);
     if (mode === 'status') return updateStatus(client, args as { post_id: number; status: 'scheduled' | 'paused' | 'draft'; scheduled_at?: string; confirm: boolean });
     if (mode === 'release_id') return updateReleaseId(client, args as { post_id: number; release_id: string; group_id?: string; confirm: true });
+    if (mode === 'approval') {
+      return updateApproval(client, args as {
+        post_id: number;
+        approval_action: 'request' | 'approve' | 'request_changes' | 'reject';
+        approval_axis?: 'asset' | 'caption';
+        approval_note?: string;
+        confirm: true;
+      });
+    }
     return editPost(client, args as EditInput);
   },
 };
@@ -241,6 +301,27 @@ async function updateStatus(
   return `Post #${input.post_id} status changed from ${transition.old_status || 'unknown'} to ${transition.new_status || input.status}.`;
 }
 
+async function updateApproval(
+  client: PosterlyClient,
+  input: {
+    post_id: number;
+    approval_action: 'request' | 'approve' | 'request_changes' | 'reject';
+    approval_axis?: 'asset' | 'caption';
+    approval_note?: string;
+    confirm: true;
+  },
+): Promise<string> {
+  if (input.confirm !== true) {
+    throw new Error('Refusing to change client approval without confirm=true after explicit user confirmation. Only a workspace owner or admin can do this, and the actor is the API key user, never a brand guest.');
+  }
+  const result = await client.setPostApproval(input.post_id, {
+    action: input.approval_action,
+    axis: input.approval_axis,
+    note: input.approval_note,
+  });
+  return JSON.stringify(result, null, 2);
+}
+
 async function updateReleaseId(
   client: PosterlyClient,
   input: { post_id: number; release_id: string; group_id?: string; confirm: true },

package/tool-registry.json

@@ -736,6 +736,43 @@
               "type": "string"
             }
           }
+        },
+        "approval": {
+          "label": "Request, approve, request changes, or reject client review",
+          "destructive": true,
+          "idempotent": true,
+          "openWorld": false,
+          "confirm": "confirm",
+          "when": [
+            "approval_action"
+          ],
+          "params": {
+            "post_id": {
+              "type": "integer",
+              "min": 1,
+              "required": true
+            },
+            "approval_action": {
+              "type": "string",
+              "enum": [
+                "request",
+                "approve",
+                "request_changes",
+                "reject"
+              ],
+              "required": true
+            },
+            "approval_axis": {
+              "type": "string",
+              "enum": [
+                "asset",
+                "caption"
+              ]
+            },
+            "approval_note": {
+              "type": "string"
+            }
+          }
         }
       }
     },
@@ -760,6 +797,9 @@
               "type": "integer",
               "min": 1,
               "required": true
+            },
+            "confirm_published": {
+              "type": "boolean"
             }
           }
         },