grep.app Code Search

Pesquise código em milhões de repositórios públicos do GitHub usando a API do grep.app.

GitHub
40
Experimente este MCPPatrocinado

Documentação

Servidor MCP Grep

Um servidor Model Context Protocol (MCP) que fornece recursos de busca de código no GitHub através da API do grep.app. Este servidor permite que assistentes de IA pesquisem em milhões de repositórios do GitHub por padrões de código, funções e implementações específicas.

🚀 Recursos

  • 🔍 Busca de Código no GitHub: Pesquise em milhões de repositórios do GitHub usando o poderoso índice de busca do grep.app
  • 🎯 Filtros Avançados: Filtre resultados por linguagem de programação, repositório e caminho de arquivo
  • 📊 Formatação Inteligente: Os resultados incluem realce de sintaxe, agrupamento por repositório e estatísticas resumidas
  • ⚡ Alto Desempenho: Implementação assíncrona com tratamento adequado de erros e limitação de taxa
  • 🛠️ Múltiplos Modos de Transporte: Suporta transporte stdio e SSE (Server-Sent Events)
  • 📝 Resultados Ricos: Retorna caminhos de arquivos, números de linha, trechos de código e informações do repositório

📋 Requisitos

  • Python: 3.10 ou superior
  • Dependências:
    • mcp - Framework Model Context Protocol
    • starlette - Framework web para transporte SSE
    • uvicorn - Servidor ASGI
    • aiohttp - Cliente HTTP assíncrono para requisições de API

🔧 Instalação

Usando uv (Recomendado)

# Install directly from PyPI
uv add grep-mcp

# Or install from source
git clone https://github.com/galperetz/grep-mcp.git
cd grep-mcp
uv sync

Usando pip

pip install grep-mcp

🎯 Uso

Como Servidor MCP (Recomendado)

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "grep-mcp": {
      "command": "uvx",
      "args": ["grep-mcp"]
    }
  }
}

Execução Direta

# Run with stdio transport (default)
python -m grep_mcp

# Run with SSE transport
python -m grep_mcp --transport sse --host 0.0.0.0 --port 8080

Argumentos de Linha de Comando

  • --transport: Escolha entre stdio (padrão) ou sse
  • --host: Host para vincular no modo SSE (padrão: 0.0.0.0)
  • --port: Porta para escutar no modo SSE (padrão: 8080)

🔧 Ferramentas Disponíveis

grep_query

Pesquise em repositórios do GitHub por padrões de código específicos.

Parâmetros:

  • query (obrigatório): A string de consulta de busca
  • language (opcional): Filtro de linguagem de programação (ex.: "Python", "JavaScript")
  • repo (opcional): Filtro de repositório no formato "dono/repo" (ex.: "fastapi/fastapi")
  • path (opcional): Filtro de caminho para diretórios específicos (ex.: "src/")

Exemplos:

# Basic search
grep_query("async def main")

# Search Python files only
grep_query("FastAPI", language="Python")

# Search specific repository
grep_query("class Config", repo="fastapi/fastapi")

# Search in specific directory
grep_query("import", path="src/")

# Combined filters
grep_query("async def", language="Python", repo="fastapi/fastapi")

📊 Formato de Resposta

A ferramenta retorna JSON estruturado com:

{
  "query": "your search query",
  "summary": {
    "total_results": 12345,
    "results_shown": 10,
    "repositories_found": 4,
    "top_languages": [
      { "language": "Python", "count": 8500 },
      { "language": "JavaScript", "count": 2000 }
    ],
    "top_repositories": [{ "repository": "owner/repo", "count": 150 }]
  },
  "results_by_repository": [
    {
      "repository": "owner/repo",
      "matches_count": 89,
      "files": [
        {
          "file_path": "src/main.py",
          "branch": "main",
          "total_matches": 5,
          "line_numbers": [10, 25, 30],
          "language": "python",
          "code_snippet": "```python\nasync def main():\n    app = FastAPI()\n    return app\n```"
        }
      ]
    }
  ]
}

🏗️ Arquitetura

  • Framework FastMCP: Construído no framework FastMCP para facilitar o desenvolvimento de servidores MCP
  • Cliente HTTP Assíncrono: Usa aiohttp para requisições de API não bloqueantes
  • Formatação de Respostas: Análise e formatação inteligente das respostas do grep.app
  • Tratamento de Erros: Tratamento abrangente de erros para falhas de API, timeouts e limites de taxa
  • Flexibilidade de Transporte: Suporta modos de transporte stdio e SSE baseado em web

🛡️ Tratamento de Erros

O servidor lida com várias condições de erro de forma graciosa:

  • Limitação de Taxa: Detecção automática e mensagens de erro amigáveis ao usuário
  • Timeouts de Rede: Timeout de 30 segundos com relatório de erros adequado
  • Falhas de API: Tratamento gracioso de problemas da API do grep.app
  • Parâmetros Inválidos: Validação abrangente de parâmetros com mensagens de erro úteis

🧪 Testes

Execute a suíte de testes:

# Using uv
uv run pytest

# Using pytest directly
pytest tests/

A cobertura de testes inclui:

  • Inicialização do servidor MCP
  • Validação de parâmetros das ferramentas
  • Cenários de tratamento de erros
  • Formatação de respostas
  • Compatibilidade de plataformas

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso: git checkout -b feature/amazing-feature
  3. Faça suas alterações com testes
  4. Execute a suíte de testes: uv run pytest
  5. Formate o código: uv run black . && uv run isort .
  6. Faça commit das alterações: git commit -m 'Add amazing feature'
  7. Envie para o branch: git push origin feature/amazing-feature
  8. Abra um Pull Request

📝 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

📞 Suporte

Feito com ❤️ para a comunidade de desenvolvimento de IA