posterly-mcp-server 0.36.0 → 0.37.0

package/dist/tools/list-conversations.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { truncateText } from '../lib/format.js';
+const INBOX_PLATFORMS = ['instagram', 'facebook', 'threads'];
+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, input) {
+        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/dist/tools/reply-to-comment.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const replyToCommentTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        comment_id: z.ZodString;
+        content: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<["public", "private"]>>;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        confirm: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        confirm: true;
+        comment_id: string;
+        workspace_id?: string | undefined;
+        type?: "public" | "private" | undefined;
+    }, {
+        content: string;
+        confirm: true;
+        comment_id: string;
+        workspace_id?: string | undefined;
+        type?: "public" | "private" | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        comment_id: string;
+        content: string;
+        type?: "public" | "private";
+        workspace_id?: string;
+        confirm: true;
+    }): Promise<string>;
+};

package/dist/tools/reply-to-comment.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+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, input) {
+        const { confirm: _confirm, ...payload } = input;
+        const result = await client.replyToComment(payload);
+        return `Comment reply sent (${result.reply_type}, reply_id ${result.reply_id}).`;
+    },
+};

package/dist/tools/send-message.d.ts

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

package/dist/tools/send-message.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+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, input) {
+        const { confirm: _confirm, ...payload } = input;
+        const result = await client.sendMessage(payload);
+        return `Message sent (message_id ${result.message_id}).`;
+    },
+};

package/dist/tools/sync-inbox.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const syncInboxTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        account_id: z.ZodNumber;
+        sync_type: z.ZodOptional<z.ZodEnum<["all", "dm", "comments"]>>;
+        workspace_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        account_id: number;
+        workspace_id?: string | undefined;
+        sync_type?: "all" | "dm" | "comments" | undefined;
+    }, {
+        account_id: number;
+        workspace_id?: string | undefined;
+        sync_type?: "all" | "dm" | "comments" | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        account_id: number;
+        sync_type?: "all" | "dm" | "comments";
+        workspace_id?: string;
+    }): Promise<string>;
+};

package/dist/tools/sync-inbox.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+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, input) {
+        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/dist/tools/update-comment.d.ts

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

package/dist/tools/update-comment.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+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, input) {
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "mcpName": "io.github.awpthorp/posterly",
   "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.awpthorp/posterly",
   "title": "posterly",
   "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "websiteUrl": "https://www.poster.ly/mcp",
   "repository": {
     "url": "https://github.com/awpthorp/posterly",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "posterly-mcp-server",
-      "version": "0.36.0",
+      "version": "0.37.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -54,6 +54,14 @@ import { deleteGoogleBusinessReviewReplyTool } from './tools/delete-google-busin
 import { listGoogleBusinessMediaTool } from './tools/list-google-business-media.js';
 import { addGoogleBusinessMediaTool } from './tools/add-google-business-media.js';
 import { deleteGoogleBusinessMediaTool } from './tools/delete-google-business-media.js';
+import { listConversationsTool } from './tools/list-conversations.js';
+import { getConversationTool } from './tools/get-conversation.js';
+import { sendMessageTool } from './tools/send-message.js';
+import { listCommentsTool } from './tools/list-comments.js';
+import { getCommentTool } from './tools/get-comment.js';
+import { replyToCommentTool } from './tools/reply-to-comment.js';
+import { updateCommentTool } from './tools/update-comment.js';
+import { syncInboxTool } from './tools/sync-inbox.js';
 import { listActivityTool } from './tools/list-activity.js';
 import { getUpdatesTool } from './tools/get-updates.js';
 import { listWebhooksTool } from './tools/list-webhooks.js';
@@ -1142,6 +1150,126 @@ server.tool(
   }
 );
 
+server.tool(
+  listConversationsTool.name,
+  listConversationsTool.description,
+  listConversationsTool.inputSchema.shape,
+  getToolAnnotations(listConversationsTool.name),
+  async (input) => {
+    try {
+      const text = await listConversationsTool.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(
+  getConversationTool.name,
+  getConversationTool.description,
+  getConversationTool.inputSchema.shape,
+  getToolAnnotations(getConversationTool.name),
+  async (input) => {
+    try {
+      const text = await getConversationTool.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(
+  sendMessageTool.name,
+  sendMessageTool.description,
+  sendMessageTool.inputSchema.shape,
+  getToolAnnotations(sendMessageTool.name),
+  async (input) => {
+    try {
+      const text = await sendMessageTool.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(
+  listCommentsTool.name,
+  listCommentsTool.description,
+  listCommentsTool.inputSchema.shape,
+  getToolAnnotations(listCommentsTool.name),
+  async (input) => {
+    try {
+      const text = await listCommentsTool.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(
+  getCommentTool.name,
+  getCommentTool.description,
+  getCommentTool.inputSchema.shape,
+  getToolAnnotations(getCommentTool.name),
+  async (input) => {
+    try {
+      const text = await getCommentTool.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(
+  replyToCommentTool.name,
+  replyToCommentTool.description,
+  replyToCommentTool.inputSchema.shape,
+  getToolAnnotations(replyToCommentTool.name),
+  async (input) => {
+    try {
+      const text = await replyToCommentTool.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(
+  updateCommentTool.name,
+  updateCommentTool.description,
+  updateCommentTool.inputSchema.shape,
+  getToolAnnotations(updateCommentTool.name),
+  async (input) => {
+    try {
+      const text = await updateCommentTool.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(
+  syncInboxTool.name,
+  syncInboxTool.description,
+  syncInboxTool.inputSchema.shape,
+  getToolAnnotations(syncInboxTool.name),
+  async (input) => {
+    try {
+      const text = await syncInboxTool.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(
   listActivityTool.name,
   listActivityTool.description,

package/src/lib/api-client.ts

@@ -629,6 +629,53 @@ export interface GoogleBusinessReviewLinkResponse {
   account_id: number;
 }
 
+export interface InboxListParams {
+  workspace_id?: string;
+  account_id?: number | number[];
+  platform?: string | string[];
+  filter?: string;
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface InboxConversationsResponse {
+  conversations: Array<Record<string, unknown>>;
+  total: number;
+  hasMore: boolean;
+}
+
+export interface InboxConversationResponse {
+  conversation: Record<string, unknown>;
+  messages: Array<Record<string, unknown>>;
+}
+
+export interface InboxCommentsResponse {
+  comments: Array<Record<string, unknown>>;
+  total: number;
+  hasMore: boolean;
+}
+
+export interface InboxCommentResponse {
+  comment: Record<string, unknown>;
+}
+
+export interface InboxSendMessageResponse {
+  success: true;
+  message_id: string;
+}
+
+export interface InboxCommentReplyResponse {
+  success: true;
+  reply_type: string;
+  reply_id: string;
+}
+
+export interface InboxSyncResponse {
+  success: true;
+  results: Record<string, unknown>;
+}
+
 export interface ActivityItem {
   id: string;
   type: 'activity' | 'publish';
@@ -1725,6 +1772,103 @@ export class PosterlyClient {
       content_type: input.contentType,
     });
   }
+
+  private appendInboxListParams(searchParams: URLSearchParams, params?: InboxListParams) {
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    const accountIds = params?.account_id == null ? [] : Array.isArray(params.account_id) ? params.account_id : [params.account_id];
+    for (const accountId of accountIds) searchParams.append('account_id', String(accountId));
+    const platforms = params?.platform == null ? [] : Array.isArray(params.platform) ? params.platform : [params.platform];
+    for (const platform of platforms) searchParams.append('platform', platform);
+    if (params?.filter) searchParams.set('filter', params.filter);
+    if (params?.search) searchParams.set('search', params.search);
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.offset != null) searchParams.set('offset', String(params.offset));
+  }
+
+  async listConversations(params?: InboxListParams): Promise<InboxConversationsResponse> {
+    const searchParams = new URLSearchParams();
+    this.appendInboxListParams(searchParams, params);
+    const qs = searchParams.toString();
+    return this.request('GET', `/inbox/conversations${qs ? `?${qs}` : ''}`);
+  }
+
+  async getConversation(params: {
+    conversation_id: string;
+    workspace_id?: string;
+    limit?: number;
+  }): Promise<InboxConversationResponse> {
+    const searchParams = new URLSearchParams();
+    if (params.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    if (params.limit) searchParams.set('limit', String(params.limit));
+    const qs = searchParams.toString();
+    return this.request(
+      'GET',
+      `/inbox/conversations/${encodeURIComponent(params.conversation_id)}${qs ? `?${qs}` : ''}`,
+    );
+  }
+
+  async sendMessage(data: {
+    conversation_id: string;
+    content: string;
+    workspace_id?: string;
+  }): Promise<InboxSendMessageResponse> {
+    const body: Record<string, unknown> = { content: data.content };
+    if (data.workspace_id) body.workspace_id = data.workspace_id;
+    return this.request('POST', `/inbox/conversations/${encodeURIComponent(data.conversation_id)}/reply`, body);
+  }
+
+  async listComments(params?: InboxListParams): Promise<InboxCommentsResponse> {
+    const searchParams = new URLSearchParams();
+    this.appendInboxListParams(searchParams, params);
+    const qs = searchParams.toString();
+    return this.request('GET', `/inbox/comments${qs ? `?${qs}` : ''}`);
+  }
+
+  async getComment(params: {
+    comment_id: string;
+    workspace_id?: string;
+  }): Promise<InboxCommentResponse> {
+    const searchParams = new URLSearchParams();
+    if (params.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    const qs = searchParams.toString();
+    return this.request(
+      'GET',
+      `/inbox/comments/${encodeURIComponent(params.comment_id)}${qs ? `?${qs}` : ''}`,
+    );
+  }
+
+  async replyToComment(data: {
+    comment_id: string;
+    content: string;
+    type?: 'public' | 'private';
+    workspace_id?: string;
+  }): Promise<InboxCommentReplyResponse> {
+    const body: Record<string, unknown> = { content: data.content };
+    if (data.type) body.type = data.type;
+    if (data.workspace_id) body.workspace_id = data.workspace_id;
+    return this.request('POST', `/inbox/comments/${encodeURIComponent(data.comment_id)}/reply`, body);
+  }
+
+  async updateComment(data: {
+    comment_id: string;
+    is_hidden?: boolean;
+    is_read?: boolean;
+    workspace_id?: string;
+  }): Promise<InboxCommentResponse> {
+    const body: Record<string, unknown> = {};
+    if (typeof data.is_hidden === 'boolean') body.is_hidden = data.is_hidden;
+    if (typeof data.is_read === 'boolean') body.is_read = data.is_read;
+    if (data.workspace_id) body.workspace_id = data.workspace_id;
+    return this.request('PATCH', `/inbox/comments/${encodeURIComponent(data.comment_id)}`, body);
+  }
+
+  async syncInbox(data: {
+    account_id: number;
+    sync_type?: 'all' | 'dm' | 'comments';
+    workspace_id?: string;
+  }): Promise<InboxSyncResponse> {
+    return this.request('POST', '/inbox/sync', data);
+  }
 }
 
 export function resolvePosterlyBaseUrl(baseUrl?: string): 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.36.0';
+export const POSTERLY_MCP_VERSION = '0.37.0';

package/src/tools/get-comment.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { formatLocalDateTime } from '../lib/format.js';
+
+export const getCommentTool = {
+  name: 'get_comment',
+  description:
+    'Get one social inbox comment and its replies. Instagram, Facebook Page, and Threads comments. Requires a Pro plan or higher plus posts:read.',
+  inputSchema: z.object({
+    comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
+    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      comment_id: string;
+      workspace_id?: string;
+    },
+  ) {
+    const result = await client.getComment(input);
+    const comment = result.comment;
+    const author = typeof comment.author_username === 'string' ? `@${comment.author_username}` : 'unknown';
+    const lines = [
+      `Comment ${String(comment.id)}`,
+      `• Platform: ${typeof comment.platform === 'string' ? comment.platform : 'unknown'}`,
+      `• Author: ${author}`,
+      `• Hidden: ${comment.is_hidden ? 'yes' : 'no'}`,
+      `• Read: ${comment.is_read === false ? 'no' : 'yes'}`,
+      `• Posted: ${formatLocalDateTime(typeof comment.posted_at === 'string' ? comment.posted_at : null)}`,
+      `• Content: ${typeof comment.content === 'string' ? comment.content : '(empty)'}`,
+    ];
+    if (typeof comment.media_permalink === 'string') lines.push(`• Media: ${comment.media_permalink}`);
+
+    const replies = Array.isArray(comment.replies) ? comment.replies : [];
+    if (replies.length > 0) {
+      lines.push('', `Replies (${replies.length}):`);
+      for (const reply of replies) {
+        const row = reply as Record<string, unknown>;
+        const replyAuthor = typeof row.author_username === 'string' ? `@${row.author_username}` : 'unknown';
+        lines.push(`- ${String(row.id)} ${replyAuthor}: ${typeof row.content === 'string' ? row.content : '(empty)'}`);
+      }
+    }
+
+    return lines.join('\n');
+  },
+};

package/src/tools/get-conversation.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { formatLocalDateTime, truncateText } from '../lib/format.js';
+
+export const getConversationTool = {
+  name: 'get_conversation',
+  description:
+    'Get one social inbox DM conversation and its messages. Instagram and Facebook Page DMs only. Requires a Pro plan or higher plus posts:read.',
+  inputSchema: z.object({
+    conversation_id: z.string().min(1).describe('Conversation ID from list_conversations.'),
+    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    limit: z.number().int().min(1).max(100).optional().describe('Maximum messages to return. Default 50, max 100.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      conversation_id: string;
+      workspace_id?: string;
+      limit?: number;
+    },
+  ) {
+    const result = await client.getConversation(input);
+    const conversation = result.conversation;
+    const username = typeof conversation.participant_username === 'string' ? `@${conversation.participant_username}` : 'unknown';
+    const lines = [
+      `Conversation ${String(conversation.id)}`,
+      `• Platform: ${typeof conversation.platform === 'string' ? conversation.platform : 'unknown'}`,
+      `• Participant: ${username}`,
+      `• Read: ${conversation.is_read === false ? 'no' : 'yes'}`,
+      `• Messages: ${result.messages.length}`,
+      '',
+    ];
+
+    for (const message of result.messages) {
+      const who = message.sender_is_business ? 'you' : (typeof message.sender_username === 'string' ? message.sender_username : 'them');
+      const when = formatLocalDateTime(typeof message.sent_at === 'string' ? message.sent_at : null);
+      const text = truncateText(typeof message.content === 'string' ? message.content : '', 240);
+      lines.push(`- [${when}] ${who}: ${text}`);
+    }
+
+    return lines.join('\n');
+  },
+};