Sapphire User MCP Server

Sapphire Wellness App のユーザープロファイルデータを AI アシスタントに公開する Python Model Context Protocol (MCP) サーバーです。健康アラート、パーソナライズされたレコメンデーション、パートナーサービスサブスクリプションなどが含まれます。

公開ツール

Related MCP server: Sapphire Wellness MCP Server

アーキテクチャ

Agent Container
      │  HTTP SSE
      ▼
sapphire-user-mcp:10003
      │
      ├──httpx──▶  User Profile API:8091
      │
      └──httpx──▶  Partner Service API:8085

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

• 上流 API: すべてのツールは HTTP 経由で REST API を呼び出します — データベースへの直接アクセスはありません

• フレームワーク: FastMCP と Pydantic v2 レスポンスモデル

プロジェクト構造

SAPPHIRE-USER-MCP/
├── sapphire_user/
│   ├── server.py           # FastMCP app + SSE entry point
│   ├── config.py           # Settings (API URLs, HOST, PORT via env)
│   ├── models/             # Pydantic response models
│   │   ├── alerts.py
│   │   ├── recommendations.py
│   │   ├── partner_service.py
│   │   └── subscriptions.py
│   └── tools/              # MCP tool definitions
│       ├── alerts.py
│       ├── recommendations.py
│       └── subscriptions.py
├── pyproject.toml
├── Dockerfile
└── .env.example

前提条件

• Python 3.11+

• 実行中の Sapphire User Profile API（デフォルト: http://localhost:8091）

• 実行中の Sapphire Partner Service API（デフォルト: http://localhost:8085）

クイックスタート

ローカル開発

# 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 USER_PROFILE_API_BASE_URL and PARTNER_SERVICE_API_BASE_URL

# 4. Run the server
python -m sapphire_user.server
# Server starts at http://0.0.0.0:8001

コンテナ化（Docker）

# Build the image
docker build -t sapphire-user-mcp .

# Run the container
docker run -p 10003:10003 --env-file .env sapphire-user-mcp

MCP サーバーは http://localhost:10003/sse で利用可能になります。

エージェントコンテナを接続するには、以下を設定します：

MCP_SERVER_URL=http://sapphire-user-mcp:10003/sse

設定

すべての設定は環境変数（または .env ファイル）から読み取られます：

ツールリファレンス

すべてのツールは単一の user_email パラメータを受け取ります。

get_user_alerts

User Profile API からユーザーの健康アラートを取得します。各アラートには以下が含まれます：

• severity — アラートの緊急度レベル（例: critical, warning）

• category — アラートをトリガーしたメトリクスカテゴリ

• alertMessage — アラートの人間が読める説明

• metricName / metricType — しきい値を超えた特定のメトリクス

get_user_recommendations

関連性スコアでランク付けされたパーソナライズされたパートナーサービスレコメンデーションを返します。各レコメンデーションには以下が含まれます：

• relevanceScore — サービスがユーザーの健康プロファイルにどの程度一致するかを示す整数ランキング

• partnerService — サービス名、カテゴリ、タイプ、説明

• generatedAt — レコメンデーションが計算されたタイムスタンプ

get_user_subscriptions

ユーザーのアクティブなパートナーサービスサブスクリプションを取得し、Partner Service API から完全なサービス詳細を各サブスクリプションに追加します。各サブスクリプションには以下が含まれます：

• partnerServiceId — 登録されたサービス識別子

• isActive — サブスクリプションが現在アクティブかどうか

• associationContext — 契約終了日およびその他のコンテキストメタデータ

• service_details — 完全なサービス仕様、価格、可用性、契約情報

ツールの検査

MCP Inspector を使用してツールスキーマを調べ、テスト呼び出しを行います：

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

Claude Desktop への接続

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "sapphire-user": {
      "url": "http://localhost:8001/sse"
    }
  }
}

次に Claude に: "sarah.chen@sapphirewellness.com にはどのような健康アラートがありますか？" と尋ねると、提供されたメールアドレスで get_user_alerts が呼び出されます。

拡張

新しいツールの追加：

1. sapphire_user/models/<name>.py を作成 — Pydantic レスポンスモデル

2. sapphire_user/tools/<name>.py を作成 — 適切な API を呼び出す @mcp.tool() 定義

3. server.py に登録