DocGen MCP Server

O que é

Servidor Model Context Protocol (MCP) via stdio para leitura e escrita de documentos, planilhas, renderização HTML→PDF (Puppeteer) e utilitários de arquivo. Está publicado no npm como docgen-mcp-server e requer Node.js 18+.

Recomenda-se executar com npx -y docgen-mcp-server@latest para o npx resolver sempre o dist-tag latest (evita reutilizar cache de instalação antiga). Para travar em uma versão: docgen-mcp-server@<versão> no lugar de @latest.

Na primeira execução, Puppeteer pode baixar Chromium (tools render_slide e render_page).

Ferramentas

| Módulo | Ferramenta | Descrição resumida | |--------|------------|-------------------| | read_ | read_doc | .docx/.pdf/.odt → Markdown; previewOnly / maxChars limitam saída. | | | read_sheet | Planilhas → JSON ou Markdown; range tipo A1:D10; previewOnly / maxRows. | | | read_archive | Lista árvore de entradas em .zip. | | write_ | write_doc | .docx/.pdf; Markdown (#, listas, ```) ou contentFormat: plain; template {{campo}}. | | | write_sheet | .xlsx ou .csv; append em .xlsx para logs. | | render_ | render_slide | HTML/CSS → PDF ou ZIP de slides (use .slide por página). | | | render_page | HTML/CSS → PDF A4 (índice opcional). | | patch_ | patch_doc | PDF: merge, split, watermark; DOCX: replace_text em XML. | | | patch_sheet | Atualiza células em .xlsx. | | system_ | scan_dir | Busca por regex em diretório ou em arquivos/ZIPs. | | | diff_file | Diff texto ou dados (planilhas). | | | bundle_zip | Compacta lista de arquivos em um ZIP. |

Segurança

• Sem .. nos caminhos; leitura limitada por tamanho de ficheiro.
• Escrita bloqueada em pastas do sistema (ex.: Windows, Program Files, .ssh, .aws no home).
• Opcional: DOCGEN_ALLOWED_ROOTS — lista separada por vírgulas de pastas absolutas; só é permitido ler/escrever dentro delas (útil em monorepos/CI).

Variáveis de ambiente (opcional)

| Variável | Efeito | |----------|--------| | DOCGEN_ALLOWED_ROOTS | Ex.: C:\repo\my-app,C:\tmp — restrição de caminhos. | | DOCGEN_SCAN_MAX_MATCHES | Máximo de correspondências em scan_dir (padrão 500). | | DOCGEN_READ_SHEET_MAX_ROWS | Teto de linhas de dados em read_sheet quando não usas maxRows (padrão 10000). |

Erros das tools devolvem structuredContent com ok: false, code, tool, message e às vezes hint.

Como usar nos clientes (recomendado: npm publicado)

Em qualquer cliente MCP com transporte stdio:

• Comando: npx (no Windows, se necessário, use o caminho completo de npx.cmd).
• Argumentos: ["-y", "docgen-mcp-server@latest"] (ou versão fixa: ["-y", "[email protected]"]).
• Variáveis de ambiente: opcional; veja variáveis do Puppeteer/Chromium se precisar de proxy ou caminho de browser.

Exemplo (Cursor, VS Code com MCP, Claude Desktop, etc.):

{
  "mcpServers": {
    "docgen": {
      "command": "npx",
      "args": ["-y", "docgen-mcp-server@latest"],
      "env": {}
    }
  }
}

No repositório há um exemplo em .cursor/mcp.json.example.

Cursor

Configurações → MCP (ou JSON de MCP do projeto): use command, args e env como acima.

Claude Desktop

Mesmo esquema de command, args e env. Detalhes de caminho do arquivo de configuração variam por SO; veja a documentação da Anthropic sobre MCP.

Problemas comuns no Windows com npx

Se aparecer EPERM, TAR_ENTRY_ERROR ou erros tipo Cannot find package '...\node_modules\yauzl\index.js', o cache do npx costuma estar corrompido (extração interrompida quando o Cursor recarrega o MCP no meio do npm install).

1. Desligue ou desative temporariamente o servidor Docgen no MCP.
2. Apague %LocalAppData%\npm-cache\_npx (pasta inteira ou só o subdiretório do pacote).
3. Suba o MCP de novo com npx -y docgen-mcp-server@latest.

Alternativa estável: npm install -g docgen-mcp-server e no MCP use command: docgen-mcp-server (sem npx), ou node com o caminho absoluto do cli.js global.

Desenvolvimento a partir do clone

git clone <repo>
cd docgen-mcp-server
npm install
npm run build
npm start

Sem build prévio (local):

npm install
npm run dev

| Script | Ação | |--------|------| | npm run build | Compila src/ → dist/ (tsc) | | npm start | node dist/cli.js | | npm run dev | tsx src/cli.ts |

Publicação no npm (mantenedores)

O pacote não inclui node_modules; o tarball contém só dist/ + README.md + package.json (dependências são instaladas pelo cliente ao rodar npx).

npm whoami
npm publish --dry-run
npm publish

Se a conta tiver 2FA “Auth and writes”, o npm exige OTP:

npm publish --otp=123456

Erro 403 Forbidden com nome livre costuma ser: OTP ausente, npm login em outra conta, ou registro apontando para outro servidor (npm config get registry deve ser https://registry.npmjs.org/).

Versões subsequentes (como no Nautilus):

npm run release        # patch
npm run release:minor
npm run release:major

Licença

ISC