Corriger la documentation avec l'IA et le Sutram MCP Server

Comment nous avons utilisé le serveur MCP pour trouver, commenter, corriger et versionner son propre guide utilisateur — sans quitter le terminal

Le problème

Nous étions en train de configurer le serveur MCP Sutram dans Claude Code lorsque la connexion a échoué. Le coupable ? Une URL erronée dans le guide utilisateur. La documentation indiquait aux utilisateurs de se connecter à https://sutram.io/mcp, mais le bon endpoint est https://app.sutram.io/mcp — le sous-domaine app. était manquant.

Une petite faute de frappe, mais une qui ferait trébucher chaque nouvel utilisateur suivant le guide. Le genre de bug qui érode la confiance dans la documentation.

Au lieu d'ouvrir l'interface Sutram, de télécharger le fichier, de faire un rechercher-remplacer, de re-téléverser et de gérer les versions manuellement, nous avons décidé de le corriger de la même manière que nous l'avions trouvé : avec l'IA et MCP, directement depuis le terminal.

Le workflow

L'intégralité de la correction a été réalisée par Claude Code en utilisant les outils du serveur MCP Sutram — les mêmes outils documentés dans le guide que nous étions en train de corriger. Voici ce qui s'est passé, étape par étape.

1. Trouver le document

Le projet organise sa documentation sous forme de records — des dossiers avec des métadonnées structurées (titre, catégorie, extrait, date de publication). Au lieu de naviguer dans l'arborescence des dossiers niveau par niveau, l'agent a recherché par métadonnées en utilisant sutram_search_folders :

{
  "conditions": [{"key": "title", "value": "MCP Server"}],
  "type": "file"
}

Un appel, un résultat : le guide utilisateur du serveur MCP — un fichier markdown de 69,5 Ko, version 1, publié, situé à /en/Docs/User guides/sutram-mcp-server-user-guide.

2. Télécharger et évaluer les dégâts

En utilisant sutram_get_item pour obtenir une URL de téléchargement, puis en récupérant le fichier, l'agent a cherché toutes les occurrences de l'URL erronée :

10 occurrences de https://sutram.io/mcp
 0 occurrence de https://app.sutram.io/mcp

L'erreur apparaissait partout : dans le schéma d'architecture, dans les exemples de configuration pour Claude Code, Cursor et Claude Desktop, dans la section de référence API, et même dans un exemple de code Node.js. Chaque extrait de configuration qu'un utilisateur copierait-collerait était cassé.

3. Créer un commentaire documentant le bug

Avant toute modification, l'agent a créé un commentaire ancré au markdown sur le fichier en utilisant sutram_create_comment :

« Bug : L'URL du serveur MCP est incorrecte dans tout le document. Les 9 occurrences indiquent https://sutram.io/mcp mais l'URL correcte est https://app.sutram.io/mcp (sous-domaine app. manquant). Cela provoque des échecs de connexion lorsque les utilisateurs suivent le guide. »

Le commentaire a été ancré directement à la première occurrence de l'URL dans le texte — pas une note générique au niveau du fichier, mais un pointeur précis vers le problème.

4. Créer une nouvelle version et réserver pour modification

Le fichier était publié (v1), donc la modification directe n'était pas possible. Le workflow de versioning nécessitait deux étapes :

sutram_create_new_version — a créé la version 2 en statut brouillon
sutram_checkout_file — a verrouillé le fichier pour modification exclusive

C'est le même workflow que les équipes d'ingénierie utilisent pour les révisions contrôlées de documents : personne d'autre ne peut modifier le fichier pendant qu'il est réservé.

5. Corriger et téléverser le fichier corrigé

L'agent a effectué un rechercher-remplacer global :

https://sutram.io/mcp → https://app.sutram.io/mcp

Les 10 occurrences ont été remplacées. Ensuite, le téléversement a suivi le flux standard en trois étapes :

sutram_request_upload — a obtenu une URL S3 pré-signée
HTTP PUT — a téléversé le fichier corrigé directement vers S3
sutram_upload_modified_file — a enregistré le nouveau contenu dans Sutram

6. Restituer et publier

Avec le fichier téléversé :

sutram_checkin_file — a libéré le verrou, rendant le fichier à nouveau disponible
sutram_publish_version — a promu la version 2 de brouillon à publié

L'historique des versions montre désormais les deux versions : v1 (l'originale avec les URL erronées) et v2 (la version corrigée), toutes deux conservées pour audit.

7. Résoudre le commentaire

Enfin, sutram_resolve_comment a marqué le commentaire de bug comme résolu. Le commentaire reste visible dans l'historique du fichier — toute personne examinant le document peut voir ce qui était erroné et quand cela a été corrigé.

Les outils utilisés

Outil	Objectif
`sutram_search_folders`	Trouver le document par métadonnées
`sutram_get_item`	Obtenir les métadonnées du fichier et l'URL de téléchargement
`sutram_create_comment`	Documenter le bug avec un commentaire ancré au markdown
`sutram_create_new_version`	Créer le brouillon v2 à partir de la v1 publiée
`sutram_checkout_file`	Verrouiller le fichier pour modification exclusive
`sutram_request_upload`	Obtenir l'URL pré-signée pour le téléversement S3
`sutram_upload_modified_file`	Enregistrer le fichier corrigé
`sutram_checkin_file`	Libérer le verrou de modification
`sutram_publish_version`	Publier la v2
`sutram_resolve_comment`	Clore le commentaire de bug

Dix outils MCP différents, orchestrés en séquence par l'agent IA, chacun réalisant une étape spécifique dans un workflow professionnel de gestion documentaire.

Pourquoi c'est important

Ce n'était ni une démo ni une preuve de concept. C'était un vrai bug, trouvé dans de la documentation en production, qui causait de vrais échecs de connexion pour les utilisateurs essayant de configurer le serveur MCP.

Ce qui le rend intéressant, c'est la boucle fermée : les propres outils du serveur MCP ont été utilisés pour corriger la propre documentation du serveur MCP. L'agent a utilisé les mêmes capacités de versioning, de commentaires et de gestion de fichiers que celles décrites dans le guide — prouvant qu'elles fonctionnent exactement comme documenté (une fois qu'on a la bonne URL, bien sûr).

L'intégralité de la correction — de la découverte à la correction publiée — a pris environ 2 minutes et n'a jamais quitté le terminal. Pas d'onglets de navigateur, pas de téléchargement manuel de fichiers, pas de copier-coller entre éditeurs. Juste un agent IA, des outils MCP et une conversation.

La vision d'ensemble

Les bugs de documentation sont particulièrement insidieux. Ils se cachent dans des fichiers qui reçoivent rarement la même rigueur de revue que le code. Ils cassent l'onboarding. Ils génèrent des tickets de support. Et ils ont tendance à persister parce que les corriger donne l'impression d'une corvée de basse priorité.

MCP change l'économie de la maintenance documentaire. Quand un agent IA peut naviguer dans un référentiel de contenu, identifier les problèmes, appliquer des corrections via un contrôle de version approprié, et documenter les changements — le tout dans la même conversation où le bug a été découvert — la barrière pour corriger la documentation tombe à quasi zéro.