# Naver Search Docs MCP Server
네이버 검색 API와 Gemini AI를 활용하여 질문에 대한 공식 문서를 찾아주는 MCP(Model Context Protocol) 서버 및 FastAPI 서비스입니다.
## 기능
- 네이버 검색 API를 사용하여 웹 검색 수행
- Gemini AI를 활용하여 검색 결과 중 공식 문서 필터링
- 공식 문서의 URL과 설명 반환
- FastAPI를 통한 REST API 제공
- 확장 가능한 MCP 도구 구조
## 프로젝트 구조
```
mcp_server/
├── src/
│ ├── __init__.py
│ ├── main.py # FastAPI 서버
│ ├── mcp_client.py # MCP 클라이언트
│ ├── mcp_server.py # MCP 서버 메인
│ ├── tools/ # MCP 도구들
│ │ ├── __init__.py
│ │ └── search_docs.py # 검색 도구
│ └── utils/ # 유틸리티 함수들
│ ├── __init__.py
│ ├── gemini.py # Gemini AI 함수
│ └── naver_search.py # 네이버 검색 함수
├── tests/
│ └── test_api.py # API 테스트
├── docs/ # 참고 문서
│ ├── ai_deps # Gemini 참고 코드
│ └── search_deps # 네이버 검색 참고 코드
├── requirements.txt # Python 의존성
├── pyproject.toml # 프로젝트 설정
├── README.md # 이 파일
└── .gitignore # Git 제외 파일
```
## 설치 방법
### 1. 의존성 설치
```bash
pip install -r requirements.txt
```
### 2. 환경 설정
#### 네이버 API 인증 정보
`src/utils/naver_search.py` 파일에서 네이버 API 인증 정보를 설정:
```python
NAVER_CLIENT_ID = 'your_client_id'
NAVER_CLIENT_SECRET = 'your_client_secret'
```
#### Google Cloud 인증
`src/utils/gemini.py` 파일에서 Google Cloud 서비스 계정 키 파일 경로 설정:
```python
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/credentials.json"
```
## 사용 방법
### 방법 1: FastAPI 서버로 사용 (권장)
#### 1. FastAPI 서버 실행
```bash
cd /Users/yanghyojun/Desktop/mcp_server
python -m src.main
```
또는 uvicorn으로 직접 실행:
```bash
uvicorn src.main:app --reload --host 0.0.0.0 --port 8001
```
서버가 **http://localhost:8001** 에서 실행됩니다.
#### 2. API 사용
**검색 API 엔드포인트**
```bash
curl -X POST "http://localhost:8001/search" \
-H "Content-Type: application/json" \
-d '{"query": "Python 공식 문서"}'
```
**응답 예시**
```json
{
"result": "'Python 공식 문서'에 대한 공식 문서를 찾았습니다:\n\n1. Python 공식 문서\n URL: https://docs.python.org/ko/3/\n 설명: Python 프로그래밍 언어의 공식 문서...\n\n",
"query": "Python 공식 문서"
}
```
**API 문서**
- Swagger UI: http://localhost:8001/docs
- ReDoc: http://localhost:8001/redoc
**기타 엔드포인트**
- `GET /`: API 상태 확인
- `GET /health`: 헬스 체크
#### 3. 테스트 실행
```bash
python tests/test_api.py
```
---
### 방법 2: 메인 서버에서 마이크로서비스로 사용
MCP 서버를 별도로 실행하고, 메인 FastAPI 서버에서 HTTP 요청으로 호출
#### 1단계: MCP 서버 실행 (8001 포트)
```bash
cd /Users/yanghyojun/Desktop/mcp_server
python -m src.main
```
#### 2단계: 메인 서버에서 HTTP 요청으로 호출
```python
# 메인 FastAPI 서버 코드
import httpx
from fastapi import HTTPException
@app.post("/search-docs")
async def search_official_docs(query: str):
"""공식 문서 검색"""
try:
async with httpx.AsyncClient() as client:
response = await client.post(
"http://localhost:8001/search",
json={"query": query},
timeout=30.0
)
response.raise_for_status()
return response.json()
except httpx.RequestError as e:
raise HTTPException(status_code=503, detail=f"MCP 서버 연결 실패: {str(e)}")
```
---
### 방법 3: MCP 서버 직접 실행
```bash
python -m src.mcp_server
```
Claude Desktop 등의 MCP 클라이언트에서 사용하려면 설정 파일에 추가:
**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"naver-search-docs": {
"command": "python",
"args": ["-m", "src.mcp_server"],
"cwd": "/Users/yanghyojun/Desktop/mcp_server"
}
}
}
```
## 새로운 MCP 도구 추가하기
### 1. 도구 클래스 생성
`src/tools/` 디렉토리에 새로운 도구 파일 생성:
```python
# src/tools/my_new_tool.py
from typing import Any, List
from mcp import types
class MyNewTool:
"""새로운 도구 설명"""
@staticmethod
def get_tool_definition() -> types.Tool:
"""도구 정의 반환"""
return types.Tool(
name="my_new_tool",
description="도구 설명",
inputSchema={
"type": "object",
"properties": {
"param": {
"type": "string",
"description": "파라미터 설명"
}
},
"required": ["param"]
}
)
@staticmethod
async def execute(arguments: dict[str, Any]) -> List[types.TextContent]:
"""도구 실행"""
# 도구 로직 구현
return [types.TextContent(
type="text",
text="결과"
)]
```
### 2. 도구 등록
`src/tools/__init__.py`에 추가:
```python
from .my_new_tool import MyNewTool
__all__ = [
"SearchDocsTool",
"MyNewTool", # 추가
]
```
### 3. MCP 서버에 등록
`src/mcp_server.py`의 `TOOLS` 리스트에 추가:
```python
from .tools import SearchDocsTool, MyNewTool
TOOLS = [
SearchDocsTool,
MyNewTool, # 추가
]
```
## 작동 원리
### FastAPI 서버 사용 시
1. FastAPI 서버 시작 시 MCP 서버를 subprocess로 실행
2. MCP 클라이언트가 stdio를 통해 MCP 서버와 연결
3. 사용자가 REST API로 검색 요청
4. MCP 클라이언트가 MCP 서버의 도구 호출
5. MCP 서버가 네이버 검색 API로 검색 수행 (최대 30개 결과)
6. 검색 결과를 Gemini AI로 분석하여 공식 문서 필터링
7. 결과를 FastAPI를 통해 JSON으로 반환
### MCP 서버 직접 사용 시
1. Claude Desktop 등의 MCP 클라이언트가 MCP 서버에 연결
2. 사용자가 질문을 입력
3. 네이버 검색 API를 사용하여 웹 검색 수행
4. 검색 결과를 Gemini AI로 분석
5. AI가 공식 문서를 식별하여 필터링
6. 공식 문서의 제목, URL, 설명 반환
## 라이선스
MIT
