posterly-mcp-server 0.36.0 → 0.38.0

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.36.0` exposes 78 tools.
+`posterly-mcp-server@0.38.0` exposes 87 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -190,6 +190,15 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `get_post_insights` (list per-post feedback-loop insights: performance tier, diagnosis, next action, metrics, baseline)
 - `list_post_suggestions` (list evidence-based weekly post drafts in the account's learned voice, each with a rationale)
 - `dismiss_suggestion` (dismiss a post suggestion after confirmation; never touches one already scheduled)
+- `list_conversations` (Instagram and Facebook Page inbox DMs; Threads has no DMs)
+- `get_conversation`
+- `send_message` (DM reply after explicit confirmation; honors Meta 24-hour windows)
+- `list_comments` (Instagram, Facebook Page, and Threads inbox comments)
+- `get_comment`
+- `reply_to_comment` (comment reply after explicit confirmation)
+- `update_comment` (hide/unhide or mark read; hide is reversible)
+- `delete_comment` (delete an Instagram or Facebook comment after confirmation; Threads replies cannot be deleted)
+- `sync_inbox` (pull latest inbox data for one account; 30-second cooldown)
 - `list_google_business_reviews`
 - `get_google_business_review_link`
 - `audit_google_business_profile`
@@ -267,6 +276,18 @@ Each API call counts as one request, so use `create_posts_batch` when you need t
 
 Details: [poster.ly/dashboard/api](https://www.poster.ly/dashboard/api)
 
+## Hosted MCP clients (Claude.ai, ChatGPT)
+
+Browser-hosted MCP hosts use the HTTP endpoint at [poster.ly/mcp](https://www.poster.ly/mcp) with OAuth instead of an API key. The HTTP endpoint supports RFC 7591 Dynamic Client Registration, so a host can self-register and complete a full connect flow without manual allowlisting:
+
+- `POST /api/oauth/register`, send `{ client_name, redirect_uris, scope }`, receive a `client_id`.
+- Standard authorization-code + PKCE at `/oauth/authorize`.
+- 1-hour access tokens with 30-day rotating refresh tokens via `/api/oauth/token`.
+
+Discovery document: [/.well-known/oauth-authorization-server](https://www.poster.ly/.well-known/oauth-authorization-server).
+
+Local stdio still uses an API key in `POSTERLY_API_KEY`.
+
 ## Links
 
 - Docs: [poster.ly/mcp](https://www.poster.ly/mcp)

package/SUBMISSIONS.md

@@ -0,0 +1,73 @@
+# MCP connector submissions
+
+Notes for listing the hosted MCP server as a one-click connector. The pipework
+(hosted HTTP MCP + stdio MCP) already works with API keys. Dynamic Client
+Registration and refresh-token rotation are what Claude.ai / ChatGPT-style hosts
+need for a connect flow without a human-allowlisted `client_id`.
+
+Do not publish these notes as user-facing marketing copy. They are for the
+person who applies the production migration and files the directory forms.
+
+## Preconditions
+
+1. Apply the DCR / refresh-token migration
+   (`supabase/migrations/20260906140000_oauth_dynamic_registration_and_refresh.sql`)
+   **before or with** the production deploy, not after. Shipping the app first
+   leaves `oauth_refresh_tokens` missing: the token endpoint then falls back to
+   a 365-day access-only grant for dynamic clients, and DCR verification that
+   expects refresh tokens will fail. Do not apply the SQL from an agent session
+   that can write straight to prod.
+2. Confirm `NEXT_PUBLIC_SITE_URL` is `https://www.poster.ly` in the production
+   deploy so discovery documents advertise the right issuer.
+3. Create a reviewer test account with the API add-on enabled, plus a short
+   setup note they can follow.
+4. Confirm discovery before submitting:
+   - `GET /.well-known/oauth-authorization-server` includes
+     `registration_endpoint` and `refresh_token` in `grant_types_supported`
+   - `POST /api/oauth/register` returns `201` with a `dyn_` `client_id`
+   - consent shows the self-registered warning, callback host, and `client_id`
+     for that client
+   - refresh-token reuse within 30 seconds returns `invalid_grant` without
+     revoking the chain; reuse older than 30 seconds revokes the chain
+   - `/api/mcp` returns `403` `origin_not_allowed` for an untrusted Origin
+   - `tools/list` includes annotations on every tool
+
+## Anthropic Connectors Directory
+
+Submit the remote MCP server at https://clau.de/mcp-directory-submission.
+
+Fallback contact: mcp-review@anthropic.com.
+
+Use:
+
+- Server URL: `https://www.poster.ly/api/mcp`
+- Server card: `https://www.poster.ly/.well-known/mcp/server-card.json`
+- Docs: `https://www.poster.ly/mcp` and `https://www.poster.ly/agents`
+  (public pages only; do not submit auth-gated `https://www.poster.ly/docs/...`
+  URLs)
+- Auth: OAuth 2.1 + PKCE, RFC 7591 Dynamic Client Registration, rotating
+  refresh tokens (1-hour access, 30-day refresh for DCR clients)
+- Platforms: all 18 production platforms
+
+Do not claim Autopilot ships. Do not claim the connector is already listed.
+
+Optional after deploy: bump and publish `posterly-mcp-server` if you want the
+stdio README changes on npm. Hosted `/api/mcp` picks up this repo deploy
+without an npm publish.
+
+## Other hosted hosts
+
+ChatGPT-style hosts follow the same DCR + authorize + token flow. HTTPS
+callbacks such as `https://chatgpt.com/oauth/callback` are already accepted by
+the redirect URI validator. Extra browser origins can be added with
+`MCP_TRUSTED_ORIGINS` (comma-separated hostnames or full URLs).
+
+The ChatGPT plugin / app directory is a separate OpenAI form. File it after
+this OAuth DCR deploy is live; it is not covered by the Anthropic connector
+submission.
+
+## Registry metadata
+
+`server.json` is the official MCP Registry metadata for the stdio package
+(`io.github.awpthorp/posterly`). Publishing that package is a separate release
+step. See `RELEASING.md`.

package/dist/index.js

@@ -53,6 +53,15 @@ 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 { deleteCommentTool } from './tools/delete-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';
@@ -718,6 +727,87 @@ server.tool(deleteGoogleBusinessMediaTool.name, deleteGoogleBusinessMediaTool.de
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(listConversationsTool.name, listConversationsTool.description, listConversationsTool.inputSchema.shape, getToolAnnotations(listConversationsTool.name), async (input) => {
+    try {
+        const text = await listConversationsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', 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);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', 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);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', 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);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', 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);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', 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);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', 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);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(deleteCommentTool.name, deleteCommentTool.description, deleteCommentTool.inputSchema.shape, getToolAnnotations(deleteCommentTool.name), async (input) => {
+    try {
+        const text = await deleteCommentTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', 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);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(listActivityTool.name, listActivityTool.description, listActivityTool.inputSchema.shape, getToolAnnotations(listActivityTool.name), async (input) => {
     try {
         const text = await listActivityTool.execute(client, input);

package/dist/lib/api-client.d.ts

@@ -624,6 +624,45 @@ export interface GoogleBusinessReviewLinkResponse {
     locationId: string | null;
     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';
@@ -1243,6 +1282,43 @@ export declare class PosterlyClient {
         content_type: string;
         size: number;
     }>;
+    private appendInboxListParams;
+    listConversations(params?: InboxListParams): Promise<InboxConversationsResponse>;
+    getConversation(params: {
+        conversation_id: string;
+        workspace_id?: string;
+        limit?: number;
+    }): Promise<InboxConversationResponse>;
+    sendMessage(data: {
+        conversation_id: string;
+        content: string;
+        workspace_id?: string;
+    }): Promise<InboxSendMessageResponse>;
+    listComments(params?: InboxListParams): Promise<InboxCommentsResponse>;
+    getComment(params: {
+        comment_id: string;
+        workspace_id?: string;
+    }): Promise<InboxCommentResponse>;
+    replyToComment(data: {
+        comment_id: string;
+        content: string;
+        type?: 'public' | 'private';
+        workspace_id?: string;
+    }): Promise<InboxCommentReplyResponse>;
+    updateComment(data: {
+        comment_id: string;
+        is_hidden?: boolean;
+        is_read?: boolean;
+        workspace_id?: string;
+    }): Promise<InboxCommentResponse>;
+    deleteComment(id: string, workspaceId?: string): Promise<{
+        success: true;
+    }>;
+    syncInbox(data: {
+        account_id: number;
+        sync_type?: 'all' | 'dm' | 'comments';
+        workspace_id?: string;
+    }): Promise<InboxSyncResponse>;
 }
 export declare function resolvePosterlyBaseUrl(baseUrl?: string): string;
 type PosterlyBaseUrlInspection = {

package/dist/lib/api-client.js

@@ -553,6 +553,86 @@ export class PosterlyClient {
             content_type: input.contentType,
         });
     }
+    appendInboxListParams(searchParams, params) {
+        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) {
+        const searchParams = new URLSearchParams();
+        this.appendInboxListParams(searchParams, params);
+        const qs = searchParams.toString();
+        return this.request('GET', `/inbox/conversations${qs ? `?${qs}` : ''}`);
+    }
+    async getConversation(params) {
+        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) {
+        const body = { 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) {
+        const searchParams = new URLSearchParams();
+        this.appendInboxListParams(searchParams, params);
+        const qs = searchParams.toString();
+        return this.request('GET', `/inbox/comments${qs ? `?${qs}` : ''}`);
+    }
+    async getComment(params) {
+        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) {
+        const body = { 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) {
+        const body = {};
+        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 deleteComment(id, workspaceId) {
+        const searchParams = new URLSearchParams();
+        if (workspaceId)
+            searchParams.set('workspace_id', workspaceId);
+        const qs = searchParams.toString();
+        return this.request('DELETE', `/inbox/comments/${encodeURIComponent(id)}${qs ? `?${qs}` : ''}`);
+    }
+    async syncInbox(data) {
+        return this.request('POST', '/inbox/sync', data);
+    }
 }
 export function resolvePosterlyBaseUrl(baseUrl) {
     const configured = (baseUrl ||

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.36.0";
+export declare const POSTERLY_MCP_VERSION = "0.38.0";

package/dist/lib/version.js

@@ -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.38.0';

package/dist/tools/delete-comment.d.ts

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

package/dist/tools/delete-comment.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export const deleteCommentTool = {
+    name: 'delete_comment',
+    description: 'Delete an Instagram or Facebook Page inbox comment. DESTRUCTIVE and IRREVERSIBLE. Threads replies cannot be deleted; hide them with update_comment instead. Requires a Pro plan or higher, posts:write, and admin workspace access. Fetch with get_comment first and pass confirm=true only after explicit user confirmation.',
+    inputSchema: z.object({
+        comment_id: z.string().min(1).describe('Comment ID from list_comments or get_comment.'),
+        workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+        confirm: z.literal(true).describe('Must be true after explicit user confirmation of the comment deletion.'),
+    }),
+    async execute(client, input) {
+        if (input.confirm !== true) {
+            throw new Error('Refusing to delete comment without confirm=true after explicit user confirmation.');
+        }
+        await client.deleteComment(input.comment_id, input.workspace_id);
+        return [
+            `Comment ${input.comment_id} deleted successfully.`,
+            'It has been deleted from the posterly inbox. On Instagram or Facebook it is also removed on the network when the platform call succeeds.',
+            '',
+            'Next step for the AI agent: tell the user the comment is gone. Threads replies cannot be deleted; hide them with update_comment instead.',
+        ].join('\n');
+    },
+};

package/dist/tools/get-comment.d.ts

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

package/dist/tools/get-comment.js

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

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

package/dist/tools/get-conversation.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+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, input) {
+        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');
+    },
+};

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const listCommentsTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        workspace_id: z.ZodOptional<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodNumber>;
+        platform: z.ZodOptional<z.ZodEnum<["instagram", "facebook", "threads"]>>;
+        filter: z.ZodOptional<z.ZodEnum<["all", "unread", "flagged"]>>;
+        search: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        platform?: "instagram" | "facebook" | "threads" | undefined;
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        filter?: "all" | "unread" | "flagged" | undefined;
+        search?: string | undefined;
+    }, {
+        platform?: "instagram" | "facebook" | "threads" | undefined;
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        filter?: "all" | "unread" | "flagged" | undefined;
+        search?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        workspace_id?: string;
+        account_id?: number;
+        platform?: "instagram" | "facebook" | "threads";
+        filter?: "all" | "unread" | "flagged";
+        search?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<string>;
+};

package/dist/tools/list-comments.js

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