Sapphire Wellness MCP Server

Un servidor Python del Model Context Protocol (MCP) que expone métricas de salud de la aplicación Sapphire Wellness a asistentes de IA.

Métricas expuestas

Related MCP server: Sapphire Wellness MCP Server

Arquitectura

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

• Transporte: HTTP SSE — necesario para despliegues multi-contenedor (stdio solo funciona cuando el agente lanza el servidor MCP como proceso hijo)

• Base de datos: PostgreSQL con tablas de métricas estilo OpenTelemetry (time, metric_name, metric_value, attributes JSONB, ...)

• Framework: FastMCP con modelos de respuesta Pydantic v2

Consulta Design.md para el documento completo de arquitectura.

Estructura del proyecto

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

Requisitos previos

• Python 3.11+

• PostgreSQL 14+ con las 6 tablas de métricas de bienestar creadas

• podman-compose o Docker Compose (para despliegue en contenedores)

Inicio rápido

Desarrollo local

# 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

En contenedores (podman-compose)

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

# Tear down
podman-compose down

El servidor MCP estará disponible en http://localhost:10002/sse.

Para conectar tu contenedor de agente, configura:

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

Configuración

Todos los ajustes se leen de variables de entorno (o de un archivo .env):

Referencia de herramientas

Todas las herramientas comparten estos parámetros:

get_activity

Devuelve pasos, calorías, distancia y minutos activos. Los totales se suman a lo largo del período.

get_blood_pressure

Devuelve lecturas sistólicas/diastólicas en mmHg. Cada lectura se clasifica según las categorías AHA:

• Normal — sistólica <120 y diastólica <80

• Elevada — sistólica 120–129 y diastólica <80

• Hipertensión etapa 1 — sistólica 130–139 o diastólica 80–89

• Hipertensión etapa 2 — sistólica ≥140 o diastólica ≥90

• Crisis hipertensiva — sistólica >180 o diastólica >120

get_glucose

Devuelve lecturas de glucosa en mg/dL con contexto de comida (fasting, pre_meal, post_meal, bedtime, random) y estadísticas que incluyen tiempo en rango (objetivo: 70–180 mg/dL).

get_heart_rate

Devuelve lecturas de frecuencia cardíaca en BPM (activa y en reposo) con media, mín, máx y BPM medio en reposo.

get_sleep

Devuelve el desglose de fases del sueño (profundo, ligero, REM, despierto) en minutos, la duración total y el porcentaje de eficiencia del sueño.

get_spo2

Devuelve lecturas de SpO2 en %, con media, mín, máx y un recuento de eventos de baja saturación (por debajo del 95%).

get_health_summary

Llama a los 6 repositorios de métricas de forma concurrente y devuelve una única respuesta combinada: ideal para informes diarios de salud.

Inspección de herramientas

Usa el MCP Inspector para explorar los esquemas de las herramientas y hacer llamadas de prueba:

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

Conexión con Claude Desktop

Añade a tu claude_desktop_config.json:

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

Después pregunta a Claude: «¿Cuál fue mi presión arterial esta semana?» y llamará a get_blood_pressure con period="week".

Esquema de base de datos

Las 6 tablas (heartrate, bloodpressure, glucose, spo2, activity, sleep) comparten el mismo esquema estilo OpenTelemetry. La columna metric_name distingue las sub-métricas dentro de cada tabla (p. ej., systolic y diastolic son filas separadas en bloodpressure). Consulta Design.md para el DDL completo y el mapeo de sub-métricas.

Ampliación

Añadir una nueva métrica:

1. Crea sapphire_wellness/models/<metric>.py — modelo Pydantic

2. Crea sapphire_wellness/repositories/<metric>_repo.py — consulta de BD + mapeo

3. Crea sapphire_wellness/tools/<metric>.py — definición de @mcp.tool()

4. Regístralo en server.py

Cambiar la base de datos: Implementa una nueva clase que replique las firmas de los métodos en repositories/base.py (HealthRepository) y pásala a las funciones register() en server.py.

Añadir check_health_alerts: Esta herramienta está prevista para la Fase 2. Marcará las lecturas fuera de los umbrales normales (p. ej., PA >140/90, SpO2 <95%) y devolverá alertas estructuradas con niveles de gravedad.