Gmail + SAP MCP-Assistent

Eine Streamlit-Anwendung, mit der Sie Gmail lesen und verwalten, SAP Business Partner / Vertrieb / Abrechnung / Produktdaten durchsuchen und einen KI-Assistenten natürliche Sprachfragen zu Ihrem Posteingang (und SAP-Datensätzen) stellen können – alles über einen einzigen Model Context Protocol (MCP)-Server.

                              Streamlit UI (app.py)
                                       │
                       ┌───────────────┴───────────────┐
                       ▼                               ▼
           Gmail / SAP / Admin tabs                  Ai tab
           (direct button click)              EmailAssistant (ai_agent.py)
                       │                       → Mistral LLM decides which
                       │                         tool(s) to call, if any
                       │                                │
                       └───────────────┬────────────────┘
                                       ▼
                     MCPClient (mcp_client.py) — one persistent
                     background event loop for every call, either path
                                        │
                                        │  Streamable HTTP transport
                                        ▼
                        FastMCP server (server.py) — dispatches
                              the tool call by name
                                        │
                       ┌────────────────┴────────────────┐
                       ▼                                 ▼
                GmailService                        SAPService
              (gmail_service.py)                  (sap_service.py)
                       │                                  │
                       ▼                                  ▼
                  Gmail API                          SAP OData API
                (OAuth credentials)                  (API key, sandbox)

Die Benutzeroberfläche kommuniziert nie direkt mit Gmail oder SAP – jede Aktion, ob ein Button-Klick oder etwas, das der KI-Assistent entschieden hat, läuft über denselben MCPClient → FastMCP-Server → Service-Layer-Pfad. Dadurch bleibt eine einzige, prüfbare Grenze zwischen der App und den beiden externen Systemen erhalten.

Anfragefluss

Es gibt zwei Möglichkeiten, wie eine Anfrage in das System gelangt, und sie treffen sich bei MCPClient.

1. Direkte UI-Aktion (Gmail / SAP / Admin-Tabs)

1. Sie klicken auf einen Button (z. B. „Suchen" im Gmail-Tab). app.py ruft eine Methode direkt auf der gemeinsamen MCPClient-Instanz auf, z. B. mcp_client.gmail_search_messages(query, max_results).

2. MCPClient plant diese Koroutine auf seiner dedizierten Hintergrund- Ereignisschleife und blockiert, bis sie abgeschlossen ist (_loop.run(...) in mcp_client.py) – das hält die MCP-Sitzung über Streamlits Rerun-pro-Interaktion-Modell hinweg sicher.

3. Der FastMCP-Server (server.py) empfängt den Tool-Aufruf über Streamable HTTP und leitet ihn an die passende Funktion weiter, z. B. gmail_search_messages().

4. Diese Funktion ruft GmailService (gmail_service.py) oder SAPService (sap_service.py) auf, die den eigentlichen Netzwerkaufruf durchführen – die Gmail-API (OAuth) oder die SAP-OData-API (API-Schlüssel) – und gibt geparste, einfache Dict-Ergebnisse zurück.

5. Das Ergebnis wandert zurück: MCP-Server → MCPClient._unwrap() → app.py, das es in st.session_state speichert und rendert.

Fehler auf jeder Ebene (MCPToolError, MCPConnectionError oder etwas Unerwartetes) werden zentral von run_action() in app.py abgefangen und als st.error angezeigt, sodass ein fehlgeschlagener Aufruf die UI nie abstürzen lässt.

2. KI-Assistent-Frage (KI-Tab)

Dies ist dieselbe Pipeline mit einer Entscheidungsschleife davor:

1. Ihre Frage (plus Chat-Verlauf) geht an EmailAssistant.ask() in ai_agent.py, das einen System-Prompt über prompts.py erstellt (mit heutigem/morgigem Datum) und ihn zusammen mit dem TOOLS-Schema an Mistral sendet.

2. Mistral entscheidet, ob es ein Tool benötigt. Wenn ja, führt ai_agent.py den Aufruf über dieselbe MCPClient-Instanz aus, die auch von den manuellen Tabs verwendet wird – EmailAssistant kommuniziert nie selbst mit Gmail/SAP – und fügt das JSON-Ergebnis wieder in das Gespräch ein.

3. Die Schritte 1–2 wiederholen sich (Suchen, dann vielleicht eine bestimmte Nachricht lesen, dann vielleicht eine weitere Suche) bis zu MISTRAL_MAX_STEPS-Mal (Standard: 12).

4. Sobald Mistral genügend Informationen hat, stoppt es die Tool-Aufrufe und gibt eine endgültige Antwort in natürlicher Sprache zurück, die app.py im Chat rendert – mit der vollständigen Tool-Aufruf-Spur in einem aufklappbaren „Verwendete Tool-Aufrufe"-Expander zum Debuggen.

Die Tool-Liste des Agents ist bewusst schmal (nur lesende Gmail/SAP- Nachschlagefunktionen), sodass er unabhängig von Ihrer Frage nichts senden, löschen oder ändern kann. Nur die manuellen Abläufe im Gmail-Tab können das, und jeder davon erfordert einen expliziten Bestätigungsschritt, bevor die zerstörerische Aktion ausgeführt wird.

3. App-Start (einmal pro Prozess)

get_mcp_client() in app.py ist mit @st.cache_resource umschlossen, sodass es genau einmal ausgeführt wird: Es erstellt den MCPClient, ruft .connect() auf, das den Hintergrund-Thread + die Ereignisschleife startet und die Streamable-HTTP-Sitzung zum FastMCP-Server öffnet. Diese Sitzung bleibt für die Lebensdauer des Streamlit-Prozesses aktiv – sie wird nicht bei jedem Rerun neu erstellt.

Funktionen

Gmail (über den Tab „Gmail")

• Nachrichten mit Gmail-eigener Suchsyntax auflisten / suchen

• Vollständige Nachricht lesen (Text, Header, Anhänge)

• E-Mails senden, Entwürfe erstellen, Nachrichten in den Papierkorb verschieben (jeweils mit explizitem Bestätigungsschritt in der UI)

• Nachrichten als gelesen/ungelesen markieren, Labels auflisten, Anhangs-Bytes abrufen

SAP (über den Tab „SAP")

• Konfiguration / Konnektivität zur SAP-OData-Sandbox prüfen

• Business Partner auflisten und suchen, einen einzelnen Partner anzeigen

• E-Mail-Adressen in den Daten auflisten

• (Standardmäßig schreibgeschützt – siehe SAP-Schreibzugriffe unten)

KI-Assistent (über den Tab „KI")

Ein Mistral-basierter Agent (ai_agent.py / EmailAssistant), der natürliche Sprachfragen beantwortet, wie zum Beispiel:

• „Fasse die wichtigen E-Mails von heute zusammen"

• „Finde E-Mails mit Anhängen"

• „Habe ich morgen Vorstellungsgespräche geplant?"

• „Fasse E-Mails der letzten 7 Tage zusammen"

Der Agent ist bewusst schreibgeschützt: Er kann nur gmail_search_messages, gmail_read_message und gmail_list_messages aufrufen (plus die schreibgeschützten SAP-Nachschlagefunktionen, die in prompts.py beschrieben sind). Er hat kein Tool zum Senden, Antworten oder Löschen von etwas, und der System-Prompt weist ihn ausdrücklich an, dies zu sagen, wenn er danach gefragt wird – jede Tatsache in seinen Antworten muss auf ein tatsächliches Tool-Ergebnis zurückgehen, niemals auf eine erfundene.

Verwaltungstab

Live-MCP-Verbindungsstatus, die Liste der Tools, die der Server derzeit bereitstellt, und die zuletzt abgerufene Gmail/SAP-Konfiguration – nützlich, um zu überprüfen, ob der Server erreichbar und korrekt konfiguriert ist.

Projektstruktur

Voraussetzungen

• Python 3.10+

• Ein Google-Cloud-Projekt mit aktivierter Gmail-API und einem OAuth- Desktop-App-Client (credentials.json)

• Zugriff auf eine SAP-OData-Sandbox (z. B. den SAP Business Accelerator Hub) mit einem API-Schlüssel, wenn der SAP-Tab/die SAP-Tools funktionieren sollen

• Ein Mistral-API-Schlüssel, wenn der KI-Assistent-Tab funktionieren soll

Einrichtung

1. Abhängigkeiten installieren

   python -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   pip install -r requirements.txt

2. Gmail-OAuth-Anmeldedaten

   Laden Sie die credentials.json Ihres OAuth-Clients von der Google Cloud Console herunter und legen Sie sie unter credentials/credentials.json ab (oder setzen Sie GMAIL_CREDENTIALS_FILE auf einen anderen Pfad). Beim ersten Aufruf eines Gmail-Tools öffnet der Server ein Browserfenster zur Autorisierung; das resultierende Token wird in credentials/token.json geschrieben.

3. Umgebungsvariablen

   Erstellen Sie eine .env-Datei im Projektstamm:

   # --- MCP server ---
   MCP_SERVER_HOST=127.0.0.1
   MCP_SERVER_PORT=8000
   LOG_LEVEL=INFO
   
   # --- MCP client (Streamlit side) ---
   MCP_SERVER_URL=http://127.0.0.1:8000/mcp
   MCP_CONNECT_TIMEOUT_SECONDS=20
   MCP_CALL_TIMEOUT_SECONDS=60
   
   # --- Gmail ---
   GMAIL_CREDENTIALS_FILE=credentials/credentials.json
   GMAIL_TOKEN_FILE=credentials/token.json
   
   # --- SAP ---
   SAP_MODE=sandbox
   SAP_BASE_URL=https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER
   SAP_API_KEY=your-sap-api-key
   SAP_VERIFY_SSL=true
   SAP_WRITE_ENABLED=false
   SAP_TIMEOUT_SECONDS=30
   
   # --- AI Assistant ---
   MISTRAL_API_KEY=your-mistral-api-key
   MISTRAL_MODEL=mistral-large-latest
   MISTRAL_MAX_STEPS=12

   Jede Variable hat einen sinnvollen Standardwert, außer den Anmeldedaten/ API-Schlüsseln selbst – siehe die Spitze jeder *_service.py / *_client.py- Datei für die genauen Fallback-Werte.

4. MCP-Server ausführen

   python server.py

   Dies startet den FastMCP-Server auf MCP_SERVER_HOST:MCP_SERVER_PORT über den Streamable-HTTP-Transport.

5. Streamlit-App ausführen (in einem zweiten Terminal)

   streamlit run app.py

   Öffnen Sie die URL, die Streamlit ausgibt (normalerweise http://localhost:8501).

SAP-Schreibzugriffe

SAPService implementiert bereits create_business_partner und update_business_partner gegen die OData-Schreibendpunkte von SAP, aber die entsprechenden MCP-Tools sind in server.py auskommentiert und die Aufrufe sind in sap_service.py hart hinter SAP_WRITE_ENABLED=true gesperrt. Um sie zu aktivieren:

1. Setzen Sie SAP_WRITE_ENABLED=true in .env.

2. Kommentieren Sie die Tool-Definitionen sap_create_business_partner / sap_update_business_partner in server.py aus.

3. Starten Sie den MCP-Server neu.

Bis dahin ist der gesamte SAP-Zugriff unabhängig vom Flag schreibgeschützt.

Sicherheitshinweise

• Der KI-Assistent kann Gmail nur lesen – er hat kein Sende-/Lösch-/ Änderungs-Tool, was sowohl in der TOOLS-Liste von ai_agent.py als auch im System-Prompt in prompts.py erzwungen wird.

• Das Senden von E-Mails, das Erstellen von Entwürfen und das Löschen/ Verschieben in den Papierkorb im Gmail-Tab erfordern jeweils ein explizites Bestätigungskontrollkästchen oder einen „Suchen → Öffnen → Bestätigen"-Ablauf, bevor die zerstörerische Aktion ausgeführt wird.

• SAP-Schreibzugriffe sind standardmäßig deaktiviert (SAP_WRITE_ENABLED=false) und die Tools, die sie ausführen würden, sind auf dem MCP-Server nicht einmal registriert, es sei denn, Sie aktivieren sie.

Fehlerbehebung

• „Verbindung zum MCP-Server fehlgeschlagen" – stellen Sie sicher, dass server.py läuft und MCP_SERVER_URL in Ihrer .env mit dessen Host/Port übereinstimmt.

• Gmail-OAuth-Fehler mit veraltetem/ungültigem Token – löschen Sie die Datei unter GMAIL_TOKEN_FILE und versuchen Sie es erneut; die App führt den OAuth-Flow erneut aus.

• SAP-Anfragen schlagen mit HTTP-Fehlern fehl – einige SAP-Sandbox- Mandanten haben nicht jeden OData-Dienst (z. B. API_SALES_ORDER_SRV, API_BILLING_DOCUMENT_SRV) standardmäßig aktiviert; prüfen Sie den Fehlertext gegen Ihren API-Katalog.

• „KI-Assistent nicht verfügbar" – MISTRAL_API_KEY fehlt oder ist leer in .env.