Introducción a Claude Context: Haz que la IA entienda de verdad todo tu repositorio de código

Claude Context es un complemento de código abierto para MCP (Model Context Protocol) desarrollado por el proveedor de bases de datos vectoriales Zilliz. Su enfoque principal es muy claro: inyectar al asistente de programación con IA la capacidad de comprender semánticamente todo tu repositorio de código.

En los flujos de trabajo tradicionales, cuando quieres que la IA te ayude a entender un repositorio desconocido, tienes que copiar manualmente las rutas de los archivos, describir la estructura del proyecto y explicar las relaciones entre módulos. Pero esto debería ser algo que la IA haga por sí misma. Con Claude Context, gracias a la búsqueda semántica, la IA puede consultar directamente funciones, clases y estructuras de datos dentro del repositorio, sin depender de que tú inyectes manualmente el contexto.

Este proyecto está alojado en GitHub en zilliztech/claude-context y utiliza la licencia MIT; el código es completamente open source.

---

Dificultad / Duración / Beneficios

Principiante | ~20 minutos | Aprenderás a otorgar, con solo 2 comandos, a cualquier herramienta de programación la capacidad de entender semánticamente millones de líneas de código, reduciendo además aproximadamente un 40% del consumo de tokens.

---

Público objetivo

• Desarrolladores que usan a diario herramientas de programación con IA como Claude Code, Cursor, Windsurf, Cline, etc.
• Personas con nociones sobre RAG (Generación Aumentada por Recuperación) y búsqueda vectorial que quieran llevarlo a la práctica en profundidad
• Equipos que buscan reducir costes de tokens y mejorar la precisión de las respuestas de la IA

---

Dependencias clave y requisitos del entorno

Requisitos del sistema

• Node.js >= 20.0.0 y < 24.0.0
• Sistema operativo: macOS, Windows o Linux

Dependencias de servicio

• Zilliz Cloud (con el uso gratuito es suficiente para uso personal): proporciona el backend de base de datos vectorial
• OpenAI API Key: se utiliza para generar vectores mediante el modelo de embeddings (también puedes sustituirlo por otros proveedores que admitan embeddings)

---

Estructura completa del árbol del proyecto

Claude Context es un paquete puro de npm; no necesitas clonar ni compilar ningún código local. Tras la instalación, gestionará su propia estructura de almacenamiento:

~/.claude/
└── plugins/
    └── claude-context/          # Directorio del complemento MCP
        └── [archivos de datos indexados]        # Instantáneas incrementales del Merkle Tree

Si usas el paquete Core para integrarlo directamente en tu aplicación, la estructura es la siguiente:

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # Para almacenar la API Key
└── your-codebase/              # Código que se va a indexar

---

Paso a paso

Paso 1: Registra Zilliz Cloud y obtén credenciales de la base de datos vectorial

El almacenamiento de vectores de Claude Context depende de Zilliz Cloud (o de Milvus autohospedado). En este paso necesitas crear una cuenta gratuita.

Abre zilliz.com/cloud y regístrate con tu correo o con tu cuenta de GitHub. Después de iniciar sesión, crea un nuevo Serverless Cluster desde la consola:

1. Haz clic en Create Cluster
2. Elige el tipo Serverless (el uso gratuito es completamente suficiente)
3. Selecciona la región más cercana (AWS us-west-2 o Singapur se usan comúnmente)
4. Nombra tu clúster, por ejemplo claude-context

Una vez creado el clúster, entra en la página de detalles y localiza Connection Info; copia estos dos valores para usarlos luego:

• Public Endpoint: con un formato como https://xxx.api.gcp-us-west1.zillizcloud.com
• API Key: con un formato como xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Paso 2: Obtén una OpenAI API Key

Claude Context usa un modelo de embeddings para convertir fragmentos de código en vectores. Necesitas preparar una OpenAI API Key para activar el modelo predeterminado text-embedding-3-small.

Abre platform.openai.com/api-keys, haz clic en Create new secret key y copia el valor generado (formato sk-xxxxxxxx...).

Paso 3: Instala el MCP de Claude Context en Claude Code

Ahora registraremos este servidor MCP dentro de Claude Code. Abre la terminal, entra en cualquier directorio de proyecto y ejecuta el siguiente comando:

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Sustituye estos marcadores de posición por tus valores reales:

• sk-your-openai-api-key → tu OpenAI API Key
• your-zilliz-cloud-api-key → tu Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → tu Zilliz Public Endpoint

Si el comando se ejecuta correctamente, verás que el servidor MCP quedó registrado. Verifica la instalación:

claude mcp list

Deberías ver claude-context en la lista y con estado running.

Si estás usando otra herramienta de programación con IA, la configuración es ligeramente distinta. Algunos escenarios comunes:

Cursor (recomendado: método con archivo de configuración):

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Windsurf (también usa configuración en JSON):

// ~/.windsurf/mcp_settings.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Paso 4: Indexa tu primer repositorio de código

Cuando la instalación haya terminado, entra en el directorio de tu proyecto y abre Claude Code:

cd your-project-directory
claude

En la conversación, escribe el siguiente comando para iniciar el indexado:

Index this codebase

Claude Context empezará a analizar el repositorio inmediatamente. Todo el proceso se divide en dos etapas:

1. Escaneo de archivos: recorre el directorio, filtrando los archivos de código a procesar según la extensión
2. Incrustaciones (embeddings): para cada archivo de código, lo fragmenta usando AST (árbol de sintaxis abstracta), llama al modelo de embeddings para generar vectores y los guarda en la base de datos vectorial

Durante el indexado, puedes preguntar en cualquier momento por el progreso:

Check the indexing status

La respuesta te indicará el porcentaje del progreso del indexado y cuántos archivos ya se han completado.

Paso 5: Verifica el resultado de la búsqueda y entiende las respuestas

Una vez finalizado el indexado, puedes comenzar con la búsqueda semántica. Aquí tienes algunos escenarios típicos de consulta:

Encontrar la implementación de una funcionalidad específica:

Find functions that handle user authentication

Los resultados incluirán nombres de funciones relacionadas, rutas de archivos, fragmentos de código y una puntuación de relevancia (entre 0 y 1; cuanto más alta, más relevante).

Entender relaciones entre módulos:

How does the payment module connect to the order module?

Ubicar rápidamente código relacionado con configuración:

Where is the database connection pool configured?

El formato de los resultados es el siguiente:

File: src/database/connection.ts:45-78
Score: 0.94
Content:
  const pool = new Pool({
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  });

Si quieres limpiar el índice y empezar de nuevo, ejecuta:

Clear the index for this codebase

---

Solución de problemas frecuentes

Q1: La versión de Node.js no es compatible y el comando falla

Síntoma: claude mcp add devuelve un error o el servidor MCP se cierra inmediatamente después de iniciarse.

Causa: Claude Context no soporta Node.js 24.x en la actualidad.

Solución:

# Comprueba la versión de Node actual
node -v

# Si es 24.x, degrádalo a 20.x (LTS)
nvm install 20
nvm use 20

Q2: Configuración errónea de variables de entorno; el indexado falla

Síntoma: Index this codebase no responde o devuelve el error Milvus connection failed.

Pasos de verificación:

1. Confirma que MILVUS_ADDRESS no lleve el prefijo https://; usa solo la parte del host
2. Asegúrate de que MILVUS_TOKEN coincida exactamente con la API Key mostrada en la consola de Zilliz Cloud
3. Verifica que OPENAI_API_KEY empiece con sk-

Ejemplo de formato correcto:

-e MILVUS_ADDRESS=in-xx-xxxxxxxx.api.gcp-us-west1.zillizcloud.com
-e MILVUS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Q3: El progreso del indexado se queda bloqueado y no hay avances

Síntoma: después de ejecutar el comando de indexado no hay respuesta durante mucho tiempo.

Solución:

1. Primero ejecuta Check the indexing status para confirmar el estado actual
2. Revisa la conexión de red (necesitas acceso a la OpenAI API y a Zilliz Cloud)
3. Si el clúster se creó hace poco, el endpoint podría aún estar inicializándose; espera 1-2 minutos y vuelve a intentarlo

Q4: Los resultados de búsqueda están vacíos o son completamente irrelevantes

Síntoma: la consulta debería coincidir con contenido del código, pero devuelve resultados vacíos.

Causa: los archivos indexados podrían estar incompletos, o la formulación de la consulta difiere mucho de los nombres usados en el código.

Solución:

1. Comprueba primero el estado del indexado: Check the indexing status
2. Prueba una consulta más concreta (usa nombres de variables o funciones que existan realmente en el código)
3. Si confirmas que el código existe pero no aparece en la búsqueda, limpia el índice y reindexa:

Clear the index for this codebase
Index this codebase

Q5: El indexado incremental no surtió efecto; el código modificado no se detecta

Síntoma: modificaste algún archivo, pero los resultados de búsqueda semántica siguen apuntando a la versión anterior.

Causa: Claude Context utiliza instantáneas del Merkle Tree para detectar cambios en archivos. Si eliminaste manualmente el archivo de la instantánea, la detección incremental puede fallar.

Solución: limpia el índice y vuelve a empezar:

Clear the index for this codebase
Index this codebase

Q6: Falló la conexión MCP y la herramienta no está disponible

Síntoma: en la lista de herramientas no aparecen search_code, index_codebase, etc.

Solución:

1. Reinicia Claude Code (a veces el servidor MCP necesita recargar)
2. Asegúrate de que la configuración MCP no tenga errores de sintaxis (en JSON, presta atención a comas y comillas)
3. Comprueba si el estado del plugin para ese con claude mcp list es running

claude mcp list

Si el estado es stopped, reinícialo manualmente:

claude mcp remove claude-context
# y luego vuelve a ejecutar el comando de instalación del Paso 3

---

Lecturas adicionales / Direcciones avanzadas

Usar un modelo de embeddings personalizado

text-embedding-3-small de OpenAI es la opción predeterminada, pero Claude Context admite múltiples proveedores de embeddings, lo que te permite desplegarlo de forma totalmente local:

Usar Ollama (modelo local):

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Usar VoyageAI:

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=voyageai \
  -e VOYAGEAI_API_KEY=your-voyageai-key \
  -e VOYAGEAI_MODEL=voyage-code-3 \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Integrar LangChain/LangGraph para RAG avanzado

Si quieres integrar las capacidades de Claude Context directamente en tu propia aplicación, puedes usar el paquete Core:

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';

// Inicializa embeddings y base de datos vectorial
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

const context = new Context({ embedding, vectorDatabase });

// Indexa el repositorio y escucha el progreso
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// Ejecuta búsqueda semántica
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

Para ver ejemplos detallados, consulta evaluation/retrieval/custom.py。

Búsqueda visual en VSCode

Si te sientes más cómodo trabajando dentro del IDE, puedes instalar el plugin Semantic Code Search. Así podrás hacer búsqueda semántica directamente en VS Code, sin necesidad de iniciar Claude Code.

Estrategia para gestionar múltiples repositorios de código

Claude Context permite gestionar varios repositorios de código al mismo tiempo. Solo tienes que llamar a Index this codebase por separado en distintos directorios; cada directorio mantendrá un índice independiente. Puedes usar el nombre del directorio para diferenciarlos:

# Directorio de trabajo A
cd ~/projects/frontend && claude
# en la conversación ejecuta Index this codebase

# Directorio de trabajo B
cd ~/projects/backend && claude
# en la conversación ejecuta Index this codebase

Principio de fragmentación por AST y indexado incremental con Merkle Tree

La capacidad de comprensión del código de Claude Context se basa en dos tecnologías fundamentales:

• Fragmentación basada en AST (AST-based Chunking): analiza la estructura del código con un árbol de sintaxis abstracta y fragmenta por límites de funciones, clases y módulos en lugar de dividirlo simplemente por número de líneas. Esto garantiza que cada chunk sea una unidad de código semánticamente completa.
• Indexado incremental con Merkle Tree: cuando cambia un archivo, mediante comparación con Merkle Tree solo se vuelven a indexar los archivos modificados en lugar de reconstruir todo el contenido. Esto reduce enormemente el coste de mantenimiento de repositorios grandes.

Si te interesa el detalle de cómo se implementan estas dos tecnologías, puedes revisar el código fuente de packages/core en el repositorio zilliztech/claude-context.