posterly-mcp-server 0.35.1 → 0.37.0

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.35.1` exposes 78 tools.
+`posterly-mcp-server@0.37.0` exposes 86 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -190,6 +190,14 @@ 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)
+- `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 +275,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,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';
@@ -718,6 +726,78 @@ 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(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';
@@ -1221,6 +1260,7 @@ export declare class PosterlyClient {
         token: string;
         path: string;
         public_url: string;
+        headers?: Record<string, string>;
     }>;
     uploadMedia(input: {
         filePath?: string;
@@ -1242,6 +1282,40 @@ 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>;
+    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

@@ -522,12 +522,13 @@ export class PosterlyClient {
             guessContentType(input.filename);
         const SIZE_THRESHOLD = 3 * 1024 * 1024; // 3MB
         if (fileBuffer.length > SIZE_THRESHOLD) {
-            // Large file: use signed URL so the API can validate actual bytes before storage.
+            // Large file: PUT to the object-storage signed URL (not a Vercel relay).
             const signed = await this.getSignedUploadUrl(input.filename, contentType, fileBuffer.length);
             const uploadRes = await fetch(signed.upload_url, {
                 method: 'PUT',
                 headers: {
                     'Content-Type': contentType,
+                    ...(signed.headers || {}),
                 },
                 body: new Uint8Array(fileBuffer),
             });
@@ -552,6 +553,79 @@ 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 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.35.1";
+export declare const POSTERLY_MCP_VERSION = "0.37.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.35.1';
+export const POSTERLY_MCP_VERSION = '0.37.0';