Naver Search Docs MCP Server
네이버 검색 API와 Gemini AI를 활용하여 질문에 대한 공식 문서를 찾아주는 MCP(Model Context Protocol) 서버 및 FastAPI 서비스입니다.
기능
프로젝트 구조
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. 의존성 설치
pip install -r requirements.txt
2. 환경 설정
네이버 API 인증 정보
src/utils/naver_search.py 파일에서 네이버 API 인증 정보를 설정:
NAVER_CLIENT_ID = 'your_client_id'
NAVER_CLIENT_SECRET = 'your_client_secret'
Google Cloud 인증
src/utils/gemini.py 파일에서 Google Cloud 서비스 계정 키 파일 경로 설정:
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/credentials.json"
사용 방법
방법 1: FastAPI 서버로 사용 (권장)
1. FastAPI 서버 실행
cd /Users/yanghyojun/Desktop/mcp_server
python -m src.main
또는 uvicorn으로 직접 실행:
uvicorn src.main:app --reload --host 0.0.0.0 --port 8001
서버가 http://localhost:8001 에서 실행됩니다.
2. API 사용
검색 API 엔드포인트
curl -X POST "http://localhost:8001/search" \
-H "Content-Type: application/json" \
-d '{"query": "Python 공식 문서"}'
응답 예시
{
"result": "'Python 공식 문서'에 대한 공식 문서를 찾았습니다:\n\n1. Python 공식 문서\n URL: https://docs.python.org/ko/3/\n 설명: Python 프로그래밍 언어의 공식 문서...\n\n",
"query": "Python 공식 문서"
}
API 문서
기타 엔드포인트
GET /: API 상태 확인
GET /health: 헬스 체크
3. 테스트 실행
방법 2: 메인 서버에서 마이크로서비스로 사용
MCP 서버를 별도로 실행하고, 메인 FastAPI 서버에서 HTTP 요청으로 호출
1단계: MCP 서버 실행 (8001 포트)
cd /Users/yanghyojun/Desktop/mcp_server
python -m src.main
2단계: 메인 서버에서 HTTP 요청으로 호출
# 메인 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 서버 직접 실행
Claude Desktop 등의 MCP 클라이언트에서 사용하려면 설정 파일에 추가:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"naver-search-docs": {
"command": "python",
"args": ["-m", "src.mcp_server"],
"cwd": "/Users/yanghyojun/Desktop/mcp_server"
}
}
}
새로운 MCP 도구 추가하기
1. 도구 클래스 생성
src/tools/ 디렉토리에 새로운 도구 파일 생성:
# 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에 추가:
from .my_new_tool import MyNewTool
__all__ = [
"SearchDocsTool",
"MyNewTool", # 추가
]
3. MCP 서버에 등록
src/mcp_server.py의 TOOLS 리스트에 추가:
from .tools import SearchDocsTool, MyNewTool
TOOLS = [
SearchDocsTool,
MyNewTool, # 추가
]
작동 원리
FastAPI 서버 사용 시
FastAPI 서버 시작 시 MCP 서버를 subprocess로 실행
MCP 클라이언트가 stdio를 통해 MCP 서버와 연결
사용자가 REST API로 검색 요청
MCP 클라이언트가 MCP 서버의 도구 호출
MCP 서버가 네이버 검색 API로 검색 수행 (최대 30개 결과)
검색 결과를 Gemini AI로 분석하여 공식 문서 필터링
결과를 FastAPI를 통해 JSON으로 반환
MCP 서버 직접 사용 시
Claude Desktop 등의 MCP 클라이언트가 MCP 서버에 연결
사용자가 질문을 입력
네이버 검색 API를 사용하여 웹 검색 수행
검색 결과를 Gemini AI로 분석
AI가 공식 문서를 식별하여 필터링
공식 문서의 제목, URL, 설명 반환
라이선스
MIT
