planpost-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukasz Blachura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# 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.
+
+## Quick start
+
+### 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.
+
+> API/MCP access is included in every paid plan — Creator: 1,000 calls/month, Pro: 10,000 calls/month. Keys are scoped: a key with only `posts:read` cannot publish.
+
+### 2. Add the server to your agent
+
+**Claude Code:**
+
+```bash
+claude mcp add planpost -e PLANPOST_API_KEY=pk_live_xxx -- npx -y planpost-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "planpost": {
+      "command": "npx",
+      "args": ["-y", "planpost-mcp"],
+      "env": { "PLANPOST_API_KEY": "pk_live_xxx" }
+    }
+  }
+}
+```
+
+**Any other MCP client:** run `npx -y planpost-mcp` over stdio with the `PLANPOST_API_KEY` environment variable set.
+
+### Remote (HTTP) mode
+
+The server can also run as a shared, multi-tenant HTTP endpoint — no local install for users, each request authenticated by its own key:
+
+```bash
+npx -y planpost-mcp --http --port 3020     # exposes POST /mcp (+ /health)
+```
+
+Connect from any HTTP-capable MCP client, e.g.:
+
+```bash
+claude mcp add --transport http planpost https://mcp.yourhost.com/mcp \
+  --header "Authorization: Bearer pk_live_xxx"
+```
+
+The transport is stateless (streamable HTTP); the `Authorization: Bearer pk_...` header is required on every request and scoped per request, so one hosted instance serves many users safely. Put it behind HTTPS (reverse proxy) in production.
+
+### 3. Talk to it
+
+> "Schedule this post to my Polish Pages group for tomorrow 9:00: …"
+>
+> "Make a quote video from this testimonial and publish it as a reel."
+>
+> "Pull the latest posts from my WordPress blog and draft a LinkedIn carousel from the newest one."
+>
+> "How much revenue did my posts drive last 30 days?"
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `PLANPOST_API_KEY` | ✅ | API key from Settings → API Keys (`pk_live_…`) |
+| `PLANPOST_API_URL` | — | API base URL (default `https://api.planpo.st`) |
+
+## Tools
+
+### Posts & publishing
+
+| Tool | Required permission | Description |
+|---|---|---|
+| `list_posts` | `posts:read` | List posts, filter by status/platform |
+| `get_post` | `posts:read` | Fetch one post |
+| `create_post` | `posts:write` | Create a draft or scheduled post (per-platform content/settings/media, UTM overrides, timezone) |
+| `update_post` | `posts:write` | Update a draft/scheduled post |
+| `delete_post` | `posts:write` | Delete a post |
+| `publish_post` | `posts:write` | Publish immediately |
+| `upload_media` | `media:write` | Get a presigned URL to upload an image/video |
+| `repurpose_content` | `repurpose:write` | Save repurposed content as draft posts |
+
+### Accounts
+
+| Tool | Required permission | Description |
+|---|---|---|
+| `list_connections` | `connections:read` | Connected social accounts |
+| `list_account_groups` | `groups:read` | Named account groups (e.g. "Polish Pages") |
+| `get_account_group` | `groups:read` | Resolve a group by id/name/default → connection IDs |
+
+Connecting a new social account requires OAuth in the dashboard — agents can target any account that's already connected.
+
+### Video & carousels
+
+| Tool | Required permission | Description |
+|---|---|---|
+| `list_video_templates` | `videos:read` | Browse video templates and their editable fields |
+| `create_video` | `videos:write` | Submit a render job from a template |
+| `get_video_status` | `videos:read` | Poll a render; completed renders return download URLs |
+| `generate_carousel` | `carousels:write` | Decompose long-form content into carousel slide text |
+| `list_carousel_styles` | `carousels:read` | Template families, 40-palette library, formats, font pairings |
+| `render_carousel` | `carousels:write` | Render slides into branded PNGs in the media library |
+| `get_carousel_render` | `carousels:read` | Poll a render; completed renders return post-ready media assets |
+| `list_brand_kits` | `brand-kits:read` | Saved brand kits (palette, fonts, logo, handle) for `render_carousel` |
+
+### Content sources
+
+| Tool | Required permission | Description |
+|---|---|---|
+| `list_content_sources` | `content-sources:read` | List WordPress/RSS sources |
+| `add_content_source` | `content-sources:write` | Connect a WordPress site or RSS feed |
+| `delete_content_source` | `content-sources:write` | Remove a source |
+| `fetch_source_content` | `content-sources:write` | Import the latest content now |
+| `list_imported_content` | `content-sources:read` | List imported content for repurposing |
+
+### Analytics & revenue
+
+| Tool | Required permission | Description |
+|---|---|---|
+| `get_analytics` | `analytics:read` | Post performance (impressions, likes, comments, shares) |
+| `get_revenue_overview` | `revenue:read` | Revenue totals + trend; optionally recent transactions and Stripe/RevenueCat MRR |
+
+Revenue data is read-only over the API; connecting Stripe/RevenueCat/Shopify happens in the dashboard (Settings → Revenue).
+
+## A typical agent workflow
+
+1. `get_account_group` (`default: true`) → connection IDs
+2. `list_video_templates` → pick a template → `create_video` → poll `get_video_status`
+3. `upload_media` (or use the render URL) → `create_post` with `scheduledFor`
+4. Later: `get_analytics` and `get_revenue_overview` to report results
+
+Or, for a branded carousel post end-to-end:
+
+1. `generate_carousel` (long-form content → slide text)
+2. `list_carousel_styles` / `list_brand_kits` → pick a family + palette or kit
+3. `render_carousel` → poll `get_carousel_render` → completed `assets`
+4. `create_post` with those assets as `media` (they're already attachment-shaped)
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc → dist/
+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.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,875 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer as createHttpServer } from "node:http";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createRequire } from "node:module";
+import { z } from "zod";
+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,
+// and dist/index.js always sits one level below it. Hardcoding it here meant
+// 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) {
+        throw new Error("No PlanPost API key: set PLANPOST_API_KEY (stdio) or send Authorization: Bearer pk_... (http)");
+    }
+    return key;
+}
+// ─── API Client ───
+async function api(path, options = {}) {
+    const url = `${BASE_URL}/api/public/v1${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${resolveApiKey()}`,
+            ...options.headers,
+        },
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        const msg = data?.error?.message || data?.message || `API error ${res.status}`;
+        throw new Error(msg);
+    }
+    return data;
+}
+/**
+ * Renders the API's advisory `warnings[]` as a readable block. These never
+ * block a write — they flag what will happen at publish time (truncation,
+ * dropped media, a flag that lost to postType) so the caller can fix it now.
+ */
+function formatWarnings(warnings) {
+    if (!Array.isArray(warnings) || warnings.length === 0)
+        return "";
+    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 dashboard deep links returned alongside a created/updated post. */
+function formatLinks(links) {
+    if (!links || typeof links !== "object")
+        return "";
+    const { edit, view } = links;
+    if (!edit && !view)
+        return "";
+    return `\n\nOpen in PlanPost:${edit ? `\n  Edit: ${edit}` : ""}${view ? `\n  View: ${view}` : ""}`;
+}
+// ─── MCP Server ───
+// Tool registration is a function so HTTP mode can build a fresh server per
+// request (stateless transport); stdio builds one at startup.
+function buildServer() {
+    const server = new McpServer(SERVER_INFO);
+    registerTools(server);
+    return server;
+}
+// ─── Tools ───
+function registerTools(server) {
+    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"),
+        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'"),
+        postType: z.enum(["post", "reel", "short", "story", "thread"]).optional().describe("Filter by post type"),
+        search: z.string().optional().describe("Free-text search across content, thread segments and label"),
+        sort: z.enum(["newest", "oldest", "scheduled"]).optional().describe("Sort order: newest (default), oldest, or scheduled (soonest scheduled first)"),
+        page: z.number().optional().describe("Page number (default: 1)"),
+        limit: z.number().optional().describe("Posts per page (default: 20, max: 100)"),
+    }, async ({ status, platform, campaign, label, postType, search, sort, page, limit }) => {
+        const params = new URLSearchParams();
+        if (status)
+            params.set("status", status);
+        if (platform)
+            params.set("platform", platform);
+        if (campaign)
+            params.set("campaign", campaign);
+        if (label)
+            params.set("label", label);
+        if (postType)
+            params.set("postType", postType);
+        if (search)
+            params.set("search", search);
+        if (sort)
+            params.set("sort", sort);
+        if (page)
+            params.set("page", String(page));
+        if (limit)
+            params.set("limit", String(limit));
+        const data = await api(`/posts?${params}`);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("get_post", "Get details of a specific post by ID.", {
+        id: z.string().describe("Post ID"),
+    }, async ({ id }) => {
+        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.", {
+        content: z.string().describe("Post text content"),
+        connectionIds: z.array(z.string()).describe("Array of social connection IDs to post to. Use list_connections or list_account_groups to find IDs."),
+        platformContent: z.record(z.string(), z.string()).optional().describe("Per-platform content overrides, e.g. { twitter: 'shorter version', linkedin: 'longer version' }"),
+        platformSettings: z.record(z.string(), z.any()).optional().describe("Per-platform settings, e.g. { instagram: { isReel: true }, youtube: { title: '...', visibility: 'public' } }"),
+        postType: z.enum(["post", "reel", "short", "story", "thread"]).optional().describe("Explicit post type (clearer than platformSettings flags, and takes precedence over them). 'reel' needs Instagram/Facebook; 'short' needs YouTube/Instagram/TikTok/Facebook; 'story' needs Instagram/Facebook; 'thread' is X/Twitter-only and requires threadSegments. Defaults to 'post', or is inferred from platformSettings flags (e.g. { instagram: { isReel: true } } → reel). NOTE: a carousel is NOT a postType — attach media with type 'carousel' or use generate_carousel/render_carousel."),
+        threadSegments: z.array(z.string()).optional().describe("Ordered tweet segments for a thread (only used when postType='thread', X/Twitter-only). 2–25 segments, each 1–280 characters."),
+        label: z.string().optional().describe("Internal working name shown in the PlanPost dashboard list, e.g. 'Garmin CIRQA - IG Carousel'. Never published to any platform — it just makes a campaign's drafts tellable apart. Highly recommended when creating several posts at once."),
+        campaign: z.string().optional().describe("Campaign tag, e.g. 'garmin-cirqa-2026' (slugified automatically). Sets utm.campaign and derives a utm.content token from the format (e.g. 'ig-carousel', 'fb-static'). Group/filter/bulk-delete by this with list_campaigns, list_posts({campaign}) and delete_posts({campaign})."),
+        schedule: z.string().optional().describe("Natural-language schedule, easier and safer than hand-building ISO: 'now', 'draft', 'today 20:30 Europe/Warsaw', 'tomorrow 07:00', 'in 2 hours', 'next week'. Takes precedence over scheduledFor. A timezone may be appended to wall-clock forms; otherwise `timezone` (or UTC) applies."),
+        scheduledFor: z.string().optional().describe("ISO 8601 datetime to schedule the post (e.g. '2026-04-10T14:00:00Z'). Omit for draft. Prefer `schedule` for anything other than an exact instant."),
+        timezone: z.string().optional().describe("Timezone for scheduling (default: UTC)"),
+        media: z.array(z.object({
+            id: z.string(),
+            type: z.enum(["image", "video"]),
+            url: z.string(),
+            key: z.string(),
+            filename: z.string(),
+            mimeType: z.string(),
+            size: z.number(),
+        })).optional().describe("Media attachments shared across every platform (use upload_media first to get URLs). Override per-platform via platformMedia."),
+        platformMedia: z.record(z.string(), z.array(z.object({
+            id: z.string(),
+            type: z.enum(["image", "video"]),
+            url: z.string(),
+            key: z.string(),
+            filename: z.string(),
+            mimeType: z.string(),
+            size: z.number(),
+        }))).optional().describe("Per-platform media overrides, e.g. { instagram: [<image>], twitter: [] } — instagram gets the image, twitter publishes with no media. Absent keys fall back to the shared `media` array. Empty `[]` is a meaningful 'no media on this platform'."),
+        utm: z.object({
+            source: z.string().optional(),
+            medium: z.string().optional(),
+            campaign: z.string().optional(),
+            content: z.string().optional(),
+        }).optional().describe("Per-post UTM tag overrides applied when attribution mode is utm. Each field can include the `{platform}` placeholder (substituted per platform at publish time). Letters, digits, `-`, `_`, `.` only. Any field omitted falls back to the user's UTM defaults configured in Settings, then to a hardcoded fallback. Example: { campaign: \"summer-2026\", content: \"weekly-tips\" }."),
+    }, async ({ content, connectionIds, platformContent, platformSettings, postType, threadSegments, label, campaign, schedule, scheduledFor, timezone, media, platformMedia, utm }) => {
+        const body = { content, connectionIds };
+        if (platformContent)
+            body.platformContent = platformContent;
+        if (platformSettings)
+            body.platformSettings = platformSettings;
+        if (postType)
+            body.postType = postType;
+        if (threadSegments)
+            body.threadSegments = threadSegments;
+        if (label)
+            body.label = label;
+        if (campaign)
+            body.campaign = campaign;
+        if (schedule)
+            body.schedule = schedule;
+        if (scheduledFor)
+            body.scheduledFor = scheduledFor;
+        if (timezone)
+            body.timezone = timezone;
+        if (media)
+            body.media = media;
+        if (platformMedia)
+            body.platformMedia = platformMedia;
+        if (utm)
+            body.utm = utm;
+        const data = await api("/posts", { method: "POST", body: JSON.stringify(body) });
+        const post = data.data;
+        const status = post.status === "published" || post.status === "processing"
+            ? "Publishing now"
+            : 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)}` }] };
+    });
+    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"),
+    }, async ({ id }) => {
+        const data = await api(`/posts/${id}/preview`);
+        const p = data.data;
+        const blocks = (p.platforms ?? []).map((pl) => {
+            const limit = pl.characterLimit ? `${pl.characterCount}/${pl.characterLimit}${pl.withinLimit ? "" : "  ⚠️ OVER LIMIT"}` : `${pl.characterCount} chars`;
+            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(", ")}` : "";
+            return [
+                `── ${pl.platform.toUpperCase()} ─────────────`,
+                `  text (${pl.contentSource}): ${limit}${pl.linksClickable ? "" : "  [links NOT clickable]"}`,
+                `  media (${pl.mediaSource}): ${media}`,
+                pl.threadSegments ? `  thread: ${pl.threadSegments.length} segment(s)` : "",
+                warn,
+                "",
+                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}` : ""}`;
+        return {
+            content: [{
+                    type: "text",
+                    text: `${header}\n\n${blocks.join("\n\n")}${formatLinks(data.links)}\n\n${JSON.stringify(p, null, 2)}`,
+                }],
+        };
+    });
+    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.", {
+        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 }) => {
+        const body = { posts };
+        if (defaults)
+            body.defaults = defaults;
+        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} FAILED  ${r.error}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Created ${d.created}/${d.total} post(s)${d.failed ? `, ${d.failed} failed` : ""}.\n${lines.join("\n")}\n\n${JSON.stringify(d, null, 2)}`,
+                }],
+        };
+    });
+    server.tool("list_campaigns", "List campaign bundles — every campaign tag in use, with post counts by status, the platforms involved and the next scheduled time. Use this to see what a campaign contains before editing or deleting it.", {}, async () => {
+        const data = await api("/posts/campaigns");
+        const rows = (data.data ?? []).map((c) => `  ${c.campaign}: ${c.total} post(s) [draft ${c.byStatus.draft}, scheduled ${c.byStatus.scheduled}, published ${c.byStatus.published}, failed ${c.byStatus.failed}] on ${c.platforms.join(", ") || "—"}`);
+        return { content: [{ type: "text", text: `${rows.length} campaign(s):\n${rows.join("\n")}\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("delete_posts", "Bulk-delete posts matching a filter — e.g. every draft in a campaign. SAFETY: a filter is required (it will never delete everything), published and processing posts are always excluded, and it runs as a DRY RUN unless confirm:true. Always call once without confirm to see what matches, show the user, then confirm.", {
+        campaign: z.string().optional().describe("Delete posts tagged with this campaign, e.g. 'garmin-cirqa-2026'"),
+        label: z.string().optional().describe("Delete posts whose internal label matches (case-insensitive substring)"),
+        ids: z.array(z.string()).optional().describe("Explicit post IDs to delete"),
+        status: z.enum(["draft", "scheduled", "failed", "cancelled", "needs_approval"]).optional().describe("Restrict to one status, e.g. 'draft'. Defaults to everything except published/processing."),
+        confirm: z.boolean().optional().describe("false/omitted = dry run listing what WOULD be deleted. true = actually delete. Always dry-run first."),
+    }, async ({ campaign, label, ids, status, confirm }) => {
+        const body = {};
+        if (campaign)
+            body.campaign = campaign;
+        if (label)
+            body.label = label;
+        if (ids)
+            body.ids = ids;
+        if (status)
+            body.status = status;
+        if (confirm)
+            body.confirm = true;
+        const data = await api("/posts/bulk-delete", { method: "POST", body: JSON.stringify(body) });
+        const d = data.data;
+        if (d.dryRun) {
+            const rows = (d.posts ?? []).map((p) => `  ${p.id} [${p.status}] ${p.label ?? ""} ${p.campaign ? `(${p.campaign})` : ""}`);
+            return { content: [{ type: "text", text: `DRY RUN — ${d.matched} post(s) would be deleted:\n${rows.join("\n")}\n\nRe-run with confirm:true to delete.` }] };
+        }
+        return { content: [{ type: "text", text: `Deleted ${d.deleted} of ${d.matched} matched post(s).` }] };
+    });
+    server.tool("list_media", "List media you already uploaded, so you can reuse an asset instead of uploading it again. Each item comes back already shaped for create_post's `media` array — pass it straight through.", {
+        type: z.enum(["image", "video"]).optional().describe("Filter by media type"),
+        search: z.string().optional().describe("Filter by filename (case-insensitive substring), e.g. 'cirqa'"),
+        page: z.number().optional().describe("Page number (default: 1)"),
+        limit: z.number().optional().describe("Items per page (default: 20, max: 100)"),
+    }, async ({ type, search, page, limit }) => {
+        const params = new URLSearchParams();
+        if (type)
+            params.set("type", type);
+        if (search)
+            params.set("search", search);
+        if (page)
+            params.set("page", String(page));
+        if (limit)
+            params.set("limit", String(limit));
+        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.", {
+        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 } })"),
+        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."),
+        campaign: z.string().nullable().optional().describe("Re-tag this post's campaign (sets utm.campaign). Pass null to clear."),
+        schedule: z.string().optional().describe("Natural-language reschedule: 'draft' (unschedule), 'today 20:30 Europe/Warsaw', 'tomorrow 07:00', 'in 2 hours', 'next week same time' (anchors on the post's current scheduled time). Use publish_post to publish immediately — 'now' is rejected here."),
+        media: z.array(z.object({
+            id: z.string(),
+            type: z.enum(["image", "video"]),
+            url: z.string(),
+            key: z.string(),
+            filename: z.string(),
+            mimeType: z.string(),
+            size: z.number(),
+        })).optional().describe("Replace the shared media array. Omit to leave existing media alone."),
+        platformMedia: z.record(z.string(), z.array(z.object({
+            id: z.string(),
+            type: z.enum(["image", "video"]),
+            url: z.string(),
+            key: z.string(),
+            filename: z.string(),
+            mimeType: z.string(),
+            size: z.number(),
+        }))).nullable().optional().describe("Per-platform media overrides. Pass `null` to clear all overrides (every platform uses the shared `media` array). Omit to leave overrides unchanged."),
+        utm: z.object({
+            source: z.string().optional(),
+            medium: z.string().optional(),
+            campaign: z.string().optional(),
+            content: z.string().optional(),
+        }).nullable().optional().describe("Per-post UTM overrides. Pass `null` to clear all overrides (use user defaults). Omit to leave alone."),
+        scheduledFor: z.string().optional().describe("New schedule time (ISO 8601), or empty string to unschedule"),
+        timezone: z.string().optional().describe("Timezone"),
+    }, async ({ id, content, connectionIds, platformContent, platformSettings, postType, threadSegments, label, campaign, schedule, media, platformMedia, utm, scheduledFor, timezone }) => {
+        const body = {};
+        if (content !== undefined)
+            body.content = content;
+        if (connectionIds !== undefined)
+            body.connectionIds = connectionIds;
+        if (platformContent !== undefined)
+            body.platformContent = platformContent;
+        if (platformSettings !== undefined)
+            body.platformSettings = platformSettings;
+        if (postType !== undefined)
+            body.postType = postType;
+        if (threadSegments !== undefined)
+            body.threadSegments = threadSegments;
+        if (label !== undefined)
+            body.label = label;
+        if (campaign !== undefined)
+            body.campaign = campaign;
+        if (schedule !== undefined)
+            body.schedule = schedule;
+        if (media !== undefined)
+            body.media = media;
+        if (platformMedia !== undefined)
+            body.platformMedia = platformMedia;
+        if (utm !== undefined)
+            body.utm = utm;
+        if (scheduledFor !== undefined)
+            body.scheduledFor = scheduledFor;
+        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)}` }] };
+    });
+    server.tool("delete_post", "Delete a post.", {
+        id: z.string().describe("Post ID to delete"),
+    }, async ({ id }) => {
+        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.", {
+        id: z.string().describe("Post ID to publish now"),
+    }, async ({ id }) => {
+        const data = await api(`/posts/${id}/publish`, { method: "POST" });
+        return { content: [{ type: "text", text: `Post is being published.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    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)}` }] };
+    });
+    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");
+        const groups = data.data;
+        if (!groups || groups.length === 0) {
+            return { content: [{ type: "text", text: "No account groups configured. Targets must be specific connectionIds (see list_connections)." }] };
+        }
+        const summary = groups.map((g) => `${g.isDefault ? "★ " : "  "}${g.name} (${g.connectionCount} accounts, id: ${g.id})`).join("\n");
+        return { content: [{ type: "text", text: `${groups.length} account groups:\n\n${summary}\n\nFull data:\n${JSON.stringify(groups, null, 2)}` }] };
+    });
+    server.tool("get_account_group", "Fetch one account group by id, name, or default flag. Returns the group's connectionIds[] so they can be passed straight to create_post. Name matching is case-insensitive (exact match preferred, substring fallback). If the name is ambiguous the server returns 300 with the candidates.", {
+        idOrName: z.string().optional().describe("Mongo ObjectId or group name (e.g. 'Polish Pages'). Omit when using default=true."),
+        default: z.boolean().optional().describe("When true, fetch the team's default group and ignore idOrName."),
+    }, async ({ idOrName, default: useDefault }) => {
+        if (!useDefault && !idOrName) {
+            throw new Error("Provide idOrName or set default=true.");
+        }
+        const path = useDefault ? "/account-groups/default" : `/account-groups/${encodeURIComponent(idOrName)}`;
+        const data = await api(path);
+        const group = data.data;
+        const connectionIds = (group.connections || []).map((c) => c.id);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Group: ${group.name}${group.isDefault ? " (default)" : ""}\nConnections (${group.connectionCount}): ${connectionIds.join(", ")}\n\nFull data:\n${JSON.stringify(group, null, 2)}`,
+                }],
+        };
+    });
+    server.tool("create_account_group", "Create a named account group (e.g. 'Polish Pages') bundling social connections, so future posts can target the whole set at once.", {
+        name: z.string().describe("Group name"),
+        description: z.string().optional(),
+        color: z.string().optional().describe("Display color (hex)"),
+        connectionIds: z.array(z.string()).optional().describe("Social connection IDs to include (see list_connections)"),
+        isDefault: z.boolean().optional().describe("Make this the team's default group"),
+    }, async ({ name, description, color, connectionIds, isDefault }) => {
+        const body = { name };
+        if (description)
+            body.description = description;
+        if (color)
+            body.color = color;
+        if (connectionIds)
+            body.connectionIds = connectionIds;
+        if (isDefault !== undefined)
+            body.isDefault = isDefault;
+        const data = await api("/account-groups", { method: "POST", body: JSON.stringify(body) });
+        return { content: [{ type: "text", text: `Group created.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("update_account_group", "Update an account group's name, description, color, default flag, or replace its full connection list.", {
+        id: z.string().describe("Group ID"),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        color: z.string().optional(),
+        isDefault: z.boolean().optional(),
+        connectionIds: z.array(z.string()).optional().describe("REPLACES the group's connections when provided"),
+    }, async ({ id, ...rest }) => {
+        const body = {};
+        for (const [k, v] of Object.entries(rest))
+            if (v !== undefined)
+                body[k] = v;
+        const data = await api(`/account-groups/${id}`, { method: "PATCH", body: JSON.stringify(body) });
+        return { content: [{ type: "text", text: `Group updated.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("delete_account_group", "Delete an account group (does not disconnect the underlying social accounts).", {
+        id: z.string().describe("Group ID"),
+    }, async ({ id }) => {
+        await api(`/account-groups/${id}`, { method: "DELETE" });
+        return { content: [{ type: "text", text: `Group ${id} deleted.` }] };
+    });
+    server.tool("add_connections_to_group", "Add social connections to an existing account group.", {
+        id: z.string().describe("Group ID"),
+        connectionIds: z.array(z.string()).describe("Connection IDs to add"),
+    }, async ({ id, connectionIds }) => {
+        const data = await api(`/account-groups/${id}/connections`, {
+            method: "POST",
+            body: JSON.stringify({ connectionIds }),
+        });
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("remove_connections_from_group", "Remove social connections from an account group.", {
+        id: z.string().describe("Group ID"),
+        connectionIds: z.array(z.string()).describe("Connection IDs to remove"),
+    }, async ({ id, connectionIds }) => {
+        const data = await api(`/account-groups/${id}/connections`, {
+            method: "DELETE",
+            body: JSON.stringify({ connectionIds }),
+        });
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("get_connection_link", "Generate a link the user can open in their browser to connect a new social account (OAuth needs a human — send them this link).", {
+        provider: z.enum(["instagram", "facebook", "twitter", "linkedin", "youtube", "tiktok", "threads"]).describe("Platform to connect"),
+    }, async ({ provider }) => {
+        const data = await api(`/connections/connect-link?provider=${provider}`);
+        return { content: [{ type: "text", text: `${data.data.url}\n\n${data.data.instructions}` }] };
+    });
+    server.tool("submit_for_approval", "Submit a post for human approval. Use this when your API key requires approval (or whenever you want a human to sign off before publishing). Returns an approve link and an approval ID to poll. On approval the post auto-schedules if it has a scheduledFor time.", {
+        postId: z.string().describe("Post ID to submit (create it first with create_post)"),
+        reviewerEmail: z.string().optional().describe("E-mail the approve link to a specific reviewer (e.g. the client). Omit to notify the team's approvers in-app."),
+        expiresInDays: z.number().optional().describe("Auto-expire the approval link after N days"),
+        supersede: z.boolean().optional().describe("If the post already has a pending approval, replace it (default false → returns 409)"),
+    }, async ({ postId, reviewerEmail, expiresInDays, supersede }) => {
+        const body = { postId, autoPublishOnApprove: true };
+        if (reviewerEmail)
+            body.reviewerEmail = reviewerEmail;
+        if (expiresInDays)
+            body.expiresInDays = expiresInDays;
+        if (supersede !== undefined)
+            body.supersede = supersede;
+        const data = await api("/approvals", { method: "POST", body: JSON.stringify(body) });
+        const d = data.data;
+        return { content: [{ type: "text", text: `Submitted for approval.\nApprove link: ${d.approveUrl}\nApproval ID: ${d.id} (poll with get_approval_status)\n\n${JSON.stringify(d, null, 2)}` }] };
+    });
+    server.tool("list_pending_approvals", "List posts waiting for approval (and their outcomes). Filter by status to build a review queue.", {
+        status: z.string().optional().describe("Comma-separated: pending, approved, rejected, changes_requested, expired, revoked. Default: all."),
+    }, async ({ status }) => {
+        const params = new URLSearchParams();
+        if (status)
+            params.set("status", status);
+        const data = await api(`/approvals?${params}`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("get_approval_status", "Check whether a human has decided on a submitted approval yet (pending / approved / rejected / changes_requested). Poll this after submit_for_approval.", {
+        approvalId: z.string().describe("Approval ID from submit_for_approval"),
+    }, async ({ approvalId }) => {
+        const data = await api(`/approvals/${approvalId}`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("get_analytics", "Get post performance analytics — impressions, likes, comments, shares.", {
+        platform: z.string().optional().describe("Filter by platform"),
+        startDate: z.string().optional().describe("Start date (ISO 8601)"),
+        endDate: z.string().optional().describe("End date (ISO 8601)"),
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Results per page"),
+    }, async ({ platform, startDate, endDate, page, limit }) => {
+        const params = new URLSearchParams();
+        if (platform)
+            params.set("platform", platform);
+        if (startDate)
+            params.set("startDate", startDate);
+        if (endDate)
+            params.set("endDate", endDate);
+        if (page)
+            params.set("page", String(page));
+        if (limit)
+            params.set("limit", String(limit));
+        const data = await api(`/analytics?${params}`);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("upload_media", "Get a presigned URL to upload an image or video for use in posts.", {
+        filename: z.string().describe("File name (e.g. 'photo.jpg')"),
+        contentType: z.string().describe("MIME type (e.g. 'image/jpeg', 'video/mp4')"),
+        size: z.number().describe("File size in bytes"),
+    }, async ({ filename, contentType, size }) => {
+        const data = await api("/media/upload-url", {
+            method: "POST",
+            body: JSON.stringify({ filename, contentType, size }),
+        });
+        return { content: [{ type: "text", text: `Upload URL generated. Upload your file with PUT to the URL below, then use the key/publicUrl in create_post media array.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("repurpose_content", "Save AI-repurposed content as draft posts. Provide an array of posts with content and target connections.", {
+        posts: z.array(z.object({
+            content: z.string().describe("Repurposed post content"),
+            connectionIds: z.array(z.string()).describe("Connection IDs to target"),
+        })).describe("Array of repurposed posts to save as drafts"),
+    }, async ({ posts }) => {
+        const data = await api("/repurpose", {
+            method: "POST",
+            body: JSON.stringify({ posts }),
+        });
+        return { content: [{ type: "text", text: `${data.data.savedCount} draft posts saved.\n\n${JSON.stringify(data.data.posts, null, 2)}` }] };
+    });
+    server.tool("list_video_templates", "List available video templates (quotes, hooks, listicles, stories, product showcases, testimonials, promos). Each template describes its editable fields — use them with create_video.", {
+        category: z.string().optional().describe("Filter by template category"),
+    }, async ({ category }) => {
+        const params = new URLSearchParams();
+        if (category)
+            params.set("category", category);
+        const data = await api(`/videos/templates?${params}`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("create_video", "Submit a video render job from a template. Returns a render ID — poll get_video_status until status is 'completed', then use the returned video URL as post media.", {
+        templateId: z.string().describe("Template ID from list_video_templates"),
+        fields: z.record(z.string(), z.any()).describe("Field values for the template, e.g. { quoteText: '...', backgroundColor: '#111' }. Field names come from the template definition."),
+        aspectRatio: z.string().optional().describe("Override aspect ratio (e.g. '9:16', '1:1'). Defaults to the template's ratio."),
+    }, async ({ templateId, fields, aspectRatio }) => {
+        const body = { templateId, fields };
+        if (aspectRatio)
+            body.aspectRatio = aspectRatio;
+        const data = await api("/videos/render", { method: "POST", body: JSON.stringify(body) });
+        return { content: [{ type: "text", text: `Render submitted. Poll get_video_status with this ID until completed.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("get_video_status", "Check the status of a video render job. Completed renders include presigned download URLs for the video and thumbnail (valid ~1 hour).", {
+        id: z.string().describe("Render ID from create_video"),
+    }, async ({ id }) => {
+        const data = await api(`/videos/render/${id}`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("generate_carousel", "Generate carousel slide TEXT (title/content/quote/CTA) from long-form content. Then call render_carousel to turn the slides into branded PNG images in the media library.", {
+        content: z.string().describe("Source content to decompose into slides (20–10,000 chars)"),
+        platform: z.enum(["instagram", "linkedin"]).optional().describe("Platform hint for tone/length (default instagram)"),
+        maxSlides: z.number().optional().describe("Max slides, 3–10 (default 5)"),
+        style: z.enum(["minimal", "bold", "professional", "playful"]).optional().describe("Copywriting tone hint"),
+        brandColors: z.object({
+            primary: z.string().optional(),
+            secondary: z.string().optional(),
+        }).optional().describe("Brand colors as hex strings"),
+    }, async ({ content, platform, maxSlides, style, brandColors }) => {
+        const body = { content };
+        if (platform)
+            body.platform = platform;
+        if (maxSlides)
+            body.maxSlides = maxSlides;
+        if (style)
+            body.style = style;
+        if (brandColors)
+            body.brandColors = brandColors;
+        const data = await api("/carousels/generate", { method: "POST", body: JSON.stringify(body) });
+        return { content: [{ type: "text", text: `Slides generated. Pass them to render_carousel (pick a family/palette via list_carousel_styles) to produce images.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("list_carousel_styles", "List the carousel design system: template families (with content-variant layouts), the 40-palette library (with resolved colors), output formats, font pairings, and slide caps. Use the ids with render_carousel.", {}, async () => {
+        const data = await api("/carousels/options");
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("render_carousel", "Render carousel slides into branded PNG images (server-side, pixel-perfect) saved to the media library. Returns a render ID — poll get_carousel_render until 'completed'. Slide 1 uses the family's cover layout, the last slide its CTA layout, middle slides cycle content variants.", {
+        slides: z.array(z.object({
+            headline: z.string().describe("Slide headline (≤500 chars)"),
+            body: z.string().describe("Slide body (≤2000 chars; may be empty)"),
+            type: z.enum(["title", "content", "quote", "cta"]).describe("Slide role — 'title' pins the cover layout, 'cta' the CTA layout"),
+            imageUrl: z.string().optional().describe("https image for this slide (used by photo layouts)"),
+        })).min(2).max(10).describe("2–10 slides, in order (from generate_carousel or hand-written)"),
+        family: z.string().describe("Template family id from list_carousel_styles (e.g. 'bold-announcement', 'tips-listicle', 'photo-story')"),
+        format: z.enum(["portrait", "square", "square-lg", "story"]).optional().describe("Output size: portrait 1080×1350 (default, IG/FB), square 1080×1080, square-lg 1200×1200 (LinkedIn), story 1080×1920 (TikTok photo mode)"),
+        paletteId: z.string().optional().describe("Palette id from list_carousel_styles (defaults to the family's suggested palette)"),
+        brandKitId: z.string().optional().describe("Brand kit id from list_brand_kits — applies its palette, fonts, logo, and handle (explicit values below still win; narrow with brandParts)"),
+        brandParts: z.object({
+            colors: z.boolean().optional().describe("Apply the kit's palette (default true)"),
+            fonts: z.boolean().optional().describe("Apply the kit's font pairing (default true)"),
+            logo: z.boolean().optional().describe("Apply the kit's logo (default true)"),
+            identity: z.boolean().optional().describe("Apply the kit's @handle / brand name (default true)"),
+        }).optional().describe("With brandKitId: which kit parts to apply. Omitted object/keys default to true (apply everything) — set a key to false to skip that part"),
+        fontPairingId: z.enum(["impact", "friendly", "editorial", "clean", "geometric"]).optional().describe("Font pairing (defaults to the family's)"),
+        fontSize: z.enum(["small", "medium", "large"]).optional().describe("Type scale (default medium)"),
+        numbering: z.boolean().optional().describe("Add an 'i/N' position chip to each slide"),
+        seamless: z.boolean().optional().describe("One wide mesh background sliced across all slides — swiping reveals a continuous panorama"),
+        seamlessSeed: z.number().optional().describe("Seed for the seamless mesh (same seed = same background)"),
+        handle: z.string().optional().describe("'@handle' meta text worked into covers and CTAs"),
+        logoUrl: z.string().optional().describe("https logo placed bottom-left on every slide"),
+        defaultImageUrl: z.string().optional().describe("Fallback https image for photo layouts when a slide has none"),
+    }, async ({ slides, family, format, paletteId, brandKitId, brandParts, fontPairingId, fontSize, numbering, seamless, seamlessSeed, handle, logoUrl, defaultImageUrl }) => {
+        const settings = {
+            version: 2,
+            format: format ?? "portrait",
+            family,
+            fontSize: fontSize ?? "medium",
+        };
+        if (paletteId)
+            settings.paletteId = paletteId;
+        if (brandKitId)
+            settings.brandKitId = brandKitId;
+        if (brandKitId && brandParts)
+            settings.brandParts = brandParts;
+        if (fontPairingId)
+            settings.fontPairingId = fontPairingId;
+        if (numbering !== undefined)
+            settings.numbering = numbering;
+        if (seamless)
+            settings.seamless = { enabled: true, ...(seamlessSeed !== undefined ? { seed: seamlessSeed } : {}) };
+        if (handle)
+            settings.handle = handle;
+        if (logoUrl)
+            settings.logoUrl = logoUrl;
+        if (defaultImageUrl)
+            settings.defaultImageUrl = defaultImageUrl;
+        const body = {
+            slides: slides.map((s, i) => ({ order: i, ...s })),
+            settings,
+        };
+        const data = await api("/carousels/render", { method: "POST", body: JSON.stringify(body) });
+        return { content: [{ type: "text", text: `Render submitted (~1-3s per slide). Poll get_carousel_render with this ID until completed.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("get_carousel_render", "Check a carousel render job. When completed, `assets` are full media attachments (id/type/url/key/filename/mimeType/size, in slide order) — pass them straight into create_post's `media` array to draft or schedule the carousel post.", {
+        id: z.string().describe("Render ID from render_carousel"),
+    }, async ({ id }) => {
+        const data = await api(`/carousels/render/${id}`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("list_brand_kits", "List saved brand kits (palette, font pairing, logo, handle). Use a kit's id as render_carousel's brandKitId for one-call branded output.", {}, async () => {
+        const data = await api("/brand-kits");
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("list_content_sources", "List connected content sources (WordPress sites, RSS feeds) used to import content for repurposing.", {}, async () => {
+        const data = await api("/content-sources");
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("add_content_source", "Connect a WordPress site or RSS feed as a content source. Imported posts can then be repurposed into social content.", {
+        type: z.enum(["wordpress", "rss"]).describe("Source type"),
+        name: z.string().describe("Display name for the source"),
+        url: z.string().describe("Site URL (WordPress base URL or RSS feed URL)"),
+        apiKey: z.string().optional().describe("Optional API key for protected WordPress sites"),
+        autoImport: z.boolean().optional().describe("Automatically import new content on the sync schedule"),
+        importFrequency: z.enum(["daily", "weekly"]).optional().describe("Auto-import frequency (default weekly)"),
+    }, async ({ type, name, url, apiKey, autoImport, importFrequency }) => {
+        const body = { type, name, url };
+        if (apiKey)
+            body.apiKey = apiKey;
+        if (autoImport !== undefined || importFrequency) {
+            body.settings = { autoImport: autoImport ?? false, importFrequency: importFrequency ?? "weekly" };
+        }
+        const data = await api("/content-sources", { method: "POST", body: JSON.stringify(body) });
+        return { content: [{ type: "text", text: `Content source connected.\n\n${JSON.stringify(data.data, null, 2)}` }] };
+    });
+    server.tool("delete_content_source", "Remove a content source.", {
+        id: z.string().describe("Content source ID"),
+    }, async ({ id }) => {
+        await api(`/content-sources/${id}`, { method: "DELETE" });
+        return { content: [{ type: "text", text: `Content source ${id} deleted.` }] };
+    });
+    server.tool("fetch_source_content", "Import the latest content from a source (e.g. new WordPress posts) right now, then list it with list_imported_content.", {
+        id: z.string().describe("Content source ID"),
+    }, async ({ id }) => {
+        const data = await api(`/content-sources/${id}/fetch`, { method: "POST" });
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("list_imported_content", "List content already imported from a source — useful as input for repurpose_content or create_post.", {
+        id: z.string().describe("Content source ID"),
+    }, async ({ id }) => {
+        const data = await api(`/content-sources/${id}/content`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("get_revenue_overview", "Get revenue analytics: totals and trend vs the previous period, recent transactions, and MRR metrics from connected providers (Stripe / RevenueCat / Shopify). Read-only.", {
+        days: z.number().optional().describe("Lookback window in days (default 30)"),
+        appId: z.string().optional().describe("Scope to a specific app's revenue connections"),
+        includeTransactions: z.boolean().optional().describe("Also fetch recent Stripe charges (default false)"),
+        includeMrr: z.boolean().optional().describe("Also fetch Stripe/RevenueCat MRR metrics (default false)"),
+    }, async ({ days, appId, includeTransactions, includeMrr }) => {
+        const params = new URLSearchParams();
+        if (days)
+            params.set("days", String(days));
+        if (appId)
+            params.set("appId", appId);
+        const overview = await api(`/revenue/overview?${params}`);
+        const result = { overview: overview.data };
+        if (includeTransactions) {
+            const txParams = new URLSearchParams();
+            if (appId)
+                txParams.set("appId", appId);
+            const tx = await api(`/revenue/transactions?${txParams}`).catch((e) => ({ data: { error: e.message } }));
+            result.transactions = tx.data;
+        }
+        if (includeMrr) {
+            const mrrParams = new URLSearchParams();
+            if (appId)
+                mrrParams.set("appId", appId);
+            const [stripe, rc] = await Promise.all([
+                api(`/revenue/stripe-metrics?${mrrParams}`).catch((e) => ({ data: { error: e.message } })),
+                api(`/revenue/rc-metrics?${mrrParams}`).catch((e) => ({ data: { error: e.message } })),
+            ]);
+            result.mrr = { stripe: stripe.data, revenuecat: rc.data };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("generate_image", "Generate an image with AI (DALL-E) for use in posts. Costs 1 AI credit. Returns the image URL — pass it through upload_media/create_post media flow.", {
+        prompt: z.string().describe("What to generate (≤4000 chars)"),
+        width: z.number().optional(),
+        height: z.number().optional(),
+        style: z.string().optional().describe("Style hint (e.g. 'photorealistic', 'illustration')"),
+    }, async ({ prompt, width, height, style }) => {
+        const body = { prompt };
+        if (width)
+            body.width = width;
+        if (height)
+            body.height = height;
+        if (style)
+            body.style = style;
+        const data = await api("/images/generate", { method: "POST", body: JSON.stringify(body) });
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("get_brand_voices", "List the user's brand voices (tone-of-voice profiles analyzed from their content).", {}, async () => {
+        const data = await api("/brand-voice");
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("get_brand_voice_prompt", "Get the ready-to-use system prompt for a brand voice — apply it when writing posts so the content matches the user's tone.", {
+        id: z.string().describe("Brand voice ID (see get_brand_voices)"),
+    }, async ({ id }) => {
+        const data = await api(`/brand-voice/${id}/prompt`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("get_best_times", "Get the best times to post per platform, based on the user's engagement history. Use before picking scheduledFor in create_post.", {
+        platform: z.string().optional().describe("Limit to one platform (e.g. 'instagram')"),
+    }, async ({ platform }) => {
+        const params = new URLSearchParams();
+        if (platform)
+            params.set("platform", platform);
+        const data = await api(`/smart-schedule/best-times?${params}`);
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+    server.tool("suggest_schedule", "Ask the smart scheduler to spread N posts across a date range at optimal times. Returns concrete timestamps for create_post.", {
+        numberOfPosts: z.number().describe("How many posts to schedule"),
+        platforms: z.array(z.string()).describe("Target platforms (e.g. ['instagram','linkedin'])"),
+        startDate: z.string().describe("Range start (ISO 8601)"),
+        endDate: z.string().describe("Range end (ISO 8601)"),
+    }, async ({ numberOfPosts, platforms, startDate, endDate }) => {
+        const data = await api("/smart-schedule/suggest", {
+            method: "POST",
+            body: JSON.stringify({ numberOfPosts, platforms, startDate, endDate }),
+        });
+        return { content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }] };
+    });
+}
+// ─── Start ───
+async function startStdio() {
+    if (!ENV_API_KEY) {
+        console.error("PLANPOST_API_KEY environment variable is required");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await buildServer().connect(transport);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let raw = "";
+        req.on("data", (chunk) => {
+            raw += chunk;
+            if (raw.length > 4 * 1024 * 1024)
+                reject(new Error("Body too large"));
+        });
+        req.on("end", () => {
+            try {
+                resolve(raw ? JSON.parse(raw) : undefined);
+            }
+            catch {
+                reject(new Error("Invalid JSON body"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+/**
+ * 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.
+ */
+async function startHttp(port) {
+    const httpServer = createHttpServer(async (req, res) => {
+        const fail = (status, message) => {
+            res.writeHead(status, { "Content-Type": "application/json" });
+            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.end(JSON.stringify({ status: "ok" }));
+                return;
+            }
+            if (url.pathname !== "/mcp")
+                return fail(404, "Not found — 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");
+            }
+            const auth = req.headers.authorization || "";
+            const key = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+            if (!key.startsWith("pk_")) {
+                return fail(401, "Provide your PlanPost API key: Authorization: Bearer pk_...");
+            }
+            const body = await readBody(req);
+            const server = buildServer();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // stateless
+            });
+            res.on("close", () => {
+                transport.close();
+                server.close();
+            });
+            await server.connect(transport);
+            await requestApiKey.run(key, () => transport.handleRequest(req, res, body));
+        }
+        catch (err) {
+            console.error("[planpost-mcp] request error:", err);
+            if (!res.headersSent)
+                fail(500, "Internal error");
+        }
+    });
+    httpServer.listen(port, () => {
+        console.log(`planpost-mcp listening on http://0.0.0.0:${port}/mcp (streamable HTTP, stateless)`);
+    });
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--http")) {
+        const portArg = args[args.indexOf("--port") + 1];
+        const port = Number(portArg) || Number(process.env.PORT) || 3020;
+        await startHttp(port);
+        return;
+    }
+    await startStdio();
+}
+main().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "planpost-mcp",
+  "version": "0.2.0",
+  "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",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "planpost-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://planpo.st",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lukBB/social-poster-v2.git",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai-agent",
+    "social-media",
+    "scheduling",
+    "planpost"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

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

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