planpost-mcp 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to `planpost-mcp`. Versions follow [semver](https://semver.org).
+
+## 0.4.1 — 2026-11-14
+
+### Changed
+- Agents that sign in with OAuth see 34 tools: the scheduling, delivery,
+  analytics, revenue and approval tools. The video, carousel, brand kit,
+  content source and repurposing tools are left out for them, because those
+  features are parked in the PlanPost app; an API key still gets all 49.
+- `create_post` no longer points agents at the carousel tools; several
+  attached images publish as a carousel where the network supports one.
+- Descriptions in the README, `server.json`, the plugin manifests, GEMINI.md
+  and the skill describe the product as it is now: an agentic scheduler, with
+  approval as a choice the user makes (off by default).
+- `generate_image` is among the tools left out for OAuth sign-ins: it calls a
+  generative image model, which the Claude directory does not allow in a
+  listed server.
+- `.claude-plugin/marketplace.json` has a marketplace description.
+
+### Removed
+- The `send-to-plan-post` skill. It described one account's own groups, not
+  the product. `skills/planpost` is the skill to install.
+
+## 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,21 +1,56 @@
 # 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 your AI agent can run. It lets Claude, ChatGPT, Cursor, Gemini CLI and other AI agents draft, schedule and publish posts to Instagram, Facebook, LinkedIn, X, Threads, TikTok and YouTube, see what failed and why, and read analytics and revenue from 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
+(they go out at the time the agent sets unless you turn that on). 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 on the **Agent** page under **Connected apps**,
+where you can turn approval on or off for each one, or remove it, 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.
+In the PlanPost dashboard open the **Agent** page and choose **Create key** and select the permissions you need (see the table below). The key (`pk_live_…`) is shown **once** — copy it.
 
-> API/MCP access is included in every paid plan — Creator: 1,000 calls/month, Pro: 10,000 calls/month. Keys are scoped: a key with only `posts:read` cannot publish.
+> API/MCP access is included on every plan: Free 200 calls a month, Creator 1,000, Pro 10,000. Keys are scoped: a key with only `posts:read` cannot publish.
 
 ### 2. Add the server to your agent
 
 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 47 tools.
+leaves it. Both expose the same 49 tools to an API key; an agent that signs in
+with OAuth gets 34 of them (see the note under Tools).
 
 Replace `pk_live_xxx` with your key throughout.
 
@@ -131,19 +166,35 @@ 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
 ```
 
-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 in production.
-`--host` / `HOST` default to `0.0.0.0`, so containers and LAN use work without
-extra flags.
+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.
+
+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/*`):
+
+| 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. |
+
+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
 
 > "Schedule this post to my Polish Pages group for tomorrow 9:00: …"
 >
-> "Make a quote video from this testimonial and publish it as a reel."
+> "Here is my new blog post. Write one version per network and spread them across next week."
 >
-> "Pull the latest posts from my WordPress blog and draft a LinkedIn carousel from the newest one."
+> "What failed to publish this week, and what do I need to fix?"
 >
 > "How much revenue did my posts drive last 30 days?"
 
@@ -151,12 +202,12 @@ extra flags.
 
 | Variable | Required | Description |
 |---|---|---|
-| `PLANPOST_API_KEY` | ✅ | API key from Settings → API Keys (`pk_live_…`) |
+| `PLANPOST_API_KEY` | stdio only | API key from the Agent page in PlanPost (`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
 
-47 tools, grouped below. The permission column is the API-key scope a tool needs; a key without the scope gets a clear error rather than a silent failure.
+49 tools, grouped below. An agent that signs in with OAuth (the hosted server with no key, which is how Claude, ChatGPT and Cursor connect) is offered 34: the AI image tool and the video, carousel, brand kit, content source and repurposing tools are left out, because those features are parked in the PlanPost app. An API key gets all 49. 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
 
@@ -168,6 +219,8 @@ extra flags.
 | `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 |
@@ -192,6 +245,8 @@ extra flags.
 
 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.
 
+X needs a paid plan. On the free plan `get_connection_link` answers with an upgrade message for `twitter`, `list_connections` marks an X account that is already connected as not on the current plan, and a post that targets X is saved as a draft with the `x_requires_paid_plan` error.
+
 ### Approvals
 
 | Tool | Required permission | Description |
@@ -268,11 +323,11 @@ Or, for a branded carousel post end-to-end:
 ```bash
 npm install
 npm run build      # tsc → dist/
-npm test           # validates server.json against the registry schema, boots the stdio server
+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
 
@@ -283,7 +338,9 @@ 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`). `npm test` fails if they disagree.
+   `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
@@ -313,8 +370,8 @@ registry, so the second step is what makes a release discoverable.
 
 An expired token shows as "Invalid or expired Registry JWT token": run the login
 again. `mcp-publisher status` deprecates or deletes a published version.
-Directory listings beyond the registry (mcp.so, Cursor Directory, outreach) are
-tracked in [DISTRIBUTION.md](./DISTRIBUTION.md).
+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",
+    };
+}

package/dist/index.js

@@ -6,6 +6,8 @@ import { createServer as createHttpServer } from "node:http";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createRequire } from "node:module";
 import { z } from "zod";
+import { annotationsFor } from "./annotations.js";
+import { AccessTokenVerifier, IntrospectionUnavailableError, InvalidTokenError, bearerChallenge, loadOAuthSettings, protectedResourceMetadata, upstreamHeaders, } from "./oauth.js";
 const ENV_API_KEY = process.env.PLANPOST_API_KEY;
 const BASE_URL = process.env.PLANPOST_API_URL || "https://api.planpo.st";
 // Single source of truth for the version: package.json ships in every tarball,
@@ -13,17 +15,20 @@ const BASE_URL = process.env.PLANPOST_API_URL || "https://api.planpo.st";
 // the two drifted on the first release that forgot to update both.
 const { version } = createRequire(import.meta.url)("../package.json");
 const SERVER_INFO = { name: "planpost", version };
-// In HTTP mode each request carries its own key (Authorization header); the
-// AsyncLocalStorage context survives across the awaits inside tool handlers,
-// so concurrent requests with different keys can't bleed into each other.
-// Stdio mode falls back to the env key.
-const requestApiKey = new AsyncLocalStorage();
-function resolveApiKey() {
-    const key = requestApiKey.getStore() || ENV_API_KEY;
-    if (!key) {
+// In HTTP mode each request carries its own credential (an API key, or an
+// OAuth grant resolved from the access token); the AsyncLocalStorage context
+// survives across the awaits inside tool handlers, so concurrent requests
+// with different credentials can't bleed into each other. Stdio mode falls
+// back to the env key.
+const requestCredential = new AsyncLocalStorage();
+function resolveCredential() {
+    const credential = requestCredential.getStore();
+    if (credential)
+        return credential;
+    if (!ENV_API_KEY) {
         throw new Error("No PlanPost API key: set PLANPOST_API_KEY (stdio) or send Authorization: Bearer pk_... (http)");
     }
-    return key;
+    return { kind: "key", key: ENV_API_KEY };
 }
 // ─── API Client ───
 async function api(path, options = {}) {
@@ -32,7 +37,7 @@ async function api(path, options = {}) {
         ...options,
         headers: {
             "Content-Type": "application/json",
-            Authorization: `Bearer ${resolveApiKey()}`,
+            ...upstreamHeaders(resolveCredential()),
             ...options.headers,
         },
     });
@@ -54,6 +59,18 @@ function formatWarnings(warnings) {
     const lines = warnings.map((w) => `  - [${w.code}]${w.platform ? ` ${w.platform}:` : ""} ${w.message}`);
     return `\n\n⚠️  ${warnings.length} warning(s):\n${lines.join("\n")}`;
 }
+/**
+ * Renders the API's `preflight.errors[]` — the checks that would make the
+ * post fail at its slot. When present the post was saved as a DRAFT, not
+ * scheduled; fix the listed fields and call update_post (or create again).
+ */
+function formatPreflight(preflight) {
+    const p = preflight;
+    if (!p || !Array.isArray(p.errors) || p.errors.length === 0)
+        return "";
+    const lines = p.errors.map((e) => `  - [${e.code}] ${e.platform}: ${e.message}${e.fix ? ` Fix: ${e.fix}` : ""}`);
+    return `\n\n⛔ Saved as DRAFT — ${p.errors.length} issue(s) block scheduling:\n${lines.join("\n")}`;
+}
 /** Renders the dashboard deep links returned alongside a created/updated post. */
 function formatLinks(links) {
     if (!links || typeof links !== "object")
@@ -66,18 +83,64 @@ function formatLinks(links) {
 // ─── MCP Server ───
 // Tool registration is a function so HTTP mode can build a fresh server per
 // request (stateless transport); stdio builds one at startup.
-function buildServer() {
+function buildServer(omit = NO_TOOLS) {
     const server = new McpServer(SERVER_INFO);
-    registerTools(server);
+    registerTools(server, omit);
     return server;
 }
+const NO_TOOLS = new Set();
+/**
+ * Tools left out for agents that signed in with OAuth, which is how every
+ * directory-listed client (Claude, ChatGPT, Cursor) connects.
+ *
+ * - generate_image calls a generative image model. The Claude directory's
+ *   compliance step requires the statement "My MCP server does not use AI
+ *   models to generate images, video, or audio", and a tool that is merely
+ *   discouraged would make that statement false.
+ * - Video and carousel templates, brand kits, content sources and repurposing
+ *   belong to features parked in the app since 2026-11-11 (PARKED_NAV in
+ *   apps/web/lib/config/nav.tsx). A signed-in agent is offered what the
+ *   product sells: scheduling, delivery, results and approvals.
+ *
+ * API-key connections, which the user sets up by hand, keep the full set.
+ * To bring a parked feature back, remove its tools here and its nav entry.
+ */
+const OMITTED_FOR_SIGNED_IN_AGENTS = new Set([
+    "generate_image",
+    // Video templates
+    "create_video",
+    "get_video_status",
+    "list_video_templates",
+    // Carousel templates and brand kits
+    "generate_carousel",
+    "render_carousel",
+    "get_carousel_render",
+    "list_carousel_styles",
+    "list_brand_kits",
+    // Content sources and repurposing
+    "add_content_source",
+    "delete_content_source",
+    "fetch_source_content",
+    "list_content_sources",
+    "list_imported_content",
+    "repurpose_content",
+]);
 // ─── Tools ───
-function registerTools(server) {
+function registerTools(target, omit = NO_TOOLS) {
+    // Every tool below is registered through this shim so its annotations
+    // (title, read-only / destructive hints) come from annotations.ts.
+    const server = {
+        tool: ((name, description, schema, handler) => {
+            if (omit.has(name))
+                return undefined;
+            return target.tool(name, description, schema, annotationsFor(name), handler);
+        }),
+    };
     server.tool("list_posts", "List your scheduled and published social media posts. Filter by status, platform, campaign, label, post type, or free text.", {
         // `needs_approval` is a first-class status, not an internal one: a post
         // parked for human sign-off is exactly what an agent needs to be able to
         // find again after submitting it.
-        status: z.enum(["draft", "needs_approval", "scheduled", "processing", "published", "failed", "cancelled"]).optional().describe("Filter by post status ('needs_approval' = waiting on human sign-off)"),
+        status: z.enum(["draft", "needs_approval", "scheduled", "processing", "published", "partially_published", "failed", "cancelled"]).optional().describe("Filter by post status ('needs_approval' = waiting on human sign-off; 'partially_published' = some platforms live, at least one failed — see platformResults[].error and .fix)"),
         platform: z.string().optional().describe("Filter by platform (instagram, twitter, linkedin, etc.)"),
         campaign: z.string().optional().describe("Filter by campaign tag, e.g. 'garmin-cirqa-2026' (matches utm.campaign; slugified automatically)"),
         label: z.string().optional().describe("Filter by internal label (case-insensitive substring), e.g. 'Garmin CIRQA'"),
@@ -119,8 +182,8 @@ function registerTools(server) {
         content: z.string().describe("Post text content"),
         connectionIds: z.array(z.string()).describe("Array of social connection IDs to post to. Use list_connections or list_account_groups to find IDs."),
         platformContent: z.record(z.string(), z.string()).optional().describe("Per-platform content overrides, e.g. { twitter: 'shorter version', linkedin: 'longer version' }"),
-        platformSettings: z.record(z.string(), z.any()).optional().describe("Per-platform settings, e.g. { instagram: { isReel: true }, youtube: { title: '...', visibility: 'public' } }"),
-        postType: z.enum(["post", "reel", "short", "story", "thread"]).optional().describe("Explicit post type (clearer than platformSettings flags, and takes precedence over them). 'reel' needs Instagram/Facebook; 'short' needs YouTube/Instagram/TikTok/Facebook; 'story' needs Instagram/Facebook; 'thread' is X/Twitter-only and requires threadSegments. Defaults to 'post', or is inferred from platformSettings flags (e.g. { instagram: { isReel: true } } → reel). NOTE: a carousel is NOT a postType — attach media with type 'carousel' or use generate_carousel/render_carousel."),
+        platformSettings: z.record(z.string(), z.any()).optional().describe("Per-platform settings, e.g. { instagram: { isReel: true }, youtube: { title: '...', visibility: 'public' } }. TikTok: a scheduled or published post MUST carry { tiktok: { privacyLevel } } with one of PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY (TikTok makes the user choose who can view each video; without it the API returns 400). Optional tiktok flags: disableComment, disableDuet, disableStitch (default true = off), brandedContent, yourBrand."),
+        postType: z.enum(["post", "reel", "short", "story", "thread"]).optional().describe("Explicit post type (clearer than platformSettings flags, and takes precedence over them). 'reel' needs Instagram/Facebook; 'short' needs YouTube/Instagram/TikTok/Facebook; 'story' needs Instagram (Facebook Stories are not supported); 'thread' is X/Twitter-only and requires threadSegments. Defaults to 'post', or is inferred from platformSettings flags (e.g. { instagram: { isReel: true } } → reel). NOTE: a carousel is NOT a postType — attach several images (or media with type 'carousel') and it publishes as a carousel where the network supports one."),
         threadSegments: z.array(z.string()).optional().describe("Ordered tweet segments for a thread (only used when postType='thread', X/Twitter-only). 2–25 segments, each 1–280 characters."),
         label: z.string().optional().describe("Internal working name shown in the PlanPost dashboard list, e.g. 'Garmin CIRQA - IG Carousel'. Never published to any platform — it just makes a campaign's drafts tellable apart. Highly recommended when creating several posts at once."),
         campaign: z.string().optional().describe("Campaign tag, e.g. 'garmin-cirqa-2026' (slugified automatically). Sets utm.campaign and derives a utm.content token from the format (e.g. 'ig-carousel', 'fb-static'). Group/filter/bulk-delete by this with list_campaigns, list_posts({campaign}) and delete_posts({campaign})."),
@@ -184,7 +247,7 @@ function registerTools(server) {
             : post.scheduledFor
                 ? `Scheduled for ${post.scheduledFor}`
                 : "Saved as draft";
-        return { content: [{ type: "text", text: `Post created (${status}).${formatWarnings(data.warnings)}${formatLinks(data.links)}\n\n${JSON.stringify(post, null, 2)}` }] };
+        return { content: [{ type: "text", text: `Post created (${status}).${formatPreflight(data.preflight)}${formatWarnings(data.warnings)}${formatLinks(data.links)}\n\n${JSON.stringify(post, null, 2)}` }] };
     });
     server.tool("preview_post", "Show exactly what each platform will receive for a post: the body after platformContent overrides, the attachments after platformMedia overrides, character count vs the platform limit, whether links are clickable, and the warnings for that platform. Use this to check a post (especially carousels, videos and multi-platform posts) BEFORE scheduling or publishing. Returns structured data plus a dashboard link for the visual preview — it does not return screenshots.", {
         id: z.string().describe("Post ID to preview"),
@@ -209,7 +272,10 @@ function registerTools(server) {
                 pl.content.length > 400 ? `${pl.content.slice(0, 400)}…` : pl.content,
             ].filter(Boolean).join("\n");
         });
-        const header = `Preview — postType=${p.postType}${p.label ? ` · ${p.label}` : ""}${p.campaign ? ` · campaign=${p.campaign}` : ""}`;
+        const blockedLine = p.preflight && p.preflight.ok === false
+            ? `\n⛔ ${p.preflight.errors.length} issue(s) block scheduling — fix them with update_post:\n${p.preflight.errors.map((e) => `  - [${e.code}] ${e.platform}: ${e.message}${e.fix ? ` Fix: ${e.fix}` : ""}`).join("\n")}\n`
+            : "";
+        const header = `Preview — postType=${p.postType}${p.label ? ` · ${p.label}` : ""}${p.campaign ? ` · campaign=${p.campaign}` : ""}${p.status ? ` · status=${p.status}` : ""}${blockedLine}`;
         return {
             content: [{
                     type: "text",
@@ -227,7 +293,9 @@ function registerTools(server) {
         const data = await api("/posts/bulk", { method: "POST", body: JSON.stringify(body) });
         const d = data.data;
         const lines = (d.results ?? []).map((r) => r.ok
-            ? `  #${r.index} OK  ${r.label ?? "(no label)"} → ${r.id} [${r.status}]${Array.isArray(r.warnings) && r.warnings.length ? ` (${r.warnings.length} warning(s))` : ""}`
+            ? `  #${r.index} OK  ${r.label ?? "(no label)"} → ${r.id} [${r.status}]${Array.isArray(r.warnings) && r.warnings.length ? ` (${r.warnings.length} warning(s))` : ""}${Array.isArray(r.preflightErrors) && r.preflightErrors.length
+                ? `\n      ⛔ saved as draft: ${r.preflightErrors.map((e) => `[${e.code}] ${e.message}${e.fix ? ` Fix: ${e.fix}` : ""}`).join(" | ")}`
+                : ""}`
             : `  #${r.index} FAILED  ${r.error}`);
         return {
             content: [{
@@ -290,7 +358,7 @@ function registerTools(server) {
         content: z.string().optional().describe("New post text content"),
         connectionIds: z.array(z.string()).optional().describe("New connection IDs"),
         platformContent: z.record(z.string(), z.string()).optional().describe("Per-platform content overrides"),
-        platformSettings: z.record(z.string(), z.any()).optional().describe("Per-platform settings (e.g. { instagram: { isReel: true } })"),
+        platformSettings: z.record(z.string(), z.any()).optional().describe("Per-platform settings (e.g. { instagram: { isReel: true } }). TikTok posts need { tiktok: { privacyLevel } } (PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | FOLLOWER_OF_CREATOR | SELF_ONLY) before they can be scheduled — this is how to repair a TikTok post that was created without one."),
         postType: z.enum(["post", "reel", "short", "story", "thread"]).optional().describe("Explicit post type; takes precedence over platformSettings flags. Same platform rules as create_post ('thread' is X/Twitter-only and needs threadSegments). Omit to leave the current type unchanged — a plain edit never downgrades a reel/short/story."),
         threadSegments: z.array(z.string()).optional().describe("Ordered tweet segments for a thread (postType='thread'). 2–25 segments, each 1–280 characters."),
         label: z.string().nullable().optional().describe("Internal working name shown in the dashboard. Pass null to clear. Never published."),
@@ -353,7 +421,7 @@ function registerTools(server) {
         if (timezone !== undefined)
             body.timezone = timezone;
         const data = await api(`/posts/${id}`, { method: "PUT", body: JSON.stringify(body) });
-        return { content: [{ type: "text", text: `Post updated.${formatWarnings(data.warnings)}${formatLinks(data.links)}\n\n${JSON.stringify(data.data, null, 2)}` }] };
+        return { content: [{ type: "text", text: `Post updated (${data.data?.status ?? "unknown"}).${formatPreflight(data.preflight)}${formatWarnings(data.warnings)}${formatLinks(data.links)}\n\n${JSON.stringify(data.data, null, 2)}` }] };
     });
     server.tool("delete_post", "Delete a post.", {
         id: z.string().describe("Post ID to delete"),
@@ -361,6 +429,84 @@ function registerTools(server) {
         await api(`/posts/${id}`, { method: "DELETE" });
         return { content: [{ type: "text", text: `Post ${id} deleted.` }] };
     });
+    server.tool("retry_failed", "Retry the platforms that failed on a failed or partially_published post. Only failures classified transient (platform outage, rate limit, network) are re-queued; failures that need the user — reconnect an account, top up X API credits, choose TikTok visibility — or that the payload caused are refused and returned with their fix. Platforms that already went out are never re-posted. Check get_post → platformResults[].errorClass / .fix first.", {
+        id: z.string().describe("Post ID with status failed or partially_published"),
+    }, async ({ id }) => {
+        let data;
+        try {
+            data = await api(`/posts/${id}/retry`, { method: "POST" });
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Retry refused: ${e?.message ?? e}` }] };
+        }
+        const retried = Array.isArray(data.retried) && data.retried.length ? data.retried.join(", ") : "nothing";
+        const blocked = Array.isArray(data.blocked) && data.blocked.length
+            ? `\n\nNot retried (a retry would fail the same way):\n${data.blocked.map((b) => `  - ${b.provider}: [${b.code}] ${b.error ?? ""}${b.fix ? ` Fix: ${b.fix}` : ""}`).join("\n")}`
+            : "";
+        return { content: [{ type: "text", text: `Retrying: ${retried}.${blocked}${formatLinks(data.links)}\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("get_delivery_report", "The morning check: everything that needs the user's attention about delivery. Posts that failed or partially failed in the last `days` days with each platform's error and fix, connections whose health went dead or degraded, pending approvals whose slot is within 48 h or already passed, approvals that expired (their posts are drafts again), scheduled posts in the next 7 days that would fail preflight if dispatched now, auto-import content sources that stopped fetching, and posting queues with free slots this week while drafts wait. Same data as the 08:00 digest e-mail. Empty `hasIssues: false` means nothing to do.", {
+        days: z.number().int().min(1).max(30).optional().describe("Look-back window in days for failures and connection changes (default 1)"),
+    }, async ({ days }) => {
+        const data = await api(`/delivery-report?days=${days ?? 1}`);
+        const r = data.data ?? {};
+        const label = (p) => p;
+        const lines = [];
+        if (!r.hasIssues) {
+            lines.push(`All clear for the last ${r.windowDays ?? days ?? 1} day(s): no failed posts, no connection changes, no approvals due or expired, no upcoming post fails preflight, no stale content source, no empty queue slots with drafts waiting.`);
+        }
+        else {
+            if (Array.isArray(r.failedPosts) && r.failedPosts.length) {
+                lines.push(`Did not go out (${r.failedPosts.length}):`);
+                for (const p of r.failedPosts) {
+                    lines.push(`  - ${p.postId} [${p.status}${p.status === "partially_published" ? ` ${p.liveCount}/${p.targetCount} live` : ""}] ${p.content}`);
+                    for (const f of p.failures ?? []) {
+                        lines.push(`      ${label(f.provider)}: [${f.errorCode ?? f.errorClass ?? "failed"}] ${f.error ?? ""}${f.fix ? ` Fix: ${f.fix}` : ""}`);
+                    }
+                }
+            }
+            if (Array.isArray(r.connections) && r.connections.length) {
+                lines.push(`Connections (${r.connections.length}):`);
+                for (const c of r.connections) {
+                    lines.push(`  - ${c.provider} @${c.username} is ${c.status}${c.reason ? ` [${c.reason}]` : ""}${c.lastError ? `: ${c.lastError}` : ""}${c.status === "dead" ? " Fix: reconnect on /connections." : ""}`);
+                }
+            }
+            if (Array.isArray(r.approvals) && r.approvals.length) {
+                lines.push(`Approvals (${r.approvals.length}):`);
+                for (const a of r.approvals) {
+                    lines.push(`  - ${a.approvalId} post ${a.postId} ${a.overdue ? "SLOT PASSED" : `due ${a.scheduledFor}`}${a.reviewerEmail ? ` (reviewer ${a.reviewerEmail})` : ""}: ${a.content}`);
+                }
+            }
+            if (Array.isArray(r.expiredApprovals) && r.expiredApprovals.length) {
+                lines.push(`Approvals that expired, posts back to draft (${r.expiredApprovals.length}):`);
+                for (const a of r.expiredApprovals) {
+                    lines.push(`  - ${a.approvalId} post ${a.postId}${a.scheduledFor ? ` (slot was ${a.scheduledFor})` : ""}${a.reviewerEmail ? ` reviewer ${a.reviewerEmail}` : ""}: ${a.content} Fix: reschedule with update_post and resubmit, or publish_post.`);
+                }
+            }
+            if (Array.isArray(r.atRisk) && r.atRisk.length) {
+                lines.push(`Scheduled posts that will fail (${r.atRisk.length}):`);
+                for (const p of r.atRisk) {
+                    lines.push(`  - ${p.postId} at ${p.scheduledFor}: ${p.content}`);
+                    for (const i of p.issues ?? []) {
+                        lines.push(`      ${i.platform}: [${i.code}] ${i.message}${i.fix ? ` Fix: ${i.fix}` : ""}`);
+                    }
+                }
+            }
+        }
+        if (Array.isArray(r.staleSources) && r.staleSources.length) {
+            lines.push(`Content sources that stopped importing (${r.staleSources.length}):`);
+            for (const src of r.staleSources) {
+                lines.push(`  - ${src.sourceId} ${src.name} (${src.frequency}, last fetch ${src.lastFetchedAt ?? "never"}, ${src.staleHours}h ago). Fix: fetch_source_content, then check the URL/credentials if it fails.`);
+            }
+        }
+        if (Array.isArray(r.staleQueues) && r.staleQueues.length) {
+            lines.push(`Posting queues with empty slots while drafts wait (${r.staleQueues.length}):`);
+            for (const q of r.staleQueues) {
+                lines.push(`  - ${q.groupName ? `group ${q.groupName} (${q.groupId})` : "global queue"}: ${q.emptySlots} of ${q.totalSlots} slots free in the next ${q.horizonDays} days, ${q.drafts} draft(s). Fix: suggest_schedule / update_post with a scheduledFor from get_posting_schedule.`);
+            }
+        }
+        return { content: [{ type: "text", text: `${lines.join("\n")}\n\n${JSON.stringify(r, null, 2)}` }] };
+    });
     server.tool("publish_post", "Publish a draft or scheduled post immediately to all connected platforms. X (Twitter): nothing sent to X may contain a link (URL, bare domain or t.co) — not the post, any thread segment, or a first comment (posted to X as a reply). The X API bills each link post at $0.20 vs $0.015, so the API rejects them; put a link-free version in platformContent.twitter.", {
         id: z.string().describe("Post ID to publish now"),
     }, async ({ id }) => {
@@ -370,8 +516,27 @@ function registerTools(server) {
     server.tool("list_connections", "List all connected social media accounts (Instagram, Twitter, LinkedIn, etc.).", {}, async () => {
         const data = await api("/connections");
         const connections = data.data;
-        const summary = connections.map((c) => `${c.provider} — ${c.metadata?.accountName || c.providerUsername} (ID: ${c.id})`).join("\n");
-        return { content: [{ type: "text", text: `${connections.length} connected accounts:\n\n${summary}\n\nFull data:\n${JSON.stringify(connections, null, 2)}` }] };
+        // Health comes from the publishing worker and token refresher: a `dead`
+        // account fails preflight for every post that targets it until `reason`
+        // is fixed, so say so next to the name instead of burying it in JSON.
+        const healthTag = (c) => {
+            const h = c.health;
+            if (!h || h.status === "healthy")
+                return "";
+            if (h.status === "degraded")
+                return "  ⚠️ last publish failed, will retry";
+            return `  ⛔ cannot publish${h.reason ? ` [${h.reason}]` : ""}${h.lastError ? `: ${String(h.lastError).slice(0, 120)}` : ""}`;
+        };
+        // `planBlocked` means the platform is not on the account's current plan
+        // (X needs a paid plan). The account is connected and healthy, but a post
+        // that targets it fails preflight with `x_requires_paid_plan`, so flag it
+        // here before the agent picks it.
+        const planTag = (c) => c.planBlocked ? `  ⛔ not on the current plan, needs ${c.requiredPlan === "pro" ? "Pro" : "Creator or Pro"}` : "";
+        const summary = connections.map((c) => `${c.provider} — ${c.metadata?.accountName || c.providerUsername} (ID: ${c.id})${planTag(c) || healthTag(c)}`).join("\n");
+        const dead = connections.filter((c) => c.health?.status === "dead").length;
+        const planBlocked = connections.filter((c) => c.planBlocked).length;
+        const headline = `${connections.length} connected accounts${dead ? `, ${dead} cannot publish until fixed` : ""}${planBlocked ? `, ${planBlocked} not on the current plan` : ""}:`;
+        return { content: [{ type: "text", text: `${headline}\n\n${summary}\n\nFull data:\n${JSON.stringify(connections, null, 2)}` }] };
     });
     server.tool("list_account_groups", "List account groups the user has set up in PlanPost (e.g. 'Polish Pages', 'English Pages'). Each group bundles social connections so you can target multiple accounts in one create_post call. Returns id, name, connectionCount, isDefault, and the underlying connections.", {}, async () => {
         const data = await api("/account-groups");
@@ -837,23 +1002,30 @@ function readBody(req) {
  * Remote/streamable-HTTP mode: `planpost-mcp --http [--port 3020]`.
  *
  * Stateless — every POST /mcp builds a fresh server + transport, and the
- * caller's `Authorization: Bearer pk_...` key is scoped to that request via
- * AsyncLocalStorage. That makes one hosted instance safely multi-tenant:
- * whoever holds a PlanPost API key can point any HTTP-capable MCP client
- * (e.g. `claude mcp add --transport http planpost https://host/mcp --header
- * "Authorization: Bearer pk_..."`) at it without local installs.
+ * caller's credential is scoped to that request via AsyncLocalStorage. That
+ * makes one hosted instance safely multi-tenant.
+ *
+ * Two ways to authenticate:
+ *  - `Authorization: Bearer pk_...` — a PlanPost API key, always accepted
+ *    (e.g. `claude mcp add --transport http planpost https://host/mcp
+ *    --header "Authorization: Bearer pk_..."`).
+ *  - OAuth, when configured (see oauth.ts): a request without credentials is
+ *    answered 401 with a pointer to the protected-resource metadata, the
+ *    client signs the user in at planpo.st, and comes back with a token.
  */
 async function startHttp(port, host) {
+    const oauth = loadOAuthSettings(process.env, BASE_URL);
+    const verifier = oauth ? new AccessTokenVerifier(oauth) : null;
     const httpServer = createHttpServer(async (req, res) => {
         // An API host must never rank: Google indexed the bare /mcp 405 JSON as a
         // page under the brand. The header, not robots.txt, is the fix on purpose:
         // a crawler has to be able to fetch the URL to see the noindex, so
         // robots.txt below allows crawling and this header does the de-indexing.
         res.setHeader("X-Robots-Tag", "noindex, nofollow");
-        const fail = (status, message) => {
+        const fail = (status, message, headers = {}) => {
             // charset is load-bearing: without it, any non-ASCII byte in a message
             // renders as mojibake in browsers that assume latin-1 for JSON.
-            res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+            res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", ...headers });
             res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }));
         };
         try {
@@ -876,6 +1048,28 @@ async function startHttp(port, host) {
                 res.end();
                 return;
             }
+            if (url.pathname === "/.well-known/openai-apps-challenge" && process.env.OPENAI_APPS_CHALLENGE) {
+                // Domain verification for the ChatGPT plugin directory: OpenAI issues
+                // a token at submission time and fetches it from here as plain text.
+                res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+                res.end(process.env.OPENAI_APPS_CHALLENGE);
+                return;
+            }
+            if (oauth && url.pathname.startsWith("/.well-known/oauth-protected-resource")) {
+                // Served at both the path-suffixed and the root well-known URL:
+                // clients try them in that order when the 401 challenge is missing.
+                const suffix = url.pathname.slice("/.well-known/oauth-protected-resource".length);
+                if (suffix !== "" && suffix !== oauth.resourceUrl.pathname) {
+                    return fail(404, "Not found. The MCP endpoint is /mcp");
+                }
+                res.writeHead(200, {
+                    "Content-Type": "application/json; charset=utf-8",
+                    "Access-Control-Allow-Origin": "*",
+                    "Cache-Control": "public, max-age=3600",
+                });
+                res.end(JSON.stringify(protectedResourceMetadata(oauth)));
+                return;
+            }
             if (url.pathname !== "/mcp")
                 return fail(404, "Not found. The MCP endpoint is /mcp");
             if (req.method !== "POST") {
@@ -883,12 +1077,46 @@ async function startHttp(port, host) {
                 return fail(405, "Method not allowed. This stateless transport accepts POST only; setup guide at https://planpo.st/mcp");
             }
             const auth = req.headers.authorization || "";
-            const key = auth.startsWith("Bearer ") ? auth.slice(7) : "";
-            if (!key.startsWith("pk_")) {
+            const bearer = /^Bearer /i.test(auth) ? auth.slice(7).trim() : "";
+            let credential;
+            if (bearer.startsWith("pk_")) {
+                credential = { kind: "key", key: bearer };
+            }
+            else if (!oauth || !verifier) {
                 return fail(401, "Provide your PlanPost API key: Authorization: Bearer pk_...");
             }
+            else if (!bearer) {
+                // The challenge is what starts the OAuth flow in the client.
+                return fail(401, "Sign in to PlanPost to use this server, or send an API key: Authorization: Bearer pk_...", { "WWW-Authenticate": bearerChallenge(oauth) });
+            }
+            else {
+                try {
+                    const authInfo = await verifier.verify(bearer);
+                    // The transport hands this to tool handlers as `extra.authInfo`.
+                    req.auth = authInfo;
+                    credential = {
+                        kind: "grant",
+                        grantId: String(authInfo.extra?.grantId),
+                        serviceSecret: oauth.serviceSecret,
+                    };
+                }
+                catch (err) {
+                    if (err instanceof InvalidTokenError) {
+                        return fail(401, err.message, {
+                            "WWW-Authenticate": bearerChallenge(oauth, err.message),
+                        });
+                    }
+                    if (err instanceof IntrospectionUnavailableError) {
+                        // Not the client's fault: a 401 here would make it throw away a
+                        // good token and send the user through sign-in again.
+                        console.error("[planpost-mcp]", err.message);
+                        return fail(503, "PlanPost sign-in is temporarily unavailable. Try again shortly.");
+                    }
+                    throw err;
+                }
+            }
             const body = await readBody(req);
-            const server = buildServer();
+            const server = buildServer(credential.kind === "grant" ? OMITTED_FOR_SIGNED_IN_AGENTS : NO_TOOLS);
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined, // stateless
             });
@@ -897,7 +1125,7 @@ async function startHttp(port, host) {
                 server.close();
             });
             await server.connect(transport);
-            await requestApiKey.run(key, () => transport.handleRequest(req, res, body));
+            await requestCredential.run(credential, () => transport.handleRequest(req, res, body));
         }
         catch (err) {
             console.error("[planpost-mcp] request error:", err);
@@ -906,7 +1134,8 @@ async function startHttp(port, host) {
         }
     });
     httpServer.listen(port, host, () => {
-        console.log(`planpost-mcp listening on http://${host}:${port}/mcp (streamable HTTP, stateless)`);
+        console.log(`planpost-mcp listening on http://${host}:${port}/mcp (streamable HTTP, stateless; ` +
+            (oauth ? `OAuth via ${oauth.issuer} + API keys)` : "API keys only)"));
     });
 }
 async function main() {

package/dist/oauth.d.ts

@@ -0,0 +1,73 @@
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { OAuthProtectedResourceMetadata } from "@modelcontextprotocol/sdk/shared/auth.js";
+/**
+ * OAuth for the hosted (streamable HTTP) server, per the MCP authorization
+ * spec. This process is the OAuth *resource server*; the PlanPost API is the
+ * *authorization server* (it runs /oauth/authorize, /token, /register).
+ *
+ * What happens here:
+ *  - `/.well-known/oauth-protected-resource[/mcp]` tells clients where to
+ *    sign in (RFC 9728).
+ *  - A request with no or a bad token gets `401` + `WWW-Authenticate: Bearer
+ *    resource_metadata="…"`, which is how a client discovers that document.
+ *  - A `ppo_at_…` access token is validated by introspection (RFC 7662) and
+ *    must have been issued for THIS server (`aud`), per RFC 8707.
+ *
+ * The access token is never forwarded to the API ("token passthrough" is
+ * forbidden by the spec). Tool calls go upstream with this server's own
+ * service secret plus the id of the grant they act for; see `Credential`.
+ *
+ * OAuth is on only when all three env vars are set, so a self-hosted
+ * `planpost-mcp --http` keeps working with API keys alone.
+ */
+export interface OAuthSettings {
+    /** Public URL of this server's MCP endpoint, e.g. https://mcp.planpo.st/mcp */
+    resourceUrl: URL;
+    /** Authorization server issuer, e.g. https://api.planpo.st */
+    issuer: string;
+    /** Where to reach the API for introspection (usually the same host). */
+    apiUrl: string;
+    /** Shared with the API (its MCP_SERVICE_SECRET). */
+    serviceSecret: string;
+}
+export declare function loadOAuthSettings(env: NodeJS.ProcessEnv, apiUrl: string): OAuthSettings | null;
+/**
+ * How a request authenticates upstream: a user's own API key, or an OAuth
+ * grant this server vouches for with its service secret.
+ */
+export type Credential = {
+    kind: "key";
+    key: string;
+} | {
+    kind: "grant";
+    grantId: string;
+    serviceSecret: string;
+};
+export declare function upstreamHeaders(credential: Credential): Record<string, string>;
+/** RFC 9728 §3.1: the well-known path carries the resource's own path as a suffix. */
+export declare function resourceMetadataUrl(settings: OAuthSettings): string;
+export declare function protectedResourceMetadata(settings: OAuthSettings): OAuthProtectedResourceMetadata;
+/**
+ * The `WWW-Authenticate` value for a 401. No `scope`: the client then asks
+ * for the authorization server's `scopes_supported`, and the user narrows
+ * nothing by accident.
+ */
+export declare function bearerChallenge(settings: OAuthSettings, invalidTokenReason?: string): string;
+/** The token is not valid here: answer 401 with a challenge. */
+export declare class InvalidTokenError extends Error {
+}
+/** The authorization server could not be asked: answer 503, not 401. */
+export declare class IntrospectionUnavailableError extends Error {
+}
+export declare class AccessTokenVerifier {
+    private readonly settings;
+    private readonly fetchImpl;
+    private cache;
+    constructor(settings: OAuthSettings, fetchImpl?: typeof fetch);
+    /**
+     * Introspects the token and checks it was minted for this server. Results
+     * are cached briefly; revocation still bites at once, because the API looks
+     * the grant up again on every tool call.
+     */
+    verify(token: string): Promise<AuthInfo>;
+}

package/dist/oauth.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { checkResourceAllowed } from "@modelcontextprotocol/sdk/shared/auth-utils.js";
+export function loadOAuthSettings(env, apiUrl) {
+    const publicUrl = env.PLANPOST_MCP_PUBLIC_URL;
+    const serviceSecret = env.PLANPOST_MCP_SERVICE_SECRET;
+    if (!publicUrl || !serviceSecret)
+        return null;
+    if (serviceSecret.length < 32) {
+        throw new Error("PLANPOST_MCP_SERVICE_SECRET must be at least 32 characters");
+    }
+    return {
+        resourceUrl: new URL(publicUrl),
+        issuer: (env.PLANPOST_OAUTH_ISSUER || apiUrl).replace(/\/+$/, ""),
+        apiUrl: apiUrl.replace(/\/+$/, ""),
+        serviceSecret,
+    };
+}
+export function upstreamHeaders(credential) {
+    return credential.kind === "key"
+        ? { Authorization: `Bearer ${credential.key}` }
+        : {
+            "X-Planpost-Mcp-Secret": credential.serviceSecret,
+            "X-Planpost-OAuth-Grant": credential.grantId,
+        };
+}
+/** RFC 9728 §3.1: the well-known path carries the resource's own path as a suffix. */
+export function resourceMetadataUrl(settings) {
+    const { resourceUrl } = settings;
+    const suffix = resourceUrl.pathname === "/" ? "" : resourceUrl.pathname;
+    return new URL(`/.well-known/oauth-protected-resource${suffix}`, resourceUrl).href;
+}
+export function protectedResourceMetadata(settings) {
+    return {
+        resource: settings.resourceUrl.href,
+        authorization_servers: [settings.issuer],
+        bearer_methods_supported: ["header"],
+        resource_name: "PlanPost",
+        resource_documentation: "https://planpo.st/docs/agents",
+    };
+}
+/**
+ * The `WWW-Authenticate` value for a 401. No `scope`: the client then asks
+ * for the authorization server's `scopes_supported`, and the user narrows
+ * nothing by accident.
+ */
+export function bearerChallenge(settings, invalidTokenReason) {
+    const parts = invalidTokenReason
+        ? [`error="invalid_token"`, `error_description="${invalidTokenReason.replace(/["\\]/g, "")}"`]
+        : [];
+    parts.push(`resource_metadata="${resourceMetadataUrl(settings)}"`);
+    return `Bearer ${parts.join(", ")}`;
+}
+/** The token is not valid here: answer 401 with a challenge. */
+export class InvalidTokenError extends Error {
+}
+/** The authorization server could not be asked: answer 503, not 401. */
+export class IntrospectionUnavailableError extends Error {
+}
+const CACHE_TTL_MS = 30_000;
+const CACHE_MAX = 2_000;
+export class AccessTokenVerifier {
+    settings;
+    fetchImpl;
+    cache = new Map();
+    constructor(settings, fetchImpl = fetch) {
+        this.settings = settings;
+        this.fetchImpl = fetchImpl;
+    }
+    /**
+     * Introspects the token and checks it was minted for this server. Results
+     * are cached briefly; revocation still bites at once, because the API looks
+     * the grant up again on every tool call.
+     */
+    async verify(token) {
+        const cacheKey = createHash("sha256").update(token).digest("hex");
+        const now = Date.now();
+        const hit = this.cache.get(cacheKey);
+        if (hit && hit.until > now && (hit.info.expiresAt ?? 0) * 1000 > now)
+            return hit.info;
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.settings.apiUrl}/oauth/introspect`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Authorization: `Bearer ${this.settings.serviceSecret}`,
+                },
+                body: new URLSearchParams({ token }).toString(),
+            });
+        }
+        catch (err) {
+            throw new IntrospectionUnavailableError(`introspection request failed: ${String(err)}`);
+        }
+        if (!response.ok) {
+            throw new IntrospectionUnavailableError(`introspection returned HTTP ${response.status}`);
+        }
+        const data = (await response.json());
+        if (!data.active || !data.grant_id || typeof data.exp !== "number") {
+            this.cache.delete(cacheKey);
+            throw new InvalidTokenError("The access token is invalid, expired or revoked");
+        }
+        if (!data.aud ||
+            !checkResourceAllowed({
+                requestedResource: data.aud,
+                configuredResource: this.settings.resourceUrl,
+            })) {
+            throw new InvalidTokenError("The access token was not issued for this server");
+        }
+        const info = {
+            token,
+            clientId: data.client_id ?? "",
+            scopes: data.scope ? data.scope.split(" ") : [],
+            expiresAt: data.exp,
+            resource: this.settings.resourceUrl,
+            extra: { grantId: data.grant_id },
+        };
+        if (this.cache.size >= CACHE_MAX)
+            this.cache.clear();
+        this.cache.set(cacheKey, { info, until: now + CACHE_TTL_MS });
+        return info;
+    }
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "planpost-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "//mcpName": "Ownership marker for the official MCP Registry: must equal `name` in server.json, or `mcp-publisher publish` fails validation. Namespace is the GitHub account that owns this repo, verified with `mcp-publisher login github`.",
   "mcpName": "io.github.lukBB/planpost",
-  "description": "PlanPost MCP server: schedule and publish social posts to Instagram, TikTok, LinkedIn, X, Facebook, Threads and YouTube from Claude, Cursor, Codex or any MCP client; render video and carousels, read analytics and revenue.",
+  "description": "PlanPost MCP server, the agentic social scheduler with revenue attribution: schedule and publish posts to Instagram, TikTok, LinkedIn, X, Facebook, Threads and YouTube from Claude, Cursor, Codex or any MCP client, render video and carousels, and read revenue per post.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -22,11 +23,10 @@
   "homepage": "https://planpo.st/mcp",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lukBB/social-poster-v2.git",
-    "directory": "packages/mcp-server"
+    "url": "git+https://github.com/lukBB/planpost-mcp.git"
   },
   "bugs": {
-    "url": "https://planpo.st/support"
+    "url": "https://github.com/lukBB/planpost-mcp/issues"
   },
   "keywords": [
     "mcp",
@@ -55,6 +55,7 @@
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build",
+    "pretest": "npm run build",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
@@ -62,9 +63,9 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
     "@types/node": "^22.0.0",
     "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1"
+    "ajv-formats": "^3.0.1",
+    "typescript": "^5.7.0"
   }
 }

package/skills/planpost/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: planpost
+description: Draft, schedule and publish social media posts through PlanPost, the agentic social scheduler your AI agent can run, then check what went out and what worked. Use when the user wants to post, schedule, queue or bulk-plan content for Instagram, TikTok, LinkedIn, X (Twitter), Facebook, Threads or YouTube, check a post's status or a failed publish, or ask which posts drove clicks, signups or revenue. Requires the PlanPost MCP server (https://mcp.planpo.st/mcp).
+license: MIT
+metadata:
+  homepage: https://planpo.st/mcp
+---
+
+# PlanPost
+
+PlanPost schedules and publishes to seven social networks, reports what
+failed and why, and reads back analytics and revenue (revenue per post on the
+Pro plan). This skill is the operating manual for its
+MCP tools. Tool names below are the ones the server exposes; your client may
+prefix them (for example `mcp__planpost__create_post`).
+
+## Before anything else
+
+If no PlanPost tools are available, the server is not connected. Tell the user
+to add `https://mcp.planpo.st/mcp` as a remote MCP server (connector) in their
+agent and sign in when the browser opens. Details per client:
+https://planpo.st/docs. Do not ask the user to paste an API key into
+the chat.
+
+## The rules that prevent bad posts
+
+1. **Resolve targets, never guess them.** Call `list_account_groups` (named
+   sets such as "Agency clients") or `list_connections` and use the IDs they
+   return. If the user names a group or handle you cannot find, show what
+   exists and ask.
+2. **Draft unless told otherwise.** `create_post` with no `scheduledFor` saves
+   a draft. Schedule only when the user gave a time, and publish immediately
+   (`publish_post`) only when they said "now" in so many words.
+3. **Say the time back.** Pass `scheduledFor` as ISO 8601 plus the user's
+   `timezone`, and repeat the local time in your answer. If they gave no time
+   and want one, `suggest_schedule` or `get_best_times` picks it.
+4. **Approval is not a failure.** If the user turned on approval for this
+   connection, a post comes back `needs_approval`: it is waiting for them in
+   PlanPost under Posts, In review. Report that and stop; do not retry or
+   re-create it. `get_approval_status` tells you when it clears.
+5. **Read warnings.** Responses carry `warnings[]` (what will be truncated or
+   dropped at publish time) and sometimes `preflight.errors[]` (the post was
+   saved as a draft because it would fail). Fix what they name, then
+   `update_post`.
+6. **X (Twitter) takes no links.** No URL, bare domain or t.co in the post,
+   any thread segment, or the first comment. Put a link-free variant in
+   `platformContent.twitter`.
+7. **TikTok needs a visibility choice.** A scheduled or published TikTok post
+   must carry `platformSettings.tiktok.privacyLevel`. Ask the user if they
+   have not said.
+
+## Common jobs
+
+**Post one thing to several networks**
+
+1. `list_account_groups` → pick the group, or `list_connections` → pick IDs.
+2. `preview_post` with the text to see per-network length and media problems.
+3. `create_post` with `content`, `connectionIds`, optional
+   `platformContent` overrides and `scheduledFor`.
+4. Give the user the status and the `Open in PlanPost` link from the response.
+
+**Plan a week or a campaign**
+
+Use `bulk_create_posts` with one manifest instead of looping `create_post`.
+Give every post the same `campaign` so `list_posts` and `list_campaigns` can
+find them again. To fill the user's standing queue instead of picking times,
+read `get_posting_schedule` first.
+
+**Attach media**
+
+Reuse before uploading: `list_media` shows what is already in the library.
+For a new file, `upload_media` returns a presigned URL; upload to it, then
+pass the returned asset in `media`.
+
+Several images attached to one post publish as a carousel where the network
+supports one. For a Reel or Short, attach the video and set `postType: "reel"`
+or `"short"`.
+
+**Turn an article into posts**
+
+Read the article (open the URL the user gives you, or ask them to paste it) →
+write per-network variants (use `get_brand_voice_prompt` when a brand voice
+exists) → `create_post` as drafts.
+
+**A post failed**
+
+`get_post` → read `platformResults[]`: `errorClass`, `error`, `fix`.
+`retry_failed` re-queues only transient failures and never re-posts a network
+that already went out. Failures that need the user (reconnect an account,
+choose TikTok visibility) come back with the fix to relay.
+
+**What worked?**
+
+`get_analytics` for reach and engagement, `get_revenue_overview` for revenue,
+signups and clicks attributed to posts. Lead with the posts that earned
+money, not the ones with the most likes.
+
+## Limits to respect
+
+- Calls count against the user's monthly API allowance; prefer one
+  `bulk_create_posts` over many `create_post` calls, and do not poll a status
+  faster than every few seconds.
+- A tool that answers with a missing-permission error means the user did not
+  grant that scope. Say which capability is missing; do not look for a
+  workaround.
+- Connecting a new social account needs a human in a browser:
+  `get_connection_link` returns the link to send them.

package/skills/send-to-plan-post/SKILL.md

@@ -1,152 +0,0 @@
----
-name: send-to-plan-post
-description: Compose and route social posts through the user's PlanPost app. Resolves named account groups ("Polish Pages", "English Pages", "SaaS", "Personal", etc.) into PlanPost connection IDs and creates draft, scheduled, or immediately-published posts. MANDATORY TRIGGERS - "send to plan post", "/send-to-plan-post", "post to PlanPost", "publish via PlanPost", "save as draft on PlanPost", "post to my <group> pages", "post this to my <group> group", "draft on PlanPost", "schedule on PlanPost", "post to Polish Pages", "post to English Pages". Also trigger when the user pastes social copy and references any known group name. Requires the planpost-mcp server registered with PLANPOST_API_KEY.
----
-
-# send-to-plan-post
-
-## What this skill does
-
-Routes user-provided content to the right set of social accounts in PlanPost, using account groups as the primary targeting concept (with a fallback to individual handle targeting). Supports draft, scheduled, and immediate-publish modes. Handles image/video attachments via PlanPost's presigned S3 upload flow.
-
-## Required MCP tools (`planpost-mcp`)
-
-The user must have the `planpost-mcp` server installed and authenticated with `PLANPOST_API_KEY`. This skill calls:
-
-- `list_account_groups` — resolve a group name into its connections
-- `get_account_group` — fetch one group (by id, name, or default flag)
-- `list_connections` — fallback when targeting individual accounts
-- `upload_media` — presigned-URL upload for attached files
-- `create_post` — draft or scheduled creation
-- `publish_post` — immediate publish of a created post
-- (read-only) `list_posts`, `get_post` — for "show me what I just sent"
-
-The API key needs these permissions: `groups:read`, `connections:read`, `posts:read`, `posts:write`, `media:write`.
-
-If the MCP server is missing or the API key is unset, stop and tell the user how to install/configure it (see `packages/mcp-server/README.md`). Do not fall back to web scraping or computer-use clicking through the dashboard.
-
-## Flow
-
-### Step 1 — Parse the request
-
-From the user's message extract:
-
-- **Content** — the post body. Preserve the user's language exactly (Polish stays Polish, English stays English). Do not "improve" copy unless asked.
-- **Target** — one of: a group name ("Polish Pages"), a list of handles ("@triathlon_info_pl on IG"), or "default".
-- **Mode** — `draft` | `schedule` | `publish-now`. **Default to `draft` when ambiguous.** Only schedule or publish if the user explicitly asks for it.
-- **Schedule time** — if mode is `schedule`, an ISO datetime or natural phrase ("tomorrow 9am"). Resolve to ISO 8601 in the user's timezone before sending.
-- **Media** — any files attached in the chat or URLs the user pasted.
-- **Platform overrides** — per-platform variants (`platformContent`) or settings (`platformSettings`, e.g. `{ instagram: { isReel: true } }`) only if the user gave them explicitly.
-
-### Step 2 — Resolve targets
-
-- **Group by name** → call `list_account_groups`, do a case-insensitive exact-name match first; if no hit, try substring; if multiple match, ask the user to pick from the matches.
-- **Default group** → call `get_account_group` with `{ default: true }`.
-- **Specific handles** → call `list_connections`, filter by `provider` + `providerUsername` (lowercase compare, strip leading `@`).
-- **No target resolved** → stop, list every group the user has, ask which one.
-
-Capture the resolved `connectionIds[]` and the human-readable list (`provider @handle`) for the confirmation step.
-
-### Step 3 — Handle media
-
-For each attached file:
-
-1. Call `upload_media` with `{ filename, contentType, size }` to get a presigned PUT URL.
-2. PUT the file bytes.
-3. Capture the returned `{ id, type, url, key, filename, mimeType, size }` and append to a `media[]` array.
-
-For pasted URLs: fetch the bytes (respect link-safety rules — verify unfamiliar URLs with the user before fetching), then upload via the same flow. If a URL fails to fetch, ask the user to attach the file directly instead.
-
-### Step 4 — Compose and confirm
-
-Before any write that publishes publicly, show a confirmation block:
-
-```
-About to <draft | schedule | publish-now>:
-
-Group:     Polish Pages (4 accounts)
-  - facebook   @triathloninfopl
-  - instagram  @triathlon_info_pl
-  - threads    @triathlon_info_pl
-  - twitter    @triathlon_info_pl
-When:      <Now | 2026-05-19 09:00 Europe/Warsaw | Draft only>
-Content:   <body, truncated to ~200 chars with [...] if longer>
-Media:     <N items, names>
-Mode:      <publish-now | schedule | draft>
-
-Reply "go" to execute, or describe edits.
-```
-
-Rules:
-
-- **Draft**: a confirmation summary is shown but the skill may proceed without an explicit "go" if the user's instruction was already unambiguous. (Drafts are reversible.)
-- **Schedule**: require explicit "go".
-- **Publish-now**: require explicit "go". If 5+ accounts are targeted, require a second `"yes publish to all <N>"` confirmation.
-
-### Step 5 — Execute
-
-- Call `create_post` with `{ content, connectionIds, media, scheduledFor?, platformContent?, platformSettings?, timezone? }`.
-- If mode is `publish-now`: take the returned post id and call `publish_post`.
-- If mode is `schedule`: setting `scheduledFor` on `create_post` is enough; do not call `publish_post`.
-- If mode is `draft`: do not set `scheduledFor` and do not call `publish_post`.
-
-### Step 6 — Report back
-
-Format the result tightly:
-
-```
-Created post <id> as <status>.
-
-Targets:
-  - facebook   @triathloninfopl    queued
-  - instagram  @triathlon_info_pl  queued
-  - threads    @triathlon_info_pl  failed (token expired — re-auth at planpo.st)
-
-Dashboard: https://planpo.st/posts/<id>
-```
-
-Surface per-platform results (`platformResults[]`) from the API response. **Do not swallow partial failures.**
-
-## Examples
-
-### Draft to a group
-
-> "draft a post on PlanPost to my English Pages — 'New SoloOperatorStack post on building Claude skills over PlanPost. Link in bio.'"
-
-→ Resolve "English Pages" via `list_account_groups`. Show confirmation. Call `create_post` with no `scheduledFor`. Report id.
-
-### Publish-now to specific handles
-
-> "post to @triathlon_info_pl on Instagram and Facebook only: 'Trening interwałowy 6x800 — kto dziś biegnie?'"
-
-→ Skip group resolution. Filter `list_connections` to those two. Confirm (4+ rule does not apply). `create_post` → `publish_post`.
-
-### Schedule with image
-
-> User drops `cover.jpg`: "schedule this for tomorrow 9am to Polish Pages: 'Lista startów na weekend ...'"
-
-→ `upload_media` for the image. Resolve Polish Pages via `get_account_group`. Resolve "tomorrow 9am" to ISO in `Europe/Warsaw`. Confirm. `create_post` with `scheduledFor`.
-
-### Discovery
-
-> "what groups do I have on PlanPost?"
-
-→ `list_account_groups`. Format as table: name, account count, default flag, color.
-
-## Safety rules
-
-- Never publish without explicit "go" / "publish" / "yes" from the user.
-- Never invent a group name — if the user names a group that doesn't exist, list what does exist and ask.
-- Never silently drop a failed-per-account result — always surface it in the final report.
-- Preserve the user's language and tone in the post body. Do not paraphrase.
-- For pasted URLs, follow link-safety rules: confirm unfamiliar URLs with the user before fetching their contents.
-
-## Failure modes and how to handle them
-
-- **API key missing** → "Set `PLANPOST_API_KEY` in your MCP config. See `packages/mcp-server/README.md`."
-- **`groups:read` permission missing** → "Your API key doesn't have the `groups:read` permission. Regenerate it at planpo.st/settings/api-keys with that scope checked, or pass connection IDs directly via `list_connections`."
-- **Group not found** → "I don't see a group called 'X'. You have: <list>. Want me to use one of these?"
-- **Ambiguous group name (HTTP 300)** → list the candidates returned by the API, ask the user to pick by id.
-- **Connection inactive (token expired)** → call this out before composing; suggest re-auth in the dashboard.
-- **Upload fails** → retry once, then ask the user to attach again or paste a different URL.
-- **Backend 5xx on `create_post`** → do not retry automatically. Confirm with the user first to avoid duplicate posts.