Sapphire Wellness MCP Server

一个 Python Model Context Protocol (MCP) 服务器，用于向 AI 助手暴露 Sapphire Wellness App 中的健康指标。

提供的指标

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 响应模型

完整 Check 过的架构说明请见 Design.md。

Related MCP server: Sapphire Wellness MCP Server

项目结构

Structure...

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），以及统计信息，并包括目标范围内时间（目标：QG70–180 mg/dL）。

get_heart_rate

返回单位为 BPM 的心率读数（活动与静息），并给出平均、最小值、最大值和平均静息心率。

get_sleep

返回睡眠睡眠阶段分布（深睡、浅睡、REM、清醒），以分钟为单位，另外附总时长和睡眠效率百分比。

get_spo2

返回 % 表示的血氧（SpO2 读数）平均、最低、最高并统计低血氧（<95%）事件次数。

get_health_summary

并发调用所有 6 个指标仓库，并返回对应一个组合后的统一响应——非常适合每日健康摘要。

检查工具

使用 MCP Inspector 查看工具 schemas 并执行测试调用：

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"。

数据库 Schema

6 张表（heartrate、bloodpressure、glucose、spos2、activity、sleep）共享相同的 OpenTelemetry 风格。DataBase 表中 metric_name 字段用于区分子指标（例如在 bloodpressure 中 systolic 和 diastolic 各占一行）。完整的 DDL 及子指标映射请见 Design.md。

扩展

新增一个指标：

1. 创建 sapphire_wellness/models/<metric>.py —— Pydantic 模型

2. 创建 sapphire_wellness/repositor/ies/<metric>_po>.py —— 数据库查询与映射

3. 创建 sapphire_wellness/tools/<metric>.py —— @mcp.tool() 定义

4. 在 server.py 中注册

切换数据库： 实现一个与 repositories/base.py 中 HealthRepository 方法签名一致的新类，并将其传给 server.py 中的 register() 函数。

添加 check_health_alerts： 该工具计划在第二阶段实现。它会标记超出阈值（如血压 >140/血氧 <95%）的读数，并返回一个包含严重级别分类的结构化告警。