Sapphire User MCP Server

Python-сервер на базе Model Context Protocol (MCP), который предоставляет AI-ассистентам данные профиля пользователя из приложения Sapphire Wellness App — включая оповещения о здоровье, персонализированные рекомендации и подписки на партнёрские сервисы.

Доступные инструменты

Related MCP server: sapphire-user-mcp

Архитектура

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

• Транспорт: HTTP SSE — требуется для многоконтейнерных развёртываний (stdio работает только когда агент запускает MCP-сервер как дочерний процесс)

• Внешние API: все инструменты вызывают REST API по HTTP — без прямого доступа к базе данных

• Фреймворк: FastMCP с моделями ответов Pydantic v2

Структура проекта

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

Предварительные требования

• Python 3.11+

• Запущенный Sapphire User Profile API (по умолчанию: http://localhost:8091)

• Запущенный Sapphire Partner Service API (по умолчанию: http://localhost:8085)

Быстрый старт

Локальная разработка

# 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

Контейнерное развёртывание (Docker)

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

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

MCP-сервер будет доступен по адресу http://localhost:10003/sse.

Чтобы подключить контейнер агента, задайте:

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

Конфигурация

Все настройки считываются из переменных окружения (или из файла .env):

Справка по инструментам

Все инструменты принимают единственный параметр user_email.

get_user_alerts

Возвращает оповещения о здоровье пользователя из User Profile API. Каждое оповещение включает:

• severity — уровень срочности оповещения (например, critical, warning)

• category — категория метрики, вызвавшая оповещение

• alertMessage — человекопонятное описание оповещения

• metricName / metricType — конкретная метрика, превысившая порог

get_user_recommendations

Возвращает персонализированные рекомендации партнёрских сервисов, ранжированные по оценке релевантности. Каждая рекомендация включает:

• relevanceScore — целочисленный рейтинг соответствия сервиса профилю здоровья пользователя

• partnerService — название, категория, тип и описание сервиса

• generatedAt — отметка времени, когда была рассчитана рекомендация

get_user_subscriptions

Возвращает активные подписки пользователя на пар тнеёрские сервисы и дополяет кажд찌? Hmm let's fix:

get_user_subscriptions

Возвращает активные подписки пользователя на партнёрские сервисы и дополняет каждую полными данными сервиса из Partner Service API. Каждая подписка включает:

• partnerServiceId — идентификатор подручённого сервиса

• isActive — активна ли подписка в данный момент

• associationContext — дата окончания контракта и другие контекстные метаданные

• service_details — полная спецификация сервиса, цены, доступность и правовая информация по контракту

Проверка инструментов

Используйте MCP Inspector для изучения схем инструментов и тестовых вызовов:

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

Connecting / use "Подключение к Claude Desktop"

Add in claude_desktop_config.json:

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

Then ask Claude: «Какие оповещения о здоровье есть у sarah.chen@sapphirewellness.com?» — и он вызовет get_user_alerts с указанным адресом электронной почты.

Extending

Добавление нового инструмента:

1. Создайте sapphire_user/models/<name>.py — Pydantic-модель ответа

2. Create sapphire_user/tools/<name>.py — @mcp.tool() definition calling the appropriate API

3. Register in server.py