posterly-mcp-server 0.33.3 → 0.35.0

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.33.3` exposes 77 tools.
+`posterly-mcp-server@0.35.0` exposes 78 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -137,6 +137,7 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `list_accounts`
 - `disconnect_account` (disconnect a connected social account after explicit confirmation)
 - `get_connect_link`
+- `connect_account` (connect a credential-based account: telegram, bluesky, discord, wordpress, devto, hashnode, lemmy; no browser session needed)
 - `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)
 - `create_api_key` (create a new API key after explicit confirmation; scopes cannot exceed the calling dashboard key)

package/RELEASING.md

@@ -0,0 +1,103 @@
+# Releasing the MCP surfaces
+
+posterly has two MCP surfaces sharing one version namespace:
+
+| Surface | Where it lives | How it reaches users |
+| --- | --- | --- |
+| Hosted HTTP | `lib/mcp/` → `POST /api/mcp` | **Automatically**, with the Vercel deploy of `main` |
+| npm stdio | `mcp-server/src/` → `posterly-mcp-server` | **Only when someone runs `npm publish`** |
+
+That asymmetry is the whole reason this file exists.
+
+## The failure this prevents
+
+The docs tell users to install with `npx -y posterly-mcp-server@latest`, so most
+MCP traffic is the npm package. The package is a thin client over `/api/v1/*`,
+which makes it tempting to assume a server-side fix reaches everyone. It does
+not. **The npm package does its own output formatting**, so anything the client
+renders itself stays broken until a publish:
+
+- tool output formatting (truncation, row caps, what columns are shown)
+- input schemas (new parameters like `limit` / `offset`)
+- tool descriptions and names
+
+This is not hypothetical. In Aug 2026 the Google Business review truncation was
+fixed server-side and merged. Hosted users got the fix on deploy. npm users kept
+seeing reviews clipped to ~180 characters, capped at 25 rows, with no dates —
+because that formatting lives in `mcp-server/src/tools/`. Only a publish fixed it.
+
+## Release order
+
+```
+change an MCP surface -> bump the version -> merge -> deploy -> npm publish
+```
+
+Bumping and publishing are separate steps with different failure modes:
+
+- **Skipping the bump is unrecoverable.** npm versions are immutable. Tool
+  changes merged under a version already on npm can never be delivered under
+  that version. `npm run check:mcp-version-bump` fails the build to prevent it.
+- **Skipping the publish is recoverable** — just publish. `npm run
+  check:mcp-published` tells you when one is outstanding.
+
+## 1. Bump the version
+
+The version appears in six places and `npm run check:mcp-parity` enforces that
+they all agree:
+
+- `lib/mcp/version.ts` — hosted endpoint
+- `mcp-server/src/lib/version.ts` — stdio package
+- `mcp-server/package.json`
+- `mcp-server/package-lock.json` (two entries)
+- `mcp-server/server.json` (two entries)
+- `mcp-server/README.md` — the `posterly-mcp-server@X.Y.Z exposes N tools` line
+
+Then rebuild so the compiled output matches, since the parity check reads
+`mcp-server/dist/lib/version.js` too:
+
+```bash
+npm --prefix mcp-server run build
+npm run check:mcp-parity
+```
+
+Use a patch bump for tool fixes and additive schema changes; a minor bump for
+new tools or a changed tool surface.
+
+## 2. Merge and deploy
+
+Land the PR and let `main` deploy. The hosted endpoint is live at this point;
+npm users are not.
+
+## 3. Publish
+
+```bash
+cd mcp-server
+npm whoami          # must be an account that can publish posterly-mcp-server
+npm publish         # add --otp=<code> if 2FA prompts
+```
+
+`prepack` rebuilds `dist/` and re-runs the parity check before packing, so a
+stale build or a drifted version cannot ship. `dist/` is gitignored but is
+included in the tarball — `prepack` is what puts it there.
+
+Sanity-check the tarball first if you want:
+
+```bash
+npm pack --dry-run
+```
+
+## 4. Verify
+
+```bash
+npm view posterly-mcp-server version dist-tags
+npm run check:mcp-published
+```
+
+Both should report the version you just published. Users on `@latest` pick it
+up on their next client restart; there is nothing for them to do.
+
+## If you published something broken
+
+Do not `npm unpublish` and do not republish the same number — npm versions are
+immutable and unpublishing breaks anyone who already resolved it. Cut the next
+patch version and publish that.

package/dist/index.js

@@ -67,6 +67,7 @@ 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 { connectAccountTool } from './tools/connect-account.js';
 import { createConnectSessionTool } from './tools/create-connect-session.js';
 import { getConnectSessionTool } from './tools/get-connect-session.js';
 import { createApiKeyTool } from './tools/create-api-key.js';
@@ -159,6 +160,15 @@ server.tool(getConnectLinkTool.name, getConnectLinkTool.description, getConnectL
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(connectAccountTool.name, connectAccountTool.description, connectAccountTool.inputSchema.shape, getToolAnnotations(connectAccountTool.name), async (input) => {
+    try {
+        const text = await connectAccountTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(createConnectSessionTool.name, createConnectSessionTool.description, createConnectSessionTool.inputSchema.shape, getToolAnnotations(createConnectSessionTool.name), async (input) => {
     try {
         const text = await createConnectSessionTool.execute(client, input);

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

@@ -738,6 +738,16 @@ export interface ConnectSession {
     completed_at?: string | null;
     expires_at: string;
 }
+export interface ConnectAccountCredentialsResponse {
+    connected: boolean;
+    account: {
+        id: number;
+        platform: string;
+        username: string;
+        [extra: string]: unknown;
+    };
+    workspace_id: string;
+}
 export interface OAuthDeveloperClient {
     id: string;
     client_id: string;
@@ -802,6 +812,7 @@ export interface PublicSignupSessionResponse {
 export interface VideoJob {
     id: string;
     status: string;
+    provider: 'google' | 'xai';
     prompt: string;
     model: string;
     duration_seconds: number;
@@ -890,6 +901,12 @@ export declare class PosterlyClient {
     getConnectSession(sessionId: string): Promise<{
         connect_session: ConnectSession;
     }>;
+    connectAccountCredentials(data: {
+        platform: string;
+        credentials: Record<string, string>;
+        workspace_id?: string;
+        connect_session_id?: string;
+    }): Promise<ConnectAccountCredentialsResponse>;
     listOAuthClients(): Promise<{
         clients: OAuthDeveloperClient[];
     }>;
@@ -999,8 +1016,10 @@ export declare class PosterlyClient {
         aspect_ratio?: string;
         style?: string;
         variations?: number;
+        provider?: 'google' | 'xai';
         model?: 'lite' | 'flash' | 'pro';
         resolution?: '512' | '1K' | '2K' | '4K';
+        quality?: 'low' | 'medium';
     }): Promise<{
         urls: string[];
         images: Array<{
@@ -1009,6 +1028,7 @@ export declare class PosterlyClient {
             path: string;
         }>;
         model: string;
+        provider: 'google' | 'xai';
         credits_used: number;
         warnings?: string[];
         usage: {
@@ -1026,11 +1046,12 @@ export declare class PosterlyClient {
         params?: Record<string, unknown>;
     }): Promise<Record<string, any>>;
     generateVideo(data: {
+        provider?: 'google' | 'xai';
         prompt: string;
         negative_prompt?: string;
-        aspect_ratio?: '16:9' | '9:16';
-        duration_seconds?: 4 | 6 | 8;
-        resolution?: '720p' | '1080p';
+        aspect_ratio?: '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3';
+        duration_seconds?: number;
+        resolution?: '480p' | '720p' | '1080p';
         model?: 'lite' | 'fast' | 'standard';
         image_url?: string;
         end_image_url?: string;

package/dist/lib/api-client.js

@@ -170,6 +170,15 @@ export class PosterlyClient {
     async getConnectSession(sessionId) {
         return this.request('GET', `/connect/sessions/${encodeURIComponent(sessionId)}`);
     }
+    async connectAccountCredentials(data) {
+        const { platform, credentials, workspace_id, connect_session_id } = data;
+        const body = { credentials };
+        if (workspace_id)
+            body.workspace_id = workspace_id;
+        if (connect_session_id)
+            body.connect_session_id = connect_session_id;
+        return this.request('POST', `/connect/${encodeURIComponent(platform)}/credentials`, body);
+    }
     async listOAuthClients() {
         return this.request('GET', '/oauth/clients');
     }

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.33.3";
+export declare const POSTERLY_MCP_VERSION = "0.35.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.33.3';
+export const POSTERLY_MCP_VERSION = '0.35.0';

package/dist/tools/connect-account.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+declare const CREDENTIAL_PLATFORMS: readonly ["telegram", "bluesky", "discord", "wordpress", "devto", "hashnode", "lemmy"];
+export declare const connectAccountTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        platform: z.ZodEnum<["telegram", "bluesky", "discord", "wordpress", "devto", "hashnode", "lemmy"]>;
+        bot_token: z.ZodOptional<z.ZodString>;
+        chat_id: z.ZodOptional<z.ZodString>;
+        handle: z.ZodOptional<z.ZodString>;
+        app_password: z.ZodOptional<z.ZodString>;
+        webhook_url: z.ZodOptional<z.ZodString>;
+        site_url: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        api_key: z.ZodOptional<z.ZodString>;
+        pat: z.ZodOptional<z.ZodString>;
+        instance: z.ZodOptional<z.ZodString>;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        connect_session_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        platform: "telegram" | "bluesky" | "discord" | "devto" | "hashnode" | "wordpress" | "lemmy";
+        username?: string | undefined;
+        workspace_id?: string | undefined;
+        connect_session_id?: string | undefined;
+        handle?: string | undefined;
+        bot_token?: string | undefined;
+        chat_id?: string | undefined;
+        app_password?: string | undefined;
+        webhook_url?: string | undefined;
+        site_url?: string | undefined;
+        api_key?: string | undefined;
+        pat?: string | undefined;
+        instance?: string | undefined;
+        password?: string | undefined;
+    }, {
+        platform: "telegram" | "bluesky" | "discord" | "devto" | "hashnode" | "wordpress" | "lemmy";
+        username?: string | undefined;
+        workspace_id?: string | undefined;
+        connect_session_id?: string | undefined;
+        handle?: string | undefined;
+        bot_token?: string | undefined;
+        chat_id?: string | undefined;
+        app_password?: string | undefined;
+        webhook_url?: string | undefined;
+        site_url?: string | undefined;
+        api_key?: string | undefined;
+        pat?: string | undefined;
+        instance?: string | undefined;
+        password?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        platform: (typeof CREDENTIAL_PLATFORMS)[number];
+        workspace_id?: string;
+        connect_session_id?: string;
+    } & Record<string, string | undefined>): Promise<string>;
+};
+export {};

package/dist/tools/connect-account.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+const CREDENTIAL_PLATFORMS = [
+    'telegram',
+    'bluesky',
+    'discord',
+    'wordpress',
+    'devto',
+    'hashnode',
+    'lemmy',
+];
+/**
+ * Per-platform credential field whitelist. Duplicated in the hosted tool
+ * (lib/mcp/http-tools.ts) on purpose: the platform manifest does not carry
+ * credential fields, and the v1 endpoint rejects unknown keys, so each tool
+ * must whitelist before building the credentials object. The MCP parity and
+ * payload checks guard the duplication.
+ */
+const PLATFORM_CREDENTIAL_FIELDS = {
+    telegram: ['bot_token', 'chat_id'],
+    bluesky: ['handle', 'app_password'],
+    discord: ['webhook_url'],
+    wordpress: ['site_url', 'username', 'app_password'],
+    devto: ['api_key'],
+    hashnode: ['pat'],
+    lemmy: ['instance', 'username', 'password'],
+};
+export const connectAccountTool = {
+    name: 'connect_account',
+    description: 'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call get_connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
+    inputSchema: z.object({
+        platform: z
+            .enum(CREDENTIAL_PLATFORMS)
+            .describe('Credential-based connection target: telegram, bluesky, discord, wordpress, devto, hashnode, or lemmy.'),
+        bot_token: z.string().optional().describe('Telegram: bot token from BotFather.'),
+        chat_id: z.string().optional().describe('Telegram: target channel or group chat ID.'),
+        handle: z.string().optional().describe('Bluesky: handle, for example posterly.bsky.social.'),
+        app_password: z.string().optional().describe('Bluesky: app password from account settings. WordPress: application password from wp-admin Users, Profile, Application Passwords.'),
+        webhook_url: z.string().optional().describe('Discord: channel webhook URL from channel settings, Integrations, Webhooks.'),
+        site_url: z.string().optional().describe('WordPress: site URL, e.g. https://blog.example.com.'),
+        username: z.string().optional().describe('WordPress: username the application password belongs to. Lemmy: username or email.'),
+        password: z.string().optional().describe('Lemmy: account password (TOTP-enabled accounts are not supported).'),
+        api_key: z.string().optional().describe('Dev.to: API key from Settings, Extensions, DEV Community API Keys.'),
+        pat: z.string().optional().describe('Hashnode: personal access token from Account Settings, Developer.'),
+        instance: z.string().optional().describe('Lemmy: instance domain, for example lemmy.world.'),
+        workspace_id: z.string().optional().describe('Workspace to connect the account into. Workspace-scoped API keys ignore this.'),
+        connect_session_id: z.string().optional().describe('Optional connect session ID to mark connected or failed based on the outcome.'),
+    }),
+    async execute(client, input) {
+        const allowedFields = PLATFORM_CREDENTIAL_FIELDS[input.platform] || [];
+        const credentials = {};
+        for (const field of allowedFields) {
+            const value = input[field];
+            if (typeof value === 'string' && value.trim()) {
+                credentials[field] = value;
+            }
+        }
+        const missing = allowedFields.filter((field) => !(field in credentials));
+        if (missing.length > 0) {
+            return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call get_connect_link with platform=${input.platform} to see field descriptions.`;
+        }
+        const result = await client.connectAccountCredentials({
+            platform: input.platform,
+            credentials,
+            workspace_id: input.workspace_id,
+            connect_session_id: input.connect_session_id,
+        });
+        const account = result.account || {};
+        const lines = [
+            `Connected ${input.platform} account: ${account.username || 'unknown'} (id ${account.id})`,
+            `Workspace: ${result.workspace_id}`,
+            'Reconnecting the same account updates it in place.',
+        ];
+        return lines.join('\n');
+    },
+};

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

@@ -9,12 +9,12 @@ export declare const createConnectSessionTool: {
         auto_start: z.ZodOptional<z.ZodBoolean>;
         debug: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "medium" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
         workspace_id?: string | undefined;
         auto_start?: boolean | undefined;
         debug?: boolean | undefined;
     }, {
-        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "medium" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
         workspace_id?: string | undefined;
         auto_start?: boolean | undefined;
         debug?: boolean | undefined;