Sapphire Wellness MCP Server

健康メトリクスをSapphire WellnessアプリからAIアシスタントに公開するPython製のModel Context Protocol (MCP)サーバーです。

公開されるメトリクス

Related MCP server: Sapphire Wellness MCP Server

アーキテクチャ

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

• トランスポート: HTTP SSE — マルチコンテナデプロイメントに必須(stdioはエージェントがMCPサーバーを子プロセスとして起動する場合にのみ機能します)

• データベース: OpenTelemetryスタイルのメトリクステーブル(time、metric_name、metric_value、attributes JSONBなど)を備えたPostgreSQL

• フレームワーク: Pydantic v2レスポンスモデルを備えたFastMCP

完全なアーキテクチャドキュメントは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以上

• 6つのウェルネスメトリクステーブルが作成されたPostgreSQL 14以上

• 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

食事コンテキスト(fasting、pre_meal、post_meal、bedtime、random)付きのmg/dL単位の血糖値測定値と、目標範囲内時間(目標: 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を作成 — DBクエリ+マッピング

3. sapphire_wellness/tools/<metric>.pyを作成 — @mcp.tool()定義

4. server.pyに登録

データベースの交換: repositories/base.py(HealthRepository)のメソッドシグネチャをミラーリングする新しいクラスを実装し、server.pyのregister()関数に渡します。

check_health_alertsの追加: このツールはフェーズ2で計画されています。正常範囲外の測定値(例: 血圧>140/90、SpO2<95%)にフラグを立て、重大度レベル付きの構造化アラートを返します。