posterly-mcp-server 0.44.0 → 0.45.0

package/README.md

@@ -33,7 +33,7 @@ name is `io.github.awpthorp/posterly`, matching this package's `mcpName`.
 ## Requirements
 
 - Node.js `20+`
-- No API key is required for the public setup tools: `get_mcp_status`, `get_agent_signup_info`, `start_signup`, and `get_signup_session`
+- No API key is required for the public setup tools: `whoami` with `view: "status"`, `get_agent_signup_info`, `start_signup`, and `get_signup_session`
 - A posterly account, API add-on, and API key are required for authenticated tools like `whoami`, `list_accounts`, `create_connect_session`, and `create_post`
 
 ## Install
@@ -76,9 +76,9 @@ After paid signup is complete and posterly shows an API key, add `POSTERLY_API_K
 3. Pay in Stripe Checkout and set your posterly password in the browser.
 4. When posterly shows your API key, add it as `POSTERLY_API_KEY`.
 5. Restart your AI client.
-6. Ask the AI to call `get_mcp_status`, then `whoami`, then continue by connecting your first social account.
+6. Ask the AI to call `whoami` with `view: "status"`, then `whoami`, then continue by connecting your first social account.
 
-The signup and connect tools return user-facing next steps by default, so agents should report progress in plain language instead of showing raw curl, HTTP payloads, or JSON. Pass `debug: true` to `start_signup`, `get_signup_session`, `get_connect_link`, `create_connect_session`, or `get_connect_session` only when troubleshooting.
+The signup and connect tools return user-facing next steps by default, so agents should report progress in plain language instead of showing raw curl, HTTP payloads, or JSON. Pass `debug: true` to `start_signup`, `get_signup_session`, `create_connect_session`, `list_platforms` (`view: "connect_link"`), or `list_accounts` (`view: "connect_session"`) only when troubleshooting.
 
 Post tools return `View in posterly` dashboard links. After scheduling, listing, reading, or deleting posts, share the returned link with the user. Current-month scheduled posts open in Calendar with the post selected; broader/future post views use Table.
 
@@ -122,116 +122,314 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.44.0` exposes 92 tools.
-
-Public setup tools work before `POSTERLY_API_KEY` exists:
-
-- `get_mcp_status` (show the installed server version, latest npm version, MCP endpoint health, API auth health, and update guidance)
-- `get_agent_signup_info`
-- `start_signup` (start paid signup and return a poll URL, browser Checkout fallback, and prepaid PaymentIntent fields when agent-card pay is enabled)
-- `get_signup_session` (poll checkout, payment, password, and agent-access status)
-
-Authenticated tools require `POSTERLY_API_KEY`:
-
-- `whoami`
-- `list_accounts`
-- `disconnect_account` (disconnect a connected social account after explicit confirmation)
-- `get_connect_link`
-- `connect_account` (connect a credential-based account: telegram, bluesky, discord, wordpress, devto, hashnode, lemmy; no browser session needed)
-- `create_connect_session` (create a guided browser handoff for connecting a social account)
-- `get_connect_session` (poll connection progress while the user approves OAuth or enters credentials)
-- `create_api_key` (create a new API key after explicit confirmation; scopes cannot exceed the calling dashboard key)
-- `delete_api_key` (revoke a user-created API key after explicit confirmation)
-- `list_workspace_members` (list teammates, roles, brand access, and pending invites; requires `members:read`, granted by the "Manage team" permission)
-- `manage_workspace_member` (invite, update, or remove a colleague with `action`; always returns a preview first and only acts on `confirm: true` plus the `preview_id` after the user approves; requires `members:write`)
-- `get_subscription` (read subscription status, tier, and cancel/pause state; requires `billing:read`)
-- `cancel_subscription` (cancel after explicit confirmation; the agent must ask for a `reason` first; requires `billing:write`)
-- `pause_subscription` (pause 30 days, one per 90-day cooldown, after confirmation; requires `billing:write`)
-- `resume_subscription` (resume a paused subscription; requires `billing:write`)
-- `downgrade_subscription` (downgrade one tier at next renewal after confirmation; requires `billing:write`)
-- `list_oauth_clients`
-- `create_oauth_client` (create a public PKCE client after explicit confirmation)
-- `update_oauth_client` (update redirect URIs/scopes after explicit confirmation)
-- `delete_oauth_client` (delete a developer client after explicit confirmation)
-- `list_platforms`
-- `get_platform_schema`
-- `trigger_platform_helper`
-- `list_brands`
-- `get_brand`
-- `list_brand_accounts`
-- `get_brand_profile`
-- `get_learned_voice` (read the voice learned from one account's real published captions)
-- `list_posts`
-- `get_post`
-- `get_post_missing`
-- `ask_support` (authenticated docs-backed support with read-only account/post diagnostics; human tickets require explicit confirmation)
-- `create_post` (supports `thread_posts: string[]` for X / Threads reply chains, plus `platform_settings` for platform-specific composer controls)
-- `validate_post` (checks and normalizes a post without creating it; call before requesting confirmation for `create_post`)
-- `submit_agent_feedback` (writes bounded private operational telemetry after a real workflow outcome; never include secrets, prompts, captions, media URLs, or personal data)
-- `submit_product_feedback` (files a product bug/idea/feedback on the public dashboard board after explicit user confirmation; not for tool failures)
-- `create_posts_batch` (create up to 25 confirmed posts in one API request)
-- `update_post` (also accepts `platform_settings`)
-- `update_post_status` (pause, resume, schedule, or draft a post after confirmation)
-- `update_post_release_id` (set/repair external release/group metadata after confirmation)
-- `delete_post`
-- `delete_post_group` (delete grouped draft/scheduled posts after confirmation)
-- `upload_media`
-- `upload_media_from_url`
-- `create_signed_upload`
-- `create_media_drop` (human drop page at https://www.poster.ly/drop/<token> for ChatGPT/Claude laptop files)
-- `list_media`
-- `find_available_slot`
-- `generate_captions`
-- `generate_image` (queues a Railway job; Gemini thinking_level / quality high, resolution up to 4K, optional reference_image_urls)
-- `get_image_job` (poll one job or list recent image jobs)
-- `get_video_options`
-- `run_video_function` (read-only Veo helpers for cost estimation and request validation)
-- `generate_video` (queues a cost-guarded Veo video job)
-- `get_credits` (read-only AI credit balance)
-- `get_video_job` (poll one job or list recent jobs)
-- `get_account_analytics`
-- `get_post_analytics`
-- `get_performance_profile` (read an account's 90-day performance profile: top formats, timing, caption-length patterns, engagement-rate trend, narrative summary)
-- `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, Threads, and LinkedIn Page 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`
-- `suggest_google_business_review_reply`
-- `reply_google_business_review` (post/update a public GBP review reply after explicit confirmation)
-- `delete_google_business_review_reply` (delete a GBP review reply after explicit confirmation)
-- `list_google_business_media` (list the photos/videos on a GBP profile gallery)
-- `add_google_business_media` (add a photo/video to a GBP profile gallery from a public URL, after explicit confirmation)
-- `delete_google_business_media` (remove a photo/video from a GBP profile gallery after explicit confirmation)
-
-> Google Business tip: pass `account_id` (the integer `id` from `list_accounts`) to every GBP tool. If you use `location_id` instead, it is the numeric `location_id` from `list_accounts` (the GBP location id), not the `ChIJ...` Place ID that `get_google_business_review_link` returns. Passing the Place ID resolves to no account and returns "Google Business Profile account not found".
-
-- `list_activity`
-- `get_updates` (read the latest posterly product updates and news)
-- `list_webhooks`
-- `create_webhook` (create a webhook after explicit confirmation)
-- `update_webhook` (update a webhook after explicit confirmation)
-- `delete_webhook` (delete a webhook after explicit confirmation)
-- `test_webhook` (send a signed test delivery after explicit confirmation)
-- `get_x_posting_quota`
-
-Analytics tools currently support Instagram, Facebook Pages, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads.
+`posterly-mcp-server@0.45.0` exposes 62 tools covering 94 actions. The hosted HTTP endpoint exposes the same catalog minus the three signup tools: 59 tools covering 91 actions.
+
+Many tools pick what to do with one parameter: `view` (reads), `action` (writes), or `type`. A few pick their mode from which parameters you pass (for example `update_post` with `status` changes the status instead of editing). Every tool description names all of its views and actions.
+
+Public setup tools work before `POSTERLY_API_KEY` exists: `whoami` with `view: "status"` (installed version, latest npm version, endpoint and API key health, update guidance), `get_agent_signup_info`, `start_signup`, and `get_signup_session`. Every other tool needs `POSTERLY_API_KEY`.
+
+### Preview then confirm
+
+Actions that post publicly or delete things work in two steps: call once without `confirm` to get a preview and a `preview_id`, show the preview to the user, then call again with the same fields plus `confirm: true` and that `preview_id`. A preview expires after 10 minutes, only works for exactly the same fields, and a public post (a comment reply, a DM, a Google review reply, new Google profile media) can be confirmed once. Other writes keep the single `confirm: true` after explicit user confirmation.
+
+### Tool sets
+
+Tools are grouped into sets: `core`, `creative`, `inbox`, `google_business`, `admin`, and `billing`, plus `signup` (always on). Every set is listed by default. To list fewer, set `POSTERLY_TOOLSETS=core,inbox` (or pass `--toolsets=core,inbox`). Sets only change what is listed; any tool can still be called by name.
+
+### Core (`core`)
+
+Accounts, posting, media, schedule, analytics, and support. What most assistants need.
+
+| Tool | What it does |
+| --- | --- |
+| `disconnect_account` | Disconnect an account |
+| `connect_account` | Connect with credentials |
+| `create_connect_session` | Start a connect session |
+| `trigger_platform_helper` | Run a platform helper |
+| `list_posts` | Posts |
+| `ask_support` | Ask support |
+| `find_available_slot` | Find a free slot |
+| `submit_agent_feedback` | Agent feedback |
+| `submit_product_feedback` | Product feedback |
+| `validate_post` | Validate a post |
+| `create_post` | Create a post |
+| `create_posts_batch` | Create posts in bulk |
+| `get_x_posting_quota` | X posting quota |
+| `create_signed_upload` | Signed upload link |
+| `create_media_drop` | Media drop link |
+| `list_media` | Media library |
+| `generate_captions` | Generate captions |
+| `list_activity` | Activity feed |
+| `get_credits` | AI credits |
+| `get_updates` | Product updates |
+
+**`whoami`**: Who am I
+
+| View | What it does |
+| --- | --- |
+| `identity` (default) | You, your scopes, and your workspaces |
+| `status` | MCP server and connection status |
+
+**`list_accounts`**: Connected accounts
+
+| View | What it does |
+| --- | --- |
+| `accounts` (default) | Connected accounts |
+| `learned_voice` | Learned voice of an account |
+| `performance_profile` | Performance profile of an account |
+| `connect_session` | Check a connect session |
+
+**`list_platforms`**: Platforms
+
+| View | What it does |
+| --- | --- |
+| `platforms` (default) | Supported platforms |
+| `schema` | Platform or account schema |
+| `connect_link` | Connection links |
+
+**`list_brands`**: Brands
+
+| View | What it does |
+| --- | --- |
+| `brands` (default) | All brands |
+| `brand` | One brand |
+| `accounts` | Brand accounts |
+| `profile` | Brand profile |
+
+**`get_post`**: One post
+
+| View | What it does |
+| --- | --- |
+| `post` (default) | One post |
+| `missing` | What a post is missing |
+
+**`update_post`**: Edit a post
+
+| Mode (picked by params) | What it does |
+| --- | --- |
+| `edit` (default) | Edit caption, media, schedule, or settings |
+| `status` (pass `status`) | Pause, resume, schedule, or move to draft |
+| `release_id` (pass `release_id`) | Set a release or group ID |
+
+**`delete_post`**: Delete posts
+
+| Mode (picked by params) | What it does |
+| --- | --- |
+| `post` (default) | Delete one post |
+| `group` (pass `group_id`) | Delete a post group (preview then confirm) |
+
+**`upload_media`**: Upload media
+
+| Mode (picked by params) | What it does |
+| --- | --- |
+| `file` (default) | Upload a file |
+| `url` (pass `url`) | Upload from a URL |
+
+**`list_analytics`**: Analytics
+
+| View | What it does |
+| --- | --- |
+| `accounts` | Account analytics |
+| `posts` | Post analytics |
+| `insights` | Post insights |
+
+### Creative (`creative`)
+
+AI image and video generation, jobs, and post suggestions.
+
+| Tool | What it does |
+| --- | --- |
+| `list_post_suggestions` | Post suggestions |
+| `dismiss_suggestion` | Dismiss a suggestion |
+| `get_video_options` | Video options |
+| `run_video_function` | Video helper |
+| `generate_video` | Generate a video |
+| `generate_image` | Generate an image |
+
+**`list_jobs`**: AI jobs
+
+| Type | What it does |
+| --- | --- |
+| `image` | Image jobs |
+| `video` | Video jobs |
+
+### Inbox (`inbox`)
+
+Social inbox comments and DMs.
+
+**`list_conversations`**: Conversations
+
+| Mode (picked by params) | What it does |
+| --- | --- |
+| `list` (default) | List conversations |
+| `conversation` (pass `conversation_id`) | One conversation with its messages |
+
+**`manage_conversation`**: Manage conversations
+
+| Action | What it does |
+| --- | --- |
+| `send` | Send a DM (preview then confirm) |
+| `sync` | Sync the inbox |
+
+**`list_comments`**: Comments
+
+| Mode (picked by params) | What it does |
+| --- | --- |
+| `list` (default) | List comments |
+| `comment` (pass `comment_id`) | One comment with its replies |
+
+**`manage_comment`**: Manage comments
+
+| Action | What it does |
+| --- | --- |
+| `reply` | Reply to a comment (preview then confirm) |
+| `update` | Hide or mark read |
+| `delete` | Delete a comment (preview then confirm) |
+
+### Google Business (`google_business`)
+
+Google Business Profile reviews, media, and audits.
+
+| Tool | What it does |
+| --- | --- |
+| `audit_google_business_profile` | Audit a Google profile |
+| `list_google_business_media` | Google profile media |
+
+**`list_google_business_reviews`**: Google reviews
+
+| View | What it does |
+| --- | --- |
+| `reviews` (default) | Google reviews |
+| `review_link` | Google review link |
+
+**`manage_google_business_review`**: Manage Google reviews
+
+| Action | What it does |
+| --- | --- |
+| `suggest_reply` | Suggest a reply (never posts) |
+| `reply` | Reply to a review (preview then confirm) |
+| `delete_reply` | Delete a review reply (preview then confirm) |
+
+**`manage_google_business_media`**: Manage Google profile media
+
+| Action | What it does |
+| --- | --- |
+| `add` | Add a photo or video (preview then confirm) |
+| `delete` | Delete a photo or video (preview then confirm) |
+
+### Admin (`admin`)
+
+API keys, OAuth clients, webhooks, and workspace members.
+
+| Tool | What it does |
+| --- | --- |
+| `create_api_key` | Create an API key |
+| `delete_api_key` | Revoke an API key |
+| `list_workspace_members` | Workspace members |
+| `list_oauth_clients` | OAuth clients |
+| `list_webhooks` | Webhooks |
+| `create_webhook` | Create a webhook |
+
+**`manage_workspace_member`**: Manage a workspace member
+
+| Action | What it does |
+| --- | --- |
+| `invite` | Invite a colleague (preview then confirm) |
+| `update` | Change role or brands (preview then confirm) |
+| `remove` | Remove a member or invite (preview then confirm) |
+
+**`manage_oauth_client`**: Manage an OAuth client
+
+| Action | What it does |
+| --- | --- |
+| `create` | Create an OAuth client |
+| `update` | Update an OAuth client |
+| `delete` | Delete an OAuth client (preview then confirm) |
+
+**`manage_webhook`**: Manage a webhook
+
+| Action | What it does |
+| --- | --- |
+| `update` | Update a webhook |
+| `delete` | Delete a webhook (preview then confirm) |
+| `test` | Send a test delivery |
+
+### Billing (`billing`)
+
+Subscription changes.
+
+| Tool | What it does |
+| --- | --- |
+| `get_subscription` | Subscription |
+| `cancel_subscription` | Cancel subscription |
+| `pause_subscription` | Pause subscription |
+| `resume_subscription` | Resume subscription |
+| `downgrade_subscription` | Downgrade subscription |
+
+### Signup (`signup`)
+
+Pre-auth signup for brand-new users. Local npm package only; always on.
+
+| Tool | What it does |
+| --- | --- |
+| `get_agent_signup_info` | Signup info for agents |
+| `start_signup` | Start a paid signup |
+| `get_signup_session` | Check a signup session |
+
+> Google Business tip: pass `account_id` (the integer `id` from `list_accounts`) to every Google Business tool. If you use `location_id` instead, it is the numeric `location_id` from `list_accounts` (the GBP location id), not the `ChIJ...` Place ID that `list_google_business_reviews` with `view: "review_link"` returns. Passing the Place ID resolves to no account and returns "Google Business Profile account not found".
+
+Analytics (`list_analytics`) currently supports Instagram, Facebook Pages, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads.
+
+## Renamed tools
+
+In 0.45.0, the old tools below moved into the tools above. The old names still work (they are not listed, and each result ends with a short note naming the new call) and may stop working after 2027-01-12. Update scripts, prompts, and "always allow" permission lists to the new names. Full guide: [MCP tool changes](https://www.poster.ly/docs/integrations/mcp-tool-changes).
+
+| Old name | New tool | Pass |
+| --- | --- | --- |
+| `get_mcp_status` | `whoami` | `view=status` |
+| `get_connect_session` | `list_accounts` | `view=connect_session` |
+| `get_learned_voice` | `list_accounts` | `view=learned_voice` |
+| `get_performance_profile` | `list_accounts` | `view=performance_profile` |
+| `get_platform_schema` | `list_platforms` | `view=schema` |
+| `get_connect_link` | `list_platforms` | `view=connect_link` (the old `platform` param is now `target`) |
+| `get_brand` | `list_brands` | `view=brand` |
+| `list_brand_accounts` | `list_brands` | `view=accounts` |
+| `get_brand_profile` | `list_brands` | `view=profile` |
+| `get_post_missing` | `get_post` | `view=missing` |
+| `update_post_status` | `update_post` | pass `status` |
+| `update_post_release_id` | `update_post` | pass `release_id` |
+| `delete_post_group` | `delete_post` | pass `group_id` (preview then confirm) |
+| `upload_media_from_url` | `upload_media` | pass `url` |
+| `get_account_analytics` | `list_analytics` | `view=accounts` |
+| `get_post_analytics` | `list_analytics` | `view=posts` |
+| `get_post_insights` | `list_analytics` | `view=insights` |
+| `get_image_job` | `list_jobs` | `type=image` |
+| `get_video_job` | `list_jobs` | `type=video` |
+| `get_comment` | `list_comments` | pass `comment_id` |
+| `reply_to_comment` | `manage_comment` | `action=reply` (preview then confirm) |
+| `update_comment` | `manage_comment` | `action=update` |
+| `delete_comment` | `manage_comment` | `action=delete` (preview then confirm) |
+| `get_conversation` | `list_conversations` | pass `conversation_id` |
+| `send_message` | `manage_conversation` | `action=send` (preview then confirm) |
+| `sync_inbox` | `manage_conversation` | `action=sync` |
+| `get_google_business_review_link` | `list_google_business_reviews` | `view=review_link` |
+| `suggest_google_business_review_reply` | `manage_google_business_review` | `action=suggest_reply` |
+| `reply_google_business_review` | `manage_google_business_review` | `action=reply` (preview then confirm) |
+| `delete_google_business_review_reply` | `manage_google_business_review` | `action=delete_reply` (preview then confirm) |
+| `add_google_business_media` | `manage_google_business_media` | `action=add` (preview then confirm) |
+| `delete_google_business_media` | `manage_google_business_media` | `action=delete` (preview then confirm) |
+| `update_webhook` | `manage_webhook` | `action=update` |
+| `delete_webhook` | `manage_webhook` | `action=delete` (preview then confirm) |
+| `test_webhook` | `manage_webhook` | `action=test` |
+| `create_oauth_client` | `manage_oauth_client` | `action=create` |
+| `update_oauth_client` | `manage_oauth_client` | `action=update` |
+| `delete_oauth_client` | `manage_oauth_client` | `action=delete` (preview then confirm) |
 
 ## Media uploads
 
 This npm/stdio server can read local file paths. When `upload_media` receives a larger local file, it automatically requests a signed upload URL and uploads the raw bytes before returning the public media URL.
 
-The hosted HTTP MCP endpoint cannot do that for local files by itself because MCP tool calls are JSON-only. On hosted HTTP MCP, `upload_media` is for small base64 uploads up to 5MB decoded. For larger media there, use `upload_media_from_url` for public direct media URLs, or call `create_signed_upload` only from clients that can also `PUT` the raw file bytes to the returned `upload_url`.
+The hosted HTTP MCP endpoint cannot do that for local files by itself because MCP tool calls are JSON-only. On hosted HTTP MCP, `upload_media` is for small base64 uploads up to 5MB decoded. For larger media there, use `upload_media` with `url` for public direct media URLs, or call `create_signed_upload` only from clients that can also `PUT` the raw file bytes to the returned `upload_url`.
 
 ## What the brand tools are for
 
@@ -240,9 +438,9 @@ Posterly workspaces often have multiple connected accounts under one client or b
 The brand tools let an assistant work at the same level a human does:
 
 - `list_brands` lets the agent see clients/brands in the workspace
-- `get_brand` returns summary info for one brand
-- `list_brand_accounts` resolves a brand into the actual connected accounts
-- `get_brand_profile` returns saved brand guidance like tone, audience, keywords, dos and don'ts, and visual notes
+- `list_brands` with `view: "brand"` returns summary info for one brand
+- `list_brands` with `view: "accounts"` resolves a brand into the actual connected accounts
+- `list_brands` with `view: "profile"` returns saved brand guidance like tone, audience, keywords, dos and don'ts, and visual notes
 
 This makes prompts like:
 
@@ -316,3 +514,4 @@ The package reads:
 
 - optional `POSTERLY_API_KEY` for authenticated posterly tools
 - optional `POSTERLY_URL` if you need to point at a non-production environment
+- optional `POSTERLY_TOOLSETS` (for example `core,inbox`) to list fewer tool sets