Corrigiendo Documentación con IA y el Sutram MCP Server

Cómo usamos el MCP Server para buscar, comentar, corregir y versionar su propia guía de usuario — sin salir de la terminal

El problema

Estábamos configurando el Sutram MCP Server en Claude Code cuando la conexión falló. ¿El culpable? Una URL incorrecta en la guía de usuario. La documentación indicaba a los usuarios conectarse a https://sutram.io/mcp, pero el endpoint correcto es https://app.sutram.io/mcp — faltaba el subdominio app..

Un pequeño error tipográfico, pero uno que haría tropezar a cada nuevo usuario que siguiera la guía. El tipo de bug que erosiona la confianza en la documentación.

En lugar de abrir la interfaz de Sutram, descargar el archivo, buscar y reemplazar, volver a subirlo y gestionar versiones manualmente, decidimos corregirlo de la misma forma en que lo encontramos: a través de IA y MCP, directamente desde la terminal.

El flujo de trabajo

Toda la corrección fue realizada por Claude Code usando las herramientas del Sutram MCP Server — las mismas herramientas documentadas en la guía que estábamos corrigiendo. Esto es lo que sucedió, paso a paso.

1. Encontrar el documento

El proyecto organiza su documentación como records — carpetas con metadatos estructurados (título, categoría, extracto, fecha de publicación). En lugar de navegar el árbol de carpetas nivel por nivel, el agente buscó por metadatos usando sutram_search_folders:

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

Una llamada, un resultado: la Guía de Usuario del MCP Server — un archivo markdown de 69.5 KB, versión 1, publicado, ubicado en /en/Docs/User guides/sutram-mcp-server-user-guide.

2. Descargar y evaluar el daño

Usando sutram_get_item para obtener una URL de descarga y luego obteniendo el archivo, el agente buscó todas las ocurrencias de la URL incorrecta:

10 ocurrencias de https://sutram.io/mcp
 0 ocurrencias de https://app.sutram.io/mcp

El error aparecía en todas partes: en el diagrama de arquitectura, en los ejemplos de configuración para Claude Code, Cursor y Claude Desktop, en la sección de referencia de la API, e incluso en un ejemplo de código en Node.js. Cada fragmento de configuración que un usuario copiaría y pegaría estaba roto.

3. Crear un comentario documentando el bug

Antes de hacer cualquier cambio, el agente creó un comentario anclado al markdown en el archivo usando sutram_create_comment:

"Bug: La URL del MCP Server es incorrecta en todo el documento. Las 9 ocurrencias muestran https://sutram.io/mcp pero la URL correcta es https://app.sutram.io/mcp (falta el subdominio app.). Esto causa fallas de conexión cuando los usuarios siguen la guía."

El comentario fue anclado directamente a la primera ocurrencia de la URL en el texto — no una nota genérica a nivel de archivo, sino un señalamiento preciso del problema.

4. Crear una nueva versión y hacer checkout para edición

El archivo estaba publicado (v1), por lo que la edición directa no era posible. El flujo de versionamiento requirió dos pasos:

sutram_create_new_version — creó la versión 2 en estado borrador
sutram_checkout_file — bloqueó el archivo para edición exclusiva

Este es el mismo flujo de trabajo que los equipos de ingeniería usan para revisiones controladas de documentos: nadie más puede modificar el archivo mientras está en checkout.

5. Corregir y subir el archivo corregido

El agente realizó un buscar-y-reemplazar global:

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

Las 10 ocurrencias reemplazadas. Luego, la subida siguió el flujo estándar de tres pasos:

sutram_request_upload — obtuvo una URL prefirmada de S3
HTTP PUT — subió el archivo corregido directamente a S3
sutram_upload_modified_file — registró el nuevo contenido en Sutram

6. Checkin y publicación

Con el archivo subido:

sutram_checkin_file — liberó el bloqueo, dejando el archivo disponible nuevamente
sutram_publish_version — promovió la versión 2 de borrador a publicada

El historial de versiones ahora muestra ambas versiones: v1 (la original con las URLs incorrectas) y v2 (la versión corregida), ambas preservadas para auditoría.

7. Resolver el comentario

Finalmente, sutram_resolve_comment marcó el comentario del bug como resuelto. El comentario permanece visible en el historial del archivo — cualquier persona que revise el documento puede ver qué estaba mal y cuándo se corrigió.

Las herramientas utilizadas

Herramienta	Propósito
`sutram_search_folders`	Encontrar el documento por metadatos
`sutram_get_item`	Obtener metadatos del archivo y URL de descarga
`sutram_create_comment`	Documentar el bug con un comentario anclado al markdown
`sutram_create_new_version`	Crear borrador v2 a partir de v1 publicada
`sutram_checkout_file`	Bloquear el archivo para edición exclusiva
`sutram_request_upload`	Obtener URL prefirmada para subida a S3
`sutram_upload_modified_file`	Registrar el archivo corregido
`sutram_checkin_file`	Liberar el bloqueo de edición
`sutram_publish_version`	Publicar v2
`sutram_resolve_comment`	Cerrar el comentario del bug

Diez herramientas MCP diferentes, orquestadas en secuencia por el agente de IA, cada una realizando un paso específico en un flujo profesional de gestión documental.

Por qué esto importa

Esto no fue una demo ni una prueba de concepto. Fue un bug real, encontrado en documentación en producción, que estaba causando fallas reales de conexión para usuarios que intentaban configurar el MCP Server.

Lo que lo hace interesante es el ciclo cerrado: las propias herramientas del MCP Server fueron usadas para corregir la propia documentación del MCP Server. El agente usó las mismas capacidades de versionamiento, comentarios y gestión de archivos que la guía describe — demostrando que funcionan exactamente como están documentadas (una vez que tienes la URL correcta, por supuesto).

Toda la corrección — desde el descubrimiento hasta la corrección publicada — tomó aproximadamente 2 minutos y nunca salió de la terminal. Sin pestañas del navegador, sin descargas manuales de archivos, sin copiar y pegar entre editores. Solo un agente de IA, herramientas MCP y una conversación.

El panorama general

Los bugs de documentación son particularmente insidiosos. Se esconden en archivos que raramente reciben el mismo rigor de revisión que el código. Rompen el onboarding. Generan tickets de soporte. Y tienden a persistir porque corregirlos se siente como una tarea de baja prioridad.

MCP cambia la economía del mantenimiento de documentación. Cuando un agente de IA puede navegar un repositorio de contenido, identificar problemas, aplicar correcciones a través de un control de versiones adecuado, y documentar los cambios — todo dentro de la misma conversación donde se descubrió el bug — la barrera para corregir documentación se reduce prácticamente a cero.