paperboy
hybriden/paperboy
Paperboy — an open-source, headless CMS. Editor-first, type-safe, self-hostable. DPX: Don't Pay eXtra. 📰
Instalação
npx convez-ai hybriden/paperboy1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
📰 Paperboy
An open-source, headless CMS — editor-first, type-safe, batteries included.
Paperboy ONE — Open, No Extras. · DPX — Don't Pay eXtra. A proper headless CMS without the enterprise "experience platform" invoice. Self-host it, own your content, ship.
Built for teams of humans and agents. Every write path — admin UI, REST, MCP — goes through the same validation, permissions and audit trail; agents are first-class editors, not an integration afterthought (the MCP↔API parity is test-enforced). See docs/POSITIONING.md.
A TypeScript monorepo: a Fastify Management + Delivery API, a React admin with visual on-page editing, a Next.js reference frontend, and a stdio MCP server — on PostgreSQL.
Highlights
- Data-driven content types — pages, blocks, and globals defined as data, not code.
- Content areas with inline + shared blocks and per-field "allowed types".
- Multisite — several sites/brands in one instance: per-site delivery keys, media library, preview URL and start page, with a site switcher in the admin and full site management (create wizard, rename, start-page picker, delete with cascade + type-the-name confirm) under Settings → Sites. Content types, locales and users stay shared. The partition is enforced deny-by-default in the same chokepoints as everything else.
- No-leak Delivery API — one read chokepoint with a
perspective; public keys see only published content, private fields never serialize, preview keys see drafts. Lists support pagination, sorting and field filters (?limit=&offset=&sort=-data.publishDate&data.author=Jane), plus full-text search (/delivery/search?q=). Every item and inline block also shipsfieldTypes— the declared type per public field — so frontends switch on schema instead of sniffing value shapes. - SEO & schema.org built in — every page delivers a server-computed
seoblock (title/description/canonical/robots/OpenGraph/Twitter) plus per-@type-correct JSON-LD with a breadcrumb trail, driven by field-level SEO roles and a schema.org type on the content type. The type editor shows a Google rich-result coverage checklist with one-click "add missing fields"; preview is alwaysnoindex. - Image transforms —
?w=800&format=webp&q=75on any media URL; variants generated once with sharp and cached on disk (widths/qualities snap to fixed steps). - Visual on-page editing — click an element in the live preview to focus its field in the editor, focus a field to highlight it in the preview, and drag shared blocks from the assets pane straight onto the page — even into a cross-origin preview iframe. The bridge ships as the framework-agnostic
@paperboycms/previewnpm package (see below). - Multi-language (document-level i18n + fallback chain) — untranslated content is flagged in the live content tree, single language variants can be deleted, and translation gaps are actionable from the dashboard. Plus hierarchical URLs from the page tree, version history + restore, trash/restore, duplicate.
- Secure by default — Argon2id + opaque server-side sessions + CSRF, passwordless TOTP 2FA, deny-by-default RBAC with object-level scope checks, append-only audit log.
- Typed client SDK —
@paperboycms/clienton npm:createClient({ baseUrl, key }), then typedgetBySlug/list/search, media-variant helpers, framework-agnostic render helpers and an optional ETag cache. No codegen — types come from the shared Zod schemas. - Agent provenance & review — every version records whether a human or an agent wrote it (🤖 badges), agent drafts carry a one-click-approve review flag, and an opt-in gate keeps agents from publishing unreviewed work.
- AI copy desk (optional) — improve/rewrite/summarize, draft prose about a selected topic, richtext-aware translation, vision-based alt text generated from the actual image bytes, and schema.org field suggestions. With no API key configured it refuses honestly with a clear error instead of faking output.
- Dashboard as a worklist — translation gaps, images missing alt text, unused blocks and empty types are named and deep-linked so they're fixable in place, not dead counts.
- Integrations — HMAC publish webhooks, media uploads with folders, and a full MCP server (drive the CMS from an AI client, with revocable tokens).
- Great admin — React 19 + Vite, light/dark themes, ⌘K command palette, accessible (axe-clean), keyboard-operable drag-drop.
Layout
apps/api Fastify v5 — Management API (auth/RBAC) + Delivery API (read-only, key-scoped)
apps/admin React 19 + Vite — the editor (tree, content areas, live preview, on-page editing)
apps/web Next.js 15 — reference headless frontend with Draft Mode preview
apps/mcp stdio MCP server — operate the whole CMS over the Model Context Protocol
packages/shared Zod schemas + shared types (single source of truth) + the AI provider
packages/db Drizzle schema, migrations, query layer (object-level authz), seed
packages/client @paperboycms/client — the typed Delivery API SDK (published to npm)
packages/preview @paperboycms/preview — the on-page-editing bridge (published to npm)
Any frontend (Next, Astro, SvelteKit, …) can be a Paperboy client — either with
@paperboycms/client (typed, ETag-aware) or by reading the Delivery API over plain HTTP;
it doesn't import the CMS, only the contract.
The npm packages
Two packages are published to npm so external frontends integrate against a contract, not against the CMS codebase. Both are versioned independently of the CMS itself.
@paperboycms/client — typed Delivery API SDK
npm install @paperboycms/client
Thin and dependency-free, end-to-end typed from the same Zod schemas the server serializes with — no codegen step:
import { createClient, mediaUrl, mediaSrcset } from "@paperboycms/client";
const cms = createClient({
baseUrl: "https://cms.example.com",
key: process.env.PAPERBOY_PUBLIC_KEY!, // pk_… = published only; prv_… = drafts (server-side!)
});
type BlogPost = { title: string; body: unknown; publishDate?: string };
const post = await cms.getBySlug<BlogPost>("hello-world", { locale: "en", populate: 2 });
const { items, total } = await cms.list<BlogPost>("BlogPost", { sort: "-data.publishDate", limit: 10 });
const hits = await cms.search("local ai", { type: "BlogPost" });
await cms.getByPath("/blog/hello-world"); // hierarchical URLs
await cms.startPage(); // the requesting site's start page
await cms.global("SiteSettings");
const img = post!.data.image as unknown as string;
const src = mediaUrl(img, { w: 640, format: "webp" }); // server-side image variants
const srcset = mediaSrcset(img); // 320/640/1024/1600w webp
It also ships render helpers that read the delivered fieldTypes schema instead of
value-sniffing — renderRichText, renderKind, contentAreas, blockData,
pbAreaAttrs — so a frontend renders richtext/markdown/text correctly even when a field
is empty, and emits the right data-pb-* attributes for the preview bridge. 404s return
null; other errors throw a typed PaperboyError; etagCache: true gives free
conditional-GET caching. Full docs in its README. The SDK is
end-to-end tested against a live server in apps/api/test/client-sdk.test.ts.
@paperboycms/preview — on-page-editing bridge
npm install @paperboycms/preview
The browser-side bridge that makes any frontend visually editable inside the admin's preview iframe. Framework-agnostic, zero runtime dependencies, and the single source of truth for the postMessage protocol between admin and frontend (click-to-edit, drag-drop of shared blocks, live patching, focus highlighting — also across origins):
import { initPreviewBridge } from "@paperboycms/preview";
if (inPreviewMode) initPreviewBridge();
<h1 data-pb-field="heading">…</h1>
<div data-pb-area="contentarea">
<section data-pb-block-index="0" data-pb-block-type="CardBlock">…</section>
</div>
Mark editable DOM with data-pb-* attributes (or let the client SDK's pbAreaAttrs
emit them) and the admin lights up: clicks focus the right field, dropped blocks land in
the right area, edits patch live. Protocol and details in
its README. apps/web is the reference consumer.
Quickstart (Docker)
docker compose up -d # db → init(migrate+seed) → api → web → admin
# Admin http://localhost:8090 (admin@paperboy.test / Admin!Passw0rd)
# API http://localhost:8091 (OpenAPI UI at /docs)
# Web http://localhost:8092
⚠️ Redeploy one service with
docker compose up -d --no-deps --force-recreate <svc>. The seed CLI refuses to wipe a database that already holds content (setFORCE_SEED=1for a deliberate reseed) — but don't lean on the seatbelt. SeeCLAUDE.md.
🪟 Super-simple setup (Windows, no experience needed)
Never used a terminal before? Follow these steps exactly — copy/paste each command.
1. Install Docker Desktop
- Download it: https://www.docker.com/products/docker-desktop/
- Run the installer, click through with the defaults, then restart your PC if it asks.
- Open Docker Desktop from the Start menu and wait until the whale icon (bottom-left) says Engine running. Leave it open in the background.
2. Get Paperboy onto your PC
- Easiest way (no extra tools): go to the project page on GitHub, click the green Code button → Download ZIP, then right-click the downloaded file → Extract All….
- You now have a folder like
paperboycms. Remember where it is (e.g. your Downloads folder).
3. Open a terminal in that folder
- Open the
paperboycmsfolder in File Explorer. - Click the address bar at the top, type
powershell, and press Enter. A blue window opens — that's your terminal, already pointed at the right folder.
4. Start everything (one command)
- Copy this line, paste it into the blue window (right-click to paste), and press Enter:
docker compose up -d - The first run downloads things and takes a few minutes. When it finishes you'll get your prompt back.
5. Open the admin
- In your browser go to http://localhost:8090
- Log in with:
- Email:
admin@paperboy.test - Password:
Admin!Passw0rd
- Email:
That's it — you're running Paperboy. 🎉
Everyday commands (run them in the same blue window, inside the paperboycms folder):
- Stop it:
docker compose stop - Start it again later:
docker compose start - See it running: check Docker Desktop, or run
docker compose ps
⚠️ Don't run
docker compose down -vor re-run the setup once you've added content — it wipes everything and resets the login. Use stop/start instead.💡 If a page won't load, make sure Docker Desktop is open and says Engine running, then try again.
Develop locally
pnpm install
docker compose up -d db
export DATABASE_URL=postgresql://paperboy:paperboy@localhost:5433/paperboy
pnpm db:seed
pnpm dev # api :8091, admin :8090, web :8092
Test
pnpm --filter @paperboy/api test # integration tests (real Postgres)
pnpm --filter @paperboy/admin test:e2e # Playwright e2e + axe accessibility
CI also runs the MCP usability eval (evals/) on every push with a deterministic
--mock driver (real MCP tool calls, no paid API) and weekly with a real model — so
regressions in the agent surface are caught for free before an agent hits them.
MCP
# Mint a token in the admin (Settings → MCP), then:
MCP_TOKEN=mcp_… DATABASE_URL=postgresql://… pnpm --filter @paperboy/mcp start # stdio (local clients)
# …or serve it over Streamable HTTP for remote clients (Bearer = MCP_TOKEN):
MCP_TOKEN=mcp_… docker compose --profile mcp up -d --no-deps mcp # → http://<host>:8093/mcp
The MCP authenticates as a Paperboy user (token or email+password) and inherits its RBAC. The default transport is stdio; set MCP_HTTP_PORT (or use the compose mcp profile) to expose it over HTTP for remote clients.
Agent-ready by design
The MCP surface is hardened against the ways LLM agents actually fail — every one of these came out of running real agent workloads against it:
- No silent damage — input is either coerced meaning-preservingly (a TipTap doc sent to a markdown field becomes real Markdown,
{en: "…"}locale wrappers unwrap, a resolved asset object collapses to its id) or rejected with a self-teaching error that names the field, the expected shape, and a copyable example. A write never destroys content and reports success. - Serialization-proof writes —
set_field(documentId, field, value)writes one field as a flat string parameter, because long strings nested inside record arguments don't survive some clients' tool-call JSON repair (they arrive as{}). - Safe defaults —
update_contentmerges over the draft by default (a full replace that drops required fields would brick the next publish), and pages auto-slug from their name so agent-created content is always reachable. - A diagnosable trail — tool errors are logged with their arguments (
docker logs), and every MCP write lands in the same append-only audit log as the admin/API (ip=mcp). - Discoverable contract —
get_content_typeannotates every field withvalueFormat+valueExample, so an agent learns the exact JSON shape from the schema instead of by trial and error.
The full rules (with the war stories behind them) live in CLAUDE.md.
Seed accounts
admin@ Admin · editor@ Editor · author@ Author (section-scoped) · viewer@ Viewer — passwords follow <Role>!Passw0rd.
Seeded credentials, keys, and secrets are dev defaults — rotate them before exposing the CMS (
SESSION_SECRET,CSRF_SECRET, the delivery keys,PREVIEW_SECRET, and the admin password).
Docs
CLAUDE.md— how to develop & deploy safely (and how AI agents should work in the repo).STACK.md— the stack and the reasoning behind each choice.docs/POSITIONING.md— what Paperboy is for and who it's for.packages/client/README.md/packages/preview/README.md— the npm packages, in depth.
License
MIT — do what you like. Don't Pay eXtra. 📰