release 2026.07.08-433699a

INSTALL.md

@@ -46,6 +46,11 @@ installiert und aktualisiert — es wird kein Installationspaket kopiert.
    `setup.sh` bereits gesetzt. `SL_INSECURE=true` nur bei self-signed
    SAP-Zertifikat.
 
+   `MCP_REQUIRED_SCOPE` bleibt im Regelfall **leer**: claude.ai und ChatGPT
+   gewähren den `mcp`-Scope im Consent nicht — mit gesetztem Wert enden deren
+   Tool-Calls mit 403. Nur setzen, wenn ausschließlich Clients zugreifen, die
+   den Scope explizit anfordern.
+
 3. **Stack starten:**
 
    ```
@@ -103,3 +108,9 @@ Wie ein Update, nur mit einer älteren Versionsnummer als Zielversion
 - `secrets/creds_key` — ohne diese Datei sind gespeicherte SAP-Zugangsdaten
   unwiederbringlich verloren
 - `.env` (enthält `SECRETS_SYSTEM` — nach Inbetriebnahme nie ändern)
+
+## Support / Troubleshooting
+
+Für Support-Mitarbeiter ohne Server-Zugang gibt es den separaten Leitfaden
+[`SUPPORT.md`](SUPPORT.md) — Störungsdiagnose komplett über das
+Admin-Webinterface, ohne Kommandozeile.

SUPPORT.md

@@ -0,0 +1,216 @@
+# EasyMCP — Support-Leitfaden (Troubleshooting über das Webinterface)
+
+**Zielgruppe:** Support-Mitarbeiter ohne Server-/SSH-Zugang.
+**Grundsatz:** Alles in dieser Anleitung passiert ausschließlich im Browser über das
+Admin-Webinterface. Es werden keine Kommandozeilen-Kenntnisse benötigt.
+
+> ⚠️ **Wichtigste Regel zuerst:**
+> Ist das **Admin-Webinterface selbst nicht erreichbar** (Seite lädt nicht, Timeout,
+> Zertifikatsfehler, dauerhaft weiße Seite), kann der Support nichts weiter tun →
+> **sofort Meldung an unseren IT-Support** (siehe [Abschnitt 8](#8-wenn-das-webinterface-nicht-erreichbar-ist--meldung-an-den-it-support)).
+
+---
+
+## 1. Die Webadressen
+
+| Adresse | Was ist das? | Für wen? |
+|---|---|---|
+| `https://mcp-admin.<domain>` | **Admin-Webinterface** — das Arbeitswerkzeug des Supports | Support (nur aus dem internen Netz erreichbar!) |
+| `https://mcp-login.<domain>` | Anmelde- und Freigabeseite, die Endbenutzer beim Verbinden sehen | Endbenutzer (automatisch, nie direkt aufrufen) |
+| `https://mcp.<domain>` | Der eigentliche MCP-Endpunkt für KI-Clients (Claude, ChatGPT, …) | Maschinen, keine Webseite |
+| `https://mcp-oauth.<domain>` | OAuth-Dienst (Hydra) | Maschinen, keine Webseite |
+
+`<domain>` durch die beim Kunden konfigurierte Domain ersetzen.
+
+**Zwei Stolperfallen, die KEINE Fehler sind:**
+
+- Die Login-Seite `mcp-login.<domain>` direkt im Browser zu öffnen ergibt
+  **„400 — login_challenge fehlt"**. Das ist **normal** — die Seite funktioniert nur
+  als Teil des Verbindungsvorgangs aus dem KI-Client heraus.
+- Das Admin-Webinterface ist **absichtlich nur aus dem internen Netz** erreichbar.
+  Von extern / aus dem Homeoffice ohne VPN kommt keine Seite — das ist kein Ausfall.
+
+---
+
+## 2. Anmeldung am Admin-Webinterface
+
+- Anmeldung mit dem dafür vorgesehenen **Admin-SAP-Benutzer** (das Passwort wird live
+  gegen SAP geprüft — es ist also immer das aktuelle SAP-Passwort dieses Benutzers).
+- Die Sitzung hält **8 Stunden**; nach einem Neustart des Dienstes oder einem Update
+  ist man abgemeldet und muss sich neu anmelden. Das ist normal.
+
+**Fehlermeldungen bei der Admin-Anmeldung:**
+
+| Meldung | Bedeutung | Maßnahme |
+|---|---|---|
+| „Anmeldung fehlgeschlagen." | Benutzer oder Passwort falsch | Zugangsdaten prüfen (ggf. wurde das SAP-Passwort des Admin-Benutzers geändert) |
+| „SAP-Backend-Problem — liegt nicht an den Zugangsdaten." | SAP Service Layer ist nicht erreichbar | **Meldung an den IT-Support** — das betrifft dann auch alle Endbenutzer |
+| „Zu viele Anmeldeversuche — bitte kurz warten." | Schutzsperre (max. 10 Versuche/Minute) | 1–2 Minuten warten, dann erneut |
+
+---
+
+## 3. Erste Orientierung: die Seite „Übersicht"
+
+Nach der Anmeldung landet man auf der **Übersicht** — bei jeder Störungsmeldung ist das
+der erste Blick:
+
+| Kachel | Zeigt | Worauf achten |
+|---|---|---|
+| **Dienste** | Wie viele Container laufen (z. B. „6 / 6 Ok") | Weniger als alle Ok → Abschnitt 5.7 |
+| **Aktivität 24 h** | Anzahl Tool-Aufrufe der letzten 24 h + Erfolgsquote | Erfolgsquote plötzlich niedrig → Audit prüfen (Abschnitt 4) |
+| **Benutzer** | Anzahl Benutzer mit hinterlegter SAP-Anmeldung | — |
+| **MCP-Tools** | Wie viele Tools aktiviert sind | Weniger als erwartet → Seite „Tools" prüfen |
+
+Darunter: die Dienste-Tabelle (Zustands-Ampel je Container) und die letzten
+Audit-Ereignisse.
+
+Zeigt eine Kachel nur **„—"** mit „Status nicht abrufbar" / „Audit nicht abrufbar",
+ist die zugehörige Datenquelle (Docker-Anbindung bzw. Datenbank) gestört →
+**Meldung an den IT-Support**, die übrigen Kacheln funktionieren unabhängig weiter.
+
+---
+
+## 4. Das wichtigste Diagnosewerkzeug: die Seite „Audit"
+
+Jeder einzelne SAP-Zugriff jedes Benutzers wird hier protokolliert — auch fehlgeschlagene.
+
+- **Filter:** Benutzer, Tool, Status (alle / OK / Fehler), Zeitraum Von/Bis.
+- **Spalten:** Zeit (**in UTC!** — deutsche Zeit ist 1–2 Stunden voraus), Benutzer,
+  SAP-User, Tool, Ziel, Status, **ms** (Antwortzeit), Detail.
+- Bei Fehlern: Zeile aufklappen (**Detail**) → dort steht „Fehler: …" mit der
+  Original-Fehlermeldung aus SAP sowie die (um Passwörter bereinigte) Anfrage.
+- **CSV-Export**: exportiert die gefilterte Ansicht — ideal als Anhang für den IT-Support.
+
+**Typisches Vorgehen bei „bei Benutzer X funktioniert etwas nicht":**
+Filter auf Benutzer X + Status „Fehler" + heutiges Datum → Detail der jüngsten
+Fehler-Einträge lesen.
+
+---
+
+## 5. Häufige Störungen: Symptom → Ursache → Lösung
+
+### 5.1 Benutzer kann den KI-Client nicht verbinden (Anmeldung schlägt fehl)
+
+Der Benutzer sieht: *„Anmeldung fehlgeschlagen. Falls Ihre SAP-Zugangsdaten korrekt
+sind, ist Ihr Benutzer möglicherweise nicht für den MCP freigeschaltet — bitte an die
+IT wenden."*
+
+Diese Meldung ist **absichtlich unspezifisch** — sie bedeutet entweder falsches
+Passwort **oder** fehlende Freischaltung. Reihenfolge für den Support:
+
+1. **Seite „Zugriff" öffnen:** Ist der Benutzer auf **Freigeschaltet**?
+   Nein → Schalter aktivieren → **Speichern**. Fertig, Benutzer erneut versuchen lassen.
+2. Ja, freigeschaltet → Benutzer bitten, sein **SAP-Passwort** zu prüfen
+   (z. B. durch normale SAP-Anmeldung im B1-Client).
+3. Steht auf der Seite „Zugriff" oben der Hinweis
+   *„SAP-Benutzerliste nicht abrufbar …"* → SAP selbst ist gestört →
+   **Meldung an den IT-Support**.
+
+### 5.2 Benutzer war verbunden, plötzlich kommen Fehler / er muss sich neu anmelden
+
+Häufigste Ursache: Der Benutzer hat sein **SAP-Passwort geändert** (oder es ist
+abgelaufen). EasyMCP verwirft die alte Anmeldung dann automatisch.
+**Lösung:** Der Benutzer trennt die Verbindung im KI-Client und verbindet sich neu
+(durchläuft die SAP-Anmeldung erneut). Kein Eingriff im Admin-Interface nötig.
+
+### 5.3 KI meldet: „Benutzer ist nicht für das MCP freigeschaltet."
+
+Seite **„Zugriff"** → Benutzer freischalten → **Speichern**.
+(Benutzer mit Kennzeichnung „Per Config erlaubt" sind fest freigeschaltet und nicht
+über die Oberfläche änderbar.)
+
+### 5.4 KI meldet: „Das Tool … ist vom Administrator deaktiviert."
+
+Seite **„Tools"** → gewünschtes Tool aktivieren → **Speichern**. Wirkt innerhalb
+weniger Sekunden. Achtung: Tools der Gruppen **Schreiben/Löschen** nur nach
+Rücksprache aktivieren.
+
+### 5.5 KI meldet: „Zu viele Anfragen — bitte kurz warten."
+
+Schutzbegrenzung. Kurz warten, dann geht es weiter. Tritt es dauerhaft/massiv auf →
+Audit prüfen, welcher Benutzer die Last erzeugt.
+
+### 5.6 Abfragen sind sehr langsam oder liefern SAP-Fehler
+
+Seite **„Audit"**: Spalte **ms** (Antwortzeit) und die Fehler-Details ansehen.
+Die dort angezeigte Zeit ist der reine SAP-Anteil — hohe Werte bedeuten, dass SAP
+selbst langsam antwortet (oft: sehr breite Abfragen ohne Zeitraum-Eingrenzung).
+Bei anhaltenden Problemen: gefilterten **CSV-Export** erzeugen und mit an den
+IT-Support geben.
+
+### 5.7 Auf der Übersicht ist ein Dienst rot / „Fehler"
+
+1. Seite **„Dienste"** öffnen. Hinweis: **„Exited (0)"** bei Migrations-Jobs ist
+   **Normalzustand** — kein Fehler!
+2. Beim betroffenen Container **„Neu starten"** klicken, kurz warten, Übersicht neu laden.
+3. Bleibt der Dienst rot oder startet immer wieder neu →
+   Seite **„Logs"**: betroffenen Container wählen, **Export (.txt)** erzeugen →
+   **Meldung an den IT-Support** mit dieser Datei.
+
+### 5.8 Benutzer klickt beim Verbinden auf „Erlauben" — und nichts passiert
+
+Bekanntes Infrastruktur-Thema (Browser blockiert die Weiterleitung).
+**Nicht im Admin-Interface lösbar → Meldung an den IT-Support** mit Angabe des
+verwendeten Browsers.
+
+### 5.9 Einem Benutzer soll der Zugriff entzogen werden (z. B. Austritt)
+
+Seite **„Zugriff"** → Schalter des Benutzers deaktivieren → **Speichern**.
+Das löscht sofort seine hinterlegten SAP-Zugangsdaten und beendet laufende
+Sitzungen. (Alternativ Seite **„Benutzer"** → „Zugriff entziehen".)
+
+---
+
+## 6. Update einspielen (Seite „Update")
+
+> Nur nach Absprache bzw. auf Anweisung durchführen.
+
+1. Seite **„Update"**: installierte Version wird angezeigt.
+2. **Zielversion** leer lassen (= neueste Version) → **„Update starten"**.
+3. Der Fortschritt läuft live als Protokoll mit. Die Meldung
+   *„[Verbindung unterbrochen — der Admin-Dienst wird gerade erneuert …]"* ist
+   **normal** — danach neu anmelden (Abschnitt 2).
+4. Anschließend zeigt die Karte **„Letztes Update"**: **Erfolgreich** oder
+   **Fehlgeschlagen**. Bei **Fehlgeschlagen**: Protokolltext kopieren →
+   **Meldung an den IT-Support**.
+
+Mögliche Meldungen: „Es läuft bereits ein Update." (warten, bis es fertig ist),
+„Ungültige Versionsangabe." (Zielversion-Feld prüfen/leeren), „Nicht verfügbar"
+(Update-Funktion nicht eingerichtet → IT-Support).
+
+---
+
+## 7. Die übrigen Seiten in Kürze
+
+| Seite | Zweck für den Support |
+|---|---|
+| **Benutzer** | Wer hat SAP-Zugangsdaten hinterlegt, letzte Anmeldung; „Zugriff entziehen" |
+| **Clients** | Vom KI-Client registrierte OAuth-Verbindungen; verwaiste Einträge löschen |
+| **Kontext** | Kundenspezifischer Zusatztext für die KI — nur nach Absprache ändern |
+| **Logs** | Container-Protokolle einsehen und als .txt exportieren (für den IT-Support) |
+
+---
+
+## 8. Wenn das Webinterface nicht erreichbar ist → Meldung an den IT-Support
+
+Vorher zwei schnelle Checks:
+
+1. **Bin ich im internen Netz / VPN?** Das Admin-Interface ist von außen bewusst
+   gesperrt (Abschnitt 1).
+2. **Anderes Gerät/Browser probieren** — um lokale Ursachen auszuschließen.
+
+Ist die Seite weiterhin nicht erreichbar (oder erscheint dauerhaft ein Fehler,
+der in dieser Anleitung nicht vorkommt): **Ticket/Meldung an unseren IT-Support**
+mit folgenden Angaben:
+
+- [ ] **Welche Adresse** wurde aufgerufen (vollständige URL)
+- [ ] **Exakte Fehlermeldung** bzw. Screenshot (auch „lädt endlos" ist eine Info)
+- [ ] **Uhrzeit** des Auftretens
+- [ ] **Betroffene Benutzer** (einer, mehrere, alle?)
+- [ ] Was **zuletzt gemacht** wurde (z. B. Update gestartet, Dienst neu gestartet)
+- [ ] Falls das Admin-Interface noch teilweise funktioniert: **Logs-Export (.txt)**
+      und/oder **Audit-CSV** anhängen
+
+Gleiches gilt für alle Punkte in dieser Anleitung, die mit
+„Meldung an den IT-Support" enden — je vollständiger die Angaben, desto schneller
+die Lösung.

VERSION

@@ -1 +1 @@
-2026.07.08-6b752bf
+2026.07.08-433699a