Sapphire User MCP Server

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

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

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

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

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

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

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

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

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

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

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

Подключение к Claude Desktop

Добавьте в ваш claude_desktop_config.json:

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

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

Расширение

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

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

2. Создайте sapphire_user/tools/<name>.py — определение @mcp.tool(), вызывающее соответствующий API

3. Зарегистрируйте в server.py