Unified Search MCP Server

Fornece capacidades de busca unificada no Google Scholar, Google Web Search e YouTube.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Unified Search MCP Server 🔍

Nível de produção servidor MCP (Model Context Protocol) que permite pesquisa integrada em Google Scholar, Google Web Search e YouTube.

License: MIT Python 3.11+ smithery badge

🚀 Principais Recursos

Recursos Principais de Pesquisa

  • 🎓 Google Scholar: Pesquisa de artigos acadêmicos (filtragem por autor, ano)
  • 🌐 Google Web Search: Pesquisa na web usando a API Google Custom Search
  • 📺 YouTube Search: Pesquisa de vídeos (duração, data de upload, opções de ordenação)
  • 🔄 Pesquisa Integrada: Pesquisa simultânea em todas as fontes

Recursos Empresariais

  • 🔐 Segurança: Criptografia de chaves de API, validação de entrada, prevenção contra XSS/injeção de SQL
  • 💾 Cache Distribuído: Cache baseado em Redis e gerenciamento de TTL
  • ⚡ Rate Limiting: Limite de taxa configurável com backend Redis
  • 📊 Monitoramento: Métricas Prometheus, health checks, logging estruturado
  • 🔄 Resiliência: Lógica de nova tentativa, circuit breaker, degradação graciosa
  • 📝 Log de Auditoria: Trilha de auditoria abrangente para conformidade

📋 Requisitos

  • Python 3.11+
  • Redis (opcional, para recursos distribuídos)
  • Chaves de API:
    • Google Custom Search API (para pesquisa na web)
      • YouTube Data API v3 (para pesquisa no YouTube)

🛠️ Instalação

Instalação rápida via Smithery

A implantação direta pela plataforma Smithery configura tudo automaticamente.

Instalação manual

  1. Clone o repositório:
git clone https://github.com/JDeun/unified-search-mcp-server.git
cd unified-search-mcp-server
  1. Crie o ambiente virtual:
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
  1. Instale as dependências:
pip install -r requirements.txt
  1. Configure o ambiente:
cp .env.example .env
# .env 파일을 편집하여 API 키와 설정 입력

⚙️ Configuração

Variáveis de ambiente

# 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

Como obter chaves de API

  1. Google Custom Search API:
  2. YouTube Data API v3:
    • Use o mesmo projeto do Google Cloud Console
      • Ative a "YouTube Data API v3"
      • Use a mesma chave de API ou crie uma nova

🚀 Uso

Executando o 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

Implantação com 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

Integração com Claude Desktop

Adicione em 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"
      }
    }
  }
}

📖 Ferramentas Disponíveis

unified_search

Pesquisa simultaneamente em todas as fontes.

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

search_google_scholar

Pesquisa artigos acadêmicos.

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

search_google_web

Pesquisa na web.

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

search_youtube

Pesquisa vídeos no YouTube.

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

get_author_info

Obtém informações do autor no Google Scholar.

info = await get_author_info("Geoffrey Hinton")

clear_cache

Remove resultados de pesquisa em cache.

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

get_api_usage_stats

Monitora o uso e os limites da API.

stats = await get_api_usage_stats()

🏗️ Arquitetura

Design Modular

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

Camada de Segurança

  • Validação e sanitização de entrada
  • Armazenamento criptografado de chaves de API
  • Rate limiting por cliente/endpoint
  • Log de auditoria para conformidade
  • CORS e rastreamento de ID de requisição

Otimização de Desempenho

  • Cache distribuído baseado em Redis
  • Pooling de conexões do cliente HTTP
  • Execução de pesquisas simultâneas
  • Novas tentativas inteligentes com backoff exponencial
  • Circuit breaker para APIs externas

📊 Monitoramento

Endpoint de Health Check

리소스: health://status

Endpoint de Métricas

리소스: metrics://stats

Principais Métricas

  • Número de requisições de pesquisa e latência
  • Taxa de acerto do cache
  • Uso de cota da API
  • Taxa de erro por fonte
  • Violações de rate limit

🔒 Segurança

Boas Práticas

  • Todas as chaves de API criptografadas com Fernet
  • Validação de entrada para prevenção de XSS/injeção de SQL
  • Rate limiting para prevenção de abuso
  • Logging estruturado sem dados sensíveis
  • Atualizações regulares de segurança

Conformidade

  • Pronto para GDPR sem armazenamento de PII
  • Trilha de auditoria para todas as pesquisas
  • Retenção de dados configurável
  • Rastreamento de uso da API

🧪 Testes

Executar testes:

pytest tests/ -v --cov=src

🤝 Contribuição

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing)
  3. Faça commit das alterações (git commit -m 'Add feature')
  4. Envie para o branch (git push origin feature/amazing)
  5. Abra um Pull Request

📝 Licença

Licença MIT - consulte o arquivo LICENSE para mais detalhes

🙏 Agradecimentos

  • Construído com FastMCP
  • Pesquisa no Google Scholar via scholarly
  • Inspiração da comunidade MCP

⚠️ Notas Importantes

Limites da API

  • Google Web Search: 100 consultas/dia (nível gratuito)
  • YouTube API: 10.000 unidades/dia (cerca de 100 pesquisas)
  • Google Scholar: sem API oficial, com limites de taxa

Considerações de Produção

  • Use Redis para implantação distribuída
  • Configure a rotação adequada de chaves de API
  • Monitore rate limits e cotas
  • Configure alertas para erros de API
  • Faça backups regulares da configuração

📞 Suporte

Problemas e dúvidas:

  • GitHub Issues: Criar issue
  • Suporte Smithery: problemas relacionados à implantação

Feito com ❤️ para a comunidade MCP