Sapphire Wellness MCP Server

Ein Python-Model Context Protocol (MCP)-Server, der Gesundheitsmetriken aus der Sapphire Wellness App für KI-Assistenten bereitstellt.

Verfügbare Metriken

Related MCP server: Sapphire Wellness MCP Server

Architektur

Agent Container
      │  HTTP SSE
      ▼
sapphire-mcp:8000  ──asyncpg──▶  PostgreSQL:5432

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

• Datenbank: PostgreSQL mit OpenTelemetry-artigen Metriktabellen (time, metric_name, metric_value, attributes JSONB, ...)

• Framework: FastMCP mit Pydantic-v2-Antwortmodellen

Siehe Design.md für das vollständige Architekturdokument.

Projektstruktur

MCPServers/
├── sapphire_wellness/
│   ├── server.py           # FastMCP app + SSE entry point
│   ├── config.py           # Settings (DB_URL, HOST, PORT via env)
│   ├── models/             # Pydantic response models per metric
│   ├── db/                 # asyncpg pool + shared base query
│   ├── repositories/       # DB → model mapping (one per metric)
│   └── tools/              # MCP tool definitions (one per metric)
├── Design.md               # Architecture reference
├── pyproject.toml
├── Dockerfile
├── podman-compose.yml
└── .env.example

Voraussetzungen

• Python 3.11+

• PostgreSQL 14+ mit den 6 erstellten Wellness-Metriktabellen

• podman-compose oder Docker Compose (für containerisierte Bereitstellung)

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 DB_URL to your PostgreSQL connection string

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

Containerisiert (podman-compose)

# Build and start all services (postgres + mcp server)
podman-compose up --build

# Tear down
podman-compose down

Der MCP-Server ist unter http://localhost:10002/sse erreichbar.

Um Ihren Agent-Container zu verbinden, setzen Sie:

MCP_SERVER_URL=http://sapphire-mcp:10002/sse

Konfiguration

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

Tool-Referenz

Alle Tools teilen diese Parameter:

get_activity

Gibt Schritte, Kalorien, Distanz und aktive Minuten zurück. Die Summen werden über den Zeitraum aufsummiert.

get_blood_pressure

Gibt systolische/diastolische Messwerte in mmHg zurück. Jeder Messwert wird anhand der AHA-Kategorien klassifiziert:

• Normal — systolisch <120 und diastolisch <80

• Erhöht — systolisch 120–129 und diastolisch <80

• Hypertonie Grad 1 — systolisch 130–139 oder diastolisch 80–89

• Hypertonie Grad 2 — systolisch ≥140 oder diastolisch ≥90

• Hypertensive Krise — systolisch >180 oder diastolisch >120

get_glucose

Gibt Glukosemesswerte in mg/dL mit Mahlzeitenkontext (fasting, pre_meal, post_meal, bedtime, random) und Statistiken einschließlich Zeit im Zielbereich (Ziel: 70–180 mg/dL) zurück.

get_heart_rate

Gibt Herzfrequenzmesswerte in BPM (aktiv und in Ruhe) mit Durchschnitt, Min, Max und durchschnittlichem Ruhepuls zurück.

get_sleep

Gibt die Aufschlüsselung der Schlafphasen (Tief, Leicht, REM, Wach) in Minuten, Gesamtdauer und Schlafeffizienz in Prozent zurück.

get_spo2

Gibt SpO2-Messwerte in % mit Durchschnitt, Min, Max und einer Anzahl von Niedrigsättigungs-Ereignissen (unter 95 %) zurück.

get_health_summary

Ruft alle 6 Metrik-Repositories gleichzeitig auf und gibt eine einzige kombinierte Antwort zurück — ideal für tägliche Gesundheits-Briefings.

Tools untersuchen

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

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

Verbindung zu Claude Desktop

Fügen Sie zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "sapphire-wellness": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Fragen Sie dann Claude: „Wie war mein Blutdruck diese Woche?" — es wird get_blood_pressure mit period="week" aufrufen.

Datenbankschema

Alle 6 Tabellen (heartrate, bloodpressure, glucose, spo2, activity, sleep) verwenden dasselbe OpenTelemetry-artige Schema. Die Spalte metric_name unterscheidet Untermetriken innerhalb jeder Tabelle (z. B. sind systolic und diastolic separate Zeilen in bloodpressure). Siehe Design.md für das vollständige DDL und die Untermetrik-Zuordnung.

Erweiterung

Hinzufügen einer neuen Metrik:

1. Erstellen Sie sapphire_wellness/models/<metric>.py — Pydantic-Modell

2. Erstellen Sie sapphire_wellness/repositories/<metric>_repo.py — DB-Abfrage + Zuordnung

3. Erstellen Sie sapphire_wellness/tools/<metric>.py — @mcp.tool()-Definition

4. Registrieren Sie in server.py

Austauschen der Datenbank: Implementieren Sie eine neue Klasse, die die Methodensignaturen in repositories/base.py (HealthRepository) nachbildet, und übergeben Sie sie an die register()-Funktionen in server.py.

Hinzufügen von check_health_alerts: Dieses Tool ist für Phase 2 geplant. Es wird Messwerte außerhalb normaler Schwellenwerte kennzeichnen (z. B. BP >140/90, SpO2 <95 %) und strukturierte Warnungen mit Schweregraden zurückgeben.