Come umanizzare un documento Word dentro Claude Code

HumanPen fornisce un server MCP stdio locale. Ogni client avvia lo stesso comando, `npx -y humanpen-mcp`, con una variabile d'ambiente che contiene la chiave API. L'agente passa un percorso assoluto a un `.docx` invece del testo, così il documento non entra mai nella finestra di contesto e il file riscritto viene salvato di nuovo sul disco.

Non c'è un endpoint remoto né un wrapper gateway davanti. Se hai usato `mcp-remote` o `supergateway` per altri server, qui non ti serve nessuno dei due.

Il progetto più ovvio è accettare una stringa e restituire una stringa. Ed è anche il progetto che crolla proprio sui documenti che le persone vogliono davvero far riscrivere.

Un `.docx` è uno zip di parti XML. Leggere i byte dentro una conversazione non dà nulla di utilizzabile, e decomprimerlo nel contesto butta via esattamente la struttura che rendeva conveniente tenerlo come file: stili dei titoli, oggetti tabella, parti delle note a piè di pagina, i campi che stanno dietro un indice. Appiattire una tesi in una stringa, riscrivere la stringa, e hai risolto il problema sbagliato. Campi di Word, indici e riferimenti incrociati spiega quanto costa questo andata e ritorno.

Quindi la chiamata allo strumento porta un percorso in ingresso e un percorso in uscita. Il file viene caricato su HTTPS, elaborato, e il risultato riscritto sul tuo disco. Niente di ingombrante tocca la tua finestra di contesto.

La strada più veloce è lasciar fare all'agente. La pagina sviluppatori ti dà una riga pronta da copiare che indirizza il tuo client alla guida di installazione MCP; la incolli, e l'agente recupera la guida, capisce quale file di configurazione legge il tuo client e ti chiede una chiave.

A mano, in Claude Code basta una riga:

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

Quel `-s user` conta più di quanto sembri. L'ambito predefinito è `local`, che registra il server solo per la cartella in cui hai eseguito il comando. Il giorno dopo apri Claude Code da un'altra parte, non trovi nessuno strumento di HumanPen e concludi, a ragione, che l'installazione è fallita.

Codex legge `~/.codex/config.toml`, dove lo stesso server è una tabella `[mcp_servers.humanpen]` con `command = "npx"`, `args = ["-y", "humanpen-mcp"]` e `env = { HUMANPEN_API_KEY = "hp_your_key" }`. Nella guida di installazione trovi il blocco da copiare.

Cursor, Windsurf, Cline e Claude Desktop assumono la stessa forma nei rispettivi file di configurazione. Una trappola, nelle app desktop: metti il percorso assoluto di `npx` in `command`. Esegui `which npx` e usa quel risultato. Queste app vengono avviate dal sistema operativo con un `PATH` minimo, il nome semplice spesso non viene trovato e l'unico sintomo è che gli strumenti non compaiono affatto.

Dopo un riavvio compaiono otto strumenti. Quello di cui parla questo articolo è `humanize_document`; `read_detection_report` e `check_job` sono i due che lo supportano.

Il motivo per farlo da un agente invece che da un modulo web è che l'agente ha già i tuoi file, incluso il rapporto di rilevamento che sta nella stessa cartella.

Affidagli entrambi. Quando è allegato un rapporto e non viene data una lista esplicita di passaggi, i passaggi segnalati in quel rapporto diventano l'ambito della riscrittura e tutto il resto del documento resta intatto. Se invece dai una lista esplicita, quella lista è definitiva e il rapporto resta solo come allegato del lavoro. Sulla REST API la stessa cosa si presenta così, rispetto alla radice API che ti mostra la pagina sviluppatori:

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

I crediti si contano sulle parole effettivamente riscritte, quindi un lavoro delimitato da un rapporto con quattro paragrafi segnalati costa come quattro paragrafi. I percorsi Skill, MCP e API attingono allo stesso saldo, e un lavoro che non si completa non viene addebitato.

Il modello non vede mai l'output.

Ciò che restituisce una chiamata conclusa è una ricevuta del lavoro: dove è stato scritto il file, quanto è costato, come si è spostato il conteggio delle parole. Nessun contenuto, nessun diff. Tutto ciò che volevi indirizzare deve essere scritto nella stringa delle istruzioni prima che il lavoro inizi, alla cieca.

La risposta abituale è che il client ha uno strumento di lettura file, quindi l'agente può semplicemente leggere il risultato. Può leggere le parole: cinque righe di `python-docx` estraggono il testo dei paragrafi e lo confrontano con l'originale. Quello che non può leggere è se la formattazione sia sopravvissuta, e la formattazione è il motivo per cui hai inviato un file invece di una stringa. Quindi l'agente può dirti che un lavoro è riuscito, quanto è costato e cosa dice ora il testo. Non può dirti se la tabella a pagina 7 sia arrivata fino in fondo.

Quel controllo è tuo, in Word, ed è lo stesso controllo che fai dopo qualsiasi riscrittura: aggiornare i campi, contare le voci bibliografiche, leggere le celle che contengono numeri. Come rivedere un documento Word umanizzato prima della consegna ha la versione completa.

Riscrivere un documento vero richiede minuti, e questo è scomodo dentro un protocollo costruito attorno a chiamate rapide. Una chiamata aspetta circa 55 secondi e poi restituisce un id di lavoro invece di un file. Il lavoro continua sul server e `check_job` lo riprende.

Da questo seguono due cose, ed entrambe valgono la pena di essere sapute prima di costruirci attorno un ciclo. Se il timeout del tuo client è più breve dell'attesa, la richiesta muore dalla tua parte mentre il lavoro continua dalla nostra, e il recupero è `check_job` con l'id che non hai ricevuto.

E una chiamata che restituisce un file e una chiamata che restituisce un id sono la stessa chiamata, quindi qualsiasi automazione attorno deve gestire entrambi gli esiti invece di dare per scontato che torni un documento.

Per due paragrafi che volevi sistemare, questa è la forma sbagliata. Paghi un upload di file, un lavoro, un'attesa e un download per qualcosa che avresti potuto leggere con i tuoi occhi.

Il conto si ribalta su un capitolo intero: il file non entra mai nel contesto, non viene mai appiattito in una stringa lungo il percorso, e l'ambito può essere definito da un rapporto di rilevamento invece che a mano. Da qualche parte tra i due c'è una linea, e il server non ha modo di capire da quale parte stai. Tu sì.

Con quali client funziona? Qualsiasi client MCP in grado di avviare un comando locale. Le configurazioni documentate coprono Claude Code, Codex, Cursor, Windsurf, Cline, Claude Desktop, VS Code, OpenCode e alcuni altri, e il contratto per qualsiasi altro è eseguire `npx -y humanpen-mcp` con `HUMANPEN_API_KEY` nel suo ambiente.

Mi serve un abbonamento separato per il server MCP? No. Skill, MCP e REST attingono allo stesso saldo di crediti, e i crediti si contano sulle parole effettivamente riscritte.

L'agente può verificare il risultato? La formattazione no. La chiamata torna con una ricevuta del lavoro invece che con il documento, e uno strumento di lettura file può recuperare la prosa ma non se campi, tabelle e stili siano sopravvissuti. Quell'ispezione è un passaggio che fai tu in Word.

Perché la mia chiamata ha restituito un id di lavoro invece di un file? Perché il lavoro ha superato la finestra di attesa, che è di circa 55 secondi. Il lavoro continua sul server; `check_job` con quell'id restituisce il risultato quando è pronto.