MCP-Server

POST /api/v1/mcp ist ein JSON-RPC-2.0-Endpunkt über einfaches HTTP. Er implementiert die Methoden tools/list und tools/call des Model Context Protocol; jede andere Methode — auch initialize — wird mit dem Fehler -32601 beantwortet. Die MCP-Transporte Streamable HTTP und SSE werden nicht angeboten. MCP-Clients, die den vollständigen Handshake benötigen, verwenden die stdio-Brücke weiter unten.

curl -s https://api.example.com/api/v1/mcp \
  -H "X-Api-Key: $ERP_PREFLIGHT_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_project_status","arguments":{"projectId":"<project id>"}}}'

Tool-Ergebnisse stehen als JSON-Text in result.content[0].text. Schlägt ein Tool-Aufruf fehl — etwa weil ein Befund in Ihrer Organisation nicht existiert —, ist result.isError gesetzt. Protokollfehler verwenden -32601 (unbekannte Methode oder unbekanntes Tool), -32602 (ungültige Argumente) und -32003 (fehlender Scope oder nicht erlaubtes Tool).

• Authentifizieren Sie sich mit einem API-Schlüssel im Header X-Api-Key. Ein Schlüssel braucht mindestens einen Scope, um den Endpunkt zu erreichen; jedes Tool prüft anschließend seinen eigenen Scope (siehe unten). Angemeldete Benutzer können den Endpunkt ebenfalls aufrufen; für sie gelten die Tool-Scopes nicht.
• Jeder Aufruf ist mandantenbezogen: Tools lesen nur Daten der aufrufenden Organisation und globales SAP-Wissen.
• Limits: 600 Aufrufe pro Minute je Organisation und 120 je Benutzer oder API-Schlüssel.
• Jede tools/list- und tools/call-Anfrage wird im Audit-Log protokolliert.

• search_knowledge (Scope projects:read) — durchsucht den SAP Knowledge Graph (freigegebene Objekte, Nachfolger, Freigabestatus) und veröffentlichte Wissensartikel. Argumente: query (2 bis 120 Zeichen), optional targetRelease.
• lookup_object (projects:read) — sucht ein SAP-Objekt im Objektkatalog der Projekte Ihrer Organisation und im Knowledge Graph (Freigabevertrag, Clean-Core-Stufe, Nachfolger). Argumente: objectName, optional projectId.
• compare_releases (projects:read) — vergleicht die Listen freigegebener Objekte zweier SAP-Releases (neu freigegeben, veraltet, geänderte Nachfolger). Argumente: sourceRelease, targetRelease, optional objectPrefix und limit (1 bis 200, Standard 50).
• get_project_status (projects:read) — Bereitschaft eines Projekts: letzte abgeschlossene Analyse, offene Befunde nach Schweregrad und Lebenszyklusstatus. Argument: projectId.
• get_findings (findings:read) — Befunde der letzten abgeschlossenen Analyse eines Projekts mit Lebenszyklusstatus. Argumente: projectId, optional severity und limit (1 bis 200, Standard 50).
• explain_finding (findings:read) — Behebungsanleitung, Konfidenz und Evidenzverweise (Pfad, Zeile, SHA-256) eines Befunds. Argument: findingId.
• generate_test (findings:read) — die für einen Befund erzeugten Regressionstest-Spezifikationen; mit promote: true wird daraus ein ausführbarer Test-Lab-Fall, wofür zusätzlich findings:write nötig ist. Argumente: findingId, optional promote.
• get_analysis (analyses:read) — Status, Engines, Laufzeiten und Befundzahlen eines Analyselaufs. Argument: analysisId.
• preflight_change (changes:propose) — die Änderungs-Firewall für Agenten: eine geplante SAP-Änderung vor der Ausführung einreichen. Argumente: projectId, summary (10 bis 2000 Zeichen), targetObjects (die betroffenen SAP-Objekte) und/oder proposedDiff (Format von POST /agent-gate/propose), optional changeType, targetRelease, environment (DEV, QA — Standard —, STAGING, PROD) und agentId. Die Änderung wird wie ein Vorschlag im Agent Gate simuliert und bewertet; das Ergebnis nennt proposalId, decision (APPROVE, REQUEST_CHANGES oder BLOCK), das gespeicherte verdict, riskClass, die verletzten Richtlinien gruppiert in blocking, review und warnings mit ihren Meldungen, die Evidenz (Zielobjekte, Auswirkungsradius, vorhergesagte Befunde, zugehörige Befunde), erforderliche Freigaben und Tests sowie reviewUrl, die Seite, auf der eine Person entscheidet. Erfordert die Tariffunktion Agent Gate; teilt sich das Limit von 120 Vorschlägen pro Minute und Organisation und 30 pro Benutzer oder API-Schlüssel mit der REST-Route.
• get_change_verdict (projects:read) — aktuelle Entscheidung, gespeichertes Prüfergebnis, approvalStatus (PENDING_REVIEW, APPROVED, REJECTED, CHANGES_REQUESTED, EXECUTED) und die Notizen der prüfenden Person zu einem Vorschlag. Argumente: proposalId, optional agentId. Ein Agent liest nur eigene Vorschläge; API-Schlüssel müssen den Agenten nennen (X-Agent-Id oder agentId); angemeldete Benutzer lesen jeden Vorschlag ihrer Organisation.

decision wird aus dem gespeicherten Prüfergebnis abgeleitet: CLEAR → APPROVE, CLEAR_WITH_WARNINGS → APPROVE mit decisionWithWarnings: true, HUMAN_REVIEW_REQUIRED und INSUFFICIENT_EVIDENCE → REQUEST_CHANGES, BLOCKED → BLOCK. APPROVE ist eine Empfehlung: Jede Änderung gibt weiterhin eine Person frei. Bei BLOCK nie ausführen.

Abgesehen vom Übernehmen eines generierten Tests ins Test Lab und vom Einreichen eines Änderungsvorschlags lesen und erläutern die Tools nur; sie ändern keine Daten.

Enthält eine Anfrage den Header X-Agent-Id mit der ID eines Agenten, der im Agent Gate Ihrer Organisation registriert ist, liefert tools/list nur die für diesen Agenten erlaubten Tools, und tools/call weist alle anderen mit -32003 ab. Ein Agent ohne erlaubte Tools kann keines aufrufen. Unbekannte oder inaktive Agenten werden abgewiesen. Ein Argument agentId von preflight_change oder get_change_verdict unterliegt denselben erlaubten Tools; sind beide angegeben, müssen sie übereinstimmen.

Agenten sind herstellerneutral: Jeder hat eine Art (Claude, Codex, GitHub Copilot, SAP Joule oder eigener Agent) und optional eine Herstellerbezeichnung, die mit seinen Vorschlägen angezeigt wird. Neue Agenten dürfen search_knowledge, lookup_object, get_findings, explain_finding, get_project_status, preflight_change und get_change_verdict verwenden, sofern die Registrierung keine anderen Tools nennt. Ein Aufruf von preflight_change über dem Limit liefert -32029 mit retryAfterSeconds; ein Tarif ohne Agent Gate liefert -32003 mit code: ENTITLEMENT_REQUIRED.

Das Paket der CLI enthält außerdem erp-preflight-mcp, einen MCP-Server über stdio für Clients, die einen lokalen Befehl starten. Er beantwortet initialize, tools/list, tools/call und ping. Seine Tools tragen das Präfix erppreflight_ (etwa erppreflight_list_projects, erppreflight_get_findings, erppreflight_search_knowledge) und rufen mit Ihrem API-Schlüssel die REST-API oder den oben beschriebenen Endpunkt auf; es gelten also die Scopes des Schlüssels. erppreflight_propose_change und erppreflight_simulate_changeset legen Change Sets an bzw. simulieren sie und benötigen projects:write.

• API-Schlüssel: ERP_PREFLIGHT_API_KEY, sonst der von erp-preflight login gespeicherte Schlüssel.
• API-URL: ERP_PREFLIGHT_API_URL, sonst die von login gespeicherte URL, sonst http://localhost:3001. Fehlt /api/v1, wird es angehängt — genau wie in der CLI.
• Konfigurationsverzeichnis: ERP_PREFLIGHT_CONFIG_DIR ersetzt ~/.erppreflight, wie in der CLI.
• Agent: ERP_PREFLIGHT_AGENT_ID (optional) wird bei Aufrufen des oben beschriebenen Endpunkts als X-Agent-Id gesendet; so gelten die erlaubten Tools des Agenten, und Änderungsvorschläge werden ihm zugeordnet.
• erppreflight_preflight_change und erppreflight_get_change_verdict rufen die Tools preflight_change und get_change_verdict mit denselben Argumenten auf.
• erppreflight_get_status liefert den Bereitschaftsbericht der API (/health/readiness: Datenbank, Redis, Speicher, Analysedienst, Malware-Scanner) mit seinem HTTP-Status.
• erp-preflight mcp startet denselben Server wie erp-preflight-mcp.

Beispielkonfiguration eines Clients (Datei und Ablageort hängen von Ihrem MCP-Client ab):

{
  "mcpServers": {
    "erp-preflight": {
      "command": "erp-preflight-mcp",
      "env": {
        "ERP_PREFLIGHT_API_KEY": "erppf_live_…",
        "ERP_PREFLIGHT_API_URL": "https://api.example.com",
        "ERP_PREFLIGHT_AGENT_ID": "<Agenten-ID aus dem Agent Gate>"
      }
    }
  }
}