posterly-mcp-server 0.8.2 → 0.19.0

package/src/tools/create-post.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.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 +19,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 +72,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
+    .enum(SUPPORTED_PLATFORM_INPUTS)
+    .optional()
+    .describe(`Platform name (required with username). Supported: ${SUPPORTED_PLATFORM_IDS.join(', ')}. Aliases such as x, gmb, and instagram-standalone are accepted.`),
+  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,104 +162,18 @@ 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.'),
-  }),
+    '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 post_type (image/video/carousel), board (from pinterest.boards helper), title, link, and cover_image_url (video Pins), 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: createPostInputSchema,
 
   async execute(
     client: PosterlyClient,
-    input: {
-      account_id?: string;
-      username?: string;
-      platform?: string;
-      caption?: string;
-      scheduled_at?: string;
-      media_url?: string;
-      media_urls?: string[];
-      post_type?: string;
-      thread_posts?: string[];
-      instagram_settings?: z.infer<typeof instagramSettingsSchema>;
-      platform_settings?: z.infer<typeof platformSettingsSchema>;
-      workspace_id?: string;
-    }
+    input: CreatePostInput,
   ) {
-    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');
+  },
+};

package/src/tools/create-signed-upload.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const createSignedUploadTool = {
+  name: 'create_signed_upload',
+  description:
+    'Create a signed direct-upload URL for a larger image or video. Upload the binary to upload_url, then use public_url with create_post.',
+  inputSchema: z.object({
+    filename: z.string().describe('Filename with extension, e.g. launch-video.mp4'),
+    content_type: z.string().describe('MIME type, e.g. video/mp4'),
+    size: z.number().int().positive().describe('File size in bytes'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { filename: string; content_type: string; size: number },
+  ) {
+    const signed = await client.getSignedUploadUrl(input.filename, input.content_type, input.size);
+    return [
+      'Signed upload created.',
+      `• Upload URL: ${signed.upload_url}`,
+      `• Token: ${signed.token}`,
+      `• Storage path: ${signed.path}`,
+      `• Public URL after upload: ${signed.public_url}`,
+    ].join('\n');
+  },
+};

package/src/tools/create-webhook.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { webhookEventSchema } from './webhook-events.js';
+
+export const createWebhookTool = {
+  name: 'create_webhook',
+  description:
+    'Create a webhook subscription for post/account/analytics events. WRITE WITH OUTBOUND SIDE EFFECTS: show the user the target URL, workspace, events, and active state, then get explicit confirmation before calling. The response includes the signing secret once.',
+  inputSchema: z.object({
+    url: z.string().url().describe('HTTPS webhook endpoint URL. Localhost HTTP is allowed by the API for development.'),
+    events: z.array(webhookEventSchema).optional().describe('Events to deliver. Defaults to core post lifecycle events.'),
+    workspace_id: z.string().optional().describe('Optional workspace filter. Omit for all workspaces owned by the API key user.'),
+    description: z.string().max(240).optional(),
+    is_active: z.boolean().optional().describe('Defaults to true.'),
+    confirm: z.literal(true).describe('Must be true after the user explicitly confirms webhook creation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      url: string;
+      events?: string[];
+      workspace_id?: string;
+      description?: string;
+      is_active?: boolean;
+      confirm: true;
+    },
+  ) {
+    const { confirm: _confirm, ...payload } = input;
+    const result = await client.createWebhook(payload);
+    const secret = result.secret ? `\nSigning secret: ${result.secret}` : '';
+    return `Webhook created: ${result.webhook.id}\nURL: ${result.webhook.url}\nEvents: ${result.webhook.events.join(', ')}${secret}`;
+  },
+};
+

package/src/tools/delete-google-business-review-reply.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const deleteGoogleBusinessReviewReplyTool = {
+  name: 'delete_google_business_review_reply',
+  description:
+    'Delete the owner reply from a Google Business Profile review. DESTRUCTIVE: confirm the review and location with the user, then pass confirm=true only after explicit confirmation.',
+  inputSchema: z.object({
+    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    account_id: z.number().int().positive().optional().describe('Google Business account ID from list_accounts.'),
+    location_id: z.string().optional().describe('Google Business location/platform_user_id.'),
+    review_name: z.string().min(1).describe('Full Google review resource name.'),
+    confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      workspace_id?: string;
+      account_id?: number;
+      location_id?: string;
+      review_name: string;
+      confirm: true;
+    },
+  ) {
+    const { confirm: _confirm, ...payload } = input;
+    const result = await client.deleteGoogleBusinessReviewReply(payload);
+    return result.message || 'Google Business review reply deleted successfully.';
+  },
+};

package/src/tools/delete-oauth-client.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const deleteOAuthClientTool = {
+  name: 'delete_oauth_client',
+  description:
+    'Delete a self-serve OAuth developer client. DESTRUCTIVE: prevents new authorizations for that client_id; existing access tokens remain revocable as API keys.',
+  inputSchema: z.object({
+    client_id: z.string().min(1),
+    confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      client_id: string;
+      confirm: true;
+    },
+  ) {
+    const result = await client.deleteOAuthClient(input.client_id);
+    return `OAuth client deleted: ${result.client_id}`;
+  },
+};

package/src/tools/delete-post-group.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const deletePostGroupTool = {
+  name: 'delete_post_group',
+  description:
+    'Delete every draft/scheduled/failed/paused post matching a caller-defined group_id, post_group_id, api_group_id, or release_id. DESTRUCTIVE: inspect the group first, list the affected posts, and pass confirm=true only after explicit confirmation.',
+  inputSchema: z.object({
+    group_id: z.string().min(1).max(160).describe('Group/release ID to delete.'),
+    confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(client: PosterlyClient, input: { group_id: string; confirm: true }) {
+    const result = await client.deletePostGroup(input.group_id);
+    return JSON.stringify(result, null, 2);
+  },
+};

package/src/tools/delete-webhook.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const deleteWebhookTool = {
+  name: 'delete_webhook',
+  description:
+    'Delete a webhook subscription. DESTRUCTIVE: list the webhook first, show the user its URL/events/workspace, and get explicit confirmation before calling.',
+  inputSchema: z.object({
+    webhook_id: z.string().describe('Webhook ID from list_webhooks.'),
+    confirm: z.literal(true).describe('Must be true after the user explicitly confirms webhook deletion.'),
+  }),
+
+  async execute(client: PosterlyClient, input: { webhook_id: string; confirm: true }) {
+    const result = await client.deleteWebhook(input.webhook_id);
+    return `Webhook deleted: ${result.id}`;
+  },
+};
+

package/src/tools/disconnect-account.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const disconnectAccountTool = {
+  name: 'disconnect_account',
+  description:
+    'Disconnect a connected social account from posterly. DESTRUCTIVE and IRREVERSIBLE: removes the account connection, emits account.disconnected webhooks, and may transfer Instagram scheduled posts to a replacement account.\n\n' +
+    'REQUIRED BEFORE CALLING: Call `list_accounts` first, show the user the exact platform, username, account ID, and workspace that will be disconnected, then get explicit confirmation. Pass confirm=true only after that confirmation.',
+  inputSchema: z.object({
+    account_id: z.string().describe('Connected social account ID from list_accounts.'),
+    confirm: z.boolean().describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { account_id: string; confirm: boolean },
+  ) {
+    if (input.confirm !== true) {
+      throw new Error('Refusing to disconnect account without confirm=true after explicit user confirmation.');
+    }
+
+    const result = await client.disconnectAccount(input.account_id);
+    const account = result.account || {};
+    return [
+      `Disconnected ${account.platform || 'account'}${account.username ? ` @${account.username}` : ''} (ID: ${account.id || input.account_id}).`,
+      `Transferred posts: ${result.transferred_post_count ?? 0}.`,
+      `Stamped posts: ${result.stamped_post_count ?? 0}.`,
+    ].join('\n');
+  },
+};

package/src/tools/generate-video.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const generateVideoTool = {
+  name: 'generate_video',
+  description:
+    'Queue a Veo AI video generation job. COSTS VEO CREDITS: confirm prompt, model, duration, resolution, aspect ratio, audio choice, and credit cost with the user before calling. Poll get_video_job for status and final video_url.',
+  inputSchema: z.object({
+    prompt: z.string().min(5).max(1024),
+    negative_prompt: z.string().max(500).optional(),
+    aspect_ratio: z.enum(['16:9', '9:16']).default('16:9').optional(),
+    duration_seconds: z.union([z.literal(4), z.literal(6), z.literal(8)]).default(8).optional(),
+    resolution: z.enum(['720p', '1080p']).default('720p').optional(),
+    model: z.enum(['fast', 'standard']).default('fast').optional(),
+    image_url: z.string().url().optional(),
+    end_image_url: z.string().url().optional(),
+    reference_images: z.array(z.object({
+      url: z.string().url(),
+      type: z.enum(['character', 'object', 'scene']),
+    })).max(3).optional(),
+    generate_audio: z.boolean().default(true).optional(),
+    source_video_url: z.string().url().optional(),
+  }),
+
+  async execute(client: PosterlyClient, input: any) {
+    const result = await client.generateVideo(input);
+    return [
+      'Video generation job queued',
+      `Job ID: ${result.job_id}`,
+      `Status: ${result.status}`,
+      `Credit cost: ${result.credit_cost} (${result.included_credit_cost || 0} included, ${result.purchased_credit_cost || 0} purchased)`,
+      result.message,
+      '',
+      'Raw response:',
+      JSON.stringify(result, null, 2),
+    ].filter(Boolean).join('\n');
+  },
+};

package/src/tools/get-connect-link.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import type { ConnectOption, PosterlyClient } from '../lib/api-client.js';
+import { CONNECT_INPUTS, PLANNED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+
+export const getConnectLinkTool = {
+  name: 'get_connect_link',
+  description:
+    'List dashboard handoff links/readiness for connecting social accounts, or get one platform connection URL. Use connection_url in a logged-in browser. Direct OAuth URLs are intentionally not exposed because provider callbacks rely on browser state.',
+  inputSchema: z.object({
+    platform: z
+      .enum(CONNECT_INPUTS)
+      .optional()
+      .describe('Connection target such as instagram, meta, linkedin_page, twitter, x, google_business, telegram, reddit, or wordpress. Omit to list live connection targets.'),
+    workspace_id: z
+      .string()
+      .optional()
+      .describe('Filter connected account counts to a workspace.'),
+    include_planned: z
+      .boolean()
+      .optional()
+      .describe(`Include planned provider expansion targets from the Postiz parity audit: ${PLANNED_PLATFORM_IDS.join(', ')}.`),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { platform?: string; workspace_id?: string; include_planned?: boolean },
+  ) {
+    const result = await client.getConnectLink(input);
+    if (result.connect) {
+      return formatConnectOption(result.connect, true);
+    }
+
+    const options = result.connect_options || [];
+    const lines = options.map((option) => formatConnectOption(option, false));
+    return `Posterly connection options (${options.length}):\n${lines.join('\n\n')}`;
+  },
+};
+
+function formatConnectOption(option: ConnectOption, includeRaw: boolean): string {
+  const missing = option.missing_env?.length
+    ? `missing env: ${option.missing_env.map((group) => group.join(' or ')).join(', ')}`
+    : 'configured';
+  const accounts = option.connected_count ?? option.connected_accounts?.length ?? 0;
+  const fields = option.credential_fields?.length
+    ? `; credential fields: ${option.credential_fields.map((field: any) => field.key).join(', ')}`
+    : '';
+  const scopes = option.scopes?.length ? `; scopes: ${option.scopes.join(', ')}` : '';
+  const raw = includeRaw ? `\n\nRaw connect option:\n${JSON.stringify(option, null, 2)}` : '';
+
+  return [
+    `${option.label} (${option.platform})`,
+    `Status: ${option.status}; method: ${option.method}; ${missing}; connected accounts: ${accounts}`,
+    `Connection URL: ${option.connection_url || 'not available'}${fields}${scopes}`,
+    raw,
+  ].join('\n');
+}

package/src/tools/get-google-business-review-link.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const getGoogleBusinessReviewLinkTool = {
+  name: 'get_google_business_review_link',
+  description:
+    'Get the direct public Google review link for a connected Google Business Profile location. Requires account_id or location_id.',
+  inputSchema: z.object({
+    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    account_id: z.number().int().positive().optional().describe('Google Business account ID from list_accounts.'),
+    location_id: z.string().optional().describe('Google Business location/platform_user_id.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      workspace_id?: string;
+      account_id?: number;
+      location_id?: string;
+    },
+  ) {
+    const result = await client.getGoogleBusinessReviewLink(input);
+    return [
+      `Review link for ${result.businessName}:`,
+      result.reviewLink,
+      `Place ID: ${result.placeId}`,
+      `Account ID: ${result.account_id}`,
+    ].join('\n');
+  },
+};

package/src/tools/get-platform-schema.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { ALL_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+
+export const getPlatformSchemaTool = {
+  name: 'get_platform_schema',
+  description:
+    'Get the platform schema for a specific connected account or platform. Call this before creating posts with platform_settings so you know allowed post types, media limits, helper tools, and field names.',
+  inputSchema: z.object({
+    account_id: z
+      .string()
+      .optional()
+      .describe('Connected account ID from list_accounts. Preferred because it returns account context.'),
+    platform: z
+      .enum(ALL_PLATFORM_INPUTS)
+      .optional()
+      .describe(`Platform ID such as ${SUPPORTED_PLATFORM_IDS.join(', ')}. Set include_planned to inspect planned providers.`),
+    include_planned: z.boolean().optional(),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { account_id?: string; platform?: string; include_planned?: boolean },
+  ) {
+    const result = await client.getPlatformSchema(input);
+    const schema = result.schema || result.platform || result.platforms?.[0];
+    if (!schema) return JSON.stringify(result, null, 2);
+
+    const fields = schema.settings_schema?.fields || [];
+    const helpers = schema.helper_tools || [];
+    const accountLine = result.account
+      ? `Account: ${(result.account.username as string) || result.account.id} (${result.account.platform})\n`
+      : '';
+
+    return [
+      `${schema.label} (${schema.id}) schema`,
+      accountLine.trim(),
+      `Status: ${schema.status}`,
+      `Post types: ${schema.post_types.join(', ') || 'n/a'}`,
+      `Content limit: ${schema.content_limit ?? 'n/a'}`,
+      `Media: ${JSON.stringify(schema.media)}`,
+      `Analytics: ${schema.analytics_supported ? 'yes' : 'no'}`,
+      fields.length
+        ? `Settings:\n${fields.map((field: any) => `• ${field.key}${field.required ? ' (required)' : ''}: ${field.description}`).join('\n')}`
+        : 'Settings: none',
+      helpers.length
+        ? `Helpers:\n${helpers.map((helper: any) => `• ${helper.name}: ${helper.description}`).join('\n')}`
+        : 'Helpers: none',
+      `Example settings: ${JSON.stringify(schema.settings_schema?.example || {})}`,
+    ].filter(Boolean).join('\n');
+  },
+};

package/src/tools/get-post-missing.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const getPostMissingTool = {
+  name: 'get_post_missing',
+  description:
+    'Inspect whether a post is missing required content, media, account, platform settings, or metadata before it can publish. Use this to repair failed or imported posts.',
+  inputSchema: z.object({
+    post_id: z.number().int().positive().describe('The post ID to inspect.'),
+  }),
+
+  async execute(client: PosterlyClient, input: { post_id: number }) {
+    const result = await client.getPostMissing(input.post_id);
+    return JSON.stringify(result, null, 2);
+  },
+};
+