Unified Search MCP Server

Proporciona capacidades de búsqueda unificada en Google Scholar, Google Web Search y YouTube.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Unified Search MCP Server 🔍

Servidor MCP (Model Context Protocol) de nivel de producción que integra búsquedas en Google Scholar, Google Web Search y YouTube.

License: MIT Python 3.11+ smithery badge

🚀 Características principales

Funciones de búsqueda principales

  • 🎓 Google Scholar: Búsqueda de artículos académicos (filtrado por autor, año)
  • 🌐 Google Web Search: Búsqueda web mediante Google Custom Search API
  • 📺 YouTube Search: Búsqueda de videos (duración, fecha de publicación, opciones de orden)
  • 🔄 Búsqueda integrada: Búsqueda simultánea en todas las fuentes

Funciones empresariales

  • 🔐 Seguridad: Cifrado de claves API, validación de entradas, prevención de XSS/inyección SQL
  • 💾 Caché distribuida: Caché basada en Redis y gestión de TTL
  • ⚡ Limitación de velocidad: Límites de velocidad configurables con backend Redis
  • 📊 Monitoreo: Métricas Prometheus, comprobaciones de salud, registro estructurado
  • 🔄 Resiliencia: Lógica de reintentos, interruptor de circuito, degradación elegante
  • 📝 Registro de auditoría: Seguimiento de auditoría integral para cumplimiento normativo

📋 Requisitos

  • Python 3.11+
  • Redis (opcional, para funciones distribuidas)
  • Claves API:
    • Google Custom Search API (para búsqueda web)
    • YouTube Data API v3 (para búsqueda en YouTube)

🛠️ Instalación

Instalación rápida mediante Smithery

Se configura automáticamente al implementar directamente a través de la plataforma Smithery.

Instalación manual

  1. Clonar el repositorio:
git clone https://github.com/JDeun/unified-search-mcp-server.git
cd unified-search-mcp-server
  1. Crear el entorno virtual:
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
  1. Instalar dependencias:
pip install -r requirements.txt
  1. Configurar el entorno:
cp .env.example .env
# .env 파일을 편집하여 API 키와 설정 입력

⚙️ Configuración

Variables de entorno

# 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

Cómo obtener claves API

  1. Google Custom Search API:
  2. YouTube Data API v3:
    • Usar el mismo proyecto de Google Cloud Console
    • Activar "YouTube Data API v3"
    • Usar la misma clave API o crear una nueva

🚀 Uso

Ejecutar el servidor

# 개발 모드 (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

Implementación con 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

Integración con Claude Desktop

Agregar a 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"
      }
    }
  }
}

📖 Herramientas disponibles

unified_search

Busca simultáneamente en todas las fuentes.

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

search_google_scholar

Busca artículos académicos.

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

search_google_web

Busca en la web.

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

search_youtube

Busca videos en YouTube.

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

get_author_info

Obtiene información del autor en Google Scholar.

info = await get_author_info("Geoffrey Hinton")

clear_cache

Elimina los resultados de búsqueda almacenados en caché.

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

get_api_usage_stats

Monitorea el uso y los límites de la API.

stats = await get_api_usage_stats()

🏗️ Arquitectura

Diseño modular

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

Capa de seguridad

  • Validación y saneamiento de entradas
  • Almacenamiento cifrado de claves API
  • Limitación de velocidad por cliente/endpoint
  • Registro de auditoría para cumplimiento normativo
  • CORS y seguimiento de ID de solicitud

Optimización del rendimiento

  • Caché distribuida basada en Redis
  • Agrupación de conexiones del cliente HTTP
  • Ejecución de búsquedas concurrentes
  • Reintentos inteligentes con retroceso exponencial
  • Interruptor de circuito para APIs externas

📊 Monitoreo

Endpoint de comprobación de salud

리소스: health://status

Endpoint de métricas

리소스: metrics://stats

Métricas principales

  • Número de solicitudes de búsqueda y latencia
  • Tasa de aciertos de caché
  • Uso de cuota de API
  • Tasa de errores por fuente
  • Violaciones de límite de velocidad

🔒 Seguridad

Buenas prácticas

  • Todas las claves API cifradas con Fernet
  • Validación de entradas para prevenir XSS/inyección SQL
  • Limitación de velocidad para prevenir abusos
  • Registro estructurado sin datos sensibles
  • Actualizaciones de seguridad periódicas

Cumplimiento normativo

  • Preparado para GDPR sin almacenamiento de PII
  • Seguimiento de auditoría para todas las búsquedas
  • Retención de datos configurable
  • Seguimiento del uso de API

🧪 Pruebas

Ejecutar pruebas:

pytest tests/ -v --cov=src

🤝 Contribuciones

  1. Hacer fork del repositorio
  2. Crear una rama de funcionalidad (git checkout -b feature/amazing)
  3. Confirmar los cambios (git commit -m 'Add feature')
  4. Hacer push a la rama (git push origin feature/amazing)
  5. Abrir un Pull Request

📝 Licencia

Licencia MIT: consulte el archivo LICENSE para más detalles

🙏 Agradecimientos

  • Construido con FastMCP
  • Búsqueda en Google Scholar mediante scholarly
  • Inspiración de la comunidad MCP

⚠️ Notas importantes

Límites de API

  • Google Web Search: 100 consultas/día (nivel gratuito)
  • YouTube API: 10,000 unidades/día (aproximadamente 100 búsquedas)
  • Google Scholar: sin API oficial, con límites de velocidad

Consideraciones de producción

  • Usar Redis para implementaciones distribuidas
  • Configurar una rotación adecuada de claves API
  • Monitorear límites de velocidad y cuotas
  • Configurar alertas para errores de API
  • Realizar copias de seguridad periódicas de la configuración

📞 Soporte

Problemas y preguntas:

  • GitHub Issues: Crear un issue
  • Soporte de Smithery: problemas relacionados con la implementación

Hecho con ❤️ para la comunidad MCP