posterly-mcp-server 0.3.1 → 0.4.0

package/dist/index.js

@@ -11,9 +11,10 @@ import { getPostTool } from './tools/get-post.js';
 import { updatePostTool } from './tools/update-post.js';
 import { deletePostTool } from './tools/delete-post.js';
 import { whoamiTool } from './tools/whoami.js';
+import { generateImageTool } from './tools/generate-image.js';
 const server = new McpServer({
     name: 'posterly',
-    version: '0.3.1',
+    version: '0.4.0',
 });
 let client;
 try {
@@ -78,6 +79,15 @@ server.tool(uploadMediaTool.name, uploadMediaTool.description, uploadMediaTool.i
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(generateImageTool.name, generateImageTool.description, generateImageTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await generateImageTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(getPostTool.name, getPostTool.description, getPostTool.inputSchema.shape, async (input) => {
     try {
         const text = await getPostTool.execute(client, input);

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

@@ -99,6 +99,31 @@ export declare class PosterlyClient {
         deleted: boolean;
         id: number;
     }>;
+    generateImage(data: {
+        prompt: string;
+        aspect_ratio?: string;
+        style?: string;
+        variations?: number;
+        model?: 'flash' | 'pro';
+        resolution?: '512' | '1K' | '2K' | '4K';
+    }): Promise<{
+        urls: string[];
+        images: Array<{
+            url: string;
+            filename: string;
+            path: string;
+        }>;
+        model: string;
+        credits_used: number;
+        warnings?: string[];
+        usage: {
+            used: number | null;
+            limit: number | null;
+            period: string | null;
+            tier: string | null;
+            billed_from: 'plan_quota' | 'credits';
+        };
+    }>;
     findAvailableSlots(params?: {
         account_ids?: string[];
         timezone?: string;

package/dist/lib/api-client.js

@@ -68,6 +68,9 @@ export class PosterlyClient {
     async deletePost(id) {
         return this.request('DELETE', `/posts/${id}`);
     }
+    async generateImage(data) {
+        return this.request('POST', '/ai/generate-image', data);
+    }
     async findAvailableSlots(params) {
         const searchParams = new URLSearchParams();
         if (params?.account_ids?.length)

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

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const generateImageTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        prompt: z.ZodString;
+        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"]>>;
+        resolution: z.ZodOptional<z.ZodEnum<["512", "1K", "2K", "4K"]>>;
+    }, "strip", z.ZodTypeAny, {
+        prompt: string;
+        aspect_ratio?: "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" | undefined;
+        style?: "photographic" | "illustration" | "minimal" | "vibrant" | "professional" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
+        variations?: number | undefined;
+        model?: "flash" | "pro" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+    }, {
+        prompt: string;
+        aspect_ratio?: "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" | undefined;
+        style?: "photographic" | "illustration" | "minimal" | "vibrant" | "professional" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
+        variations?: number | undefined;
+        model?: "flash" | "pro" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        prompt: string;
+        aspect_ratio?: string;
+        style?: string;
+        variations?: number;
+        model?: "flash" | "pro";
+        resolution?: "512" | "1K" | "2K" | "4K";
+    }): Promise<string>;
+};

package/dist/tools/generate-image.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+export const generateImageTool = {
+    name: 'generate_image',
+    description: 'Generate an AI image via Posterly\'s Nano Banana (Gemini) integration. The image is saved to the user\'s media storage and the returned URL can be passed to `create_post` as `media_url`.\n\n' +
+        'COSTS CREDITS. Every call consumes part of the user\'s monthly AI image quota (or purchased credits once the quota is exhausted). Do NOT call speculatively — always describe the image you\'re about to generate (subject, style, aspect ratio) to the user and get confirmation before calling.\n\n' +
+        'If the user is over their plan limit and has no credits, this tool returns a 402 with upgrade info. Surface that message verbatim — do not retry.\n\n' +
+        'Common aspect ratios by platform:\n' +
+        '  • Instagram feed / LinkedIn: 1:1 (square) or 4:5 (portrait)\n' +
+        '  • Instagram Story/Reel, TikTok, YouTube Shorts: 9:16\n' +
+        '  • YouTube thumbnail, Twitter cards, landscape feed: 16:9\n' +
+        '  • Pinterest: 2:3',
+    inputSchema: z.object({
+        prompt: z
+            .string()
+            .min(5)
+            .max(4000)
+            .describe('Detailed image description. 5–4000 characters. Describe subject, scene, lighting, mood, and style.'),
+        aspect_ratio: z
+            .enum([
+            '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',
+        ])
+            .optional()
+            .describe('Aspect ratio. Default 1:1. Pick based on target platform (see tool description).'),
+        style: z
+            .enum([
+            'photographic', 'illustration', 'minimal', 'vibrant', 'professional',
+            'youtube_thumbnail', 'reel_cover', 'review_background',
+        ])
+            .optional()
+            .describe('Preset style. Default photographic. Use youtube_thumbnail / reel_cover for platform-optimized covers; review_background for testimonial backgrounds.'),
+        variations: z
+            .number()
+            .int()
+            .min(1)
+            .max(4)
+            .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'])
+            .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.'),
+        resolution: z
+            .enum(['512', '1K', '2K', '4K'])
+            .optional()
+            .describe('Output resolution. Default 1K. Higher resolutions cost more credits. 512 is flash-only.'),
+    }),
+    async execute(client, input) {
+        const result = await client.generateImage(input);
+        const lines = [];
+        lines.push(`Generated ${result.images.length} image${result.images.length === 1 ? '' : 's'} via ${result.model}.`);
+        lines.push('');
+        result.images.forEach((img, i) => {
+            lines.push(`${i + 1}. ${img.url}`);
+        });
+        lines.push('');
+        lines.push(`Billed from: ${result.usage.billed_from}${result.credits_used > 0 ? ` (${result.credits_used} credits)` : ''}`);
+        if (result.usage.limit != null) {
+            lines.push(`Plan usage: ${result.usage.used ?? 0}/${result.usage.limit} this ${result.usage.period || 'period'}${result.usage.tier ? ` (${result.usage.tier})` : ''}`);
+        }
+        if (result.warnings?.length) {
+            lines.push('');
+            lines.push('Warnings:');
+            result.warnings.forEach((w) => lines.push(`• ${w}`));
+        }
+        lines.push('');
+        lines.push('Pass any of these URLs to create_post as media_url (or media_urls for a carousel).');
+        return lines.join('\n');
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -12,10 +12,11 @@ import { getPostTool } from './tools/get-post.js';
 import { updatePostTool } from './tools/update-post.js';
 import { deletePostTool } from './tools/delete-post.js';
 import { whoamiTool } from './tools/whoami.js';
+import { generateImageTool } from './tools/generate-image.js';
 
 const server = new McpServer({
   name: 'posterly',
-  version: '0.3.1',
+  version: '0.4.0',
 });
 
 let client: PosterlyClient;
@@ -112,6 +113,20 @@ server.tool(
   }
 );
 
+server.tool(
+  generateImageTool.name,
+  generateImageTool.description,
+  generateImageTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await generateImageTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 server.tool(
   getPostTool.name,
   getPostTool.description,

package/src/lib/api-client.ts

@@ -157,6 +157,30 @@ export class PosterlyClient {
     return this.request('DELETE', `/posts/${id}`);
   }
 
+  async generateImage(data: {
+    prompt: string;
+    aspect_ratio?: string;
+    style?: string;
+    variations?: number;
+    model?: 'flash' | 'pro';
+    resolution?: '512' | '1K' | '2K' | '4K';
+  }): Promise<{
+    urls: string[];
+    images: Array<{ url: string; filename: string; path: string }>;
+    model: string;
+    credits_used: number;
+    warnings?: string[];
+    usage: {
+      used: number | null;
+      limit: number | null;
+      period: string | null;
+      tier: string | null;
+      billed_from: 'plan_quota' | 'credits';
+    };
+  }> {
+    return this.request('POST', '/ai/generate-image', data);
+  }
+
   async findAvailableSlots(params?: {
     account_ids?: string[];
     timezone?: string;

package/src/tools/generate-image.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const generateImageTool = {
+  name: 'generate_image',
+  description:
+    'Generate an AI image via Posterly\'s Nano Banana (Gemini) integration. The image is saved to the user\'s media storage and the returned URL can be passed to `create_post` as `media_url`.\n\n' +
+    'COSTS CREDITS. Every call consumes part of the user\'s monthly AI image quota (or purchased credits once the quota is exhausted). Do NOT call speculatively — always describe the image you\'re about to generate (subject, style, aspect ratio) to the user and get confirmation before calling.\n\n' +
+    'If the user is over their plan limit and has no credits, this tool returns a 402 with upgrade info. Surface that message verbatim — do not retry.\n\n' +
+    'Common aspect ratios by platform:\n' +
+    '  • Instagram feed / LinkedIn: 1:1 (square) or 4:5 (portrait)\n' +
+    '  • Instagram Story/Reel, TikTok, YouTube Shorts: 9:16\n' +
+    '  • YouTube thumbnail, Twitter cards, landscape feed: 16:9\n' +
+    '  • Pinterest: 2:3',
+  inputSchema: z.object({
+    prompt: z
+      .string()
+      .min(5)
+      .max(4000)
+      .describe('Detailed image description. 5–4000 characters. Describe subject, scene, lighting, mood, and style.'),
+    aspect_ratio: z
+      .enum([
+        '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',
+      ])
+      .optional()
+      .describe('Aspect ratio. Default 1:1. Pick based on target platform (see tool description).'),
+    style: z
+      .enum([
+        'photographic', 'illustration', 'minimal', 'vibrant', 'professional',
+        'youtube_thumbnail', 'reel_cover', 'review_background',
+      ])
+      .optional()
+      .describe('Preset style. Default photographic. Use youtube_thumbnail / reel_cover for platform-optimized covers; review_background for testimonial backgrounds.'),
+    variations: z
+      .number()
+      .int()
+      .min(1)
+      .max(4)
+      .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'])
+      .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.'),
+    resolution: z
+      .enum(['512', '1K', '2K', '4K'])
+      .optional()
+      .describe('Output resolution. Default 1K. Higher resolutions cost more credits. 512 is flash-only.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      prompt: string;
+      aspect_ratio?: string;
+      style?: string;
+      variations?: number;
+      model?: 'flash' | 'pro';
+      resolution?: '512' | '1K' | '2K' | '4K';
+    }
+  ) {
+    const result = await client.generateImage(input);
+
+    const lines: string[] = [];
+    lines.push(`Generated ${result.images.length} image${result.images.length === 1 ? '' : 's'} via ${result.model}.`);
+    lines.push('');
+    result.images.forEach((img, i) => {
+      lines.push(`${i + 1}. ${img.url}`);
+    });
+    lines.push('');
+    lines.push(`Billed from: ${result.usage.billed_from}${result.credits_used > 0 ? ` (${result.credits_used} credits)` : ''}`);
+    if (result.usage.limit != null) {
+      lines.push(`Plan usage: ${result.usage.used ?? 0}/${result.usage.limit} this ${result.usage.period || 'period'}${result.usage.tier ? ` (${result.usage.tier})` : ''}`);
+    }
+    if (result.warnings?.length) {
+      lines.push('');
+      lines.push('Warnings:');
+      result.warnings.forEach((w) => lines.push(`• ${w}`));
+    }
+    lines.push('');
+    lines.push('Pass any of these URLs to create_post as media_url (or media_urls for a carousel).');
+
+    return lines.join('\n');
+  },
+};