Sapphire User MCP Server

Un servidor Python Model Context Protocol (MCP) que expone datos de perfil de usuario de la Sapphire Wellness App a asistentes de IA, incluyendo alertas de salud, recomendaciones personalizadas y suscripciones a servicios de socios.

Herramientas expuestas

Related MCP server: Sapphire Wellness MCP Server

Arquitectura

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

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

• APIs ascendentes: Todas las herramientas llaman a APIs REST sobre HTTP — sin acceso directo a la base de datos

• Framework: FastMCP con modelos de respuesta Pydantic v2

Estructura del proyecto

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

Requisitos previos

• Python 3.11+

• Una API de perfil de usuario de Sapphire en ejecución (por defecto: http://localhost:8091)

• Una API de servicios de socios de Sapphire en ejecución (por defecto: http://localhost:8085)

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 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

Contenerizado (Docker)

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

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

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

Para conectar tu contenedor de agente, establece:

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

Configuración

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

Referencia de herramientas

Todas las herramientas aceptan un único parámetro user_email.

get_user_alerts

Obtiene alertas de salud para el usuario desde la API de perfil de usuario. Cada alerta incluye:

• severity — nivel de urgencia de la alerta (p. ej. critical, warning)

• category — categoría de métrica que activó la alerta

• alertMessage — descripción legible de la alerta

• metricName / metricType — la métrica específica que superó un umbral

get_user_recommendations

Devuelve recomendaciones personalizadas de servicios de socios clasificadas por puntuación de relevancia. Cada recomendación incluye:

• relevanceScore — clasificación entera de qué tan bien coincide el servicio con el perfil de salud del usuario

• partnerService — nombre del servicio, categoría, tipo y descripción

• generatedAt — marca de tiempo cuando se calculó la recomendación

get_user_subscriptions

Obtiene las suscripciones activas a servicios de socios del usuario y enriquece cada una con detalles completos del servicio desde la API de servicios de socios. Cada suscripción incluye:

• partnerServiceId — el identificador del servicio inscrito

• isActive — si la suscripción está actualmente activa

• associationContext — fecha de fin de contrato y otros metadatos contextuales

• service_details — especificación completa del servicio, precios, disponibilidad e información del contrato

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:8001/sse

Conexión con Claude Desktop

Añade a tu claude_desktop_config.json:

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

Luego pregunta a Claude: "¿Qué alertas de salud tiene sarah.chen@sapphirewellness.com?" y llamará a get_user_alerts con el correo electrónico proporcionado.

Extensión

Añadir una nueva herramienta:

1. Crea sapphire_user/models/<name>.py — modelo de respuesta Pydantic

2. Crea sapphire_user/tools/<name>.py — definición de @mcp.tool() que llama a la API correspondiente

3. Regístralo en server.py