Booklet

Publique relatórios de incidentes em Markdown, ADRs, RFCs e runbooks como páginas web, com espaços de equipe.

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Booklet

Publique relatórios de incidentes, ADRs, RFCs e runbooks em Markdown como páginas web, com espaços de equipe.

Você escreve em Markdown, e o Booklet te dá uma página com um link. A página é tipografada, tem um sumário quando é longa o suficiente para precisar de um, e abre para qualquer pessoa para quem você enviar.

É feito para os documentos que equipes de engenharia compartilham entre si. Coloque type: incident (ou adr, rfc, runbook, postmortem, release-notes) no frontmatter e a página mostra status, severidade, data e responsáveis em uma faixa acima do título. [[ADR-012 Queue retries]] em um relatório de incidente linka para aquele ADR, e o ADR lista o incidente em "Referenciado por". Um espaço de equipe mantém os documentos de uma equipe juntos, agrupados por tipo, e uma página em um espaço pode ser restrita aos seus membros.

Há cinco formas de publicar, e todas produzem a mesma página: o editor web, a API REST, o pacote npm booklet-cli, uma GitHub Action e um servidor MCP para Claude e outros clientes MCP.

Ao vivo: booklet.ashwinsathian.com · Docs da API: /docs/reference/api · Configuração do MCP: /docs/guides/mcp

Início 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

Você recebe de volta a URL da página. O editor funciona sem conta, até 10 páginas por mês, cada uma servida por 90 dias. Uma conta (gratuita, e não há plano pago) remove ambos os limites. A CLI precisa de uma chave de API, e uma chave precisa de uma conta.

Recursos

Editor: pré-visualização ao vivo, rascunhos salvos no navegador e sincronizados com sua conta, importação de um arquivo ou URL do GitHub
Tipos de documento: frontmatter type, status, severity, date, owners e supersedes, exibidos em uma faixa de cabeçalho
Links entre páginas: [[Title]] resolve para uma página publicada no mesmo espaço de equipe, ou entre suas próprias páginas
Espaços de equipe: /t/<slug> lista as páginas de uma equipe por tipo, com um log de ADRs e um feed Atom de suas páginas públicas
Visibilidade: não listada (o padrão, não indexada), pública ou da equipe; uma senha por cima se você quiser
Páginas publicadas: sumário, tempo de leitura, temas claro e escuro, cinco temas de documento, embeds de <iframe> em /p/:id/embed
Matemática e diagramas: KaTeX ( $...$ , $$...$$), Mermaid e Graphviz em blocos de código cercados
Exportação: Markdown, HTML autocontido com diagramas e matemática desenhados, e Imprimir para PDF
Histórico de versões: 50 versões por página, um diff de linhas entre quaisquer duas, restaurar como uma nova versão
Analytics: visualizações por página, quantos leitores alcançaram 50% e 100%, referenciadores
URLs personalizadas: um endereço como /p/my-release-notes
Webhooks: page.published e page.updated, assinados, com um log das últimas 50 entregas
API REST: publicar, atualizar, listar e excluir páginas; OpenAPI 3.1 em /api/v1/openapi.json
CLI: booklet-cli no npm, com saída --json e códigos de saída para scripts
GitHub Action: AshwinSathian/publish-to-booklet
Servidor MCP: sete ferramentas e seis prompts, com login OAuth ou chave de API
Contas: e-mail e senha, chaves de acesso e login com GitHub ou Google onde o host os configurou

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

Veja packages/cli/README.md para a documentação completa (todas as flags, autenticação CI/não interativa via --key ou BOOKLET_API_KEY, pages open, etc.).

API REST

Todos os endpoints estão sob /api/v1/ e autenticados com Authorization: Bearer <bklt_...>.

Método	Caminho	Descrição
`POST`	`/api/v1/publish`	Criar uma nova página
`GET`	`/api/v1/pages`	Listar suas páginas
`GET`	`/api/v1/pages/:id`	Ler os metadados e o conteúdo bruto de uma página
`PATCH`	`/api/v1/pages/:id`	Atualizar conteúdo, slug ou visibilidade
`DELETE`	`/api/v1/pages/:id`	Excluir uma página

As chaves de API são criadas e excluídas no navegador, em Configurações, Chaves de API. Elas não fazem parte desta API.

Exemplo de publicação:

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 é um segundo hostname para a API, servido pelo mesmo aplicativo (veja docs/OPERATIONS.md). booklet.ashwinsathian.com/api/v1 é a mesma API e é o endereço que a documentação usa.

Referência completa de endpoints com formatos de requisição/resposta: booklet.ashwinsathian.com/docs/reference/api.

Servidor MCP

Um processo Node (mcp-server/) que dá a clientes Model Context Protocol acesso à API do Booklet. Ele roda sob PM2 ao lado do aplicativo principal e fala o protocolo 2026-07-28 via Streamable HTTP.

Endpoint: https://booklet-mcp.ashwinsathian.com/mcp Autenticação: login OAuth com sua conta Booklet, ou um cabeçalho Authorization: Bearer <bklt_...> (as mesmas chaves de API da API REST) Ferramentas: publish_page, update_page, get_page, list_pages, delete_page, create_document, search_pages Recursos: suas páginas publicadas, como booklet://pages/:id Prompts: cinco modelos de documento que o assistente pode preencher e publicar: incident_report, adr, release_notes, rfc e runbook

Aponte um cliente MCP para o endpoint acima. Um cliente que suporta OAuth (um conector personalizado do Claude.ai, por exemplo) faz login com sua conta Booklet; os demais enviam sua chave de API no cabeçalho Authorization. booklet.ashwinsathian.com/docs/guides/mcp tem configuração pronta para copiar e colar para Claude Desktop, Claude.ai, Cursor, Windsurf, VS Code e Zed.

Para executar o servidor localmente:

cd mcp-server && npm run dev

Pilha de tecnologia

Camada	Tecnologia
Framework	Next.js 16 (App Router)
Linguagem	TypeScript 5 (estrito)
Estilização	Tailwind CSS v4
Autenticação	Própria (e-mail + senha com argon2id, chaves de acesso, login opcional com GitHub e Google, sessões baseadas em banco de dados)
Banco de dados	MongoDB auto-hospedado (páginas, usuários, chaves de API, webhooks, documentos renderizados)
Implantação	PM2 (`ecosystem.config.js`)
Markdown	unified + remark-parse + remark-gfm + remark-math
Matemática	KaTeX
Diagramas	Mermaid, Graphviz (`@viz-js/viz`)
Analytics	Visualizações de página e profundidade de leitura, contadas pelo próprio aplicativo (MongoDB)

Desenvolvimento local

Pré-requisitos

Node.js 24 (veja .nvmrc)
String de conexão MongoDB (um mongod local, ou qualquer instância auto-hospedada/gerenciada)

Instalar e executar

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

Variáveis de ambiente

Crie .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>

Veja .env.example para a lista completa de segredos necessários (autenticação de sessão, chaves de API, tokens de senha de página, etc.). Cada um documenta seu próprio comando de geração e comportamento de falha segura.

Execute sua própria cópia

O Booklet é um aplicativo Next.js, um banco de dados MongoDB e, se você quiser clientes MCP, mais um processo Node.

Node.js 24 e uma string de conexão MongoDB.
Copie .env.example para .env.production.local e preencha cada segredo marcado como necessário. Defina NEXT_PUBLIC_SITE_URL para o endereço que as pessoas usarão.
npm ci && npm run build && npm start serve o aplicativo na porta 3000 (npm start -- -p 3100 para outra porta).
O servidor MCP é mcp-server/. ecosystem.config.js inicia ambos sob PM2, o aplicativo na porta 3100, depois que você alterar BASE e NODE_BIN no topo do arquivo para seus próprios caminhos.
Aponte a CLI para sua cópia com BOOKLET_API_URL=https://your-host.

E-mail (confirmação, redefinição de senha, convites de equipe) precisa de RESEND_API_KEY; sem ele, contas funcionam não confirmadas e um convite é um link que o proprietário envia. O login com GitHub e Google aparece quando o ID do cliente e o segredo de um provedor estão definidos. O aplicativo é AGPL-3.0: se você o modificar e executá-lo para outras pessoas, a seção 13 exige que você ofereça a elas seu código-fonte.

Implantar

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

Estrutura do projeto

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

Todo push/PR para main executa lint, typecheck (aplicativo raiz + cada pacote do workspace), uma build de produção e a suíte de testes unitários contra um contêiner de serviço MongoDB real. Veja .github/workflows/ci.yml.

Publicação automática no npm

Push para main com uma versão incrementada em packages/cli/package.json ou packages/shared/package.json → publica automaticamente booklet-cli ou booklet-api-client no npm.

Segredo necessário: NPM_TOKEN (Granular Access Token com publicação + bypass de 2FA).

Publique documentação no Booklet a partir do seu repositório

Duas formas: a GitHub Action AshwinSathian/publish-to-booklet, ou booklet-cli via npx. Veja .github/examples/publish-to-booklet.yml para ambas. Copie-o para o .github/workflows/ do seu próprio repositório, adicione um segredo BOOKLET_API_KEY e ele publica a cada release.

Licença

O Booklet tem duas licenças, divididas por diretório.

Caminho	Licença
Tudo que não está listado abaixo (o aplicativo Next.js em `src/`, `scripts/`, `tests/`, `docs/`)	AGPL-3.0-only
`packages/cli` (`booklet-cli`)	MIT
`packages/shared` (`booklet-api-client`)	MIT
`mcp-server`	MIT

A GitHub Action publish-to-booklet vive em seu próprio repositório e é MIT.

O aplicativo era MIT até e incluindo o commit 1839525. Esse commit e tudo antes dele ainda podem ser usados sob MIT. Commits posteriores ao aplicativo são AGPL-3.0-only: se você executar uma cópia modificada como um serviço de rede, a seção 13 exige que você ofereça o código-fonte aos seus usuários.