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 – on-prem über /mobbuild/admin, die View-Sperren über die WebSocket-Verbindung; in der S/4HANA Cloud über den OData-Service des Designers, die View-Sperren als Sperrsätze desselben Service. Welche Welt gilt, entscheidet allein SAP_AUTH (siehe Verbindungsparameter). In beiden Welten löst er beim Speichern denselben save-Broadcast aus wie der Designer, damit offene Designer live aktualisiert werden. Das ABAP-Backend-Coding (Klassen, Interfaces, Programme, DDIC) läuft in beiden Welten über die Standard-ADT-Schnittstelle (/sap/bc/adt/*) – dafür sind keine zusätzlichen /MOBBUILD/-Klassen nötig. 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.
• Aktiviertes ADT (/sap/bc/adt/*) auf dem SAP-System – nötig für die Backend-Coding-Werkzeuge (Klassen/Interfaces/DDIC). App-/View-Werkzeuge brauchen es nicht.
• 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-mb/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-mb: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-mb-mobile-builder-mcp-<version>.tgz

Danach steht der Befehl mobile-builder-mcp bereit.

Host-Konfiguration

Der Server wird in der MCP-Konfiguration Ihres Hosts eingetragen (bei Claude Code die Datei .mcp.json im Projekt-Root, bei Cursor ~/.cursor/mcp.json). Anmeldung und Beispielkonfiguration unterscheiden sich je Plattform:

• MCP-Server on-prem – Basic Auth mit Benutzer und Passwort, Admin-Kanal /mobbuild/admin
• MCP-Server in der S/4HANA Cloud – Anmeldung im Browser per Reentrance-Ticket, OData-Kanal

Verbindungsparameter

Variable	Pflicht	Bedeutung
SAP_HOST	ja	Basis-URL des SAP-Systems inkl. Protokoll und Port (ohne abschließenden /). Cloud: der API-Host des Tenants (…-api.s4hana.cloud.sap).
SAP_AUTH	nein	basic (Default, on-prem: Benutzer und Passwort) oder browser (S/4HANA Cloud: Anmeldung im Browser, kein Passwort).
SAP_USER	on-prem	SAP-Benutzer (Basic Auth). In der Cloud nicht setzen.
SAP_PASSWORD	on-prem	Passwort des SAP-Benutzers. In der Cloud nicht setzen.
SAP_CLIENT	nein	SAP-Mandant.
SAP_LOGON_INTERACTIVE	nein	Nur Cloud. true (Default) erlaubt dem Server, für die Anmeldung einen Browser-Tab zu öffnen. false öffnet nie einen Browser (unbeaufsichtigte Läufe): der Server verwendet ausschließlich eine bereits gespeicherte Sitzung und bricht ohne eine solche mit einem Fehler ab.
SAP_LANGUAGE	nein	Anmeldesprache (sap-language, z. B. DE). Bestimmt die Sprache der SAP-Sitzung und damit z. B., in welcher Sprache Meldungstexte gelesen und geschrieben werden. Leer = SAP-Standard (Benutzer- bzw. Systemsprache).
SAP_TLS_VERIFY	nein	false deaktiviert die TLS-Zertifikatsprüfung (nur für selbstsignierte Test-Systeme). Default true.

Gleicher SAP-Benutzer wie im Designer

Der Benutzer des MCP-Servers – on-prem SAP_USER, in der Cloud der im Browser angemeldete Benutzer – 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.

Unterschiede zwischen on-prem und Cloud

Die Werkzeuge heißen in beiden Welten gleich und werden gleich aufgerufen. Wenige Ausnahmen:

Werkzeug	On-prem	S/4HANA Cloud
check_view_class, create_view_constants	verfügbar	nicht verfügbar – Konstanten werden im Klassenquelltext angelegt, die Bindung über read_backend_class geprüft
trigger_push	wird angeboten, weist den Aufruf aber ab (Push läuft über WebSocket)	verfügbar – Push-Test an offene Apps mit pushInterval
create_service_binding, create_maintenance_object	verfügbar, selten nötig	der Weg zur Pflege-App einer App-Tabelle
atc_check	Standardprüfung	Freigabeprüfung für ABAP for Cloud Development
create_view_class	Backend-Methode des Designers	ADT-Skelett mit der Cloud-Basisklasse

Alles Weitere zum Coding in der Cloud (Sprachversion, kein Schreiben auf Tabellen aus der View-Klasse, RAP-Objekte) steht in der eingebetteten Anleitung (get_skill_doc → cloud-differences).

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 in den Papierkorb verschieben bzw. wiederherstellen. delete_app mit purge: true löscht endgültig – samt Versionshistorie, Übersetzungen, Build-Ergebnis und Sperren, nicht wiederherstellbar; eine noch deployte App lehnt das Backend ab, in der Cloud zusätzlich eine im Launchpad registrierte
add_view	View zu einer App hinzufügen
add_control	Control in eine View einfügen
set_property	Property eines Controls setzen
set_app_property	Property der App-Wurzel setzen (Titel, Namespace, Launchpad-Inbound mit semantischem Objekt und Aktion, Seitenmaße)
trigger_push	Offene Runtime-Apps zum Neuladen anstoßen (nur Cloud)
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
read_backend_class	ABAP-Quelltext einer Klasse/eines Interfaces lesen (über ADT)
list_backend_examples	Best-Practice-Beispielklassen aus dem Beispielpaket auflisten (on-prem /MOBBUILD/EXAMPLE, Cloud ZMOBBUILD_EXAMPLE; über ADT)
create_helper_class / create_backend_class / create_exception_class / create_interface	ABAP-Klassen/Interfaces im App-Paket anlegen (über ADT)
write_backend_class	Quelltext einer Klasse/eines Interfaces schreiben + aktivieren (über ADT, mit Syntax-Prüfung)
create_object / read_object / write_object	Generische ABAP-Objekte über ADT (Programm, Funktionsgruppe, CDS-View, Tabelle u. a.)
create_domain / create_data_element / create_table_type	DDIC-Domänen, -Datenelemente und -Tabellentypen im App-Paket anlegen/aktualisieren (über ADT) – inkl. Datentyp/Länge, Festwerte und Feldbeschriftungen
create_message_class / write_message_class / read_message_class	T100-Meldungsklassen pflegen (über ADT)
create_service_binding / publish_service_binding	OData-Service-Binding auf eine Service-Definition anlegen und veröffentlichen bzw. zurücknehmen (Cloud: Grundlage der Pflege-App einer App-Tabelle)
create_maintenance_object	Pflegeobjekt für die SAP-App „Benutzerdefinierte Business Configurations" anlegen – die Tabelle wird ohne eigene UI5-App pflegbar (Cloud)
write_class_include	Lokale Klassen einer Klasse schreiben (Definitions, Implementations, Makros, Testklassen)
create_test_include / run_unit_tests	ABAP-Unit-Testinclude anlegen und Tests einer Klasse ausführen
syntax_check / lint_backend / pretty_print	Quelltext prüfen, auf Regelverstöße untersuchen und formatieren
atc_check	ATC-Prüfung eines Objekts des App-Pakets (Cloud: Freigabeprüfung für ABAP for Cloud Development)
read_table / list_package	Tabelleninhalt bzw. Objektliste des App-Pakets lesen
edit_source	Eine Textstelle im Quelltext ersetzen und aktivieren
activate_objects / get_inactive_objects	Mehrere abhängige Objekte in einem Lauf aktivieren; inaktive Objekte des App-Pakets auflisten
get_class_structure / read_method / edit_method / rename_backend_class	Klassenstruktur lesen, einzelne Methoden lesen und ersetzen, Klasse umbenennen
delete_backend_object	ABAP-Objekt des App-Pakets löschen (mit ausdrücklicher Bestätigung)
get_dumps	Laufzeitfehler der letzten Minuten lesen
release_locks	Notausgang nach einem abgebrochenen Schreibvorgang: beendet die ADT-Schreibsitzung des Servers und gibt damit jede Objektsperre frei, die sie noch hält (z. B. „Benutzer … bearbeitet bereits …"). Sperren anderer Sitzungen (Eclipse, ein früherer Serverprozess) sind unerreichbar. View-Sperren der Bearbeitungs-Sitzung sind davon nicht betroffen – die fallen mit save_app bzw. discard_edit
list_control_types	Verfügbare Control-Typen abfragen; mit controlType die Details eines Typs – Eigenschaften mit Typ, Auswahlwerten und Default (wie im Eigenschaften-Panel), erlaubte Kinder und Eltern, LogicFlow-Ereignisse
validate_app	App auf Konsistenz prüfen
list_skill_docs / get_skill_doc	Eingebettete Anleitungsdokumente abrufen

Die *_view_class-/*_view_constants-Werkzeuge kapseln dieselben Backend-Funktionen wie der Binding-Tab im Designer (Klassenname an der View, Backend Klasse generieren, Verbindung zur Backend-Klasse prüfen, Backend Konstanten-Attribute generieren). package und transport werden dabei aus der App übernommen. Das eigentliche Backend-Coding (Klassen/Interfaces/DDIC lesen, anlegen, schreiben) läuft über ADT und ist – wie alle Schreibwerkzeuge – auf das Paket der App beschränkt.

Geschlossene Apps sind schreibgeschützt

Hat eine App den Status „geschlossen" (z. B. weil ihr Transport bereits freigegeben ist), lehnt der MCP-Server jede Änderung ab – sowohl am Backend-Coding als auch an Views/Controls, unabhängig davon, in welchem Transport eine Klasse liegt. Geprüft wird beim Beginn einer Bearbeitungs-Sitzung (also vor der ersten View-Mutation), bei create_view_class/create_view_constants und bei jedem ADT-Werkzeug, das Paket und Transport der App auflöst. Lesen der App und der Quelltexte bleibt möglich (get_app, validate_app, read_backend_class, read_object, read_method, get_class_structure, read_message_class, get_dumps); Werkzeuge, die das App-Paket auflösen (read_table, list_package, get_inactive_objects, run_unit_tests, syntax_check, lint_backend, atc_check), melden dagegen ebenfalls „App ist geschlossen".

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, set_app_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.

Ein Entwurf, der 15 Minuten lang nicht bearbeitet wird, verfällt: der Server verwirft ihn samt seinen View-Sperren (ungespeicherte Änderungen gehen dabei verloren). Beim Beenden des Servers werden offene Entwürfe ebenfalls verworfen und die Sperren freigegeben.

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 – on-prem über die WebSocket-Verbindung, in der Cloud über den Nachrichtenkanal, den der Designer abfragt. Wurde in der Bearbeitungs-Sitzung genau eine View berührt, übernehmen offene Designer desselben Benutzers diese View sofort, ohne Neuladen. Bei mehreren berührten Views bleibt es bei einem Schreibvorgang ohne View-Broadcast; ebenso verteilt der MCP Änderungen an der App-Wurzel (set_app_property) und an der App-Struktur (neue Views, Reihenfolge, Namen) nicht live – die erscheinen im Designer erst beim nächsten 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-mb/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-mb/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.

Werkzeugliste veraltet nach einer neuen Version

Symptom. Nach einem Versionswechsel des Pakets fehlen neue Werkzeuge oder alte Signaturen werden gemeldet.

Lösung. Den Server im MCP-Host neu verbinden (in Claude Code: /mcp → Reconnect). Der Host lädt die Werkzeugliste nur beim Verbinden.