🔍 code-search-mcp

Servidor MCP de búsqueda semántica de código local sin demonios, impulsado por LanceDB y embeddings de ONNX en proceso.
Deja de buscar palabras exactas con grep. Dale a tu asistente de codificación de IA el poder de buscar en tu código por significado.

Funciona listo para usar con Claude Code, Gemini CLI, Antigravity (agy) y Cursor en macOS, Windows y Linux.

☕️ Imagina una aplicación de cafetería

Imagina que estás desarrollando el software de una cafetería de barrio con mucha actividad.

En tu código tienes un archivo que gestiona lo que ocurre cuando un cliente pide un latte extra de leche de avena y recibe un descuento matutino:

// Apply a 15% promotional deduction if the customer visits before 9 AM
export function calculateEarlyBirdReward(bill: OrderSummary): number {
  if (bill.orderHour < 9) {
    return bill.subtotal * 0.85;
  }
  return bill.subtotal;
}

Ahora imagina que abres tu asistente de codificación de IA (como Claude Code, Cursor o Gemini CLI) y preguntas:

"¿Dónde se calcula el descuento matutino de la bebida?"

Si tu herramienta se basa únicamente en la búsqueda de texto tradicional (como grep), buscará la palabra exacta "discount".

• ¿Encontró calculateEarlyBirdReward? No.

• ¿Por qué? Porque el código usaba las palabras promotional deduction y EarlyBirdReward, pero nunca la palabra exacta "discount".

Aquí es donde la búsqueda semántica lo cambia todo.

Related MCP server: smart-coding-mcp

🧠 Qué es la búsqueda semántica (en palabras sencillas)

La búsqueda tradicional busca letras y palabras exactas.

La búsqueda semántica busca el significado detrás de tus palabras.

Cómo funciona: el mapa del significado

1. Números en lugar de letras: Un modelo de IA toma un fragmento de texto (o código) y lo convierte en una lista de números llamada embedding (o vector).

2. Coordenadas en un mapa: Piensa en estos números como coordenadas GPS en un mapa gigante de conceptos humanos.

   • "discount" y "promotional deduction" acaban situándose justo al lado el uno del otro en el mapa.

   • "espresso shot" y "latte" se sitúan juntos.

   • "database migration" se sitúa lejos, al otro lado del mapa.

3. Encontrar los vecinos más cercanos: Cuando haces una pregunta en lenguaje natural, el motor de búsqueda convierte tu pregunta en coordenadas y simplemente encuentra los fragmentos de código que están más cerca de esas coordenadas en el mapa.

                  [ Map of Meaning ]

   ☕️ "morning drink discount"   📍 (Your Question)
              │ (Close match!)
              ▼
   🏷 "calculateEarlyBirdReward" 📍 (Your Code)
   
   ─────────────────────────────────────────────
   
   🗄 "sql database migration"   📍 (Far Away - Ignored)

🚀 Por qué la búsqueda semántica cambia las reglas del juego en la codificación con IA

Cuando los asistentes de codificación con IA trabajan en repositorios grandes con miles de archivos, no pueden leer todo el repositorio en cada prompt: es demasiado lento y consume demasiados tokens.

En lugar de eso, la IA necesita encontrar instantáneamente los 2 o 3 archivos relevantes.

En los proyectos reales, nuestras bases de código están llenas de contexto rico:

• Documentación Markdown (.md): Registros de decisiones de arquitectura, guías de API, documentación de incorporación.

• Comentarios de código: explican por qué existe una regla de negocio (por ejemplo, // Deduct beans from bean hopper inventory).

• Nombres de funciones y variables: patrones de nomenclatura que pueden diferir entre bibliotecas.

La búsqueda semántica conecta tus pensamientos en lenguaje natural directamente con esos documentos Markdown, comentarios y fragmentos de código, incluso cuando no recuerdas los nombres exactos de las funciones.

🛠️ Lo que construimos: code-search-mcp

Muchas herramientas de búsqueda semántica existentes para desarrolladores requieren configuraciones pesadas:

• Instalar Python 3, entornos virtuales y pip.

• Ejecutar un servidor de base de datos externo en segundo plano (como ChromaDB) escuchando en un puerto de red.

• Configurar demonios de inicio (LaunchAgents en Mac, Programador de tareas en Windows) que consumen batería al arrancar.

• Añadir ganchos complejos de Git (pre-commit) que pueden bloquear tu trabajo si el servidor de base de datos está sin conexión.

Queríamos algo completamente diferente: cero configuración. Cero demonios externos. Funciona en cualquier proyecto al instante.

Por eso construimos code-search-mcp — un servidor Model Context Protocol (MCP) independiente y multiplataforma para Node.js.

┌─────────────────────────────────────────────────────────────┐
│                       AI Client                             │
│       (Claude Code / Gemini CLI / Antigravity / Cursor)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (JSON-RPC over stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                      code-search-mcp                        │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
│  │   Scanner &      │  │  EmbeddingEngine │  │  Watcher  │  │
│  │ Layered Ignores  │  │  (all-MiniLM-L6) │  │(chokidar) │  │
│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
│           │                     │                  │        │
│           └───────────┬─────────┴──────────────────┘        │
│                       ▼                                     │
│              VectorStore (LanceDB)                          │
│        node_modules/.cache/code-search/                     │
└─────────────────────────────────────────────────────────────┘

⚙️ La tecnología que hay dentro

🔍 Cómo funciona por debajo

1. ¿Cómo saber cuando debe empezar a indexar?

Cuando tu asistente de IA se inicia (por ejemplo, cuando abres Claude Code, Antigravity o Gemini CLI), se conecta a code-search-mcp a través de la entrada/salida estándar (stdio).

• El servidor MCP se conecta inmediatamente en menos de 15 ms.

• Un trabajador en segundo plano comienza a escanear los archivos del proyecto sin bloquear tu sesión de chat.

2. ¿Puedes buscar antes de que termine la indexación? (El superpoder de la indexación en curso)

¡Sí! Si haces una pregunta 2 segundos después de abrir su proyecto, code-search-mcp no se bloquea ni se cuelga.

Busca en los archivos que ya se hayan indexado hasta el momento y muestra un encabezado de progreso en vivo:

⚠️ [Index status: INDEXING (35% complete - 2,100/6,000 files indexed)]
Results from currently indexed files:

### Match 1: src/drinks/espresso.ts (Lines 12-30) [Score: 54.2%]

3. Ten paciencia en la primera ejecución: ¡solo ocurre una vez! ⏳

En repositorios enormes con más de 5 000 archivos, el primer índice de escaneo tarda unos minutos, porque el modelo de IA local está generando embeddings para cada fragmento de código de tu máquina por primera vez.

Las buenas noticias:

• La primera ejecución se paga una sola vez: la base de datos de vectores resultante y se guarda permanentemente en node_modules/.cache/code-search/lancedb/.

• Arranque instantáneo en ejecuciones posteriores: En cada sesión nueva o reinicio del editor, el servidor se conecta en menos de 15 ms para reindexar.

• Actualizaciones en vivo incrementales: Mientras escribes código durante el día, el observador en vivo actualiza solo el archivo que cambiaste en ~150 ms al guardarlo.

• No tienes que esperar nada: puedes empezar a hacer preguntas y buscar de inmediato; el asistente buscará lo que ya esté indexado por detrás mientras tanto.

4. ¿Dónde se guarda el índice?

Por defecto, la base de datos se guarda en: 📁 node_modules/.cache/code-search/lancedb/

¿Por qué, node_modules/.cache?

• node_modules ya está ignorado por Git en el 100 % de los proyectos.

• Cero ruido en Git: nunca aparecen carpetas sin rastrear ni diferencias no deseadas en tu repositorio.

• (Si el proyecto no tiene node_modules, se reutiliza en .code-search/).

5. ¿Qué ocurre cuando cambias de rama de Git? 🔀

Cuando haces git checkout, git switch o git pull:

1. Detección por repositución del observador: Git actualiza archivos en disco y el observador de archivos incorporados chokidar detecta en tiempo real los archivos agregados, modificados o eliminados.

2. Re-escaneo conel refuerzo rápido: solo vuelve a indexar los archivos específicos que cambiaron entre las dos ramas (tardas 1–2 segundos en vez de minutos).

3. Poda automática: Los archivos modificados o fragmentos de código antiguos de la rama anterior se eliminan automáticamente de LanceDB.

4. Sincronización manual: si quieres forzar un reconstrucción completa limpia después de una fusión masiva, basta con que le digas a tu asistente: "Ejecuta with con force: true".

⚙️ Cómo ajustar los ajustes e ignorar más archivos

Por defecto, code-search-mcp ignora automáticamente binarios (.png, .mp4, .zip), salidas de build (dist/, build/), archivos de bloqueo y cualquier archivo de más de 500 KB, a la vez que respeta tu .gitignore existente.

Si quieres personal la configuración o ignorar archivos extra para tu proyecto, tienes dos opciones:

Opción 1: Crea un archivo .codesearchignore (copa y sencillo)

Crea un archivo .codesearchignore en la raíz de tu proyecto con la sintaxis estándar de gitignore:

# Ignore mock data and test fixtures
tests/fixtures/**
src/mocks/**

# Ignore auto-generated files
src/models/*.generated.ts
locales/**

Opción 2: Crea un archivo .codesearchrc.json (configuración avanzada)

Crea un archivo .codesearchrc.json en la raíz de tu proyecto para controlar el comportamiento indexación, el procesamiento por lotes y los límites de tamaño de archivo:

{
  "maxFileSizeKb": 300,
  "batchSize": 50,
  "customExcludes": [
    "legacy_vendor/**",
    "docs/archive/**"
  ],
  "supportedExtensions": [
    ".ts", ".tsx", ".js", ".vue", ".py", ".md", ".json"
  ]
}

📦 Cómo instalar la herramienta

Puedes instalar y ejecutar la herramienta con cualquiera de estos métodos:

Paso 1: elige tu método de instalación

Método A: Desde GitHub con npx (sin instalación: no necesitas publicar en npm)

Cualquier cliente de IA puede ejecutarlo bajo demanda directamente desde su repositorio de GitHub:

npx -y github:your-username/code-search-mcp

(Node descarga automáticamente el repo, compila el bundle y ejecuta el servidor MCP).

Método B: Desde el registro npm (una vez publicado)

Si publicastes el paquete en npm:

npx -y code-search-mcp
# or global install:
npm install -g code-search-mcp

Método C: Desarrollo local / enlazado (el arranque local más rápido)

Si lo ejecutas directamente desde tu directorio local:

cd /path/to/code-search-mcp
npm install
npm run build
npm link

Ahora code-search-mcp queda registrado como un comando global en tu sistema

Paso 2: conéctal a tu cliente de IA

1. Claude Code

# If running via GitHub:
claude mcp add code-search -s user -- npx -y github:your-username/code-search-mcp

# If running locally (linked):
claude mcp add code-search -s user -- code-search-mcp

2. Antigravity CLI (agy)

Ejecuta este comando de una sola línea en tu terminal:

mkdir -p ~/.gemini/config/plugins/code-search && cat << 'EOF' > ~/.gemini/config/plugins/code-search/plugin.json
{ "name": "code-search" }
EOF
cat << 'EOF' > ~/.gemini/config/plugins/code-search/mcp_config.json
{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"]
    }
  }
}
EOF

3. Gemini CLI

Añade ~/.gemini/settings.json:

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"],
      "trust": true
    }
  }
}

4. Cursor / Claude Desktop

Agrégalo a .cursor/mcp.json:

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp", "--path", "${workspaceFolder}"]
    }
  }
}

🤖 Guía para el agente de IA y referencia de herramientas

Si eres un asistente de IA (Claude Code, Gemini CLI, Cursor, Antigravity o Windsurf) que está leyendo este repositorio, esta es tu guía de inicio rápido para usar las herramientas MCP que proporciona code-search-mcp:

🛠️ Herramientas MCP disponibles

🧭 Matriz de decisión de herramientas: cuándo usar cada herramienta

                       ┌───────────────────────────────────────────────┐
                       │ What are you looking for in the codebase?     │
                       └───────────────────────┬───────────────────────┘
                                               │
           ┌───────────────────────────────────┼───────────────────────────────────┐
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ Concept / Feature /     │         │ Known Symbol / Callers  │         │ Exact Literal String /  │
│ Business Logic Intent   │         │ & Blast Radius Analysis │         │ Error Code / CSS Class  │
│ (Natural Language)      │         │ (Exact identifier)      │         │ (Exact text match)      │
└──────────┬──────────────┘         └──────────┬──────────────┘         └──────────┬──────────────┘
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ 🔍 USE: code_search     │         │ 🌳 USE: codegraph       │         │ 🔎 USE: grep_search     │
│ • "where is payment..." │         │ • codegraph_explore     │         │ • "ERR_INVALID_AUTH"    │
│ • "tax calculation..."  │         │ • callers / callees     │         │ • ".btn-primary-blue"   │
└─────────────────────────┘         └─────────────────────────┘         └─────────────────────────┘

💡 Consejos profesionales para agentes de IA

1. Usa codeOnly: true para lógica de implementación pura: si quieres encontrar fórmulas de cálculo en TypeScript/JavaScript puro y excluir documentación Markdown o guías de habilidades, pasa siempre codeOnly: true.

2. Usa pathFilter para acotar subsistemas: si el usuario pregunta "¿cómo funciona el proceso de pago en el módulo de facturación?", pasa pathFilter: "src/billing".

3. Usa los números de línea para ediciones directas de código: los fragmentos de código se devuelven con números de línea basados en 1 (14: export function calculateTotal()). Puedes pasar directamente esos rangos de línea a replace_file_content o a view_file sin necesidad de suposiciones.

4. Tolerante a erratas: puedes pasar palabras naturales directamente; el motor maneja automáticamente los plurales (stemming) y las erratas (corrección Levenshtein) en <1 ms.

🤝 El mejor dúo de IA: por qué instalar a la vez code-search y codegraph

Los asistentes de codificación con IA funcionan mejor cuando disponen de dos herramientas complementarias: búsquedas semánticas (code-search-mcp) y grafos de código AST (codegraph).

                   ┌─────────────────────────────────────────────────────────┐
                   │  User: "Where is subscription discount handled?"        │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 1. SEMANTIC SEARCH (code_search)                        │
                   │ • Understands intent, concepts, and natural language     │
                   │ • Finds: subscription-billing.engine.ts (via JSDoc)     │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 2. AST CODE GRAPH (codegraph_explore)                   │
                   │ • Understands syntax trees, callers, and blast radius   │
                   │ • Traces: callers into legacy LegacyOrderProcessor.js   │
                   │ • Discovers: unit tests (subscription-billing.spec.ts)  │
                   └─────────────────────────────────────────────────────────┘

Por qué una sola herramienta no es suficiente:

Caso real: motor moderno vs monolito heredado

En una base de código empresarial real:

1. El motor moderno (subscription-billing.engine.ts) tiene nombres explícitos (calculateSubscriptionDiscount) y una documentación JSDoc detallada. code_search lo encuentra con una coincidencia de >55% en milisegundos.

2. El núcleo negativo () es un archivo de 2,000 líneas que usa términos antiguos (getDiscountedTotal, applyOldDeduction) o erratas. Solo la búsqueda semántica podría obtener una puntuación más baja.

3. La sinergia: en cuanto code_search da con subscription-billing.engine.ts, codegraph_explore rastrea al instante cada llamador directo hasta LegacyOrderProcessor.js y mappa el radio de impacto a través de las pruebas unitarias que lo cubren, ¡sin hacer conjeturas!

Configuración doble recomendada

Añade ambas herramientas a tu configuración de MCP:

{
  "mcpServers": {
    "code-search": {
      "command": "node",
      "args": ["/path/to/code-search-mcp/dist/bin/cli.js"]
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }
  }
}

📋 Reglas de asistente recomendadas

Para garantizar que tu asistente de IA seleccione automáticamente code_search y codegraph, añade esta regla al archivo de instrucciones de tu proyecto (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md o .cursorrules):

## Code Navigation & Search

1. **CodeGraph (`codegraph_explore`)**: Call FIRST when exploring known symbols, tracking call paths, finding usages, or analyzing blast radius (callers + covering tests).
2. **Semantic Search (`code_search`)**: Call FIRST when looking for features, domain behaviors, or business logic described in natural language (e.g. "where is discount calculated", "checkout suggestions formatted").

🧪 Cómo verificar que funciona

Una vez instalado, puedes comprobar que code-search-mcp funciona con tres comprobaciones rápidas:

Comprobación 1: pide el estado a tu asistente de IA

En cualquier conversación con Claude Code, Cursor o Gemini CLI, pregunta:

"Comprueba el estado de code_search_status"

Salida esperada:

Index Status: READY (or INDEXING)
Progress: 100%
Files: 6,070 / 6,070 indexed
Chunks: 8,204 code chunks in LanceDB

Comprobación 2: prueba una búsqueda de código en lenguaje natural

Pregunta a tu asistente:

"Usa code_search para saber cómo se manejan las reglas de descuento o las recompensas de clientes"

Salida esperada:

### Match 1: src/rewards/early-bird.ts (Lines 1-18) [Score: 56.4%]

El asistente devuelve al instante los fragmentos de código relevantes con números de línea exactos y puntuaciones de similitud.

Comprobación 3: probar la vigilancia en vivo de archivos

1. Crea un nuevo archivo de prueba en tu proyecto (por ejemplo, src/drinks/secret-recipe.ts) con un comentario único:

   // Caramel macchiato secret syrup blend formula
   export const caramelBlend = 42;

2. Guarda el archivo.

3. Pregunta de inmediato a tu asistente de IA:

   "Localiza la fórmula secreta de la mezcla del jarabe con code_search"

4. El archivo se encontrará y se devolverá en menos de 1 segundo: no se necesitan reconstrucciones manuales ni reinicios.

Comprobación 4: ejecutar la suite de pruebas automatizada (opcional)

Si desarrollas desde el código fuente, ejecuta:

npm test

Todas las 31 pruebas unitarias y de integración se ejecutarán y superarán, incluida la verificación del protocolo MCP handshake, la generación de vectores ONNX, el almacenamiento LanceDB, el ciclo de vida del watcher, la generación de vectores morfológicos y la corrección de erratas.

🛠️ Problemas reales con los que nos enfretamos y cómo los corregimos (en palabras)

Crear un buscador útil tanto para humanos como para agentes de IA de programación estuvo lleno de retos. Esto es lo que nos encontraron y cómo resolvimos cada uno:

1. 🔤 La trampa de los plurales y terminaciones ("marks" vs "Marker")

• El problema: si alguien escribe con toda naturalidad "cómo usachart iq un número o "marks" en el gráfico", usa el plural "marks". Pero en el código hay una clase llamada CIQ.Marker o markersSample. Una consulta de base de datos estándar (LIKE '%marks%') no encuentra Marker por la "s" extra.

• Cómo lo corregimos: teníamos a eliminar las terminaciones ("suffixces") . Automáticamente elimina los sufijos comunes (-s, -ing, -ed, -tion, -ers). Al buscar "marks", se busca la raíz "mark" y encuentra en el instante CIQ.Marker, markAxis y markersSample con estrminuto overhad de 0 ms.

2. ✍️ Erratas ("calcualte mrgin shortfall")

• El problema: cuando las personas teclean rápido en el chat cometen erratas (por ejemplo, escribir mrginal en lugar de margin, o calcular en lugar de calculate). Si la palabra contiene una errata, la búsqueda por palabra clave y fijada al 100% sería que.

• Cómo lo corregimos: hemos creado un V o código Léxico y corrector Levenshtein en memoria. Mientras se indexan los archivos, el elbows recopila un dicticionario con todos los nombres reales de variables, de clases y términos de tu repositorio. Cuando envías una consulta con una errata, la corrección se realiza directamente con el diccionario en < 1 ms, justo antes de la búsqueda.

3. 🤖 Bloques de código listos para agentes de IA (con números de línea)

• El problema: la salida de búsqueda daba los números de línea en la cabecera (Líneas 10-50), pero el bloque de código en sí no los usaba. Cuando un agente de codificación con IA (Claude Code, Gemini CLI, Antigravity) quería editar o citar una línea, tenía que contarlas manualmente o intentar inferir la offset.

• Cómo lo corregimos: todas las líneas dentro de los fragmentos de código de resultados se prefijan ahora automáticamente con el real y basado en 1 (10: export class ...). Así, los agentes de IA pueden pasar números de línea exactos a las herramientas de edición siempre que ese intente evitando más lecturas de archivo.

4. 📚 Ruido de documentación en las búsquedas de código puro

• El problema: al buscar conceptos amplios como "cómo formatear moneda", archivos grandes de habilidades (skill) en Markdown y guías de arquitectura a veces se colocaban por encima que las verdaderas utilidades .ts, porque la documentación contiene demasiado inglés conversacional.

• Cómo lo corregimos:

  1. Agregamos filtros de búsqueda: codeOnly: true (ignora Markdown/documentación), pathFilter: "src/...", and language.

  2. Reducimos el peso de los archivos JSON estáticos, para que la lógica TypeScript/JavaScript siempre aparezca primero.

5. 🔁 Exceso de resultados (demasiados fragmentos de un gran archivo)

• El problema: al buscar un asunto común, un archivo de 3.000 líneas con varias coincidencias ocupaba los 10 resultados que se mostraban, ocultando las coincidencias de archivos auxiliares más pequeños y limpios.

• Cómo lo corregimos: añadimos diversidad de resultados por archivo: el motor devuelve como máximo 2 fragmentos con mayor puntuación por cada archivo, para que tengas una variedad útil de resultados dentro de tu base de código.

6. ⚡ Conflictos de bloqueo de base de datos al guardar rápido

• El problema: al cambiar de rama o guardar varios archivos en una sucesión rápida, varias escrituras sobre LanceDB eran capaces de desencadenar conflictos de versión concurrente.

• Cómo lo corregimos: un pool de escrituras asíncronas con retraso exponencial. Si se da un conflicto de escritura, la cola espera durante algunos milisegundos y reintienta de forma segura, sin derribar el servidor.

💡 Resumen

Combinando las incrustaciones ONNX en proceso con LanceDB embebido, el enriquecimiento inteligente de tokens y el Model Context Protocol (MCP), hemos eliminado el trabajo pesado de la búsqueda semántica local:

• ✅ Sin demonios en segundo fondo en tu portátil.

• ✅ Sin dependencias de Python/ChromaDB.

• ✅ Sin ruido de Git (se almacena en node_modules/.cache).

• ✅ Gestiona automáticamente errores y variantes de palabras en <1 ms.

• ✅ Buscas el significado, conectando tus preguntas en lenguaje natural al código exacto y a la documentación Markdown que realmente quieres.

¡Feliz código! ☕️🚀