Customer MCP Server

Customer MCP Server ist ein Projekt zur Verbindung von LLMs mit Kundendaten mithilfe des Model Context Protocol (MCP), damit KI-Clients sicher und mit einem klaren Kontrollrahmen auf Kundendaten zugreifen können.

Systemüberblick

Dieses System ist so konzipiert, dass LLMs nur über definierte Tools auf Kundendaten zugreifen können, ohne direkten Zugriff auf die Datenbank.

Unterstützte Funktionen

• Grundlegende Kundeninformationen abrufen

• Semantische Suche im Kundenkommunikationsverlauf mithilfe von Vektor-Embeddings

• Zusammenfassung von Kauf- und Finanztransaktionsdaten mit exakten Werten

• Audit-Log für Transaktionen erfassen

• Schutz vor Prompt Injection und unbefugtem Datenzugriff

Architektur

LLM Client
    |
    | MCP Protocol
    v
MCP Server (Python)
    |
    +-------------------+
    |                   |
    v                   v
Semantic Search      SQL / Financial
PostgreSQL + pgvector PostgreSQL

Hauptfunktionen

1. Kundenprofil

• Grundlegende Kundendaten abrufen, z. B. customer_id, name, email, phone, created_at

2. Semantische Suche nach Interaktionen

• Den Chat-/Interaktionsverlauf des Kunden mithilfe von Embedding-Vektoren durchsuchen

• Geeignet für die semantische Suche nach Bedeutung in allgemeinen Fragen wie „refund issue“, „complaint“, „billing concern“

3. Finanzübersicht

• Berechnet die Anzahl der Bestellungen und den Gesamtkaufbetrag aus der Datenbank

• Verwendet SQL-Aggregation, um genaue und zuverlässige Werte zu erhalten

• Gibt ein Audit-Log der Transaktionen mit Hash-Referenz zurück

Beispiel für eine Hybridabfrage

Beispielfrage:

„Welche Probleme hat der Kunde gemeldet und wie hoch ist der Gesamtkaufbetrag?“

Ablauf:

search_customer_interactions()

    |
    v

pgvector-Ähnlichkeitssuche

    +

get_customer_purchase_summary()

    |
    v

SQL-Aggregation

    |
    v

Kombinierte verifizierte Antwort

Prozess:

1. Der MCP-Server ruft die semantische Suche in interaction_history mithilfe von pgvector auf.

2. Der MCP-Server ruft die Finanzübersicht aus purchase_orders per SQL-Aggregation ab.

3. Fasst die Ergebnisse zusammen:

• Kundenkontext

• Relevante Interaktion

• Exakter Finanzbetrag

und sendet sie an das LLM zurück.

4. Sicherheitsvorkehrungen

• Erkennt Prompt-Injection-Muster

• Überprüft die customer_id vor dem Datenzugriff

• Beschränkt den Datenzugriff ausschließlich auf MCP-Tools

Verwendete Technologien

• Python 3.12+

• FastMCP

• asyncpg

• pydantic

• openai

• google-genai

• PostgreSQL 17 + pgvector

• Docker Compose

Projektstruktur

customer-mcp/
├── app/
│   ├── config.py
│   ├── database.py
│   ├── embeddings.py
│   ├── mcp_server.py
│   ├── security.py
│   └── tools/
│       ├── customer.py
│       ├── financial.py
│       └── semantic_search.py
├── docs/
│   └── ARCHITECTURE.md
├── sql/
│   ├── 01_extensions.sql
│   ├── 02_schema.sql
│   ├── 03_indexes.sql
│   ├── 04_seed.sql
│   └── 05_security.sql
├── docker-compose.yml
├── requirements.txt
├── test_customer.py
├── test_embedding.py
├── test_financial.py
├── test_search.py
├── test_security.py
└── README.md

Voraussetzungen

• Python 3.12 oder neuer

• Docker Desktop

• Netzwerkzugriff zum Installieren von Paketen aus PyPI

Installation und Konfiguration

1. Virtuelle Umgebung erstellen

py -3.12 -m venv venv

Unter Windows:

venv\Scripts\activate

2. Abhängigkeiten installieren

pip install -r requirements.txt

3. Umgebungsvariablen konfigurieren

Erstellen Sie eine .env-Datei mit folgendem Beispiel:

DATABASE_URL=postgresql://mcp_readonly_user:CHANGE_ME@localhost:5432/customer_mcp

GEMINI_API_KEY=your_gemini_api_key_here

4. PostgreSQL-Datenbank starten

docker compose up -d

Docker Compose erstellt PostgreSQL- und pgvector-Container und initialisiert die Datenbank automatisch mit SQL-Skripten im Ordner sql/

Hinweis:

Die SQL-Skripte in docker-entrypoint-initdb.d werden nur beim ersten Erstellen des PostgreSQL-Volumes ausgeführt.

Wenn Sie eine vollständige Neuinitialisierung durchführen möchten:

docker compose down -v

docker compose up -d

Initialisierungsreihenfolge

sql/01_extensions.sql PostgreSQL-Erweiterungen aktivieren pgvector aktivieren sql/02_schema.sql Kundentabellen erstellen Interaktionsverlauf-Tabelle erstellen Kauftabellen erstellen Unveränderliche Audit-Struktur erstellen sql/03_indexes.sql Datenbankindizes erstellen pgvector-HNSW-Index für die semantische Suche erstellen sql/04_seed.sql Demo-Kundendaten einfügen Interaktionsverlauf einfügen Kaufdatensätze einfügen Audit-Datensätze einfügen sql/05_security.sql Schreibgeschützten Datenbankbenutzer erstellen SELECT-Berechtigung erteilen

Container überprüfen

docker ps

5. MCP-Server ausführen

python -m app.mcp_server

MCP Inspector

Die MCP-Tools können auch über die Benutzeroberfläche geprüft werden.

mcp-inspector python -m app.mcp_server

Verfügbare MCP-Tools

get_customer_profile

Ruft das Profil eines Kunden ab.

Datenquelle:

• customers-Tabelle

Rückgabewerte:

• customer_id

• first_name

• last_name

• email

• phone

• created_at

Beispieleingabe:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

search_customer_interactions

Semantische Suche im Interaktionsverlauf über pgvector.

Beispieleingabe:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "refund issue",
  "limit": 3
}

get_customer_purchase_summary

Ruft den exakten Kaufbetrag per SQL-Aggregation ab.

Beispieleingabe:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

Verfügbare MCP-Tools

Tests

Die folgenden Testdateien können aus dem Repository-Root-Verzeichnis ausgeführt werden:

python test_embedding.py
python test_search.py
python test_financial.py
python test_security.py
python test_customer.py

Sicherheitshinweise

• LLMs können nicht direkt auf die Datenbank zugreifen.

• Der Datenzugriff ist ausschließlich über MCP-Tools möglich.

• Für customer_id wird eine Eingabevalidierung verwendet.

• Prompt-Injection-Muster werden erkannt.

• Finanzdaten verwenden SQL-Aggregation, um exakte Werte zurückzugeben.

• Das Audit-Log ist eine unveränderliche Append-Only-Struktur.

• Der Datenbankbenutzer für MCP verwendet das Prinzip der geringsten Rechte (Least Privilege).

• UPDATE- / DELETE- / DDL-Operationen sind nicht zulässig.