Booklet

Publica informes de incidentes en Markdown, ADRs, RFCs y runbooks como páginas web, con espacios de equipo.

Servidor MCP alojado

npx add-mcp 'https://booklet-mcp.ashwinsathian.com/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Booklet

Publica informes de incidentes, ADRs, RFCs y runbooks de Markdown como páginas web, con espacios de equipo.

Escribes Markdown, y Booklet te da una página con un enlace. La página está maquetada, tiene una tabla de contenidos cuando es lo suficientemente larga como para necesitarla, y se abre para cualquiera a quien se la envíes.

Está construido para los documentos que los equipos de ingeniería se pasan entre sí. Pon type: incident (o adr, rfc, runbook, postmortem, release-notes) en el frontmatter y la página muestra estado, severidad, fecha y responsables en una franja sobre el título. [[ADR-012 Queue retries]] en un informe de incidente enlaza a ese ADR, y el ADR lista el incidente bajo "Referenciado por". Un espacio de equipo mantiene los documentos de un equipo juntos, agrupados por tipo, y una página en uno puede restringirse a sus miembros.

Hay cinco formas de publicar, y todas producen la misma página: el editor web, la API REST, el paquete npm booklet-cli, una GitHub Action, y un servidor MCP para Claude y otros clientes MCP.

En vivo: booklet.ashwinsathian.com · Documentación de API: /docs/reference/api · Configuración de MCP: /docs/guides/mcp

Inicio rápido

npm install -g booklet-cli
booklet login                            # opens your browser to authorize
booklet publish README.md --open         # publish this file, open it in your browser

Recibes la URL de la página. El editor funciona sin cuenta, hasta 10 páginas al mes, cada una servida durante 90 días. Una cuenta (gratuita, y no hay plan de pago) elimina ambos límites. La CLI necesita una clave de API, y una clave necesita una cuenta.

Características

Editor: vista previa en vivo, borradores guardados en el navegador y sincronizados con tu cuenta, importación desde un archivo o una URL de GitHub
Tipos de documento: frontmatter type, status, severity, date, owners y supersedes, mostrados en una franja de cabecera
Enlaces entre páginas: [[Title]] se resuelve a una página publicada en el mismo espacio de equipo, o entre tus propias páginas
Espacios de equipo: /t/<slug> lista las páginas de un equipo por tipo, con un registro de ADR y un feed Atom de sus páginas públicas
Visibilidad: no listada (la predeterminada, no indexada), pública o de equipo; una contraseña encima si la quieres
Páginas publicadas: tabla de contenidos, tiempo de lectura, temas oscuro y claro, cinco temas de documento, <iframe> incrustados en /p/:id/embed
Matemáticas y diagramas: KaTeX ( $...$ , $$...$$), Mermaid y Graphviz en bloques de código delimitados
Exportación: Markdown, HTML autocontenido con diagramas y matemáticas dibujadas, e Imprimir a PDF
Historial de versiones: 50 versiones por página, un diff de líneas entre dos cualesquiera, restaurar como nueva versión
Analíticas: vistas por página, cuántos lectores alcanzaron el 50% y el 100%, referentes
URLs personalizadas: una dirección como /p/my-release-notes
Webhooks: page.published y page.updated, firmados, con un registro de las últimas 50 entregas
API REST: publicar, actualizar, listar y eliminar páginas; OpenAPI 3.1 en /api/v1/openapi.json
CLI: booklet-cli en npm, con salida --json y códigos de salida para scripts
GitHub Action: AshwinSathian/publish-to-booklet
Servidor MCP: siete herramientas y seis prompts, con inicio de sesión OAuth o una clave de API
Cuentas: correo electrónico y contraseña, passkeys, e inicio de sesión con GitHub o Google donde el host los haya configurado

CLI

npm install -g booklet-cli

booklet login                          # save your API key
booklet publish README.md              # publish a file
booklet publish README.md --watch      # watch + auto-republish on save
booklet publish - < NOTES.md           # from stdin
booklet pages list                     # list your pages

Consulta packages/cli/README.md para la documentación completa (todas las banderas, autenticación CI/no interactiva mediante --key o BOOKLET_API_KEY, pages open, etc.).

API REST

Todos los endpoints están bajo /api/v1/ y se autentican con Authorization: Bearer <bklt_...>.

Método	Ruta	Descripción
`POST`	`/api/v1/publish`	Crear una nueva página
`GET`	`/api/v1/pages`	Listar tus páginas
`GET`	`/api/v1/pages/:id`	Leer los metadatos y el contenido bruto de una página
`PATCH`	`/api/v1/pages/:id`	Actualizar contenido, slug o visibilidad
`DELETE`	`/api/v1/pages/:id`	Eliminar una página

Las claves de API se crean y eliminan en el navegador, en Configuración, Claves de API. No forman parte de esta API.

Ejemplo de publicación:

curl -X POST https://booklet-api.ashwinsathian.com/api/v1/publish \
  -H "Authorization: Bearer bklt_..." \
  -H "Content-Type: application/json" \
  -d '{"raw": "# Hello\n\nThis is my page."}'

booklet-api.ashwinsathian.com es un segundo nombre de host para la API, servido por la misma aplicación (ver docs/OPERATIONS.md). booklet.ashwinsathian.com/api/v1 es la misma API, y es la dirección que usan los documentos.

Referencia completa de endpoints con formas de solicitud/respuesta: booklet.ashwinsathian.com/docs/reference/api.

Servidor MCP

Un proceso Node (mcp-server/) que da a los clientes Model Context Protocol la API de Booklet. Se ejecuta bajo PM2 junto a la aplicación principal y habla el protocolo 2026-07-28 sobre Streamable HTTP.

Endpoint: https://booklet-mcp.ashwinsathian.com/mcp Autenticación: inicio de sesión OAuth con tu cuenta de Booklet, o una cabecera Authorization: Bearer <bklt_...> (las mismas claves de API que la API REST) Herramientas: publish_page, update_page, get_page, list_pages, delete_page, create_document, search_pages Recursos: tus páginas publicadas, como booklet://pages/:id Prompts: cinco plantillas de documento que el asistente puede rellenar y publicar: incident_report, adr, release_notes, rfc y runbook

Apunta un cliente MCP al endpoint anterior. Un cliente que soporte OAuth (un conector personalizado de Claude.ai, por ejemplo) inicia sesión con tu cuenta de Booklet; el resto envía tu clave de API en la cabecera Authorization. booklet.ashwinsathian.com/docs/guides/mcp tiene configuración de copiar y pegar para Claude Desktop, Claude.ai, Cursor, Windsurf, VS Code y Zed.

Para ejecutar el servidor localmente:

cd mcp-server && npm run dev

Pila tecnológica

Capa	Tecnología
Framework	Next.js 16 (App Router)
Lenguaje	TypeScript 5 (estricto)
Estilos	Tailwind CSS v4
Autenticación	Propia (correo + contraseña con argon2id, passkeys, inicio de sesión opcional con GitHub y Google, sesiones respaldadas por base de datos)
Base de datos	MongoDB autoalojado (páginas, usuarios, claves de API, webhooks, documentos renderizados)
Despliegue	PM2 (`ecosystem.config.js`)
Markdown	unified + remark-parse + remark-gfm + remark-math
Matemáticas	KaTeX
Diagramas	Mermaid, Graphviz (`@viz-js/viz`)
Analíticas	Vistas de página y profundidad de lectura, contadas por la propia aplicación (MongoDB)

Desarrollo local

Prerrequisitos

Node.js 24 (ver .nvmrc)
Cadena de conexión de MongoDB (un mongod local, o cualquier instancia autoalojada/gestionada)

Instalar y ejecutar

npm install
npm run dev        # Next.js dev server at http://localhost:3000

Variables de entorno

Crea .env.local:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
MONGODB_URI=mongodb://localhost:27017/booklet

# Required: dedicated secret that signs/verifies team-invite JWT tokens.
# Must be its own random value; there is no fallback, and invite creation
# and joining fail closed if this is unset. Generate with: openssl rand -base64 32
INVITE_JWT_SECRET=<random-secret>

Consulta .env.example para la lista completa de secretos requeridos (autenticación de sesión, claves de API, tokens de contraseña de página, etc.). Cada uno documenta su propio comando de generación y comportamiento de cierre ante fallos.

Ejecutar tu propia copia

Booklet es una aplicación Next.js, una base de datos MongoDB y, si quieres clientes MCP, un proceso Node más.

Node.js 24 y una cadena de conexión de MongoDB.
Copia .env.example a .env.production.local y rellena cada secreto marcado como requerido. Establece NEXT_PUBLIC_SITE_URL a la dirección que usará la gente.
npm ci && npm run build && npm start sirve la aplicación en el puerto 3000 (npm start -- -p 3100 para otro puerto).
El servidor MCP es mcp-server/. ecosystem.config.js inicia ambos bajo PM2, la aplicación en el puerto 3100, una vez que cambies BASE y NODE_BIN al principio del archivo a tus propias rutas.
Apunta la CLI a tu copia con BOOKLET_API_URL=https://your-host.

El correo electrónico (confirmación, restablecimiento de contraseña, invitaciones de equipo) necesita RESEND_API_KEY; sin él las cuentas funcionan sin confirmar y una invitación es un enlace que envía el propietario. El inicio de sesión con GitHub y Google aparece cuando se establecen el ID de cliente y el secreto de un proveedor. La aplicación es AGPL-3.0: si la modificas y la ejecutas para otras personas, la sección 13 requiere que les ofrezcas tu código fuente.

Desplegar

npm run deploy     # rebuilds and restarts the PM2-managed app + MCP server (scripts/redeploy.sh)

Estructura del proyecto

src/
  app/
    app/            # Editor (client)
    p/[id]/         # Share page + embed
    my-pages/       # Dashboard: pages and folders, version history, analytics
    settings/       # Account, API keys, webhooks and their delivery log
    api/v1/         # REST API
    explore/        # Public page directory
    templates/      # Template landing pages
  components/
    blocks/         # BlockRenderer + InlineRenderer (custom AST renderer)
    share/          # TOC, export, embed, reading progress, analytics beacon
    ui/             # Design system components
  lib/
    blocks.ts       # Block/Inline type definitions
    parse.ts        # Markdown → Block[] (unified pipeline)
    db/             # MongoDB helpers
    storage.ts      # Document content storage (MongoDB)
    quota.ts        # Feature flags
    frontmatter.ts  # YAML frontmatter parser (js-yaml)
packages/           # npm workspaces; one root lockfile covers all of these
  shared/           # booklet-api-client: shared /api/v1 schemas + client
  cli/              # booklet-cli npm package
mcp-server/         # MCP server (plain Node process, run under PM2)
.github/
  workflows/        # ci.yml, publish-cli.yml, publish-shared.yml
  examples/         # publish-to-booklet.yml, use in your own repo

GitHub Actions

CI

Cada push/PR a main ejecuta lint, typecheck (aplicación raíz + cada paquete del workspace), una compilación de producción y la suite de pruebas unitarias contra un contenedor de servicio MongoDB real. Ver .github/workflows/ci.yml.

Publicación automática a npm

Push a main con una versión incrementada en packages/cli/package.json o packages/shared/package.json → publica automáticamente booklet-cli o booklet-api-client a npm.

Secreto requerido: NPM_TOKEN (Granular Access Token con publicación + omisión de 2FA).

Publicar documentos a Booklet desde tu repositorio

Dos formas: la AshwinSathian/publish-to-booklet GitHub Action, o booklet-cli mediante npx. Ver .github/examples/publish-to-booklet.yml para ambas. Cópialo en tu propio .github/workflows/ del repositorio, añade un secreto BOOKLET_API_KEY, y publica en cada release.

Licencia

Booklet tiene dos licencias, divididas por directorio.

Ruta	Licencia
Todo lo no listado abajo (la aplicación Next.js en `src/`, `scripts/`, `tests/`, `docs/`)	AGPL-3.0-only
`packages/cli` (`booklet-cli`)	MIT
`packages/shared` (`booklet-api-client`)	MIT
`mcp-server`	MIT

La publish-to-booklet GitHub Action vive en su propio repositorio y es MIT.

La aplicación fue MIT hasta e incluyendo el commit 1839525. Ese commit y todo lo anterior aún puede usarse bajo MIT. Los commits posteriores a la aplicación son AGPL-3.0-only: si ejecutas una copia modificada como servicio de red, la sección 13 requiere que ofrezcas el código fuente a sus usuarios.