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. 의존성 설치

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 문서

• Swagger UI: http://localhost:8001/docs
• ReDoc: http://localhost:8001/redoc

기타 엔드포인트

• GET /: API 상태 확인
• GET /health: 헬스 체크

3. 테스트 실행

python tests/test_api.py

---

방법 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 서버 직접 실행

python -m src.mcp_server

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 서버 사용 시

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