posterly-mcp-server 0.28.0 → 0.30.0

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.27.0` exposes 75 tools.
+`posterly-mcp-server@0.30.0` exposes 76 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -180,6 +180,7 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `get_video_options`
 - `run_video_function` (read-only Veo helpers for cost estimation and request validation)
 - `generate_video` (queues a cost-guarded Veo video job)
+- `get_credits` (read-only AI credit balance)
 - `get_video_job` (poll one job or list recent jobs)
 - `get_account_analytics`
 - `get_post_analytics`

package/dist/index.js

@@ -70,6 +70,7 @@ import { createConnectSessionTool } from './tools/create-connect-session.js';
 import { getConnectSessionTool } from './tools/get-connect-session.js';
 import { createApiKeyTool } from './tools/create-api-key.js';
 import { deleteApiKeyTool } from './tools/delete-api-key.js';
+import { getCreditsTool } from './tools/get-credits.js';
 import { getSubscriptionTool } from './tools/get-subscription.js';
 import { cancelSubscriptionTool } from './tools/cancel-subscription.js';
 import { pauseSubscriptionTool } from './tools/pause-subscription.js';
@@ -193,6 +194,15 @@ server.tool(deleteApiKeyTool.name, deleteApiKeyTool.description, deleteApiKeyToo
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(getCreditsTool.name, getCreditsTool.description, getCreditsTool.inputSchema.shape, getToolAnnotations(getCreditsTool.name), async () => {
+    try {
+        const text = await getCreditsTool.execute(client);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(getSubscriptionTool.name, getSubscriptionTool.description, getSubscriptionTool.inputSchema.shape, getToolAnnotations(getSubscriptionTool.name), async () => {
     try {
         const text = await getSubscriptionTool.execute(client);

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

@@ -331,6 +331,26 @@ export type SubscriptionSummary = {
 export type SubscriptionSummaryResponse = {
     subscription: SubscriptionSummary;
 };
+export type CreditsSummaryResponse = {
+    credits: {
+        available: number;
+        included: {
+            monthly: number;
+            used: number;
+            remaining: number;
+        };
+        purchased_balance: number;
+        plan_tier: string;
+        is_trial: boolean;
+        period_start: string;
+        /** Null while trialing or on a plan with no included pool. */
+        resets_at: string | null;
+        workspace: {
+            role: string;
+            shared_wallet: boolean;
+        };
+    };
+};
 export type CancelSubscriptionPayload = {
     reason: string;
     feedback?: string;
@@ -791,6 +811,7 @@ export declare class PosterlyClient {
         confirm: true;
     }): Promise<DeleteApiKeyResponse>;
     getSubscription(): Promise<SubscriptionSummaryResponse>;
+    getCredits(): Promise<CreditsSummaryResponse>;
     cancelSubscription(data: CancelSubscriptionPayload): Promise<CancelSubscriptionResponse>;
     pauseSubscription(): Promise<PauseSubscriptionResponse>;
     resumeSubscription(): Promise<ResumeSubscriptionResponse>;
@@ -928,7 +949,7 @@ export declare class PosterlyClient {
         aspect_ratio?: string;
         style?: string;
         variations?: number;
-        model?: 'flash' | 'pro';
+        model?: 'lite' | 'flash' | 'pro';
         resolution?: '512' | '1K' | '2K' | '4K';
     }): Promise<{
         urls: string[];

package/dist/lib/api-client.js

@@ -125,6 +125,9 @@ export class PosterlyClient {
     async getSubscription() {
         return this.request('GET', '/subscription');
     }
+    async getCredits() {
+        return this.request('GET', '/credits');
+    }
     async cancelSubscription(data) {
         return this.request('POST', '/subscription/cancel', data);
     }

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.28.0";
+export declare const POSTERLY_MCP_VERSION = "0.30.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.28.0';
+export const POSTERLY_MCP_VERSION = '0.30.0';

package/dist/tools/create-post.js

@@ -151,12 +151,20 @@ export function buildCreatePostPayload(input) {
             },
         };
     }
-    if (!caption) {
-        throw new Error('caption is required (or pass `thread_posts` for an X/Threads thread)');
+    // Mirror the server rule (lib/api-v1-post-create.ts): a post needs a caption
+    // OR media, not a caption unconditionally. Requiring one here made every
+    // media-only post impossible from the npm client, most visibly Instagram and
+    // Facebook Stories, which carry no caption at all. The dashboard composer and
+    // the hosted MCP have always allowed it; only this package disagreed.
+    const hasMedia = Boolean(input.media_url) || (input.media_urls?.length ?? 0) > 0;
+    if (!caption && !hasMedia) {
+        throw new Error('Provide caption or media (or pass `thread_posts` for an X/Threads thread). Media-only posts are valid, for example an Instagram or Facebook Story.');
     }
     return {
         ...rest,
-        caption,
+        // The server treats a missing caption as empty content when media carries
+        // the post, so send '' rather than dropping the key.
+        caption: caption ?? '',
         post_type,
         ...(platform_settings || instagram_settings
             ? { settings: { ...(instagram_settings ? { __type: 'instagram', ...instagram_settings } : {}), ...(platform_settings || {}) } }

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

@@ -8,7 +8,7 @@ export declare const generateImageTool: {
         aspect_ratio: z.ZodOptional<z.ZodEnum<["1:1", "9:16", "4:5", "3:4", "2:3", "1:4", "1:8", "21:9", "16:9", "4:3", "3:2", "4:1", "8:1", "5:4"]>>;
         style: z.ZodOptional<z.ZodEnum<["photographic", "illustration", "minimal", "vibrant", "professional", "youtube_thumbnail", "reel_cover", "review_background"]>>;
         variations: z.ZodOptional<z.ZodNumber>;
-        model: z.ZodOptional<z.ZodEnum<["flash", "pro"]>>;
+        model: z.ZodOptional<z.ZodEnum<["lite", "flash", "pro"]>>;
         resolution: z.ZodOptional<z.ZodEnum<["512", "1K", "2K", "4K"]>>;
         confirm: z.ZodLiteral<true>;
     }, "strip", z.ZodTypeAny, {
@@ -17,7 +17,7 @@ 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?: "minimal" | "professional" | "photographic" | "illustration" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "pro" | "flash" | undefined;
+        model?: "pro" | "lite" | "flash" | undefined;
         resolution?: "512" | "1K" | "2K" | "4K" | undefined;
     }, {
         confirm: true;
@@ -25,7 +25,7 @@ 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?: "minimal" | "professional" | "photographic" | "illustration" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "pro" | "flash" | undefined;
+        model?: "pro" | "lite" | "flash" | undefined;
         resolution?: "512" | "1K" | "2K" | "4K" | undefined;
     }>;
     execute(client: PosterlyClient, input: {
@@ -33,7 +33,7 @@ export declare const generateImageTool: {
         aspect_ratio?: string;
         style?: string;
         variations?: number;
-        model?: "flash" | "pro";
+        model?: "lite" | "flash" | "pro";
         resolution?: "512" | "1K" | "2K" | "4K";
         confirm: true;
     }): Promise<string>;

package/dist/tools/generate-image.js

@@ -38,13 +38,13 @@ export const generateImageTool = {
             .optional()
             .describe('How many variations to generate. Default 1. Each variation costs credits separately - prefer 1 unless the user explicitly wants options.'),
         model: z
-            .enum(['flash', 'pro'])
+            .enum(['lite', 'flash', 'pro'])
             .optional()
-            .describe('flash (default, 1 credit per 1K image) is fast and cost-effective. pro (2 credits per 1K) is higher quality for hero imagery. Start with flash unless quality is critical.'),
+            .describe('lite (8 credits, 1K only) is the cheapest and suits drafts and exploration. flash (default, 15 credits at 1K) balances quality and cost. pro (30 credits at 1K) is highest quality for hero imagery. Start with lite or flash unless quality is critical.'),
         resolution: z
             .enum(['512', '1K', '2K', '4K'])
             .optional()
-            .describe('Output resolution. Default 1K. Higher resolutions cost more credits. 512 is flash-only.'),
+            .describe('Output resolution. Default 1K. Higher resolutions cost more credits (flash: 10/15/23/35 for 512/1K/2K/4K; pro: 30 at 1K-2K, 55 at 4K). 512 is flash-only and lite supports 1K only.'),
         confirm: z.literal(true).describe('Must be true after explicit user confirmation of subject, style, aspect ratio, and credit use.'),
     }),
     async execute(client, input) {

package/dist/tools/get-credits.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getCreditsTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    execute(client: PosterlyClient): Promise<string>;
+};

package/dist/tools/get-credits.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+function formatCredits(result) {
+    const c = result.credits;
+    const inc = c.included;
+    return [
+        mdTitle('posterly AI credits'),
+        mdSection('Balance', mdKeyValue([
+            ['Available now', String(c.available)],
+            ['Included this period', `${inc.remaining} of ${inc.monthly} left (${inc.used} used)`],
+            ['Purchased packs', String(c.purchased_balance)],
+        ])),
+        mdSection('Plan', mdKeyValue([
+            ['Tier', c.plan_tier || 'unknown'],
+            ['Trial', c.is_trial ? 'yes' : 'no'],
+            [
+                'Included pool resets',
+                c.resets_at ? formatDateTime(c.resets_at) : 'no monthly reset (trial or no included pool)',
+            ],
+            ['Your workspace role', c.workspace?.role || 'unknown'],
+        ])),
+        "Credits are a shared workspace wallet: every active member draws the same pool, and packs are added to the billing owner's balance.",
+    ].join('\n\n');
+}
+export const getCreditsTool = {
+    name: 'get_credits',
+    description: "Get the authenticated user's posterly AI credit balance: what is available to spend now, how much of the monthly included allowance is left, purchased pack balance, plan tier, and when the included pool next resets. Credits are a shared WORKSPACE wallet, so this reports the balance the caller can actually spend, not a personal figure. Read-only, spends nothing. Requires the billing:read scope.",
+    inputSchema: z.object({}),
+    async execute(client) {
+        const result = await client.getCredits();
+        return formatCredits(result);
+    },
+};

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

@@ -34,10 +34,12 @@ declare const instagramSettingsSchema: z.ZodObject<{
     first_comment: z.ZodOptional<z.ZodString>;
     media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     reel_cover_url: z.ZodOptional<z.ZodString>;
+    reel_cover_method: z.ZodOptional<z.ZodString>;
     reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     post_type?: "post" | "feed" | "story" | "reel" | "carousel" | undefined;
     reel_cover_url?: string | undefined;
+    reel_cover_method?: string | undefined;
     reel_thumb_offset?: number | undefined;
     __type?: "instagram" | "instagram-standalone" | undefined;
     is_trial_reel?: boolean | undefined;
@@ -57,6 +59,7 @@ declare const instagramSettingsSchema: z.ZodObject<{
 }, {
     post_type?: "post" | "feed" | "story" | "reel" | "carousel" | undefined;
     reel_cover_url?: string | undefined;
+    reel_cover_method?: string | undefined;
     reel_thumb_offset?: number | undefined;
     __type?: "instagram" | "instagram-standalone" | undefined;
     is_trial_reel?: boolean | undefined;
@@ -80,6 +83,7 @@ declare const platformSettingsSchema: z.ZodObject<{
     content_type: z.ZodOptional<z.ZodString>;
     media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     reel_cover_url: z.ZodOptional<z.ZodString>;
+    reel_cover_method: z.ZodOptional<z.ZodString>;
     reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
     reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
     poll: z.ZodOptional<z.ZodObject<{
@@ -156,6 +160,7 @@ declare const platformSettingsSchema: z.ZodObject<{
     content_type: z.ZodOptional<z.ZodString>;
     media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     reel_cover_url: z.ZodOptional<z.ZodString>;
+    reel_cover_method: z.ZodOptional<z.ZodString>;
     reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
     reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
     poll: z.ZodOptional<z.ZodObject<{
@@ -232,6 +237,7 @@ declare const platformSettingsSchema: z.ZodObject<{
     content_type: z.ZodOptional<z.ZodString>;
     media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     reel_cover_url: z.ZodOptional<z.ZodString>;
+    reel_cover_method: z.ZodOptional<z.ZodString>;
     reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
     reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
     poll: z.ZodOptional<z.ZodObject<{
@@ -313,6 +319,9 @@ export declare const updatePostTool: {
         media_url: z.ZodOptional<z.ZodString>;
         media_urls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         post_type: z.ZodOptional<z.ZodString>;
+        reel_cover_url: z.ZodOptional<z.ZodString>;
+        reel_cover_method: z.ZodOptional<z.ZodString>;
+        reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
         instagram_settings: z.ZodOptional<z.ZodObject<{
             __type: z.ZodOptional<z.ZodEnum<["instagram", "instagram-standalone"]>>;
             post_type: z.ZodOptional<z.ZodEnum<["post", "feed", "story", "reel", "carousel"]>>;
@@ -347,10 +356,12 @@ export declare const updatePostTool: {
             first_comment: z.ZodOptional<z.ZodString>;
             media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             reel_cover_url: z.ZodOptional<z.ZodString>;
+            reel_cover_method: z.ZodOptional<z.ZodString>;
             reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             post_type?: "post" | "feed" | "story" | "reel" | "carousel" | undefined;
             reel_cover_url?: string | undefined;
+            reel_cover_method?: string | undefined;
             reel_thumb_offset?: number | undefined;
             __type?: "instagram" | "instagram-standalone" | undefined;
             is_trial_reel?: boolean | undefined;
@@ -370,6 +381,7 @@ export declare const updatePostTool: {
         }, {
             post_type?: "post" | "feed" | "story" | "reel" | "carousel" | undefined;
             reel_cover_url?: string | undefined;
+            reel_cover_method?: string | undefined;
             reel_thumb_offset?: number | undefined;
             __type?: "instagram" | "instagram-standalone" | undefined;
             is_trial_reel?: boolean | undefined;
@@ -393,6 +405,7 @@ export declare const updatePostTool: {
             content_type: z.ZodOptional<z.ZodString>;
             media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             reel_cover_url: z.ZodOptional<z.ZodString>;
+            reel_cover_method: z.ZodOptional<z.ZodString>;
             reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
             reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
             poll: z.ZodOptional<z.ZodObject<{
@@ -469,6 +482,7 @@ export declare const updatePostTool: {
             content_type: z.ZodOptional<z.ZodString>;
             media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             reel_cover_url: z.ZodOptional<z.ZodString>;
+            reel_cover_method: z.ZodOptional<z.ZodString>;
             reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
             reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
             poll: z.ZodOptional<z.ZodObject<{
@@ -545,6 +559,7 @@ export declare const updatePostTool: {
             content_type: z.ZodOptional<z.ZodString>;
             media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             reel_cover_url: z.ZodOptional<z.ZodString>;
+            reel_cover_method: z.ZodOptional<z.ZodString>;
             reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
             reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
             poll: z.ZodOptional<z.ZodObject<{
@@ -624,10 +639,14 @@ export declare const updatePostTool: {
         media_url?: string | undefined;
         media_urls?: string[] | undefined;
         post_type?: string | undefined;
+        reel_cover_url?: string | undefined;
+        reel_cover_method?: string | undefined;
+        reel_thumb_offset?: number | undefined;
         caption?: string | undefined;
         instagram_settings?: {
             post_type?: "post" | "feed" | "story" | "reel" | "carousel" | undefined;
             reel_cover_url?: string | undefined;
+            reel_cover_method?: string | undefined;
             reel_thumb_offset?: number | undefined;
             __type?: "instagram" | "instagram-standalone" | undefined;
             is_trial_reel?: boolean | undefined;
@@ -651,6 +670,7 @@ export declare const updatePostTool: {
             content_type: z.ZodOptional<z.ZodString>;
             media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             reel_cover_url: z.ZodOptional<z.ZodString>;
+            reel_cover_method: z.ZodOptional<z.ZodString>;
             reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
             reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
             poll: z.ZodOptional<z.ZodObject<{
@@ -729,10 +749,14 @@ export declare const updatePostTool: {
         media_url?: string | undefined;
         media_urls?: string[] | undefined;
         post_type?: string | undefined;
+        reel_cover_url?: string | undefined;
+        reel_cover_method?: string | undefined;
+        reel_thumb_offset?: number | undefined;
         caption?: string | undefined;
         instagram_settings?: {
             post_type?: "post" | "feed" | "story" | "reel" | "carousel" | undefined;
             reel_cover_url?: string | undefined;
+            reel_cover_method?: string | undefined;
             reel_thumb_offset?: number | undefined;
             __type?: "instagram" | "instagram-standalone" | undefined;
             is_trial_reel?: boolean | undefined;
@@ -756,6 +780,7 @@ export declare const updatePostTool: {
             content_type: z.ZodOptional<z.ZodString>;
             media_alt_texts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             reel_cover_url: z.ZodOptional<z.ZodString>;
+            reel_cover_method: z.ZodOptional<z.ZodString>;
             reel_thumb_offset: z.ZodOptional<z.ZodNumber>;
             reply_settings: z.ZodOptional<z.ZodEnum<["everyone", "following", "mentionedUsers", "subscribers", "verified"]>>;
             poll: z.ZodOptional<z.ZodObject<{

package/dist/tools/update-post.js

@@ -14,6 +14,7 @@ const instagramSettingsSchema = z.object({
     first_comment: z.string().optional(),
     media_alt_texts: z.record(z.string(), z.string()).optional(),
     reel_cover_url: z.string().optional(),
+    reel_cover_method: z.string().optional(),
     reel_thumb_offset: z.number().nonnegative().optional(),
 });
 const platformSettingsSchema = z.object({
@@ -22,6 +23,7 @@ const platformSettingsSchema = z.object({
     content_type: z.string().optional(),
     media_alt_texts: z.record(z.string(), z.string()).optional(),
     reel_cover_url: z.string().optional(),
+    reel_cover_method: z.string().optional(),
     reel_thumb_offset: z.number().nonnegative().optional(),
     reply_settings: z.enum(['everyone', 'following', 'mentionedUsers', 'subscribers', 'verified']).optional(),
     poll: z.object({ options: z.array(z.string()), duration_minutes: z.number().positive().optional(), question: z.string().optional(), duration: z.enum(['ONE_DAY', 'THREE_DAYS', 'SEVEN_DAYS', 'FOURTEEN_DAYS']).optional(), allows_multiple_answers: z.boolean().optional() }).optional(),
@@ -83,9 +85,15 @@ export const updatePostTool = {
             .string()
             .optional()
             .describe('New post type: text, image, video, carousel, reel, story, story_series, document, photo, or cover_photo'),
+        // Reel cover controls are also accepted top-level, matching the hosted
+        // endpoint. An agent reading the hosted schema will reach for these names,
+        // and scripts/check-mcp-schema-parity.ts enforces that both surfaces agree.
+        reel_cover_url: z.string().optional().describe('Cover image URL for a reel.'),
+        reel_cover_method: z.string().optional().describe('How the reel cover is chosen, e.g. an uploaded image or a frame offset.'),
+        reel_thumb_offset: z.number().nonnegative().optional().describe('Frame offset in milliseconds to use as the reel cover.'),
         instagram_settings: instagramSettingsSchema
             .optional()
-            .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_thumb_offset.'),
+            .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_cover_method, reel_thumb_offset.'),
         platform_settings: platformSettingsSchema
             .optional()
             .describe('Platform-specific settings to merge into the post. Prefer this over raw metadata.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.28.0",
+  "version": "0.30.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",
@@ -32,7 +32,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "test:annotations": "npm run build && node scripts/test-tool-annotations.mjs"
+    "test:annotations": "npm run build && node scripts/test-tool-annotations.mjs",
+    "test:payloads": "npm run build && node scripts/test-payload-builders.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",

package/scripts/test-payload-builders.mjs

@@ -0,0 +1,87 @@
+/**
+ * Behavioural tests for the payload builders.
+ *
+ * scripts/check-mcp-schema-parity.ts compares the JSON Schema each surface
+ * publishes, which catches a field going missing or an enum narrowing. It does
+ * NOT catch validation written as code rather than schema, and that is exactly
+ * how the caption bug shipped: buildCreatePostPayload threw
+ * "caption is required" for every post without caption text while the schema
+ * happily declared caption optional. Nothing compared behaviour, so the npm
+ * package rejected every media-only post (Instagram and Facebook Stories carry
+ * no caption) for as long as it did.
+ *
+ * These tests pin the rules the server actually applies, so a future edit that
+ * tightens the client past the server fails here.
+ */
+
+import assert from 'node:assert/strict';
+import { buildCreatePostPayload } from '../dist/tools/create-post.js';
+
+let failures = 0;
+function check(name, fn) {
+  try {
+    fn();
+    console.log(`PASS  ${name}`);
+  } catch (error) {
+    failures += 1;
+    console.error(`FAIL  ${name}\n      ${error.message}`);
+  }
+}
+
+const IMAGE = 'https://assets.poster.ly/users/test/a.jpg';
+
+// The server rule (lib/api-v1-post-create.ts) is "provide caption or media".
+// Media-only posts are valid and must not be rejected by the client.
+check('media-only post is accepted (Instagram Story shape)', () => {
+  const payload = buildCreatePostPayload({
+    platform: 'instagram',
+    media_url: IMAGE,
+    post_type: 'story',
+    instagram_settings: { post_type: 'story' },
+  });
+  assert.equal(typeof payload.caption, 'string', 'caption should be sent as a string');
+  assert.equal(payload.post_type, 'story');
+});
+
+check('media-only post is accepted (Facebook Story shape)', () => {
+  const payload = buildCreatePostPayload({
+    platform: 'facebook',
+    media_url: IMAGE,
+    post_type: 'story',
+    platform_settings: { __type: 'facebook', post_type: 'story' },
+  });
+  assert.equal(typeof payload.caption, 'string');
+});
+
+check('media_urls-only post is accepted', () => {
+  const payload = buildCreatePostPayload({ platform: 'instagram', media_urls: [IMAGE] });
+  assert.equal(typeof payload.caption, 'string');
+});
+
+check('caption-only post is accepted', () => {
+  const payload = buildCreatePostPayload({ platform: 'linkedin', caption: 'hello' });
+  assert.equal(payload.caption, 'hello');
+});
+
+check('post with neither caption nor media is rejected', () => {
+  assert.throws(
+    () => buildCreatePostPayload({ platform: 'instagram' }),
+    /caption or media/i,
+    'should reject, and the message should tell the caller media is an option',
+  );
+});
+
+check('thread_posts still bypasses the caption rule', () => {
+  const payload = buildCreatePostPayload({
+    platform: 'twitter',
+    thread_posts: ['one', 'two'],
+  });
+  assert.equal(payload.caption, 'one');
+  assert.equal(payload.post_type, 'x_thread');
+});
+
+if (failures > 0) {
+  console.error(`\n${failures} payload-builder test(s) failed.`);
+  process.exit(1);
+}
+console.log(`\nOK  payload builders honour the server's "caption or media" rule.`);

package/scripts/test-tool-annotations.mjs

@@ -12,7 +12,7 @@ try {
   await client.connect(transport);
   const { tools } = await client.listTools();
 
-  assert.equal(tools.length, 75);
+  assert.equal(tools.length, 76);
   for (const tool of tools) {
     assert(tool.annotations, `${tool.name} is missing annotations`);
     assert(tool.annotations.title, `${tool.name} is missing an annotation title`);

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.28.0",
+  "version": "0.30.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.28.0",
+      "version": "0.30.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -71,6 +71,7 @@ import { createConnectSessionTool } from './tools/create-connect-session.js';
 import { getConnectSessionTool } from './tools/get-connect-session.js';
 import { createApiKeyTool } from './tools/create-api-key.js';
 import { deleteApiKeyTool } from './tools/delete-api-key.js';
+import { getCreditsTool } from './tools/get-credits.js';
 import { getSubscriptionTool } from './tools/get-subscription.js';
 import { cancelSubscriptionTool } from './tools/cancel-subscription.js';
 import { pauseSubscriptionTool } from './tools/pause-subscription.js';
@@ -269,6 +270,21 @@ server.tool(
   }
 );
 
+server.tool(
+  getCreditsTool.name,
+  getCreditsTool.description,
+  getCreditsTool.inputSchema.shape,
+  getToolAnnotations(getCreditsTool.name),
+  async () => {
+    try {
+      const text = await getCreditsTool.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(
   getSubscriptionTool.name,
   getSubscriptionTool.description,

package/src/lib/api-client.ts

@@ -356,6 +356,20 @@ export type SubscriptionSummaryResponse = {
   subscription: SubscriptionSummary;
 };
 
+export type CreditsSummaryResponse = {
+  credits: {
+    available: number;
+    included: { monthly: number; used: number; remaining: number };
+    purchased_balance: number;
+    plan_tier: string;
+    is_trial: boolean;
+    period_start: string;
+    /** Null while trialing or on a plan with no included pool. */
+    resets_at: string | null;
+    workspace: { role: string; shared_wallet: boolean };
+  };
+};
+
 export type CancelSubscriptionPayload = {
   reason: string;
   feedback?: string;
@@ -968,6 +982,10 @@ export class PosterlyClient {
     return this.request('GET', '/subscription');
   }
 
+  async getCredits(): Promise<CreditsSummaryResponse> {
+    return this.request('GET', '/credits');
+  }
+
   async cancelSubscription(data: CancelSubscriptionPayload): Promise<CancelSubscriptionResponse> {
     return this.request('POST', '/subscription/cancel', data);
   }
@@ -1215,7 +1233,7 @@ export class PosterlyClient {
     aspect_ratio?: string;
     style?: string;
     variations?: number;
-    model?: 'flash' | 'pro';
+    model?: 'lite' | 'flash' | 'pro';
     resolution?: '512' | '1K' | '2K' | '4K';
   }): Promise<{
     urls: string[];

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

package/src/tools/create-post.ts

@@ -164,13 +164,23 @@ export function buildCreatePostPayload(input: CreatePostPayloadInput | CreatePos
     };
   }
 
-  if (!caption) {
-    throw new Error('caption is required (or pass `thread_posts` for an X/Threads thread)');
+  // Mirror the server rule (lib/api-v1-post-create.ts): a post needs a caption
+  // OR media, not a caption unconditionally. Requiring one here made every
+  // media-only post impossible from the npm client, most visibly Instagram and
+  // Facebook Stories, which carry no caption at all. The dashboard composer and
+  // the hosted MCP have always allowed it; only this package disagreed.
+  const hasMedia = Boolean(input.media_url) || (input.media_urls?.length ?? 0) > 0;
+  if (!caption && !hasMedia) {
+    throw new Error(
+      'Provide caption or media (or pass `thread_posts` for an X/Threads thread). Media-only posts are valid, for example an Instagram or Facebook Story.',
+    );
   }
 
   return {
     ...rest,
-    caption,
+    // The server treats a missing caption as empty content when media carries
+    // the post, so send '' rather than dropping the key.
+    caption: caption ?? '',
     post_type,
     ...(platform_settings || instagram_settings
       ? { settings: { ...(instagram_settings ? { __type: 'instagram', ...instagram_settings } : {}), ...(platform_settings || {}) } }

package/src/tools/generate-image.ts

@@ -41,13 +41,13 @@ export const generateImageTool = {
       .optional()
       .describe('How many variations to generate. Default 1. Each variation costs credits separately - prefer 1 unless the user explicitly wants options.'),
     model: z
-      .enum(['flash', 'pro'])
+      .enum(['lite', 'flash', 'pro'])
       .optional()
-      .describe('flash (default, 1 credit per 1K image) is fast and cost-effective. pro (2 credits per 1K) is higher quality for hero imagery. Start with flash unless quality is critical.'),
+      .describe('lite (8 credits, 1K only) is the cheapest and suits drafts and exploration. flash (default, 15 credits at 1K) balances quality and cost. pro (30 credits at 1K) is highest quality for hero imagery. Start with lite or flash unless quality is critical.'),
     resolution: z
       .enum(['512', '1K', '2K', '4K'])
       .optional()
-      .describe('Output resolution. Default 1K. Higher resolutions cost more credits. 512 is flash-only.'),
+      .describe('Output resolution. Default 1K. Higher resolutions cost more credits (flash: 10/15/23/35 for 512/1K/2K/4K; pro: 30 at 1K-2K, 55 at 4K). 512 is flash-only and lite supports 1K only.'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation of subject, style, aspect ratio, and credit use.'),
   }),
 
@@ -58,7 +58,7 @@ export const generateImageTool = {
       aspect_ratio?: string;
       style?: string;
       variations?: number;
-      model?: 'flash' | 'pro';
+      model?: 'lite' | 'flash' | 'pro';
       resolution?: '512' | '1K' | '2K' | '4K';
       confirm: true;
     }

package/src/tools/get-credits.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { CreditsSummaryResponse, PosterlyClient } from '../lib/api-client.js';
+import { formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+
+function formatCredits(result: CreditsSummaryResponse): string {
+  const c = result.credits;
+  const inc = c.included;
+  return [
+    mdTitle('posterly AI credits'),
+    mdSection('Balance', mdKeyValue([
+      ['Available now', String(c.available)],
+      ['Included this period', `${inc.remaining} of ${inc.monthly} left (${inc.used} used)`],
+      ['Purchased packs', String(c.purchased_balance)],
+    ])),
+    mdSection('Plan', mdKeyValue([
+      ['Tier', c.plan_tier || 'unknown'],
+      ['Trial', c.is_trial ? 'yes' : 'no'],
+      [
+        'Included pool resets',
+        c.resets_at ? formatDateTime(c.resets_at) : 'no monthly reset (trial or no included pool)',
+      ],
+      ['Your workspace role', c.workspace?.role || 'unknown'],
+    ])),
+    "Credits are a shared workspace wallet: every active member draws the same pool, and packs are added to the billing owner's balance.",
+  ].join('\n\n');
+}
+
+export const getCreditsTool = {
+  name: 'get_credits',
+  description:
+    "Get the authenticated user's posterly AI credit balance: what is available to spend now, how much of the monthly included allowance is left, purchased pack balance, plan tier, and when the included pool next resets. Credits are a shared WORKSPACE wallet, so this reports the balance the caller can actually spend, not a personal figure. Read-only, spends nothing. Requires the billing:read scope.",
+  inputSchema: z.object({}),
+
+  async execute(client: PosterlyClient) {
+    const result = await client.getCredits();
+    return formatCredits(result);
+  },
+};

package/src/tools/update-post.ts

@@ -16,6 +16,7 @@ const instagramSettingsSchema = z.object({
   first_comment: z.string().optional(),
   media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
+  reel_cover_method: z.string().optional(),
   reel_thumb_offset: z.number().nonnegative().optional(),
 });
 
@@ -25,6 +26,7 @@ const platformSettingsSchema = z.object({
   content_type: z.string().optional(),
   media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
+  reel_cover_method: z.string().optional(),
   reel_thumb_offset: z.number().nonnegative().optional(),
   reply_settings: z.enum(['everyone', 'following', 'mentionedUsers', 'subscribers', 'verified']).optional(),
   poll: z.object({ options: z.array(z.string()), duration_minutes: z.number().positive().optional(), question: z.string().optional(), duration: z.enum(['ONE_DAY', 'THREE_DAYS', 'SEVEN_DAYS', 'FOURTEEN_DAYS']).optional(), allows_multiple_answers: z.boolean().optional() }).optional(),
@@ -88,9 +90,15 @@ export const updatePostTool = {
       .string()
       .optional()
       .describe('New post type: text, image, video, carousel, reel, story, story_series, document, photo, or cover_photo'),
+    // Reel cover controls are also accepted top-level, matching the hosted
+    // endpoint. An agent reading the hosted schema will reach for these names,
+    // and scripts/check-mcp-schema-parity.ts enforces that both surfaces agree.
+    reel_cover_url: z.string().optional().describe('Cover image URL for a reel.'),
+    reel_cover_method: z.string().optional().describe('How the reel cover is chosen, e.g. an uploaded image or a frame offset.'),
+    reel_thumb_offset: z.number().nonnegative().optional().describe('Frame offset in milliseconds to use as the reel cover.'),
     instagram_settings: instagramSettingsSchema
       .optional()
-      .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_thumb_offset.'),
+      .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_cover_method, reel_thumb_offset.'),
     platform_settings: platformSettingsSchema
       .optional()
       .describe('Platform-specific settings to merge into the post. Prefer this over raw metadata.'),

package/tool-annotations.json

@@ -12,6 +12,7 @@
     "get_connect_session",
     "create_api_key",
     "delete_api_key",
+    "get_credits",
     "get_subscription",
     "cancel_subscription",
     "pause_subscription",
@@ -84,6 +85,7 @@
     "list_accounts",
     "get_connect_link",
     "get_connect_session",
+    "get_credits",
     "get_subscription",
     "list_oauth_clients",
     "list_platforms",
@@ -162,6 +164,7 @@
     "disconnect_account",
     "create_connect_session",
     "get_connect_session",
+    "get_credits",
     "get_subscription",
     "cancel_subscription",
     "pause_subscription",