Comment humaniser un document Word dans Claude Code

HumanPen fournit un serveur MCP stdio local. Tous les clients lancent la même commande, `npx -y humanpen-mcp`, avec une variable d’environnement qui contient la clé d’API. L’agent transmet un chemin absolu vers un `.docx` plutôt que son texte, si bien que le document n’entre jamais dans la fenêtre de contexte, et le fichier réécrit est réenregistré sur le disque.

Il n’y a ni point d’accès distant ni passerelle interposée. Si vous avez utilisé `mcp-remote` ou `supergateway` pour d’autres serveurs, vous n’avez besoin d’aucun des deux ici.

La conception évidente consiste à accepter une chaîne et à renvoyer une chaîne. C’est aussi celle qui s’effondre sur les documents que les lecteurs veulent vraiment faire réécrire.

Un `.docx` est une archive zip de parties XML. Lire les octets dans une conversation ne donne rien d’exploitable, et le décompresser dans le contexte jette exactement la structure qui faisait qu’il valait la peine de le garder comme fichier : styles de titres, objets de tableau, parties de notes de bas de page, champs qui se cachent derrière une table des matières. Aplatir une thèse en une chaîne, réécrire la chaîne, et vous avez résolu le mauvais problème. Champs Word, tables des matières et références croisées détaille ce que coûte cet aller-retour.

L’appel d’outil prend donc un chemin en entrée et un chemin en sortie. Le fichier est envoyé en HTTPS, traité, et le résultat réécrit sur votre disque. Rien de volumineux ne touche votre fenêtre de contexte.

Le plus rapide est de laisser l’agent s’en charger. La page développeurs vous donne une ligne prête à copier qui oriente votre client vers le guide d’installation MCP ; collez-la, et l’agent récupère le guide, détermine quel fichier de configuration votre client lit et vous demande une clé.

À la main, dans Claude Code, cela tient en une ligne :

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

Le `-s user` compte plus qu’il n’en a l’air. La portée par défaut est `local`, qui n’enregistre le serveur que pour le répertoire depuis lequel vous avez lancé la commande. Le lendemain, vous ouvrez Claude Code ailleurs, vous ne trouvez aucun outil HumanPen et vous en concluez, à juste titre, que l’installation a échoué.

Codex lit `~/.codex/config.toml`, où le même serveur est une table `[mcp_servers.humanpen]` avec `command = "npx"`, `args = ["-y", "humanpen-mcp"]` et `env = { HUMANPEN_API_KEY = "hp_your_key" }`. Le guide d’installation contient le bloc à copier.

Cursor, Windsurf, Cline et Claude Desktop prennent la même forme dans leurs propres fichiers de configuration. Un piège dans les applications de bureau : mettez le chemin absolu vers `npx` dans `command`. Lancez `which npx` et utilisez ce résultat. Le système d’exploitation démarre ces applications avec un `PATH` minimal, le nom simple souvent n’est pas trouvé, et le seul symptôme est que les outils n’apparaissent pas du tout.

Après un redémarrage, huit outils apparaissent. Celui dont parle cet article est `humanize_document` ; `read_detection_report` et `check_job` sont les deux qui le soutiennent.

La raison de passer par un agent plutôt que par un formulaire web, c’est que l’agent a déjà vos fichiers, y compris le rapport de détection qui se trouve dans le même dossier.

Confiez-lui les deux. Lorsqu’un rapport est joint et qu’aucune liste explicite de passages n’est fournie, les passages signalés dans ce rapport deviennent le périmètre de réécriture et tout le reste du document est laissé tel quel. Si vous fournissez une liste explicite, cette liste est définitive, et le rapport n’est conservé que comme pièce jointe de la tâche. Via l’API REST, la même chose ressemble à ceci, avec la racine d’API que vous indique la page développeurs :

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

Les crédits sont comptés sur les mots réellement réécrits : une tâche délimitée par un rapport avec quatre paragraphes signalés est facturée comme quatre paragraphes. Les voies Skill, MCP et API puisent dans le même solde, et une tâche qui n’aboutit pas n’est pas facturée.

Le modèle ne voit jamais le résultat.

Ce que renvoie un appel terminé, c’est un reçu pour la tâche : où le fichier a été écrit, ce que cela a coûté, comment le nombre de mots a bougé. Ni contenu, ni diff. Tout ce que vous vouliez orienter doit être écrit dans la chaîne d’instructions avant le début de la tâche, à l’aveugle.

La réponse habituelle est que le client dispose d’un outil de lecture de fichier, donc l’agent n’a qu’à lire le résultat. Il peut lire les mots : cinq lignes de `python-docx` extraient le texte des paragraphes et le comparent à l’original. Ce qu’il ne peut pas lire, c’est si la mise en forme a survécu – et la mise en forme est précisément la raison pour laquelle vous avez envoyé un fichier plutôt qu’une chaîne. L’agent peut donc vous dire qu’une tâche a réussi, ce qu’elle a coûté et ce que le texte dit maintenant. Il ne peut pas vous dire si le tableau de la page 7 est passé.

Cette vérification vous revient, dans Word, et c’est la même que celle qui suit n’importe quelle réécriture : actualiser les champs, compter les entrées bibliographiques, lire les cellules qui contiennent des chiffres. Comment relire un document Word humanisé avant de le rendre donne la version complète.

Réécrire un vrai document prend des minutes, ce qui est gênant dans un protocole conçu pour des appels d’outils rapides. Un appel attend environ 55 secondes puis renvoie un identifiant de tâche au lieu d’un fichier. Le travail continue sur le serveur, et `check_job` le récupère.

Deux choses en découlent, et les deux valent la peine d’être connues avant que vous ne construisiez une boucle autour. Si le délai d’attente de votre propre client est plus court que l’attente, la requête meurt de votre côté pendant que la tâche continue du nôtre, et la seule récupération est `check_job` avec l’identifiant que vous n’avez pas obtenu.

Et un appel qui renvoie un fichier et un appel qui renvoie un identifiant sont le même appel : tout ce que vous automatisez autour doit gérer les deux résultats plutôt que de supposer qu’un document revient.

Pour deux paragraphes que vous vouliez simplement mettre au propre, ce n’est pas la bonne forme. Vous payez un envoi de fichier, une tâche, une attente et un téléchargement pour quelque chose que vous pouviez lire de vos propres yeux.

Le calcul s’inverse sur un chapitre entier : le fichier n’entre jamais dans le contexte, il n’est jamais aplati en chaîne pendant le trajet, et le périmètre peut être défini par un rapport de détection plutôt qu’à la main. Quelque part entre les deux se trouve une ligne, et le serveur n’a aucun moyen de savoir de quel côté vous êtes. Vous, si.

Avec quels clients cela fonctionne-t-il ? Tout client MCP capable de lancer une commande locale. Les configurations documentées couvrent Claude Code, Codex, Cursor, Windsurf, Cline, Claude Desktop, VS Code, OpenCode et quelques autres, et le contrat pour tout le reste consiste à lancer `npx -y humanpen-mcp` avec `HUMANPEN_API_KEY` dans son environnement.

Faut-il un abonnement séparé pour le serveur MCP ? Non. Skill, MCP et REST puisent dans le même solde de crédits, et les crédits sont comptés sur les mots réellement réécrits.

L’agent peut-il vérifier le résultat ? Pas la mise en forme. L’appel revient avec un reçu pour la tâche plutôt qu’avec le document, et un outil de lecture de fichier peut récupérer la prose mais pas si les champs, les tableaux et les styles ont survécu. Cette inspection est une étape que vous faites vous-même dans Word.

Pourquoi mon appel d’outil a-t-il renvoyé un identifiant de tâche au lieu d’un fichier ? Parce que la tâche a dépassé la fenêtre d’attente, qui est d’environ 55 secondes. La tâche continue sur le serveur ; `check_job` avec cet identifiant renvoie le résultat dès qu’il est prêt.