Grep App

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

Documentación

Servidor MCP de Grep App

Un servidor de Model Context Protocol (MCP) que proporciona potentes capacidades de búsqueda de código en repositorios públicos de GitHub mediante la API de grep.app. Perfecto para descubrir código, aprender de proyectos de código abierto y encontrar ejemplos de implementación.

🚀 Características

🔍 Búsqueda de código avanzada: Busca en millones de repositorios públicos de GitHub
📁 Recuperación de archivos: Obtén archivos específicos o lotes de archivos de GitHub
🎯 Filtrado flexible: Filtra por idioma, repositorio, ruta de archivo y más
📊 Múltiples formatos de salida: JSON, listas numeradas o texto formateado
⚡ Operaciones por lotes: Recupera múltiples archivos de forma eficiente en paralelo
🔄 Caché de resultados: Almacena en caché los resultados de búsqueda para una recuperación rápida de archivos
📝 Registro integral: Registro integrado con rotación diaria

🛠️ Instalación y configuración

Requisitos previos

Node.js 18+
npm o yarn
CLI de Claude Code

Inicio rápido

Clona o descarga este repositorio

git clone https://github.com/ai-tools-all/grep_app_mcp.git
cd grep_app_mcp

Instala las dependencias
```
npm install
```
Compila el proyecto
```
npm run build
```

Prueba el servidor

# HTTP mode (recommended for development)
./run.sh http dev

# or STDIO mode
./run.sh stdio dev

🔧 Añadir a Claude Code

Método 1: Usar la configuración de MCP

Añade este servidor a tu configuración de MCP de Claude Code:

{
  "mcpServers": {
    "grep_app": {
      "command": "node",
      "args": ["/path/to/grep_app_mcp/dist/server-stdio.js"],
      "env": {}
    }
  }
}

Método 2: Usar transporte HTTP

Para el modo HTTP, añade a tu configuración:

{
  "mcpServers": {
    "grep_app": {
      "url": "http://localhost:8603/mcp"
    }
  }
}

Luego inicia el servidor:

./run.sh http prod

📖 Uso de run.sh

El script run.sh proporciona formas convenientes de iniciar el servidor:

Uso básico

./run.sh [mode] [environment]

Modos

http - Servidor HTTP con soporte de streaming (predeterminado)
stdio - Servidor STDIO para integración directa con MCP

Entornos

dev - Modo de desarrollo con recarga en caliente (predeterminado)
prod - Modo de producción (requiere paso de compilación)

Ejemplos

# Development (default) - HTTP server with hot reload
./run.sh

# Development - HTTP server  
./run.sh http dev

# Production - HTTP server
./run.sh http prod

# Development - STDIO server
./run.sh stdio dev

# Production - STDIO server  
./run.sh stdio prod

# Show help
./run.sh help

Endpoints HTTP (cuando se usa el modo HTTP)

Streaming HTTP: http://localhost:8603/mcp
Eventos enviados por el servidor: http://localhost:8603/sse

🔨 Herramientas disponibles

1. searchCode

Busca código en repositorios públicos de GitHub.

Parámetros:

query (obligatorio) - Cadena de consulta de búsqueda
jsonOutput - Devuelve formato JSON (predeterminado: false)
numberedOutput - Devuelve formato de lista numerada (predeterminado: false)
caseSensitive - Búsqueda sensible a mayúsculas y minúsculas
useRegex - Trata la consulta como patrón regex
wholeWords - Buscar solo palabras completas
repoFilter - Filtra por patrón de nombre de repositorio
pathFilter - Filtra por patrón de ruta de archivo
langFilter - Filtra por lenguaje(s) de programación

Ejemplo:

{
  "query": "async function fetchData",
  "langFilter": "TypeScript,JavaScript",
  "numberedOutput": true
}

2. github_file

Obtiene un único archivo de un repositorio de GitHub.

Parámetros:

owner (obligatorio) - Propietario del repositorio
repo (obligatorio) - Nombre del repositorio
path (obligatorio) - Ruta del archivo
ref (opcional) - Referencia de rama/commit/etiqueta

Ejemplo:

{
  "owner": "microsoft",
  "repo": "vscode", 
  "path": "src/vs/editor/editor.api.ts"
}

3. github_batch_files

Obtiene múltiples archivos de repositorios de GitHub en paralelo.

Parámetros:

files (obligatorio) - Matriz de objetos de archivo con propietario, repositorio, ruta y ref opcional

Ejemplo:

{
  "files": [
    {"owner": "facebook", "repo": "react", "path": "packages/react/index.js"},
    {"owner": "microsoft", "repo": "TypeScript", "path": "src/compiler/types.ts"}
  ]
}

4. batch_retrieve_files

Recupera archivos de resultados de búsqueda previamente almacenados en caché.

Parámetros:

query (obligatorio) - Consulta de búsqueda original
resultNumbers (opcional) - Matriz de índices de resultados a recuperar

Ejemplo:

{
  "query": "tower_governor",
  "resultNumbers": [1, 2, 3]
}

🎯 Flujos de trabajo comunes

1. Descubrimiento de código

# Search for React hooks examples
searchCode("useEffect cleanup", langFilter: "JavaScript,TypeScript")

# Retrieve specific files from results  
batch_retrieve_files(query: "useEffect cleanup", resultNumbers: [1, 3, 5])

2. Aprendizaje de patrones

# Find authentication implementations
searchCode("JWT authentication middleware", repoFilter: "*express*")

# Get specific implementation details
github_file(owner: "auth0", repo: "express-jwt", path: "lib/index.js")

3. Investigación de API

# Discover API patterns
searchCode("GraphQL resolver", pathFilter: "*/resolvers/*")

# Compare multiple implementations
github_batch_files([
  {owner: "apollographql", repo: "apollo-server", path: "packages/apollo-server-core/src/resolvers.ts"},
  {owner: "graphql", repo: "graphql-js", path: "src/execution/execute.js"}
])

📋 Desarrollo

Scripts disponibles

npm run build - Compila TypeScript a JavaScript
npm run start - Inicia el servidor HTTP de producción
npm run start-stdio - Inicia el servidor STDIO de producción
npm run dev - Inicia el servidor HTTP de desarrollo con recarga en caliente
npm run dev-stdio - Inicia el servidor STDIO de desarrollo con recarga en caliente
npm run test-client - Ejecuta el cliente de prueba

Estructura del proyecto

src/
├── core/           # Core utilities (logger, types)
├── tools/          # MCP tool implementations
├── server.ts       # HTTP server entry point
└── server-stdio.ts # STDIO server entry point

📝 Registro

El servidor incluye un registro integral con rotación diaria:

Ubicación: directorio logs/
Rotación: Diaria con nombres de archivo basados en fecha
Niveles: error, warn, info, debug
Formato: JSON con marcas de tiempo

🤝 Contribuciones

Haz un fork del repositorio
Crea una rama de características
Realiza tus cambios
Añade pruebas si corresponde
Envía una solicitud de extracción (pull request)

📄 Licencia

Licencia ISC: consulta package.json para más detalles

🔗 Relacionados

grep.app - El servicio de búsqueda que impulsa esta herramienta
Model Context Protocol - Especificación de MCP
Claude Code - CLI oficial de Claude