Sapphire Wellness MCP Server

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

Доступные показатели

Related MCP server: Sapphire Wellness MCP Server

Архитектура

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

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

• База данных: PostgreSQL с таблицами показателей в стиле OpenTelemetry (time, metric_name, metric_value, attributes JSONB, ...)

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

Полный документ по архитектуре см. в Design.md.

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

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

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

• Python 3.11+

• PostgreSQL 14+ с созданными 6 таблицами показателей здоровья

• podman-compose или Docker Compose (для контейнерного развёртывания)

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

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

# 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

Контейнерное развёртывание (podman-compose)

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

# Tear down
podman-compose down

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

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

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

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

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

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

Все инструменты используют общие параметры:

get_activity

Возвращает шаги, калории, дистанцию и активные минуты. Итоги суммируются за период.

get_blood_pressure

Возвращает показания систолического/диастолического давления в мм рт. ст. Каждое показание классифицируется по категориям AHA:

• Нормальное — систолическое <120 и диастолическое <80

• Повышенное — систолическое 120–129 и диастолическое <80

• Гипертония 1-й стадии — систолическое 130–139 или диастолическое 80–89

• Гипертония 2-й стадии — систолическое ≥140 или диастолическое ≥90

• Гипертонический криз — систолическое >180 или диастолическое >120

get_glucose

Возвращает показания глюкозы в мг/дл с контекстом приёма пищи (fasting, pre_meal, post_meal, bedtime, random) и статистикой, включая время в диапазоне (целевой диапазон: 70–180 мг/дл).

get_heart_rate

Возвращает показания частоты сердечных сокращений в BPM (активные и в покое) со средним, мин, макс и средним значением ЧСС в покое.

get_sleep

Возвращает разбивку по стадиям сна (глубокий, лёгкий, REM, бодрствование) в минутах, общую длительность и процент эффективности сна.

get_spo2

Возвращает показания SpO2 в %, со средним, мин, макс и количеством событий низкого насыщения (ниже 95%).

get_health_summary

Вызывает все 6 репозиториев показателей конкурентно и возвращает единый комбинированный ответ — идеально для ежедневных сводок о здоровье.

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

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

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

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

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

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

Затем спросите Claude: «Каким было моё артериальное давление на этой неделе?» — и он вызовет get_blood_pressure с period="week".

Схема базы данных

Все 6 таблиц (heartrate, bloodpressure, glucose, spo2, activity, sleep) используют одинаковую схему в стиле OpenTelemetry. Колонка metric_name различает под-показатели внутри каждой таблицы (например, systolic и diastolic — отдельные строки в bloodpressure). Полный DDL и сопоставление под-показателей см. в Design.md.

Расширение

Добавление нового показателя:

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

2. Создайте sapphire_wellness/repositories/<metric>_repo.py — запрос к БД + сопоставление

3. Создайте sapphire_wellness/tools/<metric>.py — определение @mcp.tool()

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

Замена базы данных: Реализуйте новый класс, повторяющий сигнатуры методов в repositories/base.py (HealthRepository), и передайте его в функции register() в server.py.

Добавление check_health_alerts: Этот инструмент запланирован на Фазу 2. Он будет отмечать показания, выходящие за пределы нормальных порогов (например, АД >140/90, SpO2 <95%), и возвращать структурированные предупреждения с уровнями серьёзности.