Unified Search MCP Server 🔍

프로덕션 레벨 MCP (Model Context Protocol) 서버로 Google Scholar, Google Web Search, YouTube를 통합 검색할 수 있습니다.

License: MIT Python 3.11+ smithery badge

🚀 주요 기능

핵심 검색 기능

🎓 Google Scholar: 학술 논문 검색 (저자, 연도 필터링)
🌐 Google Web Search: Google Custom Search API를 사용한 웹 검색
📺 YouTube Search: 동영상 검색 (길이, 업로드 날짜, 정렬 옵션)
🔄 통합 검색: 모든 소스에서 동시 검색

엔터프라이즈 기능

🔐 보안: API 키 암호화, 입력값 검증, XSS/SQL 인젝션 방지
💾 분산 캐싱: Redis 기반 캐싱 및 TTL 관리
⚡ Rate Limiting: Redis 백엔드 기반 설정 가능한 rate limit
📊 모니터링: Prometheus 메트릭, 헬스 체크, 구조화된 로깅
🔄 복원력: 재시도 로직, 서킷 브레이커, 우아한 성능 저하
📝 감사 로깅: 규정 준수를 위한 포괄적인 감사 추적

📋 요구 사항

Python 3.11+
Redis (선택사항, 분산 기능용)
API 키:
- Google Custom Search API (웹 검색용)
- YouTube Data API v3 (YouTube 검색용)

🛠️ 설치

Smithery를 통한 빠른 설치

Smithery 플랫폼을 통해 직접 배포하면 자동으로 설정됩니다.

수동 설치

저장소 클론:

git clone https://github.com/JDeun/unified-search-mcp-server.git cd unified-search-mcp-server

가상 환경 생성:

python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate

의존성 설치:

pip install -r requirements.txt

환경 설정:

cp .env.example .env

.env 파일을 편집하여 API 키와 설정 입력

⚙️ 설정

환경 변수

API 키

GOOGLE_API_KEY=your-google-api-key GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your-cse-id YOUTUBE_API_KEY=your-youtube-api-key

보안

MCP_ENCRYPTION_KEY=your-256-bit-key MCP_RATE_LIMIT_SECRET=your-secret

Redis (선택사항)

MCP_REDIS_URL=redis://localhost:6379/0

설정

MCP_ENV=production MCP_LOG_LEVEL=INFO MCP_CACHE_TTL=3600

API 키 발급 방법

Google Custom Search API:
- Google Cloud Console 접속
- "Custom Search API" 활성화
- 인증 정보 생성 (API 키)
- cse.google.com에서 Custom Search Engine 생성
YouTube Data API v3:
- 동일한 Google Cloud Console 프로젝트 사용
- "YouTube Data API v3" 활성화
- 동일한 API 키 사용 또는 새로 생성

🚀 사용법

서버 실행

개발 모드 (stdio)

python unified_search_server.py

프로덕션 모드 (HTTP)

python unified_search_server.py --transport streamable-http

커스텀 포트

MCP_PORT=8080 python unified_search_server.py --transport streamable-http

Docker 배포

이미지 빌드

docker build -t unified-search-mcp .

컨테이너 실행

docker run -p 8000:8000
-e GOOGLE_API_KEY=your-key
-e GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your-cse
-e YOUTUBE_API_KEY=your-key
unified-search-mcp

Claude Desktop 통합

claude_desktop_config.json에 추가:

{ "mcpServers": { "unified-search": { "command": "python", "args": ["/path/to/unified_search_server.py"], "env": { "GOOGLE_API_KEY": "your-key", "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your-cse", "YOUTUBE_API_KEY": "your-key" } } } }

📖 사용 가능한 도구

unified_search

모든 소스에서 동시에 검색합니다.

results = await unified_search( query="인공지능", sources=["scholar", "web", "youtube"], num_results=10 )

search_google_scholar

학술 논문을 검색합니다.

results = await search_google_scholar( query="머신러닝", author="Yann LeCun", year_start=2020, year_end=2024, num_results=10 )

search_google_web

웹을 검색합니다.

results = await search_google_web( query="ChatGPT", language="ko", safe_search="medium", num_results=10 )

search_youtube

YouTube 동영상을 검색합니다.

results = await search_youtube( query="파이썬 튜토리얼", video_duration="medium", upload_date="month", order="viewCount", num_results=20 )

get_author_info

Google Scholar에서 저자 정보를 가져옵니다.

info = await get_author_info("Geoffrey Hinton")

clear_cache

캐시된 검색 결과를 삭제합니다.

await clear_cache(source="web") # 또는 None으로 전체 삭제

get_api_usage_stats

API 사용량과 제한을 모니터링합니다.

stats = await get_api_usage_stats()

🏗️ 아키텍처

모듈식 설계

src/
├── config/       # 설정 및 보안
├── models/       # 데이터 모델 및 검증
├── services/     # 검색 서비스 구현
├── cache/        # 캐싱 레이어
├── utils/        # 유틸리티 (로깅, rate limiting)
├── monitoring/   # 메트릭 및 헬스 체크
└── mcp_server.py # 메인 서버 구현

보안 레이어

입력값 검증 및 살균
API 키 암호화 저장
클라이언트/엔드포인트별 rate limiting
규정 준수를 위한 감사 로깅
CORS 및 요청 ID 추적

성능 최적화

Redis 기반 분산 캐싱
HTTP 클라이언트 연결 풀링
동시 검색 실행
지수 백오프를 통한 스마트 재시도
외부 API용 서킷 브레이커

📊 모니터링

헬스 체크 엔드포인트

리소스: health://status

메트릭 엔드포인트

리소스: metrics://stats

주요 메트릭

검색 요청 수 및 지연 시간
캐시 히트율
API 할당량 사용량
소스별 오류율
Rate limit 위반

🔒 보안

모범 사례

모든 API 키 Fernet으로 암호화
XSS/SQL 인젝션 방지를 위한 입력 검증
남용 방지를 위한 rate limiting
민감한 데이터 없는 구조화된 로깅
정기적인 보안 업데이트

규정 준수

PII 저장 없는 GDPR 준비
모든 검색에 대한 감사 추적
설정 가능한 데이터 보존
API 사용량 추적

🧪 테스트

테스트 실행:

pytest tests/ -v --cov=src

🤝 기여

저장소 포크
기능 브랜치 생성 (git checkout -b feature/amazing)
변경 사항 커밋 (git commit -m 'Add feature')
브랜치에 푸시 (git push origin feature/amazing)
Pull Request 열기

📝 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일 참조

🙏 감사의 말

FastMCP로 구축
scholarly를 통한 Google Scholar 검색
MCP 커뮤니티의 영감

⚠️ 중요 사항

API 제한

Google Web Search: 100 쿼리/일 (무료 티어)
YouTube API: 10,000 유닛/일 (약 100 검색)
Google Scholar: 공식 API 없음, rate 제한 있음

프로덕션 고려사항

분산 배포를 위해 Redis 사용
적절한 API 키 로테이션 설정
Rate limit 및 할당량 모니터링
API 오류에 대한 알림 설정
정기적인 설정 백업

📞 지원

문제 및 질문:

GitHub Issues: 이슈 생성
Smithery 지원: 배포 관련 문제

MCP 커뮤니티를 위해 ❤️로 제작

Unified Search MCP Server