Sapphire User MCP Server

Ein Python-Model Context Protocol (MCP)-Server, der Benutzerprofildaten aus der Sapphire Wellness App für KI-Assistenten bereitstellt – einschließlich Gesundheitswarnungen, personalisierter Empfehlungen und Partnerdienst-Abonnements.

Verfügbare Tools

Related MCP server: Sapphire Wellness MCP Server

Architektur

Agent Container
      │  HTTP SSE
      ▼
sapphire-user-mcp:10003
      │
      ├──httpx──▶  User Profile API:8091
      │
      └──httpx──▶  Partner Service API:8085

• Transport: HTTP SSE – erforderlich für Multi-Container-Bereitstellungen (stdio funktioniert nur, wenn der Agent den MCP-Server als untergeordneten Prozess startet)

• Upstream-APIs: Alle Tools rufen REST-APIs über HTTP auf – kein direkter Datenbankzugriff

• Framework: FastMCP mit Pydantic-v2-Antwortmodellen

Projektstruktur

SAPPHIRE-USER-MCP/
├── sapphire_user/
│   ├── server.py           # FastMCP app + SSE entry point
│   ├── config.py           # Settings (API URLs, HOST, PORT via env)
│   ├── models/             # Pydantic response models
│   │   ├── alerts.py
│   │   ├── recommendations.py
│   │   ├── partner_service.py
│   │   └── subscriptions.py
│   └── tools/              # MCP tool definitions
│       ├── alerts.py
│       ├── recommendations.py
│       └── subscriptions.py
├── pyproject.toml
├── Dockerfile
└── .env.example

Voraussetzungen

• Python 3.11+

• Eine laufende Sapphire User Profile API (Standard: http://localhost:8091)

• Eine laufende Sapphire Partner Service API (Standard: http://localhost:8085)

Schnellstart

Lokale Entwicklung

# 1. Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# 2. Install dependencies
pip install -e .

# 3. Configure environment
cp .env.example .env
# Edit .env — set USER_PROFILE_API_BASE_URL and PARTNER_SERVICE_API_BASE_URL

# 4. Run the server
python -m sapphire_user.server
# Server starts at http://0.0.0.0:8001

Containerisiert (Docker)

# Build the image
docker build -t sapphire-user-mcp .

# Run the container
docker run -p 10003:10003 --env-file .env sapphire-user-mcp

Der MCP-Server ist unter http://localhost:10003/sse verfügbar.

Um Ihren Agent-Container zu verbinden, setzen Sie:

MCP_SERVER_URL=http://sapphire-user-mcp:10003/sse

Konfiguration

Alle Einstellungen werden aus Umgebungsvariablen (oder einer .env-Datei) gelesen:

Tool-Referenz

Alle Tools akzeptieren einen einzelnen Parameter user_email.

get_user_alerts

Ruft Gesundheitswarnungen für den Benutzer von der User Profile API ab. Jede Warnung enthält:

• severity – Dringlichkeitsstufe der Warnung (z. B. critical, warning)

• category – Metrikkategorie, die die Warnung ausgelöst hat

• alertMessage – menschenlesbare Beschreibung der Warnung

• metricName / metricType – die spezifische Metrik, die einen Schwellenwert überschritten hat

get_user_recommendations

Gibt personalisierte Empfehlungen für Partnerdienste zurück, sortiert nach Relevanzwert. Jede Empfehlung enthält:

• relevanceScore – ganzzahlige Bewertung, wie gut der Dienst zum Gesundheitsprofil des Benutzers passt

• partnerService – Dienstname, Kategorie, Typ und Beschreibung

• generatedAt – Zeitstempel, wann die Empfehlung berechnet wurde

get_user_subscriptions

Ruft die aktiven Partnerdienst-Abonnements des Benutzers ab und ergänzt jedes mit vollständigen Servicedetails von der Partner Service API. Jedes Abonnement enthält:

• partnerServiceId – die Kennung des eingeschriebenen Dienstes

• isActive – ob das Abonnement derzeit aktiv ist

• associationContext – Vertragsendedatum und andere kontextbezogene Metadaten

• service_details – vollständige Dienstspezifikation, Preise, Verfügbarkeit und Vertragsinformationen

Tools untersuchen

Verwenden Sie den MCP Inspector, um Tool-Schemas zu erkunden und Testaufrufe durchzuführen:

npx @modelcontextprotocol/inspector http://localhost:8001/sse

Verbindung zu Claude Desktop herstellen

Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "sapphire-user": {
      "url": "http://localhost:8001/sse"
    }
  }
}

Fragen Sie dann Claude: „Welche Gesundheitswarnungen hat sarah.chen@sapphirewellness.com?" und es wird get_user_alerts mit der angegebenen E-Mail aufrufen.

Erweitern

Hinzufügen eines neuen Tools:

1. Erstellen Sie sapphire_user/models/<name>.py – Pydantic-Antwortmodell

2. Erstellen Sie sapphire_user/tools/<name>.py – @mcp.tool()-Definition, die die entsprechende API aufruft

3. Registrieren Sie es in server.py