planpost-mcp 0.3.0 → 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.
@@ -15,7 +48,7 @@ In the PlanPost dashboard go to **Settings → API Keys → Create Key** and sel
 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.
 
 Replace `pk_live_xxx` with your key throughout.
 
@@ -131,11 +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
 ```
 
-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
 
@@ -151,12 +200,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 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
 
-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. 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 +217,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 |
@@ -268,11 +319,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 +334,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 +366,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")
@@ -72,12 +89,17 @@ function buildServer() {
     return server;
 }
 // ─── Tools ───
-function registerTools(server) {
+function registerTools(target) {
+    // 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) => 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,7 +141,7 @@ 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' } }"),
+        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; '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."),
         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."),
@@ -184,7 +206,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 +231,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 +252,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 +317,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 +380,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 +388,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 +475,21 @@ 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)}` : ""}`;
+        };
+        const summary = connections.map((c) => `${c.provider} — ${c.metadata?.accountName || c.providerUsername} (ID: ${c.id})${healthTag(c)}`).join("\n");
+        const dead = connections.filter((c) => c.health?.status === "dead").length;
+        const headline = `${connections.length} connected accounts${dead ? `, ${dead} cannot publish until fixed` : ""}:`;
+        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 +955,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 +1001,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,10 +1030,44 @@ 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 transport = new StreamableHTTPServerTransport({
@@ -897,7 +1078,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 +1087,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.0",
   "//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,114 @@
+---
+name: planpost
+description: Draft, schedule and publish social media posts through PlanPost, the agentic social scheduler with revenue attribution, and report what they earned. Use when the user wants to post, schedule, queue, repurpose or bulk-plan content for Instagram, TikTok, LinkedIn, X (Twitter), Facebook, Threads or YouTube, render a carousel or video for a post, 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 and attributes
+revenue back to individual posts. 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/agents. 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.** A post that comes back `needs_approval` is
+   waiting for the account owner in PlanPost. 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`.
+
+**Carousel**
+
+`generate_carousel` (slide text) → `list_carousel_styles` or
+`list_brand_kits` → `render_carousel` → poll `get_carousel_render` until
+`completed` → `create_post` with the returned `assets` as `media`.
+
+**Video**
+
+`list_video_templates` → `create_video` → poll `get_video_status` →
+`create_post` with `postType: "reel"` or `"short"`.
+
+**Turn an article into posts**
+
+`list_content_sources` → `fetch_source_content` → `list_imported_content` →
+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 render
+  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.
+- Image, video and carousel generation spend the user's AI credits or render
+  quota. Confirm before generating more than a couple.
+- Connecting a new social account needs a human in a browser:
+  `get_connection_link` returns the link to send them.