Zurück zum Blog

Dokumentation mit KI und dem Sutram MCP Server korrigieren

By Sergio Vieira Greve
Dokumentation mit KI und dem Sutram MCP Server korrigieren

Wie wir den MCP Server nutzten, um sein eigenes Benutzerhandbuch zu finden, zu kommentieren, zu korrigieren und zu versionieren — ohne das Terminal zu verlassen

Das Problem

Wir konfigurierten gerade den Sutram MCP Server in Claude Code, als die Verbindung fehlschlug. Der Übeltäter? Eine falsche URL im Benutzerhandbuch. Die Dokumentation wies Benutzer an, sich mit https://sutram.io/mcp zu verbinden, aber der korrekte Endpunkt ist https://app.sutram.io/mcp — die app.-Subdomain fehlte.

Ein kleiner Tippfehler, aber einer, der jeden neuen Benutzer stolpern lassen würde, der dem Handbuch folgt. Die Art von Fehler, die das Vertrauen in Dokumentation untergräbt.

Anstatt die Sutram-Oberfläche zu öffnen, die Datei herunterzuladen, zu suchen und zu ersetzen, erneut hochzuladen und Versionen manuell zu verwalten, beschlossen wir, den Fehler so zu beheben, wie wir ihn gefunden hatten: durch KI und MCP, direkt vom Terminal aus.

Der Arbeitsablauf

Die gesamte Korrektur wurde von Claude Code mit den Sutram MCP Server Tools durchgeführt — denselben Tools, die im Handbuch dokumentiert sind, das wir korrigierten. Hier ist, was Schritt für Schritt passierte.

1. Das Dokument finden

Das Projekt organisiert seine Dokumentation als Records — Ordner mit strukturierten Metadaten (Titel, Kategorie, Auszug, Veröffentlichungsdatum). Anstatt den Ordnerbaum Ebene für Ebene zu durchsuchen, suchte der Agent nach Metadaten mit sutram_search_folders:

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

Ein Aufruf, ein Ergebnis: das MCP Server Benutzerhandbuch — eine 69,5 KB große Markdown-Datei, Version 1, veröffentlicht, unter /en/Docs/User guides/sutram-mcp-server-user-guide.

2. Herunterladen und den Schaden bewerten

Mit sutram_get_item zum Erhalt einer Download-URL und anschließendem Abruf der Datei suchte der Agent nach allen Vorkommen der falschen URL:

10 Vorkommen von https://sutram.io/mcp
 0 Vorkommen von https://app.sutram.io/mcp

Der Fehler tauchte überall auf: im Architekturdiagramm, in Konfigurationsbeispielen für Claude Code, Cursor und Claude Desktop, im API-Referenzabschnitt und sogar in einem Node.js-Codebeispiel. Jeder einzelne Konfigurationsausschnitt, den ein Benutzer kopieren würde, war fehlerhaft.

3. Einen Kommentar zur Dokumentation des Fehlers erstellen

Bevor Änderungen vorgenommen wurden, erstellte der Agent einen markdown-verankerten Kommentar zur Datei mit sutram_create_comment:

„Bug: Die MCP-Server-URL ist im gesamten Dokument falsch. Alle 9 Vorkommen zeigen https://sutram.io/mcp, aber die korrekte URL ist https://app.sutram.io/mcp (fehlende app.-Subdomain). Dies verursacht Verbindungsfehler, wenn Benutzer dem Handbuch folgen."

Der Kommentar wurde direkt am ersten Vorkommen der URL im Text verankert — kein generischer Kommentar auf Dateiebene, sondern ein präziser Verweis auf das Problem.

4. Neue Version erstellen und zur Bearbeitung auschecken

Die Datei war veröffentlicht (v1), daher war eine direkte Bearbeitung nicht möglich. Der Versionierungsworkflow erforderte zwei Schritte:

  1. sutram_create_new_version — erstellte Version 2 im Entwurfsstatus
  2. sutram_checkout_file — sperrte die Datei zur exklusiven Bearbeitung

Das ist derselbe Workflow, den Ingenieurteams für kontrollierte Dokumentrevisionen verwenden: Niemand anderes kann die Datei ändern, solange sie ausgecheckt ist.

5. Die korrigierte Datei reparieren und hochladen

Der Agent führte ein globales Suchen-und-Ersetzen durch:

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

Alle 10 Vorkommen ersetzt. Dann folgte der Upload dem Standard-Drei-Schritte-Ablauf:

  1. sutram_request_upload — erhielt eine vorsignierte S3-URL
  2. HTTP PUT — lud die korrigierte Datei direkt auf S3 hoch
  3. sutram_upload_modified_file — registrierte den neuen Inhalt bei Sutram

6. Einchecken und veröffentlichen

Mit der hochgeladenen Datei:

  • sutram_checkin_file — gab die Sperre frei, sodass die Datei wieder verfügbar war
  • sutram_publish_version — beförderte Version 2 vom Entwurf zur Veröffentlichung

Die Versionshistorie zeigt nun beide Versionen: v1 (das Original mit den falschen URLs) und v2 (die korrigierte Version), beide zur Prüfung aufbewahrt.

7. Den Kommentar auflösen

Abschließend markierte sutram_resolve_comment den Bug-Kommentar als gelöst. Der Kommentar bleibt in der Dateihistorie sichtbar — jeder, der das Dokument überprüft, kann sehen, was falsch war und wann es behoben wurde.

Die verwendeten Tools

Tool Zweck
sutram_search_folders Dokument anhand von Metadaten finden
sutram_get_item Dateimetadaten und Download-URL abrufen
sutram_create_comment Den Fehler mit einem markdown-verankerten Kommentar dokumentieren
sutram_create_new_version v2-Entwurf aus veröffentlichter v1 erstellen
sutram_checkout_file Die Datei zur exklusiven Bearbeitung sperren
sutram_request_upload Vorsignierte URL für S3-Upload erhalten
sutram_upload_modified_file Die korrigierte Datei registrieren
sutram_checkin_file Die Bearbeitungssperre freigeben
sutram_publish_version v2 veröffentlichen
sutram_resolve_comment Den Bug-Kommentar schließen

Zehn verschiedene MCP-Tools, in Reihe vom KI-Agenten orchestriert, jedes einen spezifischen Schritt in einem professionellen Dokumentenmanagement-Workflow ausführend.

Warum das wichtig ist

Das war keine Demo und kein Proof of Concept. Es war ein echter Fehler, der in der Produktionsdokumentation gefunden wurde und echte Verbindungsfehler für Benutzer verursachte, die versuchten, den MCP Server einzurichten.

Was es interessant macht, ist der geschlossene Kreislauf: Die eigenen Tools des MCP Servers wurden verwendet, um die eigene Dokumentation des MCP Servers zu korrigieren. Der Agent nutzte dieselben Versionierungs-, Kommentar- und Dateiverwaltungsfunktionen, die das Handbuch beschreibt — und bewies damit, dass sie genau wie dokumentiert funktionieren (sobald man die richtige URL hat, natürlich).

Die gesamte Korrektur — von der Entdeckung bis zur veröffentlichten Berichtigung — dauerte etwa 2 Minuten und verließ nie das Terminal. Keine Browser-Tabs, keine manuellen Dateidownloads, kein Kopieren zwischen Editoren. Nur ein KI-Agent, MCP-Tools und eine Konversation.

Das große Ganze

Dokumentationsfehler sind auf einzigartige Weise heimtückisch. Sie stecken in Dateien, die selten dieselbe Review-Sorgfalt wie Code erfahren. Sie behindern das Onboarding. Sie erzeugen Support-Tickets. Und sie neigen dazu, fortzubestehen, weil ihre Behebung sich wie eine Aufgabe mit niedriger Priorität anfühlt.

MCP verändert die Ökonomie der Dokumentationspflege. Wenn ein KI-Agent ein Content-Repository navigieren, Probleme identifizieren, Korrekturen durch ordnungsgemäße Versionskontrolle anwenden und die Änderungen dokumentieren kann — alles innerhalb derselben Konversation, in der der Fehler entdeckt wurde — sinkt die Hürde zur Behebung von Dokumentation auf nahezu null.

Zurück zum Blog