Schemaänderung über den MCP-Server

Worum es geht

Modelle kannst du im Hub von Hand pflegen. Du kannst sie aber auch von einem KI-Client ändern lassen, zum Beispiel von Claude. Dafür hat der Hub einen MCP-Server. MCP (Model Context Protocol) ist ein Standard, über den ein KI-Client Werkzeuge (Tools) eines Servers aufruft.

Der KI-Client schreibt dabei nicht einfach drauflos. Jede Änderung läuft durch dieselbe Schleuse: beschreiben, prüfen, planen, von dir freigeben lassen, einmal anwenden.

Drei Begriffe kommen auf dieser Seite immer wieder vor:

Die Werkzeuge

Der MCP-Server bietet 15 Tools. Die meisten lesen nur.

Ein CDMS ist im Hub ein Modul. Seine ID ist die cdmsId, mit der alle Tools arbeiten. Dieselben Informationen gibt es auch als lesbare MCP-Ressourcen unter cdms://targets/{cdmsId}/….

Der Weg einer Änderung

So sieht das als Gespräch zwischen den Beteiligten aus:

sequenceDiagram
    actor B as Benutzer
    participant K as KI-Client
    participant M as MCP-Server (Hub)
    participant DB as Hub-Datenbank
    K->>M: cdms_list_targets, cdms_get_capabilities, cdms_get_schema
    M-->>K: Ziele, Regeln, Ist-Schema
    K->>M: cdms_create_operation_context(cdmsId)
    M-->>K: operationId (30 min gültig)
    K->>M: cdms_validate_blueprint(operationId, blueprint)
    M-->>K: valid, errors, warnings
    K->>M: cdms_plan_changes(operationId, blueprint)
    M-->>K: planId, summary, changes, destructiveChanges
    K->>M: cdms_create_change_set(operationId, planId)
    M-->>K: changeSetId, PENDING_APPROVAL
    K->>B: zeigt den Plan
    B-->>K: "Ja, anwenden"
    K->>M: cdms_approve_change_set(operationId, changeSetId, confirmDestructive)
    M-->>K: APPROVED
    K->>M: cdms_apply_change_set(operationId, changeSetId, idempotencyKey)
    M->>DB: Ist-Schema neu lesen und vergleichen
    M->>DB: alle Änderungen in einer Transaktion
    M-->>K: APPLIED + Ergebnis je Element

Der Blueprint

Der Blueprint ist ein JSON-Dokument. Es beschreibt Ordner, Enums, Modelle, Felder, Beziehungen und Zugriffsfilter so, wie sie nach der Änderung da sein sollen.

{
  "operationId": "4c2b…",
  "blueprint": {
    "blueprintVersion": "1",
    "target": { "cdmsId": "a7f5…", "expectedCdmsName": "CVC Backend" },
    "folders": [
      { "ref": "folder.crm", "name": "CRM",
        "existingFolderId": "2a7f…" }            ← vorhandener Ordner
    ],
    "enums": [
      { "ref": "enum.status", "folderRef": "folder.crm",
        "name": "CUSTOMER_STATUS",
        "values": [ { "key": "ACTIVE" }, { "key": "BLOCKED" } ] }
    ],
    "models": [
      { "ref": "model.customer", "folderRef": "folder.crm",
        "name": "Customer",                      ← gibt es schon
        "fields": [
          { "ref": "field.customer.status", "name": "status",
            "type": "ENUM", "enumRef": "enum.status",
            "required": true }
        ] }
    ]
  }
}

{
  "valid": true,
  "errors": [],
  "warnings": [
    { "code": "BLUEPRINT_INVALID", "element": "model.customer",
      "message": "Das Modell '/crm/Customer' existiert bereits … wird wiederverwendet …" }
  ],
  "models": [ { "ref": "model.customer", "existingId": "9b1…" } ], …
}

Vier Regeln solltest du kennen:

1. Symbolische Namen statt IDs. Elemente verweisen über ihre ref aufeinander, zum Beispiel enumRef: "enum.status". Die IDs vergibt der Hub.
2. Ergänzen, nie still löschen. Was schon existiert, erkennt der Hub an seinem Pfad (/crm/Customer) und verwendet es wieder. Was im Blueprint fehlt, bleibt unverändert. Ändern oder Löschen von Vorhandenem geht nur ausdrücklich über den Abschnitt migrations.
3. Was du benutzt, deklarierst du mit. Willst du ein vorhandenes Modell oder Enum referenzieren, steht es im Blueprint, sonst kommt BLUEPRINT_REFERENCE_NOT_FOUND. Für vorhandene Ordner gibst du existingFolderId an.
4. Eine Beziehung ist ein Feldpaar. Beide Seiten stehen als RELATION-Feld im Blueprint und zeigen über inverseFieldRef aufeinander, siehe Beide Seiten einer Beziehung.
5. Keine Umgebung angeben. Ein CDMS hat keine Umgebung: Sein Modell gilt in Entwicklung, Test und Produktion gleich, die Umgebungen unterscheiden sich nur in ihren Daten. target.expectedEnvironment ist deshalb ein Fehler.

Der Hub prüft streng: Ein unbekannter JSON-Schlüssel ist schon ein Fehler. Inhaltliche Befunde sammelt er aber vollständig, damit der KI-Client alles in einem Durchgang korrigieren kann.

Ausdrückliche Änderungen: migrations

Alles, was Vorhandenes verändert oder entfernt, steht als eigener Eintrag unter migrations:

Jede Migration gilt im Plan als destruktiv. Ebenso destruktiv sind ein kaskadierendes Löschen über eine Beziehung, ein entfernter Zugriffsfilter und ein Modell, das auditiert wird. Ein Change Set mit destruktiven Änderungen gibst du nur mit einer eigenen Rolle frei und nur, wenn du diese Änderungen gesondert bestätigst, siehe weiter unten „Destruktive Änderungen freigeben“.

Der Plan

cdms_plan_changes validiert noch einmal und vergleicht dann den Blueprint mit dem Ist-Schema. Heraus kommt ein Plan:

{ "operationId": "4c2b…", "blueprint": { … wie oben … } }

{
  "planId": "af72…",
  "summary": { "createCount": 2, "updateCount": 0, "deleteCount": 0,
               "unchangedCount": 2, "destructiveChangeCount": 0 },
  "changes": [
    { "type": "UNCHANGED", "elementType": "folder", "path": "/crm" },
    { "type": "CREATE",    "elementType": "enum",   "path": "/crm/CUSTOMER_STATUS" },
    { "type": "UNCHANGED", "elementType": "model",  "path": "/crm/Customer" },
    { "type": "CREATE",    "elementType": "field",  "path": "/crm/Customer#status" }
  ],
  "destructiveChanges": [],
  "blueprintHash": "269a…"
}

Jede Zeile in changes hat einen Typ: CREATE, UPDATE, DELETE oder UNCHANGED. Unter destructiveChanges stehen im Klartext alle Änderungen, die etwas zerstören können. Genau diesen Plan zeigt der KI-Client dir, bevor du freigibst. Ein Plan lebt 30 Minuten.

Das Change Set und seine Zustände

cdms_create_change_set nimmt nur eine planId, keinen neuen Blueprint. Was freigegeben wird, ist also genau das, was geplant wurde.

stateDiagram-v2
    [*] --> PENDING_APPROVAL: cdms_create_change_set
    PENDING_APPROVAL --> APPROVED: cdms_approve_change_set
    APPROVED --> APPLIED: cdms_apply_change_set, Erfolg
    APPROVED --> FAILED: cdms_apply_change_set, Fehler
    APPLIED --> ROLLED_BACK: cdms_rollback_change_set
    FAILED --> [*]
    ROLLED_BACK --> [*]
    APPLIED --> [*]

FAILED und ROLLED_BACK sind Endzustände. Ein Change Set wird nie ein zweites Mal versucht. Ein Werkzeug zum Verwerfen gibt es nicht: Ein Change Set, das du nicht freigibst, bleibt in PENDING_APPROVAL und wird nie angewendet.

Destruktive Änderungen freigeben

Stehen im Plan Einträge unter destructiveChanges, reicht ein einfaches „Ja“ nicht:

Der KI-Client zeigt dir die destruktiven Änderungen einzeln und fragt gesondert danach. Nur wenn du genau diesen Teil bestätigst, sendet er confirmDestructive: true. Die Rolle vergibt dein Administrator; welche es ist, legt der Betreiber des Hubs fest. Beim Anwenden prüft der Server die Rolle noch einmal. Wurde sie dir inzwischen entzogen, wird nicht geschrieben.

Ein Change Set ohne destruktive Änderungen braucht weder die Rolle noch die Bestätigung.

Genau einmal anwenden

Wenn sich die Basis inzwischen geändert hat

Zwischen Planen und Anwenden kann jemand anders das Modell im Hub geändert haben. Deshalb liest der Server vor dem Schreiben das Schema neu ein:

Zurücknehmen

cdms_rollback_change_set geht nur aus APPLIED. Der Rollback macht in umgekehrter Reihenfolge rückgängig, was das Change Set angelegt oder geändert hat. Elemente, die nur wiederverwendet wurden (REUSED), bleiben unberührt. Auch der Rollback läuft in einer Transaktion, und wie beim Anwenden läuft auf einem CDMS immer nur einer. Die Rolle für destruktive Änderungen braucht er nicht: Er nimmt nur zurück, was dasselbe Change Set getan hat.

Ein Change Set, das ein Modell (DELETE_MODEL) oder ein Enum (DELETE_ENUM) gelöscht hat, lässt sich nicht zurücknehmen. Der Server lehnt den Rollback dann von vornherein ab.

Der Operation Context: ein Ziel, eine halbe Stunde

Die operationId ist kein Schlüssel, den man weitergeben kann. Kennt jemand anders sie, etwa aus einem geteilten Chatverlauf, kann er damit nichts freigeben, anwenden oder zurücknehmen: Für ihn gibt es diesen Kontext nicht.

Der Kontext gilt 30 Minuten ab dem Anlegen. Freigeben, Anwenden und Zurücknehmen brauchen ihn. Die ganze Kette vom Öffnen bis zum Anwenden muss also in dieser Zeit laufen. Ist die Zeit um, öffnest du eine neue Klammer und planst neu.

Beim Öffnen akzeptiert der Server nur die UUID des CDMS. Die lesenden Tools nehmen auch den genauen Modulnamen. Mehrere Treffer ergeben CDMS_TARGET_AMBIGUOUS, es gibt keine ungefähre Suche.

Den KI-Client anbinden

Dein Zugang

Die Zugangsdaten bekommst du von uns bei der Registrierung bzw. mit dem Vertragsabschluss:

Ein Client-Secret gibt es nicht. Der Zugang ist ein öffentlicher OAuth-Client und wird mit PKCE abgesichert: Der KI-Client erzeugt für jede Anmeldung einen Einmal-Schlüssel, den nur er kennt. Ein Werkzeug auf deinem Rechner könnte ein Secret ohnehin nicht geheim halten.

Was du sehen und ändern darfst, entscheidet dein Benutzerkonto, nicht der Zugang. Ein CDMS, auf das du keine Rechte hast, taucht in cdms_list_targets nicht auf.

Claude Code

claude mcp add --transport http --client-id <ihre-client-id> --callback-port <port> \
  codamai-cdms https://<host>/api/mcp

• --transport http steht vor Name und URL. Ohne ihn legt Claude Code einen lokalen stdio-Server an.
• --client-id und --callback-port sind Pflicht. Ohne sie versucht Claude Code, sich selbst als Client zu registrieren, und das lehnt der Hub ab.
• Kein --client-secret, siehe oben.
• Mit --scope project landet der Eintrag in der .mcp.json des Projekts und gilt für das ganze Team, mit --scope user für alle deine Projekte.

Danach meldest du dich in einer Claude-Code-Sitzung an:

Im selben Menü /mcp siehst du die Tools des Servers und kannst dich wieder abmelden, etwa wenn du den Benutzer wechselst oder sich deine Rechte geändert haben. Verwalten kannst du den Eintrag auch von der Kommandozeile:

claude mcp list                  # alle Server mit Verbindungsstatus
claude mcp get codamai-cdms      # Details zu einem Server
claude mcp remove codamai-cdms   # Server entfernen

Statt claude mcp add kannst du den Server auch direkt in die .mcp.json im Projekt schreiben:

{
  "mcpServers": {
    "codamai-cdms": {
      "type": "http",
      "url": "https://<host>/api/mcp",
      "oauth": { "clientId": "<ihre-client-id>", "callbackPort": <port> }
    }
  }
}

Trage keinen Authorization-Header ein. Das Token holt sich der Client selbst über die Anmeldung, und ein fester Header wäre ein eingecheckter Zugangsschlüssel.

Weniger Rückfragen, aber nicht beim Schreiben

Claude Code fragt vor jedem Tool-Aufruf nach. Die lesenden Tools kannst du in .claude/settings.json dauerhaft erlauben. Die Namen haben das Schema mcp__<servername>__<toolname>:

{
  "permissions": {
    "allow": [
      "mcp__codamai-cdms__cdms_list_targets",
      "mcp__codamai-cdms__cdms_get_target",
      "mcp__codamai-cdms__cdms_get_capabilities",
      "mcp__codamai-cdms__cdms_get_structure",
      "mcp__codamai-cdms__cdms_get_schema"
    ]
  }
}

cdms_approve_change_set, cdms_apply_change_set und cdms_rollback_change_set gehören nie in diese Liste. Die Rückfrage vor diesen Aufrufen ist deine Freigabe.

Andere KI-Clients

Rechte

Alles, was der MCP-Server liest und schreibt, läuft über dieselben Rechteprüfungen wie die REST-API. Ein CDMS, das du nicht sehen darfst, gibt es für dich nicht: Die Antwort ist CDMS_TARGET_NOT_FOUND, siehe Unsichtbar ist 404.

Und danach?

Das Anwenden ändert nur die Modelle im Hub. Deine Anwendung merkt davon erst etwas beim nächsten Build:

Wie der Build die Metadaten holt, steht unter Codegenerierung im Build.

Fallen