Sapphire Health MCP Server

Ein Python-Model Context Protocol (MCP)-Serv, der Gesundheitsmetriken aus der Sapphire Health 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-Bereitungen (stdlib funktioniert nur, wenn der Agent eDen MP-Server als Kindprozess startet)

• Datenbank: PostgreSQL mit Metriktabellen im OpenTelemetry-Stil (time, metric_name, metric_value, `attributes JSONB“, ...)

• Framework: FastMCP mit Pydantic-v2-Antwortmodellen

Für das vollständige Architekur-Document siehe Design.md.

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

• Pyth Herm, ... C Preter her

Voraussetzungen

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

Prerequisites

• Python 3.11+

• PostgreSQL 14+ mitden angelegten 6 Wellnes-Mess-Metriktabellen

• [podman-kom](https://github.com/containers/pod… compose) oder Docker Compose (for containerisierte Bereitstellung)

Schnellstart

Lokal Entwickung

# 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

Containerisierung (pod-compose)

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

# Tear down
podman-compose down

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

Um Ihren Agent-Containner zu verbinden, setzen Sie:

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

Configuration

All settings read from environment variables (or .env file): "All settings are read from environment variables (or a .opt) file.

Tool-Referenz

Alle Tools teach these parameters:

Parameter | Type | Default | Description | | user_id | str | — | User whose data to query | | date | str | "today" | ISO-Datum YYYY-MM-DD oder "today" | | period | str | "day" | "day" (24 h), "week" (7 Tage), "month" (30 Tage) |

**All tools share these parameters. vor." table. re...

get_activity

Gibt Schritte, Kalorien, Distanz und aktive Minuten zurück. Die Gesamtsummen werden den Zeitraum summiert.

get_blood_pressure

Liefert systolische/diastolische Messwerte in mmHg. Jeder Messwert wird anhand der AHA-Kategorien klassifiziert:

• Normal — systolisch <120 und diastolisch <80

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

• Hoch Stufe 1 — systolisch 130–139 oder diastolisch 80–89

• Hoch Stufe 2 — systolisch ≥140 oder diastolisch ≥90

• Hypertensive Krise — systolisch >180 oder diastolisch >120

get_glucose

Liefert Glukose-Werte in mg/dL mit Mahlzeitigkeitsspring. Mahlzeit context (fasting, pre_meal, post_meal, bedtime, random) und Statistik inklusive Zeit im Zielbereich (Ziel: 70–180 mg/dL).

get_heart_rate

Liefert Herzfrequenz-Messwertphe in BPM (active and ruhend) mit Dischnitt, Min., Max. und durchschnittlichen Ruhepuls.

###get_sleep

Liefert die Schlafphasen-Aufhdiederung (Tie-Schlaf, Leich-Schlaf, REM, Wachphasen) in Minuten, die Gesamtée! unddie Schlaf-effizienz in %.

get_he2

Liefert SpO2–Messwerte in % mit Durschnitt, Min., Max. und der Anzahl der Meldereignèíse mit niederer Sättigung (unter 95 %).

get_health_summary

Ruft alle 6 Metriken-Repositorien gleichzeitig auf und gibt eine einzelne zusammengefasste Antworte zurück –– ideal für täiche Gesundheitsberichte.

Investigating Tools

Use the [MCP Inspector](https://github.com/modelntextent も)-tool to explore tool schema и test calls:

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

Connect to Claude Desktop

Add to your claude_desktop_config.json:

To connect Claude Desktop, add to your claude_desktop_config.json:

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

Then ask Claude: „Wie war mein Blutdruck diese Woche?" – und it wird get_blood_pressure mit period="week" aufrufen.

Database Schema

All 6 timestamps: heartrate, bloodpressure, glucose, s, activity, sleep — the exact same OpenTelemetry-style schema. The metric_name column distinguishes sub-metrics within each table (e.g. systolic anddiastol are separate rows in bloodpressure). For full DDL and sub-metric mapping see Design.md.

Extending

Adding a new metric:

1. Erzuellen Sie saphhire_wellness/models/<metric>.py – Pydantic-Modell

2. Erstellen Sie sapphire_wellness/repositories/<metric>_repo.py – DB query + mapping

3. Erstellen Sie sapphire_wellness/tools/<metric>.py – define @mcp.tool()

4. Registieren Sie in server.py

Swapping the database:

Implement a new class that imitates the method signatures in repositories/base.py and pass it to the register() functions in server.py.

Adding check_health_erts:

This tool is geplant for Phase 2. It marks values outside the normal threshold (e.g. BP >140/90, SpO2 <95%) and returns structured alerts with severity levels.