CodeSeeker

CodeSeeker

Búsqueda y transformación avanzada de código para asistentes de IA

Un servidor integral del Protocolo de Contexto de Modelo (MCP) que combina las filosofías de ugrep y ast-grep para ofrecer capacidades inteligentes de búsqueda y reemplazo para flujos de trabajo de desarrollo modernos.

🚀 Características

CodeSeeker proporciona a los asistentes de IA capacidades completas de búsqueda Y reemplazo:

🔍 Herramientas de búsqueda principales

• Búsqueda básica: Coincidencia de patrones estándar con filtrado por tipo de archivo y contexto
• Búsqueda booleana: Búsqueda estilo Google con operadores AND, OR, NOT
• Búsqueda difusa: Coincidencia aproximada de patrones que permite errores de caracteres
• Búsqueda en archivos comprimidos: Búsqueda dentro de archivos y archivos comprimidos (zip, tar, 7z, etc.)
• Búsqueda interactiva: Inicia la interfaz TUI de ugrep para búsqueda en tiempo real
• Búsqueda de estructura de código: Encuentra funciones, clases, métodos, importaciones y variables

🔧 Herramientas de búsqueda y reemplazo

• Buscar y reemplazar: Búsqueda y reemplazo seguros con vista previa en modo simulación y copias de seguridad automáticas
• Reemplazo masivo: Múltiples operaciones de búsqueda/reemplazo en un solo comando
• Refactorización de código: Refactorización consciente del lenguaje para estructuras de código en múltiples lenguajes

⚡ Características avanzadas

• Salida JSON: Resultados estructurados perfectos para el procesamiento de IA
• Filtrado por tipo de archivo: Busca lenguajes de programación específicos o tipos de documentos
• Líneas de contexto: Muestra líneas circundantes para una mejor comprensión
• Estadísticas de búsqueda: Obtén métricas detalladas sobre las operaciones de búsqueda
• Soporte de archivos comprimidos: Busca en archivos comprimidos anidados sin extracción
• Seguridad primero: Modo simulación por defecto con creación automática de copias de seguridad
• Conciencia del lenguaje: Patrones inteligentes para JavaScript, TypeScript, Python, Java, C++

📋 Requisitos previos

1. Instalar ugrep

Ubuntu/Debian:

sudo apt-get install ugrep

macOS (Homebrew):

brew install ugrep

Windows (Chocolatey):

choco install ugrep

Desde el código fuente:

git clone https://github.com/Genivia/ugrep.git
cd ugrep
./configure
make
sudo make install

Verificar la instalación:

ugrep --version
# Should show version 7.4 or higher

2. Instalar Node.js

Asegúrate de tener Node.js 18+ instalado:

node --version
# Should show v18.0.0 or higher

🛠️ Instalación

Clonar y compilar

git clone https://github.com/yourusername/codeseeker-mcp.git
cd codeseeker-mcp
npm install
npm run build

Prueba rápida

npm test
# Should show all tests passing

⚙️ Configuración

Integración con Claude Desktop

Añade a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "codeseeker": {
      "command": "node",
      "args": ["/absolute/path/to/codeseeker-mcp/build/index.js"]
    }
  }
}

Nota: Reemplaza /absolute/path/to/codeseeker-mcp con la ruta real de tu instalación.

📖 Ejemplos de uso

Búsqueda básica

Search for "function" in JavaScript files:
- Pattern: function
- File Types: js,ts
- Path: ./src
- Case Sensitive: false

Búsqueda booleana

Find TODO items that are urgent but not marked as later:
- Query: TODO AND urgent -NOT later
- File Types: cpp,h,js,py

Búsqueda difusa

Find "function" with up to 2 character errors (matches "functoin", "functio", etc.):
- Pattern: function  
- Max Errors: 2
- File Types: js,ts,py

Buscar y reemplazar

Replace old function names with new ones (safe preview first):
- Pattern: oldFunctionName
- Replacement: newFunctionName
- File Types: js,ts
- Dry Run: true (preview changes)
- Backup: true (create backups)

Reemplazo masivo

Multiple replacements in one operation:
- Replace "var " with "const "
- Replace "== " with "=== " 
- File Types: js,ts
- Dry Run: true

Refactorización de código

Refactor function names across a codebase:
- Structure Type: function
- Old Pattern: getUserData
- New Pattern: fetchUserData
- Language: typescript
- Dry Run: true

🔧 Referencia de herramientas

Herramientas de búsqueda

basic_search

Búsqueda de patrones estándar con opciones de filtrado.

Parámetros:

• pattern (obligatorio): Patrón de búsqueda o expresión regular
• path (opcional): Directorio a buscar (por defecto: directorio actual)
• caseSensitive (opcional): Búsqueda sensible a mayúsculas (por defecto: false)
• fileTypes (opcional): Tipos de archivo separados por comas (p. ej., "js,py,cpp")
• excludeTypes (opcional): Tipos de archivo a excluir
• contextLines (opcional): Líneas de contexto alrededor de las coincidencias
• maxResults (opcional): Máximo de resultados (por defecto: 100)

boolean_search

Búsqueda estilo Google con operadores booleanos.

Parámetros:

• query (obligatorio): Consulta booleana (admite AND, OR, NOT, paréntesis)
• path, fileTypes, maxResults: Igual que la búsqueda básica

Consultas de ejemplo:

• "error AND (critical OR fatal)"
• "TODO AND urgent -NOT completed"
• "function OR method -NOT test"

fuzzy_search

Coincidencia aproximada de patrones.

Parámetros:

• pattern (obligatorio): Patrón a buscar
• maxErrors (opcional): Errores de caracteres permitidos 1-9 (por defecto: 2)
• path, fileTypes, maxResults: Igual que la búsqueda básica

archive_search

Busca en archivos comprimidos y archivos.

Parámetros:

• pattern (obligatorio): Patrón de búsqueda
• path, maxResults: Igual que la búsqueda básica
• archiveTypes (opcional): Tipos de archivo comprimido a buscar

code_structure_search

Encuentra estructuras de código específicas.

Parámetros:

• structureType (obligatorio): Tipo a buscar (función, clase, método, importación, variable)
• name (opcional): Nombre específico a buscar
• language (obligatorio): Lenguaje de programación (js, ts, py, java, cpp)
• path, maxResults: Igual que la búsqueda básica

interactive_search

Inicia el modo TUI interactivo.

Parámetros:

• initialPattern (opcional): Patrón de búsqueda inicial
• path (opcional): Directorio inicial

Herramientas de reemplazo

search_and_replace

Búsqueda y reemplazo seguros con vista previa.

Parámetros:

• pattern (obligatorio): Patrón de búsqueda o expresión regular
• replacement (obligatorio): Texto de reemplazo (admite grupos de captura $1, $2)
• path (opcional): Directorio a procesar (por defecto: directorio actual)
• fileTypes (opcional): Tipos de archivo a incluir
• caseSensitive (opcional): Búsqueda sensible a mayúsculas (por defecto: false)
• dryRun (opcional): Modo vista previa (por defecto: true)
• maxFiles (opcional): Máximo de archivos a procesar (por defecto: 50)
• backup (opcional): Crear copias de seguridad (por defecto: true)

bulk_replace

Múltiples operaciones de búsqueda/reemplazo.

Parámetros:

• replacements (obligatorio): Matriz de objetos {pattern, replacement, description}
• path, fileTypes, caseSensitive, dryRun, backup: Igual que search_and_replace

code_refactor

Refactorización de código consciente del lenguaje.

Parámetros:

• structureType (obligatorio): Tipo de estructura de código (función, clase, variable, importación)
• oldPattern (obligatorio): Patrón a encontrar
• newPattern (obligatorio): Patrón de reemplazo
• language (obligatorio): Lenguaje de programación (js, ts, py, java, cpp)
• path, dryRun, backup: Igual que search_and_replace

Herramientas de utilidad

list_file_types

Obtén todos los tipos de archivo admitidos para el filtrado.

get_search_stats

Obtén estadísticas detalladas de búsqueda y métricas de rendimiento.

🏗️ Desarrollo

Estructura del proyecto

codeseeker-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Node.js dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── test.js              # Test suite
├── README.md            # This file
└── SETUP.md             # Quick setup guide

Compilación

npm run build           # Compile TypeScript
npm run dev            # Watch mode for development
npm run inspector      # Debug with MCP inspector

Pruebas del servidor

# Test basic functionality
npm test

# Use MCP inspector for interactive testing
npm run inspector

# Test with Claude Desktop
# (Add to config and restart Claude Desktop)

🚨 Características de seguridad

Modo simulación

Todas las operaciones de reemplazo usan por defecto el modo simulación por seguridad:

• Previsualiza los cambios antes de aplicarlos
• Ve exactamente lo que se modificará
• Sin sobrescrituras accidentales

Copias de seguridad automáticas

Al realizar cambios:

• Los archivos de copia de seguridad se crean automáticamente con marcas de tiempo
• Los archivos originales se conservan
• Reversión fácil si es necesario

Manejo de errores

• Mensajes de error completos
• Manejo elegante de fallos
• Verificación de permisos de archivos

🐛 Solución de problemas

Problemas comunes

"ugrep no encontrado"

• Asegúrate de que ugrep esté instalado y en tu PATH
• Ejecuta ugrep --version para verificar la instalación

"Permiso denegado"

• Asegúrate de que el archivo build/index.js sea ejecutable
• Ejecuta chmod +x build/index.js (en sistemas Unix)

"Errores de módulo no encontrado"

• Ejecuta npm install para instalar las dependencias
• Asegúrate de usar Node.js 18 o superior

"Claude Desktop no muestra las herramientas"

• Verifica que la ruta del archivo de configuración sea correcta
• Reinicia Claude Desktop después de los cambios de configuración
• Revisa los registros de Claude Desktop para errores de conexión

"No se encontraron archivos para procesar"

• Comprueba que la ruta exista y contenga archivos coincidentes
• Verifica que los filtros de tipo de archivo sean correctos
• Asegúrate de que ugrep pueda acceder a los directorios especificados

⚡ Notas de rendimiento

• ugrep es extremadamente rápido, a menudo supera a otras herramientas grep
• La salida JSON añade una sobrecarga mínima
• La búsqueda en archivos comprimidos puede ser más lenta según la compresión
• Los conjuntos de resultados grandes están limitados por el parámetro maxResults
• Las operaciones de reemplazo procesan archivos de manera eficiente con transmisión
• El modo interactivo requiere una terminal y no puede ejecutarse a través de MCP

🤝 Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Confirma tus cambios (git commit -m 'Add some amazing feature')
4. Sube la rama (git push origin feature/amazing-feature)
5. Abre una solicitud de extracción

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🔗 Proyectos relacionados

• ugrep - El reemplazo de grep ultrarrápido
• ast-grep - Herramienta de búsqueda y reescritura de código basada en AST
• Model Context Protocol - Estándar abierto para conexiones de datos con IA
• Claude Desktop - Asistente de IA con soporte MCP

📊 Resumen de herramientas

Herramienta	Propósito	Entrada	Salida
basic_search	Búsqueda de texto estándar	Patrón + filtros	Coincidencias con contexto
boolean_search	Consultas de búsqueda lógica	Expresión booleana	Resultados filtrados
fuzzy_search	Coincidencia aproximada	Patrón + tolerancia a errores	Coincidencias difusas
archive_search	Buscar archivos comprimidos	Patrón + tipos de archivo comprimido	Contenido de archivos comprimidos
code_structure_search	Encontrar elementos de código	Tipo de estructura + lenguaje	Definiciones de código
search_and_replace	Buscar y reemplazar texto	Patrón + reemplazo	Vista previa/cambios
bulk_replace	Múltiples reemplazos	Matriz de operaciones	Resultados por lotes
code_refactor	Refactorizar estructuras de código	Patrones antiguos/nuevos + lenguaje	Código refactorizado
interactive_search	Iniciar modo TUI	Patrón inicial	Comando a ejecutar
list_file_types	Mostrar tipos admitidos	Ninguno	Extensiones disponibles
get_search_stats	Métricas de búsqueda	Parámetros de búsqueda	Estadísticas de rendimiento

---

CodeSeeker: inteligencia en cada búsqueda, precisión en cada cambio.

Total de herramientas disponibles: 11 (8 de búsqueda + 3 de reemplazo)