posterly-mcp-server 0.36.0 → 0.37.0

package/src/tools/list-comments.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { truncateText } from '../lib/format.js';
+
+const INBOX_PLATFORMS = ['instagram', 'facebook', 'threads'] as const;
+
+export const listCommentsTool = {
+  name: 'list_comments',
+  description:
+    'List social inbox comments and replies for Instagram, Facebook Pages, and Threads. Filter by account, platform, unread/flagged, or search. Requires a Pro plan or higher plus posts:read.',
+  inputSchema: z.object({
+    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    account_id: z.number().int().positive().optional().describe('Social account ID from list_accounts.'),
+    platform: z.enum(INBOX_PLATFORMS).optional().describe('instagram, facebook, or threads.'),
+    filter: z.enum(['all', 'unread', 'flagged']).optional().describe('Comment filter. Defaults to all.'),
+    search: z.string().optional().describe('Search comment content or author username.'),
+    limit: z.number().int().min(1).max(100).optional().describe('Number of comments to return. Default 50, max 100.'),
+    offset: z.number().int().min(0).optional().describe('Skip this many comments before returning results.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      workspace_id?: string;
+      account_id?: number;
+      platform?: 'instagram' | 'facebook' | 'threads';
+      filter?: 'all' | 'unread' | 'flagged';
+      search?: string;
+      limit?: number;
+      offset?: number;
+    },
+  ) {
+    const result = await client.listComments(input);
+    if (result.comments.length === 0) {
+      return 'No inbox comments found matching your filters.';
+    }
+
+    const lines = [`Inbox comments (showing ${result.comments.length} of ${result.total}):`];
+    for (const comment of result.comments) {
+      const author = typeof comment.author_username === 'string' ? `@${comment.author_username}` : 'unknown';
+      const platform = typeof comment.platform === 'string' ? comment.platform : 'unknown';
+      const flags: string[] = [];
+      if (comment.is_read === false) flags.push('unread');
+      if (comment.is_hidden) flags.push('hidden');
+      if (comment.is_flagged) flags.push('flagged');
+      const flagLabel = flags.length > 0 ? `, ${flags.join(', ')}` : '';
+      const text = truncateText(typeof comment.content === 'string' ? comment.content : '', 80);
+      const replies = Array.isArray(comment.replies) ? comment.replies.length : 0;
+      lines.push(`- ${String(comment.id)} (${platform}, ${author}${flagLabel}${replies ? `, ${replies} replies` : ''}): ${text}`);
+    }
+
+    if (result.hasMore) {
+      const nextOffset = (input.offset ?? 0) + result.comments.length;
+      lines.push('', `More comments available. Call again with offset: ${nextOffset}.`);
+    }
+
+    return lines.join('\n');
+  },
+};

package/src/tools/list-conversations.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { truncateText } from '../lib/format.js';
+
+const INBOX_PLATFORMS = ['instagram', 'facebook', 'threads'] as const;
+
+export const listConversationsTool = {
+  name: 'list_conversations',
+  description:
+    'List social inbox DM conversations for Instagram and Facebook Page inboxes. Filter by account, platform, unread/starred/archived, or search. Requires a Pro plan or higher plus posts:read. Threads has no DMs.',
+  inputSchema: z.object({
+    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    account_id: z.number().int().positive().optional().describe('Social account ID from list_accounts.'),
+    platform: z.enum(INBOX_PLATFORMS).optional().describe('instagram or facebook. Threads has no DMs.'),
+    filter: z.enum(['all', 'unread', 'starred', 'archived']).optional().describe('Conversation filter. Defaults to all (excludes archived).'),
+    search: z.string().optional().describe('Search participant username or last message preview.'),
+    limit: z.number().int().min(1).max(100).optional().describe('Number of conversations to return. Default 50, max 100.'),
+    offset: z.number().int().min(0).optional().describe('Skip this many conversations before returning results.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      workspace_id?: string;
+      account_id?: number;
+      platform?: 'instagram' | 'facebook' | 'threads';
+      filter?: 'all' | 'unread' | 'starred' | 'archived';
+      search?: string;
+      limit?: number;
+      offset?: number;
+    },
+  ) {
+    const result = await client.listConversations(input);
+    if (result.conversations.length === 0) {
+      return 'No inbox conversations found matching your filters.';
+    }
+
+    const lines = [`Inbox conversations (showing ${result.conversations.length} of ${result.total}):`];
+    for (const conversation of result.conversations) {
+      const username = typeof conversation.participant_username === 'string' ? `@${conversation.participant_username}` : 'unknown';
+      const platform = typeof conversation.platform === 'string' ? conversation.platform : 'unknown';
+      const unread = conversation.is_read === false ? 'unread' : 'read';
+      const preview = truncateText(typeof conversation.last_message_preview === 'string' ? conversation.last_message_preview : '', 80);
+      lines.push(`- ${String(conversation.id)} (${platform}, ${username}, ${unread}): ${preview}`);
+    }
+
+    if (result.hasMore) {
+      const nextOffset = (input.offset ?? 0) + result.conversations.length;
+      lines.push('', `More conversations available. Call again with offset: ${nextOffset}.`);
+    }
+
+    return lines.join('\n');
+  },
+};

package/src/tools/reply-to-comment.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const replyToCommentTool = {
+  name: 'reply_to_comment',
+  description:
+    'Reply to an Instagram, Facebook Page, or Threads inbox comment. WRITE: posts to the social network. Facebook has no private comment replies. Threads has no DMs, so only public replies. Instagram supports public or private. Requires a Pro plan or higher plus posts:write. Pass confirm=true only after explicit user confirmation.',
+  inputSchema: z.object({
+    comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
+    content: z.string().min(1).describe('Reply text to post.'),
+    type: z.enum(['public', 'private']).optional().describe('public (default) or private. Private is Instagram only.'),
+    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+    confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      comment_id: string;
+      content: string;
+      type?: 'public' | 'private';
+      workspace_id?: string;
+      confirm: true;
+    },
+  ) {
+    const { confirm: _confirm, ...payload } = input;
+    const result = await client.replyToComment(payload);
+    return `Comment reply sent (${result.reply_type}, reply_id ${result.reply_id}).`;
+  },
+};

package/src/tools/send-message.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const sendMessageTool = {
+  name: 'send_message',
+  description:
+    'Send a DM reply in an Instagram or Facebook Page inbox conversation. WRITE: posts to the social network. Honor the 24-hour messaging window. Threads has no DMs. Requires a Pro plan or higher plus posts:write. Pass confirm=true only after explicit user confirmation.',
+  inputSchema: z.object({
+    conversation_id: z.string().min(1).describe('Conversation ID from list_conversations.'),
+    content: z.string().min(1).describe('Message text to send.'),
+    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+    confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      conversation_id: string;
+      content: string;
+      workspace_id?: string;
+      confirm: true;
+    },
+  ) {
+    const { confirm: _confirm, ...payload } = input;
+    const result = await client.sendMessage(payload);
+    return `Message sent (message_id ${result.message_id}).`;
+  },
+};

package/src/tools/sync-inbox.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const syncInboxTool = {
+  name: 'sync_inbox',
+  description:
+    'Pull the latest Instagram, Facebook Page, or Threads inbox data for one connected account. Honors a 30-second cooldown. Threads syncs replies only (no DMs). Requires a Pro plan or higher plus posts:write.',
+  inputSchema: z.object({
+    account_id: z.number().int().positive().describe('Social account ID from list_accounts.'),
+    sync_type: z.enum(['all', 'dm', 'comments']).optional().describe('What to sync. Defaults to all. Threads is comments-only.'),
+    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      account_id: number;
+      sync_type?: 'all' | 'dm' | 'comments';
+      workspace_id?: string;
+    },
+  ) {
+    const result = await client.syncInbox(input);
+    const parts = ['Inbox sync completed.'];
+    const keys = Object.keys(result.results || {});
+    if (keys.length > 0) parts.push(`Synced: ${keys.join(', ')}.`);
+    return parts.join(' ');
+  },
+};

package/src/tools/update-comment.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const updateCommentTool = {
+  name: 'update_comment',
+  description:
+    'Update an inbox comment: hide/unhide it on the platform, or mark it read/unread. Hide is reversible and does not delete the comment. Requires a Pro plan or higher plus posts:write.',
+  inputSchema: z.object({
+    comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
+    is_hidden: z.boolean().optional().describe('Hide or unhide the comment on Instagram, Facebook, or Threads.'),
+    is_read: z.boolean().optional().describe('Mark the comment read or unread in posterly.'),
+    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      comment_id: string;
+      is_hidden?: boolean;
+      is_read?: boolean;
+      workspace_id?: string;
+    },
+  ) {
+    const result = await client.updateComment(input);
+    const comment = result.comment;
+    const parts = [`Comment ${String(comment.id)} updated.`];
+    if (typeof comment.is_hidden === 'boolean') parts.push(`Hidden: ${comment.is_hidden ? 'yes' : 'no'}.`);
+    if (typeof comment.is_read === 'boolean') parts.push(`Read: ${comment.is_read ? 'yes' : 'no'}.`);
+    return parts.join(' ');
+  },
+};

package/tool-annotations.json

@@ -77,7 +77,15 @@
     "update_webhook",
     "delete_webhook",
     "test_webhook",
-    "get_x_posting_quota"
+    "get_x_posting_quota",
+    "list_conversations",
+    "get_conversation",
+    "send_message",
+    "list_comments",
+    "get_comment",
+    "reply_to_comment",
+    "update_comment",
+    "sync_inbox"
   ],
   "readOnlyTools": [
     "get_agent_signup_info",
@@ -117,7 +125,11 @@
     "list_activity",
     "get_updates",
     "list_webhooks",
-    "get_x_posting_quota"
+    "get_x_posting_quota",
+    "list_conversations",
+    "get_conversation",
+    "list_comments",
+    "get_comment"
   ],
   "destructiveTools": [
     "disconnect_account",
@@ -158,7 +170,8 @@
     "delete_google_business_review_reply",
     "delete_google_business_media",
     "update_webhook",
-    "delete_webhook"
+    "delete_webhook",
+    "update_comment"
   ],
   "openWorldTools": [
     "start_signup",
@@ -201,6 +214,10 @@
     "update_webhook",
     "delete_webhook",
     "test_webhook",
-    "get_x_posting_quota"
+    "get_x_posting_quota",
+    "send_message",
+    "reply_to_comment",
+    "update_comment",
+    "sync_inbox"
   ]
 }