posterly-mcp-server 0.4.0 → 0.6.0

package/dist/tools/get-brand.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export const getBrandTool = {
+    name: 'get_brand',
+    description: 'Get one brand/client by ID. Returns its workspace, source, linked legacy brand group if present, and the number of social accounts assigned to it.',
+    inputSchema: z.object({
+        brand_id: z.string().describe('The brand ID to look up (from list_brands).'),
+    }),
+    async execute(client, input) {
+        const result = await client.getBrand(input.brand_id);
+        const brand = result.brand;
+        const lines = [
+            `Brand: ${brand.name}`,
+            `• ID: ${brand.id}`,
+            `• Source: ${brand.source}`,
+            `• Workspace: ${brand.workspace_id || 'N/A'}`,
+            `• Accounts assigned: ${brand.account_count ?? 0}`,
+        ];
+        if (brand.workspace_client_id)
+            lines.push(`• Workspace client ID: ${brand.workspace_client_id}`);
+        if (brand.legacy_brand_group_id)
+            lines.push(`• Legacy brand group ID: ${brand.legacy_brand_group_id}`);
+        if (brand.created_at)
+            lines.push(`• Created: ${brand.created_at}`);
+        if (brand.updated_at)
+            lines.push(`• Updated: ${brand.updated_at}`);
+        return lines.join('\n');
+    },
+};

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/dist/tools/list-brand-accounts.d.ts

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

package/dist/tools/list-brand-accounts.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const listBrandAccountsTool = {
+    name: 'list_brand_accounts',
+    description: 'List the connected social accounts assigned to a brand/client. Use this when a user refers to a brand name rather than a raw account handle.',
+    inputSchema: z.object({
+        brand_id: z.string().describe('The brand ID to inspect (from list_brands).'),
+    }),
+    async execute(client, input) {
+        const accounts = await client.listBrandAccounts(input.brand_id);
+        if (accounts.length === 0) {
+            return 'No social accounts are currently assigned to this brand.';
+        }
+        const lines = accounts.map((account) => `• ${account.platform} — @${account.username} (ID: ${account.id}${account.workspace_id ? `, ws: ${account.workspace_id}` : ''})`);
+        return `Brand accounts (${accounts.length}):\n${lines.join('\n')}`;
+    },
+};

package/dist/tools/list-brands.d.ts

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

package/dist/tools/list-brands.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export const listBrandsTool = {
+    name: 'list_brands',
+    description: 'List brands/clients the caller can access. Returns each brand ID, name, workspace ID, source, and how many social accounts are currently assigned to it.',
+    inputSchema: z.object({
+        workspace_id: z
+            .string()
+            .optional()
+            .describe('Filter to brands in a specific workspace (get IDs via whoami).'),
+    }),
+    async execute(client, input) {
+        const brands = await client.listBrands({ workspace_id: input.workspace_id });
+        if (brands.length === 0) {
+            return input.workspace_id
+                ? 'No brands found in this workspace.'
+                : 'No brands found. Create brands in the posterly dashboard first.';
+        }
+        const lines = brands.map((brand) => {
+            const suffix = [
+                `ID: ${brand.id}`,
+                brand.workspace_id ? `ws: ${brand.workspace_id}` : null,
+                `accounts: ${brand.account_count}`,
+                brand.source,
+            ].filter(Boolean).join(', ');
+            return `• ${brand.name} (${suffix})`;
+        });
+        return `Brands (${brands.length}):\n${lines.join('\n')}`;
+    },
+};

package/dist/tools/list-posts.d.ts

@@ -6,22 +6,26 @@ export declare const listPostsTool: {
     inputSchema: z.ZodObject<{
         status: z.ZodOptional<z.ZodString>;
         platform: z.ZodOptional<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodString>;
         limit: z.ZodOptional<z.ZodNumber>;
         workspace_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
         status?: string | undefined;
         platform?: string | undefined;
+        account_id?: string | undefined;
         limit?: number | undefined;
     }, {
         workspace_id?: string | undefined;
         status?: string | undefined;
         platform?: string | undefined;
+        account_id?: string | undefined;
         limit?: number | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         status?: string;
         platform?: string;
+        account_id?: string;
         limit?: number;
         workspace_id?: string;
     }): Promise<string>;

package/dist/tools/list-posts.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export const listPostsTool = {
     name: 'list_posts',
-    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, or workspace_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
+    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, or workspace_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
     inputSchema: z.object({
         status: z
             .string()
@@ -11,12 +11,16 @@ export const listPostsTool = {
             .string()
             .optional()
             .describe('Filter by platform: instagram, twitter, linkedin, etc.'),
+        account_id: z
+            .string()
+            .optional()
+            .describe('Filter to a specific social account ID (from list_accounts).'),
         limit: z
             .number()
             .min(1)
-            .max(50)
+            .max(100)
             .optional()
-            .describe('Number of posts to return (default 10, max 50)'),
+            .describe('Number of posts to return (default 20, max 100)'),
         workspace_id: z
             .string()
             .optional()
@@ -25,7 +29,7 @@ export const listPostsTool = {
     async execute(client, input) {
         const { posts, total } = await client.listPosts({
             ...input,
-            limit: input.limit || 10,
+            limit: input.limit || 20,
         });
         if (posts.length === 0) {
             return 'No posts found matching your criteria.';

package/package.json

@@ -1,8 +1,27 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
   "license": "MIT",
+  "homepage": "https://www.poster.ly/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awpthorp/posterly.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/awpthorp/posterly/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "posterly",
+    "social-media",
+    "scheduling",
+    "claude",
+    "cursor",
+    "chatgpt"
+  ],
   "type": "module",
   "bin": {
     "posterly-mcp": "./dist/index.js"

package/src/index.ts

@@ -4,6 +4,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { PosterlyClient } from './lib/api-client.js';
 import { listAccountsTool } from './tools/list-accounts.js';
+import { listBrandsTool } from './tools/list-brands.js';
+import { getBrandTool } from './tools/get-brand.js';
+import { listBrandAccountsTool } from './tools/list-brand-accounts.js';
+import { getBrandProfileTool } from './tools/get-brand-profile.js';
 import { createPostTool } from './tools/create-post.js';
 import { findSlotTool } from './tools/find-slot.js';
 import { listPostsTool } from './tools/list-posts.js';
@@ -13,10 +17,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.6.0',
 });
 
 let client: PosterlyClient;
@@ -57,6 +63,62 @@ server.tool(
   }
 );
 
+server.tool(
+  listBrandsTool.name,
+  listBrandsTool.description,
+  listBrandsTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await listBrandsTool.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(
+  getBrandTool.name,
+  getBrandTool.description,
+  getBrandTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await getBrandTool.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(
+  listBrandAccountsTool.name,
+  listBrandAccountsTool.description,
+  listBrandAccountsTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await listBrandAccountsTool.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(
+  getBrandProfileTool.name,
+  getBrandProfileTool.description,
+  getBrandProfileTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await getBrandProfileTool.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(
   createPostTool.name,
   createPostTool.description,
@@ -169,6 +231,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

@@ -10,6 +10,43 @@ export interface Account {
   workspace_id?: string | null;
 }
 
+export interface Brand {
+  id: string;
+  name: string;
+  workspace_id?: string | null;
+  workspace_client_id?: string | null;
+  legacy_brand_group_id?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  source: 'canonical' | 'legacy';
+  account_count: number;
+}
+
+export interface BrandProfile {
+  id: string | null;
+  brand_group_id: string | null;
+  workspace_client_id: string | null;
+  brand_name: string;
+  tone_of_voice?: string | null;
+  audience?: string | null;
+  brand_values?: string | null;
+  do_donts?: unknown;
+  keywords?: unknown;
+  competitors?: unknown;
+  custom_instructions?: string | null;
+  visual_guidelines?: unknown;
+  logo_url?: string | null;
+  brand_story?: string | null;
+  example_posts?: unknown;
+  topics_to_cover?: unknown;
+  topics_to_avoid?: unknown;
+  voice_examples?: unknown;
+  last_context_refresh_at?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  source: 'canonical' | 'legacy';
+}
+
 export interface Post {
   id: number;
   content: string;
@@ -45,6 +82,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;
@@ -99,9 +207,31 @@ export class PosterlyClient {
     return data.accounts;
   }
 
+  async listBrands(params?: { workspace_id?: string }): Promise<Brand[]> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    const qs = searchParams.toString();
+    const data = await this.request<{ brands: Brand[] }>('GET', `/brands${qs ? `?${qs}` : ''}`);
+    return data.brands;
+  }
+
+  async getBrand(id: string): Promise<{ brand: Brand }> {
+    return this.request('GET', `/brands/${encodeURIComponent(id)}`);
+  }
+
+  async listBrandAccounts(id: string): Promise<Account[]> {
+    const data = await this.request<{ accounts: Account[] }>('GET', `/brands/${encodeURIComponent(id)}/accounts`);
+    return data.accounts;
+  }
+
+  async getBrandProfile(id: string): Promise<{ brand_profile: BrandProfile }> {
+    return this.request('GET', `/brands/${encodeURIComponent(id)}/profile`);
+  }
+
   async listPosts(params?: {
     status?: string;
     platform?: string;
+    account_id?: string;
     limit?: number;
     offset?: number;
     workspace_id?: string;
@@ -109,6 +239,7 @@ export class PosterlyClient {
     const searchParams = new URLSearchParams();
     if (params?.status) searchParams.set('status', params.status);
     if (params?.platform) searchParams.set('platform', params.platform);
+    if (params?.account_id) searchParams.set('account_id', params.account_id);
     if (params?.limit) searchParams.set('limit', String(params.limit));
     if (params?.offset) searchParams.set('offset', String(params.offset));
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
@@ -198,6 +329,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,