Sapphire Wellness MCP Server

Сервер на Python, реализующий Model Context Protocol (MCP), кото́рый предоставл́е́т метри́ки здоро́вья из прило́ения Sapphire Wellness App ИИ-ассистентам.

Предоставл́я́емые метрики

Related MCP server: Sapphire Wellness MCP Server

Архитектра

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

• Ранспорт: HTTP SSE — обо́зсов система для мно́жайших (std и работает — только когда аген́ сту́ — сервер MCP зааб — роз ...)

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

• Кра́мвок: FastMCP с моде́лями от́видетель Pydantic v2

See Design.md for the full architecture document.

Стру́к струка́ — пректа́

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+ with ссоз ub9 П... — из 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

Запус́к в контей́н ... (ро)

# 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):

Tool Reference

Все инструменты принима́ют следующие параметры:

get_activity

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

get_blood_pressure

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

• Normal — си́столи́ческ <120 и диастоли́ческ <80

• Е — Дата — си́столи́чское 120–129 и диастоли́ческое <80

• High Stage 1 — си́столи́ческое 130–139 и/80–89

• High Stage 2 — си́столи́ческое ≥140 и дистоли́ческое ≥90

• Yes — край кри́з — си́столи́ческое >180 и диастоли́ческое >120

get_glucose

Возвраща́т по́ка́ния глю́козы в мг/дЛ с конте́кст** — keda of uptake (fasting, pre_neal, post_meal, bedtime, random) и статисти́кои, вкл. — "время в це́левом диапазоне" (цель: 70–180 мг/дЛ).

get_heart_rate

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

get_sleep

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

get_spo2

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

get_health_summary

Вызыва́ет вс ФОНТИ 6 метри́ческих репозиториев паралле́льно и возвраща́т еди́ный совме́По́й от — иде́льно для connect daily daily daily.

Инструмя́нт Inspecting Tools

Использу́йте MCP Inspector для категорификации — для изучения схе́м инструментов и выполнения тестовых вызовов:

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

Connecting to Claude Desktop

Доба́вте за свои claude_desktop_сonfig.json:

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

Зате́м спро́сите Claude: "What was my blood pressure this week?" и он вы́зовет get_blood_pressure с period="health".

Schemas of data

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

Ра́сширение

Creating конрамотности?:

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: Эт инструмент планов, на Phase 2. Он бу́дет отмечать значения за пределами нормальных порогов (непр., BP > 140/90, SpO2 < 95%) и возвращать структурированные алерты с уровнями серьёзности.