posterly-mcp-server 0.19.4 → 0.19.6

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.0` exposes 49 tools:
+`posterly-mcp-server@0.19.6` 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.6',
 });
-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

@@ -165,8 +165,10 @@ export interface AccountAnalyticsSummary {
     total_likes?: number | null;
     platform_metrics?: Record<string, number | null | undefined>;
     display_metrics?: Array<{
+        key?: string;
         label: string;
         value: number | null | undefined;
+        unit?: string;
     }>;
 }
 export interface AccountAnalyticsSnapshot {
@@ -346,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;
@@ -358,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;
@@ -399,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;
@@ -413,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/tools/create-connect-session.d.ts

@@ -0,0 +1,24 @@
+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>;
+    }, "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;
+    }, {
+        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;
+    }>;
+    execute(client: PosterlyClient, input: {
+        platform: string;
+        workspace_id?: string;
+        auto_start?: boolean;
+    }): Promise<string>;
+};

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

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+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. Open connect_session.connect_url for the user, then poll get_connect_session to narrate progress.',
+    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.'),
+    }),
+    async execute(client, input) {
+        const result = await client.createConnectSession(input);
+        return formatConnectSession(result.connect_session, true);
+    },
+};
+function formatConnectSession(session, includeRaw) {
+    return [
+        `Posterly connect session: ${session.id}`,
+        `Platform: ${session.platform}`,
+        `Status: ${session.status}`,
+        `Message: ${session.status_message}`,
+        `Connection URL: ${session.connect_url}`,
+        `Poll URL: ${session.poll_url}`,
+        `Connected accounts: ${session.connected_count ?? session.connected_accounts?.length ?? 0}`,
+        `Expires: ${session.expires_at}`,
+        '',
+        'Next step: Open the connection URL for the user, then call get_connect_session with this session ID until the status is terminal.',
+        includeRaw ? `\nRaw connect session:\n${JSON.stringify(session, null, 2)}` : '',
+    ].filter(Boolean).join('\n');
+}

package/dist/tools/create-webhook.d.ts

@@ -14,15 +14,15 @@ export declare const createWebhookTool: {
         url: string;
         confirm: true;
         workspace_id?: string | undefined;
-        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced")[] | undefined;
         description?: string | undefined;
+        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced")[] | undefined;
         is_active?: boolean | undefined;
     }, {
         url: string;
         confirm: true;
         workspace_id?: string | undefined;
-        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced")[] | undefined;
         description?: string | undefined;
+        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced")[] | undefined;
         is_active?: boolean | undefined;
     }>;
     execute(client: PosterlyClient, input: {

package/dist/tools/generate-image.d.ts

@@ -15,14 +15,14 @@ export declare const generateImageTool: {
         aspect_ratio?: "16:9" | "9:16" | "1:1" | "4:5" | "3:4" | "2:3" | "1:4" | "1:8" | "21:9" | "4:3" | "3:2" | "4:1" | "8:1" | "5:4" | undefined;
         style?: "professional" | "photographic" | "illustration" | "minimal" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "flash" | "pro" | undefined;
+        model?: "pro" | "flash" | undefined;
         resolution?: "512" | "1K" | "2K" | "4K" | undefined;
     }, {
         prompt: string;
         aspect_ratio?: "16:9" | "9:16" | "1:1" | "4:5" | "3:4" | "2:3" | "1:4" | "1:8" | "21:9" | "4:3" | "3:2" | "4:1" | "8:1" | "5:4" | undefined;
         style?: "professional" | "photographic" | "illustration" | "minimal" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "flash" | "pro" | undefined;
+        model?: "pro" | "flash" | undefined;
         resolution?: "512" | "1K" | "2K" | "4K" | undefined;
     }>;
     execute(client: PosterlyClient, input: {

package/dist/tools/get-account-analytics.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+declare const presentationSchema: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
+type AnalyticsPresentation = z.infer<typeof presentationSchema>;
 export declare const getAccountAnalyticsTool: {
     name: string;
     description: string;
@@ -7,18 +9,23 @@ export declare const getAccountAnalyticsTool: {
         account_id: z.ZodNumber;
         from: z.ZodOptional<z.ZodString>;
         to: z.ZodOptional<z.ZodString>;
+        presentation: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
     }, "strip", z.ZodTypeAny, {
         account_id: number;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }, {
         account_id: number;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         account_id: number;
         from?: string;
         to?: string;
+        presentation?: AnalyticsPresentation;
     }): Promise<string>;
 };
+export {};