Cloud ALM MCP

Node.js- und TypeScript-Grundgerüst für einen SAP-Cloud-ALM-Model-Context-Protocol-Server.

Dieses Repository ist derzeit mock-first. Es kann ohne SAP-Cloud-ALM-Anmeldedaten, BTP-Destination-Service-Konfiguration oder OAuth-Einrichtung installiert, gebaut, getestet und gestartet werden.

Zielarchitektur

• Laufzeit: Node.js auf SAP BTP Cloud Foundry.

• Produktions-MCP-Transport: MCP Streamable HTTP über das offizielle MCP-TypeScript-SDK.

• STR-158 verwendet zustandsloses Streamable HTTP für den POC, indem kein MCP-Sitzungs-ID-Generator gesetzt wird.

• Lokaler Fallback-Transport: stdio, nur für die lokale Entwicklung vorgesehen.

• Zukünftiger Cloud-ALM-Zugriffspfad: SAP BTP Destination Service.

• Zukünftiges Authentifizierungsmodell: OAuth2 Client Credentials über eine konfigurierte Destination.

Echte SAP-Cloud-ALM-Konnektivität ist in STR-158 bewusst nicht enthalten.

Sitzungs- und Zustandsanforderungen müssen vor der Produktionsnutzung durch Agenten überprüft werden, falls spätere Tool-Abläufe persistenten MCP-Sitzungszustand erfordern. STR-158 führt bewusst keinen Sitzungsspeicher ein.

Related MCP server: Cubi MCP Playground

Lokale Entwicklung

npm install
npm run build
npm test
npm start

Standardmäßig führt npm start den Mock-Modus über HTTP aus und stellt bereit:

• MCP-Endpunkt: POST /mcp

• Health-Endpunkt: GET /health

Der entfernte MCP-Endpunkt ist zustandslos und nur für POST ausgelegt. GET, DELETE und andere nicht unterstützte Methoden auf /mcp geben 405 Method Not Allowed mit Allow: POST zurück; GET-SSE und MCP-Sitzungsbeendigung sind bewusst nicht implementiert. JSON-Anforderungstexte sind auf 64kb begrenzt.

Beispiel:

curl http://localhost:3000/health

Verwenden Sie .env.example als Liste der unterstützten Platzhalter. Fügen Sie keine echten Cloud-ALM-Geheimnisse in lokale Dateien ein, die in git committet werden.

SAP-BTP-Cloud-Foundry-POC-Bereitstellung

manifest.yml definiert eine einzelne cloud-alm-mcp-Cloud-Foundry-Anwendung mit nodejs_buildpack, command: npm start und einem HTTP-Health-Check auf /health. Die erste Bereitstellung ist bewusst auf den sicheren Mock-Modus festgelegt:

RUNTIME_MODE=mock
MCP_TRANSPORT=http
EXTERNAL_CALLS_ENABLED=false
READ_CAPABILITY_ENABLED=true
WRITE_CAPABILITY_ENABLED=false

Für STR-162 sind keine Cloud-ALM-Anmeldedaten, OAuth-Einstellungen, XSUAA/IAS-Bindung, Destination-Service-Bindung oder echte Destination-Werte erforderlich.

Cloud-Foundry-Staging führt npm install aus; der postinstall-Lebenszyklus des Pakets führt npm run build aus, sodass dist/src/index.js vor npm start existiert. TypeScript und die für die Kompilierung benötigten Typpakete sind reguläre Abhängigkeiten, sodass die Standard-Node.js-Buildpack-Produktionsinstallation die App bauen kann, ohne nur lokale Tools wie vitest und tsx mitzuführen.

Die App verwendet weiterhin den von der Plattform bereitgestellten PORT; hardcodieren Sie keinen Produktionsport. package.json fordert Node.js 22.x für deterministisches Staging-/Laufzeitverhalten bei der ersten Bereitstellung an. SAP BTP Cloud Foundry unterstützt derzeit Node.js 22 über nodejs_buildpack; Betreiber sollten die genaue Zielfoundation vor der Bereitstellung dennoch mit cf buildpacks überprüfen.

package-lock.json bleibt die maßgebliche npm-Abhängigkeitssperre. Es ist kein packageManager-Feld gesetzt, da Cloud Foundry npm für eine Root-package.json/package-lock.json verwendet und das Erzwingen einer npm-Version nur erforderlich ist, wenn sich das Standard-npm der Zielfoundation als inkompatibel erweist.

Lokale Validierung:

npm install
npm run build
npm test
npm start
curl http://localhost:3000/health

Vom Betreiber benötigte BTP-Werte:

CF API endpoint
BTP org
BTP space
route/domain decision, if not using the default route

Manueller BTP-Validierungsablauf:

cf login -a <api-endpoint>
cf target -o <org> -s <space>
cf buildpacks
cf push
cf app cloud-alm-mcp
cf logs cloud-alm-mcp --recent
curl https://<route>/health

Nach der Bereitstellung validieren Sie, dass /health status: ok zurückgibt, POST /mcp im Mock-Modus funktioniert, GET /mcp 405 Method Not Allowed mit Allow: POST zurückgibt und die Logs Anforderungs-IDs, Methode, Pfad, Status und Dauer ohne Anforderungstexte, Autorisierungsheader, Token oder Geheimnisse enthalten.

Konfiguration

Zentrale Umgebungsvariablen:

• RUNTIME_MODE=mock|destination

• MCP_TRANSPORT=http|stdio

• PORT=3000

• READ_CAPABILITY_ENABLED=true|false

• WRITE_CAPABILITY_ENABLED=true|false

• ALLOWED_DESTINATIONS=cloud-alm-dev

• EXTERNAL_CALLS_ENABLED=false|true

Lokale Standardwerte sind bewusst sicher: Mock-Laufzeit, HTTP-Transport, Lesen aktiviert, Schreiben deaktiviert und externe Aufrufe deaktiviert.

Der Destination-Modus existiert in diesem Grundgerüst nur als Platzhalter. Er schlägt geschlossen fehl, bis die BTP-Destination-Service-Suche und der OAuth-Token-Ablauf in späteren Aufgaben implementiert werden.

Mock-Task-Client

Der Mock-Modus verwendet deterministische In-Memory-Task- und Kommentardaten für lokale Entwicklung und Tests. Er unterstützt nur die aktuellen Mock-Vertragsfelder: Task-id, title, status, priority und Kommentar-id, taskId, author, text, createdAt.

Der Mock-Client gibt bekannte Tasks zurück, lehnt unbekannte Task-IDs ab, hängt jeweils einen Kommentar mit deterministischen IDs an und aktualisiert nur explizit auf der Whitelist stehende Mock-Task-Felder. Diese Felder werden nicht als offizielle SAP-CALM_TKM-Payload-Felder beansprucht. Echte Cloud-ALM-Endpunkte, Payload-Schemata, Scopes, Paginierungsnamen und Aktualisierungssemantik bleiben unverifiziert und werden auf die echte Integrationsarbeit verschoben.

Sicherheitsgrenze

Die Policy Guard wird codebasiert vor Cloud-ALM-Client-Aufrufen durchgesetzt. Sie validiert:

• nur zulässige Operationsnamen,

• Trennung von Lese-/Schreibfähigkeiten,

• Ablehnung von Löschoperationen,

• Ablehnung von Massenoperationen,

• Ablehnung unbekannter Operationen,

• keine agentengelieferte Destination oder Kundenauswahl,

• Fail-Closed-Verhalten bei mehrdeutiger Konfiguration.

Dies ist bewusst keine reine Prompt-Durchsetzung. Kundenisolierung und dauerhafte Audit-Protokollierung bleiben zukünftige Architekturarbeit, wobei Modulgrenzen bereits vorhanden sind.

Audit-Ereignisse reservieren bereits optionale Felder für zukünftige Rückverfolgbarkeit: Akteur, Kundenkontext, Ressourcentyp/-ID und Korrelations-ID. Das Grundgerüst erfindet keine echten Akteur- oder Kundenwerte und protokolliert keine Anforderungs-Payloads, Token, Autorisierungsheader, Client-IDs, Client-Geheimnisse oder sensible Antworttexte.