posterly-mcp-server 0.19.5 → 0.19.7

package/README.md

@@ -4,6 +4,8 @@ Use Posterly from any MCP-compatible AI client.
 
 This package gives Claude Desktop, Cursor, Windsurf, Cline, and other local MCP clients a `stdio` server that can:
 
+- start paid Posterly signup before an API key exists
+- poll signup progress while the user completes checkout and password setup
 - list connected social accounts
 - resolve brands/clients into the right accounts
 - schedule and manage posts
@@ -16,26 +18,34 @@ Posterly also exposes the same toolset over HTTP at [poster.ly/mcp](https://www.
 ## Requirements
 
 - Node.js `20+`
-- A Posterly account: [poster.ly/signup](https://www.poster.ly/signup)
-- The Posterly API add-on enabled: [poster.ly/dashboard/api](https://www.poster.ly/dashboard/api)
-- A Posterly API key
+- No API key is required for the public signup tools: `get_agent_signup_info`, `start_signup`, and `get_signup_session`
+- A Posterly account, API add-on, and API key are required for authenticated tools like `whoami`, `list_accounts`, `create_connect_session`, and `create_post`
 
 ## Install
 
-You can install globally:
+Recommended: use it via `npx` in your MCP config so your client runs the current server without a global install.
 
-```bash
-npm install -g posterly-mcp-server
+To let an AI agent start signup before a Posterly API key exists, install the server without `POSTERLY_API_KEY`:
+
+```json
+{
+  "mcpServers": {
+    "posterly": {
+      "command": "npx",
+      "args": ["-y", "posterly-mcp-server@latest"]
+    }
+  }
+}
 ```
 
-Or just use it via `npx` in your MCP config:
+After paid signup is complete and Posterly shows an API key, add `POSTERLY_API_KEY` to unlock the authenticated tools:
 
 ```json
 {
   "mcpServers": {
     "posterly": {
       "command": "npx",
-      "args": ["-y", "posterly-mcp-server"],
+      "args": ["-y", "posterly-mcp-server@latest"],
       "env": {
         "POSTERLY_API_KEY": "pst_live_your_key_here"
       }
@@ -46,12 +56,12 @@ Or just use it via `npx` in your MCP config:
 
 ## Quick setup
 
-1. Sign up at [poster.ly](https://www.poster.ly/signup)
-2. Go to [Dashboard → API & MCP](https://www.poster.ly/dashboard/api)
-3. Enable the API add-on
-4. Generate an API key
-5. Paste it into your MCP client config as `POSTERLY_API_KEY`
-6. Restart your AI client
+1. Add the Posterly MCP server to your AI client.
+2. If you do not have Posterly yet, ask the AI to call `start_signup`.
+3. Pay in Stripe Checkout and set your Posterly password in the browser.
+4. When Posterly shows your API key, add it as `POSTERLY_API_KEY`.
+5. Restart your AI client.
+6. Ask the AI to call `whoami`, then continue by connecting your first social account.
 
 ## Example configs
 
@@ -64,7 +74,7 @@ Add this to your Claude Desktop MCP config:
   "mcpServers": {
     "posterly": {
       "command": "npx",
-      "args": ["-y", "posterly-mcp-server"],
+      "args": ["-y", "posterly-mcp-server@latest"],
       "env": {
         "POSTERLY_API_KEY": "pst_live_your_key_here"
       }
@@ -82,7 +92,7 @@ Add the same server definition to your Cursor MCP settings:
   "mcpServers": {
     "posterly": {
       "command": "npx",
-      "args": ["-y", "posterly-mcp-server"],
+      "args": ["-y", "posterly-mcp-server@latest"],
       "env": {
         "POSTERLY_API_KEY": "pst_live_your_key_here"
       }
@@ -93,12 +103,22 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.19.5` exposes 49 tools:
+`posterly-mcp-server@0.19.7` exposes 54 tools.
+
+Public signup tools work before `POSTERLY_API_KEY` exists:
+
+- `get_agent_signup_info`
+- `start_signup` (start paid signup and return a Posterly checkout handoff URL)
+- `get_signup_session` (poll checkout, payment, password, and agent-access status)
+
+Authenticated tools require `POSTERLY_API_KEY`:
 
 - `whoami`
 - `list_accounts`
 - `disconnect_account` (disconnect a connected social account after explicit confirmation)
 - `get_connect_link`
+- `create_connect_session` (create a guided browser handoff for connecting a social account)
+- `get_connect_session` (poll connection progress while the user approves OAuth or enters credentials)
 - `list_oauth_clients`
 - `create_oauth_client` (create a public PKCE client after explicit confirmation)
 - `update_oauth_client` (update redirect URIs/scopes after explicit confirmation)
@@ -214,5 +234,5 @@ npm start
 
 The package reads:
 
-- `POSTERLY_API_KEY`
+- optional `POSTERLY_API_KEY` for authenticated Posterly tools
 - optional `POSTERLY_URL` if you need to point at a non-production environment

package/dist/index.js

@@ -2,6 +2,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { PosterlyClient } from './lib/api-client.js';
+import { getAgentSignupInfoTool } from './tools/get-agent-signup-info.js';
+import { getSignupSessionTool } from './tools/get-signup-session.js';
+import { startSignupTool } from './tools/start-signup.js';
 import { listAccountsTool } from './tools/list-accounts.js';
 import { disconnectAccountTool } from './tools/disconnect-account.js';
 import { listBrandsTool } from './tools/list-brands.js';
@@ -47,23 +50,45 @@ import { getXPostingQuotaTool } from './tools/get-x-posting-quota.js';
 import { createSignedUploadTool } from './tools/create-signed-upload.js';
 import { uploadMediaFromUrlTool } from './tools/upload-media-from-url.js';
 import { getConnectLinkTool } from './tools/get-connect-link.js';
+import { createConnectSessionTool } from './tools/create-connect-session.js';
+import { getConnectSessionTool } from './tools/get-connect-session.js';
 import { listOAuthClientsTool } from './tools/list-oauth-clients.js';
 import { createOAuthClientTool } from './tools/create-oauth-client.js';
 import { updateOAuthClientTool } from './tools/update-oauth-client.js';
 import { deleteOAuthClientTool } from './tools/delete-oauth-client.js';
 const server = new McpServer({
     name: 'posterly',
-    version: '0.19.0',
+    version: '0.19.7',
 });
-let client;
-try {
-    client = new PosterlyClient();
-}
-catch (err) {
-    console.error(err.message);
-    process.exit(1);
-}
+const client = new PosterlyClient();
 // Register tools
+server.tool(getAgentSignupInfoTool.name, getAgentSignupInfoTool.description, getAgentSignupInfoTool.inputSchema.shape, async () => {
+    try {
+        const text = await getAgentSignupInfoTool.execute(client);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(startSignupTool.name, startSignupTool.description, startSignupTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await startSignupTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(getSignupSessionTool.name, getSignupSessionTool.description, getSignupSessionTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getSignupSessionTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(whoamiTool.name, whoamiTool.description, whoamiTool.inputSchema.shape, async () => {
     try {
         const text = await whoamiTool.execute(client);
@@ -100,6 +125,24 @@ server.tool(getConnectLinkTool.name, getConnectLinkTool.description, getConnectL
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(createConnectSessionTool.name, createConnectSessionTool.description, createConnectSessionTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await createConnectSessionTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(getConnectSessionTool.name, getConnectSessionTool.description, getConnectSessionTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getConnectSessionTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(listOAuthClientsTool.name, listOAuthClientsTool.description, listOAuthClientsTool.inputSchema.shape, async () => {
     try {
         const text = await listOAuthClientsTool.execute(client);

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

@@ -348,6 +348,26 @@ export interface ConnectOption {
     connected_count?: number;
     connected_accounts?: Account[];
 }
+export interface ConnectSession {
+    id: string;
+    platform: string;
+    method: 'dashboard_oauth' | 'manual_credentials';
+    status: 'created' | 'opened' | 'awaiting_provider' | 'awaiting_credentials' | 'connected' | 'failed' | 'cancelled' | 'expired';
+    status_message: string;
+    connect_url: string;
+    poll_url: string;
+    workspace_id?: string | null;
+    connected_account_ids: string[];
+    connected_accounts: Account[];
+    connected_count: number;
+    error_code?: string | null;
+    error_message?: string | null;
+    created_at: string;
+    opened_at?: string | null;
+    provider_redirected_at?: string | null;
+    completed_at?: string | null;
+    expires_at: string;
+}
 export interface OAuthDeveloperClient {
     id: string;
     client_id: string;
@@ -360,6 +380,55 @@ export interface OAuthDeveloperClient {
     created_at?: string;
     updated_at?: string;
 }
+export type PublicSignupTier = 'starter' | 'pro' | 'power_user' | 'agency';
+export interface PublicSignupPayload {
+    email: string;
+    name?: string;
+    tier?: PublicSignupTier;
+    interval?: 'month';
+    api_addon?: boolean;
+    return_path?: string;
+    source?: string;
+}
+export interface PublicSignupSession {
+    id: string;
+    status: string;
+    status_message?: string;
+    next_action?: {
+        actor?: string;
+        type?: string;
+        label?: string;
+        description?: string;
+    };
+    agent_next_steps?: string[];
+    checkout_redirect_url?: string | null;
+    checkout?: Record<string, unknown>;
+    account?: Record<string, unknown>;
+    billing?: Record<string, unknown>;
+    links?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    expires_at?: string;
+    [key: string]: unknown;
+}
+export interface PublicSignupResponse {
+    signup_session?: PublicSignupSession;
+    checkout_session_id?: string;
+    checkout_url?: string | null;
+    checkout_redirect_url?: string | null;
+    poll_url?: string | null;
+    complete_url?: string | null;
+    dashboard_url?: string | null;
+    status?: string;
+    status_message?: string;
+    links?: Record<string, unknown>;
+    account?: Record<string, unknown>;
+    billing?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface PublicSignupSessionResponse {
+    signup_session: PublicSignupSession;
+}
 export interface VideoJob {
     id: string;
     status: string;
@@ -401,7 +470,12 @@ export declare class PosterlyClient {
     private baseUrl;
     private apiKey;
     constructor(apiKey?: string, baseUrl?: string);
+    hasApiKey(): boolean;
+    private requireApiKey;
     private request;
+    private publicRequest;
+    startSignup(data: PublicSignupPayload): Promise<PublicSignupResponse>;
+    getSignupSession(sessionId: string): Promise<PublicSignupSessionResponse>;
     whoami(): Promise<Whoami>;
     listAccounts(params?: {
         workspace_id?: string;
@@ -415,6 +489,17 @@ export declare class PosterlyClient {
         connect?: ConnectOption;
         connect_options?: ConnectOption[];
     }>;
+    createConnectSession(data: {
+        platform: string;
+        workspace_id?: string;
+        auto_start?: boolean;
+    }): Promise<{
+        connect_session: ConnectSession;
+        connect?: ConnectOption;
+    }>;
+    getConnectSession(sessionId: string): Promise<{
+        connect_session: ConnectSession;
+    }>;
     listOAuthClients(): Promise<{
         clients: OAuthDeveloperClient[];
     }>;

package/dist/lib/api-client.js

@@ -6,11 +6,17 @@ export class PosterlyClient {
     constructor(apiKey, baseUrl) {
         this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
         this.baseUrl = (baseUrl || process.env.POSTERLY_URL || 'https://www.poster.ly').replace(/\/$/, '');
+    }
+    hasApiKey() {
+        return Boolean(this.apiKey);
+    }
+    requireApiKey() {
         if (!this.apiKey) {
-            throw new Error('POSTERLY_API_KEY is required. Set it as an environment variable.');
+            throw new Error('Posterly access is not installed yet. Use start_signup to begin paid setup, or set POSTERLY_API_KEY after signup.');
         }
     }
     async request(method, path, body) {
+        this.requireApiKey();
         const url = `${this.baseUrl}/api/v1${path}`;
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
@@ -30,6 +36,27 @@ export class PosterlyClient {
         }
         return res.json();
     }
+    async publicRequest(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {};
+        const init = { method, headers };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        const res = await fetch(url, init);
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(err.error || `API error: ${res.status}`);
+        }
+        return res.json();
+    }
+    async startSignup(data) {
+        return this.publicRequest('POST', '/api/v1/signup', data);
+    }
+    async getSignupSession(sessionId) {
+        return this.publicRequest('GET', `/api/v1/signup/sessions/${encodeURIComponent(sessionId)}`);
+    }
     async whoami() {
         return this.request('GET', '/whoami');
     }
@@ -56,6 +83,13 @@ export class PosterlyClient {
             : '/connect';
         return this.request('GET', `${path}${qs ? `?${qs}` : ''}`);
     }
+    async createConnectSession(data) {
+        const { platform, ...body } = data;
+        return this.request('POST', `/connect/${encodeURIComponent(platform)}/sessions`, body);
+    }
+    async getConnectSession(sessionId) {
+        return this.request('GET', `/connect/sessions/${encodeURIComponent(sessionId)}`);
+    }
     async listOAuthClients() {
         return this.request('GET', '/oauth/clients');
     }
@@ -304,6 +338,7 @@ export class PosterlyClient {
         });
     }
     async uploadMedia(input) {
+        this.requireApiKey();
         let fileBuffer;
         if (input.filePath) {
             fileBuffer = await readFile(resolve(input.filePath));

package/dist/lib/format.d.ts

@@ -0,0 +1,11 @@
+import type { Account, Post } from './api-client.js';
+export declare const DASHBOARD_CALENDAR_URL: string;
+export declare const DASHBOARD_TABLE_URL: string;
+export declare const DASHBOARD_CONNECT_URL: string;
+export declare function formatLocalDateTime(value?: string | null): string;
+export declare function dashboardUrlForPost(post: Pick<Post, 'id' | 'scheduled_at'>): string;
+export declare function dashboardUrlForPosts(): string;
+export declare function dashboardUrlForPostList(posts: Array<Pick<Post, 'scheduled_at'>>): string;
+export declare function truncateText(value: string | null | undefined, max?: number): string;
+export declare function formatAccountLabel(account: Account): string;
+export declare function formatConnectedAccounts(accounts?: Account[]): string;

package/dist/lib/format.js

@@ -0,0 +1,51 @@
+const POSTERLY_APP_URL = (process.env.POSTERLY_URL || 'https://www.poster.ly').replace(/\/$/, '');
+export const DASHBOARD_CALENDAR_URL = `${POSTERLY_APP_URL}/dashboard/calendar`;
+export const DASHBOARD_TABLE_URL = `${POSTERLY_APP_URL}/dashboard/table`;
+export const DASHBOARD_CONNECT_URL = `${POSTERLY_APP_URL}/dashboard/connect`;
+export function formatLocalDateTime(value) {
+    if (!value)
+        return 'N/A';
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value;
+    return date.toLocaleString();
+}
+export function dashboardUrlForPost(post) {
+    const baseUrl = isInCurrentMonth(post.scheduled_at) ? DASHBOARD_CALENDAR_URL : DASHBOARD_TABLE_URL;
+    const url = new URL(baseUrl);
+    url.searchParams.set('post_id', String(post.id));
+    return url.toString();
+}
+export function dashboardUrlForPosts() {
+    return DASHBOARD_TABLE_URL;
+}
+export function dashboardUrlForPostList(posts) {
+    if (posts.length > 0 && posts.every((post) => isInCurrentMonth(post.scheduled_at))) {
+        return DASHBOARD_CALENDAR_URL;
+    }
+    return DASHBOARD_TABLE_URL;
+}
+export function truncateText(value, max = 80) {
+    const text = value?.trim() || '';
+    if (!text)
+        return '(empty)';
+    return text.length > max ? `${text.slice(0, max - 1)}...` : text;
+}
+export function formatAccountLabel(account) {
+    const username = account.username ? `@${account.username}` : `account ${account.id}`;
+    return `${account.platform} ${username}`;
+}
+export function formatConnectedAccounts(accounts) {
+    if (!accounts?.length)
+        return 'none yet';
+    return accounts.map(formatAccountLabel).join(', ');
+}
+function isInCurrentMonth(value) {
+    if (!value)
+        return false;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return false;
+    const now = new Date();
+    return date.getFullYear() === now.getFullYear() && date.getMonth() === now.getMonth();
+}

package/dist/tools/create-connect-session.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const createConnectSessionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        platform: z.ZodEnum<["bluesky", "devto", "discord", "facebook", "facebook_instagram", "facebook_pages", "gmb", "google-business", "google_business", "google_business_profile", "hashnode", "instagram", "instagram-standalone", "instagram_direct", "linkedin", "linkedin-company", "linkedin-page", "linkedin_company", "linkedin_page", "linkedin_personal", "mastodon", "medium", "meta", "meta_business", "pinterest", "reddit", "skool", "slack", "telegram", "threads", "tiktok", "twitter", "whop", "wordpress", "x", "x_twitter", "youtube"]>;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        auto_start: z.ZodOptional<z.ZodBoolean>;
+        debug: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        platform: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "linkedin" | "youtube" | "pinterest" | "threads" | "google_business" | "telegram" | "bluesky" | "reddit" | "wordpress" | "mastodon" | "medium" | "devto" | "hashnode" | "discord" | "slack" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "x" | "meta" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "instagram_direct" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        workspace_id?: string | undefined;
+        auto_start?: boolean | undefined;
+        debug?: boolean | undefined;
+    }, {
+        platform: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "linkedin" | "youtube" | "pinterest" | "threads" | "google_business" | "telegram" | "bluesky" | "reddit" | "wordpress" | "mastodon" | "medium" | "devto" | "hashnode" | "discord" | "slack" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "x" | "meta" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "instagram_direct" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        workspace_id?: string | undefined;
+        auto_start?: boolean | undefined;
+        debug?: boolean | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        platform: string;
+        workspace_id?: string;
+        auto_start?: boolean;
+        debug?: boolean;
+    }): Promise<string>;
+};

package/dist/tools/create-connect-session.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { DASHBOARD_CONNECT_URL, formatConnectedAccounts, formatLocalDateTime } from '../lib/format.js';
+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.',
+    inputSchema: z.object({
+        platform: z
+            .enum(CONNECT_INPUTS)
+            .describe('Connection target such as instagram, meta, linkedin_page, twitter, google_business, telegram, or bluesky.'),
+        workspace_id: z
+            .string()
+            .optional()
+            .describe('Workspace to connect the account into. Workspace-scoped API keys ignore this.'),
+        auto_start: z
+            .boolean()
+            .optional()
+            .describe('When true, the dashboard starts the provider flow after the user opens the URL. Defaults to true.'),
+        debug: z
+            .boolean()
+            .optional()
+            .describe('When true, include the raw connect session JSON for debugging. Keep false for normal user-facing agent flows.'),
+    }),
+    async execute(client, input) {
+        const { debug, ...payload } = input;
+        const result = await client.createConnectSession(payload);
+        return formatConnectSession(result.connect_session, Boolean(debug));
+    },
+};
+function formatConnectSession(session, includeRaw) {
+    const connected = session.connected_count ?? session.connected_accounts?.length ?? 0;
+    return [
+        `Posterly connect session created: ${session.id}`,
+        `Platform: ${session.platform}`,
+        `Status: ${session.status}`,
+        `Message: ${session.status_message}`,
+        `Secure connection URL: ${session.connect_url}`,
+        `Poll URL: ${session.poll_url}`,
+        `Connected accounts: ${connected}`,
+        `Accounts: ${formatConnectedAccounts(session.connected_accounts)}`,
+        `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.',
+        includeRaw ? `\nRaw connect session:\n${JSON.stringify(session, null, 2)}` : '',
+    ].filter(Boolean).join('\n');
+}