grep.app Code Search

Busca código en millones de repositorios públicos de GitHub usando la API de grep.app.

GitHub
40
Prueba este MCPPatrocinado

Documentación

Servidor MCP Grep

Un servidor Model Context Protocol (MCP) que proporciona capacidades de búsqueda de código en GitHub a través de la API de grep.app. Este servidor permite a los asistentes de IA buscar en millones de repositorios de GitHub patrones de código, funciones e implementaciones específicas.

🚀 Características

  • 🔍 Búsqueda de código en GitHub: Busca en millones de repositorios de GitHub utilizando el potente índice de búsqueda de grep.app
  • 🎯 Filtrado avanzado: Filtra resultados por lenguaje de programación, repositorio y ruta de archivo
  • 📊 Formato inteligente: Los resultados incluyen resaltado de sintaxis, agrupación por repositorio y estadísticas resumidas
  • ⚡ Alto rendimiento: Implementación asíncrona con manejo adecuado de errores y limitación de velocidad
  • 🛠️ Múltiples modos de transporte: Soporta transporte stdio y SSE (Server-Sent Events)
  • 📝 Resultados enriquecidos: Devuelve rutas de archivo, números de línea, fragmentos de código e información del repositorio

📋 Requisitos

  • Python: 3.10 o superior
  • Dependencias:
    • mcp - Framework Model Context Protocol
    • starlette - Framework web para transporte SSE
    • uvicorn - Servidor ASGI
    • aiohttp - Cliente HTTP asíncrono para solicitudes API

🔧 Instalación

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)

Añade a la configuración de tu cliente MCP:

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

Ejecución directa

# 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 línea de comandos

  • --transport: Elige entre stdio (predeterminado) o sse
  • --host: Host al que vincularse para modo SSE (predeterminado: 0.0.0.0)
  • --port: Puerto para escuchar en modo SSE (predeterminado: 8080)

🔧 Herramientas disponibles

grep_query

Busca patrones de código específicos en repositorios de GitHub.

Parámetros:

  • query (obligatorio): La cadena de consulta de búsqueda
  • language (opcional): Filtro de lenguaje de programación (ej., "Python", "JavaScript")
  • repo (opcional): Filtro de repositorio en formato "propietario/repositorio" (ej., "fastapi/fastapi")
  • path (opcional): Filtro de ruta para directorios específicos (ej., "src/")

Ejemplos:

# 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 respuesta

La herramienta devuelve JSON estructurado con:

{
  "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```"
        }
      ]
    }
  ]
}

🏗️ Arquitectura

  • Framework FastMCP: Construido sobre el framework FastMCP para facilitar el desarrollo de servidores MCP
  • Cliente HTTP asíncrono: Utiliza aiohttp para solicitudes API sin bloqueo
  • Formato de respuesta: Análisis y formato inteligente de las respuestas de grep.app
  • Manejo de errores: Manejo integral de errores para fallos de API, tiempos de espera y límites de velocidad
  • Flexibilidad de transporte: Soporta modos de transporte stdio y SSE basado en web

🛡️ Manejo de errores

El servidor maneja varias condiciones de error con elegancia:

  • Limitación de velocidad: Detección automática y mensajes de error fáciles de usar
  • Tiempos de espera de red: Tiempo de espera de 30 segundos con informe de errores adecuado
  • Fallos de API: Manejo elegante de problemas de la API de grep.app
  • Parámetros no válidos: Validación integral de parámetros con mensajes de error útiles

🧪 Pruebas

Ejecuta el conjunto de pruebas:

# Using uv
uv run pytest

# Using pytest directly
pytest tests/

La cobertura de pruebas incluye:

  • Inicialización del servidor MCP
  • Validación de parámetros de herramientas
  • Escenarios de manejo de errores
  • Formato de respuesta
  • Compatibilidad de plataformas

🤝 Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características: git checkout -b feature/amazing-feature
  3. Realiza tus cambios con pruebas
  4. Ejecuta el conjunto de pruebas: uv run pytest
  5. Formatea el código: uv run black . && uv run isort .
  6. Confirma los cambios: git commit -m 'Add amazing feature'
  7. Sube a la rama: git push origin feature/amazing-feature
  8. Abre una solicitud de extracción (Pull Request)

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

📞 Soporte

Hecho con ❤️ para la comunidad de desarrollo de IA