posterly-mcp-server 0.19.4 → 0.19.6

package/dist/tools/start-signup.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import type { PosterlyClient, PublicSignupTier } from '../lib/api-client.js';
+export declare const startSignupTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        tier: z.ZodDefault<z.ZodEnum<["starter", "pro", "power_user", "agency"]>>;
+        interval: z.ZodDefault<z.ZodEnum<["month"]>>;
+        api_addon: z.ZodDefault<z.ZodBoolean>;
+        return_path: z.ZodDefault<z.ZodString>;
+        source: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        email: string;
+        tier: "starter" | "pro" | "power_user" | "agency";
+        interval: "month";
+        api_addon: boolean;
+        return_path: string;
+        source: string;
+        name?: string | undefined;
+    }, {
+        email: string;
+        name?: string | undefined;
+        tier?: "starter" | "pro" | "power_user" | "agency" | undefined;
+        interval?: "month" | undefined;
+        api_addon?: boolean | undefined;
+        return_path?: string | undefined;
+        source?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        email: string;
+        name?: string;
+        tier?: PublicSignupTier;
+        interval?: "month";
+        api_addon?: boolean;
+        return_path?: string;
+        source?: string;
+    }): Promise<string>;
+};

package/dist/tools/start-signup.js

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+const DEFAULT_RETURN_PATH = '/dashboard/api?api_signup=success';
+export const startSignupTool = {
+    name: 'start_signup',
+    description: 'Start the public Posterly paid signup flow for a user before Posterly API access exists. Returns a Posterly checkout handoff URL and signup poll URL. The user must handle payment and password setup in the browser.',
+    inputSchema: z.object({
+        email: z
+            .string()
+            .email()
+            .describe('User email address to sign up. Confirm this with the user before calling.'),
+        name: z
+            .string()
+            .optional()
+            .describe('Optional user or workspace name to pass into Posterly signup.'),
+        tier: z
+            .enum(['starter', 'pro', 'power_user', 'agency'])
+            .default('starter')
+            .describe('Posterly plan to start. Use starter unless the user explicitly chooses another plan.'),
+        interval: z
+            .enum(['month'])
+            .default('month')
+            .describe('Billing interval. Public agent signup currently supports monthly billing.'),
+        api_addon: z
+            .boolean()
+            .default(true)
+            .describe('Always true for AI agent setup because MCP/API access requires the API add-on.'),
+        return_path: z
+            .string()
+            .default(DEFAULT_RETURN_PATH)
+            .describe('Where Posterly should continue after checkout and password setup.'),
+        source: z
+            .string()
+            .default('posterly_mcp_pre_auth_signup')
+            .describe('Source label for analytics and support diagnostics.'),
+    }),
+    async execute(client, input) {
+        const response = await client.startSignup({
+            email: input.email,
+            name: input.name,
+            tier: input.tier ?? 'starter',
+            interval: input.interval ?? 'month',
+            api_addon: input.api_addon ?? true,
+            return_path: input.return_path ?? DEFAULT_RETURN_PATH,
+            source: input.source ?? 'posterly_mcp_pre_auth_signup',
+        });
+        return formatSignupStart(response);
+    },
+};
+function valueFromLinks(response, key) {
+    const links = response.signup_session?.links ?? response.links;
+    const value = links?.[key];
+    return typeof value === 'string' ? value : null;
+}
+function formatSignupStart(response) {
+    const session = response.signup_session;
+    const sessionId = session?.id || response.checkout_session_id;
+    const checkoutUrl = response.checkout_url || valueFromLinks(response, 'checkout_url');
+    const checkoutRedirectUrl = response.checkout_redirect_url || session?.checkout_redirect_url || valueFromLinks(response, 'checkout_redirect_url');
+    const pollUrl = response.poll_url || valueFromLinks(response, 'poll_url');
+    const completeUrl = response.complete_url || valueFromLinks(response, 'complete_url');
+    const status = session?.status || response.status || 'checkout_pending';
+    const message = session?.status_message || response.status_message;
+    const lines = [
+        'Posterly signup started.',
+        sessionId ? `Signup session: ${sessionId}` : '',
+        `Status: ${status}`,
+        message ? `Message: ${message}` : '',
+        checkoutRedirectUrl ? `Checkout handoff URL: ${checkoutRedirectUrl}` : '',
+        checkoutUrl ? `Checkout URL: ${checkoutUrl}` : '',
+        pollUrl ? `Poll URL: ${pollUrl}` : '',
+        completeUrl ? `Completion URL: ${completeUrl}` : '',
+        '',
+        'Next steps for the AI agent:',
+        '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.',
+        '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.',
+        '5. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
+        '',
+        `Raw signup response:\n${JSON.stringify(response, null, 2)}`,
+    ];
+    return lines.filter(Boolean).join('\n');
+}

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

@@ -16,16 +16,16 @@ export declare const updateWebhookTool: {
         webhook_id: string;
         workspace_id?: string | null | undefined;
         url?: string | undefined;
-        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced")[] | undefined;
         description?: string | null | 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;
     }, {
         confirm: true;
         webhook_id: string;
         workspace_id?: string | null | undefined;
         url?: string | undefined;
-        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced")[] | undefined;
         description?: string | null | 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.19.4",
+  "version": "0.19.6",
   "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
   "license": "MIT",
   "homepage": "https://www.poster.ly/mcp",

package/src/index.ts

@@ -3,6 +3,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';
@@ -48,6 +51,8 @@ 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';
@@ -55,19 +60,54 @@ import { deleteOAuthClientTool } from './tools/delete-oauth-client.js';
 
 const server = new McpServer({
   name: 'posterly',
-  version: '0.19.0',
+  version: '0.19.6',
 });
 
-let client: PosterlyClient;
-
-try {
-  client = new PosterlyClient();
-} catch (err: any) {
-  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' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, 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 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(
+  getSignupSessionTool.name,
+  getSignupSessionTool.description,
+  getSignupSessionTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await getSignupSessionTool.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(
   whoamiTool.name,
   whoamiTool.description,
@@ -124,6 +164,34 @@ server.tool(
   }
 );
 
+server.tool(
+  createConnectSessionTool.name,
+  createConnectSessionTool.description,
+  createConnectSessionTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await createConnectSessionTool.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(
+  getConnectSessionTool.name,
+  getConnectSessionTool.description,
+  getConnectSessionTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await getConnectSessionTool.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(
   listOAuthClientsTool.name,
   listOAuthClientsTool.description,

package/src/lib/api-client.ts

@@ -152,7 +152,7 @@ export interface AccountAnalyticsSummary {
   total_watch_minutes?: number | null;
   total_likes?: number | null;
   platform_metrics?: Record<string, number | null | undefined>;
-  display_metrics?: Array<{ label: string; value: number | null | undefined }>;
+  display_metrics?: Array<{ key?: string; label: string; value: number | null | undefined; unit?: string }>;
 }
 
 export interface AccountAnalyticsSnapshot {
@@ -328,6 +328,35 @@ export interface ConnectOption {
   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;
@@ -341,6 +370,60 @@ export interface OAuthDeveloperClient {
   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;
@@ -387,9 +470,17 @@ export class PosterlyClient {
   constructor(apiKey?: string, baseUrl?: string) {
     this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
     this.baseUrl = (baseUrl || process.env.POSTERLY_URL || 'https://www.poster.ly').replace(/\/$/, '');
+  }
 
+  hasApiKey(): boolean {
+    return Boolean(this.apiKey);
+  }
+
+  private requireApiKey(): void {
     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.'
+      );
     }
   }
 
@@ -398,6 +489,8 @@ export class PosterlyClient {
     path: string,
     body?: unknown,
   ): Promise<T> {
+    this.requireApiKey();
+
     const url = `${this.baseUrl}/api/v1${path}`;
     const headers: Record<string, string> = {
       Authorization: `Bearer ${this.apiKey}`,
@@ -422,6 +515,38 @@ export class PosterlyClient {
     return res.json() as Promise<T>;
   }
 
+  private async publicRequest<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {};
+    const init: RequestInit = { 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() as Promise<T>;
+  }
+
+  async startSignup(data: PublicSignupPayload): Promise<PublicSignupResponse> {
+    return this.publicRequest('POST', '/api/v1/signup', data);
+  }
+
+  async getSignupSession(sessionId: string): Promise<PublicSignupSessionResponse> {
+    return this.publicRequest('GET', `/api/v1/signup/sessions/${encodeURIComponent(sessionId)}`);
+  }
+
   async whoami(): Promise<Whoami> {
     return this.request<Whoami>('GET', '/whoami');
   }
@@ -453,6 +578,19 @@ export class PosterlyClient {
     return this.request('GET', `${path}${qs ? `?${qs}` : ''}`);
   }
 
+  async createConnectSession(data: {
+    platform: string;
+    workspace_id?: string;
+    auto_start?: boolean;
+  }): Promise<{ connect_session: ConnectSession; connect?: ConnectOption }> {
+    const { platform, ...body } = data;
+    return this.request('POST', `/connect/${encodeURIComponent(platform)}/sessions`, body);
+  }
+
+  async getConnectSession(sessionId: string): Promise<{ connect_session: ConnectSession }> {
+    return this.request('GET', `/connect/sessions/${encodeURIComponent(sessionId)}`);
+  }
+
   async listOAuthClients(): Promise<{ clients: OAuthDeveloperClient[] }> {
     return this.request('GET', '/oauth/clients');
   }
@@ -879,6 +1017,8 @@ export class PosterlyClient {
     filename: string;
     contentType?: string;
   }): Promise<{ url: string; path: string }> {
+    this.requireApiKey();
+
     let fileBuffer: Buffer;
 
     if (input.filePath) {

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

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import type { ConnectSession, PosterlyClient } from '../lib/api-client.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. 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: PosterlyClient,
+    input: { platform: string; workspace_id?: string; auto_start?: boolean },
+  ) {
+    const result = await client.createConnectSession(input);
+    return formatConnectSession(result.connect_session, true);
+  },
+};
+
+function formatConnectSession(session: ConnectSession, includeRaw: boolean): string {
+  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');
+}