@harpix/doc-api-mcp

MCP da harpix para documentar APIs no modelo da harpix. Extrai o schema da fonte oficial (OpenAPI, dicionario), verifica campo inventado, e publica no Confluence. Replicavel em qualquer maquina: instala com um comando.

Vai usar a ferramenta? Leia o GUIA-DE-USO.md, que cobre o fluxo de trabalho completo passo a passo. O README abaixo é a visão do pacote.

O que ele faz

Empacota como ferramentas de MCP o trabalho que hoje e feito na mao:

• discover_api — porta de entrada: recebe o link do site de documentacao de qualquer API e descobre a fonte (spec no proprio link, declarado no HTML por Redoc/Swagger UI/Scalar/RapiDoc, dentro dos scripts da pagina, ou nos caminhos convencionais do dominio). Diz na cara quando nao existe spec.
• fetch_openapi — baixa um spec OpenAPI, JSON ou YAML, e lista as operacoes.
• get_operation — extrai uma operacao com deref de $ref: campos, tipos, obrigatorios, exemplos, respostas.
• verify_against_source — confere todo campo citado no rascunho contra a fonte; acusa campo inventado.
• publish_confluence — cria ou atualiza uma pagina no Confluence (REST v2).

E carrega o metodo (modelo da harpix) como resource/prompt doc_api_method, entao o agente e autossuficiente em qualquer cliente Claude.

Divisao em 3 camadas

1. MCP (este pacote): as ferramentas deterministicas + o metodo.
2. Modelo: o julgamento, redigir e revisar.
3. Usuario: aprova o rascunho antes de publicar.

Instalar (um comando, sem login)

O pacote esta publicado no npm publico. Quem instala nao precisa de git, nem de npm login, nem de acesso a repo. So precisa de Node 18+.

Passo unico, um comando so no terminal (cmd ou PowerShell). Ele registra o MCP e ja abre o Claude pronto pra usar:

npx -y hpx-doc-api-mcp setup

Passo 2, reiniciar o Claude Code e digitar /mcp para ver doc-api conectado.

Passo 3, conectar o Confluence. Digite /mcp no Claude Code e adicione o conector do Atlassian. Ele abre o navegador pra voce logar com a sua conta e autorizar. Sem API token, sem credencial em arquivo: voce publica com as permissoes que ja tem.

Esse e o caminho recomendado, e o unico usado na harpix, onde o Confluence e gerido pela empresa e o time nao tem acesso a chave de API.

Publicacao: conector do Atlassian

A publicacao no Confluence e feita pelo MCP oficial do Atlassian, nao por este pacote. A divisao fica assim:

• doc-api (este pacote): extrai o schema da fonte e verifica campo inventado.
• conector do Atlassian: le e escreve as paginas do Confluence.

As tools set_confluence e publish_confluence deste pacote, que dependem de API token, seguem disponiveis para quem tem token proprio, mas estao em modo legado e devem sair numa versao futura.

Roadmap

• v0.1: extracao, verificacao, publish. (atual)
• v0.2: render_pdf (puppeteer, Chromium embutido), parse_sankhya_dict.
• v0.3: classify_layout e cross_reference (assertividade por origem).