planpost-mcp 0.2.1 → 0.4.0

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,9 +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.", {
-        status: z.enum(["draft", "scheduled", "processing", "published", "failed", "cancelled"]).optional().describe("Filter by post status"),
+        // `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", "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'"),
@@ -112,11 +137,11 @@ function registerTools(server) {
         const data = await api(`/posts/${id}`);
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     });
-    server.tool("create_post", "Create a new social media post. Saves as draft or schedules it for a specific time.", {
+    server.tool("create_post", "Create a new social media post. Saves as draft or schedules it for a specific time. 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.", {
         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."),
@@ -181,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"),
@@ -193,7 +218,9 @@ function registerTools(server) {
             const media = pl.mediaCount === 0
                 ? `no media${pl.mediaSource === "override" ? " (text-only override)" : ""}`
                 : `${pl.mediaCount} ${pl.mediaCount === 1 ? "item" : "items"} (${pl.media.map((m) => m.filename ?? m.type).join(", ")})`;
-            const warn = pl.warnings?.length ? `\n  warnings: ${pl.warnings.map((w) => w.code).join(", ")}` : "";
+            const warn = pl.warnings?.length
+                ? `\n  warnings:\n${pl.warnings.map((w) => `    - [${w.code}] ${w.message}`).join("\n")}`
+                : "";
             return [
                 `── ${pl.platform.toUpperCase()} ─────────────`,
                 `  text (${pl.contentSource}): ${limit}${pl.linksClickable ? "" : "  [links NOT clickable]"}`,
@@ -204,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",
@@ -212,7 +242,7 @@ function registerTools(server) {
                 }],
         };
     });
-    server.tool("bulk_create_posts", "Create a whole campaign of posts from one manifest. Each entry accepts the same fields as create_post; `defaults` supplies values shared by every entry (campaign, connectionIds, timezone, ...) so you don't repeat them. Rows are independent — one bad row fails alone and the rest still get created. Max 50 per call. Returns a per-row result with ids, warnings and edit links.", {
+    server.tool("bulk_create_posts", "Create a whole campaign of posts from one manifest. Each entry accepts the same fields as create_post; `defaults` supplies values shared by every entry (campaign, connectionIds, timezone, ...) so you don't repeat them. Rows are independent — one bad row fails alone and the rest still get created. Max 50 per call. Returns a per-row result with ids, warnings and edit links. 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.", {
         posts: z.array(z.record(z.string(), z.any())).describe("Array of post payloads. Each accepts every create_post field: content, connectionIds, platformContent, platformSettings, postType, threadSegments, label, campaign, schedule/scheduledFor, media, platformMedia, utm."),
         defaults: z.record(z.string(), z.any()).optional().describe("Fields merged into every entry before its own values (which always win). Ideal for campaign, connectionIds and timezone."),
     }, async ({ posts, defaults }) => {
@@ -222,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: [{
@@ -280,12 +312,12 @@ function registerTools(server) {
         const data = await api(`/media?${params}`);
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     });
-    server.tool("update_post", "Update a draft or scheduled post.", {
+    server.tool("update_post", "Update a draft or scheduled post. 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 update"),
         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."),
@@ -348,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"),
@@ -356,7 +388,85 @@ function registerTools(server) {
         await api(`/posts/${id}`, { method: "DELETE" });
         return { content: [{ type: "text", text: `Post ${id} deleted.` }] };
     });
-    server.tool("publish_post", "Publish a draft or scheduled post immediately to all connected platforms.", {
+    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 }) => {
         const data = await api(`/posts/${id}/publish`, { method: "POST" });
@@ -365,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");
@@ -774,6 +897,31 @@ function registerTools(server) {
         });
         return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
     });
+    server.tool("get_posting_schedule", "Read the weekly posting queue schedule: the global schedule plus any per-group overrides. Slots are {day: 1-7 (Mon=1..Sun=7), time: 'HH:MM' 24h} in the user's timezone. Groups without an override inherit the global schedule. Needs the schedule:read permission.", {}, async () => {
+        const data = await api("/posting-queue/queues");
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("set_posting_schedule", "Replace the weekly posting queue slots for the global schedule or one account group (Pro feature; needs the schedule:write permission). Pass the FULL desired slot list — it replaces the existing one. An empty array on a group removes its override so it inherits the global schedule again.", {
+        groupId: z
+            .string()
+            .optional()
+            .describe("Account group id (from list_account_groups); omit for the global schedule"),
+        slots: z
+            .array(z.object({
+            day: z.number().int().min(1).max(7).describe("ISO weekday: 1=Monday .. 7=Sunday"),
+            time: z
+                .string()
+                .regex(/^([01]\d|2[0-3]):[0-5]\d$/)
+                .describe("24h time 'HH:MM' in the user's timezone, e.g. '09:30'"),
+        }))
+            .describe("The complete weekly slot list to store"),
+    }, async ({ groupId, slots }) => {
+        const data = await api(`/posting-queue/queues/${encodeURIComponent(groupId ?? "global")}`, {
+            method: "PUT",
+            body: JSON.stringify({ slots }),
+        });
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
 }
 // ─── Start ───
 async function startStdio() {
@@ -807,36 +955,119 @@ 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) => {
-        const fail = (status, message) => {
-            res.writeHead(status, { "Content-Type": "application/json" });
+        // 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, 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", ...headers });
             res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }));
         };
         try {
             const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
             if (url.pathname === "/health") {
-                res.writeHead(200, { "Content-Type": "application/json" });
+                res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
                 res.end(JSON.stringify({ status: "ok" }));
                 return;
             }
+            if (url.pathname === "/robots.txt") {
+                // Allow crawling so the X-Robots-Tag noindex is actually seen.
+                res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+                res.end("User-agent: *\nDisallow:\n");
+                return;
+            }
+            if (url.pathname === "/" && (req.method === "GET" || req.method === "HEAD")) {
+                // A human (or crawler) landing on the bare host gets the docs page
+                // instead of a JSON error.
+                res.writeHead(302, { Location: "https://planpo.st/mcp" });
+                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 — MCP endpoint is /mcp");
+                return fail(404, "Not found. The MCP endpoint is /mcp");
             if (req.method !== "POST") {
                 // Stateless mode: no SSE resumption stream, no sessions to delete.
-                return fail(405, "Method not allowed — stateless transport accepts POST only");
+                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({
@@ -847,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);
@@ -856,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>;
+}