planpost-mcp 0.2.1 → 0.4.0

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.2.1",
-  "//mcpName": "Ownership marker for the official MCP Registry: must equal `name` in server.json, or publishing fails validation.",
-  "mcpName": "st.planpo/mcp",
-  "description": "PlanPost MCP server — let Claude and other AI agents schedule posts, manage social media, create videos and carousels, and read analytics via the PlanPost public API",
+  "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, 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"
@@ -19,28 +20,52 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://planpo.st/agent",
+  "homepage": "https://planpo.st/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lukBB/planpost-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lukBB/planpost-mcp/issues"
+  },
   "keywords": [
     "mcp",
     "model-context-protocol",
-    "claude",
-    "ai-agent",
+    "mcp-server",
     "social-media",
+    "social-media-scheduling",
     "scheduling",
+    "instagram",
+    "tiktok",
+    "linkedin",
+    "twitter",
+    "facebook",
+    "threads",
+    "youtube",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini-cli",
+    "ai-agent",
     "planpost"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "pretest": "npm run build",
+    "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "ajv": "^8.17.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.