posterly-mcp-server 0.38.0 → 0.40.0

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.38.0` exposes 87 tools.
+`posterly-mcp-server@0.40.0` exposes 89 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -176,6 +176,8 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `upload_media`
 - `upload_media_from_url`
 - `create_signed_upload`
+- `create_media_drop` (human drop page at https://www.poster.ly/drop/<token> for ChatGPT/Claude laptop files)
+- `list_media`
 - `find_available_slot`
 - `generate_captions`
 - `generate_image`

package/dist/index.js

@@ -74,6 +74,8 @@ import { getPlatformSchemaTool } from './tools/get-platform-schema.js';
 import { triggerPlatformHelperTool } from './tools/trigger-platform-helper.js';
 import { getXPostingQuotaTool } from './tools/get-x-posting-quota.js';
 import { createSignedUploadTool } from './tools/create-signed-upload.js';
+import { createMediaDropTool } from './tools/create-media-drop.js';
+import { listMediaTool } from './tools/list-media.js';
 import { uploadMediaFromUrlTool } from './tools/upload-media-from-url.js';
 import { getConnectLinkTool } from './tools/get-connect-link.js';
 import { connectAccountTool } from './tools/connect-account.js';
@@ -502,6 +504,24 @@ server.tool(createSignedUploadTool.name, createSignedUploadTool.description, cre
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(createMediaDropTool.name, createMediaDropTool.description, createMediaDropTool.inputSchema.shape, getToolAnnotations(createMediaDropTool.name), async (input) => {
+    try {
+        const text = await createMediaDropTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(listMediaTool.name, listMediaTool.description, listMediaTool.inputSchema.shape, getToolAnnotations(listMediaTool.name), async (input) => {
+    try {
+        const text = await listMediaTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(getVideoOptionsTool.name, getVideoOptionsTool.description, getVideoOptionsTool.inputSchema.shape, getToolAnnotations(getVideoOptionsTool.name), async () => {
     try {
         const text = await getVideoOptionsTool.execute(client);

package/dist/lib/api-client.d.ts

@@ -440,6 +440,12 @@ export interface Workspace {
     timezone?: string | null;
     role?: string;
 }
+export interface WhoamiOnboarding {
+    completed: boolean;
+    next_step: string;
+    next_step_label: string;
+    instruction: string;
+}
 export interface Whoami {
     user: {
         id: string;
@@ -451,6 +457,7 @@ export interface Whoami {
     };
     default_workspace: Workspace;
     workspaces: Workspace[];
+    onboarding?: WhoamiOnboarding;
 }
 export interface AccountAnalyticsSummary {
     current_followers: number;
@@ -1262,6 +1269,33 @@ export declare class PosterlyClient {
         public_url: string;
         headers?: Record<string, string>;
     }>;
+    createMediaDrop(input?: {
+        filename?: string;
+        maxFiles?: number;
+    }): Promise<{
+        session_id: string;
+        drop_url: string;
+        expires_at: string;
+        max_bytes: number;
+        max_files: number;
+        instructions: string;
+    }>;
+    listMedia(params?: {
+        limit?: number;
+        dropSessionId?: string;
+    }): Promise<{
+        media: Array<{
+            id: string;
+            public_url: string;
+            filename: string;
+            path: string;
+            mime: string | null;
+            bytes: number | null;
+            created_at: string;
+            drop_session_id: string | null;
+        }>;
+        total: number;
+    }>;
     uploadMedia(input: {
         filePath?: string;
         base64Data?: string;

package/dist/lib/api-client.js

@@ -506,6 +506,21 @@ export class PosterlyClient {
             size,
         });
     }
+    async createMediaDrop(input) {
+        return this.request('POST', '/media/drop-sessions', {
+            filename: input?.filename,
+            max_files: input?.maxFiles,
+        });
+    }
+    async listMedia(params) {
+        const searchParams = new URLSearchParams();
+        if (params?.limit)
+            searchParams.set('limit', String(params.limit));
+        if (params?.dropSessionId)
+            searchParams.set('drop_session_id', params.dropSessionId);
+        const qs = searchParams.toString();
+        return this.request('GET', `/media${qs ? `?${qs}` : ''}`);
+    }
     async uploadMedia(input) {
         this.requireApiKey();
         let fileBuffer;

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.38.0";
+export declare const POSTERLY_MCP_VERSION = "0.40.0";

package/dist/lib/version.js

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.38.0';
+export const POSTERLY_MCP_VERSION = '0.40.0';

package/dist/tools/create-media-drop.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const createMediaDropTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        filename: z.ZodOptional<z.ZodString>;
+        max_files: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        filename?: string | undefined;
+        max_files?: number | undefined;
+    }, {
+        filename?: string | undefined;
+        max_files?: number | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        filename?: string;
+        max_files?: number;
+    }): Promise<string>;
+};

package/dist/tools/create-media-drop.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export const createMediaDropTool = {
+    name: 'create_media_drop',
+    description: 'Create a human drop page so ChatGPT or Claude users can upload a laptop file without dashboard login. Returns drop_url (https://www.poster.ly/drop/<token>). Send that URL to the user, wait, then call list_media. This is not the chat paperclip and not create_signed_upload.',
+    inputSchema: z.object({
+        filename: z.string().optional().describe('Optional filename hint for the user, e.g. launch-video.mp4'),
+        max_files: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe('How many files the drop can accept. Default 10, max 10.'),
+    }),
+    async execute(client, input) {
+        const drop = await client.createMediaDrop({
+            filename: input.filename,
+            maxFiles: input.max_files,
+        });
+        return [
+            'Media drop created. Send this URL to the user. They open it with no posterly login and drop the file.',
+            `• Drop URL: ${drop.drop_url}`,
+            `• Session ID: ${drop.session_id}`,
+            `• Expires: ${drop.expires_at}`,
+            `• Max bytes: ${drop.max_bytes}`,
+            `• Max files: ${drop.max_files}`,
+            drop.instructions,
+            'After they finish, call list_media with this drop_session_id, then validate_post / create_post using public_url.',
+            'Chat attachments never reach MCP. HEIC and PDF are rejected.',
+        ].join('\n');
+    },
+};

package/dist/tools/create-signed-upload.d.ts

@@ -8,12 +8,12 @@ export declare const createSignedUploadTool: {
         content_type: z.ZodString;
         size: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        content_type: string;
         filename: string;
+        content_type: string;
         size: number;
     }, {
-        content_type: string;
         filename: string;
+        content_type: string;
         size: number;
     }>;
     execute(client: PosterlyClient, input: {

package/dist/tools/get-agent-signup-info.js

@@ -17,11 +17,12 @@ export const getAgentSignupInfoTool = {
             '- start_signup: starts paid signup and returns a Posterly checkout handoff URL plus a signup poll URL.',
             '- get_signup_session: polls checkout, payment, password, and agent-access status.',
             '',
-            'After Posterly access is installed:',
-            '- whoami: confirm the paid Posterly account/workspace.',
-            '- create_connect_session: create a secure browser OAuth handoff for the social platform the user chooses.',
-            '- get_connect_session: poll the OAuth handoff until connected.',
-            '- create_post: schedule posts after the user confirms the account and content.',
+            '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.',
+            '- Brand voice: ask how they want to sound, then use that on captions.',
+            '- create_post: first scheduled post after validate_post and explicit confirm.',
             '',
             'Conversation style:',
             '- Keep the user updated in plain language: checkout pending, payment confirmed, password setup needed, account connected, post scheduled.',

package/dist/tools/get-signup-session.js

@@ -59,9 +59,9 @@ function guidanceForStatus(status) {
         case 'authorize_agent':
             return 'Tell the user Posterly is ready for agent authorization. Send them the provided authorization or completion link if one is present.';
         case 'agent_access_required':
-            return 'Tell the user API access is active, but this AI still needs Posterly access. Ask them to paste the Posterly MCP/API setup instructions here or install the Posterly MCP server, then continue with social account connection.';
+            return 'Tell the user API access is active, but this AI still needs Posterly access. Ask them to paste the Posterly MCP/API setup instructions here or install the Posterly MCP server. Then onboard them IN THIS chat: about you, connect, brand voice, first post. Do not send them to /onboarding-v2.';
         case 'api_access_active':
-            return 'Posterly API access is active. Ask which social account the user wants to connect first, then create a connect session.';
+            return 'Posterly API access is active. Call whoami, then onboard them IN THIS chat: about you (name and timezone), connect the first account, brand voice, first post. Do not send them to /onboarding-v2.';
         default:
             return 'Explain the current status to the user and keep polling unless the session is terminal.';
     }

package/dist/tools/list-media.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const listMediaTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        limit: z.ZodOptional<z.ZodNumber>;
+        drop_session_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        drop_session_id?: string | undefined;
+    }, {
+        limit?: number | undefined;
+        drop_session_id?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        limit?: number;
+        drop_session_id?: string;
+    }): Promise<string>;
+};

package/dist/tools/list-media.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export const listMediaTool = {
+    name: 'list_media',
+    description: 'List the newest media assets for the authenticated user. After create_media_drop, pass drop_session_id to see files the human uploaded on /drop/<token>. Use public_url with validate_post / create_post.',
+    inputSchema: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Number of assets to return (default 10, max 50)'),
+        drop_session_id: z
+            .string()
+            .optional()
+            .describe('Filter to files uploaded through one create_media_drop session'),
+    }),
+    async execute(client, input) {
+        const result = await client.listMedia({
+            limit: input.limit,
+            dropSessionId: input.drop_session_id,
+        });
+        if (result.media.length === 0) {
+            return 'No media found. If you just sent a drop URL, wait for the user to finish uploading, then call list_media again.';
+        }
+        const lines = result.media.map((item) => {
+            const size = typeof item.bytes === 'number' ? `${item.bytes} bytes` : 'unknown size';
+            const drop = item.drop_session_id ? ` drop=${item.drop_session_id}` : '';
+            return `• ${item.filename} (${item.mime || 'unknown'}, ${size})${drop}\n  public_url: ${item.public_url}`;
+        });
+        return [
+            `Media (${result.media.length} of ${result.total}):`,
+            ...lines,
+            '',
+            'Pass public_url to validate_post / create_post. Do not invent URLs.',
+        ].join('\n');
+    },
+};

package/dist/tools/start-signup.js

@@ -78,7 +78,7 @@ function formatSignupStart(response, includeRaw) {
         '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
         '2. Call get_signup_session with the signup session ID until the status changes.',
         '3. Tell the user when Posterly sends the password setup email.',
-        '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat.',
+        '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
         '5. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
         includeRaw ? `\nRaw signup response:\n${JSON.stringify(response, null, 2)}` : '',
     ];

package/dist/tools/upload-media-from-url.d.ts

@@ -9,12 +9,12 @@ export declare const uploadMediaFromUrlTool: {
         content_type: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         url: string;
-        content_type?: string | undefined;
         filename?: string | undefined;
+        content_type?: string | undefined;
     }, {
         url: string;
-        content_type?: string | undefined;
         filename?: string | undefined;
+        content_type?: string | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         url: string;

package/dist/tools/whoami.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { code, mdKeyValue, mdTable, mdTitle } from '../lib/format.js';
 export const whoamiTool = {
     name: 'whoami',
-    description: 'Return the authenticated user, API key scopes, the default (personal) workspace, and every workspace the caller can post in. ALWAYS call this at the start of a session before creating, listing, or scheduling posts - posts created without an explicit workspace_id land in the default workspace shown here, and confirming with the user first prevents posts from appearing in the wrong workspace.',
+    description: 'Return the authenticated user, API key scopes, workspaces, and onboarding next step. ALWAYS call this at the start of a session. If onboarding.completed is false, walk the remaining onboarding steps IN THIS conversation (about you, connect, brand voice, first post). Do not send the user to /onboarding-v2 or the dashboard composer wizard.',
     inputSchema: z.object({}),
     async execute(client) {
         const info = await client.whoami();
@@ -13,7 +13,11 @@ export const whoamiTool = {
                 ['API scopes', info.api_key.scopes.join(', ') || 'none'],
                 ['Default workspace', `${info.default_workspace.name} (${code(info.default_workspace.id)})`],
                 ['Default timezone', info.default_workspace.timezone || 'n/a'],
+                ['Onboarding', info.onboarding?.completed ? 'complete' : info.onboarding?.next_step_label || 'unknown'],
             ]),
+            info.onboarding && !info.onboarding.completed
+                ? `**Onboarding next:** ${info.onboarding.next_step_label}. ${info.onboarding.instruction}`
+                : '',
             mdTable(['Workspace', 'Workspace ID', 'Role', 'Timezone', 'Default'], info.workspaces.map((workspace) => [
                 `${workspace.name}${workspace.is_personal ? ' (personal)' : ''}`,
                 code(workspace.id),
@@ -22,6 +26,6 @@ export const whoamiTool = {
                 workspace.id === info.default_workspace.id,
             ])),
             '**Tip:** Pass `workspace_id` to `create_post`, `list_posts`, `list_accounts`, and `find_available_slot` when you want the assistant to stay inside one workspace.',
-        ].join('\n\n');
+        ].filter(Boolean).join('\n\n');
     },
 };

package/package.json

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

package/src/index.ts

@@ -75,6 +75,8 @@ import { getPlatformSchemaTool } from './tools/get-platform-schema.js';
 import { triggerPlatformHelperTool } from './tools/trigger-platform-helper.js';
 import { getXPostingQuotaTool } from './tools/get-x-posting-quota.js';
 import { createSignedUploadTool } from './tools/create-signed-upload.js';
+import { createMediaDropTool } from './tools/create-media-drop.js';
+import { listMediaTool } from './tools/list-media.js';
 import { uploadMediaFromUrlTool } from './tools/upload-media-from-url.js';
 import { getConnectLinkTool } from './tools/get-connect-link.js';
 import { connectAccountTool } from './tools/connect-account.js';
@@ -776,6 +778,36 @@ server.tool(
   }
 );
 
+server.tool(
+  createMediaDropTool.name,
+  createMediaDropTool.description,
+  createMediaDropTool.inputSchema.shape,
+  getToolAnnotations(createMediaDropTool.name),
+  async (input) => {
+    try {
+      const text = await createMediaDropTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  listMediaTool.name,
+  listMediaTool.description,
+  listMediaTool.inputSchema.shape,
+  getToolAnnotations(listMediaTool.name),
+  async (input) => {
+    try {
+      const text = await listMediaTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 server.tool(
   getVideoOptionsTool.name,
   getVideoOptionsTool.description,

package/src/lib/api-client.ts

@@ -465,11 +465,19 @@ export interface Workspace {
   role?: string;
 }
 
+export interface WhoamiOnboarding {
+  completed: boolean;
+  next_step: string;
+  next_step_label: string;
+  instruction: string;
+}
+
 export interface Whoami {
   user: { id: string; email: string | null };
   api_key: { id: string; scopes: string[] };
   default_workspace: Workspace;
   workspaces: Workspace[];
+  onboarding?: WhoamiOnboarding;
 }
 
 export interface AccountAnalyticsSummary {
@@ -1702,6 +1710,46 @@ export class PosterlyClient {
     });
   }
 
+  async createMediaDrop(input?: {
+    filename?: string;
+    maxFiles?: number;
+  }): Promise<{
+    session_id: string;
+    drop_url: string;
+    expires_at: string;
+    max_bytes: number;
+    max_files: number;
+    instructions: string;
+  }> {
+    return this.request('POST', '/media/drop-sessions', {
+      filename: input?.filename,
+      max_files: input?.maxFiles,
+    });
+  }
+
+  async listMedia(params?: {
+    limit?: number;
+    dropSessionId?: string;
+  }): Promise<{
+    media: Array<{
+      id: string;
+      public_url: string;
+      filename: string;
+      path: string;
+      mime: string | null;
+      bytes: number | null;
+      created_at: string;
+      drop_session_id: string | null;
+    }>;
+    total: number;
+  }> {
+    const searchParams = new URLSearchParams();
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.dropSessionId) searchParams.set('drop_session_id', params.dropSessionId);
+    const qs = searchParams.toString();
+    return this.request('GET', `/media${qs ? `?${qs}` : ''}`);
+  }
+
   async uploadMedia(input: {
     filePath?: string;
     base64Data?: string;

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.38.0';
+export const POSTERLY_MCP_VERSION = '0.40.0';

package/src/tools/create-media-drop.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const createMediaDropTool = {
+  name: 'create_media_drop',
+  description:
+    'Create a human drop page so ChatGPT or Claude users can upload a laptop file without dashboard login. Returns drop_url (https://www.poster.ly/drop/<token>). Send that URL to the user, wait, then call list_media. This is not the chat paperclip and not create_signed_upload.',
+  inputSchema: z.object({
+    filename: z.string().optional().describe('Optional filename hint for the user, e.g. launch-video.mp4'),
+    max_files: z
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe('How many files the drop can accept. Default 10, max 10.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { filename?: string; max_files?: number },
+  ) {
+    const drop = await client.createMediaDrop({
+      filename: input.filename,
+      maxFiles: input.max_files,
+    });
+    return [
+      'Media drop created. Send this URL to the user. They open it with no posterly login and drop the file.',
+      `• Drop URL: ${drop.drop_url}`,
+      `• Session ID: ${drop.session_id}`,
+      `• Expires: ${drop.expires_at}`,
+      `• Max bytes: ${drop.max_bytes}`,
+      `• Max files: ${drop.max_files}`,
+      drop.instructions,
+      'After they finish, call list_media with this drop_session_id, then validate_post / create_post using public_url.',
+      'Chat attachments never reach MCP. HEIC and PDF are rejected.',
+    ].join('\n');
+  },
+};

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

@@ -22,11 +22,12 @@ export const getAgentSignupInfoTool = {
       '- start_signup: starts paid signup and returns a Posterly checkout handoff URL plus a signup poll URL.',
       '- get_signup_session: polls checkout, payment, password, and agent-access status.',
       '',
-      'After Posterly access is installed:',
-      '- whoami: confirm the paid Posterly account/workspace.',
-      '- create_connect_session: create a secure browser OAuth handoff for the social platform the user chooses.',
-      '- get_connect_session: poll the OAuth handoff until connected.',
-      '- create_post: schedule posts after the user confirms the account and content.',
+      '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.',
+      '- Brand voice: ask how they want to sound, then use that on captions.',
+      '- create_post: first scheduled post after validate_post and explicit confirm.',
       '',
       'Conversation style:',
       '- Keep the user updated in plain language: checkout pending, payment confirmed, password setup needed, account connected, post scheduled.',

package/src/tools/get-signup-session.ts

@@ -68,9 +68,9 @@ function guidanceForStatus(status: string): string {
     case 'authorize_agent':
       return 'Tell the user Posterly is ready for agent authorization. Send them the provided authorization or completion link if one is present.';
     case 'agent_access_required':
-      return 'Tell the user API access is active, but this AI still needs Posterly access. Ask them to paste the Posterly MCP/API setup instructions here or install the Posterly MCP server, then continue with social account connection.';
+      return 'Tell the user API access is active, but this AI still needs Posterly access. Ask them to paste the Posterly MCP/API setup instructions here or install the Posterly MCP server. Then onboard them IN THIS chat: about you, connect, brand voice, first post. Do not send them to /onboarding-v2.';
     case 'api_access_active':
-      return 'Posterly API access is active. Ask which social account the user wants to connect first, then create a connect session.';
+      return 'Posterly API access is active. Call whoami, then onboard them IN THIS chat: about you (name and timezone), connect the first account, brand voice, first post. Do not send them to /onboarding-v2.';
     default:
       return 'Explain the current status to the user and keep polling unless the session is terminal.';
   }

package/src/tools/list-media.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const listMediaTool = {
+  name: 'list_media',
+  description:
+    'List the newest media assets for the authenticated user. After create_media_drop, pass drop_session_id to see files the human uploaded on /drop/<token>. Use public_url with validate_post / create_post.',
+  inputSchema: z.object({
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe('Number of assets to return (default 10, max 50)'),
+    drop_session_id: z
+      .string()
+      .optional()
+      .describe('Filter to files uploaded through one create_media_drop session'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { limit?: number; drop_session_id?: string },
+  ) {
+    const result = await client.listMedia({
+      limit: input.limit,
+      dropSessionId: input.drop_session_id,
+    });
+
+    if (result.media.length === 0) {
+      return 'No media found. If you just sent a drop URL, wait for the user to finish uploading, then call list_media again.';
+    }
+
+    const lines = result.media.map((item) => {
+      const size = typeof item.bytes === 'number' ? `${item.bytes} bytes` : 'unknown size';
+      const drop = item.drop_session_id ? ` drop=${item.drop_session_id}` : '';
+      return `• ${item.filename} (${item.mime || 'unknown'}, ${size})${drop}\n  public_url: ${item.public_url}`;
+    });
+
+    return [
+      `Media (${result.media.length} of ${result.total}):`,
+      ...lines,
+      '',
+      'Pass public_url to validate_post / create_post. Do not invent URLs.',
+    ].join('\n');
+  },
+};

package/src/tools/start-signup.ts

@@ -99,7 +99,7 @@ function formatSignupStart(response: PublicSignupResponse, includeRaw: boolean):
     '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
     '2. Call get_signup_session with the signup session ID until the status changes.',
     '3. Tell the user when Posterly sends the password setup email.',
-    '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat.',
+    '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
     '5. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
     includeRaw ? `\nRaw signup response:\n${JSON.stringify(response, null, 2)}` : '',
   ];

package/src/tools/whoami.ts

@@ -5,7 +5,7 @@ import { code, mdKeyValue, mdTable, mdTitle } from '../lib/format.js';
 export const whoamiTool = {
   name: 'whoami',
   description:
-    'Return the authenticated user, API key scopes, the default (personal) workspace, and every workspace the caller can post in. ALWAYS call this at the start of a session before creating, listing, or scheduling posts - posts created without an explicit workspace_id land in the default workspace shown here, and confirming with the user first prevents posts from appearing in the wrong workspace.',
+    'Return the authenticated user, API key scopes, workspaces, and onboarding next step. ALWAYS call this at the start of a session. If onboarding.completed is false, walk the remaining onboarding steps IN THIS conversation (about you, connect, brand voice, first post). Do not send the user to /onboarding-v2 or the dashboard composer wizard.',
   inputSchema: z.object({}),
 
   async execute(client: PosterlyClient) {
@@ -18,7 +18,11 @@ export const whoamiTool = {
         ['API scopes', info.api_key.scopes.join(', ') || 'none'],
         ['Default workspace', `${info.default_workspace.name} (${code(info.default_workspace.id)})`],
         ['Default timezone', info.default_workspace.timezone || 'n/a'],
+        ['Onboarding', info.onboarding?.completed ? 'complete' : info.onboarding?.next_step_label || 'unknown'],
       ]),
+      info.onboarding && !info.onboarding.completed
+        ? `**Onboarding next:** ${info.onboarding.next_step_label}. ${info.onboarding.instruction}`
+        : '',
       mdTable(
         ['Workspace', 'Workspace ID', 'Role', 'Timezone', 'Default'],
         info.workspaces.map((workspace) => [
@@ -30,6 +34,6 @@ export const whoamiTool = {
         ]),
       ),
       '**Tip:** Pass `workspace_id` to `create_post`, `list_posts`, `list_accounts`, and `find_available_slot` when you want the assistant to stay inside one workspace.',
-    ].join('\n\n');
+    ].filter(Boolean).join('\n\n');
   },
 };

package/tool-annotations.json

@@ -45,6 +45,8 @@
     "upload_media",
     "upload_media_from_url",
     "create_signed_upload",
+    "create_media_drop",
+    "list_media",
     "get_video_options",
     "run_video_function",
     "generate_video",
@@ -113,6 +115,7 @@
     "validate_post",
     "find_available_slot",
     "list_posts",
+    "list_media",
     "get_video_options",
     "get_video_job",
     "get_post",
@@ -196,6 +199,7 @@
     "create_posts_batch",
     "upload_media_from_url",
     "create_signed_upload",
+    "create_media_drop",
     "run_video_function",
     "generate_video",
     "get_video_job",