posterly-mcp-server 0.44.0 → 0.45.1

package/src/tools/connect-account.ts

@@ -31,7 +31,7 @@ const PLATFORM_CREDENTIAL_FIELDS: Record<string, string[]> = {
 export const connectAccountTool = {
   name: 'connect_account',
   description:
-    'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call get_connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
+    'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call list_platforms with view=connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
   inputSchema: z.object({
     platform: z
       .enum(CREDENTIAL_PLATFORMS)
@@ -70,7 +70,7 @@ export const connectAccountTool = {
 
     const missing = allowedFields.filter((field) => !(field in credentials));
     if (missing.length > 0) {
-      return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call get_connect_link with platform=${input.platform} to see field descriptions.`;
+      return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call list_platforms with view=connect_link and target=${input.platform} to see field descriptions.`;
     }
 
     const result = await client.connectAccountCredentials({

package/src/tools/create-connect-session.ts

@@ -6,7 +6,7 @@ import { CONNECT_INPUTS } from '../generated/platform-manifest.js';
 export const createConnectSessionTool = {
   name: 'create_connect_session',
   description:
-    'Create a short-lived posterly dashboard handoff session for connecting a social account. Send the secure connection URL to the user, then poll get_connect_session to narrate progress. Do not ask for social media passwords or OAuth codes; posterly handles those browser steps.',
+    'Create a short-lived posterly dashboard handoff session for connecting a social account. Send the secure connection URL to the user, then poll list_accounts with view=connect_session to narrate progress. Do not ask for social media passwords or OAuth codes; posterly handles those browser steps.',
   inputSchema: z.object({
     platform: z
       .enum(CONNECT_INPUTS)
@@ -49,7 +49,7 @@ function formatConnectSession(session: ConnectSession, includeRaw: boolean): str
     `Expires: ${formatLocalDateTime(session.expires_at)}`,
     `Dashboard connect page: ${DASHBOARD_CONNECT_URL}`,
     '',
-    'Next step for the AI agent: send the secure connection URL to the user, explain that posterly will handle the browser OAuth step, then poll get_connect_session until the account is connected or the session ends.',
+    'Next step for the AI agent: send the secure connection URL to the user, explain that posterly will handle the browser OAuth step, then poll list_accounts with view=connect_session until the account is connected or the session ends.',
     includeRaw ? `\nRaw connect session:\n${JSON.stringify(session, null, 2)}` : '',
   ].filter(Boolean).join('\n');
 }

package/src/tools/create-post.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
+import type { PosterlyClient, Account } from '../lib/api-client.js';
 import { dashboardUrlForPost, formatLocalDateTime } from '../lib/format.js';
 import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
 
@@ -156,7 +156,7 @@ export const createPostPayloadInputSchema = z.object({
     .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. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Call get_platform_schema(account_id) first.'),
+      .describe('Instagram-specific settings. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Call list_platforms with view=schema and account_id first.'),
   platform_settings: platformSettingsSchema
     .optional()
     .describe('Platform-specific settings for the selected account. Use this for non-Instagram settings and prefer it over raw metadata.'),
@@ -173,7 +173,61 @@ export const createPostInputSchema = createPostPayloadInputSchema.extend({
 export type CreatePostInput = z.infer<typeof createPostInputSchema>;
 export type CreatePostPayloadInput = z.infer<typeof createPostPayloadInputSchema>;
 
-export function buildCreatePostPayload(input: CreatePostPayloadInput | CreatePostInput): Parameters<PosterlyClient['createPost']>[0] {
+export type AccountPlatformLookup =
+  | { found: true; platform: string | null }
+  | { found: false; detail: string };
+
+export type AccountPlatformResolver = (accountId: string, workspaceId?: string) => Promise<AccountPlatformLookup>;
+
+/**
+ * Builds a resolver that answers "what platform is this account_id on?" via
+ * client.listAccounts() (there is no GET /accounts/:id), for thread_posts
+ * calls that gave account_id without platform. Caches one in-flight lookup
+ * per workspace_id (including the unscoped list, keyed ''), so
+ * create_posts_batch never issues more than one accounts request per
+ * distinct workspace_id even though every item in the batch calls this
+ * independently: the cache is populated synchronously (before the first
+ * await) on the first call for a given workspace_id, so concurrent
+ * Promise.all callers for the same workspace_id share the one in-flight
+ * request. A failed lookup (non-2xx, missing accounts:read, network error)
+ * is cached too, so it is reported once per workspace_id rather than
+ * surfacing a fresh error per item.
+ */
+export function createAccountPlatformResolver(client: PosterlyClient): AccountPlatformResolver {
+  const cache = new Map<string, Promise<{ ok: true; platforms: Map<string, string> } | { ok: false; detail: string }>>();
+  const lookupForWorkspace = (workspaceKey: string) => {
+    let pending = cache.get(workspaceKey);
+    if (!pending) {
+      pending = (async () => {
+        try {
+          const accounts: Account[] = await client.listAccounts(workspaceKey ? { workspace_id: workspaceKey } : undefined);
+          const platforms = new Map<string, string>();
+          for (const account of accounts) {
+            if (account && typeof account.platform === 'string' && account.id !== undefined && account.id !== null) {
+              platforms.set(String(account.id), account.platform);
+            }
+          }
+          return { ok: true as const, platforms };
+        } catch (error: any) {
+          return { ok: false as const, detail: error?.message || 'accounts lookup failed' };
+        }
+      })();
+      cache.set(workspaceKey, pending);
+    }
+    return pending;
+  };
+  return async (accountId, workspaceId) => {
+    const workspaceKey = workspaceId || '';
+    const lookup = await lookupForWorkspace(workspaceKey);
+    if (!lookup.ok) return { found: false, detail: lookup.detail };
+    return { found: true, platform: lookup.platforms.get(String(accountId)) ?? null };
+  };
+}
+
+export async function buildCreatePostPayload(
+  input: CreatePostPayloadInput | CreatePostInput,
+  resolvePlatform: AccountPlatformResolver,
+): Promise<Parameters<PosterlyClient['createPost']>[0]> {
   const { confirm: _confirm, thread_posts, caption, post_type, instagram_settings, platform_settings, ...rest } = input as CreatePostInput & CreatePostPayloadInput;
 
   if (thread_posts && thread_posts.length > 0) {
@@ -181,12 +235,33 @@ export function buildCreatePostPayload(input: CreatePostPayloadInput | CreatePos
       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.',
-      );
+    let isTwitter = platformHint === 'twitter' || platformHint === 'x';
+    let isThreads = platformHint === 'threads';
+    if (!isTwitter && !isThreads) {
+      if (!input.account_id) {
+        throw new Error(
+          'thread_posts requires `platform` to be "twitter" or "threads", or pass `account_id` for an X/Threads account.',
+        );
+      }
+      // No platform hint: never guess X. Resolve the account's real platform
+      // first, so a Threads account_id builds a threads_thread, not an
+      // x_thread that the server then rejects.
+      const lookup = await resolvePlatform(input.account_id, input.workspace_id);
+      if (!lookup.found) {
+        throw new Error(
+          `thread_posts could not resolve account_id's platform (${lookup.detail}). Pass \`platform\` explicitly.`,
+        );
+      } else if (lookup.platform === 'threads') {
+        isThreads = true;
+      } else if (lookup.platform === 'twitter') {
+        isTwitter = true;
+      } else {
+        throw new Error(
+          lookup.platform
+            ? `thread_posts requires an X/Twitter or Threads account; account_id resolved to platform "${lookup.platform}".`
+            : 'thread_posts requires `platform` to be "twitter" or "threads", or an `account_id` that exists in list_accounts. Pass `platform` explicitly.',
+        );
+      }
     }
     const arrayKey = isThreads ? 'threads_thread_posts' : 'x_thread_tweets';
     const totalKey = isThreads ? 'threads_thread_total' : 'x_thread_total';
@@ -237,9 +312,9 @@ export const createPostTool = {
     '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' +
     'AFTER CALLING: Tell the user the post was created, include the posterly dashboard link returned by the tool, and offer the next natural action. Do not narrate raw HTTP, curl, or API plumbing.\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' +
-    '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_from_url` first if you want to upload once and reuse the returned posterly URL across posts.\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 `get_platform_schema` with 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. 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,
 
@@ -250,7 +325,7 @@ export const createPostTool = {
     if (input.confirm !== true) {
       throw new Error('Refusing to create post without confirm=true after explicit user confirmation.');
     }
-    const payload = buildCreatePostPayload(input);
+    const payload = await buildCreatePostPayload(input, createAccountPlatformResolver(client));
     const { thread_posts, instagram_settings, platform_settings } = input;
 
     const result = await client.createPost(payload);

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { dashboardUrlForPostList, formatLocalDateTime } from '../lib/format.js';
-import { buildCreatePostPayload, createPostPayloadInputSchema, type CreatePostPayloadInput } from './create-post.js';
+import { buildCreatePostPayload, createAccountPlatformResolver, createPostPayloadInputSchema, type CreatePostPayloadInput } from './create-post.js';
 
 export const createPostsBatchTool = {
   name: 'create_posts_batch',
@@ -26,7 +26,18 @@ export const createPostsBatchTool = {
     if (input.confirm !== true) {
       throw new Error('Refusing to create batch posts without confirm=true after explicit user confirmation.');
     }
-    const payloads = input.posts.map((post) => buildCreatePostPayload(post));
+    // One resolver shared across the whole batch: createAccountPlatformResolver
+    // caches its accounts lookup per workspace_id, so N items that all need
+    // thread_posts platform resolution for the same workspace still cost one
+    // listAccounts() call, not N.
+    const resolvePlatform = createAccountPlatformResolver(client);
+    const payloads = await Promise.all(input.posts.map(async (post, index) => {
+      try {
+        return await buildCreatePostPayload(post, resolvePlatform);
+      } catch (error: any) {
+        throw new Error(`Item ${index}: ${error?.message || 'invalid post input'}`);
+      }
+    }));
     const result = await client.createPostsBatch({ posts: payloads });
 
     const createdPosts = result.posts.map((item) => item.post);

package/src/tools/delete-post.ts

@@ -1,31 +1,72 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
-import { dashboardUrlForPosts } from '../lib/format.js';
+import { code, dashboardUrlForPosts } from '../lib/format.js';
+import { previewThenConfirm, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+type DeletePostInput = {
+  post_id?: number;
+  group_id?: string;
+  confirm?: boolean;
+  preview_id?: string;
+};
 
 export const deletePostTool = {
   name: 'delete_post',
   description:
-    'Delete a scheduled or draft post. DESTRUCTIVE and IRREVERSIBLE - the post and its caption cannot be recovered. Cannot delete published or currently publishing posts.\n\n' +
-    'REQUIRED BEFORE CALLING: Fetch the post with `get_post` first and show the user what will be deleted (caption, account, scheduled time). Get explicit confirmation ("yes delete it", "remove it") before calling. Never delete multiple posts in a single batch without listing each one and confirming the full list.',
+    '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.',
   inputSchema: z.object({
-    post_id: z.number().describe('The post ID to delete'),
-    confirm: z.literal(true).describe('Must be true after explicit user confirmation of the post deletion.'),
+    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.'),
+    confirm: z
+      .boolean()
+      .optional()
+      .describe('post_id: true after explicit user confirmation of the deletion. group_id: leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('group_id: the preview_id from the preview call. Required with confirm: true.'),
   }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    delete_post_group: z.object({
+      group_id: z.string().min(1).max(160),
+      confirm: z.literal(true),
+    }),
+  },
 
-  async execute(
-    client: PosterlyClient,
-    input: { post_id: number; confirm: true },
-  ) {
-    if (input.confirm !== true) {
-      throw new Error('Refusing to delete post without confirm=true after explicit user confirmation.');
+  async execute(client: PosterlyClient, input: DeletePostInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'delete_post', input);
+    if (mode === 'group') {
+      return previewThenConfirm({
+        tool: 'delete_post',
+        action: 'group',
+        args,
+        nonce: false,
+        legacyRefusal: 'Refusing to delete post group without confirm=true after explicit user confirmation.',
+        ctx,
+        // 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.`,
+          'To see the posts first, call list_posts and check each post\'s group or release ID.',
+        ].join('\n\n'),
+        run: async () => {
+          const result = await client.deletePostGroup(args.group_id);
+          return JSON.stringify(result, null, 2);
+        },
+      });
     }
-    const result = await client.deletePost(input.post_id);
-    return [
-      `Post #${result.id} deleted successfully.`,
-      'It has been removed from the posterly queue.',
-      `View queue in posterly: ${dashboardUrlForPosts()}`,
-      '',
-      'Next step for the AI agent: tell the user the post is gone and offer to create, reschedule, or review the next post.',
-    ].join('\n');
+    return deleteOne(client, args as { post_id: number; confirm?: boolean });
   },
 };
+
+async function deleteOne(client: PosterlyClient, input: { post_id: number; confirm?: 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);
+  return [
+    `Post #${result.id} deleted successfully.`,
+    'It has been removed from the posterly queue.',
+    `View queue in posterly: ${dashboardUrlForPosts()}`,
+    '',
+    'Next step for the AI agent: tell the user the post is gone and offer to create, reschedule, or review the next post.',
+  ].join('\n');
+}

package/src/tools/generate-image.ts

@@ -5,7 +5,7 @@ import { mdKeyValue, mdTitle } from '../lib/format.js';
 export const generateImageTool = {
   name: 'generate_image',
   description:
-    'Queue an AI image job via posterly using Nano Banana (Gemini) or Grok Imagine Image 2.0 (xAI). Returns job_id. Poll get_image_job until status is completed, then pass urls to create_post as media_url / media_urls. Gemini thinking high does not change the credit price.\n\n' +
+    'Queue an AI image job via posterly using Nano Banana (Gemini) or Grok Imagine Image 2.0 (xAI). Returns job_id. Poll list_jobs with type=image until status is completed, then pass urls to create_post as media_url / media_urls. Gemini thinking high does not change the credit price.\n\n' +
     'COSTS CREDITS. Every call consumes part of the user\'s monthly AI image quota (or purchased credits once the quota is exhausted). Do NOT call speculatively - always describe the image you\'re about to generate (subject, style, aspect ratio, quality/thinking, resolution) to the user and get confirmation before calling.\n\n' +
     'If the user is over their plan limit and has no credits, this tool returns a 402 with upgrade info. Surface that message verbatim - do not retry.\n\n' +
     'Common aspect ratios by platform:\n' +
@@ -100,7 +100,7 @@ export const generateImageTool = {
         ['Credits used', result.credits_used],
         ['Billed from', result.usage?.billed_from],
       ]),
-      result.message || 'Poll get_image_job with this job_id until status is completed, then pass urls to create_post.',
+      result.message || 'Poll list_jobs with type=image and this job_id until status is completed, then pass urls to create_post.',
     ].filter(Boolean).join('\n\n');
   },
 };

package/src/tools/generate-video.ts

@@ -4,7 +4,7 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const generateVideoTool = {
   name: 'generate_video',
   description:
-    'Queue an AI video generation job with Google Veo 3.1 or xAI Grok Imagine Video 1.5. COSTS CREDITS: confirm provider, prompt, duration, resolution, aspect ratio, audio choice, and credit cost with the user before calling. Grok supports 1–15 seconds and 480p–1080p; reference-to-video is capped at 720p. Poll get_video_job for status and final video_url.',
+    'Queue an AI video generation job with Google Veo 3.1 or xAI Grok Imagine Video 1.5. COSTS CREDITS: confirm provider, prompt, duration, resolution, aspect ratio, audio choice, and credit cost with the user before calling. Grok supports 1 to 15 seconds and 480p to 1080p; reference-to-video is capped at 720p. Poll list_jobs with type=video for status and final video_url.',
   inputSchema: z.object({
     provider: z.enum(['google', 'xai']).default('google').optional(),
     prompt: z.string().min(5).max(4000),

package/src/tools/get-agent-signup-info.ts

@@ -18,14 +18,14 @@ export const getAgentSignupInfoTool = {
       authState,
       '',
       'Pre-auth tools:',
-      '- get_mcp_status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
+      '- whoami with view=status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
       '- start_signup: starts paid signup and returns a signup poll URL, a browser Checkout fallback, and, when enabled, a prepaid PaymentIntent for a Link virtual card (credential_type: card).',
       '- get_signup_session: polls payment, password, and agent-access status.',
       '',
       'After posterly access is installed, onboard the user IN THIS chat (do not send them to /onboarding-v2):',
       '- whoami: confirm the paid account and read onboarding.next_step.',
       '- About you: confirm name and IANA timezone.',
-      '- create_connect_session / get_connect_session: first social account in the browser.',
+      '- create_connect_session, then list_accounts with view=connect_session: first social account in the browser.',
       '- Brand voice: ask how they want to sound, then use that on captions.',
       '- create_post: first scheduled post after validate_post and explicit confirm.',
       '',

package/src/tools/get-post.ts

@@ -1,35 +1,49 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { dashboardUrlForPost, formatLocalDateTime } from '../lib/format.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
 
 export const getPostTool = {
   name: 'get_post',
   description:
-    'Get details of a specific post by ID. Returns caption, status, scheduled time, media, and platform info.',
+    'One post by ID. view=post (default): caption, status, scheduled time, media, and platform info. view=missing: whether the post is missing required content, media, account, platform settings, or metadata before it can publish; use it to repair failed or imported posts.',
   inputSchema: z.object({
     post_id: z.number().describe('The post ID to look up'),
+    view: z.enum(['post', 'missing']).optional().describe('post (default) or missing.'),
   }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    get_post_missing: z.object({ post_id: z.number().int().positive() }),
+  },
 
-  async execute(
-    client: PosterlyClient,
-    input: { post_id: number },
-  ) {
-    const result = await client.getPost(input.post_id);
-    const p = result.post as Record<string, any>;
+  async execute(client: PosterlyClient, input: { post_id: number; view?: 'post' | 'missing' }, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'get_post', input);
+    if (mode === 'missing') return postMissing(client, args as { post_id: number });
+    return post(client, args as { post_id: number });
+  },
+};
 
-    const lines = [
-      `Post #${p.id}`,
-      `• Status: ${p.status}`,
-      `• Caption: ${p.content || '(empty)'}`,
-      `• Type: ${p.post_type || 'unknown'}`,
-      `• Scheduled: ${formatLocalDateTime(p.scheduled_at)}`,
-      `• View in posterly: ${dashboardUrlForPost({ id: p.id, scheduled_at: p.scheduled_at })}`,
-    ];
+async function post(client: PosterlyClient, input: { post_id: number }): Promise<string> {
+  const result = await client.getPost(input.post_id);
+  const p = result.post as Record<string, any>;
 
-    if (p.platform_post_url) lines.push(`• Published URL: ${p.platform_post_url}`);
-    if (p.media_url) lines.push(`• Media: ${p.media_url}`);
-    if (p.media_urls?.length) lines.push(`• Media (${p.media_urls.length}): ${p.media_urls.join(', ')}`);
+  const lines = [
+    `Post #${p.id}`,
+    `• Status: ${p.status}`,
+    `• Caption: ${p.content || '(empty)'}`,
+    `• Type: ${p.post_type || 'unknown'}`,
+    `• Scheduled: ${formatLocalDateTime(p.scheduled_at)}`,
+    `• View in posterly: ${dashboardUrlForPost({ id: p.id, scheduled_at: p.scheduled_at })}`,
+  ];
 
-    return lines.join('\n');
-  },
-};
+  if (p.platform_post_url) lines.push(`• Published URL: ${p.platform_post_url}`);
+  if (p.media_url) lines.push(`• Media: ${p.media_url}`);
+  if (p.media_urls?.length) lines.push(`• Media (${p.media_urls.length}): ${p.media_urls.join(', ')}`);
+
+  return lines.join('\n');
+}
+
+async function postMissing(client: PosterlyClient, input: { post_id: number }): Promise<string> {
+  const result = await client.getPostMissing(input.post_id);
+  return JSON.stringify(result, null, 2);
+}