posterly-mcp-server 0.3.1 → 0.5.0

package/dist/index.js

@@ -11,9 +11,12 @@ 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';
+import { getAccountAnalyticsTool } from './tools/get-account-analytics.js';
+import { getPostAnalyticsTool } from './tools/get-post-analytics.js';
 const server = new McpServer({
     name: 'posterly',
-    version: '0.3.1',
+    version: '0.5.0',
 });
 let client;
 try {
@@ -78,6 +81,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);
@@ -105,6 +117,24 @@ server.tool(deletePostTool.name, deletePostTool.description, deletePostTool.inpu
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(getAccountAnalyticsTool.name, getAccountAnalyticsTool.description, getAccountAnalyticsTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getAccountAnalyticsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(getPostAnalyticsTool.name, getPostAnalyticsTool.description, getPostAnalyticsTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getPostAnalyticsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

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

@@ -43,6 +43,86 @@ export interface Whoami {
     default_workspace: Workspace;
     workspaces: Workspace[];
 }
+export interface AccountAnalyticsSummary {
+    current_followers: number;
+    followers_change: number;
+    total_reach: number | null;
+    total_views: number | null;
+    total_accounts_engaged: number | null;
+    total_follows_gained: number;
+    total_follows_lost: number;
+    engagement_rate: number;
+    engagement_rate_by_followers: number;
+    total_website_clicks: number | null;
+    total_call_clicks: number | null;
+    total_direction_requests: number | null;
+    total_conversations: number | null;
+    total_bookings: number | null;
+}
+export interface AccountAnalyticsSnapshot {
+    date: string;
+    followers: number | null;
+    following: number | null;
+    media_count: number | null;
+    reach: number | null;
+    views: number | null;
+    profile_views: number | null;
+    accounts_engaged: number | null;
+    follows_gained: number | null;
+    follows_lost: number | null;
+    website_clicks: number | null;
+    call_clicks: number | null;
+    direction_requests: number | null;
+    conversations: number | null;
+    bookings: number | null;
+}
+export interface AccountAnalyticsResponse {
+    account: {
+        id: number;
+        platform: string;
+        username: string;
+    };
+    range: {
+        from: string;
+        to: string;
+    };
+    summary: AccountAnalyticsSummary;
+    snapshots: AccountAnalyticsSnapshot[];
+}
+export interface PostAnalyticsRow {
+    id: number | null;
+    platform_media_id: string;
+    platform: string;
+    posted_at: string | null;
+    likes: number;
+    comments: number;
+    impressions: number;
+    reach: number;
+    saved: number;
+    shares: number;
+    plays: number;
+    total_interactions: number;
+    media_type: string | null;
+    media_url: string | null;
+    permalink: string | null;
+    caption_snippet: string | null;
+    synced_at: string;
+}
+export interface PostAnalyticsResponse {
+    account: {
+        id: number;
+        platform: string;
+        username: string;
+    };
+    range: {
+        from: string;
+        to: string;
+    };
+    posts: PostAnalyticsRow[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 export declare class PosterlyClient {
     private baseUrl;
     private apiKey;
@@ -99,12 +179,49 @@ 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;
         count?: number;
         workspace_id?: string;
     }): Promise<Slot[]>;
+    getAccountAnalytics(params: {
+        account_id: number;
+        from?: string;
+        to?: string;
+    }): Promise<AccountAnalyticsResponse>;
+    getPostAnalytics(params: {
+        account_id: number;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PostAnalyticsResponse>;
     getSignedUploadUrl(filename: string, contentType: string, size: number): Promise<{
         upload_url: string;
         token: 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)
@@ -82,6 +85,28 @@ export class PosterlyClient {
         const data = await this.request('GET', `/slots/next${qs ? `?${qs}` : ''}`);
         return data.slots;
     }
+    async getAccountAnalytics(params) {
+        const searchParams = new URLSearchParams();
+        searchParams.set('account_id', String(params.account_id));
+        if (params.from)
+            searchParams.set('from', params.from);
+        if (params.to)
+            searchParams.set('to', params.to);
+        return this.request('GET', `/analytics/accounts?${searchParams.toString()}`);
+    }
+    async getPostAnalytics(params) {
+        const searchParams = new URLSearchParams();
+        searchParams.set('account_id', String(params.account_id));
+        if (params.from)
+            searchParams.set('from', params.from);
+        if (params.to)
+            searchParams.set('to', params.to);
+        if (params.limit)
+            searchParams.set('limit', String(params.limit));
+        if (params.offset)
+            searchParams.set('offset', String(params.offset));
+        return this.request('GET', `/analytics/posts?${searchParams.toString()}`);
+    }
     async getSignedUploadUrl(filename, contentType, size) {
         return this.request('POST', '/media/signed-upload', {
             filename,

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/dist/tools/get-account-analytics.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getAccountAnalyticsTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        account_id: z.ZodNumber;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        account_id: number;
+        from?: string | undefined;
+        to?: string | undefined;
+    }, {
+        account_id: number;
+        from?: string | undefined;
+        to?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        account_id: number;
+        from?: string;
+        to?: string;
+    }): Promise<string>;
+};

package/dist/tools/get-account-analytics.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export const getAccountAnalyticsTool = {
+    name: 'get_account_analytics',
+    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, LinkedIn, and Google Business Profile. Returns follower growth, reach, views, engagement rate, and platform-specific metrics (e.g. website clicks, direction requests for GBP).',
+    inputSchema: z.object({
+        account_id: z
+            .number()
+            .describe('The social account ID (from list_accounts)'),
+        from: z
+            .string()
+            .optional()
+            .describe('Start date (ISO date, e.g. 2026-03-19). Defaults to 30 days ago.'),
+        to: z
+            .string()
+            .optional()
+            .describe('End date (ISO date). Defaults to today.'),
+    }),
+    async execute(client, input) {
+        const result = await client.getAccountAnalytics(input);
+        const { account, range, summary, snapshots } = result;
+        const lines = [
+            `Analytics for @${account.username} (${account.platform}, id ${account.id})`,
+            `Range: ${range.from} → ${range.to} (${snapshots.length} daily snapshots)`,
+            '',
+            'Summary:',
+            `• Followers: ${summary.current_followers.toLocaleString()} (${formatDelta(summary.followers_change)} in range)`,
+            `• Follows gained / lost: +${summary.total_follows_gained} / -${summary.total_follows_lost}`,
+        ];
+        if (summary.total_reach !== null)
+            lines.push(`• Total reach: ${summary.total_reach.toLocaleString()}`);
+        if (summary.total_views !== null)
+            lines.push(`• Total views: ${summary.total_views.toLocaleString()}`);
+        if (summary.total_accounts_engaged !== null) {
+            lines.push(`• Total accounts engaged: ${summary.total_accounts_engaged.toLocaleString()}`);
+        }
+        lines.push(`• Engagement rate (by reach): ${summary.engagement_rate}%`, `• Engagement rate (by followers): ${summary.engagement_rate_by_followers}%`);
+        if (account.platform === 'google_business') {
+            if (summary.total_website_clicks !== null) {
+                lines.push(`• Website clicks: ${summary.total_website_clicks.toLocaleString()}`);
+            }
+            if (summary.total_call_clicks !== null) {
+                lines.push(`• Call clicks: ${summary.total_call_clicks.toLocaleString()}`);
+            }
+            if (summary.total_direction_requests !== null) {
+                lines.push(`• Direction requests: ${summary.total_direction_requests.toLocaleString()}`);
+            }
+            if (summary.total_conversations !== null) {
+                lines.push(`• Conversations: ${summary.total_conversations.toLocaleString()}`);
+            }
+            if (summary.total_bookings !== null) {
+                lines.push(`• Bookings: ${summary.total_bookings.toLocaleString()}`);
+            }
+        }
+        return lines.join('\n');
+    },
+};
+function formatDelta(n) {
+    return n >= 0 ? `+${n.toLocaleString()}` : n.toLocaleString();
+}

package/dist/tools/get-post-analytics.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getPostAnalyticsTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        account_id: z.ZodNumber;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        account_id: number;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+    }, {
+        account_id: number;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        account_id: number;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<string>;
+};

package/dist/tools/get-post-analytics.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export const getPostAnalyticsTool = {
+    name: 'get_post_analytics',
+    description: 'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays) for a connected social account. Supports Instagram, LinkedIn, and Google Business Profile. Returns the most recent posts first.',
+    inputSchema: z.object({
+        account_id: z
+            .number()
+            .describe('The social account ID (from list_accounts)'),
+        from: z
+            .string()
+            .optional()
+            .describe('Start date (ISO date, e.g. 2026-03-19). Defaults to 30 days ago.'),
+        to: z
+            .string()
+            .optional()
+            .describe('End date (ISO date). Defaults to today.'),
+        limit: z
+            .number()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe('Number of posts to return (default 50, max 200)'),
+        offset: z.number().min(0).optional().describe('Pagination offset'),
+    }),
+    async execute(client, input) {
+        const result = await client.getPostAnalytics(input);
+        const { account, range, posts, total } = result;
+        if (posts.length === 0) {
+            return `No analytics found for @${account.username} (${account.platform}) between ${range.from} and ${range.to}.`;
+        }
+        const lines = [
+            `Post analytics for @${account.username} (${account.platform})`,
+            `Range: ${range.from} → ${range.to}  •  Showing ${posts.length} of ${total}`,
+            '',
+        ];
+        for (const p of posts) {
+            const postedAt = p.posted_at
+                ? new Date(p.posted_at).toLocaleString()
+                : 'unknown date';
+            const caption = p.caption_snippet
+                ? p.caption_snippet.length > 60
+                    ? `${p.caption_snippet.slice(0, 60)}…`
+                    : p.caption_snippet
+                : '(no caption)';
+            const metrics = [
+                `${p.likes} likes`,
+                `${p.comments} comments`,
+                `${p.reach.toLocaleString()} reach`,
+            ];
+            if (p.impressions)
+                metrics.push(`${p.impressions.toLocaleString()} impressions`);
+            if (p.saved)
+                metrics.push(`${p.saved} saved`);
+            if (p.shares)
+                metrics.push(`${p.shares} shares`);
+            if (p.plays)
+                metrics.push(`${p.plays.toLocaleString()} plays`);
+            lines.push(`• [${postedAt}] ${caption}`);
+            lines.push(`  ${metrics.join(' • ')}`);
+            if (p.permalink)
+                lines.push(`  ${p.permalink}`);
+        }
+        return lines.join('\n');
+    },
+};

package/package.json

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

package/src/index.ts

@@ -12,10 +12,13 @@ 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';
+import { getAccountAnalyticsTool } from './tools/get-account-analytics.js';
+import { getPostAnalyticsTool } from './tools/get-post-analytics.js';
 
 const server = new McpServer({
   name: 'posterly',
-  version: '0.3.1',
+  version: '0.5.0',
 });
 
 let client: PosterlyClient;
@@ -112,6 +115,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,
@@ -154,6 +171,34 @@ server.tool(
   }
 );
 
+server.tool(
+  getAccountAnalyticsTool.name,
+  getAccountAnalyticsTool.description,
+  getAccountAnalyticsTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await getAccountAnalyticsTool.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(
+  getPostAnalyticsTool.name,
+  getPostAnalyticsTool.description,
+  getPostAnalyticsTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await getPostAnalyticsTool.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 };
+    }
+  }
+);
+
 // Start the server
 async function main() {
   const transport = new StdioServerTransport();

package/src/lib/api-client.ts

@@ -45,6 +45,77 @@ export interface Whoami {
   workspaces: Workspace[];
 }
 
+export interface AccountAnalyticsSummary {
+  current_followers: number;
+  followers_change: number;
+  total_reach: number | null;
+  total_views: number | null;
+  total_accounts_engaged: number | null;
+  total_follows_gained: number;
+  total_follows_lost: number;
+  engagement_rate: number;
+  engagement_rate_by_followers: number;
+  total_website_clicks: number | null;
+  total_call_clicks: number | null;
+  total_direction_requests: number | null;
+  total_conversations: number | null;
+  total_bookings: number | null;
+}
+
+export interface AccountAnalyticsSnapshot {
+  date: string;
+  followers: number | null;
+  following: number | null;
+  media_count: number | null;
+  reach: number | null;
+  views: number | null;
+  profile_views: number | null;
+  accounts_engaged: number | null;
+  follows_gained: number | null;
+  follows_lost: number | null;
+  website_clicks: number | null;
+  call_clicks: number | null;
+  direction_requests: number | null;
+  conversations: number | null;
+  bookings: number | null;
+}
+
+export interface AccountAnalyticsResponse {
+  account: { id: number; platform: string; username: string };
+  range: { from: string; to: string };
+  summary: AccountAnalyticsSummary;
+  snapshots: AccountAnalyticsSnapshot[];
+}
+
+export interface PostAnalyticsRow {
+  id: number | null;
+  platform_media_id: string;
+  platform: string;
+  posted_at: string | null;
+  likes: number;
+  comments: number;
+  impressions: number;
+  reach: number;
+  saved: number;
+  shares: number;
+  plays: number;
+  total_interactions: number;
+  media_type: string | null;
+  media_url: string | null;
+  permalink: string | null;
+  caption_snippet: string | null;
+  synced_at: string;
+}
+
+export interface PostAnalyticsResponse {
+  account: { id: number; platform: string; username: string };
+  range: { from: string; to: string };
+  posts: PostAnalyticsRow[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
 export class PosterlyClient {
   private baseUrl: string;
   private apiKey: string;
@@ -157,6 +228,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;
@@ -174,6 +269,34 @@ export class PosterlyClient {
     return data.slots;
   }
 
+  async getAccountAnalytics(params: {
+    account_id: number;
+    from?: string;
+    to?: string;
+  }): Promise<AccountAnalyticsResponse> {
+    const searchParams = new URLSearchParams();
+    searchParams.set('account_id', String(params.account_id));
+    if (params.from) searchParams.set('from', params.from);
+    if (params.to) searchParams.set('to', params.to);
+    return this.request('GET', `/analytics/accounts?${searchParams.toString()}`);
+  }
+
+  async getPostAnalytics(params: {
+    account_id: number;
+    from?: string;
+    to?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<PostAnalyticsResponse> {
+    const searchParams = new URLSearchParams();
+    searchParams.set('account_id', String(params.account_id));
+    if (params.from) searchParams.set('from', params.from);
+    if (params.to) searchParams.set('to', params.to);
+    if (params.limit) searchParams.set('limit', String(params.limit));
+    if (params.offset) searchParams.set('offset', String(params.offset));
+    return this.request('GET', `/analytics/posts?${searchParams.toString()}`);
+  }
+
   async getSignedUploadUrl(
     filename: string,
     contentType: 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');
+  },
+};

package/src/tools/get-account-analytics.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const getAccountAnalyticsTool = {
+  name: 'get_account_analytics',
+  description:
+    'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, LinkedIn, and Google Business Profile. Returns follower growth, reach, views, engagement rate, and platform-specific metrics (e.g. website clicks, direction requests for GBP).',
+  inputSchema: z.object({
+    account_id: z
+      .number()
+      .describe('The social account ID (from list_accounts)'),
+    from: z
+      .string()
+      .optional()
+      .describe('Start date (ISO date, e.g. 2026-03-19). Defaults to 30 days ago.'),
+    to: z
+      .string()
+      .optional()
+      .describe('End date (ISO date). Defaults to today.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { account_id: number; from?: string; to?: string }
+  ) {
+    const result = await client.getAccountAnalytics(input);
+    const { account, range, summary, snapshots } = result;
+
+    const lines: string[] = [
+      `Analytics for @${account.username} (${account.platform}, id ${account.id})`,
+      `Range: ${range.from} → ${range.to} (${snapshots.length} daily snapshots)`,
+      '',
+      'Summary:',
+      `• Followers: ${summary.current_followers.toLocaleString()} (${formatDelta(summary.followers_change)} in range)`,
+      `• Follows gained / lost: +${summary.total_follows_gained} / -${summary.total_follows_lost}`,
+    ];
+
+    if (summary.total_reach !== null) lines.push(`• Total reach: ${summary.total_reach.toLocaleString()}`);
+    if (summary.total_views !== null) lines.push(`• Total views: ${summary.total_views.toLocaleString()}`);
+    if (summary.total_accounts_engaged !== null) {
+      lines.push(`• Total accounts engaged: ${summary.total_accounts_engaged.toLocaleString()}`);
+    }
+    lines.push(
+      `• Engagement rate (by reach): ${summary.engagement_rate}%`,
+      `• Engagement rate (by followers): ${summary.engagement_rate_by_followers}%`
+    );
+
+    if (account.platform === 'google_business') {
+      if (summary.total_website_clicks !== null) {
+        lines.push(`• Website clicks: ${summary.total_website_clicks.toLocaleString()}`);
+      }
+      if (summary.total_call_clicks !== null) {
+        lines.push(`• Call clicks: ${summary.total_call_clicks.toLocaleString()}`);
+      }
+      if (summary.total_direction_requests !== null) {
+        lines.push(`• Direction requests: ${summary.total_direction_requests.toLocaleString()}`);
+      }
+      if (summary.total_conversations !== null) {
+        lines.push(`• Conversations: ${summary.total_conversations.toLocaleString()}`);
+      }
+      if (summary.total_bookings !== null) {
+        lines.push(`• Bookings: ${summary.total_bookings.toLocaleString()}`);
+      }
+    }
+
+    return lines.join('\n');
+  },
+};
+
+function formatDelta(n: number): string {
+  return n >= 0 ? `+${n.toLocaleString()}` : n.toLocaleString();
+}

package/src/tools/get-post-analytics.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const getPostAnalyticsTool = {
+  name: 'get_post_analytics',
+  description:
+    'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays) for a connected social account. Supports Instagram, LinkedIn, and Google Business Profile. Returns the most recent posts first.',
+  inputSchema: z.object({
+    account_id: z
+      .number()
+      .describe('The social account ID (from list_accounts)'),
+    from: z
+      .string()
+      .optional()
+      .describe('Start date (ISO date, e.g. 2026-03-19). Defaults to 30 days ago.'),
+    to: z
+      .string()
+      .optional()
+      .describe('End date (ISO date). Defaults to today.'),
+    limit: z
+      .number()
+      .min(1)
+      .max(200)
+      .optional()
+      .describe('Number of posts to return (default 50, max 200)'),
+    offset: z.number().min(0).optional().describe('Pagination offset'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      account_id: number;
+      from?: string;
+      to?: string;
+      limit?: number;
+      offset?: number;
+    }
+  ) {
+    const result = await client.getPostAnalytics(input);
+    const { account, range, posts, total } = result;
+
+    if (posts.length === 0) {
+      return `No analytics found for @${account.username} (${account.platform}) between ${range.from} and ${range.to}.`;
+    }
+
+    const lines: string[] = [
+      `Post analytics for @${account.username} (${account.platform})`,
+      `Range: ${range.from} → ${range.to}  •  Showing ${posts.length} of ${total}`,
+      '',
+    ];
+
+    for (const p of posts) {
+      const postedAt = p.posted_at
+        ? new Date(p.posted_at).toLocaleString()
+        : 'unknown date';
+      const caption = p.caption_snippet
+        ? p.caption_snippet.length > 60
+          ? `${p.caption_snippet.slice(0, 60)}…`
+          : p.caption_snippet
+        : '(no caption)';
+      const metrics = [
+        `${p.likes} likes`,
+        `${p.comments} comments`,
+        `${p.reach.toLocaleString()} reach`,
+      ];
+      if (p.impressions) metrics.push(`${p.impressions.toLocaleString()} impressions`);
+      if (p.saved) metrics.push(`${p.saved} saved`);
+      if (p.shares) metrics.push(`${p.shares} shares`);
+      if (p.plays) metrics.push(`${p.plays.toLocaleString()} plays`);
+
+      lines.push(`• [${postedAt}] ${caption}`);
+      lines.push(`  ${metrics.join(' • ')}`);
+      if (p.permalink) lines.push(`  ${p.permalink}`);
+    }
+
+    return lines.join('\n');
+  },
+};