posterly-mcp-server 0.19.8 → 0.19.10

package/README.md

@@ -4,6 +4,8 @@ Use Posterly from any MCP-compatible AI client.
 
 This package gives Claude Desktop, Cursor, Windsurf, Cline, and other local MCP clients a `stdio` server that can:
 
+- start paid Posterly signup before an API key exists
+- poll signup progress while the user completes checkout and password setup
 - list connected social accounts
 - resolve brands/clients into the right accounts
 - schedule and manage posts
@@ -12,35 +14,39 @@ This package gives Claude Desktop, Cursor, Windsurf, Cline, and other local MCP
 - generate images
 - read account and post analytics
 
-Tool results are returned as Markdown-first chat summaries with headings, compact tables, short next-step notes, and occasional status icons. MCP clients may still rephrase the final answer, but the raw tool content is designed to look good directly in chat.
-
-Posterly also exposes the same toolset over HTTP at [poster.ly/mcp](https://www.poster.ly/mcp), but this npm package is the local `stdio` transport.
+Posterly also exposes the same authenticated toolset over HTTP at [poster.ly/mcp](https://www.poster.ly/mcp), but this npm package is the local `stdio` transport.
 
 ## Requirements
 
 - Node.js `20+`
-- A Posterly account: [poster.ly/signup](https://www.poster.ly/signup)
-- The Posterly API add-on enabled: [poster.ly/dashboard/api](https://www.poster.ly/dashboard/api)
-- A Posterly API key
-
-No API key is required for the public signup tools: `get_agent_signup_info`, `start_signup`, and `get_signup_session`.
+- No API key is required for the public setup tools: `get_mcp_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
 
-You can install globally:
+Recommended: use it via `npx` in your MCP config so your client runs the current server without a global install.
 
-```bash
-npm install -g posterly-mcp-server
+To let an AI agent start signup before a Posterly API key exists, install the server without `POSTERLY_API_KEY`:
+
+```json
+{
+  "mcpServers": {
+    "posterly": {
+      "command": "npx",
+      "args": ["-y", "posterly-mcp-server@latest"]
+    }
+  }
+}
 ```
 
-Or just use it via `npx` in your MCP config:
+After paid signup is complete and Posterly shows an API key, add `POSTERLY_API_KEY` to unlock the authenticated tools:
 
 ```json
 {
   "mcpServers": {
     "posterly": {
       "command": "npx",
-      "args": ["-y", "posterly-mcp-server"],
+      "args": ["-y", "posterly-mcp-server@latest"],
       "env": {
         "POSTERLY_API_KEY": "pst_live_your_key_here"
       }
@@ -51,12 +57,16 @@ Or just use it via `npx` in your MCP config:
 
 ## Quick setup
 
-1. Sign up at [poster.ly](https://www.poster.ly/signup)
-2. Go to [Dashboard → API & MCP](https://www.poster.ly/dashboard/api)
-3. Enable the API add-on
-4. Generate an API key
-5. Paste it into your MCP client config as `POSTERLY_API_KEY`
-6. Restart your AI client
+1. Add the Posterly MCP server to your AI client.
+2. If you do not have Posterly yet, ask the AI to call `start_signup`.
+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.
+
+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.
+
+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.
 
 ## Example configs
 
@@ -69,7 +79,7 @@ Add this to your Claude Desktop MCP config:
   "mcpServers": {
     "posterly": {
       "command": "npx",
-      "args": ["-y", "posterly-mcp-server"],
+      "args": ["-y", "posterly-mcp-server@latest"],
       "env": {
         "POSTERLY_API_KEY": "pst_live_your_key_here"
       }
@@ -87,7 +97,7 @@ Add the same server definition to your Cursor MCP settings:
   "mcpServers": {
     "posterly": {
       "command": "npx",
-      "args": ["-y", "posterly-mcp-server"],
+      "args": ["-y", "posterly-mcp-server@latest"],
       "env": {
         "POSTERLY_API_KEY": "pst_live_your_key_here"
       }
@@ -98,15 +108,16 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.19.8` exposes 55 tools: 3 public signup helpers plus the 52 authenticated API/MCP tools.
+`posterly-mcp-server@0.19.10` exposes 56 tools.
 
-Public signup helpers:
+Public setup tools work before `POSTERLY_API_KEY` exists:
 
+- `get_mcp_status` (show the installed server version, latest npm version, API origin, API key presence, and update guidance)
 - `get_agent_signup_info`
 - `start_signup` (start paid signup and return a Posterly checkout handoff URL)
 - `get_signup_session` (poll checkout, payment, password, and agent-access status)
 
-Authenticated tools:
+Authenticated tools require `POSTERLY_API_KEY`:
 
 - `whoami`
 - `list_accounts`
@@ -194,6 +205,7 @@ much more reliable than forcing the agent to guess from raw account handles alon
 - `Schedule this as an Instagram Story with a first comment and @partner as collaborator`
 - `Schedule this YouTube video as unlisted, add the thumbnail URL, and put it in our launch playlist`
 - `Post this TikTok with direct-post privacy set to public and stitch disabled`
+- `Schedule these 5 photos as a TikTok` (image posts auto-detect as a photo slideshow of 1 to 35 images, no post type needed)
 - `How did Grassroots perform on Instagram in the last 30 days?`
 
 ## Pricing
@@ -230,5 +242,5 @@ npm start
 
 The package reads:
 
-- `POSTERLY_API_KEY`
+- optional `POSTERLY_API_KEY` for authenticated Posterly tools
 - optional `POSTERLY_URL` if you need to point at a non-production environment