# naver-flight-mcp

네이버 항공권 검색 API를 사용하여 최저가 항공권 정보를 조회하는 Model Context Protocol (MCP) 서버입니다.

## ✨ 주요 기능

- **직항 항공권 최저가 검색** (성인 1명, 이코노미 클래스)
- **왕복 항공편 정보 조회** (출발/도착 시간, 소요시간, 항공편명)
- **최저가 순 상위 10개** 항공권 정보 제공
- **실시간 SSE 스트림 처리**로 완전한 데이터 수집
- **상세한 로그**로 검색 과정 추적

## 🚀 설치 및 설정

### 1. 프로젝트 클론 및 설치

```bash
# 프로젝트 클론
git clone https://github.com/your-username/naver-flight-mcp.git
cd naver-flight-mcp

# 의존성 설치
npm install

# TypeScript 빌드
npm run build
```

### 2. Cursor MCP 설정

**Windows**: `C:\Users\{사용자명}\.cursor\mcp.json`
**MacOS**: `~/.cursor/mcp.json`

#### 설정 파일 예시

```json
{
  "mcpServers": {
    "naver-flight": {
      "command": "node",
      "args": ["C:/Users/{사용자명}/naver-flight-mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

#### 실제 경로 예시 (Windows)

```json
{
  "mcpServers": {
    "naver-flight": {
      "command": "node",
      "args": ["C:/Users/hwang/naver-flight-mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

### 3. Cursor 재시작

MCP 설정을 추가한 후 Cursor를 재시작하면 네이버 항공권 검색 도구를 사용할 수 있습니다.

## 📖 사용 방법

### Cursor에서 사용

MCP 설정 후 Cursor에서 다음과 같이 사용할 수 있습니다:

```
네이버 항공권 검색: 부산(PUS) → 나리타(NRT), 2025-12-15 ~ 2025-12-19
```

### 검색 파라미터

```typescript
{
  departure: "PUS",           // 출발지 공항 코드
  arrival: "NRT",             // 도착지 공항 코드
  departureDate: "2025-12-15", // 출발일 (YYYY-MM-DD)
  returnDate: "2025-12-19"    // 복귀일 (YYYY-MM-DD)
}
```

### 출력 예시

```
항공권 검색 결과 (PUS → NRT):

순위: 1
출발일: 20251215
복귀일: 20251219
가는편: 7C1153
오는편: 7C1154
총요금: 278,700원
가는편 출발: 11:05
가는편 도착: 13:10
소요시간: 125분
오는편 출발: 14:05
오는편 도착: 16:45
소요시간: 160분
---
```

## 🧪 테스트 결과

### 2025년 12월 부산(PUS) - 나리타(NRT) 검색 결과

| 날짜                    | 최저가        | 항공편        | 상태    |
| ----------------------- | ------------- | ------------- | ------- |
| 2025-12-01 ~ 2025-12-05 | 304,000원     | 7C1153/7C1154 | ✅ 성공 |
| 2025-12-08 ~ 2025-12-12 | **277,000원** | 7C1153/7C1154 | ✅ 성공 |
| 2025-12-15 ~ 2025-12-19 | 278,700원     | 7C1153/7C1154 | ✅ 성공 |
| 2025-12-22 ~ 2025-12-26 | 416,400원     | 7C1153/7C1154 | ✅ 성공 |

### 인천(ICN) - 나리타(NRT) 검색 결과

| 날짜                    | 최저가    | 항공편        | 상태    |
| ----------------------- | --------- | ------------- | ------- |
| 2025-12-15 ~ 2025-12-19 | 312,600원 | BX0164/BX0163 | ✅ 성공 |

## 🔧 기술적 특징

### SSE 스트림 처리 개선

- **실시간 데이터 수집**: 네이버 API의 Server-Sent Events를 완전히 처리
- **점진적 데이터 증가**: 0개 → 16개 → 18개 → 20개 → 76개 → 77개
- **최종 유효 데이터 선택**: 가장 많은 데이터가 포함된 응답 사용
- **상세한 로그**: 각 단계별 데이터 수집 과정 추적

### 로그 예시

```
SSE 응답 처리 시작...
SSE 데이터 수신: 항공편 0개, 요금 0개
SSE 데이터 수신: 항공편 16개, 요금 32개
유효한 데이터 발견: 항공편 16개, 요금 32개
SSE 데이터 수신: 항공편 20개, 요금 100개
유효한 데이터 발견: 항공편 20개, 요금 100개
최종 데이터: 항공편 20개, 요금 100개
총 7009개의 요금 정보 발견
처리 완료 - 10개의 유효한 항공편
```

## 📁 프로젝트 구조

```
naver-flight-mcp/
├── src/
│   ├── tools/
│   │   └── NaverFlightSearch.ts  # 네이버 항공권 검색 도구
│   └── index.ts                   # MCP 서버 진입점
├── dist/                          # 빌드된 파일
├── NAVER_FLIGHT_API_ANALYSIS.md  # API 분석 문서
├── NAVER_FLIGHT_MCP_TEST_RESULTS.md  # 테스트 결과
├── package.json
├── tsconfig.json
└── README.md
```

## 🔌 API 정보

- **엔드포인트**: `https://flight-api.naver.com/flight/international/searchFlights`
- **방식**: REST API (Server-Sent Events)
- **검색 조건**: 성인 1명, 직항만, 이코노미 클래스 (고정)
- **응답 시간**: 일반적으로 4-5초 소요

## 🛠️ 개발자 정보

### 로컬 개발

```bash
# 개발 서버 실행
npm run dev

# 빌드
npm run build

# 로그 확인
node dist/index.js
```

### 의존성

- **TypeScript**: 타입 안전성
- **node-fetch**: HTTP 요청 처리
- **zod**: 스키마 검증
- **@modelcontextprotocol/sdk**: MCP 서버 구현

## 📄 라이선스

MIT