@postsider/mcp 0.0.0-bootstrap.0

package/README.md

@@ -0,0 +1,190 @@
+# @postsider/mcp
+
+MCP (Model Context Protocol) server that gives AI agents selected access to a
+PostSider instance through its public API. Works with Claude Code, Claude
+Desktop, Codex, Cursor, and any MCP-compatible client. Talks to cloud
+(`api.postsider.com`) or a self-hosted instance, authenticated with an
+organization API key.
+
+PostSider is a shared operational calendar: the agent prepares and schedules
+work, and a human reviews what actually goes live.
+
+## Install
+
+### 1. Create an API key
+
+In PostSider, open **Settings -> API** and generate an organization API key.
+
+### 2. Connect your client
+
+Claude Code:
+
+```bash
+claude mcp add postsider -e POSTSIDER_API_KEY=your_api_key -- npx -y @postsider/mcp
+```
+
+Claude Desktop or any generic MCP client:
+
+```json
+{
+  "mcpServers": {
+    "postsider": {
+      "command": "npx",
+      "args": ["-y", "@postsider/mcp"],
+      "env": {
+        "POSTSIDER_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+### 3. Verify with a read-only prompt
+
+Ask your agent, and confirm it answers without changing anything:
+
+```text
+List my connected PostSider channels. Do not create or modify anything.
+```
+
+Then:
+
+```text
+Show my PostSider calendar for the next 14 days. Do not create or modify anything.
+```
+
+### 4. Only then prepare a draft
+
+```text
+Create one draft only for the selected channel. Show me the exact content first. Do not publish it.
+```
+
+### From source
+
+```bash
+pnpm --filter @postsider/mcp build
+```
+
+Then point your client at the built entrypoint:
+
+```json
+{
+  "mcpServers": {
+    "postsider": {
+      "command": "node",
+      "args": ["/absolute/path/to/apps/mcp/dist/index.js"],
+      "env": {
+        "POSTSIDER_API_KEY": "your_api_key",
+        "POSTSIDER_API_URL": "https://api.postsider.com"
+      }
+    }
+  }
+}
+```
+
+### Claude Code plugin
+
+The package directory is also a Claude Code plugin: `.claude-plugin/plugin.json`
+declares the API key as a secret user setting, `.mcp.json` starts this server at
+the pinned released version, and `skills/postsider-workflow/SKILL.md` teaches the
+read-first, draft-first workflow. The repository root is a plugin marketplace, so
+the plugin installs from the repository directly:
+
+```bash
+claude plugin marketplace add lumizone/postsider
+claude plugin install postsider@postsider
+```
+
+Installation stores the key outside the plugin: pass it at install time with
+`--config api_key=your_api_key`, or set it afterwards with
+`/plugin configure postsider@postsider` inside Claude Code. The key is never
+written into the plugin directory.
+
+## What the agent can do
+
+19 tools, all prefixed `postsider_`.
+
+### Read
+
+| Tool | Action |
+|------|--------|
+| `postsider_list_channels` | List connected social channels (ids, names, platforms). Call this first to get channel ids. |
+| `postsider_get_agency_overview` | Org-wide overview: clients, channels, queued, drafts, published, errors, pending approvals. |
+| `postsider_get_customer_report` | The same report scoped to one customer. |
+| `postsider_list_groups` | List channel groups. |
+| `postsider_find_slot` | Next free queue slot for a channel, in UTC. |
+| `postsider_list_posts` | List posts in a date range. |
+| `postsider_get_post` | Full post details, including the publish error if any. |
+| `postsider_get_post_missing_fields` | Per-channel validation problems, so they can be fixed before publishing. |
+| `postsider_get_post_analytics` | Analytics for a single post. |
+| `postsider_get_channel_analytics` | Account-level analytics for a channel. |
+| `postsider_get_notifications` | Recent notifications: publish failures, channels needing reconnection. |
+| `postsider_get_publishing_state` | Whether publishing is active or paused for the organization. |
+| `postsider_get_approval_status` | Approval status of a draft, including a reviewer note when rejected. |
+
+### Write
+
+| Tool | Action | Risk |
+|------|--------|------|
+| `postsider_create_post` | Create a post as a draft, a scheduled post, or an immediate publish across channels. | Creates content and can publish |
+| `postsider_update_post_status` | Move a post between `draft` and `schedule`. | Reversible |
+| `postsider_request_approval` | Send a draft into the human approval queue. | Reversible |
+| `postsider_upload_media_from_url` | Import media into the library from a public HTTPS URL. | Creates media |
+| `postsider_delete_post` | Permanently delete a post **and every other channel version of it** (one group). Read the post first. | Destructive |
+| `postsider_pause_publishing` | Emergency stop for the whole organization. Resuming is human-only. | Destructive |
+
+Every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint` and
+`openWorldHint` explicitly, so a client can tell a read from a kill switch.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `POSTSIDER_API_KEY` | yes | - | Organization API key (Settings -> API) |
+| `POSTSIDER_API_URL` | no | `https://api.postsider.com` | Instance base URL |
+
+`POSTSIDER_API_URL` must be HTTPS. Plain HTTP is accepted only on loopback
+(`localhost`, `127.0.0.1`, `[::1]`) for local development.
+
+For a self-hosted instance, point `POSTSIDER_API_URL` at where the public API is
+served. Behind the bundled nginx the API lives under `/api`, so use your domain
+plus `/api`, e.g. `https://social.example.com/api`. The server appends
+`/public/v1` to whatever you set.
+
+## Safety
+
+- The API key is read from the environment and sent only to the configured
+  PostSider API URL. It is never printed, logged, or included in an error.
+- Credentials embedded in `POSTSIDER_API_URL` are rejected.
+- Redirects are refused rather than followed: a redirect would move an
+  authenticated request off the configured origin, so the client fails with an
+  actionable message instead.
+- Requests time out after 30 seconds, and a failing response body is read up to
+  8 KB before being reported.
+- Tool arguments are validated locally, before any network call: ids must be
+  non-empty, dates must be real ISO 8601 dates (`2026-02-30` is refused, not sent
+  to the API), post status `draft` or `schedule`, and media imports require a
+  public HTTPS URL.
+- A missing API key exits 1 with an explanatory message on stderr. stdout carries
+  protocol frames only.
+
+## Development
+
+```bash
+pnpm --filter @postsider/mcp typecheck
+pnpm --filter @postsider/mcp typecheck:tests
+pnpm --filter @postsider/mcp test
+pnpm --filter @postsider/mcp build
+pnpm --filter @postsider/mcp version:gate
+pnpm --filter @postsider/mcp validate:registry
+pnpm --filter @postsider/mcp smoke:tarball
+claude plugin validate --strict apps/mcp
+```
+
+## Design
+
+This server is a thin wrapper over selected `/public/v1` REST API endpoints,
+authenticated with the raw API key. It has no dependency on the backend and
+pulls in only `@modelcontextprotocol/sdk` and `zod`, so it stays lean and easy to
+maintain. All tool registrations live in a single factory, so the stdio
+transport today and any future transport share one agent-facing surface.

package/dist/client.js

@@ -0,0 +1,268 @@
+/**
+ * The PostSider public API client: base URL validation, bounded requests, and
+ * actionable errors. `server.ts` builds one per request from the organization
+ * API key.
+ */
+/**
+ * Hosts allowed to use plain HTTP: loopback only, for local development and
+ * self-hosting. `URL.hostname` keeps the brackets on an IPv6 literal.
+ */
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+/**
+ * Validate `POSTSIDER_API_URL` and normalize it to the `<base>/public/v1` prefix.
+ *
+ * The public API is served over HTTPS. Plain HTTP is accepted only on loopback,
+ * and credentials embedded in the URL are always rejected. Every message names
+ * POSTSIDER_API_URL so the user knows which setting to fix, and none of them
+ * includes the rejected URL, so an embedded password can never reach a log.
+ */
+function resolveBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error('POSTSIDER_API_URL is not a valid absolute URL. Use e.g. https://api.postsider.com.');
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error('POSTSIDER_API_URL must not embed credentials (username or password). ' +
+            'Remove them and pass the key as POSTSIDER_API_KEY instead.');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error(`POSTSIDER_API_URL must use http or https, not "${parsed.protocol.replace(':', '')}". Use e.g. https://api.postsider.com.`);
+    }
+    if (parsed.protocol === 'http:' && !LOOPBACK_HOSTNAMES.has(parsed.hostname)) {
+        throw new Error(`POSTSIDER_API_URL must use https for non-local host "${parsed.hostname}". ` +
+            'Plain http is allowed only for local development on localhost, 127.0.0.1 or [::1].');
+    }
+    return (parsed.origin + parsed.pathname.replace(/\/+$/, '') + '/public/v1');
+}
+/** Hard ceiling on how long a single API request may take. */
+const REQUEST_TIMEOUT_MS = 30_000;
+/** Hard ceiling on how much of a failing response body is read or echoed. */
+const MAX_ERROR_BODY_BYTES = 8 * 1024;
+/**
+ * Hard ceiling on a successful response body. Tool results are injected into the
+ * agent's context, so an unbounded payload is a problem regardless of who causes
+ * it. 8 MB is far beyond any sane calendar response.
+ */
+const MAX_RESPONSE_BODY_BYTES = 8 * 1024 * 1024;
+/**
+ * Read `name` off a thrown value without relying on the Error prototype chain.
+ * A `DOMException` cross-realm value is not always `instanceof Error`, so
+ * classifying by prototype silently misroutes timeouts to the generic branch.
+ */
+function thrownName(err) {
+    if (typeof err === 'object' && err !== null && 'name' in err) {
+        return String(err.name);
+    }
+    return '';
+}
+/**
+ * Read a message off a thrown value's `cause`, which is where the runtime puts
+ * the real reason for a failed `fetch` (for example "unexpected redirect").
+ *
+ * Read structurally, never with `instanceof`: inside a test runner's VM the
+ * cause can come from another realm, which is the same trap `thrownName` exists
+ * to avoid.
+ */
+function thrownCauseMessage(err) {
+    if (typeof err === 'object' && err !== null && 'cause' in err) {
+        const cause = err.cause;
+        if (typeof cause === 'string') {
+            return cause;
+        }
+        if (typeof cause === 'object' && cause !== null && 'message' in cause) {
+            return String(cause.message);
+        }
+    }
+    return '';
+}
+/** Parse a JSON body, falling back to raw text when it is not JSON. */
+function parseBody(text) {
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Read a response body without ever buffering more than `maxBytes`.
+ *
+ * The download is aborted as soon as the ceiling is passed, so a broken or
+ * hostile server cannot stream unbounded data into the agent's context. The loop
+ * reads one chunk past the ceiling before deciding, so a body of exactly
+ * `maxBytes` is not falsely reported as truncated, and the over-read is bounded
+ * to that single chunk.
+ *
+ * Bodies without a stream reader (test doubles, bodiless responses) cannot be
+ * streamed at all, so they are read and then cut with the same byte ceiling.
+ */
+async function readBoundedBody(res, maxBytes) {
+    const encoder = new TextEncoder();
+    if (!res.body) {
+        const text = await res.text();
+        const bytes = encoder.encode(text);
+        if (bytes.byteLength <= maxBytes) {
+            return { text, truncated: false };
+        }
+        return {
+            text: new TextDecoder().decode(bytes.subarray(0, maxBytes)),
+            truncated: true,
+        };
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let seen = 0;
+    let truncated = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (!value) {
+                continue;
+            }
+            seen += value.byteLength;
+            chunks.push(value);
+            if (seen > maxBytes) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    finally {
+        // Release the connection even when we stopped reading early.
+        await reader.cancel().catch(() => undefined);
+    }
+    const all = new Uint8Array(seen);
+    let offset = 0;
+    for (const chunk of chunks) {
+        all.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    // Cut the BYTES, not the decoded string, so the ceiling stays exact.
+    const bytes = truncated ? all.subarray(0, maxBytes) : all;
+    return { text: new TextDecoder().decode(bytes), truncated };
+}
+/**
+ * Thin HTTP client for the PostSider public API (`/public/v1`).
+ *
+ * Auth is the RAW api key in the `Authorization` header (no `Bearer` prefix),
+ * matching the platform's public API contract. This client has no dependency on
+ * the backend; it talks to any PostSider instance (cloud or self-hosted) over
+ * HTTP, so the MCP server works the same everywhere.
+ */
+export class PostsiderClient {
+    apiKey;
+    base;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.base = resolveBaseUrl(baseUrl);
+    }
+    async request(method, path, opts = {}) {
+        if (!path.startsWith('/')) {
+            // Internal invariant: every path in server.ts is a literal starting with "/".
+            throw new Error(`Internal error: API paths must start with "/", received "${path}".`);
+        }
+        const url = new URL(this.base + path);
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null && v !== '') {
+                    url.searchParams.set(k, String(v));
+                }
+            }
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: this.apiKey,
+                    ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
+                    ...(opts.idempotencyKey ? { 'Idempotency-Key': opts.idempotencyKey } : {}),
+                },
+                body: opts.body ? JSON.stringify(opts.body) : undefined,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                // The public API never legitimately redirects, and a redirect would
+                // otherwise leave the validated origin: the HTTPS/loopback policy above
+                // only covers the URL the user configured, not wherever it points next.
+                redirect: 'error',
+            });
+        }
+        catch (err) {
+            const name = thrownName(err);
+            if (name === 'TimeoutError' || name === 'AbortError') {
+                throw new Error(`PostSider did not respond within ${REQUEST_TIMEOUT_MS / 1000}s (${method} ${path} at ${url.origin}). Check POSTSIDER_API_URL and that the instance is online.`);
+            }
+            // This client refuses redirects on purpose (see `redirect: 'error'`), so a
+            // redirected request would otherwise surface as an opaque "fetch failed".
+            if (thrownCauseMessage(err).toLowerCase().includes('redirect')) {
+                throw new Error(`PostSider answered ${method} ${path} with a redirect, which this client refuses to follow ` +
+                    `because it would send the API key to another address. Point POSTSIDER_API_URL directly at the ` +
+                    `PostSider API (self-hosted installs behind the bundled nginx need the /api suffix, e.g. https://social.example.com/api).`);
+            }
+            throw new Error(`Could not reach PostSider at ${url.origin}. Check POSTSIDER_API_URL and that the instance is online. (${err instanceof Error ? err.message : String(err)})`);
+        }
+        /**
+         * Read the body, turning an abort that happens mid-response into the same
+         * timeout message instead of leaking a raw DOMException to the agent.
+         */
+        const readBody = async (maxBytes) => {
+            try {
+                return await readBoundedBody(res, maxBytes);
+            }
+            catch (err) {
+                const name = thrownName(err);
+                if (name === 'TimeoutError' || name === 'AbortError') {
+                    throw new Error(`PostSider did not finish sending its response within ${REQUEST_TIMEOUT_MS / 1000}s (${method} ${path} at ${url.origin}). Check POSTSIDER_API_URL and that the instance is online.`);
+                }
+                throw new Error(`PostSider API ${method} ${path} response could not be read: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+        if (!res.ok) {
+            const { text: raw, truncated } = await readBody(MAX_ERROR_BODY_BYTES);
+            const data = parseBody(truncated ? `${raw} [truncated]` : raw);
+            const apiMsg = data && typeof data === 'object' && 'msg' in data
+                ? String(data.msg)
+                : typeof data === 'string'
+                    ? data
+                    : res.statusText;
+            // 423 = Emergency Pause (kill switch): surface WHY the post did not go
+            // out so an agent understands a paused org instead of a generic failure.
+            if (res.status === 423) {
+                const d = (data && typeof data === 'object' ? data : {});
+                const reason = typeof d.reason === 'string' ? d.reason : undefined;
+                throw new Error(`Publishing is paused for this organization${reason ? ` (${reason})` : ''}. No posts can be scheduled or published until an owner resumes from the PostSider dashboard.`);
+            }
+            if (res.status === 401 || res.status === 403) {
+                throw new Error(`Unauthorized (${res.status}). The POSTSIDER_API_KEY is missing or invalid. Generate one in PostSider under Settings -> API.`);
+            }
+            throw new Error(`PostSider API ${method} ${path} failed (${res.status}): ${apiMsg}`);
+        }
+        // A successful body is agent-visible payload, so it is bounded too: without
+        // a ceiling a broken instance could exhaust memory on the user's machine.
+        const { text, truncated } = await readBody(MAX_RESPONSE_BODY_BYTES);
+        if (truncated) {
+            throw new Error(`PostSider API ${method} ${path} returned more than ${MAX_RESPONSE_BODY_BYTES / (1024 * 1024)} MB, which is more than this server will load. Narrow the request, for example with a shorter date range.`);
+        }
+        return parseBody(text);
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    post(path, body, idempotencyKey) {
+        return this.request('POST', path, { body, idempotencyKey });
+    }
+    put(path, body) {
+        return this.request('PUT', path, { body });
+    }
+    del(path) {
+        return this.request('DELETE', path);
+    }
+}

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * PostSider MCP server entrypoint (stdio transport).
+ *
+ * Reads configuration from the environment, builds the client, and connects the
+ * shared server factory to stdio. Every tool registration lives in `server.ts`
+ * so that no transport can drift away from another.
+ *
+ * Configuration (environment variables):
+ *   POSTSIDER_API_KEY  (required) - org API key from Settings -> API
+ *   POSTSIDER_API_URL  (optional) - instance base URL
+ *                                   default: https://api.postsider.com
+ *
+ * Transport: stdio (the standard for local MCP clients).
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { PostsiderClient } from './client.js';
+import { createPostSiderMcpServer } from './server.js';
+const apiKey = process.env.POSTSIDER_API_KEY;
+const baseUrl = process.env.POSTSIDER_API_URL || 'https://api.postsider.com';
+async function main(key, url) {
+    const client = new PostsiderClient(key, url);
+    const server = createPostSiderMcpServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log the origin only: it is what the client actually talks to, and it cannot
+    // carry a query-string secret that the client would have dropped anyway.
+    process.stderr.write(`PostSider MCP server running (stdio) against ${new URL(url).origin}\n`);
+}
+if (!apiKey) {
+    // Fail fast with an actionable message on stderr (stdout is the MCP channel).
+    process.stderr.write('POSTSIDER_API_KEY is not set. Add it to your MCP client config. ' +
+        'Generate a key in PostSider under Settings -> API.\n');
+    process.exit(1);
+}
+main(apiKey, baseUrl).catch((err) => {
+    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/post-body.js

@@ -0,0 +1,29 @@
+/**
+ * Pure mapping from the MCP `postsider_create_post` tool arguments to the
+ * PostSider public API request body for `POST /public/v1/posts`.
+ *
+ * Kept as a standalone, dependency-free function so it can be unit-tested in
+ * isolation (importing `index.ts` would start the stdio server and require
+ * POSTSIDER_API_KEY). `index.ts` imports and uses this verbatim, so runtime
+ * behavior is unchanged.
+ */
+/**
+ * Map the create-post tool arguments to the public API request body.
+ * Defaults: `image` -> [], `settings` -> {}, `tags` -> []. `firstComment` is
+ * only included when provided.
+ */
+export function buildCreatePostBody(args) {
+    const { type, date, shortLink, posts, tags } = args;
+    return {
+        type,
+        date,
+        shortLink,
+        tags: tags ?? [],
+        posts: posts.map((p) => ({
+            integration: { id: p.channelId },
+            value: [{ content: p.content, image: p.images ?? [] }],
+            ...(p.firstComment ? { firstComment: p.firstComment } : {}),
+            settings: p.settings ?? {},
+        })),
+    };
+}