Documentei MCP + plugins

Servidor MCP que deixa qualquer agente de IA (Claude Code, Codex) fazer CRUD completo de docs, changelog, seções e políticas do seu projeto no Documentei. Tudo nasce como rascunho — a IA escreve, você publica.

Um repo, três entregas:

• @documentei/mcp (src/) — o motor MCP, publicado no npm.
• plugin Claude Code (.claude-plugin/) — este repo também é seu próprio marketplace.
• plugin Codex (.codex-plugin/) — pronto pra quando o marketplace do Codex abrir.

v2.0.0 (breaking): as 6 tools da v1 (read_changelog, upsert_doc_page, …) foram substituídas pelas tools explícitas por operação abaixo. Updates são parciais e omitir publish preserva a publicação atual (não despublica ao editar).

Tools

CRUD por entidade. Listas são enxutas (sem conteúdo) e paginadas por cursor; use *_get para o conteúdo completo.

| Grupo | Tools | |---|---| | Changelog | changelog_list, changelog_get, changelog_create, changelog_update, changelog_delete, changelog_set_published | | Páginas de doc | doc_list, doc_get, doc_create, doc_update, doc_delete, doc_move, doc_set_published | | Seções | section_list, section_create, section_update, section_delete, section_reorder | | Políticas | policy_get, policy_upsert, policy_set_published |

doc_create aceita kind (page/group) + parentId para montar a árvore; doc_move reposiciona. *_set_published publica/despublica por id sem mexer no conteúdo.

Configuração

| Env | Obrigatória | Default | Descrição | |---|---|---|---| | DOCUMENTEI_API_KEY | sim | — | A apiKey do seu projeto (1 chave = 1 projeto). Gere em Configurações do projeto → API. | | DOCUMENTEI_API_BASE | não | https://documentei-app.vercel.app | Base da API. Já aponta pra prod hospedada — defina só se rodar uma instância própria (ex.: http://localhost:3000 em dev). | | DOCUMENTEI_API_TIMEOUT_MS | não | 15000 | Timeout por chamada (com 1 retry em 429/5xx). |

Conectar

Claude Code

/plugin marketplace add AlexxAlmeida/documentei_plugin
/plugin install documentei

Depois exporte as envs no shell (o .mcp.json do plugin lê DOCUMENTEI_API_KEY do ambiente):

export DOCUMENTEI_API_KEY=sk_xxx
export DOCUMENTEI_API_BASE=https://documentei-app.vercel.app

Codex (caminho universal hoje)

codex mcp add documentei \
  -e DOCUMENTEI_API_KEY=sk_xxx \
  -e DOCUMENTEI_API_BASE=https://documentei-app.vercel.app \
  -- npx -y @documentei/mcp

O compartilhamento de plugins por marketplace no Codex está disponível só pra ChatGPT Business hoje. O .codex-plugin/ já está pronto pra quando abrir; até lá, use o codex mcp add acima.

Dev / teste local

pnpm install
pnpm build
# servidor isolado no MCP Inspector:
DOCUMENTEI_API_KEY=sk_test npx @modelcontextprotocol/inspector node dist/index.js
# plugin local no Claude Code:
#   /plugin marketplace add /caminho/absoluto/documentei-plugin
#   /plugin install documentei

Backend (client/)

As tools batem na API autenticada /api/v1/* do app Documentei (client/), resolvida por Authorization: Bearer <apiKey> e escopada por projeto. O corpo manda content em Markdown + format: "MARKDOWN". Auth, rate limit (leitura 60/60s, escrita 240/60s) e o contrato CRUD completo já estão implementados no client/.

Publicar

Duas entregas, dois canais. O npm vem primeiro — o plugin roda npx @documentei/mcp, então sem o pacote no registry nada conecta.

# 1. motor MCP no npm (prepublishOnly já roda o build)
npm login
npm publish --access public          # @documentei/mcp

# 2. o repo vira o marketplace do Claude Code
git push -u origin main

Bump de versão: mantenha package.json, .claude-plugin/plugin.json e .codex-plugin/plugin.json na mesma versão antes de publicar.

Licença

MIT.