Voltar ao Blog

Corrigindo Documentação com IA e o Sutram MCP Server

By Sergio Vieira Greve
Corrigindo Documentação com IA e o Sutram MCP Server

Como usamos o MCP Server para encontrar, comentar, corrigir e versionar seu próprio guia do usuário — sem sair do terminal

O problema

Estávamos configurando o Sutram MCP Server no Claude Code quando a conexão falhou. O culpado? Uma URL errada no guia do usuário. A documentação instruía os usuários a se conectarem a https://sutram.io/mcp, mas o endpoint correto é https://app.sutram.io/mcp — faltava o subdomínio app..

Um erro pequeno, mas que faria qualquer novo usuário tropeçar ao seguir o guia. O tipo de bug que mina a confiança na documentação.

Em vez de abrir a interface do Sutram, baixar o arquivo, buscar e substituir, fazer upload de novo e gerenciar versões manualmente, decidimos corrigir da mesma forma que encontramos: com IA e MCP, direto do terminal.

O fluxo de trabalho

Toda a correção foi feita pelo Claude Code usando as ferramentas do Sutram MCP Server — as mesmas ferramentas documentadas no guia que estávamos corrigindo. Veja o que aconteceu, passo a passo.

1. Encontrar o documento

O projeto organiza sua documentação como records — pastas com metadados estruturados (título, categoria, resumo, data de publicação). Em vez de navegar pela árvore de pastas nível por nível, o agente buscou por metadados usando sutram_search_folders:

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

Uma chamada, um resultado: o Guia do Usuário do MCP Server — um arquivo markdown de 69,5 KB, versão 1, publicado, localizado em /en/Docs/User guides/sutram-mcp-server-user-guide.

2. Baixar e avaliar o estrago

Usando sutram_get_item para obter a URL de download e depois buscando o arquivo, o agente procurou todas as ocorrências da URL errada:

10 ocorrências de https://sutram.io/mcp
 0 ocorrências de https://app.sutram.io/mcp

O erro aparecia em todo lugar: no diagrama de arquitetura, nos exemplos de configuração para Claude Code, Cursor e Claude Desktop, na seção de referência da API e até em um exemplo de código Node.js. Cada trecho de configuração que o usuário copiaria e colaria estava quebrado.

3. Criar um comentário documentando o bug

Antes de fazer qualquer alteração, o agente criou um comentário ancorado ao markdown no arquivo usando sutram_create_comment:

"Bug: A URL do MCP Server está incorreta em todo o documento. Todas as 9 ocorrências mostram https://sutram.io/mcp, mas a URL correta é https://app.sutram.io/mcp (falta o subdomínio app.). Isso causa falhas de conexão quando os usuários seguem o guia."

O comentário foi ancorado diretamente à primeira ocorrência da URL no texto — não uma nota genérica no nível do arquivo, mas um apontamento preciso para o problema.

4. Criar uma nova versão e fazer checkout para edição

O arquivo estava publicado (v1), então a edição direta não era possível. O fluxo de versionamento exigia duas etapas:

  1. sutram_create_new_version — criou a versão 2 em status de rascunho
  2. sutram_checkout_file — travou o arquivo para edição exclusiva

Esse é o mesmo fluxo que equipes de engenharia usam para revisões controladas de documentos: ninguém mais pode modificar o arquivo enquanto ele está em checkout.

5. Corrigir e fazer upload do arquivo corrigido

O agente fez um buscar-e-substituir global:

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

Todas as 10 ocorrências substituídas. Em seguida, o upload seguiu o fluxo padrão de três etapas:

  1. sutram_request_upload — obteve uma URL pré-assinada do S3
  2. HTTP PUT — fez o upload do arquivo corrigido diretamente para o S3
  3. sutram_upload_modified_file — registrou o novo conteúdo no Sutram

6. Checkin e publicação

Com o arquivo enviado:

  • sutram_checkin_file — liberou a trava, tornando o arquivo disponível novamente
  • sutram_publish_version — promoveu a versão 2 de rascunho para publicada

O histórico de versões agora mostra ambas: v1 (a original com as URLs erradas) e v2 (a versão corrigida), ambas preservadas para auditoria.

7. Resolver o comentário

Por fim, sutram_resolve_comment marcou o comentário do bug como resolvido. O comentário permanece visível no histórico do arquivo — qualquer pessoa revisando o documento pode ver o que estava errado e quando foi corrigido.

As ferramentas utilizadas

Ferramenta Finalidade
sutram_search_folders Encontrar o documento por metadados
sutram_get_item Obter metadados e URL de download do arquivo
sutram_create_comment Documentar o bug com um comentário ancorado ao markdown
sutram_create_new_version Criar rascunho v2 a partir da v1 publicada
sutram_checkout_file Travar o arquivo para edição exclusiva
sutram_request_upload Obter URL pré-assinada para upload no S3
sutram_upload_modified_file Registrar o arquivo corrigido
sutram_checkin_file Liberar a trava de edição
sutram_publish_version Publicar a v2
sutram_resolve_comment Fechar o comentário do bug

Dez ferramentas MCP diferentes, orquestradas em sequência pelo agente de IA, cada uma executando uma etapa específica em um fluxo profissional de gestão de documentos.

Por que isso importa

Isso não foi uma demonstração nem uma prova de conceito. Foi um bug real, encontrado em documentação de produção, que estava causando falhas reais de conexão para usuários tentando configurar o MCP Server.

O que torna isso interessante é o ciclo fechado: as próprias ferramentas do MCP Server foram usadas para corrigir a própria documentação do MCP Server. O agente usou as mesmas capacidades de versionamento, comentários e gerenciamento de arquivos que o guia descreve — provando que funcionam exatamente como documentado (desde que você tenha a URL certa, é claro).

Toda a correção — da descoberta à publicação — levou cerca de 2 minutos e nunca saiu do terminal. Sem abas no navegador, sem downloads manuais, sem copiar e colar entre editores. Apenas um agente de IA, ferramentas MCP e uma conversa.

O panorama geral

Bugs de documentação são especialmente traiçoeiros. Ficam em arquivos que raramente recebem o mesmo rigor de revisão que o código. Quebram o onboarding. Geram chamados de suporte. E tendem a persistir porque corrigi-los parece uma tarefa de baixa prioridade.

O MCP muda a economia da manutenção de documentação. Quando um agente de IA consegue navegar por um repositório de conteúdo, identificar problemas, aplicar correções com controle de versão adequado e documentar as mudanças — tudo dentro da mesma conversa onde o bug foi descoberto — a barreira para corrigir documentação cai para praticamente zero.

Voltar ao Blog