posterly-mcp-server 0.29.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>;

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.29.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.29.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/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.29.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.29.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.29.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);
   }

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.29.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/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",