# 네이버 백과사전 검색 MCP 서버

네이버 백과사전 검색 API를 MCP(Model Context Protocol) 서버로 래핑한 프로젝트입니다.

## 기능

- 네이버 백과사전 검색 API 연동
- stdin/stdout 모드 지원
- HTTP 모드 지원
- 에러 처리 및 로깅
- 테스트 코드 포함

## 설치

### 1. 의존성 설치

```bash
pip install -r requirements.txt
```

### 2. 환경 변수 설정

```bash
cp env.example .env
```

`.env` 파일을 편집하여 네이버 API 키를 설정하세요:

```bash
NAVER_CLIENT_ID=your_client_id_here
NAVER_CLIENT_SECRET=your_client_secret_here
```

## 사용법

### 쉬운 실행 방법 (권장)

```bash
# stdin/stdout 모드 (기본)
python3 run_server.py --mode stdin

# HTTP 모드
python3 run_server.py --mode http --host localhost --port 8000

# 도움말
python3 run_server.py --help
```

### 직접 실행 방법

```bash
# stdin/stdout 모드
PYTHONPATH=. python3 src/server.py --mode stdin

# HTTP 모드
PYTHONPATH=. python3 src/server.py --mode http --host localhost --port 8000

# 도움말
PYTHONPATH=. python3 src/server.py --help
```

## API 키 발급

1. [네이버 개발자 센터](https://developers.naver.com/)에 접속
2. 애플리케이션 등록
3. 검색 API 사용 권한 설정
4. 클라이언트 아이디와 시크릿 발급

## 테스트

```bash
# 모든 테스트 실행
PYTHONPATH=. python3 -m pytest tests/

# 특정 테스트 실행
PYTHONPATH=. python3 -m pytest tests/test_naver_api.py -v
PYTHONPATH=. python3 -m pytest tests/test_server.py -v
```

## 프로젝트 구조

```
naver-encyc-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py          # MCP 서버 메인
│   ├── naver_api.py       # 네이버 API 클라이언트
│   ├── models.py          # 데이터 모델
│   └── config/
│       ├── __init__.py
│       └── settings.py    # 설정 관리
├── tests/
│   ├── __init__.py
│   ├── test_naver_api.py  # API 클라이언트 테스트
│   └── test_server.py     # 서버 테스트
├── docs/                  # 문서
├── requirements.txt       # 의존성
├── env.example           # 환경 변수 예시
├── run_server.py         # 실행 스크립트 (권장)
└── README.md            # 프로젝트 문서
```

## MCP 함수

### search_encyclopedia

네이버 백과사전에서 검색어로 관련 정보를 검색합니다.

**파라미터:**
- `query` (string, 필수): 검색할 키워드
- `display` (integer, 선택): 한 번에 표시할 검색 결과 개수 (기본값: 10, 최대: 100)
- `start` (integer, 선택): 검색 시작 위치 (기본값: 1, 최대: 1000)

**응답:**
```json
{
  "total": 100,
  "start": 1,
  "display": 10,
  "items": [
    {
      "title": "검색 결과 제목",
      "link": "https://example.com",
      "description": "검색 결과 설명",
      "thumbnail": "https://example.com/image.jpg"
    }
  ],
  "last_build_date": "Mon, 26 Sep 2016 10:50:00 +0900"
}
```

## 오류 처리

서버는 다음과 같은 오류 상황을 처리합니다:

- 네이버 API 오류 (SE01, SE02, SE03 등)
- 네트워크 오류
- 설정 오류 (API 키 미설정)
- 예상치 못한 오류

오류 응답 형식:
```json
{
  "error": true,
  "error_code": "ERROR_CODE",
  "message": "오류 메시지",
  "status_code": 400
}
```

## 라이선스

MIT License

## 참고 자료

- [네이버 백과사전 검색 API 문서](https://developers.naver.com/docs/serviceapi/search/encyclopedia/encyclopedia.md)
- [FastMCP 문서](https://github.com/fastmcp/fastmcp)
- [MCP 프로토콜 스펙](https://modelcontextprotocol.io/)