Sapphire Wellness MCP 서버

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 단위의 심박수 측정값(활동 중 및 안정 시)을 반환합니다.

get_sleep

수면 단계별 시간(깊은, 얕은, REM, 각성)을 분 단위로, 총 수면 시간, 수면 효율 백분율을 반환합니다.

get_spo2

평균, 최소, 최대, 저산소 포화도 이벤트 수(95% 미만)를 포함한 % 단위의 SpO2 측정값을 반환합니다.

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에게 *"이번 주 내 혈압은 어땠어?"*라고 물어보면 period="week"로 get_blood_pressure를 호출합니다.

데이터베이스 스키마

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 추가: 이 도구는 Phase 2에서 계획되어 있습니다. 정상 임계값을 벗어난 측정값(예: 혈압 >140/90, SpO2 <95%)을 플래그로 표시하고 심각도 수준이 포함된 구조화된 알림을 반환합니다.