posterly-mcp-server 0.23.2 → 0.24.0

package/src/lib/api-client.ts

@@ -62,6 +62,77 @@ export interface LearnedVoice {
   derived_at: string | null;
 }
 
+export interface PerformanceProfile {
+  social_account_id: number;
+  platform: string;
+  username: string | null;
+  sample_size: number;
+  window_days: number;
+  engagement_rate_avg: number | null;
+  engagement_rate_trend: 'up' | 'down' | 'flat' | 'unknown';
+  bullets: string[];
+  narrative_summary: string | null;
+  stats: Record<string, unknown>;
+  derived_at: string | null;
+}
+
+export type PerformanceProfileNullReason =
+  | 'insufficient_data'
+  | 'feature_not_available'
+  | 'platform_not_measurable';
+
+export interface PerformanceProfileResponse {
+  performance_profile: PerformanceProfile | null;
+  reason: PerformanceProfileNullReason | null;
+}
+
+export interface FeedbackInsight {
+  id: string;
+  post_id: number;
+  social_account_id: number;
+  username: string | null;
+  platform: string;
+  checkpoint: '1h' | '6h' | '24h' | '72h' | '7d';
+  performance_tier: string;
+  action_type: string;
+  title: string;
+  diagnosis: string;
+  next_action: string;
+  impact_score: number;
+  confidence: number;
+  metrics: Record<string, unknown>;
+  baseline: Record<string, unknown>;
+  caption: string | null;
+  permalink: string | null;
+  published_at: string | null;
+  created_at: string;
+}
+
+export interface FeedbackInsightsResponse {
+  insights: FeedbackInsight[];
+}
+
+export interface PostSuggestion {
+  id: string;
+  social_account_id: number;
+  platform: string;
+  account: { id: number; username: string | null; platform: string };
+  caption: string;
+  rationale: string | null;
+  period_key: string | null;
+  status: string;
+  created_at: string;
+}
+
+export interface PostSuggestionsResponse {
+  suggestions: PostSuggestion[];
+}
+
+export interface DismissSuggestionResponse {
+  ok: boolean;
+  status: string;
+}
+
 export interface Post {
   id: number;
   content: string;
@@ -889,6 +960,42 @@ export class PosterlyClient {
     return this.request('GET', `/accounts/${encodeURIComponent(String(id))}/learned-voice`);
   }
 
+  async getAccountPerformanceProfile(id: string | number): Promise<PerformanceProfileResponse> {
+    return this.request('GET', `/accounts/${encodeURIComponent(String(id))}/performance-profile`);
+  }
+
+  async getPostInsights(params?: {
+    account_id?: string | number;
+    post_id?: number;
+    checkpoint?: '1h' | '6h' | '24h' | '72h' | '7d';
+    limit?: number;
+  }): Promise<FeedbackInsightsResponse> {
+    const searchParams = new URLSearchParams();
+    if (params?.account_id) searchParams.set('account_id', String(params.account_id));
+    if (params?.post_id) searchParams.set('post_id', String(params.post_id));
+    if (params?.checkpoint) searchParams.set('checkpoint', params.checkpoint);
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    const qs = searchParams.toString();
+    return this.request('GET', `/analytics/insights${qs ? `?${qs}` : ''}`);
+  }
+
+  async listPostSuggestions(params?: {
+    account_id?: string | number;
+    status?: 'pending' | 'scheduled' | 'dismissed';
+    limit?: number;
+  }): Promise<PostSuggestionsResponse> {
+    const searchParams = new URLSearchParams();
+    if (params?.account_id) searchParams.set('account_id', String(params.account_id));
+    if (params?.status) searchParams.set('status', params.status);
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    const qs = searchParams.toString();
+    return this.request('GET', `/suggestions${qs ? `?${qs}` : ''}`);
+  }
+
+  async dismissSuggestion(id: string): Promise<DismissSuggestionResponse> {
+    return this.request('POST', `/suggestions/${encodeURIComponent(id)}/dismiss`, {});
+  }
+
   async listPosts(params?: {
     status?: string;
     platform?: string;

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.23.1';
+export const POSTERLY_MCP_VERSION = '0.24.0';

package/src/tools/create-connect-session.ts

@@ -10,7 +10,7 @@ export const createConnectSessionTool = {
   inputSchema: z.object({
     platform: z
       .enum(CONNECT_INPUTS)
-      .describe('Connection target such as instagram, meta, linkedin_page, twitter, google_business, telegram, or bluesky.'),
+      .describe('Connection target such as instagram, meta, linkedin_page, twitter, google_business, telegram, bluesky, discord, mastodon, devto, hashnode, wordpress, or lemmy.'),
     workspace_id: z
       .string()
       .optional()

package/src/tools/create-post.ts

@@ -39,6 +39,7 @@ export const platformSettingsSchema = z.object({
   // Threads
   reply_control: z.enum(['everyone', 'accounts_you_follow', 'mentioned_only', 'followers_only', 'parent_post_author_only']).optional(),
   topic_tag: z.string().optional(), // Threads single discovery topic tag
+  share_to_instagram: z.boolean().optional(), // Threads: also share the published post to the linked Instagram account as a Story
   text_attachment: z.record(z.unknown()).optional(),
   // Facebook
   text_format_preset_id: z.string().optional(),

package/src/tools/dismiss-suggestion.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { mdSuccess } from '../lib/format.js';
+
+export const dismissSuggestionTool = {
+  name: 'dismiss_suggestion',
+  description:
+    'Dismiss a proactive post suggestion so it stops appearing. WRITE: confirm the exact suggestion with the user first. Never dismisses a suggestion that was already turned into a scheduled post (that would break adoption tracking).',
+  inputSchema: z.object({
+    suggestion_id: z
+      .string()
+      .describe('Suggestion ID from list_post_suggestions.'),
+  }),
+
+  async execute(client: PosterlyClient, input: { suggestion_id: string }) {
+    const result = await client.dismissSuggestion(input.suggestion_id);
+    return mdSuccess('Suggestion dismissed', [
+      ['Suggestion ID', input.suggestion_id],
+      ['Status', result.status || 'dismissed'],
+    ]);
+  },
+};

package/src/tools/get-performance-profile.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { mdTitle, mdSection, mdKeyValue, mdBullets, mdQuote, mdEmpty, formatPercent, formatDateTime } from '../lib/format.js';
+
+export const getPerformanceProfileTool = {
+  name: 'get_performance_profile',
+  description:
+    "Get the performance profile posterly has derived for a connected account from the last 90 days of per-post analytics. Returns coaching stats (format, timing, caption-length patterns), an engagement-rate trend, and a narrative summary. Keyed by social account ID (from list_accounts or list_brand_accounts). Returns nothing until the account has a derived profile; Google Business Profile and other platforms without per-post analytics never get one. Read-only; requires a Pro plan or higher.",
+  inputSchema: z.object({
+    account_id: z
+      .union([z.string(), z.number()])
+      .describe('The social account ID to inspect (from list_accounts or list_brand_accounts).'),
+  }),
+
+  async execute(client: PosterlyClient, input: { account_id: string | number }) {
+    const { performance_profile, reason } = await client.getAccountPerformanceProfile(input.account_id);
+
+    if (!performance_profile) {
+      const detail = reason === 'platform_not_measurable'
+        ? 'This platform does not produce per-post analytics, so posterly cannot build a performance profile for it.'
+        : reason === 'feature_not_available'
+          ? 'Performance profiles require a Pro plan or higher.'
+          : 'posterly has not built a performance profile for this account yet. It needs about 90 days of tracked posts to learn from.';
+      return mdEmpty('performance profile yet', detail);
+    }
+
+    const label = performance_profile.username
+      ? `@${performance_profile.username}${performance_profile.platform ? ` (${performance_profile.platform})` : ''}`
+      : `account ${performance_profile.social_account_id}`;
+
+    const rate = performance_profile.engagement_rate_avg != null
+      ? formatPercent(performance_profile.engagement_rate_avg * 100)
+      : 'n/a';
+
+    return [
+      mdTitle('Account performance profile', `${label} · last ${performance_profile.window_days ?? 90} days`),
+      performance_profile.narrative_summary ? mdSection('Summary', mdQuote(performance_profile.narrative_summary)) : '',
+      performance_profile.bullets.length ? mdSection('What is working', mdBullets(performance_profile.bullets)) : '',
+      mdSection('Stats', mdKeyValue([
+        ['Posts sampled', performance_profile.sample_size],
+        ['Avg engagement rate', rate],
+        ['Engagement trend', performance_profile.engagement_rate_trend],
+        ['Derived at', formatDateTime(performance_profile.derived_at)],
+      ])),
+    ].filter(Boolean).join('\n\n');
+  },
+};

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { mdTitle, mdSection, mdKeyValue, mdEmpty, truncateText, formatDateTime } from '../lib/format.js';
+
+export const getPostInsightsTool = {
+  name: 'get_post_insights',
+  description:
+    'List per-post feedback insights from the posterly performance feedback loop: for recently published posts, the performance tier (great/good/mixed/poor), a diagnosis, a suggested next action, metrics, and the baseline it was compared against. Filter by account_id, post_id, and checkpoint (1h, 6h, 24h, 72h, 7d). Read-only; requires a Pro plan or higher.',
+  inputSchema: z.object({
+    account_id: z
+      .union([z.string(), z.number()])
+      .optional()
+      .describe('Filter to one social account ID (from list_accounts).'),
+    post_id: z.number().int().positive().optional().describe('Filter to one post ID.'),
+    checkpoint: z
+      .enum(['1h', '6h', '24h', '72h', '7d'])
+      .optional()
+      .describe('Filter to one checkpoint after publish.'),
+    limit: z.number().int().min(1).max(100).optional().describe('Max insights to return (default 20).'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      account_id?: string | number;
+      post_id?: number;
+      checkpoint?: '1h' | '6h' | '24h' | '72h' | '7d';
+      limit?: number;
+    },
+  ) {
+    const { insights } = await client.getPostInsights(input);
+
+    if (!insights.length) {
+      return mdEmpty(
+        'feedback insights',
+        'No per-post feedback insights are available for these filters yet. Insights appear as posts hit their 1h, 6h, 24h, 72h, and 7d checkpoints.',
+      );
+    }
+
+    const blocks = insights.map((insight) => {
+      const heading = `${insight.title || 'Insight'} (${insight.performance_tier}, ${insight.checkpoint})`;
+      return mdSection(
+        heading,
+        mdKeyValue([
+          ['Post ID', insight.post_id],
+          ['Platform', insight.platform],
+          ['Account', insight.username ? `@${insight.username}` : String(insight.social_account_id)],
+          ['Diagnosis', truncateText(insight.diagnosis, 220)],
+          ['Next action', truncateText(insight.next_action, 220)],
+          ['Impact score', insight.impact_score],
+          ['Confidence', insight.confidence],
+          ['Published', formatDateTime(insight.published_at)],
+          ['Permalink', insight.permalink || undefined],
+        ]),
+      );
+    });
+
+    return [mdTitle(`Post feedback insights (${insights.length})`), ...blocks].join('\n\n');
+  },
+};

package/src/tools/list-post-suggestions.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { mdTitle, mdSection, mdKeyValue, mdEmpty, truncateText } from '../lib/format.js';
+
+export const listPostSuggestionsTool = {
+  name: 'list_post_suggestions',
+  description:
+    "List proactive post suggestions: evidence-based weekly drafts posterly writes in each account's learned voice, each with a rationale tying it back to what has performed well for that account. Filter by account_id and status (pending, scheduled, dismissed; default pending). Read-only; requires a Pro plan or higher. Use dismiss_suggestion to hide one.",
+  inputSchema: z.object({
+    account_id: z
+      .union([z.string(), z.number()])
+      .optional()
+      .describe('Filter to one social account ID (from list_accounts).'),
+    status: z
+      .enum(['pending', 'scheduled', 'dismissed'])
+      .optional()
+      .describe('Suggestion status to list (default pending).'),
+    limit: z.number().int().min(1).max(100).optional().describe('Max suggestions to return (default 20).'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      account_id?: string | number;
+      status?: 'pending' | 'scheduled' | 'dismissed';
+      limit?: number;
+    },
+  ) {
+    const { suggestions } = await client.listPostSuggestions(input);
+
+    if (!suggestions.length) {
+      return mdEmpty(
+        'post suggestions',
+        'No proactive post suggestions match these filters. posterly generates fresh drafts weekly for accounts with a learned voice.',
+      );
+    }
+
+    const blocks = suggestions.map((suggestion) => {
+      const label = suggestion.account?.username
+        ? `@${suggestion.account.username} (${suggestion.platform || suggestion.account?.platform})`
+        : `account ${suggestion.social_account_id}`;
+      return mdSection(
+        label,
+        mdKeyValue([
+          ['Suggestion ID', suggestion.id],
+          ['Status', suggestion.status],
+          ['Period', suggestion.period_key || undefined],
+          ['Caption', truncateText(suggestion.caption, 240)],
+          ['Rationale', suggestion.rationale ? truncateText(suggestion.rationale, 240) : undefined],
+        ]),
+      );
+    });
+
+    return [mdTitle(`Post suggestions (${suggestions.length})`), ...blocks].join('\n\n');
+  },
+};

package/src/tools/update-post.ts

@@ -30,6 +30,7 @@ const platformSettingsSchema = z.object({
   poll: z.object({ options: z.array(z.string()), duration_minutes: z.number().positive().optional(), question: z.string().optional(), duration: z.enum(['ONE_DAY', 'THREE_DAYS', 'SEVEN_DAYS', 'FOURTEEN_DAYS']).optional(), allows_multiple_answers: z.boolean().optional() }).optional(),
   reply_control: z.enum(['everyone', 'accounts_you_follow', 'mentioned_only', 'followers_only', 'parent_post_author_only']).optional(),
   topic_tag: z.string().optional(),
+  share_to_instagram: z.boolean().optional(), // Threads: also share the published post to the linked Instagram account as a Story
   text_attachment: z.record(z.unknown()).optional(),
   text_format_preset_id: z.string().optional(),
   document_title: z.string().optional(),