# VitalDB MCP Server - Advanced Edition

VitalDB 데이터를 자연어로 탐색하고 **고급 분석**을 수행할 수 있는 Model Context Protocol (MCP) 서버입니다.

## ✨ 주요 기능

### 🔍 1. 고급 데이터 필터링
- **통계 기반 필터링**: "평균 심박수가 100 이상인 케이스 찾기"
- **조건식 지원**: `>100`, `>=80`, `<60`, `50-100` 등
- **대규모 분석**: 최대 100개 이상의 케이스 동시 처리

### 📊 2. 일괄 분석
- **배치 처리**: 여러 케이스를 한 번에 분석
- **다중 트랙 분석**: 한 케이스의 여러 신호를 동시 분석
- **통계 추출**: 평균, 중앙값, 표준편차, 왜도, 첨도 등

### 🔗 3. 상관관계 분석
- **두 신호 간 상관계수** 계산
- **케이스별 상관관계** 및 전체 상관관계
- **산점도 시각화** (추세선 포함)

### 📈 4. 그룹 비교
- **두 그룹 통계 비교**
- **t-test 자동 수행**
- **p-value 계산** 및 유의성 판단

### 🎨 5. 고급 시각화
- **무제한 케이스 플롯**: 오버레이 또는 서브플롯
- **분포 시각화**: 히스토그램, 박스플롯, 바이올린 플롯
- **히트맵**: 시간대별 트랙 값 변화
- **상관관계 산점도**: 회귀선 포함

### 🔬 6. 이상치 탐지
- **Z-score 방법**: 표준편차 기반
- **IQR 방법**: 사분위수 기반
- **시각화**: 이상치 위치 자동 표시

### 📂 7. 데이터 내보내기
- **CSV 저장**: 분석 결과를 파일로 저장
- **다중 케이스/트랙** 지원

## 🚀 설치 방법

### 1. 의존성 설치

```bash
cd /Users/yeze-macbookair-2025/workspaces/vitaldb-mcp-server
./install.sh
```

### 2. Claude Desktop 설정

**설정 파일 위치**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vitaldb": {
      "command": "/Users/yeze-macbookair-2025/workspaces/vitaldb-mcp-server/venv/bin/python",
      "args": ["/Users/yeze-macbookair-2025/workspaces/vitaldb-mcp-server/server.py"]
    }
  }
}
```

### 3. Claude Desktop 재시작

설정 후 Claude Desktop을 완전히 종료하고 다시 시작하세요.

## 💡 실제 활용 예시

**"마취 중 평균 심박수가 100 이상이었던 환자들의 수술 중 체온 변화 특징은?"**

이런 복잡한 질문도 자연어로 가능합니다!

## 🛠️ 사용 가능한 도구

### 기본 도구
- `find_cases`: 트랙 기반 케이스 검색
- `get_case_info`: 케이스 정보 조회  
- `search_available_tracks`: 사용 가능한 트랙 목록

### 고급 분석
- `filter_cases_by_statistics`: 통계 조건 필터링
- `batch_analyze_cases`: 일괄 분석
- `analyze_correlation`: 상관관계 분석
- `compare_groups`: 그룹 비교
- `detect_anomalies`: 이상치 탐지
- `time_window_analysis`: 시간 구간 분석
- `export_to_csv`: CSV 내보내기

### 시각화
- `plot_multiple_cases`: 다중 케이스 플롯 (무제한)
- `plot_distribution`: 분포 시각화
- `plot_scatter_correlation`: 산점도 상관관계
- `plot_heatmap`: 시간대별 히트맵

## 📋 VitalDB 트랙 종류

### 생체 신호
- `ECG_II`, `ECG_V5`: 심전도
- `PLETH`: 맥파
- `RESP`: 호흡 파형

### 혈압
- `ART`: 동맥압
- `CVP`: 중심정맥압
- `PAP`: 폐동맥압
- `NIBP_SYS`, `NIBP_DIA`, `NIBP_MBP`: 비침습적 혈압

### 산소/가스
- `SpO2`: 산소포화도
- `EtCO2`: 호기말 이산화탄소
- `FiO2`: 흡입산소농도

### 마취/진정
- `BIS`: 뇌파지수
- `MAC`: 최소폐포농도

### 기타
- `HR`: 심박수
- `RR`: 호흡수
- `TEMP`: 체온

## 🔧 문제 해결

### 1. MCP 서버가 연결되지 않는 경우
- Claude Desktop을 완전히 종료하고 재시작
- 설정 파일의 경로가 정확한지 확인
- Python 경로가 올바른지 확인

### 2. VitalDB 다운로드 느린 경우
- 인터넷 연결 확인
- 샘플링 간격을 크게 설정 (예: interval=1.0)
- 작은 케이스 수로 시작

### 3. 패키지 오류
```bash
cd /Users/yeze-macbookair-2025/workspaces/vitaldb-mcp-server
source venv/bin/activate
pip install --upgrade -r requirements.txt
```

## 📚 프로젝트 구조

```
vitaldb-mcp-server/
├── server.py              # 메인 서버 (MCP 엔드포인트)
├── tools.py               # 도구 정의
├── handlers.py            # 분석 기능 핸들러
├── visualization.py       # 시각화 핸들러
├── utils.py               # 유틸리티 함수
├── requirements.txt       # Python 의존성
├── install.sh            # 설치 스크립트 (Mac/Linux)
├── install.bat           # 설치 스크립트 (Windows)
└── README.md            # 이 문서
```

## 🎓 학습 리소스

- [VitalDB 공식 문서](https://vitaldb.net/docs/)
- [VitalDB 데이터셋 설명](https://vitaldb.net/dataset/)
- [MCP 프로토콜](https://modelcontextprotocol.io)

## 📝 라이선스

MIT License

---

**제작**: VitalDB MCP Server Advanced Edition  
**버전**: 2.0.0  
**최종 업데이트**: 2025-10-07