planpost-mcp 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to `planpost-mcp`. Versions follow [semver](https://semver.org).
+
+## 0.4.0 — 2026-11-09
+
+### Added
+- **OAuth sign-in for the hosted server.** With `--http`, the server is now an
+  OAuth 2.1 resource server per the MCP authorization spec (revision
+  2026-07-28): protected-resource metadata at
+  `/.well-known/oauth-protected-resource`, a `401` +
+  `WWW-Authenticate: Bearer resource_metadata="…"` challenge for
+  unauthenticated requests, access-token validation by introspection with an
+  audience check, and no token passthrough. Clients that support remote MCP
+  authorization (Claude, ChatGPT, Cursor, Gemini CLI, VS Code) can connect to
+  `https://mcp.planpo.st/mcp` with no key. Enabled by
+  `PLANPOST_MCP_PUBLIC_URL` + `PLANPOST_MCP_SERVICE_SECRET`; without them the
+  server behaves exactly as before.
+- **Tool annotations** on all 49 tools: `title`, `readOnlyHint`,
+  `destructiveHint`, `idempotentHint`, `openWorldHint`.
+- **Agent bundles** in the repository: `skills/planpost/SKILL.md`
+  (`npx skills add`), `gemini-extension.json` + `GEMINI.md` (Gemini CLI
+  extension), `.claude-plugin/` (Claude Code plugin and marketplace) and
+  `.cursor-plugin/` + `mcp.json` (Cursor plugin).
+- Tests for hosted OAuth mode and for manifest consistency; `npm test` now
+  builds first.
+
+### Changed
+- `server.json`: the hosted remote's `Authorization` header is optional
+  (omit it to sign in with OAuth).
+- API-key authentication (`Authorization: Bearer pk_…` over HTTP,
+  `PLANPOST_API_KEY` over stdio) is unchanged.
+
+## 0.3.0 — 2026-11-08
+
+- Listed on the official MCP Registry as `io.github.lukBB/planpost`
+  (`server.json`, `mcpName`).
+- Hosted-first README: install snippets for Claude Code, Claude Desktop,
+  Cursor, Codex CLI and Gemini CLI.
+- `retry_failed` and `get_delivery_report` tools; publish failures carry an
+  error class and a suggested fix.
+- `npm test`: registry schema validation and a stdio boot test.
+
+## 0.2.x
+
+- Streamable HTTP mode (`--http`) with per-request API keys, powering
+  `https://mcp.planpo.st/mcp`.
+- Account groups, approvals, smart scheduling, carousels, video rendering,
+  content sources, brand voice, revenue overview.

package/README.md

@@ -1,9 +1,42 @@
 # planpost-mcp
 
-MCP (Model Context Protocol) server for [PlanPost](https://planpo.st) — lets Claude and other AI agents schedule social media posts, create videos and carousels, manage content sources, and read analytics and revenue data by talking to your PlanPost account.
+MCP (Model Context Protocol) server for [PlanPost](https://planpo.st), the agentic social scheduler with revenue attribution. It lets Claude, ChatGPT, Cursor, Gemini CLI and other AI agents schedule social media posts, create videos and carousels, manage content sources, and read analytics and revenue data by talking to your PlanPost account.
 
 ## Quick start
 
+### The short way: sign in
+
+Add `https://mcp.planpo.st/mcp` to your agent as a remote MCP server (a
+"connector" in Claude and ChatGPT) and leave the authentication fields empty.
+The first time the agent uses it, a browser opens on planpo.st: log in, review
+what the agent may do, and choose whether its posts wait for your approval.
+No key to create or paste.
+
+```bash
+claude mcp add --transport http planpost https://mcp.planpo.st/mcp
+```
+
+```json
+{ "mcpServers": { "planpost": { "url": "https://mcp.planpo.st/mcp" } } }
+```
+
+Connected agents are listed under **Settings → API Keys → Connected apps**,
+where you can remove one at any time. They use the same permissions and the
+same monthly call allowance as API keys.
+
+The repository also ships ready-made bundles: a Claude Code plugin
+(`.claude-plugin/`), a Cursor plugin (`.cursor-plugin/`), a Gemini CLI
+extension (`gemini-extension.json`) and an agent skill:
+
+```bash
+npx skills add lukBB/planpost-mcp --skill planpost
+gemini extensions install https://github.com/lukBB/planpost-mcp
+claude plugin marketplace add lukBB/planpost-mcp && claude plugin install planpost@planpost-plugins
+```
+
+The rest of this section is the API-key route: use it for clients without
+OAuth support, for CI, or when you want a key limited to a few permissions.
+
 ### 1. Get an API key
 
 In the PlanPost dashboard go to **Settings → API Keys → Create Key** and select the permissions you need (see the table below). The key (`pk_live_…`) is shown **once** — copy it.
@@ -12,13 +45,36 @@ In the PlanPost dashboard go to **Settings → API Keys → Create Key** and sel
 
 ### 2. Add the server to your agent
 
-**Claude Code:**
+Two ways to connect. **Hosted** is the default: point your client at
+`https://mcp.planpo.st/mcp`, nothing to install, your key travels as a header.
+**Local** runs the same server on your machine with `npx`, so the key never
+leaves it. Both expose the same 49 tools.
+
+Replace `pk_live_xxx` with your key throughout.
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http planpost https://mcp.planpo.st/mcp \
+  --header "Authorization: Bearer pk_live_xxx"
+```
+
+Local fallback:
 
 ```bash
 claude mcp add planpost -e PLANPOST_API_KEY=pk_live_xxx -- npx -y planpost-mcp
 ```
 
-**Claude Desktop** (`claude_desktop_config.json`):
+Run `claude mcp list` afterwards to confirm it is connected.
+
+**Claude Desktop**
+
+Hosted: Settings → Connectors → Add custom connector. Name `PlanPost`, URL
+`https://mcp.planpo.st/mcp`, then add the header `Authorization: Bearer pk_live_xxx`.
+
+Local fallback, in `claude_desktop_config.json` (macOS:
+`~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), then
+restart the app:
 
 ```json
 {
@@ -32,11 +88,71 @@ claude mcp add planpost -e PLANPOST_API_KEY=pk_live_xxx -- npx -y planpost-mcp
 }
 ```
 
-**Any other MCP client:** run `npx -y planpost-mcp` over stdio with the `PLANPOST_API_KEY` environment variable set.
+**Cursor** (`~/.cursor/mcp.json`, or `.cursor/mcp.json` per project)
+
+```json
+{
+  "mcpServers": {
+    "planpost": {
+      "url": "https://mcp.planpo.st/mcp",
+      "headers": { "Authorization": "Bearer pk_live_xxx" }
+    }
+  }
+}
+```
+
+Local fallback: replace the entry with
+`{ "command": "npx", "args": ["-y", "planpost-mcp"], "env": { "PLANPOST_API_KEY": "pk_live_xxx" } }`.
+A project-level `.cursor/mcp.json` is committed with your repo, so prefer the
+hosted form and keep the key out of the file.
+
+**OpenAI Codex CLI** (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.planpost]
+url = "https://mcp.planpo.st/mcp"
+bearer_token_env_var = "PLANPOST_API_KEY"
+```
+
+Export `PLANPOST_API_KEY` in your shell; Codex reads the token from the
+environment, not the file. `codex mcp add` does the same thing interactively.
+
+Local fallback:
 
-### Remote (HTTP) mode
+```toml
+[mcp_servers.planpost]
+command = "npx"
+args = ["-y", "planpost-mcp"]
+
+[mcp_servers.planpost.env]
+PLANPOST_API_KEY = "pk_live_xxx"
+```
 
-The server can also run as a shared, multi-tenant HTTP endpoint — no local install for users, each request authenticated by its own key:
+**Gemini CLI** (`~/.gemini/settings.json`, or `.gemini/settings.json` per project)
+
+```json
+{
+  "mcpServers": {
+    "planpost": {
+      "httpUrl": "https://mcp.planpo.st/mcp",
+      "headers": { "Authorization": "Bearer pk_live_xxx" },
+      "timeout": 10000
+    }
+  }
+}
+```
+
+Gemini CLI uses `httpUrl` for streamable HTTP, not `url`; the wrong key is a
+silent no-op. Local fallback: the same `command`/`args`/`env` entry as Cursor.
+
+**Any other MCP client:** connect to `https://mcp.planpo.st/mcp` (streamable
+HTTP, `Authorization: Bearer pk_live_xxx` on every request), or run
+`npx -y planpost-mcp` over stdio with `PLANPOST_API_KEY` set. Per-client
+walkthroughs with screenshots: [planpo.st/docs/agents](https://planpo.st/docs/agents).
+
+### Self-hosting the HTTP endpoint
+
+`mcp.planpo.st` is this same package running with `--http`. To run your own:
 
 ```bash
 npx -y planpost-mcp --http --port 3020     # exposes POST /mcp (+ /health)
@@ -48,16 +164,27 @@ Behind a reverse proxy, bind to loopback so the port isn't reachable directly:
 HOST=127.0.0.1 npx -y planpost-mcp --http --port 3020
 ```
 
-Connect from any HTTP-capable MCP client, e.g.:
+The transport is stateless (streamable HTTP); credentials are read from every
+request and scoped to it, so one hosted instance serves many users safely. Put
+it behind HTTPS in production. `--host` / `HOST` default to `0.0.0.0`, so
+containers and LAN use work without extra flags.
 
-```bash
-claude mcp add --transport http planpost https://mcp.yourhost.com/mcp \
-  --header "Authorization: Bearer pk_live_xxx"
-```
+A self-hosted endpoint accepts API keys (`Authorization: Bearer pk_...`) out of
+the box. OAuth sign-in is switched on by three variables, and needs a PlanPost
+API that runs the authorization server (`/oauth/*`):
 
-The transport is stateless (streamable HTTP); the `Authorization: Bearer pk_...` header is required on every request and scoped per request, so one hosted instance serves many users safely. Put it behind HTTPS (reverse proxy) in production.
+| Variable | Description |
+|---|---|
+| `PLANPOST_MCP_PUBLIC_URL` | Public URL of this endpoint, e.g. `https://mcp.example.com/mcp`. Tokens are issued for exactly this URL. |
+| `PLANPOST_MCP_SERVICE_SECRET` | 32+ random characters shared with the API (`MCP_SERVICE_SECRET` there). |
+| `PLANPOST_OAUTH_ISSUER` | Authorization server origin. Defaults to `PLANPOST_API_URL`. |
+| `OPENAI_APPS_CHALLENGE` | Optional. Token served at `/.well-known/openai-apps-challenge` for ChatGPT directory domain verification. |
 
-`--host` / `HOST` default to `0.0.0.0`, so containers and LAN use work without extra flags.
+With those set the server follows the MCP authorization spec: it serves
+`/.well-known/oauth-protected-resource`, answers unauthenticated requests with
+`401` and a `WWW-Authenticate: Bearer resource_metadata="…"` challenge,
+validates access tokens by introspection, checks they were issued for this
+endpoint, and never forwards them upstream.
 
 ### 3. Talk to it
 
@@ -73,11 +200,13 @@ The transport is stateless (streamable HTTP); the `Authorization: Bearer pk_...`
 
 | Variable | Required | Description |
 |---|---|---|
-| `PLANPOST_API_KEY` | ✅ | API key from Settings → API Keys (`pk_live_…`) |
+| `PLANPOST_API_KEY` | stdio only | API key from Settings → API Keys (`pk_live_…`). Not needed with `--http`, where each request brings its own credentials. |
 | `PLANPOST_API_URL` | — | API base URL (default `https://api.planpo.st`) |
 
 ## Tools
 
+49 tools, grouped below. The permission column is the scope a tool needs, whether it comes from an API key or from OAuth sign-in; a credential without the scope gets a clear error rather than a silent failure. Every tool carries MCP annotations (a title plus read-only, destructive and open-world hints) so clients know which calls to confirm.
+
 ### Posts & publishing
 
 | Tool | Required permission | Description |
@@ -88,6 +217,13 @@ The transport is stateless (streamable HTTP); the `Authorization: Bearer pk_...`
 | `update_post` | `posts:write` | Update a draft/scheduled post |
 | `delete_post` | `posts:write` | Delete a post |
 | `publish_post` | `posts:write` | Publish immediately |
+| `retry_failed` | `posts:write` | Re-queue the platforms that failed for a transient reason; never re-posts one that went out |
+| `get_delivery_report` | `posts:read` | The morning check: recent failed or partly failed posts with each platform's error and fix, unhealthy connections, approvals running late |
+| `preview_post` | `posts:read` | Show exactly what each platform will receive (text after overrides, attachments, warnings) |
+| `bulk_create_posts` | `posts:write` | Create a whole campaign of posts from one manifest |
+| `list_campaigns` | `posts:read` | Campaign tags in use, with post counts by status and platform |
+| `delete_posts` | `posts:write` | Bulk-delete posts matching a filter (a filter is required) |
+| `list_media` | `media:read` | Media already uploaded, so an asset can be reused instead of re-uploaded |
 | `upload_media` | `media:write` | Get a presigned URL to upload an image/video |
 | `repurpose_content` | `repurpose:write` | Save repurposed content as draft posts |
 
@@ -98,8 +234,31 @@ The transport is stateless (streamable HTTP); the `Authorization: Bearer pk_...`
 | `list_connections` | `connections:read` | Connected social accounts |
 | `list_account_groups` | `groups:read` | Named account groups (e.g. "Polish Pages") |
 | `get_account_group` | `groups:read` | Resolve a group by id/name/default → connection IDs |
+| `create_account_group` | `groups:write` | Create a named group bundling connections |
+| `update_account_group` | `groups:write` | Rename, recolour, set default, or replace a group's connections |
+| `delete_account_group` | `groups:write` | Delete a group (the accounts stay connected) |
+| `add_connections_to_group` | `groups:write` | Add connections to a group |
+| `remove_connections_from_group` | `groups:write` | Remove connections from a group |
+| `get_connection_link` | `connections:read` | Link the user opens in a browser to connect a new social account (OAuth needs a human) |
+
+Connecting a new social account requires OAuth in a browser: `get_connection_link` hands the user the link, and the agent can target the account once it is connected.
+
+### Approvals
+
+| Tool | Required permission | Description |
+|---|---|---|
+| `submit_for_approval` | `approvals:write` | Send a post to a human reviewer (required when the API key is approval-gated) |
+| `list_pending_approvals` | `approvals:read` | Posts waiting for review, with outcomes |
+| `get_approval_status` | `approvals:read` | Pending / approved / rejected / changes requested for one submission |
+
+### Scheduling
 
-Connecting a new social account requires OAuth in the dashboard — agents can target any account that's already connected.
+| Tool | Required permission | Description |
+|---|---|---|
+| `get_best_times` | `schedule:read` | Best posting times per platform from the account's engagement history |
+| `suggest_schedule` | `schedule:read` | Spread N posts across a date range at optimal times; returns concrete timestamps |
+| `get_posting_schedule` | `schedule:read` | Weekly queue slots, global plus per-group overrides |
+| `set_posting_schedule` | `schedule:write` | Replace the weekly queue slots for the global schedule or one group (Pro) |
 
 ### Video & carousels
 
@@ -113,6 +272,7 @@ Connecting a new social account requires OAuth in the dashboard — agents can t
 | `render_carousel` | `carousels:write` | Render slides into branded PNGs in the media library |
 | `get_carousel_render` | `carousels:read` | Poll a render; completed renders return post-ready media assets |
 | `list_brand_kits` | `brand-kits:read` | Saved brand kits (palette, fonts, logo, handle) for `render_carousel` |
+| `generate_image` | `images:write` | Generate an image with AI for a post (1 AI credit); pass the URL to `create_post` |
 
 ### Content sources
 
@@ -133,6 +293,13 @@ Connecting a new social account requires OAuth in the dashboard — agents can t
 
 Revenue data is read-only over the API; connecting Stripe/RevenueCat/Shopify happens in the dashboard (Settings → Revenue).
 
+### Brand voice (Pro)
+
+| Tool | Required permission | Description |
+|---|---|---|
+| `get_brand_voices` | `brand-voice:read` | Tone-of-voice profiles analysed from the user's content |
+| `get_brand_voice_prompt` | `brand-voice:read` | Ready-to-use system prompt for a voice; apply it when drafting posts |
+
 ## A typical agent workflow
 
 1. `get_account_group` (`default: true`) → connection IDs
@@ -152,10 +319,55 @@ Or, for a branded carousel post end-to-end:
 ```bash
 npm install
 npm run build      # tsc → dist/
+npm test           # builds, validates server.json and the plugin manifests, boots stdio, exercises hosted OAuth mode
 PLANPOST_API_KEY=pk_test_xxx node dist/index.js
 ```
 
-The server speaks MCP over stdio. It calls the PlanPost public API (`/api/public/v1`) with your key; nothing else is stored or sent anywhere.
+The server speaks MCP over stdio, or streamable HTTP with `--http`. It calls the PlanPost public API (`/api/public/v1`) with your credentials; nothing else is stored or sent anywhere. Changes are listed in [CHANGELOG.md](./CHANGELOG.md).
+
+## Maintainers
+
+Releasing a version means publishing twice: the code to npm, then the metadata
+to the [official MCP Registry](https://registry.modelcontextprotocol.io), which
+only stores `server.json` and checks that the npm package it points at exists
+and carries the matching `mcpName`. Glama and other directories import from the
+registry, so the second step is what makes a release discoverable.
+
+1. Bump `version` in `package.json` **and** in `server.json` (top level and
+   `packages[0].version`), `gemini-extension.json`, `.claude-plugin/plugin.json`
+   and `.cursor-plugin/plugin.json`, and add a `CHANGELOG.md` entry. `npm test`
+   fails if any of them disagree.
+2. Publish to npm first; the registry rejects a version npm does not have yet:
+
+   ```bash
+   npm publish --access public
+   ```
+
+3. Install the publisher CLI once (`brew install mcp-publisher`, or the tarball
+   from the registry's GitHub releases), then log in. The `io.github.lukBB/*`
+   namespace is proven by GitHub device-flow login as that account:
+
+   ```bash
+   mcp-publisher login github
+   ```
+
+4. Validate and publish from this directory:
+
+   ```bash
+   mcp-publisher validate
+   mcp-publisher publish
+   ```
+
+5. Confirm the listing:
+
+   ```bash
+   curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.lukBB/planpost"
+   ```
+
+An expired token shows as "Invalid or expired Registry JWT token": run the login
+again. `mcp-publisher status` deprecates or deletes a published version.
+A tagged GitHub release is what the Gemini CLI extension gallery and the
+plugin marketplaces pick up, so tag `vX.Y.Z` after publishing.
 
 ## License
 

package/dist/annotations.d.ts

@@ -0,0 +1,3 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+export declare const ANNOTATED_TOOLS: string[];
+export declare function annotationsFor(name: string): ToolAnnotations;

package/dist/annotations.js

@@ -0,0 +1,66 @@
+const TOOLS = {
+    list_posts: ["List posts", "read"],
+    get_post: ["Get a post", "read"],
+    // Can publish immediately, and a published post cannot be recalled.
+    create_post: ["Create, schedule or publish a post", "destroy", "world"],
+    preview_post: ["Preview a post per platform", "read"],
+    bulk_create_posts: ["Create several posts", "destroy", "world"],
+    list_campaigns: ["List campaigns", "read"],
+    delete_posts: ["Delete several posts", "destroy"],
+    list_media: ["List media library", "read"],
+    update_post: ["Edit a post", "destroy", "world"],
+    delete_post: ["Delete a post", "destroy"],
+    retry_failed: ["Retry failed platforms", "destroy", "world"],
+    get_delivery_report: ["Get delivery report", "read"],
+    publish_post: ["Publish a post now", "destroy", "world"],
+    list_connections: ["List connected social accounts", "read"],
+    list_account_groups: ["List account groups", "read"],
+    get_account_group: ["Get an account group", "read"],
+    create_account_group: ["Create an account group", "write"],
+    update_account_group: ["Edit an account group", "destroy"],
+    delete_account_group: ["Delete an account group", "destroy"],
+    add_connections_to_group: ["Add accounts to a group", "write"],
+    remove_connections_from_group: ["Remove accounts from a group", "destroy"],
+    get_connection_link: ["Get a link to connect an account", "read"],
+    submit_for_approval: ["Submit a post for approval", "write"],
+    list_pending_approvals: ["List pending approvals", "read"],
+    get_approval_status: ["Get approval status", "read"],
+    get_analytics: ["Get post analytics", "read"],
+    upload_media: ["Get a media upload URL", "write"],
+    repurpose_content: ["Repurpose content with AI", "write"],
+    list_video_templates: ["List video templates", "read"],
+    create_video: ["Render a video", "write"],
+    get_video_status: ["Get video render status", "read"],
+    generate_carousel: ["Draft carousel slides", "write"],
+    list_carousel_styles: ["List carousel styles", "read"],
+    render_carousel: ["Render a carousel", "write"],
+    get_carousel_render: ["Get carousel render status", "read"],
+    list_brand_kits: ["List brand kits", "read"],
+    list_content_sources: ["List content sources", "read"],
+    add_content_source: ["Add a content source", "write", "world"],
+    delete_content_source: ["Delete a content source", "destroy"],
+    fetch_source_content: ["Sync a content source", "write", "world"],
+    list_imported_content: ["List imported content", "read"],
+    get_revenue_overview: ["Get revenue overview", "read"],
+    generate_image: ["Generate an image", "write"],
+    get_brand_voices: ["List brand voices", "read"],
+    get_brand_voice_prompt: ["Get a brand voice prompt", "read"],
+    get_best_times: ["Get best times to post", "read"],
+    suggest_schedule: ["Suggest a schedule", "read"],
+    get_posting_schedule: ["Get posting schedule", "read"],
+    set_posting_schedule: ["Replace posting schedule", "destroy"],
+};
+export const ANNOTATED_TOOLS = Object.keys(TOOLS);
+export function annotationsFor(name) {
+    const entry = TOOLS[name];
+    if (!entry)
+        throw new Error(`Tool "${name}" has no entry in annotations.ts`);
+    const [title, kind, world] = entry;
+    return {
+        title,
+        readOnlyHint: kind === "read",
+        destructiveHint: kind === "destroy",
+        idempotentHint: kind === "read",
+        openWorldHint: world === "world",
+    };
+}