Sapphire Wellness MCP Server

AIアシスタントにSapphire Wellness Appの健康指標を公開する、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サーバーを子プロセスとして起動する場合のみ動作します）

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

• フレームワーク: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

血糖値(mg/dL)を食事コンテキスト(fasting、pre_meal、post_meal、bedtime、random)とともに返し、目標範囲70〜180 mg/dLの射程内時間を含む統計情報を提供します。

get_heart_rate

心拍数(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列は各テーブル内のサブメトリクスを区別します（例：bloodpressureテーブル内ではsystolicとdiastolicは別々の行として保存されます）。完全な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を追加する場合: このツールはPhase 2で計画されています。正常範囲外の値（例：血圧140/90超、SpO2 95％未満）を検出し、重大度レベル付きの構造化アラートを返すものです。