# 배포 가이드
예약 플랫폼 통합 MCP 서버를 원격(Remote) 서버로 배포하는 방법을 설명합니다.
## 목차
- [로컬 테스트](#로컬-테스트)
- [Docker 배포](#docker-배포)
- [클라우드 배포](#클라우드-배포)
- [Google Cloud Run](#google-cloud-run)
- [Railway](#railway)
- [Render](#render)
- [PlayMCP 등록](#playmcp-등록)
---
## 로컬 테스트
### 1. STDIO 모드 (로컬 개발)
```bash
# 기본 모드 (Claude Desktop/CLI용)
python3 -m src.server
```
### 2. HTTP 모드 (Remote MCP 서버)
```bash
# HTTP transport로 실행
TRANSPORT=http PORT=8000 python3 -m src.server
```
서버는 `http://localhost:8000/mcp`에서 접근 가능합니다.
### 3. SSE 모드 (레거시)
```bash
# SSE transport로 실행 (권장하지 않음)
TRANSPORT=sse PORT=8000 python3 -m src.server
```
---
## Docker 배포
### 1. Docker 이미지 빌드
```bash
docker build -t reservation-mcp-server .
```
### 2. Docker 컨테이너 실행
```bash
docker run -p 8000:8000 \
-e TRANSPORT=http \
-e PORT=8000 \
reservation-mcp-server
```
### 3. Docker Compose 사용
```bash
# 서비스 시작
docker-compose up -d
# 로그 확인
docker-compose logs -f
# 서비스 중지
docker-compose down
```
---
## 클라우드 배포
### Google Cloud Run
#### 사전 요구사항
- Google Cloud 계정
- gcloud CLI 설치 및 로그인
#### 배포 방법
```bash
# 1. 프로젝트 ID 설정
export PROJECT_ID="your-project-id"
gcloud config set project $PROJECT_ID
# 2. Cloud Build API 활성화
gcloud services enable cloudbuild.googleapis.com run.googleapis.com
# 3. 배포
gcloud run deploy reservation-mcp-server \
--source . \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars TRANSPORT=http \
--port 8000
```
#### 인증 추가 (프로덕션 환경)
```bash
# 인증 필요한 서비스로 배포
gcloud run deploy reservation-mcp-server \
--source . \
--platform managed \
--region us-central1 \
--no-allow-unauthenticated \
--set-env-vars TRANSPORT=http \
--port 8000
```
---
### Railway
#### 사전 요구사항
- Railway 계정: https://railway.app
#### 배포 방법
1. **Railway CLI 설치**
```bash
npm install -g @railway/cli
```
2. **로그인**
```bash
railway login
```
3. **프로젝트 초기화**
```bash
railway init
```
4. **배포**
```bash
railway up
```
5. **환경 변수 설정**
- Railway 대시보드에서 설정
- `TRANSPORT=http`
- `PORT=8000` (Railway가 자동으로 설정하는 경우 생략 가능)
6. **도메인 할당**
- Railway 대시보드에서 자동으로 생성된 URL 확인
- 또는 커스텀 도메인 설정
---
### Render
#### 사전 요구사항
- Render 계정: https://render.com
#### 배포 방법
1. **Render 대시보드 접속**
- https://dashboard.render.com
2. **New Web Service 생성**
- "New +" → "Web Service" 클릭
- GitHub 리포지토리 연결
3. **서비스 설정**
- **Name**: `reservation-mcp-server`
- **Environment**: `Docker`
- **Region**: 가까운 지역 선택
- **Branch**: `main` (또는 배포할 브랜치)
4. **환경 변수 설정**
```
TRANSPORT=http
PORT=8000
```
5. **배포**
- "Create Web Service" 클릭
- 자동으로 빌드 및 배포 진행
6. **URL 확인**
- 배포 완료 후 생성된 URL 확인
- 예: `https://reservation-mcp-server.onrender.com`
#### render.yaml 사용 (선택사항)
프로젝트 루트에 `render.yaml` 파일 생성:
```yaml
services:
- type: web
name: reservation-mcp-server
env: docker
region: oregon
plan: free
envVars:
- key: TRANSPORT
value: http
- key: PORT
value: 8000
healthCheckPath: /
```
---
## 환경 변수 설정
모든 배포 플랫폼에서 다음 환경 변수를 설정하세요:
| 변수명 | 값 | 설명 |
|--------|-----|------|
| `TRANSPORT` | `http` | Transport 모드 (http/sse/stdio) |
| `PORT` | `8000` | 서버 포트 (플랫폼에 따라 자동 설정될 수 있음) |
---
## 배포 후 확인
### 헬스 체크
```bash
curl https://your-server-url.com/
```
### MCP 엔드포인트 확인
```bash
curl -X POST https://your-server-url.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```
---
## PlayMCP 등록
### 1. PlayMCP 콘솔 접속
https://playmcp.kakao.com/console
### 2. MCP 서버 등록
- **서버 이름**: 예약 플랫폼 통합 관리
- **서버 설명**: 여러 예약 플랫폼(네이버, 에어비앤비, 스페이스클라우드, 야놀자, 카카오)의 예약을 한 곳에서 통합 관리
- **서버 URL**: 배포한 서버의 URL (예: `https://your-server.onrender.com/mcp`)
- **카테고리**: 생산성 / 비즈니스 도구
### 3. 제공하는 Tools
아래 Tools를 문서화하여 등록:
#### 📊 예약 조회 (4개)
- `get_today_reservations` - 오늘 예약 현황
- `get_reservations_by_date` - 특정 날짜 예약 조회
- `get_reservations_by_platform` - 플랫폼별 예약 조회
- `get_week_reservations` - 이번 주 예약 조회
#### ⚠️ 중복 예약 방지 (2개)
- `check_duplicate_reservations` - 중복 예약 감지
- `check_time_slot` - 특정 시간대 예약 가능 여부
#### 💰 매출/정산 (2개)
- `get_revenue_summary` - 매출 요약 (일/주/월)
- `calculate_platform_fees` - 플랫폼 수수료 계산
#### 👥 고객 관리 (3개)
- `get_blacklist` - 블랙리스트 조회
- `add_to_blacklist` - 블랙리스트 추가
- `get_noshow_customers` - 노쇼 고객 조회
#### 📝 기타 (2개)
- `generate_reminder_message` - 예약 안내 메시지 생성
- `sync_platform_ical` - iCal URL에서 예약 동기화
### 4. 심사 제출
- 모든 정보 입력 완료 후 심사 제출
- 심사 통과 후 "전체 공개"로 전환
- 공모전 응모 페이지에서 응모
---
## 트러블슈팅
### Docker 빌드 실패
```bash
# 캐시 없이 다시 빌드
docker build --no-cache -t reservation-mcp-server .
```
### 포트 충돌
```bash
# 다른 포트로 실행
docker run -p 8080:8000 \
-e TRANSPORT=http \
-e PORT=8000 \
reservation-mcp-server
```
### 데이터 영속성
Docker 볼륨을 사용하여 데이터 보존:
```bash
docker run -p 8000:8000 \
-v $(pwd)/data:/app/data \
-e TRANSPORT=http \
reservation-mcp-server
```
---
## 보안 고려사항
### 1. 인증 추가
프로덕션 환경에서는 반드시 인증을 추가하세요:
- API 키 인증
- OAuth 2.0
- JWT 토큰
### 2. CORS 설정
브라우저에서 접근하는 경우 CORS 설정 필요
### 3. Rate Limiting
악용 방지를 위한 요청 제한 설정
---
## 다음 단계
1. ✅ 로컬 HTTP 서버 테스트 완료
2. ✅ Docker 이미지 빌드 및 테스트
3. 🔄 클라우드 배포 (Google Cloud Run / Railway / Render 중 선택)
4. 🔄 PlayMCP 콘솔 등록
5. 🔄 심사 제출 및 전체 공개
6. 🔄 공모전 응모
---
## 참고 자료
- FastMCP 공식 문서: https://gofastmcp.com
- MCP 프로토콜 스펙: https://modelcontextprotocol.io
- PlayMCP: https://playmcp.kakao.com
