# 예약 플랫폼 통합 관리 MCP
여러 예약 플랫폼(네이버, 에어비앤비, 스페이스클라우드, 야놀자, 카카오)의 예약을 한 곳에서 통합 관리하는 MCP 서버입니다.
## 주요 기능
### 📊 예약 조회
- 오늘/특정 날짜 예약 현황 조회
- 플랫폼별 예약 조회
- 예약 검색
### ⚠️ 중복 예약 방지
- 중복 예약 자동 감지
- 예약 가능 시간대 조회
### 💰 매출/정산 관리
- 일/주/월 매출 요약
- 플랫폼별 매출 분석
- 플랫폼 수수료 계산
### 👥 고객 관리
- 블랙리스트 관리
- 노쇼 고객 추적
- 고객 예약 이력
### 📝 메시지 생성
- 예약 안내 메시지 자동 생성
## 지원 플랫폼
- 네이버 예약
- 에어비앤비
- 스페이스클라우드
- 야놀자
- 카카오 예약
## 기술 스택
- Python 3.12+
- FastMCP
- iCalendar (ics) 파싱
## 설치 방법
```bash
# 가상환경 생성
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 의존성 설치
pip install -r requirements.txt
```
## 사용 방법
### 1. 테스트 데이터 생성
```bash
# 가상환경 활성화
source venv/bin/activate
# 샘플 데이터 생성
python test_data.py
```
### 2. MCP 서버 테스트
```bash
# MCP 서버 테스트 실행
python test_mcp.py
```
### 3. Claude Desktop에서 사용
Claude Desktop 설정 파일(`claude_desktop_config.json`)을 Claude Desktop의 설정 디렉토리에 복사:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
설정 예시:
```json
{
"mcpServers": {
"reservation-platform": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/PlayMCP",
"env": {
"PATH": "/path/to/PlayMCP/venv/bin:${PATH}"
}
}
}
}
```
### 4. 사용 가능한 Tools
#### 📊 예약 조회
- `get_today_reservations` - 오늘 예약 현황 조회
- `get_reservations_by_date` - 특정 날짜 예약 조회
- `get_reservations_by_platform` - 플랫폼별 예약 조회
- `get_week_reservations` - 이번 주 예약 조회
#### ⚠️ 중복 예약 방지
- `check_duplicate_reservations` - 중복 예약 감지
- `check_time_slot` - 특정 시간대 예약 가능 여부 확인
#### 💰 매출/정산
- `get_revenue_summary` - 매출 요약 (일/주/월)
- `calculate_platform_fees` - 플랫폼 수수료 계산
#### 👥 고객 관리
- `get_blacklist` - 블랙리스트 조회
- `add_to_blacklist` - 블랙리스트 추가
- `get_noshow_customers` - 노쇼 고객 조회
#### 📝 기타
- `generate_reminder_message` - 예약 안내 메시지 생성
- `sync_platform_ical` - iCal URL에서 예약 동기화
## 프로젝트 구조
```
PlayMCP/
├── src/
│ ├── server.py # MCP 서버 메인
│ ├── models.py # 데이터 모델
│ ├── storage.py # 데이터 저장소
│ ├── ical_parser.py # iCal 파싱
│ └── tools/ # MCP Tools
├── data/ # 로컬 데이터 저장
├── requirements.txt # Python 의존성
├── test_data.py # 테스트 데이터 생성
└── test_mcp.py # MCP 서버 테스트
```
## 개발 로드맵
- [x] 프로젝트 초기 설정
- [x] 데이터 모델 및 저장소
- [x] iCal 파싱 기능
- [x] 예약 조회 Tools (4개)
- [x] 중복 체크 Tools (2개)
- [x] 매출/정산 Tools (2개)
- [x] 고객 관리 Tools (3개)
- [x] 메시지 생성 & 동기화 Tools (2개)
- [x] 로컬 테스트 완료
- [x] **데이터 관리 개선 (인메모리 캐시)**
- [x] **Remote HTTP 서버 전환**
- [x] **Docker 설정 완료**
- [ ] 클라우드 배포 (Google Cloud Run/Railway/Render)
- [ ] PlayMCP 등록
## 로컬 실행
### STDIO 모드 (Claude Desktop/CLI)
```bash
python3 -m src.server
```
### HTTP 모드 (Remote MCP 서버)
```bash
# HTTP transport로 실행
TRANSPORT=http PORT=8000 python3 -m src.server
```
서버는 `http://localhost:8000/mcp`에서 접근 가능합니다.
## Docker 배포
### Docker로 실행
```bash
# 이미지 빌드
docker build -t reservation-mcp-server .
# 컨테이너 실행
docker run -p 8000:8000 -e TRANSPORT=http reservation-mcp-server
```
### Docker Compose로 실행
```bash
docker-compose up -d
```
## 클라우드 배포
자세한 배포 방법은 [DEPLOYMENT.md](DEPLOYMENT.md)를 참고하세요.
- **Google Cloud Run**: 완전 관리형 컨테이너 플랫폼
- **Railway**: 간편한 Git 기반 배포
- **Render**: 무료 티어 지원
## PlayMCP 등록
1. https://playmcp.kakao.com/console 접속
2. 배포된 서버 URL 등록
3. Tools 정보 입력
4. 심사 제출 → 전체 공개
5. 공모전 응모
자세한 내용은 [DEPLOYMENT.md](DEPLOYMENT.md)의 "PlayMCP 등록" 섹션 참고
## 성능 개선
### 인메모리 캐시
- 모든 데이터를 메모리에 로드하여 읽기 성능 대폭 향상
- Thread Lock으로 동시성 문제 해결
- 파일 I/O 최소화
## 라이선스
MIT License
