posterly-mcp-server 0.4.0 → 0.6.0

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-brand-profile.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const getBrandProfileTool = {
+  name: 'get_brand_profile',
+  description:
+    'Get the extended brand profile for a brand/client. Returns voice/tone guidance, audience, keywords, dos and don’ts, visual notes, and other saved brand context.',
+  inputSchema: z.object({
+    brand_id: z.string().describe('The brand ID to inspect (from list_brands).'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { brand_id: string },
+  ) {
+    const result = await client.getBrandProfile(input.brand_id);
+    const profile = result.brand_profile as Record<string, any>;
+
+    const lines = [
+      `Brand profile: ${profile.brand_name}`,
+      `• Source: ${profile.source}`,
+    ];
+
+    if (profile.workspace_client_id) lines.push(`• Workspace client ID: ${profile.workspace_client_id}`);
+    if (profile.brand_group_id) lines.push(`• Legacy brand group ID: ${profile.brand_group_id}`);
+    if (profile.tone_of_voice) lines.push(`• Tone of voice: ${profile.tone_of_voice}`);
+    if (profile.audience) lines.push(`• Audience: ${profile.audience}`);
+    if (profile.brand_values) lines.push(`• Brand values: ${profile.brand_values}`);
+    if (profile.custom_instructions) lines.push(`• Custom instructions: ${profile.custom_instructions}`);
+    if (profile.logo_url) lines.push(`• Logo URL: ${profile.logo_url}`);
+
+    addStructuredLine(lines, 'Keywords', profile.keywords);
+    addStructuredLine(lines, 'Competitors', profile.competitors);
+    addStructuredLine(lines, 'Do / Don’ts', profile.do_donts);
+    addStructuredLine(lines, 'Visual guidelines', profile.visual_guidelines);
+    addStructuredLine(lines, 'Brand story', profile.brand_story);
+    addStructuredLine(lines, 'Example posts', profile.example_posts);
+    addStructuredLine(lines, 'Topics to cover', profile.topics_to_cover);
+    addStructuredLine(lines, 'Topics to avoid', profile.topics_to_avoid);
+    addStructuredLine(lines, 'Voice examples', profile.voice_examples);
+
+    if (profile.last_context_refresh_at) {
+      lines.push(`• Last refreshed: ${profile.last_context_refresh_at}`);
+    }
+
+    if (lines.length === 2) {
+      lines.push('• No extended brand profile fields have been saved yet.');
+    }
+
+    return lines.join('\n');
+  },
+};
+
+function addStructuredLine(lines: string[], label: string, value: unknown) {
+  const formatted = formatStructuredValue(value);
+  if (formatted) {
+    lines.push(`• ${label}: ${formatted}`);
+  }
+}
+
+function formatStructuredValue(value: unknown): string | null {
+  if (value == null) return null;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+    return value
+      .map((item) => formatStructuredValue(item) || JSON.stringify(item))
+      .filter(Boolean)
+      .join(' | ');
+  }
+  if (typeof value === 'object') {
+    const json = JSON.stringify(value);
+    return json === '{}' ? null : json;
+  }
+  return String(value);
+}

package/src/tools/get-brand.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+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: PosterlyClient,
+    input: { brand_id: string },
+  ) {
+    const result = await client.getBrand(input.brand_id);
+    const brand = result.brand as Record<string, any>;
+
+    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/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');
+  },
+};

package/src/tools/list-brand-accounts.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+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: PosterlyClient,
+    input: { brand_id: string },
+  ) {
+    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/src/tools/list-brands.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+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: PosterlyClient, input: { workspace_id?: string }) {
+    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/src/tools/list-posts.ts

@@ -4,7 +4,7 @@ import type { PosterlyClient } from '../lib/api-client.js';
 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.',
+    '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()
@@ -14,12 +14,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()
@@ -28,11 +32,17 @@ export const listPostsTool = {
 
   async execute(
     client: PosterlyClient,
-    input: { status?: string; platform?: string; limit?: number; workspace_id?: string }
+    input: {
+      status?: string;
+      platform?: string;
+      account_id?: string;
+      limit?: number;
+      workspace_id?: string;
+    }
   ) {
     const { posts, total } = await client.listPosts({
       ...input,
-      limit: input.limit || 10,
+      limit: input.limit || 20,
     });
 
     if (posts.length === 0) {