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

• 전송: HTTP SSE — 다중 컨테이너 배포에 필요(stdio는 에이전트가 MCP 서버를 자식 프로세스로 생성할 때만 작동)

• 업스트림 API: 모든 도구는 HTTP를 통한 REST API를 호출합니다 — 직접적인 데이터베이스 액세스는 없음

• 프레임워크: Pydantic v2 응답 모델을 사용하는 FastMCP

프로젝트 구조

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에 등록