Breaking Changes in MCP-Servern verfolgen

Ein MCP-Server ist eine API, deren wichtigster Konsument ein Sprachmodell ist. Das macht Breaking Changes ungewöhnlicher als sonst: Ein Client wirft nie einen Typfehler, das Modell ruft ein Tool einfach etwas falsch auf.

Warum Schema-Drift so leicht übersehen wird

Ein Server-Autor benennt einen Parameter von query in search_text um oder macht ein optionales Feld verpflichtend. Beim Deployment schlägt nichts fehl. Die Tool-Liste wird zur Laufzeit abgerufen, sodass jeder Client das neue Schema bei der nächsten Verbindung übernimmt. Agenten, die gestern noch funktionierten, übergeben nun die alten Argumentnamen und erhalten Validierungsfehler – oder, schlimmer, stillschweigend ignorierte Eingaben.

Drei Arten von Änderungen haben uns immer wieder Ärger gemacht:

• Ein Tool wurde umbenannt oder entfernt.
• Ein Parameter hat den Typ gewechselt oder wurde verpflichtend.
• Eine Beschreibung hat sich so weit geändert, dass sich ändert, wann ein Modell das Tool wählt.

Was Proxar vergleicht

Proxar erstellt Snapshots der tools/list-Antwort jedes Servers, vor dem es sitzt, und speichert sie mit einem Content-Hash. Ändert sich der Hash, vergleicht es die beiden Snapshots Tool für Tool.

{
  "name": "search_issues",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "integer" }
    },
    "required": ["query"]
  }
}

Der Diff durchläuft das JSON Schema jedes Tools, nicht den Rohtext – das Umsortieren von Schlüsseln oder Umformatieren zählt also nie als Änderung.

Entscheiden, was ein Breaking Change ist

Wir verwenden bewusst ein konservatives Regelwerk, im Geiste von Semantic Versioning für Bibliotheken.

Breaking

Ein Tool entfernen, einen Parameter entfernen, einen Pflichtparameter hinzufügen, einen Typ einengen (zum Beispiel string auf ein Enum) oder eine Einschränkung wie maxLength verschärfen.

Kompatibel

Ein Tool hinzufügen, einen optionalen Parameter hinzufügen, einen Typ erweitern oder eine Einschränkung lockern.

Braucht einen Menschen

Änderungen an Beschreibungen. Wir können nicht beurteilen, ob eine umformulierte Beschreibung das Verhalten des Modells verändert. Proxar markiert sie deshalb als Hinweis statt als Bruch und zeigt alten und neuen Text nebeneinander.

Was daraus folgt

Ein Breaking Diff blockiert standardmäßig keinen Traffic. Er löst einen Alert mit dem genauen geänderten Pfad aus, zum Beispiel search_issues.inputSchema.required, und Sie können den vorherigen Snapshot fixieren, während Sie Ihre Agenten anpassen.

# compare the pinned snapshot with what the server reports now
proxar diff --server issues-mcp --against pinned

Was wir noch falsch machen

Semantische Änderungen hinter einem unveränderten Schema sind für uns unsichtbar. Wenn ein Tool beginnt, Ergebnisse anders sortiert zurückzugeben, ist das Schema identisch und der Diff leer. Das sagen wir lieber, als so zu tun, als deckte eine Schema-Prüfung es ab. Stichproben von Antworten stehen auf der Liste; wir schreiben darüber, sobald es funktioniert.