Agentic Retail MCP-System

Eine Full-Stack-Anwendung für künstliche Intelligenz, die einen Model Context Protocol (MCP)-Server implementiert, der sicher an eine Firebase Firestore-Datenbank angebunden ist, über eine Streamlit-Chat-Schnittstelle gesteuert wird und von OpenAIs gpt-4o betrieben wird.

Systemarchitektur

Dieses Projekt wurde unter Verwendung eines entkoppelten Microservice-Musters erstellt:

1. MCP-Backend-Server (src/server.py): Ein fastmcp-Python-Server, der einzelhandelsspezifische Tools ['check_inventory', 'calculate_elasticity', 'get_demand_forecast'] bereitstellt. Verbindet sich direkt mit Google Cloud Firestore.

2. KI-Streamlit-Frontend (src/client.py): Eine asynchrone Web-Benutzeroberfläche, die mit Ihrem Backend-Server über persistente Server-Sent Events (SSE) kommuniziert. Analysiert Tool-Eingaben und schleift diese dynamisch in OpenAI-Funktionsaufrufe ein.

Related MCP server: E-commerce MCP Server

Voraussetzungen & Konfiguration

Bevor Sie Skripte ausführen, müssen Sie Ihre .env-Datei im Stammverzeichnis des Projekts konfigurieren.

Erstellen Sie eine .env-Datei und definieren Sie die folgenden Variablen:

# Your OpenAI API Key for the GPT-4o Agent
OPENAI_API_KEY="sk-proj-YOUR-KEY-HERE"

# The absolute path to your Firebase Service Account JSON key
FIREBASE_CREDENTIALS_PATH="./firebase-key.json"

(Wenn FIREBASE_CREDENTIALS_PATH leer gelassen wird, versucht das System, die Application Default Credentials von Google Cloud nativ zu verwenden).

Installation

Dieses Projekt verwendet uv als blitzschnellen Python-Paket-Abhängigkeitsmanager.

Führen Sie den folgenden Befehl im Stammverzeichnis aus, um sicherzustellen, dass die Abhängigkeiten auf Python >= 3.11 abgebildet sind:

uv init
uv add mcp pydantic firebase-admin python-dotenv openai streamlit

Datenbankinitialisierung (Mock-Daten)

Wenn Sie eine neue Firebase Firestore-Instanz haben, können Sie die integrierten Seeding-Tools verwenden, um Ihre Datenbank mit 100 Beispiel-Einzelhandelsprodukten zu füllen.

1. Generieren Sie die statischen CSV-Mock-Datenstrukturen:

   uv run python generate_data.py

2. Streamen Sie die generierten CSV-Daten direkt in Ihre Firebase NoSQL-Datenbank:

   uv run python seed_db.py

Ausführen der Anwendung

Da die Web-Schnittstelle und der Tool-Server über eine isolierte lokale Netzwerkschleife kommunizieren, müssen Sie beide Prozesse parallel in zwei separaten Terminal-Tabs ausführen.

1. Starten des Backend-Tool-Servers

Dies startet eine ASGI-Uvicorn-App auf Port 8000, die alle Tool-Ausführungsanfragen nativ über HTTP Server Sent Events verarbeitet.

uv run python src/server.py

2. Starten des Streamlit-Clients

Starten Sie in einem neuen Terminalfenster den Streamlit-Konversationsagenten:

uv run streamlit run src/client.py 

Ein Webbrowser-Tab öffnet sich automatisch unter http://localhost:8501. Sie können nun Fragen stellen wie "Wie hoch ist der Lagerbestand von Produkt P1002?" oder "Analysiere die Preiselastizitätsprognosen für P1100".

Cloud-Bereitstellungen (Google Cloud Run)

Wenn Sie Ihren KI-Agenten und Ihre Backend-Infrastruktur dauerhaft in die Cloud verlagern möchten, habe ich fortschrittliche Dockerfiles konfiguriert, die speziell für die serverlose Bereitstellung auf Google Cloud Run entwickelt wurden.

Bitte lesen Sie die vollständige DEPLOYMENT.md-Dokumentation für Anweisungen zum Hochladen beider Container ins Web.