posterly-mcp-server 0.4.0 → 0.5.0

package/dist/index.js

@@ -12,9 +12,11 @@ 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.4.0',
+    version: '0.5.0',
 });
 let client;
 try {
@@ -115,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;
@@ -130,6 +210,18 @@ export declare class PosterlyClient {
         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

@@ -85,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/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.4.0",
+  "version": "0.5.0",
   "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -13,10 +13,12 @@ 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.4.0',
+  version: '0.5.0',
 });
 
 let client: PosterlyClient;
@@ -169,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;
@@ -198,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/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');
+  },
+};