posterly-mcp-server 0.39.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.39.0` exposes 89 tools.
+`posterly-mcp-server@0.40.0` exposes 89 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 

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;

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.39.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.39.0';
+export const POSTERLY_MCP_VERSION = '0.40.0';

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/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/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.39.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.39.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.39.0",
+      "version": "0.40.0",
       "transport": {
         "type": "stdio"
       },

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 {

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

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/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');
   },
 };