Sapphire Wellness MCP Server

一个 Python Model Context Protocol (MCP) 服务器，向 AI 助手提供来自 Sapphire Wellness App 的健康指标。

暴露的指标

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

返回收缩压/舒张压读数（mmHg）。每个读数按 AHA 分类：

• 正常 — 收缩压 <120 且舒张压 <80

• 升高 — 收缩压 120–129 且舒张压 <80

• 1 级高血压 — 收缩压 130–139 或舒张压 80–89

• 2 级高血压 — 收缩压 ≥140 或舒张压 ≥90

• 高血压危象 — 收缩压 >180 或舒张压 >120

get_glucose

返回血糖读数（mg/dL），包含餐食背景（fasting、pre_meal、post_meal、bedtime、random）以及统计信息，包括目标范围内时间（目标：70–180 mg/dL）。

get_heart_rate

返回心率读数（BPM，活跃和静息），包含平均值、最小值、最大值和平均静息 BPM。

get_sleep

返回睡眠阶段细分（深睡、浅睡、快速眼动、清醒）的分钟数、总时长和睡眠效率百分比。

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）中的方法签名，并将其传递给 server.py 中的 register() 函数。

添加 check_health_alerts：

此工具计划在第二阶段实现。它将标记超出正常阈值的读数（例如血压 >140/90、SpO2 <95%），并返回带有严重程度级别的结构化警报。