Unified Search MCP Server 🔍
프로덕션 레벨 MCP (Model Context Protocol) 서버로 Google Scholar, Google Web Search, YouTube를 통합 검색할 수 있습니다.
🚀 주요 기능
핵심 검색 기능
- 🎓 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 파일 참조
🙏 감사의 말
⚠️ 중요 사항
API 제한
- Google Web Search: 100 쿼리/일 (무료 티어)
- YouTube API: 10,000 유닛/일 (약 100 검색)
- Google Scholar: 공식 API 없음, rate 제한 있음
프로덕션 고려사항
- 분산 배포를 위해 Redis 사용
- 적절한 API 키 로테이션 설정
- Rate limit 및 할당량 모니터링
- API 오류에 대한 알림 설정
- 정기적인 설정 백업
📞 지원
문제 및 질문:
- GitHub Issues: 이슈 생성
- Smithery 지원: 배포 관련 문제
MCP 커뮤니티를 위해 ❤️로 제작