diff --git a/INSTALL.md b/INSTALL.md index 0dbb11c..30432ce 100644 --- a/INSTALL.md +++ b/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. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..684a7a6 --- /dev/null +++ b/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.` | **Admin-Webinterface** — das Arbeitswerkzeug des Supports | Support (nur aus dem internen Netz erreichbar!) | +| `https://mcp-login.` | Anmelde- und Freigabeseite, die Endbenutzer beim Verbinden sehen | Endbenutzer (automatisch, nie direkt aufrufen) | +| `https://mcp.` | Der eigentliche MCP-Endpunkt für KI-Clients (Claude, ChatGPT, …) | Maschinen, keine Webseite | +| `https://mcp-oauth.` | OAuth-Dienst (Hydra) | Maschinen, keine Webseite | + +`` durch die beim Kunden konfigurierte Domain ersetzen. + +**Zwei Stolperfallen, die KEINE Fehler sind:** + +- Die Login-Seite `mcp-login.` 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. diff --git a/VERSION b/VERSION index b38f475..8093a52 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2026.07.08-9f6d863 +2026.07.08-433699a