Como humanizar um documento do Word dentro do Claude Code

O HumanPen fornece um servidor MCP stdio local. Todo cliente inicia o mesmo comando, `npx -y humanpen-mcp`, com uma variável de ambiente que guarda a chave de API. O agente envia um caminho absoluto para um `.docx` em vez do texto, então o documento nunca entra na janela de contexto, e o arquivo reescrito é gravado de volta no disco.

Não há endpoint remoto nem wrapper de gateway na frente. Se você já usou `mcp-remote` ou `supergateway` para outros servidores, aqui não vai precisar de nenhum dos dois.

O desenho óbvio é receber uma string e devolver uma string. Também é o desenho que desmorona exatamente nos documentos que as pessoas de fato querem reescrever.

Um `.docx` é um zip de partes XML. Ler os bytes dentro de uma conversa não dá nada aproveitável, e descompactá-los no contexto descarta justamente a estrutura que fazia valer a pena mantê-los como arquivo: estilos de título, objetos de tabela, partes de notas de rodapé, os campos por trás de um sumário. Achatar uma tese até virar uma string, reescrever a string, e você resolveu o problema errado. Campos do Word, sumários e referências cruzadas mostra o custo dessa ida e volta.

Então a chamada da ferramenta leva um caminho na entrada e um caminho na saída. O arquivo é enviado por HTTPS, processado, e o resultado é gravado de volta no seu disco. Nada grande toca a sua janela de contexto.

O caminho mais rápido é deixar o agente fazer. A página de desenvolvedores entrega uma linha pronta para copiar que aponta o seu cliente para o guia de instalação do MCP; cole, e o agente busca o guia, descobre qual arquivo de configuração o seu cliente lê e pede uma chave.

Na mão, no Claude Code é uma linha:

claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp

O `-s user` importa mais do que parece. O escopo padrão é `local`, que registra o servidor apenas para o diretório em que você rodou o comando. No dia seguinte você abre o Claude Code em outro lugar, não encontra nenhuma ferramenta do HumanPen e conclui, com toda a razão, que a instalação falhou.

O Codex lê `~/.codex/config.toml`, onde o mesmo servidor é uma tabela `[mcp_servers.humanpen]` com `command = "npx"`, `args = ["-y", "humanpen-mcp"]` e `env = { HUMANPEN_API_KEY = "hp_your_key" }`. O guia de instalação tem o bloco para copiar.

Cursor, Windsurf, Cline e Claude Desktop assumem a mesma forma nos seus próprios arquivos de configuração. Uma armadilha nos aplicativos de desktop: coloque o caminho absoluto até `npx` em `command`. Rode `which npx` e use o resultado. O sistema operacional inicia esses aplicativos com um `PATH` mínimo, o nome simples muitas vezes não é encontrado, e o único sintoma é que as ferramentas não aparecem nunca.

Depois de reiniciar, oito ferramentas aparecem. A que interessa neste post é `humanize_document`; `read_detection_report` e `check_job` são as duas que dão suporte a ela.

O motivo para fazer isso por um agente em vez de um formulário web é que o agente já tem os seus arquivos, incluindo o relatório de detecção que está na mesma pasta.

Entregue os dois ao trabalho. Quando há um relatório anexado e nenhuma lista explícita de trechos é fornecida, os trechos marcados nesse relatório se tornam o escopo da reescrita e todo o resto do documento fica intocado. Se você der uma lista explícita, essa lista é definitiva, e o relatório fica apenas como anexo do trabalho. Pela API REST, a mesma coisa fica assim, contra a raiz de API que a página de desenvolvedores mostra:

curl -X POST "$HP_API_ROOT/jobs/humanize" -H "Authorization: Bearer $HP_API_KEY" -F "file=@paper.docx" -F "turnitin_file=@turnitin-report.pdf" -F "strategy=balanced" -F "additional_instructions=Keep terminology and citations unchanged."

Os créditos são contados sobre as palavras efetivamente reescritas, então um trabalho delimitado por um relatório com quatro parágrafos marcados custa como quatro parágrafos. Os caminhos Skill, MCP e API consomem o mesmo saldo, e um trabalho que não chega ao fim não é cobrado.

O modelo nunca vê o resultado.

O que uma chamada concluída devolve é um recibo do trabalho: onde o arquivo foi gravado, quanto custou, como o número de palavras se moveu. Nenhum conteúdo, nenhum diff. Tudo o que você queria direcionar precisa estar escrito na string de instruções antes de o trabalho começar, no escuro.

A resposta usual é que o cliente tem uma ferramenta de leitura de arquivo, então o agente pode simplesmente ler o resultado. Ele pode ler as palavras: cinco linhas de `python-docx` puxam o texto dos parágrafos e comparam com o original. O que ele não consegue ler é se a formatação sobreviveu, e a formatação é o motivo pelo qual você mandou um arquivo em vez de uma string. Então o agente pode dizer que um trabalho foi concluído, quanto custou e o que o texto diz agora. Não pode dizer se a tabela da página 7 chegou inteira.

Essa verificação é sua, no Word, e é a mesma verificação de depois de qualquer reescrita: atualizar campos, contar entradas bibliográficas, ler as células com números. Como revisar um documento do Word humanizado antes de enviar traz a versão completa.

Reescrever um documento real leva minutos, o que é desajeitado dentro de um protocolo feito para chamadas rápidas. Uma chamada espera cerca de 55 segundos e depois devolve um id de trabalho em vez de um arquivo. O trabalho continua rodando no servidor, e `check_job` o retoma.

Duas coisas seguem disso, e ambas valem saber antes de construir um loop em volta. Se o timeout do seu próprio cliente for mais curto que a espera, a requisição morre do seu lado enquanto o trabalho continua do nosso, e a saída é `check_job` com o id que você não recebeu.

E uma chamada que devolve um arquivo e uma chamada que devolve um id são a mesma chamada, então qualquer automação em volta precisa tratar os dois resultados em vez de assumir que volta um documento.

Para dois parágrafos que você queria deixar organizados, essa é a forma errada. Você paga um upload de arquivo, um trabalho, uma espera e um download por algo que poderia ter lido com os próprios olhos.

A conta inverte em um capítulo inteiro: o arquivo nunca entra no contexto, nunca é achatado até virar uma string no caminho, e o escopo pode ser definido por um relatório de detecção em vez de à mão. Em algum lugar entre os dois existe uma linha, e o servidor não tem como saber de que lado você está. Você tem.

Com quais clientes isso funciona? Com qualquer cliente MCP capaz de iniciar um comando local. As configurações documentadas cobrem Claude Code, Codex, Cursor, Windsurf, Cline, Claude Desktop, VS Code, OpenCode e alguns outros, e o contrato para qualquer outro é rodar `npx -y humanpen-mcp` com `HUMANPEN_API_KEY` no ambiente dele.

Preciso de uma assinatura separada para o servidor MCP? Não. Skill, MCP e REST consomem o mesmo saldo de créditos, e os créditos são contados sobre as palavras efetivamente reescritas.

O agente pode verificar o resultado? A formatação não. A chamada volta com um recibo do trabalho em vez do documento, e uma ferramenta de leitura de arquivo recupera a prosa, mas não se os campos, as tabelas e os estilos sobreviveram. Essa inspeção é um passo que você mesmo faz no Word.

Por que a minha chamada devolveu um id de trabalho em vez de um arquivo? Porque o trabalho passou da janela de espera, que é de cerca de 55 segundos. O trabalho continua no servidor; `check_job` com esse id devolve o resultado quando estiver pronto.