easymcp-release/SUPPORT.md

# 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.