@velocms/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VeloCMS
+
+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,218 @@
+# @velocms/mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [VeloCMS](https://velocms.org) —
+draft, edit, publish, and manage your blog (posts, media, comments, members,
+site settings) from Claude Code, Claude Desktop, Cursor, or any other MCP
+client.
+
+It's a thin, typed wrapper around the VeloCMS Public API
+(`https://<your-blog>/api/v1`, documented at
+[`/api/openapi`](https://velocms.org/api/openapi) on any VeloCMS site): every
+tool maps to one real API call, with Zod-validated inputs and readable
+errors — no scraping, no browser automation, just the platform's own
+supported REST API.
+
+## What it does
+
+| Tool | What it does |
+|---|---|
+| `list_posts` | List posts, paginated, optionally filtered by status (`draft`/`published`) |
+| `get_post` | Fetch a single post by ID, including its full content and SEO fields |
+| `create_post` | Create a new post (defaults to `draft`) |
+| `update_post` | Partially update an existing post — only the fields you pass change |
+| `delete_post` | Permanently delete a post |
+| `publish_post` | Set a post's status to `published` (stamps `published_at`) |
+| `unpublish_post` | Set a post's status back to `draft` |
+| `list_media` | List the media library, paginated, optionally filtered by MIME type |
+| `list_comments` | List comments, paginated, optionally filtered by post or moderation status |
+| `moderate_comment` | Set a comment's status to `approved`, `pending`, or `spam` |
+| `list_members` | List subscribers/readers (emails are masked, e.g. `u***@example.com`) |
+| `get_site_settings` | Read the blog's name, description, and feature flags |
+
+Every tool ships a description an LLM can read to figure out when and how to
+use it — that's the point of MCP, not just a REST proxy with extra steps.
+See [Tool reference](#tool-reference) below for full argument lists.
+
+## Setup
+
+### 1. Get a VeloCMS API key
+
+In your VeloCMS dashboard: **Settings → API Keys** → create a key with the
+scopes you need (`posts:read`, `posts:write`, `media:read`, `comments:read`,
+`comments:moderate`, `members:read`, `site-settings:read`, etc.). API access
+requires the **Pro plan or higher**.
+
+### 2. Configure your MCP client
+
+You don't need to clone this repo — `npx` fetches and runs it on demand.
+
+#### Claude Code
+
+```bash
+claude mcp add velocms \
+  --env VELOCMS_SITE_URL=https://myblog.velocms.org \
+  --env VELOCMS_API_KEY=velo_your_64_char_hex_key_here \
+  -- npx -y -p @velocms/mcp velocms-mcp
+```
+
+MCP servers register their tools at session start, so restart your Claude
+Code session after adding this.
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json` (Settings → Developer → Edit
+Config):
+
+```json
+{
+  "mcpServers": {
+    "velocms": {
+      "command": "npx",
+      "args": ["-y", "-p", "@velocms/mcp", "velocms-mcp"],
+      "env": {
+        "VELOCMS_SITE_URL": "https://myblog.velocms.org",
+        "VELOCMS_API_KEY": "velo_your_64_char_hex_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+#### Cursor / any other MCP client
+
+Same shape as above — point the client's MCP config at
+`npx -y -p @velocms/mcp velocms-mcp` with `VELOCMS_SITE_URL` and
+`VELOCMS_API_KEY` set in its `env`. The server speaks standard MCP over
+stdio, so any client that supports stdio MCP servers works.
+
+### 3. Local install (contributing / running from source)
+
+```bash
+git clone https://github.com/VeloCMS/velocms-mcp.git
+cd velocms-mcp
+npm install
+npm run build
+cp .env.example .env
+# edit .env and set VELOCMS_SITE_URL + VELOCMS_API_KEY
+VELOCMS_SITE_URL=... VELOCMS_API_KEY=... node dist/index.js
+```
+
+## Config reference
+
+| Env var | Required | Description |
+|---|---|---|
+| `VELOCMS_SITE_URL` | yes | Your blog's base URL — a `*.velocms.org` subdomain or a bound custom domain. No trailing slash needed. |
+| `VELOCMS_API_KEY` | yes | An API key from `/admin/settings → API Keys`. Requires Pro plan or higher. Never logged. |
+
+If either is missing, the server prints a clear message to stderr and exits
+immediately (`process.exit(1)`) — it never starts half-configured.
+
+## Tool reference
+
+Argument names are camelCase; the server maps them to the API's snake_case
+JSON fields for you.
+
+**`list_posts`** — `page?`, `perPage?` (max 100), `status?` (`draft` |
+`published`).
+
+**`get_post`** — `id` (required).
+
+**`create_post`** — `title` (required, ≤255 chars), `slug?`, `contentHtml?`,
+`contentJson?` (TipTap ProseMirror document — prefer `contentHtml` unless
+you need this), `excerpt?` (≤500), `status?` (`draft` default | `published`),
+`tags?` (string array), `seoTitle?` (≤60), `seoDescription?` (≤160).
+
+**`update_post`** — `id` (required) + any of the `create_post` fields
+(all optional here). At least one field besides `id` is required — the tool
+rejects a no-op call before making any network request.
+
+**`delete_post`** — `id` (required). Permanent.
+
+**`publish_post`** / **`unpublish_post`** — `id` (required). Shorthand for
+`update_post({ status: "published" })` / `update_post({ status: "draft" })`.
+
+**`list_media`** — `page?`, `perPage?`, `type?` (MIME type prefix, e.g.
+`"image"`).
+
+**`list_comments`** — `page?`, `perPage?`, `postId?`, `status?` (`approved`
+| `pending` | `spam`).
+
+**`moderate_comment`** — `id` (required), `status` (required: `approved` |
+`pending` | `spam`).
+
+**`list_members`** — `page?`, `perPage?`, `tier?` (`free` | `paid`).
+
+**`get_site_settings`** — no arguments.
+
+## Error handling model
+
+The VeloCMS API returns a consistent JSON error envelope:
+
+```json
+{ "error": { "code": "RATE_LIMITED", "message": "...", "details": {} } }
+```
+
+This client surfaces that message directly (never a raw stack trace),
+enriched with actionable hints:
+
+- **401** (`UNAUTHORIZED`) — the message tells you to check `VELOCMS_API_KEY`.
+- **403** (`PLAN_UPGRADE_REQUIRED`) — the message points at `/admin/billing`.
+- **403** (`INVALID_SCOPE`/`FORBIDDEN`) — the message tells you to check the
+  key's scopes.
+- **429** (`RATE_LIMITED`) — the `Retry-After` response header (seconds) is
+  parsed and included in the error message, and returned as
+  `retryAfterSeconds` if you're calling the client library directly.
+- **Any other non-2xx** — the API's own `code` + `message` are surfaced as-is.
+
+Rate limits are plan-based (Pro: 30/min, 1,000/hr · Business: 120/min,
+5,000/hr · Agency: 300/min, 20,000/hr) — this server does not retry
+automatically; it fails fast with the wait time so an interactive tool call
+never blocks silently.
+
+## Security
+
+- Your API key is a **tenant-scoped** credential — it can only reach the
+  one blog it was issued for, and only the endpoints its scopes allow.
+- The key is read once from the environment and never logged, echoed, or
+  included in any tool output.
+- Member emails returned by `list_members` are masked by the API itself
+  (e.g. `u***@example.com`) — this server never sees or handles unmasked
+  member PII.
+- Encrypted tenant settings (Stripe keys, AI provider keys) are excluded
+  from `get_site_settings` by the API — there is no way to read them
+  through this server.
+
+## Notes on this MCP server
+
+- **`moderate_comment`'s body field is `status`, not `action`** —
+  `PATCH /api/v1/comments/{id}/moderate` takes `{ "status": "approved" |
+  "pending" | "spam" }` per the API's own schema, so the tool's input is
+  named to match.
+- **`get_post` and `get_site_settings` return the record directly** (not
+  wrapped in `{ "data": ... }`) — only the write endpoints (`create_post`,
+  `update_post`, `moderate_comment`) wrap their response, matching the API's
+  own inconsistency here (documented in `openapi.yaml`).
+- There is currently no `upload_media` tool — `POST /api/v1/media` takes
+  `multipart/form-data`, which doesn't map cleanly onto typical MCP client
+  transports. `list_media` is available for referencing media already
+  uploaded through the dashboard. Contributions welcome if you need this.
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test             # vitest — all tests run against a mocked fetch, no live API calls
+npm run build        # emits dist/
+```
+
+The test suite covers: the `Authorization: Bearer` header on every request,
+each tool's exact method/URL/body mapping, error-code mapping for
+401/403/429/500 responses, and the missing-env-var fail-fast path. No test
+in this repository makes a real network call.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Minimal REST client for the VeloCMS Public API (`public/openapi.yaml` in the
+ * main VeloCMS repository is the source of truth for every shape used here).
+ *
+ * Auth: `Authorization: Bearer <api-key>` — verbatim format from
+ * `src/lib/api/middleware.ts` `withApiAuth()` (missing/invalid header ->
+ * `401 UNAUTHORIZED`; see that file's step 1).
+ *
+ * Base path: `${siteUrl}/api/v1`. Every endpoint requires a Pro-or-higher
+ * plan and the scope listed for it in `openapi.yaml`.
+ *
+ * Error envelope (`openapi.yaml` `#/components/schemas/ApiError`):
+ *
+ *   { "error": { "code": "...", "message": "...", "details"?: {...} } }
+ *
+ * Rate limiting (`openapi.yaml` `#/components/responses/RateLimited`,
+ * `middleware.ts` steps 4-5): a `429` response carries a `Retry-After` header
+ * (seconds until the window resets). This client does not retry
+ * automatically — it surfaces the wait time in the thrown error's message
+ * and `retryAfterSeconds` so the calling agent can decide what to do next.
+ */
+export interface VeloCmsClientOptions {
+    /** Tenant site base URL, e.g. `https://myblog.velocms.org` or a bound custom domain. */
+    siteUrl: string;
+    /** API key from the VeloCMS admin → Settings → API Keys (format: `velo_<64-hex>`). */
+    apiKey: string;
+    /** Injectable fetch implementation — used by tests, defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Request timeout in ms (default 30s). */
+    requestTimeoutMs?: number;
+}
+/** `openapi.yaml` `ApiError.error.code` enum, plus a local fallback for unrecognized/absent codes. */
+export type VeloCmsApiErrorCode = "UNAUTHORIZED" | "INVALID_SCOPE" | "RATE_LIMITED" | "QUOTA_EXCEEDED" | "NOT_FOUND" | "VALIDATION_ERROR" | "FORBIDDEN" | "INTERNAL_ERROR" | "PLAN_UPGRADE_REQUIRED" | "HTTPS_REQUIRED" | "UNKNOWN_ERROR";
+/**
+ * Thrown for every non-2xx response. Carries the API's own error code +
+ * message (never a raw stack trace) plus the HTTP status and, on 429s, the
+ * `Retry-After` value in seconds.
+ */
+export declare class VeloCmsApiError extends Error {
+    readonly code: VeloCmsApiErrorCode;
+    readonly status: number | null;
+    readonly details?: Record<string, unknown>;
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, opts?: {
+        code?: VeloCmsApiErrorCode;
+        status?: number | null;
+        details?: Record<string, unknown>;
+        retryAfterSeconds?: number;
+    });
+}
+export type QueryParams = Record<string, string | number | boolean | undefined>;
+export type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+export declare class VeloCmsClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    constructor(opts: VeloCmsClientOptions);
+    private buildUrl;
+    /**
+     * Sends one request against `${siteUrl}/api/v1${path}`. Resolves with the
+     * parsed JSON body on 2xx (or `undefined` for a 204), throws
+     * `VeloCmsApiError` on any non-2xx response or network failure/timeout.
+     */
+    request<T>(method: HttpMethod, path: string, opts?: {
+        query?: QueryParams;
+        body?: unknown;
+    }): Promise<T>;
+    private buildError;
+}

package/dist/client.js

@@ -0,0 +1,157 @@
+/**
+ * Minimal REST client for the VeloCMS Public API (`public/openapi.yaml` in the
+ * main VeloCMS repository is the source of truth for every shape used here).
+ *
+ * Auth: `Authorization: Bearer <api-key>` — verbatim format from
+ * `src/lib/api/middleware.ts` `withApiAuth()` (missing/invalid header ->
+ * `401 UNAUTHORIZED`; see that file's step 1).
+ *
+ * Base path: `${siteUrl}/api/v1`. Every endpoint requires a Pro-or-higher
+ * plan and the scope listed for it in `openapi.yaml`.
+ *
+ * Error envelope (`openapi.yaml` `#/components/schemas/ApiError`):
+ *
+ *   { "error": { "code": "...", "message": "...", "details"?: {...} } }
+ *
+ * Rate limiting (`openapi.yaml` `#/components/responses/RateLimited`,
+ * `middleware.ts` steps 4-5): a `429` response carries a `Retry-After` header
+ * (seconds until the window resets). This client does not retry
+ * automatically — it surfaces the wait time in the thrown error's message
+ * and `retryAfterSeconds` so the calling agent can decide what to do next.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+function isApiErrorBody(value) {
+    if (typeof value !== "object" || value === null || !("error" in value))
+        return false;
+    const err = value.error;
+    if (typeof err !== "object" || err === null)
+        return false;
+    const { code, message } = err;
+    return typeof code === "string" && typeof message === "string";
+}
+/**
+ * Thrown for every non-2xx response. Carries the API's own error code +
+ * message (never a raw stack trace) plus the HTTP status and, on 429s, the
+ * `Retry-After` value in seconds.
+ */
+export class VeloCmsApiError extends Error {
+    code;
+    status;
+    details;
+    retryAfterSeconds;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "VeloCmsApiError";
+        this.code = opts.code ?? "UNKNOWN_ERROR";
+        this.status = opts.status ?? null;
+        this.details = opts.details;
+        this.retryAfterSeconds = opts.retryAfterSeconds;
+    }
+}
+export class VeloCmsClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    requestTimeoutMs;
+    constructor(opts) {
+        if (!opts.siteUrl) {
+            throw new Error("VeloCmsClient requires siteUrl (e.g. https://myblog.velocms.org). Set VELOCMS_SITE_URL.");
+        }
+        if (!opts.apiKey) {
+            throw new Error("VeloCmsClient requires apiKey. Get one from your VeloCMS dashboard: " +
+                "/admin/settings -> API Keys (Pro plan or higher required). Set VELOCMS_API_KEY.");
+        }
+        this.baseUrl = opts.siteUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    buildUrl(path, query) {
+        const url = new URL(`${this.baseUrl}/api/v1${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+    /**
+     * Sends one request against `${siteUrl}/api/v1${path}`. Resolves with the
+     * parsed JSON body on 2xx (or `undefined` for a 204), throws
+     * `VeloCmsApiError` on any non-2xx response or network failure/timeout.
+     */
+    async request(method, path, opts = {}) {
+        const url = this.buildUrl(path, opts.query);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...(opts.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new VeloCmsApiError(`Request to ${path} timed out after ${this.requestTimeoutMs}ms.`, { code: "INTERNAL_ERROR" });
+            }
+            throw new VeloCmsApiError(`Network error calling the VeloCMS API (${path}): ` +
+                `${err instanceof Error ? err.message : String(err)}. ` +
+                "Check that VELOCMS_SITE_URL is correct and reachable.", { code: "INTERNAL_ERROR" });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        const rawText = await response.text();
+        let json;
+        if (rawText) {
+            try {
+                json = JSON.parse(rawText);
+            }
+            catch {
+                json = undefined;
+            }
+        }
+        if (!response.ok) {
+            throw this.buildError(response, json, path);
+        }
+        return json;
+    }
+    buildError(response, json, path) {
+        const body = isApiErrorBody(json) ? json : undefined;
+        const code = body?.error.code ?? "UNKNOWN_ERROR";
+        let message = body?.error.message ?? `VeloCMS API returned HTTP ${response.status} for ${path}.`;
+        const details = body?.error.details;
+        const retryAfterHeader = response.headers.get("retry-after");
+        const retryAfterParsed = retryAfterHeader !== null ? Number(retryAfterHeader) : NaN;
+        const retryAfterSeconds = Number.isFinite(retryAfterParsed) ? retryAfterParsed : undefined;
+        if (response.status === 401) {
+            message +=
+                " Check that VELOCMS_API_KEY is set and valid (get one from /admin/settings -> API Keys).";
+        }
+        else if (response.status === 403) {
+            message +=
+                code === "PLAN_UPGRADE_REQUIRED"
+                    ? " The VeloCMS Public API requires a Pro plan or higher — upgrade at /admin/billing."
+                    : " Check that VELOCMS_API_KEY has the scope required for this operation.";
+        }
+        else if (response.status === 429 && retryAfterSeconds !== undefined) {
+            message += ` Retry after ${retryAfterSeconds} second(s).`;
+        }
+        return new VeloCmsApiError(message, {
+            code,
+            status: response.status,
+            details,
+            retryAfterSeconds,
+        });
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure env-resolution helper — kept separate from `index.ts` (which has a
+ * `#!/usr/bin/env node` shebang and starts the stdio server as a side effect
+ * on import) so the fail-fast "missing env var" behavior is unit-testable
+ * without spawning a subprocess or calling `process.exit`.
+ */
+export interface VeloCmsEnvConfig {
+    siteUrl: string;
+    apiKey: string;
+}
+export type VeloCmsEnvResolution = {
+    ok: true;
+    config: VeloCmsEnvConfig;
+} | {
+    ok: false;
+    missing: string[];
+};
+/**
+ * Reads `VELOCMS_SITE_URL` + `VELOCMS_API_KEY` from the given environment
+ * (defaults to `process.env`). Never logs the resolved values.
+ */
+export declare function resolveEnvConfig(env?: NodeJS.ProcessEnv): VeloCmsEnvResolution;
+/** Human-readable message for the missing-env-var fail-fast path (stderr only, never stdout). */
+export declare function formatMissingEnvMessage(missing: string[]): string;

package/dist/env.js

@@ -0,0 +1,30 @@
+/**
+ * Pure env-resolution helper — kept separate from `index.ts` (which has a
+ * `#!/usr/bin/env node` shebang and starts the stdio server as a side effect
+ * on import) so the fail-fast "missing env var" behavior is unit-testable
+ * without spawning a subprocess or calling `process.exit`.
+ */
+/**
+ * Reads `VELOCMS_SITE_URL` + `VELOCMS_API_KEY` from the given environment
+ * (defaults to `process.env`). Never logs the resolved values.
+ */
+export function resolveEnvConfig(env = process.env) {
+    const siteUrl = env.VELOCMS_SITE_URL;
+    const apiKey = env.VELOCMS_API_KEY;
+    const missing = [];
+    if (!siteUrl)
+        missing.push("VELOCMS_SITE_URL");
+    if (!apiKey)
+        missing.push("VELOCMS_API_KEY");
+    if (missing.length > 0 || !siteUrl || !apiKey) {
+        return { ok: false, missing };
+    }
+    return { ok: true, config: { siteUrl, apiKey } };
+}
+/** Human-readable message for the missing-env-var fail-fast path (stderr only, never stdout). */
+export function formatMissingEnvMessage(missing) {
+    return (`[velocms-mcp] Missing required environment variable(s): ${missing.join(", ")}.\n` +
+        "  VELOCMS_SITE_URL — your blog's base URL, e.g. https://myblog.velocms.org (or a bound custom domain)\n" +
+        "  VELOCMS_API_KEY  — an API key from your VeloCMS dashboard: /admin/settings -> API Keys (Pro plan or higher)\n" +
+        "Set both in your MCP client config or shell environment. See README.md for setup.");
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * velocms-mcp — MCP stdio server for the VeloCMS Public API.
+ *
+ * Registers every tool from `./tools.js` against a single `VeloCmsClient`
+ * instance. Run directly (`node dist/index.js`) or via the `velocms-mcp` /
+ * `npx @velocms/mcp` bin entry — register it in an MCP client's config (see
+ * README.md).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * velocms-mcp — MCP stdio server for the VeloCMS Public API.
+ *
+ * Registers every tool from `./tools.js` against a single `VeloCmsClient`
+ * instance. Run directly (`node dist/index.js`) or via the `velocms-mcp` /
+ * `npx @velocms/mcp` bin entry — register it in an MCP client's config (see
+ * README.md).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { VeloCmsApiError, VeloCmsClient } from "./client.js";
+import { formatMissingEnvMessage, resolveEnvConfig } from "./env.js";
+import { tools } from "./tools.js";
+const SERVER_NAME = "velocms-mcp";
+const SERVER_VERSION = "0.1.0";
+function formatError(err) {
+    if (err instanceof VeloCmsApiError) {
+        const statusPart = err.status !== null ? `, HTTP ${err.status}` : "";
+        const parts = [`VeloCMS API error (${err.code}${statusPart}): ${err.message}`];
+        if (err.details)
+            parts.push(`Details: ${JSON.stringify(err.details)}`);
+        return parts.join("\n");
+    }
+    if (err instanceof Error)
+        return `Error: ${err.message}`;
+    return `Error: ${String(err)}`;
+}
+async function main() {
+    const resolution = resolveEnvConfig();
+    if (!resolution.ok) {
+        console.error(formatMissingEnvMessage(resolution.missing));
+        process.exit(1);
+    }
+    const client = new VeloCmsClient(resolution.config);
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    for (const [name, tool] of Object.entries(tools)) {
+        server.registerTool(name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, async (args) => {
+            try {
+                const result = await tool.handler(client, (args ?? {}));
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: formatError(err) }], isError: true };
+            }
+        });
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[velocms-mcp] MCP server running on stdio (${Object.keys(tools).length} tools registered).`);
+}
+main().catch((err) => {
+    console.error(`[velocms-mcp] Fatal error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tool registry for velocms-mcp. Each entry is `{ title, description,
+ * inputSchema, handler }`:
+ *
+ * - `inputSchema` is a Zod *raw shape* (a plain object of Zod schemas) —
+ *   this is what `@modelcontextprotocol/sdk`'s `server.registerTool()`
+ *   expects as its second argument's `inputSchema` field.
+ * - `handler(client, rawArgs)` re-validates `rawArgs` against
+ *   `z.object(shape)` internally (belt-and-suspenders: the MCP SDK already
+ *   validates against `inputSchema` before calling the handler, but parsing
+ *   again here gives every handler a precisely-typed `args` value without
+ *   needing an `any` escape hatch at the registry boundary — and it means
+ *   `handler` can be called directly and safely from tests/CLI code with a
+ *   plain object).
+ *
+ * Every request/response shape below is taken from `public/openapi.yaml` in
+ * the main VeloCMS repository (the canonical API contract) — see the
+ * per-tool comments for the exact operationId + line references used.
+ */
+import { z } from "zod";
+import { VeloCmsClient } from "./client.js";
+export interface ToolEntry {
+    title: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    handler: (client: VeloCmsClient, rawArgs: Record<string, unknown>) => Promise<unknown>;
+}
+export declare const tools: Record<string, ToolEntry>;

package/dist/tools.js

@@ -0,0 +1,375 @@
+/**
+ * Tool registry for velocms-mcp. Each entry is `{ title, description,
+ * inputSchema, handler }`:
+ *
+ * - `inputSchema` is a Zod *raw shape* (a plain object of Zod schemas) —
+ *   this is what `@modelcontextprotocol/sdk`'s `server.registerTool()`
+ *   expects as its second argument's `inputSchema` field.
+ * - `handler(client, rawArgs)` re-validates `rawArgs` against
+ *   `z.object(shape)` internally (belt-and-suspenders: the MCP SDK already
+ *   validates against `inputSchema` before calling the handler, but parsing
+ *   again here gives every handler a precisely-typed `args` value without
+ *   needing an `any` escape hatch at the registry boundary — and it means
+ *   `handler` can be called directly and safely from tests/CLI code with a
+ *   plain object).
+ *
+ * Every request/response shape below is taken from `public/openapi.yaml` in
+ * the main VeloCMS repository (the canonical API contract) — see the
+ * per-tool comments for the exact operationId + line references used.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Shared arg pieces
+// ---------------------------------------------------------------------------
+const postStatusEnum = z.enum(["draft", "published"]);
+const commentStatusEnum = z.enum(["approved", "pending", "spam"]);
+const memberTierEnum = z.enum(["free", "paid"]);
+const pageArg = z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe("Page number (1-based). Default: 1.");
+const perPageArg = z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Records per page, max 100. Default: 20.");
+// ---------------------------------------------------------------------------
+// list_posts — GET /api/v1/posts (openapi.yaml operationId: listPosts)
+// ---------------------------------------------------------------------------
+const listPostsShape = {
+    page: pageArg,
+    perPage: perPageArg,
+    status: postStatusEnum.optional().describe("Filter by post status (draft or published)."),
+};
+const listPostsSchema = z.object(listPostsShape);
+async function handleListPosts(client, rawArgs) {
+    const args = listPostsSchema.parse(rawArgs);
+    return client.request("GET", "/posts", {
+        query: { page: args.page, per_page: args.perPage, status: args.status },
+    });
+}
+// ---------------------------------------------------------------------------
+// get_post — GET /api/v1/posts/{id} (operationId: getPost)
+// Response is the PostFull record DIRECTLY (not wrapped in `data`) —
+// see openapi.yaml lines ~836-842.
+// ---------------------------------------------------------------------------
+const getPostShape = {
+    id: z.string().min(1).describe("PocketBase record ID of the post."),
+};
+const getPostSchema = z.object(getPostShape);
+async function handleGetPost(client, rawArgs) {
+    const args = getPostSchema.parse(rawArgs);
+    return client.request("GET", `/posts/${encodeURIComponent(args.id)}`);
+}
+// ---------------------------------------------------------------------------
+// create_post — POST /api/v1/posts (operationId: createPost)
+// Body: CreatePostBody. Response: 201 { data: PostFull }.
+// ---------------------------------------------------------------------------
+const createPostShape = {
+    title: z.string().min(1).max(255).describe("Post title. Required."),
+    slug: z.string().min(1).max(255).optional().describe("Auto-generated from title if omitted."),
+    contentHtml: z.string().optional().describe("Post body as HTML."),
+    contentJson: z
+        .unknown()
+        .optional()
+        .describe("TipTap ProseMirror JSON document (arbitrary structure). Prefer contentHtml unless you " +
+        "specifically need to write a ProseMirror document."),
+    excerpt: z.string().max(500).optional(),
+    status: postStatusEnum
+        .optional()
+        .describe("draft (default) or published. Publishing here stamps published_at automatically — " +
+        "or create as draft and call publish_post later."),
+    tags: z.array(z.string()).optional(),
+    seoTitle: z.string().max(60).optional().describe("SEO meta title, max 60 chars."),
+    seoDescription: z.string().max(160).optional().describe("SEO meta description, max 160 chars."),
+};
+const createPostSchema = z.object(createPostShape);
+async function handleCreatePost(client, rawArgs) {
+    const args = createPostSchema.parse(rawArgs);
+    const body = { title: args.title };
+    if (args.slug !== undefined)
+        body.slug = args.slug;
+    if (args.contentHtml !== undefined)
+        body.content_html = args.contentHtml;
+    if (args.contentJson !== undefined)
+        body.content_json = args.contentJson;
+    if (args.excerpt !== undefined)
+        body.excerpt = args.excerpt;
+    if (args.status !== undefined)
+        body.status = args.status;
+    if (args.tags !== undefined)
+        body.tags = args.tags;
+    if (args.seoTitle !== undefined)
+        body.seo_title = args.seoTitle;
+    if (args.seoDescription !== undefined)
+        body.seo_description = args.seoDescription;
+    const response = await client.request("POST", "/posts", { body });
+    return response.data;
+}
+// ---------------------------------------------------------------------------
+// update_post — PATCH /api/v1/posts/{id} (operationId: updatePost)
+// Body: PatchPostBody (all fields optional). Response: 200 { data: PostFull }.
+// ---------------------------------------------------------------------------
+const updatePostShape = {
+    id: z.string().min(1).describe("PocketBase record ID of the post to update."),
+    title: z.string().min(1).max(255).optional(),
+    slug: z.string().min(1).max(255).optional(),
+    contentHtml: z.string().optional(),
+    contentJson: z.unknown().optional().describe("TipTap ProseMirror JSON document."),
+    excerpt: z.string().max(500).optional(),
+    status: postStatusEnum
+        .optional()
+        .describe("draft or published. Transitioning draft -> published stamps published_at automatically. " +
+        "Prefer publish_post/unpublish_post for a status-only change."),
+    tags: z.array(z.string()).optional(),
+    seoTitle: z.string().max(60).optional(),
+    seoDescription: z.string().max(160).optional(),
+};
+const updatePostSchema = z.object(updatePostShape);
+const UPDATE_POST_FIELD_KEYS = [
+    "title",
+    "slug",
+    "contentHtml",
+    "contentJson",
+    "excerpt",
+    "status",
+    "tags",
+    "seoTitle",
+    "seoDescription",
+];
+async function handleUpdatePost(client, rawArgs) {
+    const args = updatePostSchema.parse(rawArgs);
+    const body = {};
+    if (args.title !== undefined)
+        body.title = args.title;
+    if (args.slug !== undefined)
+        body.slug = args.slug;
+    if (args.contentHtml !== undefined)
+        body.content_html = args.contentHtml;
+    if (args.contentJson !== undefined)
+        body.content_json = args.contentJson;
+    if (args.excerpt !== undefined)
+        body.excerpt = args.excerpt;
+    if (args.status !== undefined)
+        body.status = args.status;
+    if (args.tags !== undefined)
+        body.tags = args.tags;
+    if (args.seoTitle !== undefined)
+        body.seo_title = args.seoTitle;
+    if (args.seoDescription !== undefined)
+        body.seo_description = args.seoDescription;
+    const hasAnyField = UPDATE_POST_FIELD_KEYS.some((key) => args[key] !== undefined);
+    if (!hasAnyField) {
+        throw new Error("update_post: provide at least one field to change besides id (title, slug, contentHtml, " +
+            "contentJson, excerpt, status, tags, seoTitle, seoDescription).");
+    }
+    const response = await client.request("PATCH", `/posts/${encodeURIComponent(args.id)}`, { body });
+    return response.data;
+}
+// ---------------------------------------------------------------------------
+// delete_post — DELETE /api/v1/posts/{id} (operationId: deletePost) -> 204
+// ---------------------------------------------------------------------------
+const deletePostShape = {
+    id: z.string().min(1).describe("PocketBase record ID of the post to delete."),
+};
+const deletePostSchema = z.object(deletePostShape);
+async function handleDeletePost(client, rawArgs) {
+    const args = deletePostSchema.parse(rawArgs);
+    await client.request("DELETE", `/posts/${encodeURIComponent(args.id)}`);
+    return { ok: true, id: args.id };
+}
+// ---------------------------------------------------------------------------
+// publish_post / unpublish_post — both PATCH /api/v1/posts/{id} with a
+// status-only body (openapi.yaml PatchPostBody.status). Kept as separate
+// tools from update_post because "publish this" / "take this down" are the
+// two most common single-purpose actions an agent performs.
+// ---------------------------------------------------------------------------
+const publishPostShape = {
+    id: z.string().min(1).describe("PocketBase record ID of the post to publish."),
+};
+const publishPostSchema = z.object(publishPostShape);
+async function setPostStatus(client, id, status) {
+    const response = await client.request("PATCH", `/posts/${encodeURIComponent(id)}`, { body: { status } });
+    return response.data;
+}
+async function handlePublishPost(client, rawArgs) {
+    const args = publishPostSchema.parse(rawArgs);
+    return setPostStatus(client, args.id, "published");
+}
+const unpublishPostShape = {
+    id: z.string().min(1).describe("PocketBase record ID of the post to unpublish."),
+};
+const unpublishPostSchema = z.object(unpublishPostShape);
+async function handleUnpublishPost(client, rawArgs) {
+    const args = unpublishPostSchema.parse(rawArgs);
+    return setPostStatus(client, args.id, "draft");
+}
+// ---------------------------------------------------------------------------
+// list_media — GET /api/v1/media (operationId: listMedia)
+// ---------------------------------------------------------------------------
+const listMediaShape = {
+    page: pageArg,
+    perPage: perPageArg,
+    type: z.string().optional().describe("Filter by MIME type prefix (e.g. 'image')."),
+};
+const listMediaSchema = z.object(listMediaShape);
+async function handleListMedia(client, rawArgs) {
+    const args = listMediaSchema.parse(rawArgs);
+    return client.request("GET", "/media", {
+        query: { page: args.page, per_page: args.perPage, type: args.type },
+    });
+}
+// ---------------------------------------------------------------------------
+// list_comments — GET /api/v1/comments (operationId: listComments)
+// ---------------------------------------------------------------------------
+const listCommentsShape = {
+    page: pageArg,
+    perPage: perPageArg,
+    postId: z.string().optional().describe("Filter to comments on a specific post."),
+    status: commentStatusEnum.optional().describe("Filter by moderation status."),
+};
+const listCommentsSchema = z.object(listCommentsShape);
+async function handleListComments(client, rawArgs) {
+    const args = listCommentsSchema.parse(rawArgs);
+    return client.request("GET", "/comments", {
+        query: { page: args.page, per_page: args.perPage, post_id: args.postId, status: args.status },
+    });
+}
+// ---------------------------------------------------------------------------
+// moderate_comment — PATCH /api/v1/comments/{id}/moderate
+// (operationId: moderateComment). Body field is `status` per openapi.yaml
+// lines ~1109-1115 (NOT "action" — see README "Notes on this MCP server").
+// ---------------------------------------------------------------------------
+const moderateCommentShape = {
+    id: z.string().min(1).describe("PocketBase record ID of the comment to moderate."),
+    status: commentStatusEnum.describe("Moderation status to apply: approved, pending, or spam."),
+};
+const moderateCommentSchema = z.object(moderateCommentShape);
+async function handleModerateComment(client, rawArgs) {
+    const args = moderateCommentSchema.parse(rawArgs);
+    const response = await client.request("PATCH", `/comments/${encodeURIComponent(args.id)}/moderate`, { body: { status: args.status } });
+    return response.data;
+}
+// ---------------------------------------------------------------------------
+// list_members — GET /api/v1/members (operationId: listMembers)
+// Email local parts are masked by the API (e.g. u***@example.com) — this
+// tool never sees or handles unmasked member emails.
+// ---------------------------------------------------------------------------
+const listMembersShape = {
+    page: pageArg,
+    perPage: perPageArg,
+    tier: memberTierEnum.optional().describe("Filter by subscription tier (free or paid)."),
+};
+const listMembersSchema = z.object(listMembersShape);
+async function handleListMembers(client, rawArgs) {
+    const args = listMembersSchema.parse(rawArgs);
+    return client.request("GET", "/members", {
+        query: { page: args.page, per_page: args.perPage, tier: args.tier },
+    });
+}
+// ---------------------------------------------------------------------------
+// get_site_settings — GET /api/v1/site-settings (operationId: getSiteSettings)
+// Response is the SiteSettings record directly (not wrapped in `data`).
+// Encrypted fields (member_stripe_*, ai_api_key) are excluded by the API.
+// ---------------------------------------------------------------------------
+const getSiteSettingsShape = {};
+const getSiteSettingsSchema = z.object(getSiteSettingsShape);
+async function handleGetSiteSettings(client, rawArgs) {
+    getSiteSettingsSchema.parse(rawArgs);
+    return client.request("GET", "/site-settings");
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+export const tools = {
+    list_posts: {
+        title: "List posts",
+        description: "Lists blog posts for the authenticated tenant, paginated (default 20/page, max 100). " +
+            "Optionally filter by status (draft or published). Requires the posts:read API key scope.",
+        inputSchema: listPostsShape,
+        handler: handleListPosts,
+    },
+    get_post: {
+        title: "Get a post",
+        description: "Fetches a single post by its PocketBase record ID, including content_html/content_json " +
+            "and SEO fields. Requires the posts:read scope.",
+        inputSchema: getPostShape,
+        handler: handleGetPost,
+    },
+    create_post: {
+        title: "Create a post",
+        description: "Creates a new blog post. Defaults to status=draft — pass status=published to publish " +
+            "immediately (stamps published_at automatically), or create as a draft and call " +
+            "publish_post once you're ready. Requires the posts:write scope.",
+        inputSchema: createPostShape,
+        handler: handleCreatePost,
+    },
+    update_post: {
+        title: "Update a post",
+        description: "Partially updates an existing post — only the fields you pass are changed. Requires at " +
+            "least one field besides id. Requires the posts:write scope.",
+        inputSchema: updatePostShape,
+        handler: handleUpdatePost,
+    },
+    delete_post: {
+        title: "Delete a post",
+        description: "Permanently deletes a post by ID. Requires the posts:write scope.",
+        inputSchema: deletePostShape,
+        handler: handleDeletePost,
+    },
+    publish_post: {
+        title: "Publish a post",
+        description: "Sets a post's status to published (stamps published_at). Shorthand for " +
+            "update_post({ status: 'published' }). Requires the posts:write scope.",
+        inputSchema: publishPostShape,
+        handler: handlePublishPost,
+    },
+    unpublish_post: {
+        title: "Unpublish a post",
+        description: "Sets a post's status back to draft, taking it off the public site. Shorthand for " +
+            "update_post({ status: 'draft' }). Requires the posts:write scope.",
+        inputSchema: unpublishPostShape,
+        handler: handleUnpublishPost,
+    },
+    list_media: {
+        title: "List media",
+        description: "Lists items in the media library, paginated. Optionally filter by MIME type prefix " +
+            "(e.g. 'image'). Requires the media:read scope.",
+        inputSchema: listMediaShape,
+        handler: handleListMedia,
+    },
+    list_comments: {
+        title: "List comments",
+        description: "Lists comments, paginated. Optionally filter to a specific post (postId) and/or by " +
+            "moderation status (approved, pending, spam). Requires the comments:read scope.",
+        inputSchema: listCommentsShape,
+        handler: handleListComments,
+    },
+    moderate_comment: {
+        title: "Moderate a comment",
+        description: "Sets a comment's moderation status (approved, pending, or spam). Requires the " +
+            "comments:moderate scope.",
+        inputSchema: moderateCommentShape,
+        handler: handleModerateComment,
+    },
+    list_members: {
+        title: "List members",
+        description: "Lists reader/subscriber records, paginated. Email local parts are masked by the API " +
+            "(e.g. u***@example.com). Optionally filter by tier (free or paid). Requires the " +
+            "members:read scope.",
+        inputSchema: listMembersShape,
+        handler: handleListMembers,
+    },
+    get_site_settings: {
+        title: "Get site settings",
+        description: "Fetches the tenant's site configuration (name, description, logo, favicon, " +
+            "members/comments enabled flags). Encrypted fields (Stripe keys, AI API key) are always " +
+            "excluded by the API. Requires the site-settings:read scope.",
+        inputSchema: getSiteSettingsShape,
+        handler: handleGetSiteSettings,
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Response DTOs for the VeloCMS Public API (`/api/v1`), mirrored from
+ * `public/openapi.yaml` in the main VeloCMS repository (components.schemas).
+ * Kept intentionally close to the wire shape (snake_case field names) so a
+ * tool's JSON output matches what `openapi.yaml` documents.
+ */
+export type PostStatus = "draft" | "published";
+export interface PostSummary {
+    id: string;
+    title: string;
+    slug: string;
+    status: PostStatus;
+    excerpt?: string | null;
+    tags?: string[];
+    published_at?: string | null;
+    created: string;
+    updated: string;
+}
+/** GET /api/v1/posts/{id} response shape (PostFull = PostSummary + body/SEO fields). */
+export interface PostFull extends PostSummary {
+    content_html?: string;
+    content_json?: unknown;
+    seo_title?: string | null;
+    seo_description?: string | null;
+}
+/** Envelope every paginated list endpoint returns (openapi.yaml PaginatedMeta + items). */
+export interface PaginatedList<T> {
+    page: number;
+    per_page: number;
+    total: number;
+    total_pages: number;
+    items: T[];
+}
+export interface MediaItem {
+    id: string;
+    filename: string;
+    url: string;
+    mime_type: string;
+    size: number;
+    width?: number | null;
+    height?: number | null;
+    alt?: string | null;
+    created: string;
+}
+export type CommentStatus = "approved" | "pending" | "spam";
+export interface CommentRecord {
+    id: string;
+    post_id: string;
+    author_name: string;
+    author_email?: string | null;
+    body: string;
+    parent_id?: string | null;
+    status: CommentStatus;
+    created: string;
+    updated: string;
+}
+export type MemberTier = "free" | "paid";
+export type MemberStatus = "active" | "cancelled" | "past_due";
+export interface MemberSummary {
+    id: string;
+    /** Local part is masked by the API for privacy, e.g. `u***@example.com`. */
+    email: string;
+    tier: MemberTier;
+    status: MemberStatus;
+    created: string;
+    updated: string;
+}
+export interface SiteSettings {
+    id: string;
+    tenant_id: string;
+    site_name: string;
+    site_description?: string | null;
+    site_logo?: string | null;
+    site_favicon?: string | null;
+    members_enabled: boolean;
+    comments_enabled: boolean;
+    created: string;
+    updated: string;
+}
+/** POST/PATCH endpoints that wrap their record in `{ "data": ... }`. */
+export interface ApiEnvelope<T> {
+    data: T;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Response DTOs for the VeloCMS Public API (`/api/v1`), mirrored from
+ * `public/openapi.yaml` in the main VeloCMS repository (components.schemas).
+ * Kept intentionally close to the wire shape (snake_case field names) so a
+ * tool's JSON output matches what `openapi.yaml` documents.
+ */
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@velocms/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for VeloCMS — draft, publish, and manage your blog (posts, media, comments, members) from Claude Code, Claude Desktop, Cursor, or any MCP client.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "VeloCMS",
+    "url": "https://velocms.org"
+  },
+  "keywords": [
+    "velocms",
+    "blog",
+    "cms",
+    "mcp",
+    "mcp-server",
+    "claude",
+    "publishing",
+    "seo"
+  ],
+  "homepage": "https://velocms.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VeloCMS/velocms-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/VeloCMS/velocms-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "velocms-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}