MCP-Server

Der Mobile Builder bringt einen MCP-Server mit, über den ein KI-Assistent (z. B. Claude) das Designer-Backend steuern kann: Apps anlegen, Views und Controls erzeugen, Properties setzen und Apps validieren – mit denselben Backend-Aufrufen wie der Designer selbst.

Optionales Werkzeug

Der MCP-Server ist ein zusätzlicher Zugang für KI-gestützte App-Erstellung. Der Designer funktioniert vollständig ohne ihn.

Einordnung

Der MCP-Server spricht dasselbe Backend an wie der Designer (/mobbuild/admin) und nutzt zusätzlich den save-Broadcast der WebSocket-Verbindung, um offene Designer live zu aktualisieren. Die Architektur-Übersicht zeigt seine Einordnung im Gesamtbild.

Voraussetzungen

• Node.js ≥ 20 auf dem Rechner, der den MCP-Server startet.
• Ein MCP-fähiger Host (z. B. Claude Code, Cursor, Cline).
• Ein SAP-Benutzer mit denselben Designer-Berechtigungen, mit denen Sie sich auch am Designer anmelden.
• Eine gültige Lizenz mit freiem Developer-Slot und dem Modul AI. Der MCP-Server meldet sich als Entwickler an und belegt damit eine Developer-Lizenz – wie ein im Designer angemeldeter Entwickler. Ohne gültige Lizenz, ohne freien Developer-Slot oder ohne AI-Modul verweigern die Backend-Werkzeuge die Ausführung mit einer Lizenzmeldung.

Installation

Der MCP-Server wird als npm-Paket @hpc/mobile-builder-mcp ausgeliefert. Es gibt zwei Wege – je nachdem, ob der Host-Rechner die HPC-Paket-Registry erreicht.

Variante A — npm-Registry (empfohlen)

Hinterlegen Sie die HPC-Registry in einer .npmrc (im Home-Verzeichnis oder im Projekt). Den projektgebundenen Registry-Pfad und einen GitLab Deploy-Token mit Scope read_package_registry erhalten Sie von HPC:

@hpc:registry=https://git.codesign.gmbh/api/v4/projects/58/packages/npm/
//git.codesign.gmbh/api/v4/projects/58/packages/npm/:_authToken=<DEPLOY_TOKEN>

Projekt-Endpunkt, nicht Instanz-Endpunkt

Beide Zeilen müssen den projektgebundenen Pfad …/projects/58/packages/npm/ verwenden – nicht den Instanz-Pfad …/packages/npm/. Ein projektgebundener Deploy-Token wird am Instanz-Endpunkt abgelehnt (404 Project not found bzw. 401). Außerdem muss der Pfad in beiden Zeilen identisch sein, sonst sendet npm den Token nicht mit (→ 401 Unauthorized).

Nur read_package_registry

Der Deploy-Token braucht ausschließlich den Scope read_package_registry. Vergeben Sie nicht read_repository – das würde Lesezugriff auf den Produkt-Quellcode geben. Den projektgebundenen Pfad zeigt GitLab unter Packages & Registries → Package Registry → Registry setup → Project-level an.

Eine separate Installation ist dann nicht nötig – der Host startet das Paket per npx (siehe Host-Konfiguration). Pinnen Sie eine feste Version statt @latest.

Variante B — Offline-Tarball (abgeschottete Landschaft)

Erreicht der Host-Rechner die Registry nicht, liefert HPC eine self-contained .tgz aus. Diese global installieren:

npm i -g ./hpc-mobile-builder-mcp-<version>.tgz

Danach steht der Befehl mobile-builder-mcp bereit.

Host-Konfiguration

Tragen Sie den Server in der MCP-Konfiguration Ihres Hosts ein. Bei Claude Code ist das die Datei .mcp.json im Projekt-Root:

{
  "mcpServers": {
    "mobile-builder": {
      "command": "npx",
      "args": ["-y", "@hpc/mobile-builder-mcp@<version>"],
      "env": {
        "SAP_HOST": "https://ihr-sap-host:44300",
        "SAP_USER": "…",
        "SAP_PASSWORD": "…",
        "SAP_CLIENT": "200"
      }
    }
  }
}

Passwort nicht im Klartext

Hosts wie Claude Code expandieren ${VARIABLE} in den env-Werten aus den Umgebungsvariablen. So bleibt das Passwort aus der Konfigurationsdatei:

"SAP_PASSWORD": "${SAP_PASSWORD}"

Die Variable muss in der Umgebung gesetzt sein, in der der Host npx startet (z. B. via ~/.zshrc oder Ihr Secrets-Management).

Bei der Offline-Installation (Variante B) ersetzen Sie command/args durch den global installierten Befehl:

"command": "mobile-builder-mcp"

Cursor (~/.cursor/mcp.json) und andere Hosts werden analog konfiguriert – gleicher mcpServers-Block.

Verbindungsparameter

Variable	Pflicht	Bedeutung
SAP_HOST	ja	Basis-URL des SAP-Systems inkl. Protokoll und Port (ohne abschließenden /).
SAP_USER	ja	SAP-Benutzer (Basic Auth).
SAP_PASSWORD	ja	Passwort des SAP-Benutzers.
SAP_CLIENT	nein	SAP-Mandant.
SAP_TLS_VERIFY	nein	false deaktiviert die TLS-Zertifikatsprüfung (nur für selbstsignierte Test-Systeme). Default true.

Gleicher SAP-Benutzer wie im Designer

SAP_USER muss derselbe SAP-Benutzer sein, mit dem der Designer geöffnet ist. Nur so greifen Sperren und Live-Updates korrekt: Mutationen, die der MCP-Server auslöst, erscheinen im Designer desselben Benutzers, und fremd gesperrte Views bleiben unangetastet.

Verfügbare Werkzeuge

Werkzeug	Zweck
list_apps	Alle Apps des Mandanten auflisten
get_app	Eine App inklusive View-Struktur laden
create_app	Neue App anlegen
delete_app / restore_app	App löschen bzw. wiederherstellen
add_view	View zu einer App hinzufügen
add_control	Control in eine View einfügen
set_property	Property eines Controls setzen
remove_control	Control entfernen
bind_view_class	ABAP-Handler-Klasse an eine View binden (View-Eigenschaft class)
save_app	Alle gesammelten Änderungen in einem Schreibvorgang speichern
discard_edit	Begonnene Bearbeitung verwerfen, ohne zu speichern
check_view_class	Prüfen, ob die gebundene ABAP-Klasse im System existiert
create_view_class	Die gebundene ABAP-Handler-Klasse im System anlegen
create_view_constants	Konstanten (Control-IDs und Event-Handler) als Klassen-Attribute generieren
list_control_types	Verfügbare Control-Typen abfragen
validate_app	App auf Konsistenz prüfen
list_skill_docs / get_skill_doc	Eingebettete Anleitungsdokumente abrufen

Die vier *_view_class-/*_view_constants-Werkzeuge kapseln dieselben Backend-Funktionen wie der Binding-Tab im Designer (Klassenname an der View, Backend-Klasse anlegen, Verbindung prüfen, Konstanten anlegen). package und transport werden dabei aus der App übernommen.

Bearbeiten & Speichern

Änderungen werden nicht nach jeder einzelnen Aktion gespeichert. Der Server sammelt sie in einer Bearbeitungs-Sitzung und schreibt sie erst mit save_app in einem Schreibvorgang ins Backend:

1. Aufbauen/Überarbeiten — add_view, add_control, set_property, remove_control, bind_view_class ändern zunächst nur einen lokalen Entwurf.
2. Prüfen — validate_app (prüft den Entwurf) bzw. get_app (liefert den Entwurf, markiert als noch nicht gespeichert).
3. Speichern — save_app schreibt alles auf einmal, oder discard_edit verwirft die Bearbeitung.

So lässt sich z. B. eine ganze App aufbauen oder eine View vollständig überarbeiten und erst am Schluss einmal speichern – statt vieler Einzel-Speicherungen.

Live-Sync & View-Sperren

Die Bearbeitung verhält sich genauso kollaborativ wie im Designer:

• Sperren werden gesetzt und gehalten. Beim ersten Bearbeiten einer bestehenden View sperrt der Server sie – wie eine im Designer geöffnete View – und hält die Sperre bis zum Speichern bzw. Verwerfen. Eine von einem anderen Benutzer gesperrte View wird nicht verändert. Eine View, die du selbst gerade im Designer geöffnet hast, kann der MCP weiterhin bearbeiten (er nutzt deine bestehende Sperre).
• Änderungen werden beim Speichern live gepusht. save_app löst denselben save-Broadcast aus wie der Designer; offene Designer desselben Benutzers übernehmen die Änderung sofort, ohne Neuladen.

Wie das View-Locking insgesamt funktioniert, beschreibt der Abschnitt Multi-User & Echtzeit der Architektur-Seite.

Fehlerbehebung

npm error code ETARGET / „No matching version found" trotz existierender Version

Symptom. Der Server startet nicht, der MCP-Host meldet MCP error -32000: Connection closed. Das stderr-Log zeigt:

npm error code ETARGET
npm error notarget No matching version found for @hpc/mobile-builder-mcp@<version>.

Obwohl die gepinnte <version> in der Registry existiert (im GitLab-Package-Registry-UI sichtbar), findet npx sie nicht. Das -32000 ist nur die Folge – npx bricht vor dem Server-Start ab.

Ursache. Ein veraltetes npm-Metadaten-Cache (Packument) auf dem Host. npm hat die Versionsliste des Pakets von einem früheren Zeitpunkt gecacht und revalidiert sie per Conditional Request; die Registry antwortet mit 304 Not Modified, sodass npm die alte Liste behält – die frisch publizierte Version fehlt darin. Das tritt vor allem auf, wenn in der .mcp.json auf eine gerade erst publizierte Version gepinnt wird, bevor der lokale Cache sie kennt. Es ist kein Registry-, Token- oder Netzwerkfehler.

Diagnose. Prüfen, ob die Version am Registry-Endpunkt wirklich liegt – am rohen Endpunkt vorbei am npm-Cache:

# zeigt die echte Versionsliste der Registry (Token aus der .npmrc)
curl -s -H "Authorization: Bearer <DEPLOY_TOKEN>" \
  "https://git.codesign.gmbh/api/v4/projects/58/packages/npm/@hpc/mobile-builder-mcp" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print('dist-tags:', d.get('dist-tags')); print('versions:', list(d.get('versions',{}).keys()))"

Erscheint die gepinnte Version hier, der Fehler kommt aber weiterhin → es ist der lokale Cache.

Lösung. npm-Cache leeren, dann neu verbinden:

npm cache clean --force

Anschließend im MCP-Host neu verbinden (in Claude Code: /mcp → Reconnect). npx lädt das Packument frisch und findet die Version. Nicht auf eine ältere Version downgraden – der Pin ist korrekt, nur der Cache war veraltet.

Vorbeugen

Setzen Sie den Versions-Pin in der .mcp.json erst, nachdem HPC die Version als verfügbar gemeldet hat – nicht im selben Moment des Publish. So ist das Packument bei der ersten Auflösung bereits aktuell.