# Sapphire User MCP Server

A Python [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes user profile data from the Sapphire Wellness App to AI assistants — including health alerts, personalised recommendations, and partner service subscriptions.

## Tools Exposed

| Tool | Description |
|------|-------------|
| `get_user_alerts` | Health alerts triggered by metric thresholds (abnormal vitals, low activity, etc.) |
| `get_user_recommendations` | Personalised partner service recommendations ranked by relevance score |
| `get_user_subscriptions` | Active partner service subscriptions with full service details |

## Architecture

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

- **Transport**: HTTP SSE — required for multi-container deployments (stdio only works when the agent spawns the MCP server as a child process)
- **Upstream APIs**: All tools call REST APIs over HTTP — no direct database access
- **Framework**: [FastMCP](https://github.com/modelcontextprotocol/python-sdk) with Pydantic v2 response models

## Project Structure

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

## Prerequisites

- Python 3.11+
- A running Sapphire User Profile API (default: `http://localhost:8091`)
- A running Sapphire Partner Service API (default: `http://localhost:8085`)

## Quick Start

### Local Development

```bash
# 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
```

### Containerised (Docker)

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

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

The MCP server will be available at `http://localhost:10003/sse`.

To connect your agent container, set:
```
MCP_SERVER_URL=http://sapphire-user-mcp:10003/sse
```

## Configuration

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

| Variable | Default | Description |
|----------|---------|-------------|
| `HOST` | `0.0.0.0` | MCP server bind address |
| `PORT` | `8001` | MCP server bind port |
| `USER_PROFILE_API_BASE_URL` | `http://localhost:8091` | Sapphire User Profile API base URL |
| `PARTNER_SERVICE_API_BASE_URL` | `http://localhost:8085` | Sapphire Partner Service API base URL |

## Tool Reference

All tools accept a single `user_email` parameter.

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_email` | `str` | The user's email address (e.g. `sarah.chen@sapphirewellness.com`) |

### `get_user_alerts`

Fetches health alerts for the user from the User Profile API. Each alert includes:
- **severity** — alert urgency level (e.g. `critical`, `warning`)
- **category** — metric category that triggered the alert
- **alertMessage** — human-readable description of the alert
- **metricName / metricType** — the specific metric that breached a threshold

### `get_user_recommendations`

Returns personalised partner service recommendations ranked by relevance score. Each recommendation includes:
- **relevanceScore** — integer ranking of how well the service matches the user's health profile
- **partnerService** — service name, category, type, and description
- **generatedAt** — timestamp when the recommendation was computed

### `get_user_subscriptions`

Fetches the user's active partner service subscriptions and enriches each with full service details from the Partner Service API. Each subscription includes:
- **partnerServiceId** — the enrolled service identifier
- **isActive** — whether the subscription is currently active
- **associationContext** — contract end date and other contextual metadata
- **service_details** — full service spec, pricing, availability, and contract information

## Inspecting Tools

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to explore tool schemas and make test calls:

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

## Connecting to Claude Desktop

Add to your `claude_desktop_config.json`:

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

Then ask Claude: *"What health alerts does sarah.chen@sapphirewellness.com have?"* and it will call `get_user_alerts` with the provided email.

## Extending

**Adding a new tool:**
1. Create `sapphire_user/models/<name>.py` — Pydantic response model
2. Create `sapphire_user/tools/<name>.py` — `@mcp.tool()` definition calling the appropriate API
3. Register in `server.py`